minimax-h3-python-tv-generator AGENTS.md

H3 Episode Director — Agent's Guide

This is the canonical reference for any agent (human or LLM) creating or modifying episodes in this pipeline. Read it before touching shows/.

1. Pipeline Overview

A "show" is a series (Seinfeld, Sudirman). An "episode" is one ~2–10 minute video composed of N shots (typically 12–45). Each shot is a single MiniMax H3 video clip (5–15 s). Clips are rendered via ComfyUI, persisted to disk, then concatenated with ffmpeg into the final episode file.

screenplay.txt  ──►  shots.json (per-shot prompts + timing)  ──►  render  ──►  assemble.mp4
   (human)            (human or LLM)                          (ComfyUI)        (ffmpeg)

Scripts:

• orchestrate.py — renders pending shots via ComfyUI, auto-assembles at end.
• assemble.py — re-stitches already-rendered shots (no render).
• promptcraft.py — single-idea → single-prompt helper (LLM-driven; optional).
• storyboard.py — screenplay → shots.json helper (LLM-driven; optional).
• common.py — shared helpers, paths, HTTP, JSON.
• inject.py — sentinel substitution into ComfyUI template graphs.
• template.json — t2v / i2v graph (MiniMaxH3ImageToVideo).
• template-ref.json — v2v graph (MiniMaxH3ReferenceToVideo; experimental).

2. Show & Episode Layout

shows/
  <show>/
    overlay.md              show-level style rules (tone, palette, characters)
    episodes/
      01/
        screenplay.txt      the source script (TITLE, LOGLINE, [SCENE] blocks)
        shots.json          the production sheet (one entry per shot)
        output/             rendered shot_NNN.{mp4,webm} files
        hand_craft.py       (optional) manual overrides
      02/
        ...

common.show_paths(show, episode) returns the canonical paths. --show NAME --episode N flags scope every script to the right directory.

3. Per-Shot JSON Schema (canonical)

Each entry in shots.json["shots"] has:

field	type	required	meaning
id	int	yes	1-based, sequential, never reused
scene_id	int	yes	scene number from screenplay (1-based)
prompt	string	yes	full MiniMax H3 prompt (see §5)
duration_s	float	yes	total clip length ComfyUI renders
seed	int	yes	deterministic per-shot seed
mode	string	yes	t2v / i2v / v2v (see §6)
content_start	float	rec.	seconds before action begins (pre-roll)
content_end	float	rec.	seconds after which action ends (post-roll begins)
steps	int	optional	override inference steps (default per template)
fade_in	float	optional	seconds of fade-in applied at assembly (cross-fade from prev)
fade_out	float	optional	seconds of fade-out applied at assembly (cross-fade to next)
status	string	auto	pending / running / done / failed — managed by orchestrator
video_path	string	auto	relative path to rendered clip
last_frame_path	string	auto	absolute path to last-frame PNG (used by next i2v shot)
prompt_id	string	auto	ComfyUI prompt UUID
attempts	int	auto	render attempt count