| # Node guide |
|
|
| This is a user-facing map of the nodes you normally see in a Context Loop |
| workflow. It focuses on what to connect and what comes out; exact expert fields |
| remain documented by the node tooltips and the linked specialist guides. |
|
|
| ## Read a node at a glance |
|
|
| The tables use this direction: |
|
|
| ```text |
| input socket or widget ──> NODE ──> output socket |
| ``` |
|
|
| - **Socket** means connect another node. |
| - **Widget** means choose or type a value on the node. |
| - Inputs marked optional can stay disconnected for the normal path. |
| - Outputs described as status or summary are for inspection; they do not need |
| to be wired for generation. |
|
|
| The flow overview in the [README](../README.md#how-the-graph-is-organized) shows |
| where the core nodes sit. |
|
|
| ## How disabled nodes are shown |
|
|
| Disabled nodes remain part of the saved workflow, so their sockets and purpose |
| still matter. These docs keep their node-shaped representation and add an |
| explicit state label: |
|
|
| | Representation | ComfyUI mode | Meaning | |
| |---|---:|---| |
| | **Solid card — ACTIVE** | `0` | Executes when its output is requested. | |
| | **Grey dashed card — MUTED** | `2` | Present, but never executes. No output is produced. | |
| | **Dashed amber card — BYPASSED** | `4` | Skips its operation and forwards a compatible input. | |
|
|
| This follows the useful behavior of disabled-pack schema previews: input |
| sockets, widgets, defaults, and outputs remain visible even though the node is |
| not live. It prevents a muted recovery branch from looking like missing or |
| broken documentation. |
|
|
| In the shipped generation examples, **Load Manifest → Assemble — recovery** is |
| muted. Unmute that pair only to assemble saved scenes without rendering. In |
| some deferred-upscale examples, an attention override is bypassed intentionally |
| for compatibility. |
|
|
| ## Main loop |
|
|
| | Node | Inputs you normally use | Outputs you normally use | What it does | |
| |---|---|---|---| |
| | **MiniMax H3 Generation Profile** | Widgets: Scene continuity, Audio profile. Optional: `lip_sync_options`. | `chain_policy`, `status` | Turns two user choices into the complete policy expected by Plan. | |
| | **MiniMax H3 Plan (Modern)** | Required `chain_policy`; organized Project, Canvas, Generation defaults, and Delivery settings; optional `project_assets`. | `plan`, `summary`, scene count, width, height, blend frames | Recommended for new graphs. Keeps the familiar scene-column editor, removes all legacy fallback controls, and compiles the same Plan contract as the original node. | |
| | **MiniMax H3 Context Loop Plan** | Widgets: Scene Plan, `run_name`, size, duration, seed. Optional sockets: `chain_policy`, `project_assets`. | `plan`, `summary`, scene count, width, height, blend frames | Original compatibility-preserving Plan. Existing workflows keep it unchanged. Connect Generation Profile, then use **Upgrade to Modern Plan…** from its context menu when desired. | |
| | **MiniMax H3 Chain Preflight** | `plan` | checked `plan`, `preflight`, `ready`, `status`, report JSON | Validates the full plan before model-heavy nodes execute. Wire its Plan output to Loop Start. | |
| | **MiniMax H3 Context Loop Start** | `plan`. Optional: scene range, source timeline, source audio, external context. | `flow`, `state`, `status` | Starts scene 1, a bounded range, or a compatible resume. | |
| | **MiniMax H3 Context Loop Current Shot** | `state`. Optional source-audio fallback. | state, scene index/count, prompt, seed, raw length, steps, size, source-audio slice, blend frames | Exposes the current scene as ordinary ComfyUI values. | |
| | **MiniMax H3 Current Tagged Ref2VA Scene** | `state`, CLIP, video VAE, audio VAE, tagged references. Optional: Tagged Scene Options. | state, positive conditioning, latent, typed scene data | Compact prompt-driven Ref2VA route. It replaces the visible Current Shot + Tagged Ref2VA pair in new reference graphs. | |
| | **MiniMax H3 Context Loop Context** | state, conditioning, video VAE, latent. Optional: audio VAE, model, drift sigmas, anchors, lip-sync voice. | conditioning, trim frames, continuation flag, latent, model | Adds the selected visual/audio continuation. Scene 1 is effectively a pass-through. | |
| | **MiniMax H3 Context Loop Trim** | decoded images, trim count. Optional: audio, FPS, overlap controls, state. | delivered images/audio, overlap-ready images, overlap count | Removes the repeated head context and retains any frames needed for assembly blending. | |
| | **MiniMax H3 Context Loop Segment + Checkpoint** | state, delivered images, sampled latent. Optional: audio, overlap-ready images, denoised latent. | `segment`, `status` | Saves the scene movie, latent continuation, dependency record, and immutable revision. | |
| | **MiniMax H3 Context Loop Review Gate** | state, segment. Widgets: enabled, timeout, candidate count, memory cleanup, partial assembly. | reviewed `segment`, `status` | Pauses for approve, retry, reroll, candidate selection, or clean stop. | |
| | **MiniMax H3 Context Loop End** | flow, state, images, sampled latent, reviewed segment. | manifest, manifest JSON, final context frames, final context latent | Recurses into the next scene or finishes the selected range. | |
| | **MiniMax H3 Context Loop Assemble** | manifest. Widgets: audio source, filename, bitrate. Optional: output copy, blend/tone controls, recovery media. | `video_path` | Verifies selected segments, joins them, and muxes the chosen audio into the final MP4. | |
|
|
| The H3 model loader, scheduler, sampler, and VAE decoders are ordinary ComfyUI |
| or MiniMax H3 nodes. Context Loop provides the plan, continuity, checkpoint, and |
| recovery layer around them. |
|
|
| ## Authoring and policy nodes |
|
|
| | Node | In → out | Use it when… | |
| |---|---|---| |
| | **Scene Prompt Editor** | Plan → Plan | You want the stable per-scene prompt editor and prompt history. | |
| | **Rich Scene Prompt Editor (Experimental)** | Plan → Plan | You want the experimental rich editor and optional optimizer UI. | |
| | **Plan Studio (Experimental)** | Plan and optional Source Timeline → Plan | You want editorial placement, gaps, chapter views, previews, timeline controls, or picture-only alternate final-cut takes. | |
| | **Project Asset Carousel** | Project name/catalog; optional existing tagged refs or upscale model → project assets, references, Source Timeline | You want one project library instead of many loader/tag nodes. See the [Carousel guide](PROJECT_ASSETS.md). | |
| | **Scene LoRA Scheduler** | Model plus lazily revealed LoRA inputs; state → scene model | Different scenes use different connected LoRA routes. | |
| | **Lip-Sync Options** | Timing/denoise widgets; optional vocal stem → lip-sync options and voice | The Generation Profile uses **Lip-sync to source audio**. | |
| | **Advanced Policy Override** | chain policy + advanced transition → chain policy | You need Tone, Latent, Detail, Drift-Control, or Color-Stable Drift behavior. | |
| | **Manual Chain Policy (Legacy)** | Low-level transition/audio widgets → chain policy | An existing workflow already uses it. Prefer Generation Profile for new graphs. | |
| | **Legacy 0.4 Policy Adapter** | Old 0.4 fields; optional current policy → chain policy | You are rebuilding or migrating an old control surface. | |
|
|
| See [Scene authoring](SCENE_AUTHORING.md), [Audio and |
| continuity](AUDIO_AND_CONTINUITY.md), and the [complete Plan format](../H3_CHAIN_FORMAT_GUIDE.md). |
|
|
| ## References and source media |
|
|
| | Node group | Main inputs → outputs | Use it for | |
| |---|---|---| |
| | **Tagged Picture / Video / Motion / Audio Ref** | Media + tag/options → tagged references | Build a prompt-selected `@tag` reference collection. | |
| | **Tagged Ref2VA** | Tagged refs + CLIP/VAEs + current scene values → conditioning, latent, fingerprint | Compile only the references used by the current prompt. | |
| | **Tagged Scene Options** | Reference/backend widgets → options | Keep non-default reference settings off the compact Current Tagged Scene node. | |
| | **Scene Data Extract** | typed scene data + selected field → typed value | Recover a secondary Current Tagged Scene value such as source-audio slice or RefMod sources. | |
| | **Scheduled Picture / Video / Audio Ref** | Media + scene selector/options → schedule | Assign media by scene number or range instead of prompt tags. | |
| | **Scheduled Ref2VA** | Schedule + current scene + CLIP/VAEs → conditioning, latent, fingerprint | Compile the active scheduled references for one scene. | |
| | **Source Timeline** | Source media/path and timing options → Source Timeline | Register the reusable video/audio timeline once. | |
| | **Audio Tracks** | Optional full mix, vocals, instrumental AUDIO → Source Timeline | Use vocals for source-locked lip-sync while preserving the full mix for delivery; mix stems only when a full mix is absent. See [grouped audio](AUDIO_AND_CONTINUITY.md#grouped-songs-full-mix-vocals-and-instrumental). | |
| | **Reference Video Prep** | Video + fit/timing controls → prepared reference | Prepare motion/reference video for H3 timing. | |
| | **Frame Gate** | Opening image; optional last frame + scene index → first/last-frame outputs | Apply the opening image only to scene 1. Do not bypass it in I2V workflows. | |
| | **Frame Index Switch** | Scene index + image inputs → selected image | Alternate last-frame targets across scenes. | |
| | **Existing Video Context** | Plan plus source video or frames; optional audio → external context | Prepend an existing clip and continue from its tail. | |
|
|
| Lazy motion loaders, source-timeline previews, semantic anchors, and Patch |
| Priority are advanced reference tools. Their behavior is |
| covered by [Scheduled references](SCHEDULED_REFERENCES.md) and [Advanced |
| workflows](ADVANCED_WORKFLOWS.md). |
| |
| ## Runs, recovery, and output |
| |
| | Node | Main inputs → outputs | Use it for | |
| |---|---|---| |
| | **Run Manager** | Plan, archive controls, optional loader assets/Source Timeline/tagged refs → Plan, Source Timeline | Browse runs, restore a saved Plan and loader bindings, and archive recovery assets. | |
| | **Checkpoint Manager** | Saved UI selection; optional Plan → selected manifest | Pin a workflow-local lineage or choose **Selected chapter only** for chapter export/upscaling. Chapter output preserves original scene numbers and timing, and permits different resolutions in earlier chapters. Local output leaves the project and connected Plan unchanged. | |
| | **Load Manifest** | Plan; optional source media/context → manifest, manifest JSON, status | Verify and load saved segments without executing the generation loop. Usually muted in generation examples. | |
| | **Chapter Delivery** | Manifest, enabled, chapter number → delivery manifest, snapshot path | Seal a chosen chapter's generated scenes for independent export. `0` selects the chapter containing the last generated scene; a positive number selects that chapter explicitly. | |
| | **Chapter Recovery Load** | Run name, chapter number, optional snapshot ID → chapter manifest | Recover a sealed chapter's exact saved lineage and editorial state without loading or extending the rest of the run. | |
| | **Export PNG Sequence + Audio** | Manifest + optional VAEs, or file-backed VIDEO + upscale state; output folder, 8/16-bit PNGs, workers, verification, reuse → directory, PNG count, status, WAV path, VIDEO | Legacy latent PNG/WAV export remains available. VIDEO mode decodes and publishes one scene at a time with bounded memory, then passes the original VIDEO downstream. Verified unchanged frames can be reused; changed contents are never overwritten. | |
| | **Full-Chain Latent Video Adapter** | Generated manifest + video VAE → cached continuous video | Build a low-RAM, disk-backed whole-run input for SeedVR2. | |
| | **Assemble** | Manifest + audio/output choices → MP4 path | Join a complete or partial source/upscale manifest. | |
| |
| See [Runs and recovery](RUNS_AND_RECOVERY.md) for review branches, resume rules, |
| folder layout, deferred upscaling, and assembly options. |
| |
| ## Masking nodes |
| |
| | Node | Main inputs → outputs | Use it for | |
| |---|---|---| |
| | **Masking · Loop Source AV Target** | State + source video/audio + H3 target → scene target latent | Slice the exact source interval for the current loop scene. | |
| | **Masking · Loop Mask Slice** | State + mask batch → current scene masks | Keep a tracked mask aligned with recursive scene timing. | |
| | **Masking · Trim Source AV** | Source frames; optional audio → valid-length frames/audio, length, status | Trim the tail to H3's largest valid `17k+5` frame count without padding or resizing. | |
| | **Masking · Grid Preview** | Mask + H3 grid controls → snapped mask, preview, status | Inspect the actual 32×32 H3 cells that will change. | |
| | **Masking · Apply Target Mask** | H3 target latent + mask → masked target | Combine the spatial mask with any existing AV protection mask. | |
| | **Masking · Master Audio + Video Prefix** | H3 target + full source track + timing/prefix options → masked target, audio slice | Protect exact source audio while controlling the incoming video prefix. | |
| | **Masking · Two-Clip AV Bridge** | Start/end clips + H3 target → bridge target | Protect both ends and generate only the middle gap. | |
| |
| Use [Masked editing](MASKED_EDITING.md) for the required wiring and mask/audio |
| semantics. |
| |
| ## Upscale and research nodes |
| |
| Deferred-upscale workflows include a checkpoint adapter, current-scene node, |
| reference-conditioning recovery, pass-2 AV preparation, segment save, and an |
| upscale Loop End. The de-rope example adds Guard, Freeze Mask, Continuity, and |
| Recovered AV nodes. These nodes are designed to be used as a supplied group, |
| not assembled one at a time from this short reference. |
| |
| Start from a [deferred-upscale example](../example_workflows/README.md#deferred-upscale) |
| and use [Runs and recovery](RUNS_AND_RECOVERY.md#whole-chain-seedvr2-finishing) |
| for the detailed contracts. |
| |
| Nodes whose names end in **Experimental**, **Research**, **Internal**, or |
| **Legacy** are not the normal starting point. Keep their supplied wiring unless |
| you are following the matching specialist guide. |
| |
