H3 Prompt Director · Story → MiniMax H3 Video Prompts

Turn a narrative text into a single Markdown delivery file: overview table + asset table + per-segment blocks. Each segment's prompt can be copied directly into a local ComfyUI Ref2VA (R2V) workflow, paired with MiniMaxH3AddGuide for cross-segment continuation.

Fully automatic by default: from story to delivery without stopping for creative approval. Quality is backed by the checklist in Phase ⑥. The only round boundary is the anti-truncation checkpoint at 00-workflow.md §6.11 (end current round after Phase ④ saves; user replies "continue" to enter ⑤⑥). It is not a wait for approval—only a progress report.

Boundary: If only tweaking syntax, filling fields, or asking grammar details of an existing prompt, go directly to references/official/ and 01-grammar.md; do not run all six phases. Only run the full process when converting narrative text into storyboards, segments, assets, and per-segment prompts.

First use: Official documents are not distributed with the repository. First run bash scripts/fetch-official.sh (Windows: scripts/fetch-official.ps1) to download them to references/official/; the skill can still run without them, but grammar details will lack the highest-priority authority.

Startup Order

The authoritative workflow is references/00-workflow.md (six phases, packing rules, delivery structure, full QA checklist). Read it fully before starting, then read corresponding sections according to the hook table below. Do not pre-read all of 03–10 at startup—only read each section once, just before its effective phase.

Phase	What to Do	Read This Phase
① Story Analysis	Character table (one appearance anchor per person), scene table, plot beats, dialogue originals, emotion curve; decide adaptation scope	00; `08-dialogue.md` (three destinations for dialogue)
② Shot Breakdown & Duration Budget	Split shot list: shot size/camera movement/image/sound/budget duration; supplement action chains, object origins, state continuity, prop whitelist	`03-camera.md`, `04-emotion.md`, `05-rhythm.md`, `06-sound.md`, `07-style.md`, `09-transition.md`
③ Segment Packing	Pack shots into segments in order; snap to 24FPS grid; three atomicities; per-segment connection list; Mode B continuation	`05-rhythm.md` (§3 single-pass algorithm), `08-dialogue.md`, `09-transition.md`
④ Consistent Assets	Asset table: character images / scene images / prop images / timbre audio; each image has a generation prompt or user-provided marker	`02-assets.md`
⑤ Prompt Writing	Write Ref2VA's six sections per segment; opening continuity; declaration sentences; action wording	`01-grammar.md` (must-read), `05-rhythm.md` §4, `08-dialogue.md`
⑥ QA & Delivery	Check against 00 §5 checklist item by item; record only deviations and cross-segment conclusions; deliver per 00 §4 structure	00 §4–§6

After Phase ④ completes, first save all planned tables, then end the current round with a one-line summary (segment count / total duration / asset count / file path). Only enter ⑤⑥ to write increments segment-by-segment after the user replies "continue". This is a hard constraint to prevent truncation of long tasks; the checkpoint does not ask for creative trade-offs, which is consistent with "fully automatic".

Invariant Rules That Must Not Be Violated

These rules must be followed even if a section hasn't been read yet. In case of conflict with the three official documents, the official text takes precedence.

Dual-channel tags: <Picture N> / <Video N> / <Audio N> only number the R2V reference input slots; numbers = actual connection order, meaning constant across six sections. Guide frames/images fed via AddGuide go through VAE into conditioning, do not occupy a slot number, and are not written as tags in prompts; guide continuity is expressed only in natural language in the opening description, cross-referenced with pixel anchors.
Mode B continuation (default): Last 22 frames of previous segment's output → AddGuide's image input, frame_idx=0; the tail audio corresponding to those same 22 frames → audio input (audio anchoring enabled by default). The segment's opening writes "Continue the motion and sound from the end of the previous segment"; delivery notes specify trimming the first 22 frames at splice (skip if the execution layer auto-trims the prefix).
Usable tail: The last 22 frames (0.92s, roughly the last 1 second) of each segment must fall within the same shot, with clear and readable image; static not required—natural motion ending or slow movement is allowed; only fast camera movement or cuts within those final 22 frames are prohibited.
Duration grid: Segment total duration snaps to a 17k+5 frame grid at 24FPS (3.75–14.38s, see 01-grammar.md §6). All [Shot N] At MM:SS.mmm timestamps strictly increase, lie within the segment duration, and match the overview table; internal cut points need not be grid values.
Packing three atomicities: Shots do not cross segments; continuous dialogue (one sentence or a group) does not cross segments; each segment's references ≤ 9 images / 3 videos / 3 audios (count = appearing character images + scene images + prop images; timbre references occupy audio slots, guide tail audio does not). Fractional slack is absorbed by transition/connecting shots, order: transition shot → ending atmosphere shot → establishing shot; do not touch action shots or emotion shots.
Scene images: By default, a 12-panel split image, containing no movable objects; the 12 panels must cover different areas/viewpoints, not 12 similar angles. Reference must declare the grid nature; movable objects get their own prop images, with explicit appearance shots and interaction subjects.
Dialogue: <d>[language] original text</d> preserves every character, no translation, no rewriting, no polishing; (Sx) is independently numbered by utterance order within the segment, each segment attaches a character→(Sx) mapping table (for user reference, not part of the prompt); narration uses fixed voiceover sentence structure with a declared closed-mouth instruction.
Language: Narrative body defaults to Chinese (project switch, can revert to English). Fixed tokens are always English: six-section field names, [Shot N], At MM:SS.mmm, reference tags, <d>[language], <scenetrans>, <cutoff>, retention markers, summary task type prefix, N/A.

Most Common Writing Pitfalls

Full rules in 01-grammar.md and 00-workflow.md; only the most frequent errors that cause rework are listed here:

Six sections, fixed order: subject_definitions → summary → retention_analysis → detailed_description → overall_soundscape → non_diegetic_music. Cannot reorder, cannot omit sections (write N/A for no music).
<Picture N> independent entries only for frame/composition anchors (first frame/last frame/key frame/composition anchor). Images used solely to define characters, scenes, props, styles do not get a separate entry—reference the source image within the corresponding <Subject N> definition sentence. However, every image connected to a reference channel occupies a <Picture N> number, numbered consecutively in connection order for that segment (starting from 1 each segment); "no separate entry" only affects writing style, not slot occupancy or counting.
Ships, vehicles, large carriers treated as movable objects: generate a prop image, not a scene image (scene image red line: no movable objects allowed).
Scene image declaration sentence: <Subject 2> is the environment of this courtyard, its form taken from <Picture 2>; <Picture 2> is a 12-panel reference grid of multiple views of the same environment, each panel being a different area and viewpoint of the same location, not a continuous shot or storyboard; the 12 panels together form a complete panorama, containing no movable objects.
Prop image declaration sentence: <Subject 3> is the bamboo sieve prop, its form and weave taken from <Picture 3>; it appears in [Shot 6], [Shot 7], held with both hands by <Subject 1>.
Mode B segment summary prefix uses [reference generation] (combine with + if other references exist); video continuation is used only when a real <Video N> reference video exists.
Summary language: Square bracket task type prefix always English; the overview text after the prefix follows the project's narrative language (Chinese by default). 01-grammar.md §2's "English overview" is the official default expression, overridden by the project language switch—no contradiction.
Summary covers all tags: The summary must name the role of every reference tag in that segment, including <Audio N> bound timbres (e.g., "<Audio 1> only provides timbre reference for..."); describing only visuals but not audio = incomplete reference relationships.
<Subject N> definition must have textual anchors: Write at least 2–3 verifiable features (age/body type/clothing/material); cannot only write "appearance taken from <Picture N>"; the reference image handles pixels, the text handles constraints—missing either causes drift.
First utterance of a speaker must declare within the sentence (identity/age/gender/on-screen or off/pitch etc. + (Sx)), subsequent reuse does not re-declare; retention_analysis must not contain (Sx).
Complete dialogue sentence: <Speaker Label> (<Sx>) + speech verb + <d>[language] original text</d>. <d> follows the speech verb immediately and occupies its own sentence; do not embed <d> inside descriptive sentences like "lip movement synchronized with...".
Dialogue budget uses wider estimate: 05-rhythm.md §2's "characters ÷ 3 (calm: ÷ 2.5) + 2–2.5s" takes priority over 00-workflow.md's +1.5–2s baseline; cut points may drift, so buffer wider is safer.
Do not add dialogue not present in the original: Default is only "keep / change to narration / delete" three destinations; when user explicitly requests additions, write each sentence into the decision record, and maintain character voice and period vocabulary.
Camera movement written as natural action sentences within the shot (type + amplitude + speed, the latter two only if meaningful); prohibit token stacking.
Actions have a start state and an end state; every pick/place of an object is explicit about source and destination; only one instance of the same prop appears; desktop items named individually; core actions occupy a dedicated shot and show a visible result.
Morphological changes arranged at segment boundaries: The segment before the change carries the old form image, the segment after carries the new form image; the segment where the change occurs only carries the new form image; the pre-change starting state is anchored by the last 22 frames of the previous segment's guide. If the change is mid-segment, prioritize splitting the segment or moving the change to the segment start to avoid two mutually exclusive reference images in the same segment.
Timbre reference attachment scope: Segments where a character speaks attach that character's timbre reference; segments without speech do not attach, to avoid ownerless <Audio N>; the same character across segments always uses the same file.

Delivery File

Write strictly following the skeleton of assets/delivery-template.md; structure defined in 00-workflow.md §4:

Overview table (segment number | shot composition including slack record | segment duration grid value | reference slots | guide source) + global generation parameters
Asset table (global number | name | anchor description | generation prompt or user-provided marker)
Overall connection diagram—omitted by default; per-segment connection list is the operational version; only output mermaid if user explicitly requests it
Per-segment blocks: parameters → connection list (reference channels + guide channel + speaker mapping + line budget) → six-section prompts → splice instructions

The planning tables from Phases ①–④ (character table / scene table / shot table / morphological change table / line-by-line budget) are placed at the front of the delivery file, all in tables; packing results written into the shot table's "Segment Number" column, no separate packing table; if no morphological changes, write "None" in that table.

Write incrementally: first write overview table + asset skeleton, then append segment by segment via tool calls. Do not stuff the entire delivery into a single chat message; only leave progress notes, final summary, and file path in the chat.

Execution Discipline

Fully automatic: No waiting for confirmation between phases. When making trade-off decisions (adaptation scope, narration position, seams, props with/without image, etc.), write them into the delivery's "Decision Record" at the moment of decision; on crash recovery, follow the record; do not re‑evaluate.
Language A/B: The specification library records that Chinese body text has completed A/B validation in a real project and remains the default (see 10-troubleshooting.md §1). Do not output a bilingual version by default; only re‑test if the user explicitly requests it.
Undefined attribute finalization: If the original text doesn't specify age/gender/appearance, finalize them during Phase ① analysis and write into the decision record; asset images, character table, and prompts share the same set of anchors—do not write independent sets.
Checkpoint in single‑round environments: If the runtime cannot truly interrupt rounds (subtasks / automated single‑round calls), continuously execute ⑤⑥ and note in the summary "Phase ④ round checkpoint skipped"; do not stall waiting for "continue".
Empty retrieval skip: If using a knowledge base for lookup and the result is empty, try at most 1 time, then note "Specification for this section missing; executing per official grammar and general rules"—do not re‑phrase and retry.
Failure recovery: On mid‑run error/truncation, first read the already‑written delivery, then continue from the last successfully written segment block; do not restart from the beginning.
Inline QA: While writing each segment, concurrently verify items relevant to that segment; after all segments are written, only run a single cross‑segment check (seams / total tag count / total duration / reference count).

Generation‑Time Troubleshooting

When user reports the generated result is subpar, read references/10-troubleshooting.md: first locate the layer (wiring layer → prompt layer → asset layer), diagnose before adjusting parameters, change only one variable at a time. Cascade rule: after regenerating segment N, the guide clip for segment N+1 and later must be re‑extracted from the new result; if the new tail‑frame state does not match the original opening description, synchronously revise downstream opening descriptions.

Reference File Index

File	Content
`references/00-workflow.md`	[Workflow Authority] Six phases, packing, Mode B continuation, delivery structure, full QA checklist, efficiency rules, conflict arbitration
`references/01-grammar.md`	[Grammar Baseline] Ref2VA six sections, tags & dual channels, dialogue sentences, duration grid, local node parameters, prohibited list
`references/02-assets.md`	Character images / 12‑panel scene images / prop images (including multiple forms) / timbre reference audio and red lines
`references/03-camera.md`	Shot size system, opening hooks, camera movement choices, axis, camera red lines
`references/04-emotion.md`	Emotion visibility principle, three levels of performance, emotion shot hold
`references/05-rhythm.md`	Connecting action trade‑offs, duration budget & line‑by‑line calculation, single‑pass packing algorithm, action description
`references/06-sound.md`	Three layers of sound ownership, continuity, music craft, sound narrative
`references/07-style.md`	Style anchor four‑piece set, period consistency red line, light source naming, color
`references/08-dialogue.md`	Dialogue three destinations, density budget, narration craft, multi‑person conversation, original fidelity
`references/09-transition.md`	Intra‑segment transition vocabulary, transition shots, cross‑segment seams, blocking rules
`references/10-troubleshooting.md`	Quick fault reference, retry decisions & cascade regeneration
`references/official/official-skill.md`	Official H3 Skill original (T2VA/I2VA/FL2VA/L2VA/Ref2VA entry; fetched at install, not shipped with repo)
`references/official/base-en.txt`	Official base mode grammar original (T2VA/I2VA/FL2VA/L2VA; fetched at install)
`references/official/ref-en.txt`	Official Ref2VA six‑section grammar original (tags, retention, full examples; fetched at install)
`references/README.md`	Sources, versions, file name mapping, and update method
`assets/delivery-template.md`	Delivery file skeleton and table headers

Conflict arbitration: Three official documents (references/official/, must be fetched first) > 00-workflow.md > Creative sections 03–09. Creative sections must not alter the workflow or official grammar.

h3-prompt-director