| # MiniMax H3 Loop Plan Formatting Guide |
|
|
| This guide belongs to `ComfyUI-MiniMaxH3-Contex-Loop` and describes the JSON |
| accepted by both `MiniMax H3 Context Loop Plan` (`MiniMaxH3ChainPlan`) and |
| `MiniMax H3 Plan (Modern)` (`MiniMaxH3ChainPlanModern`), including |
| scene lengths, prompts, seeds, steps, audio timing, and resume-safe settings. |
|
|
| ## Visual editor or raw JSON |
|
|
| `H3 Chain Plan` includes a scene-card editor. Write shared continuity text and |
| scene prompts as normal multiline text; the editor stores them as readable |
| JSON line arrays automatically. Drag scenes to reorder them, duplicate or |
| delete cards, and choose inherited duration, seconds, or exact H3 frames. The |
| timing label on every card shows raw and delivered frames, while the header |
| shows total delivered runtime. Scene cards receive distinct colors |
| automatically; use the small header swatch to customize one, or double-click |
| the swatch to restore its automatic color. Colors are UI-only and do not alter |
| the plan or checkpoint compatibility. |
|
|
| The compact **Output** button with its outline folder-open icon in the Plan |
| header creates and opens the current `output/h3_chains/<run_name>` directory on |
| the ComfyUI host. When the host is headless or its systemd service cannot |
| access a desktop session, the button copies the absolute host path instead. |
|
|
| The optional **MiniMax H3 Scene Prompt Editor** companion connects to the Plan |
| and provides a larger, adjustable-font view of one scene prompt at a time. Its |
| textarea is bidirectionally synchronized with the active |
| `plan_json.shots[n].prompt`; only the active scene and font-size preferences are |
| stored on the companion itself. Arrow buttons and `Alt+Left/Right` navigate |
| scenes, while `@` opens reference tags and `#` inserts dialogue markup. |
|
|
| Its optional **Prompt Assistant** connects to a running `comfyui-mcp |
| --panel-orchestrator` and can ask Codex or Hermes to discuss, rewrite, shorten, |
| critique, or improve continuity for the active scene. Shared and adjacent scene |
| context are controlled by checkboxes; selected text is included automatically. |
| The agent's proposed replacement is staged below the chat and remains editable. |
| Only **Apply to scene** changes `shots[n].prompt`. A source-revision fence warns |
| and asks for confirmation when manual edits landed after the request began. |
|
|
| Inside a prompt, type `@` or click **@ Reference** to insert one of the |
| references actually connected and active for that scene. Core conditioning |
| inserts native `<Picture N>`, `<Video N>`, or `<Audio N>` labels; Scheduled |
| Ref2VA offers optional stable `@aliases` which compile to those labels. Select |
| dialogue text and type |
| `#`, or click **# Dialogue**, to wrap it in `<d>...</d>`. These interactions |
| are authoring shortcuts only; they produce ordinary MiniMax prompt text. |
| When the editor can trace the Plan downstream to Scheduled Ref2VA, core |
| Ref2VA, or core Image-to-Video, the tray shows the references actually wired |
| for that scene. Hover to preview loaded media. Core FL2VA exposes its connected |
| first and last frames as `<Picture 1>` and `<Picture 2>`; L2VA with only a last |
| frame correctly exposes that frame as `<Picture 1>`. When a core I2V first |
| frame passes through **MiniMax H3 First-Scene Image Gate**, Picture 1 is active |
| only in scene 1 and is omitted from the menu on continuation scenes. |
|
|
| The experimental **Rich Scene Prompt Editor** adds color-coded tokens, larger |
| media previews, prompt guides, revision history, and one-click **Optimize**. |
| Its optimizer connection is global rather than stored on the node or in the |
| workflow. Open **ComfyUI Settings → MiniMax H3 Context Loop → Prompt |
| optimizer** and choose: |
|
|
| - **Direct API** (default) for an OpenAI-compatible Chat Completions endpoint, |
| the OpenAI Responses format, or Gemini Native. Enter the server URL and model; |
| an API key is optional for local OpenAI-compatible servers and required for |
| Gemini Native. |
| - **MCP agent** to use a provider advertised by the compatible separately |
| installed `comfyui-mcp` prompt bridge. |
| - **Disabled** to turn off optimizer execution while keeping manual Studio |
| editing available. |
|
|
| Reference-media reading is a separate opt-in setting and is off by default. |
| When enabled, only reference files resolvable inside ComfyUI's input, output, |
| or temp roots are considered. OpenAI-compatible and Responses requests attach |
| images; Gemini Native can also receive video and audio. Provider credentials |
| are saved in ComfyUI user settings and are never serialized into workflow JSON. |
|
|
| Use the editor's **JSON** button when you need to inspect, paste, import, or |
| export the underlying plan. The JSON format below remains the runtime contract |
| and existing plans are backward compatible. |
|
|
| The Plan also exposes an optional forced STRING socket named |
| `plan_json_input`. Connect an LLM node, local story director, reusable STRING, |
| or any other provider-independent JSON source. A non-empty upstream string is |
| the execution source and receives the same normalization and validation as the |
| internal JSON; an empty string or disconnected socket uses the visual editor's |
| stored `plan_json`. While connected, the visual editor clearly labels its cards |
| as the editable fallback. This socket replaces only the scene-plan JSON—Plan |
| settings such as `run_name`, dimensions, context, and audio mode remain their |
| own inputs. |
|
|
| ## Copy/paste workflow note |
|
|
| The following block is intentionally compact enough to paste into a ComfyUI |
| Note node: |
|
|
| ```text |
| H3 LOOP PLAN — QUICK FORMAT |
| |
| Use the built-in H3 Chain Plan scene editor, or open its JSON panel and paste |
| valid JSON. Use double quotes, no comments, and no trailing commas. |
| |
| { |
| "prompt_prefix": "Global subject, wardrobe, style and continuity rules.", |
| "defaults": { |
| "duration_seconds": 15, |
| "steps": 20 |
| }, |
| "shots": [ |
| { |
| "id": "intro", |
| "prompt": [ |
| "Use <Picture 1> for the subject's identity and physical features.", |
| "Her wardrobe remains unchanged throughout the sequence.", |
| "", |
| "Begin with an opening tracking shot backstage.", |
| "End while she is opening the corridor door." |
| ], |
| "seed": 123 |
| }, |
| { |
| "id": "street", |
| "prompt": [ |
| "Continue through the already-opening door without resetting her stride.", |
| "Keep the incoming camera direction, lighting and subject pose.", |
| "", |
| "Move from the corridor into the street.", |
| "End with the camera beginning a left orbit." |
| ], |
| "duration_seconds": 10, |
| "steps": 24, |
| "seed": 456 |
| }, |
| { |
| "id": "outro", |
| "prompt": [ |
| "Continue the unfinished left orbit from the previous scene.", |
| "Resolve the performance and finish on a calm wide composition." |
| ], |
| "length": 124 |
| } |
| ] |
| } |
| |
| SCENE OVERRIDES |
| - prompt can be one string OR an array of readable lines. The node joins array |
| entries with real line breaks. Use an empty string entry for a blank line. |
| - duration_seconds: requested generated duration; rounded UP to H3's 17k+5 grid. |
| - length or frames: exact raw frame count; must be 5, 22, 39, 56...3592. |
| - steps: sampler steps for this scene, 1–10000. |
| - seed: fixed uint64 seed. Omit it for a deterministic seed from base_seed. |
| - id: unique scene name used by checkpoints. Changing it can change an auto seed. |
| - prompt: scene-specific text. It may be blank or omitted when prompt_prefix |
| (or global_prompt) is non-empty; otherwise a prompt is required. |
| |
| LENGTH AT 24 FPS, context=22, anchor=head |
| - 5 seconds -> raw 124 frames; clip 1 delivers 124, later clips deliver 102. |
| - 10 seconds -> raw 243 frames; clip 1 delivers 243, later clips deliver 221. |
| - 15 seconds -> raw 362 frames; clip 1 delivers 362, later clips deliver 340. |
| Later clips lose the 22 repeated context frames after Trim. Use length for |
| frame-exact control. Every non-final shot must deliver at least the effective |
| incoming context requested by the following scene. |
| |
| PRECEDENCE |
| shot value > JSON defaults > H3 Chain Plan node defaults. |
| |
| RECOMMENDED PLAN SETTINGS |
| - width/height: multiples of 32; 960x544 is a good starting point. |
| - Transition Policy: Guide (22 frames); Latent Guide keeps Guide behavior but |
| directly reuses a generated predecessor's saved latent. Use experimental |
| Detail AV, Drift-Control AV, Hard AV, or Soft AV (39 frames) only for |
| same-shot target-latent continuation. Drift-Control AV additionally routes |
| MODEL through Chain Context and is initially validated at 20 steps. |
| - encode_mode: video |
| - anchor_mode: head |
| - crop: disabled |
| - Audio Policy for an exact music track: Source / source reference on / |
| generated continuity off. |
| - Legacy fallback: context_length 22, continuation_mode guide, audio_mode |
| source_track. |
| - segment_crf: 18–20 |
| |
| RUN / RESUME |
| - New run: unique run_name and Loop Start start_clip=1. |
| - Resume at scene N: keep the same settings and run_name; set start_clip=N. |
| - Optional bounded run: set scene_range to `N` or inclusive `N:M`. A |
| non-empty range overrides start_clip and must remain contiguous. |
| - The Review Gate can discover saved checkpoints and set start_clip for you: |
| Refresh, select Resume scene N, then press Load checkpoint. |
| - Approve & stop can join all accepted scenes into a partial MP4. Checkpointed |
| audio is the default; wire the full song to source_audio to use source audio. |
| - Optional model unloading releases VRAM while the gate waits. Continuing must |
| reload models; stopping ends the execution without a reload. |
| - Changing a completed scene's prompt, seed, length, model settings, references, |
| or source audio invalidates its checkpoint history. |
| - Change generation_fingerprint whenever model, VAE, LoRA, references, CFG, |
| scheduler, or another generation dependency changes. |
| |
| SOURCE-TIMELINE WIRING |
| Register video/audio once with Source Timeline. Connect the descriptor to |
| Preflight (or Plan Studio) and Loop Start. Current Shot obtains scene slices |
| from state and Assemble recovers the descriptor from the manifest. The source |
| song must cover the complete delivered video duration. |
| ``` |
|
|
| ## Complete JSON shape |
|
|
| `plan_json` accepts either a plan object or a bare list of shots: |
|
|
| ```text |
| Plan = { |
| "prompt_prefix"?: string | string[], |
| "global_prompt"?: string | string[], // alias of prompt_prefix |
| "defaults"?: { |
| "duration_seconds"?: number, |
| "steps"?: integer |
| }, |
| "shots": Shot[] |
| } |
| |
| Shot = string | { |
| "id"?: string, |
| "prompt"?: string | string[], |
| "duration_seconds"?: number, |
| "length"?: integer, |
| "frames"?: integer, // alias of length |
| "steps"?: integer, |
| "seed"?: integer | digit string, |
| "lora_route"?: "base" | "a" | "b" | "c" | "d", |
| "context_length"?: 0 | 1 | 5 | 22 | 39 | ... | 243, |
| "audio_context_length"?: integer, // 0..240 |
| "continuation_mode"?: "guide" | "tone_carry_guide" | "latent_guide" | "tapered_guide" | "masked_av" | "tapered_av" | "feathered_av" | "audio_feathered_av" | "drift_control_av" |
| } |
| ``` |
|
|
| The notation above explains the structure; it is not JSON because it contains |
| comments and `?` markers. Actual `plan_json` must be strict JSON: |
|
|
| - use double quotes around keys and strings; |
| - do not include comments; |
| - do not leave a trailing comma; |
| - encode line breaks inside prompts as `\n`; |
| - include between 1 and 128 shots. |
|
|
| ## Top-level plan fields |
|
|
| | Field | Required | Meaning | |
| |---|---:|---| |
| | `shots` | Yes | Ordered list of scenes. Each entry can be an object or a prompt string. | |
| | `prompt_prefix` | No | String or array of lines prepended to every scene prompt, separated by one blank line. Use it for identity, wardrobe, style, camera, and continuity rules shared by all scenes. | |
| | `global_prompt` | No | Alias for `prompt_prefix`. `prompt_prefix` wins when both are present. | |
| | `defaults.duration_seconds` | No | JSON-level default scene duration. Overrides the node's `default_duration_seconds`. | |
| | `defaults.steps` | No | JSON-level default sampler steps. Overrides the node's `default_steps`. | |
|
|
| For convenient pasting, top-level `duration_seconds` and `steps` are also |
| accepted as aliases and moved into `defaults` when **Apply JSON** is clicked. |
| The canonical JSON shown afterward always uses the `defaults` object. |
|
|
| Precedence is always: |
|
|
| ```text |
| per-shot value > JSON defaults > H3 Chain Plan node value |
| ``` |
|
|
| ## Per-scene fields |
|
|
| | Field | Required | Rules and behavior | |
| |---|---:|---| |
| | `prompt` | Conditional | Scene-specific string or array of strings. It may be blank or omitted when `prompt_prefix`/`global_prompt` is non-empty. Array entries are joined with real newlines; use `""` for a blank line. The shared prefix is prepended automatically. | |
| | `id` | No | Unique checkpoint identifier. Defaults to `clip_0001`, `clip_0002`, etc. Unsupported filename characters become `_`; the result is limited to 96 characters. | |
| | `duration_seconds` | No | Positive requested raw generation duration. It is rounded up to a valid H3 frame count. Ignored when `length` or `frames` is present. | |
| | `length` | No | Exact raw frame count. Must be between 5 and 3592 and satisfy `length % 17 == 5`. | |
| | `frames` | No | Alias for `length`. `length` wins when both are present. | |
| | `steps` | No | Sampler steps for this scene, from 1 to 10000. | |
| | `seed` | No | Fixed unsigned 64-bit seed, from 0 to 18446744073709551615. A decimal digit string is also accepted and lets browsers preserve values above JavaScript's exact integer range. When omitted, the seed is derived deterministically from `base_seed`, scene index, and scene `id`. | |
|
|
| A shot can also be only a prompt string: |
|
|
| ```json |
| { |
| "shots": [ |
| "Opening scene.", |
| "Continue through the doorway.", |
| "Finish on a wide sunrise shot." |
| ] |
| } |
| ``` |
|
|
| String shots use automatic IDs, the default duration and steps, and derived |
| seeds. |
|
|
| ## Setting scene length |
|
|
| MiniMax H3 runs at 24 fps and accepts only raw lengths on this grid: |
|
|
| ```text |
| 5, 22, 39, 56, 73, ... 3592 frames |
| ``` |
|
|
| Equivalently: |
|
|
| ```text |
| length % 17 == 5 |
| ``` |
|
|
| ### Use seconds for convenience |
|
|
| ```json |
| { |
| "id": "closeup", |
| "prompt": "Continue into a close tracking shot.", |
| "duration_seconds": 5 |
| } |
| ``` |
|
|
| The node converts seconds using: |
|
|
| ```text |
| requested_frames = ceil(duration_seconds × 24) |
| raw_frames = the next frame count where raw_frames % 17 == 5 |
| ``` |
|
|
| It always rounds up. The generated duration can therefore be longer than the |
| number entered. |
|
|
| | Requested | Raw frames | Raw duration | Delivered by clip 1 | Delivered by later clip with 22-frame head context | |
| |---:|---:|---:|---:|---:| |
| | 0.2 s | 5 | 0.208 s | 5 frames / 0.208 s | Invalid: not longer than the overlap | |
| | 1 s | 39 | 1.625 s | 39 frames / 1.625 s | 17 frames / 0.708 s | |
| | 5 s | 124 | 5.167 s | 124 frames / 5.167 s | 102 frames / 4.250 s | |
| | 10 s | 243 | 10.125 s | 243 frames / 10.125 s | 221 frames / 9.208 s | |
| | 15 s | 362 | 15.083 s | 362 frames / 15.083 s | 340 frames / 14.167 s | |
| | 30 s | 736 | 30.667 s | 736 frames / 30.667 s | 714 frames / 29.750 s | |
|
|
| ### Use frames for exact control |
|
|
| ```json |
| { |
| "id": "outro", |
| "prompt": "Resolve the movement and end the performance.", |
| "length": 124 |
| } |
| ``` |
|
|
| Use `length` when exact H3 timing matters. Invalid examples include `120`, |
| `240`, and `360`; the nearby valid values are `124`, `243`, and `362`. |
|
|
| ### Raw length versus delivered length |
|
|
| With the recommended `anchor_mode: head`, the beginning of every continuation |
| contains the previous scene's repeated context. `MiniMax H3 Context Loop Trim` |
| removes that overlap: |
|
|
| ```text |
| clip 1 delivered frames = raw_frames |
| later delivered frames = raw_frames - that scene's effective context_length |
| ``` |
|
|
| The Trim node's optional `images_with_overlap` output can retain the requested |
| number of repeated visual frames for an external stitcher. Its standard |
| `images` output remains fully trimmed, and audio always removes the complete |
| overlap from its public waveform. With `match_tail` enabled, that same AUDIO |
| value privately carries the full decoded overlap directly to Segment Save. |
| Generated-audio assembly lets a later masked-AV scene own that interval, so a |
| Soft AV audio release is not discarded. No additional audio socket or wire is |
| needed. Visual assembly remains independent and uses its configured overlap. |
|
|
| Generated-audio assembly derives each scene's sample budget from cumulative |
| delivered frame boundaries. This distributes fractional samples across the run |
| instead of independently rounding every scene, preventing boundary rounding |
| from accumulating into long-run A/V drift. New masked-AV checkpoints also save |
| the current scene's decoded overlap; old checkpoints without it retain the |
| legacy delivered-only hard-cut fallback. |
|
|
| For `context_length: 22`, a later scene with `length: 362` contributes 340 new |
| frames, or 14.167 seconds, to the final video. The source-audio window still |
| covers all 362 raw frames and begins 22 frames before the prior delivered end, |
| so its overlap matches the repeated picture context. |
|
|
| For the dedicated single-image I2VA example, each requested 10-second scene |
| rounds up to 243 raw frames and `context_length: 5`. Two scenes therefore |
| deliver `243 + (243 - 5) = 481` frames, or 20.04 seconds at 24 fps. The |
| First-Scene Image Gate supplies the opening image only to scene 1; scene 2 has |
| no Picture label and relies on incoming motion context. |
|
|
| With `anchor_mode: before`, no repeated head is delivered, so every scene |
| delivers its complete raw length. This mode is retained for experimentation; |
| `head` is the tested and recommended mode. |
|
|
| Every non-final scene must deliver at least the next scene's effective |
| `context_length` so that scene has enough context. The plan rejects shorter |
| predecessors before render; a next-scene override of `0` needs none. |
|
|
| ## Prompt formatting |
|
|
| For human editing, use an array of lines instead of writing escaped `\n` |
| characters. The node joins entries with real newlines. Use an empty string |
| entry when you want a blank line: |
|
|
| ```json |
| { |
| "shots": [ |
| { |
| "id": "arrival", |
| "prompt": [ |
| "Use <Picture 1> for her facial identity, hairstyle, skin tone, age, body proportions, and distinctive physical features.", |
| "Her wardrobe is the outfit defined here.", |
| "", |
| "Throughout every scene S1 wears the same fitted thigh-length dove-grey designer cocktail dress in opaque structured fabric with a deliberate low cleavage cutout, carries a small black designer handbag, and wears black high-heeled pumps.", |
| "", |
| "<Subject 2> (S2) enters from camera right." |
| ] |
| } |
| ] |
| } |
| ``` |
|
|
| This reaches MiniMax as: |
|
|
| ```text |
| Use <Picture 1> for her facial identity, hairstyle, skin tone, age, body proportions, and distinctive physical features. |
| Her wardrobe is the outfit defined here. |
| |
| Throughout every scene S1 wears the same fitted thigh-length dove-grey designer cocktail dress in opaque structured fabric with a deliberate low cleavage cutout, carries a small black designer handbag, and wears black high-heeled pumps. |
| |
| <Subject 2> (S2) enters from camera right. |
| ``` |
|
|
| Put stable information in `prompt_prefix` and only scene-specific changes in |
| each `prompt`; both fields accept the same readable array format: |
|
|
| ```json |
| { |
| "prompt_prefix": "<Subject 1> keeps the same face, yellow-and-pink hair, black cropped T-shirt, ripped jeans and silver chain. Photorealistic continuous music-video take with no cuts.", |
| "defaults": { |
| "duration_seconds": 15, |
| "steps": 20 |
| }, |
| "shots": [ |
| { |
| "id": "backstage", |
| "prompt": "Track backward as <Subject 1> walks through the backstage room. End with her opening the corridor door." |
| }, |
| { |
| "id": "corridor", |
| "prompt": "Continue the same stride and camera movement through the already-opening door. End with the camera beginning a left orbit." |
| } |
| ] |
| } |
| ``` |
|
|
| When the same complete prompt should drive every scene, scene prompts can be |
| empty or omitted: |
|
|
| ```json |
| { |
| "prompt_prefix": "The complete shared MiniMax prompt used for every scene.", |
| "shots": [ |
| {"id": "scene_01", "length": 362}, |
| {"id": "scene_02", "length": 362} |
| ] |
| } |
| ``` |
|
|
| For seamless results, each continuation prompt should explicitly preserve the |
| incoming action, camera direction, subject pose, lighting, and unfinished |
| movement. End each scene with an action still in progress, then begin the next |
| prompt by continuing that exact action. |
|
|
| ## Seeds and steps |
|
|
| Use fixed seeds when a plan must be exactly reproducible: |
|
|
| ```json |
| { |
| "shots": [ |
| { |
| "id": "scene_01", |
| "prompt": "Opening scene.", |
| "seed": 983590410766495, |
| "steps": 20 |
| } |
| ] |
| } |
| ``` |
|
|
| When `seed` is absent, a deterministic seed is derived from: |
|
|
| ```text |
| base_seed + scene index + scene id |
| ``` |
|
|
| The same plan and `base_seed` produce the same derived seeds. Changing a scene |
| ID or moving it to another position changes its derived seed. |
|
|
| `lora_route` selects a pre-patched MODEL input on **MiniMax H3 Scene LoRA |
| Scheduler**. Omit it or use `base` for the unpatched route; `a` through `d` |
| select LoRA A-D. The scheduler is not a loader: create each branch with the |
| ordinary ComfyUI LoRA loader already used by the workflow, and stack loaders |
| when one scene needs several LoRAs. Because its MODEL inputs are lazy, only the |
| active scene's selected branch is evaluated. Route selection is stored in the |
| Plan and checkpoint revision as provenance, but is deliberately excluded from |
| checkpoint/resume verification. LoRA filenames and strengths remain external; |
| include them in `generation_fingerprint` only when strict invalidation is |
| desired. |
|
|
| `continuation_mode` describes the transition from the preceding clip into this |
| scene. Omit it to inherit the Plan node setting. Use `guide` when this is a new |
| shot that should retain motion/appearance context while allowing a different |
| camera, action, or environment. Use `latent_guide` for the same behavior while |
| reusing a compatible generated predecessor's sampled video latent directly; |
| imported context falls back to RGB/VAE Guide. Use `masked_av` when it directly |
| continues the same shot and should preserve the preceding AV prefix exactly. |
| Use experimental `tapered_av` for the same 39-frame hard-mask geometry while |
| conditioning on a deterministic, disposable video-only latent-noise copy; it |
| does not alter carried audio or the accepted predecessor checkpoint. |
| Use experimental `drift_control_av` to keep that predecessor latent clean while |
| the sampler moves its disposable prefix to the next scheduler sigma on every |
| evaluation. It is fixed to 39 context frames, uses an 8+4 clean-seam taper, |
| and requires the H3 MODEL to pass through Chain Context's MODEL sockets. |
| Scene 1 uses the field only when Existing Video Context supplies a predecessor. |
|
|
| `context_length` overrides incoming video context for one scene. Omit it (or |
| leave the visual selector blank) to inherit the Plan node setting. Set it to |
| `0` for a completely new visual scene. Positive values use the same native H3 |
| choices as the Plan setting. Scene 1's override applies when Existing Video |
| Context is connected. |
|
|
| `audio_context_length` independently controls prior generated sound in guide |
| mode. Blank inherits the Plan audio setting; when that Plan setting is `0`, it |
| follows the scene's effective video context. An explicit per-scene `0` means no |
| audio carry, while a positive value can continue sound with video context `0`. |
| It applies to `generated_audio` and `source_plus_timeline`; `source_track` uses |
| its exact timeline slice. Masked AV ignores the independent value and preserves |
| audio for the same physical interval as its video prefix. |
|
|
| The compact Plan editor places these controls beside Steps under **Show |
| advanced**; Plan Studio keeps them in the existing scene-properties row. |
|
|
| ## H3 Chain Plan node settings |
|
|
| | Setting | Accepted values | Recommended use | |
| |---|---|---| |
| | `run_name` | Filename-safe text; normalized to at most 96 characters | Give each independent render a unique name. Keep it unchanged only when resuming. | |
| | `generation_fingerprint` | Any stable version string | Include model, VAE, LoRA, global-reference, CFG, sampler, and scheduler versions. Change it when any external generation dependency changes. | |
| | `width`, `height` | Positive multiples of 32, UI range 32–4096 | `960 × 544` is the supplied long-form workflow setting. | |
| | `transition_policy` | Cut, Guide, Tone Guide, Latent Guide, Detail Guide, Detail AV, Drift-Control AV, Hard AV, Soft AV policy wire | Preferred 0.5 incoming-boundary control. | |
| | `audio_policy` | Independent final/reference/continuity policy wire | Preferred 0.5 audio-intent control. | |
| | `continuation_mode` | `guide`, `tone_carry_guide`, `latent_guide`, `tapered_guide`, `masked_av`, `tapered_av`, `feathered_av`, `audio_feathered_av`, or `drift_control_av` | Legacy/advanced implementation override for scenes without `shots[n].continuation_mode`. `latent_guide` needs video encode mode and at least 5 positive context frames; `tapered_guide` accepts normal Guide context lengths and 22 is its published baseline; experimental `tapered_av` and `drift_control_av` are fixed to 39 frames. Drift-Control AV also needs Chain Context's MODEL route. | |
| | `context_length` | `0`, `1`, then native runs `5`, `22`, `39`, ... `243` | Legacy/advanced exact context. Guide accepts the native runs; AV requires the shared-clock subset `39`, `90`, `141`, `192`, or `243`. | |
| | `encode_mode` | `video` or `frames` | Use `video`. It preserves motion inside the VAE latent and is more efficient. | |
| | `anchor_mode` | `head` or `before` | Use `head`; wire `trim_frames` into MiniMax H3 Context Loop Trim. | |
| | `crop` | `disabled` or `center` | Use `disabled` when references and output already share the intended framing. | |
| | `audio_mode` | `source_track`, `generated_audio`, or `source_plus_timeline` | Legacy 0.4 fallback when Audio Policy is unconnected. | |
| | `audio_context_length` | `0`–`240` frames | In generated-audio modes, `0` follows the video context length; `22` is the tested explicit value. It is unused for video-only context in `source_track`. | |
| | `default_duration_seconds` | Positive seconds, up to 149.667 s | Used only when JSON defaults and the scene both omit a length. | |
| | `default_steps` | `1`–`10000` | Used only when JSON defaults and the scene both omit steps. | |
| | `base_seed` | Unsigned 64-bit integer | Source for deterministic seeds when a scene omits `seed`. | |
| | `segment_crf` | `0`–`51` | H.264 checkpoint-segment quality. Lower is higher quality and larger. Start around `18`–`20`. | |
|
|
| ### Which audio mode should I use for a voice? |
|
|
| The Plan's `audio_mode` controls the chain timeline and final soundtrack. It |
| does not turn scheduled `@voice` / native `<Audio N>` references on or off. |
|
|
| - Use `source_track` when you have the finished spoken performance, dialogue, |
| vocal, or song and want that exact recording in the final video. Connect the |
| complete track to Loop Start and Assemble, then route Current Shot's |
| frame-exact slice into Ref2VA or Scheduled Audio. |
| - Use `generated_audio` when you have only a short voice identity, accent, or |
| timbre reference and want H3 to generate new speech/sound described by the |
| prompt. Schedule that clip as `@voice`, connect the audio VAE to Loop Context, |
| and save the trimmed decoded audio for continuity and assembly. |
| - Use `source_plus_timeline` only when you intentionally want both the exact |
| source slice and the preceding generated-audio latent. It is experimental. |
|
|
| ## Scene-scheduled Ref2VA references |
|
|
| Use the scheduled reference nodes when a picture, video, or audio reference |
| should apply to selected scenes instead of every recursive iteration. |
|
|
| ```text |
| Scheduled Picture Ref ─→ Scheduled Video Ref ─→ Scheduled Audio Ref |
| ↓ |
| Current Shot ─ state, prompt, clip_index, clip_count ─→ Scheduled Ref2VA |
| Current Shot ─ width, height, length ───────────→ Scheduled Ref2VA |
| CLIP + video VAE + audio VAE ──────────────────→ Scheduled Ref2VA |
| ``` |
|
|
| ### Convert an existing core Ref2VA node |
|
|
| For an existing workflow, right-click **MiniMax H3 Reference to Video** and |
| select **Convert to MiniMax H3 Scheduled Ref2VA**. The conversion is a graph |
| edit, not a runtime monkeypatch. It: |
|
|
| - replaces the visible core node with Scheduled Ref2VA at the same position; |
| - preserves CLIP, both VAEs, prompt, width, height, length, image-size mode, |
| and both downstream core outputs; |
| - creates one schedule entry for every connected picture, video, paired video |
| soundtrack, and standalone audio socket; |
| - keeps same-index video/audio inputs together in one Video Schedule node; |
| - connects Current Shot `state`, `clip_index`, and `clip_count` when the loop node is |
| already connected to the core prompt/dimensions, or is the only Current Shot; |
| - connects a static schedule fingerprint to the only Plan when safe and leaves |
| it disconnected when a reference depends on Current Shot, avoiding a cycle; |
| - preserves an existing non-empty Plan `generation_fingerprint` instead of |
| overwriting it; combine the displayed schedule hash explicitly in that case. |
|
|
| Converted entries initially use all scenes and readable aliases such as |
| `@picture_1`, `@video_1`, `@video_1_audio`, and `@audio_1`. Edit their selectors, |
| and tags after conversion. A paired-audio socket without its same-index video |
| is ignored because core Ref2VA would ignore it as well. |
|
|
| Each entry has a stable human alias. Using it is optional: a Plan prompt can say `@hero_face`, |
| `@performance`, or `@voice` without knowing which native H3 ordinal that |
| reference will receive in a particular scene. Core workflows can continue using |
| native labels directly. In a scheduled prompt, do not mix native and alias names |
| for the same source; either manage native numbering yourself or let the alias |
| compiler own it. |
|
|
| The `scenes` field uses one-based scene numbers: |
|
|
| | Value | Active scenes | |
| |---|---| |
| | blank, `all`, or `*` | every scene | |
| | `3` | scene 3 | |
| | `1:5` | scenes 1 through 5 | |
| | `1,3,5:8` | scenes 1, 3, and 5 through 8 | |
|
|
| Overlapping or adjacent ranges are normalized. Zero, reversed ranges, malformed |
| tokens, and selections beyond `clip_count` stop before model execution with a |
| specific error. Unlike Loop Start's render range, disjoint reference selections |
| are safe because they do not skip the chain's motion dependency. |
|
|
| ### Video-reference timeline modes |
|
|
| `sequential` remains experimental in 0.5. `restart_each_scene` remains the safe, |
| backward-compatible default and preserves existing schedule fingerprints. |
|
|
| Each Scheduled Video Ref chooses one of two source-timeline behaviors: |
|
|
| | Mode | Behavior | |
| |---|---| |
| | `restart_each_scene` | Every active scene receives the reference beginning at source frame 0. This is the compatibility default for existing workflows and short reusable motion examples. | |
| | `sequential` | The source advances on the Plan timeline. Each scene receives an exact source slice beginning at that scene's `generation_start_frame`, relative to the first scene where this reference is active. | |
|
|
| Sequential mode requires Current Shot `state` connected to Scheduled Ref2VA. |
| It uses the same overlap already represented in the Plan. With 243 raw frames |
| and 22 head-context frames, scene 1 uses reference frames `0:243`; scene 2 |
| starts at generation frame 221 and therefore uses `221:464`. This overlap is |
| intentional: the reference motion shown beneath the pinned continuation frames |
| is the same motion, rather than frame 0 replaying against a later scene. |
|
|
| If the selector begins at scene 4, reference source frame 0 aligns with scene |
| 4. Later active scenes follow the Plan's elapsed generation time, including |
| inactive gaps. The video must already be 24 fps and contain every requested |
| frame. Paired video audio is sliced to the same time interval with sample-exact |
| rounding. A short source, missing state, changed Plan timing, or mismatched |
| scene state stops with an explicit error; the scheduler never wraps or pads a |
| motion reference silently. |
|
|
| Motion Context is not `<Video 0>` and does not consume one of stock Ref2VA's |
| three external video slots. It travels as an H3 guide/keyframe and has no |
| prompt-visible label; scheduled references remain `<Video 1>` through |
| `<Video 3>`. Internally all visual conditioning blocks are presented to the |
| model, so additional references may still cost VRAM and introduce competing |
| motion instructions. |
|
|
| See |
| [`Ref2V Sequential Motion - EXPERIMENTAL - MiniMax H3.json`](<example_workflows/Ref2V Sequential Motion - EXPERIMENTAL - MiniMax H3.json>) |
| for the minimal two-scene wiring. Its Reference Video Prep selects 464 frames, |
| so the user-supplied native video and embedded audio must cover at least |
| 19.333 seconds after conversion to 24 fps. |
|
|
| ### Prompt definitions and native labels |
|
|
| Write reference definitions directly in the Plan prompt. Optional stable aliases |
| are useful when scheduled references renumber between scenes: |
|
|
| ```text |
| subject_definitions: |
| <Subject 1> is the woman whose facial identity comes from @hero_face and whose |
| walking motion comes from @performance; preserve her hairstyle, skin tone, |
| apparent age, and distinctive physical features. |
| ``` |
|
|
| For one active picture and one active video, the compiled prompt receives: |
|
|
| ```text |
| subject_definitions: |
| <Subject 1> is the woman whose facial identity comes from <Picture 1> and whose |
| walking motion comes from <Video 1>; preserve her hairstyle, skin tone, |
| apparent age, and distinctive physical features. |
| ``` |
|
|
| The wrapper only replaces active `@tags`; it never inserts definitions. This |
| keeps the complete six-section H3 prompt visible in the Plan and Prompt Editor. |
| Unknown tags and tags scheduled for another scene are rejected rather than |
| leaking unresolved aliases into H3. |
|
|
| ComfyUI's stock Ref2VA presents media in a fixed order, and the compiler mirrors |
| it exactly: |
|
|
| 1. active pictures, numbered `<Picture 1>`, `<Picture 2>`, and so on; |
| 2. active videos, with each paired soundtrack's `<Audio N>` presented directly |
| before that video's `<Video N>`; |
| 3. active standalone audio, continuing the independent `<Audio N>` numbering. |
|
|
| Picture, video, and audio ordinals are independent. A video soundtrack therefore |
| receives its own audio tag; if `audio_tag` is blank, `@performance` derives |
| `@performance_audio`. The stock limits are validated per scene: 9 pictures, |
| 3 videos, and 3 standalone audios. Scenes with no active references remain |
| valid and expand to stock Ref2VA without dynamic reference sockets. |
|
|
| ### Optional legacy patch ownership control |
|
|
| Updated ComfyUI builds containing merged PR #15439 keep H3 guide placement and |
| Ref2VA merging entirely core-owned; Patch Priority is then an unchanged |
| pass-through reporting that no compatibility patch is required. On an older |
| ComfyUI build, the first compatible H3 Motion Context copy loaded owns the |
| legacy process-level wrappers. If an older installed copy wins load order, wire |
| **MiniMax H3 Patch Priority** between the conditioning node and **MiniMax H3 |
| Context Loop Context**: |
|
|
| ```text |
| Ref2VA / I2V conditioning → Patch Priority → Context Loop Context |
| ``` |
|
|
| The node passes conditioning through bit-for-bit and executes an ownership |
| check first. It can replace only a recognised older copy of the same shared |
| patch family. It preserves the known-compatible H3-Multishot payload merge and |
| SolAttn layout observer. Any unknown wrapper is rejected with its ownership |
| reason instead of being overwritten. The selection is process-global after the |
| node executes; one wired node is enough for the workflow, while a disconnected |
| control node will not execute. |
|
|
| ### Checkpoint compatibility |
|
|
| Every schedule entry fingerprints its normalized selector, tags, and actual |
| media bytes. For a schedule made entirely from static loaders, connect |
| its `schedule_fingerprint` output to Plan `generation_fingerprint`. Changing a |
| reference file, its selector, or its tag will then invalidate incompatible |
| saved predecessors. |
|
|
| An entry may instead consume a per-iteration output—for example Current Shot's |
| frame-exact `source_audio_slice`. Keep that entry inside the recursive body and |
| do not connect its changing fingerprint backward to Plan. Source-track mode |
| already fingerprints the complete source waveform at Loop Start, so its scene |
| slices remain resume-safe without creating a graph cycle. |
|
|
| ## Extending an existing video |
|
|
| Use **MiniMax H3 Existing Video Context** when scene 1 must continue a decoded |
| video rather than begin from an empty timeline. |
|
|
| Open |
| [`Extend Existing Video Model Workflow - MiniMax H3.json`](<example_workflows/Extend Existing Video Model Workflow - MiniMax H3.json>) |
| for a complete two-scene model with generated-audio continuity, original-video |
| prepend, review/retry controls, and a muted recovery branch. This workflow is |
| **experimental** while the imported AV continuation path receives broader |
| real-world validation. It is a separate example; the existing looping and |
| historical workflows are not modified. |
|
|
| ```text |
| Chain Plan ───────────────────────────┐ |
| Core Load Video (VIDEO) ───────────────┼→ Existing Video Context → Loop Start |
| Other loader IMAGE + AUDIO + FPS ─────┘ |
| H3 audio VAE (when carrying audio) ─────────────────────────────→ Loop Context |
| ``` |
|
|
| Use exactly one video route: |
|
|
| - `source_video` accepts a native ComfyUI `VIDEO`. The adapter decodes its |
| frames and embedded audio and reads its exact FPS; the `source_fps` widget is |
| ignored. A separately connected `source_audio` overrides embedded audio. |
| - `source_frames` accepts an `IMAGE` batch from VHS or another loader. Wire its |
| `AUDIO` output when available and set or connect `source_fps` to the actual |
| frame rate represented by that batch. |
|
|
| Connecting both `source_video` and `source_frames` is rejected instead of |
| silently choosing one. |
|
|
| The adapter performs four explicit operations: |
|
|
| 1. decodes native `VIDEO`, or accepts already decoded `source_frames`, then |
| resamples from the effective source FPS to H3's 24 fps; |
| 2. fits them to the Plan width/height using the Plan crop setting; |
| 3. keeps the last effective scene-1 `context_length` frames and optional |
| matching audio tail as scene 1's predecessor (or none when it is `0`); |
| 4. when `prepend_original` is enabled, persists the complete normalized source |
| for automatic partial/final assembly. |
|
|
| No original H3 latent is required or recoverable from an ordinary MP4. The |
| decoded tail is re-encoded with the same H3 video/audio VAE path used between |
| generated scenes. |
|
|
| With recommended `anchor_mode: head`, imported context changes scene 1 timing |
| to the same rule used by later continuations: |
|
|
| ```text |
| scene 1 delivered frames = raw_frames - scene 1's effective context_length |
| ``` |
|
|
| Therefore a 362-frame first scene with 22 imported context frames contributes |
| 340 new frames. Keep Loop Trim connected with `match_tail=true`. |
|
|
| Legacy `source_audio` has two distinct meanings in this setup: |
|
|
| - Existing Video Context `source_audio` is the soundtrack of the video being |
| extended. Its tail seeds the first join and its full normalized duration is |
| preserved when prepend is enabled. |
| - Loop Start / Current Shot / Assemble `source_audio` is the compatibility |
| soundtrack for the generated extension. In 0.5, register that media once with |
| Source Timeline instead. For scene 1 the loop constructs one raw conditioning |
| window from the imported audio tail followed by this track from time zero. |
|
|
| For `generated_audio` or `source_plus_timeline`, connect the H3 audio VAE to |
| Loop Context so the imported decoded tail can become a timeline audio guide. |
| With no imported audio, visual continuation still works and generated sound |
| starts fresh. In `source_track`, the first source-reference window already |
| contains the imported tail, so Loop Context does not need the audio VAE. |
|
|
| When `prepend_original=true`, Assemble detects the prelude in the manifest and |
| places it before all generated segments. Original audio is prepended to either |
| the source-track or checkpointed generated extension audio; `audio_source:none` |
| creates a silent final MP4. The source must be normalized and re-encoded because |
| arbitrary input videos cannot safely share H.264 parameters, dimensions, and |
| timestamps with generated segments. The Plan's `segment_crf` controls that |
| single normalization pass. |
|
|
| Reconnect the same Plan, source video, and adapter when resuming or rebuilding a |
| manifest. The imported tail is fingerprinted as part of checkpoint continuity; |
| changing it correctly invalidates dependent generated scenes. |
|
|
| ## Audio modes and formatting |
|
|
| ### `source_track` |
| |
| Recommended for a music video driven by one song. |
| |
| - In 0.5, set Audio Policy to Source/On/Off and connect the full track once to |
| Source Timeline. The old Loop Start/Current Shot/Assemble AUDIO fan-out |
| remains accepted for saved 0.4 workflows. |
| - Current Shot slices a frame-exact raw audio window for each Ref2VA scene. |
| - Motion Context carries picture context only. |
| - Assemble muxes the original source track over the stitched video. |
| - Wire trimmed decoded audio into Segment Save. H3's generated audio is saved |
| as per-scene WAVs and as one combined `.generated.wav` beside the final MP4, |
| even though the MP4 itself uses the original source track. |
| - The song must be at least as long as the total delivered video. |
| - A genuinely silent placeholder may be shorter; Loop Start detects it and |
| zero-pads scene slices and final assembly to the required duration. |
| - The waveform is hashed; changing or miswiring the song is rejected. |
| |
| ### `generated_audio` |
|
|
| - No source track is required. |
| - Chain Context carries the preceding H3 audio latent on the timeline. |
| - Wire trimmed decoded audio into Segment Save. |
| - Assemble uses cumulative frame boundaries and lets every later masked-AV |
| scene own its saved decoded overlap, preserving hard or feathered AV sound. |
| - The same generated track is also preserved as WAV sidecars for later editing. |
| - MiniMax H3 Context Loop Trim must keep `match_tail` enabled for exact sample counts. |
|
|
| ### `source_plus_timeline` |
|
|
| - Ref2VA receives the frame-exact source-song window. |
| - Chain Context also carries the preceding generated audio latent. |
| - This mode is experimental. |
| - Assemble selects the source track when `audio_source` is `plan`. |
| - H3's generated track remains available in the generated-audio WAV sidecars. |
|
|
| ## Native MiniMax H3 guides |
|
|
| When ComfyUI exposes **MiniMax H3 Add Guide** (introduced by |
| [ComfyUI PR #15439](https://github.com/Comfy-Org/ComfyUI/pull/15439)), Loop |
| Context automatically emits core video/audio guide records instead of the |
| legacy keyframe/ref representation. Existing ComfyUI releases continue through |
| the guarded compatibility path with a one-time update warning, so workflows do |
| not need a version switch. |
|
|
| To add a scene-local still, clip, or audio anchor, place the official Add Guide |
| node **after Loop Context**. It appends its guide to the continuation anchors. |
| When Ref2VA references are present, merged core places the complete guide set |
| on the target scene timeline rather than the preceding reference cursor. This |
| pack does not wrap the native layout or payload path. |
|
|
| ## Starting, resuming, and changing a plan |
|
|
| For a fresh render: |
|
|
| ```text |
| run_name: choose a new name |
| start_clip: 1 |
| scene_range: leave blank |
| ``` |
|
|
| To resume from scene N: |
|
|
| ```text |
| run_name: keep the original name |
| start_clip: N |
| scene_range: leave blank |
| ``` |
|
|
| The Start node loads the checkpoint from scene `N - 1` and validates every |
| completed predecessor. You may edit scene N and later scenes. Changing any of |
| the following for an earlier completed scene invalidates resume: |
|
|
| - prompt, seed, steps, duration, or length; |
| - width, height, context, crop, anchor, encoding, or audio mode; |
| - source audio waveform; |
| - `generation_fingerprint`. |
|
|
| The checkpoint browser embedded in the Review Gate is a shortcut for this |
| setup. It lists saved predecessor slots under the current `run_name`, changes |
| Loop Start's `start_clip`, and leaves the same validation to the next queued |
| execution. Loading previews the joined partial through that checkpoint when |
| available, or the saved predecessor scene otherwise. **Approve & stop** also |
| writes a partial joined video through the accepted scene when |
| `assemble_partial_on_stop` is enabled. |
|
|
| During active sampling, the floating **Cancel & reroll scene N** action uses |
| the scene index emitted by Current Shot. It cancels that exact ComfyUI prompt |
| ID, waits for an `execution_interrupted` confirmation, stores a new explicit |
| seed in scene N, sets `start_clip` to N, and queues normally. Scene N > 1 is |
| only cancelled after checkpoint N - 1 is confirmed ready. For a bounded run, |
| the remaining range becomes `N:end`; otherwise `scene_range` is cleared so it |
| cannot override the adjusted `start_clip`. If the prompt finishes during the |
| request, no Plan value is changed and nothing is automatically requeued. |
|
|
| ### Generate a bounded scene range |
|
|
| `scene_range` is inclusive and overrides `start_clip` when non-empty: |
|
|
| ```text |
| scene_range: 3 # generate only scene 3 |
| scene_range: 3:8 # generate scenes 3 through 8 |
| ``` |
|
|
| Whitespace is allowed. A range starting above 1 loads and validates the |
| checkpoint for the preceding scene. A range ending before the final planned |
| scene emits a partial manifest containing every verified predecessor through |
| the selected end, so Assemble can create the chain through that point. |
|
|
| Disjoint syntax such as `1,3,5:8` is intentionally rejected. Scene 5 depends |
| on scene 4, and rerendering an earlier selected scene would invalidate a |
| skipped descendant checkpoint. |
|
|
| Model, VAE, LoRA, references, CFG, sampler, and scheduler sit outside the Plan |
| node, so the chain cannot inspect them directly. Record them in |
| `generation_fingerprint` and change that string whenever they change. |
|
|
| ## Saved prompts and workflow recovery |
|
|
| Segment Save preserves the actual effective prompt and seed used for every |
| accepted render. A run under `output/h3_chains/<run_name>/` contains: |
|
|
| ```text |
| source/existing_video_<hash>.mp4 normalized prelude when prepend is enabled |
| source/existing_video_<hash>.safetensors preserved prelude audio |
| plan.json normalized effective plan for this run |
| workflow.json loadable frontend ComfyUI workflow |
| api_prompt.json queued API-format graph fallback |
| manifest.json completed segment manifest |
| segments/clip_0001.<id>.mp4 video with the full prompt in MP4 metadata |
| segments/clip_0001.<id>.prompt.txt |
| checkpoints/clip_0001.json structured prompt, seed, paths and hashes |
| checkpoints/clip_0001.<id>.json immutable metadata for each saved revision |
| checkpoints/clip_0001.<id>.safetensors |
| final/<filename>.mp4 workflow, API graph and manifest embedded |
| ``` |
|
|
| Saving the same scene again updates `checkpoints/clip_0001.json` to the active |
| revision but retains every earlier MP4, prompt sidecar, safetensors checkpoint, |
| and versioned metadata file. Each current record links to the previous one via |
| `supersedes`, so rerolling or regenerating a scene is non-destructive. |
|
|
| The segment record and manifest store `prompt_prefix`, `scene_prompt`, the |
| combined `prompt`, `prompt_hash`, `prompt_file_sha256`, `seed`, and paths to the |
| recovery archives. `prompt_hash` identifies normalized prompt text, while |
| `prompt_file_sha256` verifies the exact sidecar bytes. Older Windows sidecars |
| that used CRLF line endings remain resumable through normalized text checking. |
| The same prompt fields are also stored in the safetensors metadata. In 0.5, |
| edit the active prompt in Scene Prompt Editor or Rich Scene Prompt Editor; |
| Review Gate reads that Plan prompt on Retry/Reroll. Its legacy textarea is |
| available through the Interface setting. Review retries rewrite `plan.json`, |
| `workflow.json`, and `api_prompt.json` with the effective scene prompt and |
| exact uint64 seed before saving the replacement. |
| Both segment and assembled MP4 files use ComfyUI's standard `workflow` and |
| `prompt` tags, so metadata-aware ComfyUI loaders can recover the graph directly; |
| assembled files additionally embed the completed `h3_manifest`. |
|
|
| `workflow.json` is the file to drag back into ComfyUI. `plan.json` remains the |
| authoritative record of what the loop actually rendered if an external API |
| queued the job without frontend workflow metadata. As with ordinary ComfyUI |
| workflow metadata, connected node widget values are archived too; keep the run |
| folder private if a workflow contains credentials or other sensitive values. |
|
|
| ### Re-decode checkpoints to PNG |
|
|
| Wire a completed or partial manifest and the same H3 video VAE into |
| **MiniMax H3 Context Loop Export PNG Sequence**. The node: |
|
|
| 1. verifies every safetensors checkpoint hash without depending on the H.264 |
| segment file; |
| 2. decodes one full scene latent at a time; |
| 3. computes `trim_frames = raw_frames - delivered_frames` and removes the |
| repeated continuation overlap; |
| 4. writes a continuous frame-numbered 8-bit RGB PNG sequence; |
| 5. writes `export.json` with scene frame ranges, prompts, seeds and checkpoints. |
|
|
| The export lives under |
| `output/h3_chains/<run_name>/frames/<export_name>/`. If that folder already |
| exists, a numbered sibling is created instead of overwriting it. PNG compression |
| is lossless: changing `png_compression` only changes encoding time and file size. |
| When `embed_workflow` is enabled, the first PNG stores the archived `workflow`, |
| API `prompt`, effective `h3_plan`, and `h3_manifest`; each scene's first frame |
| stores its effective scene metadata and full prompt. |
|
|
| The checkpoint contains the exact sampled video latent, but VAE decoding is a |
| separate computation. For the closest reconstruction, use the same H3 video |
| VAE, ComfyUI version, precision, and decode/tiling behavior as the original |
| render. The PNG files are lossless representations of this new decode after its |
| conversion to standard 8-bit RGB; they are not guaranteed to be bit-identical |
| to frames decoded previously under different settings. |
|
|
| ## Complete music-video template |
|
|
| ```json |
| { |
| "prompt_prefix": "<Subject 1> is the same performer in every scene. Preserve facial identity, hair, wardrobe, proportions and accessories. Photorealistic high-energy music video shown as one uninterrupted moving-camera take. No cuts. Continue subject motion, camera momentum, lighting and geometry across every boundary.", |
| "defaults": { |
| "duration_seconds": 15, |
| "steps": 20 |
| }, |
| "shots": [ |
| { |
| "id": "clip_01", |
| "prompt": "Begin in a backstage room. Track backward as <Subject 1> approaches a lit doorway. End while the door is opening.", |
| "seed": 1001 |
| }, |
| { |
| "id": "clip_02", |
| "prompt": "Continue through the already-opening doorway without resetting her stride or the camera. Follow into a concrete corridor. End as the corridor begins transforming.", |
| "seed": 1002 |
| }, |
| { |
| "id": "clip_03", |
| "prompt": "Continue the corridor transformation and the same forward motion. Move into a wide exterior. End with the camera starting to rise.", |
| "duration_seconds": 10, |
| "steps": 24, |
| "seed": 1003 |
| }, |
| { |
| "id": "clip_04", |
| "prompt": "Complete the rising camera move, resolve the performance, and finish on a calm wide composition.", |
| "length": 124, |
| "seed": 1004 |
| } |
| ] |
| } |
| ``` |
|
|
| ## Common formatting errors |
|
|
| | Error | Fix | |
| |---|---| |
| | Invalid JSON | Use double quotes, remove comments, and remove trailing commas. | |
| | Empty prompt | Provide a non-empty scene `prompt`, or provide a non-empty `prompt_prefix`/`global_prompt` that the scene can use alone. | |
| | Duplicate ID | Give every scene a unique `id`. | |
| | Invalid exact length | Use a value from the `17k+5` grid, such as `124`, `243`, or `362`. | |
| | Continuation is too short | Make its raw length greater than `context_length`; every non-final scene must also deliver enough frames for the next context. | |
| | Unexpected scene duration | Remember that seconds round up and later `head` clips lose the repeated context after trimming. Inspect Current Shot's `raw` and `delivered` status. | |
| | Resume rejected | Restore the prior completed-scene settings and source track, or start a new run from clip 1 with a new `run_name`. | |
| | Source audio too short | Use a longer song, shorten the plan, or choose a non-source audio mode. Truly silent placeholder audio is padded automatically; non-silent audio is never padded. | |
| | Final audio/video drift | Wire both decoded streams through MiniMax H3 Context Loop Trim and leave `match_tail` enabled. It truncates excess audio or zero-pads a fractional-step shortage. | |
|
|
