h3-prompt-director

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.

1. 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.
2. 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).
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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:

1. Overview table (segment number | shot composition including slack record | segment duration grid value | reference slots | guide source) + global generation parameters
2. Asset table (global number | name | anchor description | generation prompt or user-provided marker)
3. Overall connection diagram—omitted by default; per-segment connection list is the operational version; only output mermaid if user explicitly requests it
4. 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.