| <p align="center"> |
| <img src="assets/minimax-h3-context-loop.svg" alt="MiniMax H3 Context Loop 0.6 — scene plans that survive the render" width="100%"> |
| </p> |
|
|
| # ComfyUI MiniMax H3 Context Loop |
|
|
| Build a multi-scene MiniMax H3 video with one reusable sampling graph. |
| Review each scene, compare takes, resume from checkpoints, and assemble the |
| result later—without keeping the whole production in memory. |
|
|
| [Getting started](docs/GETTING_STARTED.md) · |
| [Workflows](example_workflows/README.md) · |
| [Changelog](CHANGELOG.md) · |
| [Documentation](docs/README.md) |
|
|
| ## Changelog |
|
|
| ### 0.6.5 — Upscale anchor overrides and clear checkpoint sources |
|
|
| - Choose semantic-anchor size and mode for cached, rebuilt, or connected |
| upscale references, including the VIDEO conditioning node. |
| - Checkpoint Manager explicitly names the output branch, available scenes, |
| Original/DeRoPE source and fallback scenes, independently of preview browsing. |
|
|
| ### 0.6.4 — Preserve reference sizing during recovery |
|
|
| - Recover saved Max sizing through linked inputs and Tagged Scene Options. |
| - Apply Match/Max upscale overrides to automatic caches too, rebuilding native |
| picture conditioning from original masters without changing the source cache. |
|
|
| ### 0.6.3 — Cancellation-safe processing saves |
|
|
| - Preserve saved DeRoPE/upscale scenes when manifest updates or network |
| acknowledgements fail. |
| - Recover interrupted PNG publication from a scene journal; accept recreated |
| video containers when their delivered pixels match the existing PNGs. |
| - Keep earlier scenes and conflicting partial files safe. See |
| [cancellation and scene-level resume](docs/processing-resume.md). |
|
|
| ### 0.6.2 — Upscale recovery and saving |
|
|
| - **Recover lost reference caches.** Upscale rebuilds missing Ref2VA tensors |
| from verified saved reference media. Per-reference tensor files avoid repeated |
| bundles; legacy caches remain readable and can be converted safely. |
| - **Reliable deferred sources.** Full-sequence upscale respects selected final-cut |
| alternates and saved DeRoPE sources. Checkpoint previews no longer shorten the |
| processing range. Processing tabs expose saved versions and guarded cleanup. |
| - **Scene-by-scene PNG export.** The existing PNG Sequence + Audio node accepts |
| file-backed VIDEO and passes it through after saving each scene, with selectable |
| 8/16-bit PNGs, bounded memory, and network-storage-safe reuse. |
| - **Exact recovery records.** New takes keep their own Plan/workflow snapshots; |
| later edits cannot replace those saved settings. Original media must still |
| exist for a lost reference cache to be rebuilt. |
|
|
| - **Grouped source audio.** Assign full mix, vocals and instrumental in the |
| Carousel or Audio Tracks node. Vocals drive lip-sync; the full mix stays the |
| soundtrack. Per-scene Lip-sync On/Off controls do not alter delivery. |
|
|
| ### 0.6.1 — Chapter output and authoring |
|
|
| - **Chapter output.** Export or recover a chosen chapter, including its already |
| generated scenes while it is unfinished. Chapters can use different resolutions; |
| locked saved scenes preserve their chapter's original size. |
| - **Local checkpoint branches.** Pin a branch for this workflow's output without |
| changing the project's active branch. Select **Selected chapter only** for |
| chapter-specific export and upscale experiments. |
| - **Authoring polish.** Rich prompt marker menus and completion improvements, |
| clearer responsive/light-theme controls, and scene duplication that preserves |
| prompts and updates context links correctly. |
| - **Pixel upscale controls.** Optional conditioning width and height; `0` keeps |
| automatic sizing from the upscaled images. |
|
|
| ### 0.6 — Better authoring, recovery, and export |
|
|
| - **Production Plan.** The familiar scene columns, with settings organized |
| into Project, Canvas, Generation, and Delivery. The original Plan node stays |
| available; migration is optional. |
| - **Context Builder.** Compose picture context from multiple saved-scene |
| windows, choose their frame repartition, and adjust boundary controls in |
| Plan Studio. Audio follows the predecessor by default and can be unlocked |
| for independent context selection. |
| - **Plan Studio and review.** Non-destructive trims, picture-only final-cut |
| alternates, and scene LoRA routes. Candidate selection now keeps seeds and |
| settings synchronized across the Plan and editors. |
| - **Project Asset Carousel.** More reliable project switching and previews, |
| editable semantic-anchor size/mode with downstream inheritance, and video |
| references that keep their own duration. |
| - **Recovery and editing fixes.** Safer checkpoint rollback, stale-response |
| protection when switching projects, and fixes for empty-scene navigation, |
| archive restoration, and source audio after scene resizing. |
| - **Faster PNG + WAV export.** Parallel PNG saving, progress and timing logs, |
| plus synchronized audio export. Connect the video VAE, audio VAE, or both. |
| - **Rebuilt 0.6 workflows.** Clean settings, readable layouts, and wiring |
| checked against the release nodes. Studio examples include the Carousel and |
| Checkpoint Manager; older workflows are kept in the archive. |
| - **Experimental pixel upscaling.** A scene-by-scene DLSS5 + USDU example with |
| conditioning matched to the actual upscaled image size and original audio |
| preserved. Full external GPU refinement testing is still pending. |
|
|
| [Full changelog](CHANGELOG.md) · |
| [0.5 → 0.6 visual overview](docs/assets/minimax-h3-context-loop-0.5-to-0.6-major-improvements.png) |
|
|
| <details> |
| <summary>Earlier milestones</summary> |
|
|
| - **0.5:** generation profiles, candidate review, checkpoint branches, project |
| assets, and deferred upscale workflows. |
| - **0.4:** tagged references, Studio authoring, saved-run recovery, and masked |
| video/audio editing. |
| - **0.1–0.3:** the recursive scene loop, review gate, per-scene checkpoints, |
| prompt editor, and archival PNG export. |
|
|
| </details> |
|
|
| ## Install |
|
|
| From `ComfyUI/custom_nodes`: |
|
|
| ```bash |
| git clone https://github.com/seitanism/ComfyUI-H3-Motion-Context-MultiRef.git |
| git clone https://github.com/ethanfel/ComfyUI-MiniMaxH3-Context-Loop.git |
| ``` |
|
|
| `main` is the 0.6 release line. Use `nightly` only for development features. |
|
|
| Restart ComfyUI. Use a build with native MiniMax H3 **Add Guide** support and |
| install your H3 model, text encoder, video VAE, and audio VAE; models are not |
| bundled. `ffmpeg` on `PATH` is recommended for review and assembly. Optional |
| upscale packs and example assets are listed in the [workflow catalog](example_workflows/README.md). |
|
|
| ## First run |
|
|
| 1. Open [T2V Normal](<example_workflows/T2V Normal - MiniMax H3 0.6.json>) and |
| select the four model files. |
| 2. Give **Production Plan** a unique `run_name`, edit the scene prompts, and |
| keep the default Generation Profile for a first test. |
| 3. Queue. Preflight checks the plan, then the loop renders and checkpoints one |
| scene at a time. |
| 4. At **Review Gate**, approve, retry, reroll, or approve and stop. After the |
| last approval, **Assemble** writes the final MP4. |
|
|
| For Studio workflows, set the run name in **Project Asset Carousel** instead. |
| See [Getting started](docs/GETTING_STARTED.md) for setup and recovery steps. |
|
|
| ## Choose a workflow |
|
|
| | Starting point | Workflow | |
| |---|---| |
| | Text | [T2V Normal](<example_workflows/T2V Normal - MiniMax H3 0.6.json>) | |
| | First image / first and last images | [I2V Normal](<example_workflows/I2V Normal - MiniMax H3 0.6.json>) / [FL2V Normal](<example_workflows/FL2V Normal - MiniMax H3 0.6.json>) | |
| | Tagged references and timeline editing | [Ref2V Studio](<example_workflows/Ref2V Studio - MiniMax H3 0.6.json>) | |
| | References with a source soundtrack | [Ref2V Studio Source Audio](<example_workflows/Ref2V Studio Source Audio - MiniMax H3 0.6.json>) | |
| | Inpaint, extend, bridge, or upscale video | [All examples and requirements](example_workflows/README.md) | |
|
|
| **Normal** keeps the scene-column editor. **Studio** adds an optional |
| experimental timeline interface without changing the sampling graph. |
|
|
| <details> |
| <summary>How the graph is organized</summary> |
|
|
| ### How the graph is organized |
|
|
|  |
|
|
| Only the current scene enters the sampler. Loop End advances to the next scene |
| or passes a manifest to Assemble. The muted **Load Manifest → Assemble** branch |
| can assemble saved scenes without rendering again. |
|
|
| </details> |
|
|
| ## Updating from 0.5 |
|
|
| Back up your workflows and project folders before updating. Existing Plan nodes |
| remain supported; the new examples have **0.6** in their filenames, and the |
| older examples are preserved under [Archive/0.5](example_workflows/Archive/0.5/). |
| Restart ComfyUI after updating and hard-refresh the browser. |
|
|
| Keep the same `run_name` to resume the same production; use a new one for a |
| different project. Saved runs live in `output/h3_chains/<run_name>/`, with final |
| movies under `final/`. Carousel media lives in `input/h3_projects/<run_name>/` |
| and is mirrored into the run for recovery. These paths follow your configured |
| ComfyUI input/output directories. Resume checks still reject incompatible |
| generation changes; see [Runs and recovery](docs/RUNS_AND_RECOVERY.md). |
|
|
| The repository is now spelled **Context-Loop**. Existing installs named |
| `ComfyUI-MiniMaxH3-Contex-Loop` can stay in place—do not install a second copy |
| just to change the folder name. |
|
|
| ## Origins and license |
|
|
| Started from **NikoDemon80's** [H3 Motion Context](https://github.com/NikoDemon80/ComfyUI-H3-Motion-Context). |
| See [Feature origins](docs/FEATURE_TRACEABILITY.md) and |
| [Third-party notices](THIRD_PARTY_NOTICES.md) for contributors and upstream work. |
|
|
| GPL-3.0 · [License](LICENSE) · [Contributing](CONTRIBUTING.md) |
|
|
