| # Runs, review, and recovery |
|
|
| ## Stable 0.6.2 recovery update |
|
|
| Update the Context Loop pack and restart ComfyUI to load the upscale/cache fixes. |
| Existing workflows and legacy reference bundles remain supported; conversion is |
| optional. The PNG exporter is still **MiniMax H3 Context Loop Export PNG Sequence |
| + Audio**, with optional file-backed VIDEO/state inputs and an appended VIDEO |
| passthrough output. No replacement of the old latent-export workflow is required. |
|
|
| New generation and alternate takes save immutable recovery documents under |
| `h3_chains/<run>/recovery_archives/<revision>/`. The active Run also retains |
| `plan.json`, `workflow.json`, and `api_prompt.json` for older recovery tools. |
| Historical checkpoint output uses its own snapshot, not a later edited Plan. |
| Older root-only archives remain readable but cannot retroactively supply unknown |
| reference timing/settings. Rebuilding disposable reference latents still requires |
| the original saved reference media and identities; missing or altered originals |
| produce an actionable error instead of silently changing the render. |
|
|
| ## Review Gate |
|
|
| Place **Review Gate** between Segment + Checkpoint and Loop End. Each scene is |
| persisted before the gate waits, then the gate offers: |
|
|
| - **Approve & continue** |
| - **Generate next candidate** when a multi-take batch is not complete |
| - **Retry scene / seed / length** |
| - **Reroll seed** |
| - **Approve & stop**, optionally assembling a partial video |
|
|
| Set Review Gate's optional **candidate_count** above 1 to collect several |
| different-seed takes. The gate pauses after every saved candidate instead of |
| blindly generating the full batch. Use **Generate next candidate** to continue, |
| or accept the current scene early and interrupt the remaining batch. The |
| carousel previews every completed take with synchronized sound; arrow keys and |
| the visible dots move between them. Mark one or more takes to keep, then choose |
| the take that becomes the active continuation. Its saved video frames and AV |
| tensors—not the last generated take—become the context for the following scene. |
| The active take and checked alternatives remain in checkpoint history; unkept |
| alternatives are deleted only after the active checkpoint is promoted safely. |
| The default value of 1 keeps the normal one-take review behavior. The widget can |
| be converted to an input and driven by a regular INT node; the safety limit is |
| 20 candidates per scene. |
| |
| Notification sound, automatic timeout, and model unloading while waiting are |
| optional. Drag the bar below the player to resize it; double-click to restore |
| the default height. |
| |
| When a Scene Prompt Editor or Rich Scene Prompt Editor is bound to the same |
| Plan, Review Gate selects the scene under review there automatically. Editor |
| changes are used by **Retry prompt / seed** or **Reroll seed** through the live |
| Plan prompt. In 0.5, Review Gate's own prompt field is disabled by default. |
| Restore it under **Settings → MiniMax H3 Context Loop → Interface → Review Gate |
| → Enable prompt editing inside Review Gate**. When enabled, text explicitly |
| typed in that field wins for the submitted retry and is synchronized back to |
| the Plan and connected editor after the server accepts it. |
| |
| During sampling, the optional floating **Cancel & reroll scene N** control |
| targets only the active H3 prompt. It waits for confirmed interruption, writes a |
| new explicit scene seed, moves Loop Start to that scene, preserves a bounded |
| range end, and queues normally. Once saving or review begins, Review Gate owns |
| the retry instead. |
| |
| Disable the floating control under **Settings → MiniMax H3 Context Loop → |
| Interface → Cancel & reroll** without affecting Review Gate. |
| |
| ## Between-scene memory cleanup |
| |
| Loop End can apply a runtime-only `between_scene_cleanup` policy after the |
| current scene and checkpoint are durable, immediately before it starts the next |
| scene or retry: |
| |
| - `off` keeps ComfyUI's normal caches. |
| - `unload_models` unloads model weights and empties the device allocator. |
| - `fresh_scene` first asks ComfyUI's active RAM-pressure cache to evict reusable |
| execution outputs and runs Python garbage collection, then releases remaining |
| pinned model pages, unloads models, and empties the device allocator. Use it |
| for chains that switch large models between scenes; the next scene will reload |
| anything that was evicted. |
| |
| The policy does not enter Plan or resume hashes. It deliberately preserves the |
| small recursive carry and dynamic graph result because ComfyUI has no supported |
| way to reset the entire executor while that graph is still resolving. On cache |
| types other than RAM pressure, `fresh_scene` still unloads models and clears |
| allocators, but no executor-output eviction callback is available. |
| |
| ## Resume |
| |
| For a fresh run: |
| |
| ```text |
| run_name: choose a new name |
| start_clip: 1 |
| scene_range: blank |
| ``` |
| |
| To resume scene N, keep the original `run_name` and dependency settings, then |
| set `start_clip: N`. The loop loads checkpoint N−1 and validates all completed |
| predecessors that the selected scene actually consumes. Editing scene N or |
| later is safe; changing an earlier prompt, |
| seed, timing, source waveform, Plan compatibility setting, or |
| `generation_fingerprint` invalidates the dependent resume. |
| |
| A visually new scene can still consume the immediately previous generated |
| audio when its video context is `0` but its audio context is positive. That |
| audio-only edge validates the predecessor's prompt/model/source identity and |
| saved artifacts, but ignores its unrelated incoming visual-boundary recipe. |
| Set both scene video context and audio context to `0` (or select Visual Cut) |
| for a completely independent scene. |
| |
| Loop Start's `verify_resume_history` switch is enabled by default. Disable it |
| only when you intentionally want scene N to consume the existing saved scene |
| N−1 despite a changed Plan. The override skips Plan/history matching; it does |
| not skip missing-file checks, SHA-256 artifact validation, checkpoint tensor |
| validation, or metadata's own recorded-history consistency. Consequently, any |
| new settings that describe the saved predecessor are not retroactively present |
| in its pixels or AV latent. |
| |
| Plan-wide continuation mode and context length are the exceptions: they choose |
| how the next scene consumes its saved predecessor. Changing either does not |
| alter completed frames or their saved AV latent, so it does not invalidate the |
| prefix. If the checkpoint's cached decoded tail is shorter than the newly |
| requested context, the loop re-decodes its complete saved video latent and |
| extracts the longer tail without regenerating the scene. Explicit per-scene |
| continuation and context overrides remain part of that scene's history. |
| |
| Review Gate's checkpoint browser can set up this resume and preview the joined |
| partial through the selected predecessor. |
| |
| **Manifest Load** also supports interrupted runs. It discovers the longest |
| contiguous active checkpoint prefix beginning at scene 1, verifies every scene |
| and artifact through that point, and emits a partial manifest when later scenes |
| have not been saved. Connect that output directly to **Assemble** to recover the |
| finished prefix without sampling again. A missing scene ends the prefix; an |
| orphaned later checkpoint is never joined across the gap. When every planned |
| scene is present, the same node emits the normal completed manifest. |
|
|
| ### Restore an earlier scene revision |
|
|
| **Refresh** in Review Gate discovers the active checkpoint and every immutable |
| revision retained for that scene. Choose the scene to resume, then select the |
| desired version of each predecessor under **Checkpoint history**. Clicking |
| **Restore & load** validates the selected MP4, safetensors checkpoint, hashes, |
| shared prompt, and compatibility contract before atomically promoting the |
| selected prefix. The corresponding prompts, seeds, lengths, steps, and scene |
| identifiers are restored into the connected Plan, and Loop Start is armed for |
| the next scene. |
|
|
| The active versions are selected by default. Restoring an earlier version does |
| not delete the current one, so another revision can be promoted later. Exact |
| continuation requires the revision's checkpoint metadata and safetensors file; |
| an MP4 copied from `segments/` or `reviews/` alone cannot recreate the saved AV |
| latent. When only video survives, use Existing Video Context as a re-encoded |
| continuation instead. |
|
|
| Retrying, rerolling, and candidate collection intentionally retain earlier |
| files as immutable revisions; they are recovery points rather than abandoned |
| temporary files. Inactive leaf revisions can be deleted from the same panel or |
| the dedicated Checkpoint Manager to reclaim space. |
| Review Gate now retrieves a fresh server-side deletion preview before asking |
| for confirmation. Active revisions and revisions with dependent later scenes |
| cannot be deleted. Cleanup is limited to that revision's segment, safetensors |
| checkpoint, prompt/audio/blend sidecars, unshared preview, and versioned |
| metadata; Plan archives, assets, prompt history, assembled exports, and other |
| revisions are never included. |
|
|
| ## Checkpoint Manager |
|
|
| Connect the active Plan to **MiniMax H3 Checkpoint Manager** when you want its |
| run preselected or want **Load selected branch** to restore saved Plan values. |
| The node outputs only `selected_manifest`; it is not a Plan pass-through and is |
| normally kept beside the generation route. Its run selector can inspect any |
| other folder under `output/h3_chains`. |
|
|
| Select a **branch heading** to choose the whole generated branch for output. |
| Clicking an individual clip only previews it; it does not shorten the output |
| or switch its branch. Use the downstream upscale/export range controls to |
| choose which scenes to process. |
|
|
| For an experiment, click **Use branch locally**. This saves the entire browsed |
| branch (the row containing the previewed clip), not just its prefix through |
| that clip. It pins the exact lineage on `selected_manifest` in this workflow |
| only, including the earlier chapters included in that selection. Browsing |
| other takes, refreshing, reopening the workflow, or activating another branch |
| in a different tab cannot move this pin. Saved files are still verified on |
| execution: a missing or corrupt pinned take fails instead of falling back to |
| the project's active branch. The output row and **local output** badges show |
| which revisions are pinned. **Follow branch selection** releases the pin; |
| output then follows branch-heading selections, never clip previews. An explicit |
| run switch asks before releasing it. Save the workflow to keep the pin on disk. |
|
|
| Older workflows can contain a partial pin saved while previewing an ancestor. |
| The output row flags this. Choose the intended branch heading and click |
| **Use branch locally** once to replace that old selection. Shared ancestors |
| can lead to multiple branches, so reopening a workflow never guesses which |
| descendant you intended or silently switches an existing snapshot. |
|
|
| **Make branch active (project)**, **Roll active branch back (project)** and |
| **Load selected branch** remain project-wide actions. Local selection neither |
| restores connected Plan settings nor arms generation/resume. Downstream nodes |
| retain their own save and deletion protections. Use the |
| manager's manifest output for the experiment, not Manifest Load (which reads the |
| project's active checkpoints). |
|
|
| The manager groups immutable scene revisions into inferred branches. A revision |
| can appear in more than one branch when it is their shared ancestor. Selecting |
| a revision shows its saved preview, prompt, seed, timing, canvas, storage, |
| parent, following scenes, and the exact video/audio frame context those |
| following scenes consume. Older checkpoints derive this graph from predecessor |
| revision and checkpoint hashes; newly saved checkpoints also carry a stable |
| branch id and effective context fields. |
|
|
| Plan chapters are checkpoint-management boundaries. The **All scenes** tab |
| shows a separate graph for each chapter. Project-wide activation of a Chapter 2 |
| branch changes only Chapter 2 pointers and connected Plan scene values; Chapter |
| 1 keeps its current active branch. The chapter-start checkpoint can retain its |
| original predecessor as provenance, but that structural edge does not choose |
| the preceding chapter. Explicit visual or audio context recorded by a scene is |
| still preserved as a generation dependency. |
|
|
| If a branch ends with an empty next-scene slot and saved candidates |
| exist elsewhere, the graph displays **Reuse saved clip**. Click it to preview |
| the available candidates and choose **Attach selected candidate**. This is |
| offered only when the candidate consumes neither predecessor video context nor |
| generated-audio continuity. The manager creates a new immutable lineage record |
| pointing at the chosen parent; the original video, audio, prompt, and checkpoint |
| files remain shared and are not regenerated or copied. Shared-file deletion is |
| reference-aware, so those files are retained until the last lineage record that |
| uses them is deleted. |
|
|
| Reuse is checked against the saved take's resolved context and audio policy, |
| not the current Plan. Candidates that cannot safely change parents show a |
| reason instead of disappearing. A rollback tip still appears as an active |
| branch even when its old descendants remain saved. |
|
|
| Rerendering an earlier scene can leave old pointer files on disk. Checkpoint |
| Manager, Plan Studio and recovery exclude those disconnected descendants from |
| the active chapter branch. They remain available as saved inactive takes; no |
| media, checkpoint, prompt, scene slot or chapter export is deleted. Use |
| **Make branch active / Roll active branch back** to explicitly reconcile those |
| old pointers. Recovery stops at the coherent saved prefix, and resuming through |
| an inactive tail requires selecting or attributing a matching lineage first, |
| even with history verification disabled. |
|
|
| If deleting the active branch tip rolls the run back while alternate leaf |
| revisions remain, select the surviving branch and click **Make branch active**. |
| The manager validates and promotes that revision's chapter lineage directly, |
| including when no Plan is connected. With an editable Plan connected, it also |
| restores the lineage's saved scene prompts, seeds, lengths, steps, context, |
| LoRA route, and boundary/audio overrides. Exact saved prompts reactivate their |
| existing Prompt Editor history revisions instead of adding duplicates. |
| Immutable revisions, workflow state, references, and assembled videos are left |
| untouched. You can then keep the chosen candidate active and continue deleting |
| the rejected inactive leaves. |
| **Load selected branch** remains the separate resume operation: it also restores |
| saved Plan inputs and arms Loop Start for the following scene. |
|
|
| Deletion is deliberately one scene revision at a time: |
|
|
| 1. Select an inactive revision. |
| 2. Inspect its complete file list, estimated reclaimed size, and preserved |
| categories. |
| 3. If later revisions depend on it, select and delete those leaf revisions |
| first. |
| 4. Confirm the now-safe leaf deletion. If anything changed after the preview, |
| the server refuses it and asks for a fresh preview. |
|
|
| This first release does not bulk-delete branches. The leaf-first workflow makes |
| the exact context consequences visible and avoids silently orphaning later |
| checkpoints. |
|
|
| Chapter recovery snapshots also protect the takes and recovery files they use. |
| Historical `supersedes` links do **not** protect a replaced take: they are an |
| audit trail, not recovery inputs. Actual scene, alternate and recovery-file |
| references still block deletion. |
|
|
| If an unwanted snapshot is the blocker, the deletion inspector offers |
| **Retire Chapter … snapshot …**. Inspect the scenes and confirm to move only |
| that snapshot's JSON from `chapters/<chapter>/manifests/` into the sibling |
| `retired_manifests/` directory. No clip, active pointer, processing take, |
| reference or assembled export is deleted. Other retained snapshots and branch |
| dependencies still block unsafe deletion; remove unused leaves first. |
|
|
| Retired snapshots no longer appear in Chapter Loader, release their recovery |
| pins and cannot be silently republished by a stale selection. Workflows pinned |
| to them need a new source. The archived JSON keeps the original bytes; it can |
| be moved back to `manifests/` to restore the snapshot only while all its inputs |
| still exist. Deleting those inputs later makes full recovery unavailable. |
| Retirement requires a fresh preview on confirmation and uses the Run mutation |
| lock. Workflow-ownership locking remains nightly-only. |
|
|
| ### Saved processing tabs |
|
|
| Checkpoint Manager has **Original**, **DeRoPE**, and **Latent Upscale** tabs. |
| **Pixel Upscale** and **Other processing** also appear when those saved profiles |
| exist. Chapter filtering applies to the processing views. The original branch |
| rows stay in place, with each clip's saved processing takes shown beneath its |
| source revision, including retained older takes and multiple profiles. |
|
|
| The catalogue reads the existing `upscaled/<profile>/checkpoints/` directories |
| at run and chapter scope. It matches both source revision and checkpoint hash; |
| scene number alone never attaches a take to another branch. Attributed aliases |
| with matching saved content can share versions. Unresolved sources remain |
| visible in a separate section. Stage labels come from the saved recipe/backend, |
| not the profile folder name; the bundled combined LBH + DeRoPE recipe appears |
| under DeRoPE at its actual saved resolution. |
|
|
| Switching tabs or inspecting a derivative does not rewrite `selected_manifest`, |
| move a local pin, activate a branch, restore a Plan, or delete a checkpoint. |
| For a later latent-upscale pass, select a saved take in **DeRoPE**, then click |
| **Use DeRoPE branch locally**. This pins the whole saved processing branch to |
| the browsed original branch; the downstream Adapter still controls start/end. |
| Scenes absent from that DeRoPE branch automatically use their selected original |
| take. A saved but incomplete/corrupt latent is an error, not an original fallback. |
| Return to **Original → Use branch locally** to explicitly use originals again. |
|
|
| New saves keep an immutable processing-lineage snapshot. Older saves can use |
| their existing full/partial profile manifest if it identifies the chosen take. |
| A shared take with multiple processing descendants is ambiguous: choose a later |
| take unique to the desired processing branch. No "latest scene" mixing occurs. |
|
|
| The inspector reports canvas, RAW/delivered frames, audio route, full-latent |
| save status, profile and metadata location. A continuation tail is explicitly |
| not a full latent. Listing checks file availability without loading tensors or |
| hashing every large checkpoint; availability is not execution validation. |
|
|
| To remove a saved processing take, select it in its processing tab and click |
| **Delete processed version**. The file/size preview and confirmation cover only |
| that take's video, checkpoint, audio and prompt sidecars, its revision metadata, |
| its current processed pointer (if still selected), and affected full/partial |
| branch manifests. Removing a pointer does not promote another take. Older takes, |
| original generation checkpoints, shared references/caches and assembled videos |
| are kept. This also works for processing takes whose original is unavailable. |
|
|
| Deletion is blocked while another saved take depends on that processing source |
| or requires its saved branch; the inspector lists clickable dependents to |
| delete first. Independent **pixel** takes are the exception to sequence ordering: |
| the saved pixel backend with zero HQ context proves that a later clip does not |
| consume its predecessor's processed output. Such later clips are kept when an |
| earlier take is deleted. This applies to legacy full/partial manifests and new |
| immutable lineage snapshots, not just newly rendered clips. Actual source or |
| context references still block deletion, and unproven/other backends retain |
| their conservative branch protection. |
|
|
| Affected sequence manifests are invalidated, not shortened or spliced across |
| the missing scene. Surviving clip files, pointers and immutable metadata stay |
| unchanged and visible in their processing tab. An old lineage with a missing |
| take is no longer offered as a complete source branch. Rebuild the missing |
| scenes before resuming a full sequence; no other take is silently substituted. |
|
|
| Ownership is checked again on confirmation, and changed files or |
| dependencies require a fresh preview. An in-flight save cannot republish a |
| deleted processing dependency. A workflow-local pin is never silently redirected: |
| if it referenced the deleted take, explicitly select another source before running. |
| Deletion is permanent; the preview does not load or hash large tensor files. |
|
|
| ### Alternate final-cut takes |
|
|
| Use an alternate when one accepted scene needs a prompt-level visual correction |
| but later scenes already depend on its original checkpoint. |
|
|
| 1. Open that scene in Plan Studio and expand **Alternate final-cut take**. |
| 2. Edit the alternate prompt and seed, then enable the draft. |
| 3. Queue normally. Loop Start renders only that scene. |
| 4. Approve the alternate in Review Gate. |
|
|
| Acceptance selects the alternate picture for preview, assembly, PNG export, |
| whole-chain latent finishing, and deferred latent/pixel/CAT upscale loops. |
| It does not replace the active generation |
| checkpoint: later scenes keep their original visual/audio ancestry, and final |
| audio for the corrected scene remains the original audio. |
|
|
| Deferred upscale resolves the selected ALT before reading source tensors or |
| reference conditioning, for both full-branch and chapter output. It uses the |
| ALT's video latent, prompt, seed and reference identity, but reads the original |
| audio separately without loading another full video tensor. Adapter/current |
| status names the selected ALT, and saved processing takes remain linked to the |
| base scene in Checkpoint Manager. A sealed chapter uses its frozen final-cut |
| selection; an unsealed full-branch input uses the current selection when the |
| loop starts. |
|
|
| Resume checks the actual picture source: an upscale previously made from the |
| original cannot be reused for a newly selected ALT (or vice versa). Restart at |
| the affected scene, or use a new profile. Saved DeRoPE must likewise belong to |
| the selected picture; scenes absent from a partial DeRoPE branch use their |
| selected ALT/original. Changing an ALT never overwrites generation checkpoints |
| or silently swaps an already selected DeRoPE latent for unprocessed media. |
|
|
| Plan Studio marks the selection `ALT`. Checkpoint Manager nests the immutable |
| alternate under its base take rather than drawing a new continuation branch. |
| Choose **Original** in Plan Studio to restore the base picture at any time. |
|
|
| An alternate must preserve the scene identity and duration. If a later scene |
| exists, set the blend entering that scene to `0`: its saved overlap still shows |
| the original base take, so assembly rejects a crossfade from an alternate. |
|
|
| ### Whole-chain SeedVR2 finishing |
|
|
| SeedVR2 is best treated as a final whole-video backend, not as another |
| scene-recursive H3 pass. Select the final scene of a complete branch in |
| Checkpoint Manager and use this graph: |
|
|
| ```text |
| Checkpoint Manager.selected_manifest |
| + original H3 video VAE |
| ↓ |
| Full-Chain Latent Video Adapter |
| ↓ native, file-backed VIDEO |
| SeedVR2 Direct Video Upscaler |
| ↓ |
| core Save Video |
| ``` |
|
|
| **Full-Chain Latent Video Adapter** verifies and decodes the original |
| safetensors video latent for every selected scene; it never reads the saved |
| H.264 scene previews. It trims repeated context, applies the saved incoming |
| blend schedule, and writes one lossless RGB movie before SeedVR2 starts. |
| SeedVR2 therefore chunks a continuous timeline rather than restarting at H3 |
| scene boundaries. A chain with Existing Video Context also streams its saved |
| prelude into the same movie. |
|
|
| `decode_buffer=disk-backed` is the recommended default. MiniMax H3's VAE keeps |
| its native temporal chunking but writes the decoded float scene into a |
| temporary mmap. The adapter converts and encodes one frame at a time, retaining |
| only the next boundary window in normal RAM, then deletes that scene buffer. |
| Peak ordinary RAM is therefore bounded by latent/model overhead and the blend |
| window instead of the decoded duration of the full chain. `memory` is a |
| compatibility fallback that holds one decoded scene at a time; neither mode |
| holds the whole production. |
|
|
| The continuous source is content-addressed and reused at: |
|
|
| ```text |
| output/h3_chains/<run_name>/upscaled/seedvr2/source/<cache_key>.mkv |
| ``` |
|
|
| The cache key includes the immutable checkpoint lineage, VAE implementation, |
| blend schedule, prelude, and selected audio policy. Disable `reuse_cache` to |
| force a fresh VAE decode. `audio_source=plan` recovers the saved final-audio |
| policy and source audio directly from the manifest. Both an explicit Source |
| Timeline and a legacy AUDIO connected once at Loop Start are now materialized |
| as path-backed run state. Only manifests created before that legacy promotion, |
| and therefore lacking a recovery descriptor, need the optional `source_audio` |
| socket. |
|
|
| Use the audio-preserving **SeedVR2 Direct Video Upscaler** from |
| [ethanfel/ComfyUI-SeedVR2_VideoUpscaler](https://github.com/ethanfel/ComfyUI-SeedVR2_VideoUpscaler). |
| It reads the adapter movie in `chunk_size` batches, returns one file-backed |
| H.264 VIDEO, and embeds the source audio in that VIDEO so it can connect |
| straight to core Save Video. Its separate AUDIO output remains available for |
| alternate muxing graphs. |
|
|
| ### Export and recover a particular chapter |
|
|
| Connect **Load Manifest**, **Loop End**, or **Checkpoint Manager** to |
| **Chapter Delivery**, then connect `delivery_manifest` to **Assemble** or |
| **Export PNG Sequence + Audio**. Set `enabled=true` and `chapter_number=1`, `2`, |
| or another explicit chapter number. `0` selects the chapter containing the last |
| generated scene; it is not required when you want a particular older chapter. |
|
|
| An unfinished chapter exports only its generated scenes. Chapter Delivery saves |
| an immutable manifest with their exact revisions, editorial state, resolution, |
| and audio offsets. Later scenes or branch switches cannot extend that snapshot. |
| Explicitly deliver the chapter again to capture new scenes or changed takes. |
| Unchanged snapshots are reused; changed selections create another snapshot. |
| MP4 and PNG/WAV output lives under |
| `output/h3_chains/<run>/chapters/<number>_<chapter_id>/`. On main, each PNG export |
| uses a new numbered folder; it does not append to an earlier frame export. |
|
|
| Use **Chapter Recovery Load** with the run name and chapter number to load a saved |
| snapshot independently. An empty snapshot ID loads the newest; a full ID picks |
| an exact older version. This is a recovery manifest, not a copy of all media: |
| keep the run's referenced checkpoints and assets. Checkpoint Manager protects |
| artifacts needed by sealed snapshots from deletion. |
|
|
| To select chapter output without saving a snapshot, use Checkpoint Manager's |
| **Selected chapter only** scope. A local branch pin alone still outputs its |
| selected lineage, including earlier chapters; the scope controls the filtering. |
|
|
| ### Deferred H3 upscale child runs |
|
|
| Select the generated branch heading you want in Checkpoint Manager and click |
| **Use branch locally** to keep that source fixed while experimenting, |
| then connect its **selected_manifest** output to **MiniMax H3 Checkpoint Upscale |
| Adapter**. The manager verifies the immutable lineage and embeds recovery-only |
| compatibility and Source Timeline metadata directly. No source Plan, Chain |
| Policy, or decoded source media is retained by the recursive upscale graph. |
| |
| Use a separate adapter **profile** name for each upscale experiment. Results |
| live under `output/h3_chains/<run>/upscaled/<profile>/`; a local source pin is |
| not a separate output folder and does not isolate experiments sharing a profile. |
| |
| To upscale or export just one chapter, set the manager's output scope to |
| **Selected chapter only**, select that chapter's branch heading, and click |
| **Use branch locally**. Changing the scope of an existing local pin keeps its |
| pinned tip; browsing another take does not move it. Earlier chapters may have |
| different resolutions: only the selected chapter's media and compatibility are |
| validated. Earlier pinned revision metadata is still read to preserve exact |
| source-audio and editorial timing. Selecting output does not seal a chapter or |
| change project-wide active branches. |
| |
| Chapter output keeps original scene numbers: a Chapter 2 containing saved |
| scenes 8–10 outputs scenes 8–10, even if scenes 11–12 are still planned. |
| On Upscale Adapter, `start_clip=1` starts at the first selected scene (8 here), |
| `end_clip=0` means the last selected scene (10), and `start_clip=9` resumes after |
| verifying scene 8's saved HQ output. No HQ prefix from Chapter 1 is required. |
| Reference schedules retain their original Plan scene numbering. |
| |
| Extending the selected branch from scene 8 to scenes 8–10 does not invalidate |
| an unchanged scene 8 upscale. Resume validates every completed scene's source |
| revision and media hashes, RAW/delivered frame clock, saved prompt/sampling |
| settings, and upscale profile, plus its saved output artifacts. New saves also |
| record a per-scene source contract. Older saves use their existing source |
| provenance without rewriting the files. The whole-manifest hash remains |
| provenance, not a reason to reject an unchanged prefix when later clips are |
| added. Changed completed sources or profile settings still require a new pass. |
| |
| Chapter upscale profiles and finals are isolated under |
| `output/h3_chains/<run>/chapters/<number>_<chapter_id>/upscaled/<profile>/`. |
| Connect the upscale manifest to **H3 Chain Assemble**; no Chapter Delivery |
| filter is needed after a chapter-only selection. Use Chapter Delivery separately |
| if you also want to seal an immutable original-quality chapter snapshot. |
| |
| ```text |
| Checkpoint Manager → Upscale Adapter → Upscale Current Scene |
| → backend graph |
| → Upscale Segment Save |
| → Upscale Loop End → H3 Chain Assemble |
| ``` |
| |
| **Upscale Current Scene** prefers the optional `denoised_output` saved by |
| Segment + Checkpoint and falls back to the terminal sampler latent in older |
| checkpoints. It exposes the joint H3 AV latent as well as separate video and |
| audio latents: |
| |
| - Combined-style nodes can consume `source_latent` directly. |
| - Video-only LBH nodes consume `source_video_latent`. **MiniMax H3 Pass-2 AV |
| Prepare** recombines their output with `source_audio_latent`, performs |
| NestedTensor-safe CONST re-noise on video only, and locks the saved audio |
| with a zero denoise mask. |
| - LTX 2.5 is a decoded-video V2V path, not an H3-latent path. Decode the H3 |
| source latent, run the LTX refinement/upscale graph, and send its raw frame |
| batch to Upscale Segment Save. |
| |
| For H3 pass-2 conditioning, **Upscale Reference Conditioning** first reads the |
| exact cache descriptor recorded on the selected source revision. Tagged and |
| Scheduled Ref2VA create that cache automatically: native H3 reference latents |
| remain in safetensors while compact Qwen presentation frames allow the saved |
| compiled prompt to be tokenized again. **H3 Conditioning Sync From Latents** |
| then compares the original scene video latent with the actual LBH output. It |
| applies the exact horizontal and vertical scale to `match` picture |
| `minimax_refs` and `minimax_keyframes`, while preserving `max` picture refs at |
| their Core H3 capped geometry. Pictures already rebuilt from a cache-v2 RGB |
| master at the pass-2 canvas are not scaled twice. It updates changed reference |
| H/W metadata and deliberately leaves text, temporal positions, and audio |
| conditioning untouched. A de-rope target may have a longer video time axis; |
| sync accepts that deliberate difference because it changes only spatial |
| reference geometry. Upscale Reference |
| Conditioning's default `exclude_video_keep_audio` policy removes both the Qwen |
| motion-video presentation and native motion-video latent because the pass-2 |
| source latent already contains the generated motion; audio paired with a video |
| reference is converted to an audio-only reference. `keep_video_native` and |
| `resize_video` remain available for comparison, and the sync node follows the |
| selected conditioning policy automatically. Build sampler 2's new |
| Guider from the returned conditioning rather than reusing the original Guider. |
| Thus the child graph needs no reference registry or original picture/video/audio |
| connections. Both cache versions retain the encoded native reference blocks |
| used by sync; cache v2 additionally keeps original picture masters for |
| workflows that choose target-resolution VAE re-encoding instead. |
| |
| The bundled **Deferred Upscale + De-Rope - H3 LBH 3D** workflow wraps |
| [ComfyUI-MAINodes](https://github.com/matlowai/ComfyUI-MAINodes)' stable |
| decoded time-smear recipe in the child loop: |
| |
| ```text |
| source x0 → H3 Jerk Oracle → Chain De-Rope Guard → H3 Time Smear |
| → H3 video VAE encode → LBH 3D → Chain De-Rope Continuity |
| → H3 V2V Init + Inject Schedule → sampler |
| → Exact/Audio Recover → re-encode → Chain Recovered AV |
| ``` |
| |
| Guard forces the parent scene's repeated prefix to rate 1 and protects the |
| last 17 frames when another selected scene follows. It enables Time Smear's |
| `expand_to_end` only at the branch tip. Freeze Mask consumes Time Smear's final |
| `hold_map_used` (including legal-grid padding) and freezes the protected prefix |
| inside H3 V2V Init. For Drift-Control scene 2+, Continuity then replaces that |
| target-resolution prefix with the prior HQ tail before sampling. |
| |
| Audio uses the identical hold map. Decode the source RAW audio latent, run H3 |
| Audio Smear, VAE-encode it into H3 V2V Init, and recover the pass-2 audio after |
| sampling. The workflow seeds audio at strength 0.5 to keep dialogue timing |
| aligned but uses MAINodes' safe final preset that retains the original |
| performance. Segment Save's optional `recovered_audio` input trims the same |
| repeated RAW prefix as video and records the recovered result. Chain Recovered |
| AV rejects a still-dilated latent and packs the re-encoded world-clock video |
| and audio for optional full-latent saving and compact Drift-Control resume. |
| |
| This is the stable pixel-smear route, not MAINodes' experimental temporal |
| latent insertion. The expanded IMAGE batch stays on CPU, but high-motion |
| scenes can still become two to three times longer internally. Narrow the |
| adapter's scene range or reduce oracle aggressiveness when RAM or wall time is |
| too high. Spatial upscale and de-rope remain in the same regeneration pass so |
| a later independent upscale cannot undo the recovered motion timing. |
| |
| #### Saving DeRoPE for a later deferred pass |
| |
| The current combined example already wires recovered frames through VAE Encode |
| and **Chain Recovered AV**, and sends that recovered latent to Upscale Segment |
| Save and Loop End. The example now has **save_latent ON**, so new renders retain |
| the complete recovered latent for a later pass. Existing workflows keep their |
| stored setting; preview-only results do not gain a latent by opening the tab. |
| |
| For a separate later latent-upscale pass, a DeRoPE save needs: |
| |
| - `save_latent` enabled **before rendering**, with Recovered AV connected to |
| Segment Save's `upscaled_latent`. Enabling it changes the profile configuration; |
| use a new profile instead of resuming a prefix saved with the old setting. |
| - A full video latent re-encoded **after Exact Recover** on the original RAW |
| clock, including the continuation head (the saver trims delivered pixels |
| separately). Recovered AV checks the H3 temporal length; a stretched pass-2 |
| intermediate is not a recovered output. |
| - Aligned recovered audio where appropriate. Joint AV saves reuse recovered |
| audio latents and the saved delivered waveform. Video-only saves that preserve |
| the original performance reuse the exact original take's audio latent, loading |
| only audio from that checkpoint. If recovered audio replaces the performance, |
| connect its re-encoded `audio_latent` to Recovered AV before saving. |
| - Source revision/hash and reference-cache provenance retained through each |
| stage. Saved child tensors use `upscaled_video`/`upscaled_audio` or |
| `upscaled_samples`; Current Scene translates these into its source AV streams. |
| Reference-cache lookup retains the original generation fingerprint and canvas, |
| then rebuilds conditioning for the processing canvas. New upscale results |
| remain linked through their DeRoPE parent to the original checkpoint. |
|
|
| Select a **different output profile** for the later pass. The original generation |
| and DeRoPE source files are not overwritten. Full latent headers and checksums |
| are checked at execution; a continuation tail or time-stretched intermediate is |
| not a valid recovered source. |
|
|
| When pass 2 should use a different reference set, insert **Upscale Reference + |
| Prompt Override** on the normal `H3_TAGGED_REFERENCES` line and connect its |
| `references` and `prompt_override` outputs to **Upscale Reference |
| Conditioning**. An explicit registry replaces, rather than ambiguously merging |
| with, the compiled cache. The node can remove comma-separated tags without |
| renumbering references by hand; the conditioning node recompiles the resulting |
| prompt, Qwen presentation, and native blocks together. Leave its reference |
| input unconnected to retain the automatic cache route. Connected picture/video |
| refs require the original H3 video VAE, while activated standalone or paired |
| audio additionally requires the H3 audio VAE. No Plan or Source Timeline is |
| introduced; sequential/source-timeline live refs should be converted to a |
| scene-local restart/standalone reference before use in deferred upscale. |
|
|
| Upscale Reference Conditioning encodes the exact saved compiled prompt by |
| default. Its optional `prompt_override` is encoded instead when supplied, so a |
| user can provide a short appearance/detail-only pass-2 prompt without repeating |
| the source scene's motion or camera instructions. Automatic natural-language |
| motion stripping is intentionally avoided because it cannot reliably separate |
| action from identity, framing, or continuity clauses. The bundled LBH workflow |
| therefore leaves the override blank and uses the original compiled prompt by |
| default. Its How To Run note retains a neutral preservation/detail replacement |
| prompt for an explicit copy/paste A/B test. |
| Missing reference caches are rebuilt automatically before applying |
| `missing_cache`, including in Pixel Conditioning and the CAT video wrapper. |
| Recovery uses the selected generation take's saved reference lineage (also |
| through DeRoPE), not the current Plan or current tag assignments. It verifies |
| archived/input project media against saved content hashes, decodes only active |
| references, and re-encodes them with the connected H3 VAEs. Native pictures, |
| video/audio references, and Qwen-only semantic anchors retain their separate |
| roles. No diffusion sampling or source-scene regeneration is needed. |
|
|
| Recovered caches use the existing deduplicated V3 tensor store and a run-local |
| `reference_cache/rebuilt_<identity>.json` index. Subsequent upscales reuse them; |
| original checkpoint metadata, source media and legacy bundles are not rewritten |
| or deleted. An absent cache bundle/object is recoverable; an existing corrupt |
| payload still fails integrity validation. |
|
|
| Recovery keeps presentation settings from an exact surviving cache manifest or |
| immutable saved recipe/reference lineage. Older takes without those settings |
| use `match`, semantic size `512`, and `timestamped_video`; the status explicitly |
| lists these defaults. Sequential/source-timeline references additionally need |
| their immutable saved Plan timing. Recovery never executes archived workflows. |
|
|
| Saved sizing is also recovered through static string input links and the modern |
| Current Tagged Ref2VA Scene's connected Tagged Scene Options. Unconnected |
| Options nodes or ambiguous/dynamic links are not treated as historical evidence. |
| The upscale `override_ref_image_size` applies to automatic caches and rebuilt |
| references as well as connected Tagged overrides. `inherit` keeps the saved |
| policy; explicit `match`/`max` rebuilds native picture conditioning as needed |
| without changing the source cache. Changing an old Match cache to Max uses its |
| picture masters, or reconstructs them from verified archived media when absent; |
| it never just relabels the smaller Match tensors. Existing Max caches keep their |
| native geometry. Semantic anchors and motion/audio policy remain separate. |
|
|
| `override_semantic_anchor_size` and `override_semantic_anchor_mode` expose the |
| same anchor choices as Tagged Scene Options, plus `inherit`. They apply to |
| cached references, missing-cache recovery, and connected Tagged references in |
| the latent, pixel, and inherited VIDEO conditioning nodes. For example, choose |
| `1280` and `timestamped_video` to explicitly restore those legacy settings. |
| Anchor size is independent of `override_ref_image_size=match/max` and the output |
| canvas. Connected anchor bundles supply their settings when inheriting. |
| Changing cached anchor settings rebuilds the presentation **and prompt labels** |
| from verified saved media into a separate reusable cache; the source checkpoint |
| and original cache remain unchanged. If the required media cannot be recovered, |
| connect explicit Tagged references rather than silently keeping the wrong |
| cached anchor settings. Status reports the explicit choices. Use a new upscale |
| profile for changed conditioning settings to avoid mixing previous processed |
| clips with the new pass. The new pixel/VIDEO widgets are appended after the |
| existing canvas controls to preserve saved workflows' positional widget values. |
|
|
| Connect `video_vae` for native visual reference rebuilds and `audio_vae` for |
| native audio. If an original file, saved reference identity, or required VAE is |
| unavailable, `error` names the recovery requirement; `text_only` explicitly |
| falls back without reference conditioning. Connected Tagged references remain |
| an intentional override and bypass automatic recovery. |
|
|
| Segment Save adopts each verified cache object into |
| `output/h3_chains/<run_name>/reference_cache/` and records only that run-local |
| descriptor. Copying or backing up the parent run therefore preserves everything |
| required to rebuild pass-2 Ref2VA conditioning. |
|
|
| New V3 scene caches are small JSON manifests pointing into |
| `reference_cache/objects/<tensor-content-hash>.safetensors`. Identical reference |
| originals, previews, and encoded latents are stored once across scenes/revisions |
| within the project. Shared staging objects are hard-linked into the project |
| where supported, otherwise copied once. V1/V2 scene-sized bundles remain readable |
| and unchanged until explicitly converted. Updating the nodes does not compact |
| or delete existing bundles. The [reference-cache converter](SCHEDULED_REFERENCES.md#converting-existing-bundles) |
| can split them losslessly, then retire each old bundle after a verified render |
| using the conversion successfully commits through an H3 saver. Small legacy JSON |
| addresses and conversion/retirement receipts remain for checkpoint compatibility. |
| Objects must not be deleted individually while any scene still references them. |
|
|
| Legacy checkpoints that still point into `output/h3_reference_cache/` migrate |
| without a rerender. Selecting their complete branch in Checkpoint Manager |
| hard-links the verified cache into the corresponding run (or copies it when a |
| hard link is unavailable) and returns a run-local descriptor. Migration never |
| deletes the global object or rewrites immutable revision metadata. Later branch |
| loads resolve the verified run-local equivalent first, so the old staging copy |
| can be archived or removed after a successful selection and upscale check. |
| Read-only workflow-local/chapter-only selections do not perform this migration; |
| checkpoints without an exact cache descriptor still use shared-cache discovery. |
|
|
| Send the backend's decoded **raw** frame batch to both Segment Save and Loop |
| End. They remove the parent scene's repeated context head exactly once, persist |
| the delivered HQ segment, and carry optional HQ context to the next iteration. |
| Set a distinct `profile` for each recipe so settings and outputs cannot collide. |
| The profile folder is: |
|
|
| ```text |
| output/h3_chains/<run_name>/upscaled/<profile>/ |
| ├── segments/ |
| ├── checkpoints/ |
| ├── prompts/ |
| ├── audio/ |
| ├── partial/ |
| ├── upscale_manifest.json |
| └── final/ |
| ``` |
|
|
| `save_latent` defaults off. Segment Save still writes a small verified |
| safetensors checkpoint containing the assembly audio, so the child run remains |
| resumable and mergeable without duplicating the much larger HQ sampler latent. |
| When the following source scene uses Drift-Control AV, that checkpoint also |
| contains only the preceding scene's 12-step HQ video tail. Pass-2 AV Prepare |
| splices this tail into scene 2+'s prefix, gives it zero added noise and a zero |
| denoise mask, and refines only the new video region. This compact context is |
| enough for exact interruption-safe HQ continuation without enabling full |
| latent saving. Older child checkpoints without the tail safely protect their |
| independently upscaled source prefix and report that fallback in node status. |
| Enable full latent saving only when you want to reopen/refine the HQ latent |
| itself. The transient `upscaled_latent` connection on Loop End remains usable |
| for scene continuity whether or not persistence is enabled. |
|
|
| For new parent renders, connect SamplerCustomAdvanced `denoised_output` to |
| Segment + Checkpoint's optional `denoised_latent` input. Existing checkpoints |
| remain valid and use their terminal sampler output. Keep the parent branch |
| until every selected child scene has been persisted; a completed child profile |
| contains its own HQ video segments and audio needed by H3 Chain Assemble. |
| Assemble recognizes the upscale manifest, reconstructs a recoverable Source |
| Timeline from the embedded parent manifest, and keeps the canonical HQ result |
| under `upscaled/<profile>/final/`. Its normal `copy_to_output` and |
| `output_subfolder` controls can additionally publish the MP4 in ComfyUI's |
| regular output tree. Legacy source-track runs without the embedded descriptor |
| still need their original full AUDIO connected to Assemble. |
|
|
| ## Run Manager |
|
|
| Connect the active Plan output to **MiniMax H3 Run Manager**. It discovers runs |
| under the ComfyUI host's `output/h3_chains`, including remote Docker hosts. |
| Select a run and choose **Load selected archive into Plan**; after confirmation |
| it restores archived prompts and Plan controls without changing graph links. |
|
|
| The two names at the top are deliberately separate: |
|
|
| - **Active Plan** is the connected Plan's current `run_name`. Generation and |
| **Save assets to active Plan** use this name. |
| - **Selected archive** is only the folder highlighted in the browser. Selecting |
| it does not change the Plan. **Load selected archive into Plan** is the only |
| action that applies its archived prompts and settings. |
|
|
| When both names match, the archive is marked **ACTIVE PLAN**. When they differ, |
| the selected archive is labeled **not loaded**, so opening an old folder or |
| inspecting it cannot be mistaken for switching the generation run. |
|
|
| Restore prefers: |
|
|
| 1. `api_prompt.json`; |
| 2. `workflow.json`; |
| 3. effective settings derived from `plan.json` for older runs. |
|
|
| The fallback retains exact scene lengths, steps, and seeds even when an old run |
| did not archive unused default-widget values. |
|
|
| ## Archive reference assets |
|
|
| Connect loader outputs to Run Manager's dynamic **Connect loader asset** socket, |
| up to 12 assets. Classify each as Picture, Video, Audio reference, or Source |
| track so a short voice reference cannot be confused with a project soundtrack. |
|
|
| Wire all Semantic Picture Anchor nodes into one Semantic Anchor Bundle, then |
| connect the Bundle's **references** output to Run Manager's |
| **tagged_references** socket. The same line can feed Tagged Ref2VA and Plan |
| Studio. The interface discovers the Bundle's upstream image loaders and |
| archives/restores them as individual picture assets without consuming the 12 |
| direct loader sockets. |
| |
| - Archive images and audio default on. |
| - Archive video defaults off because video references can be large. |
| - Only files inside ComfyUI's input directory are eligible for fallback copies. |
| - Content-addressing deduplicates unchanged media and retains changed versions. |
| |
| Restore first uses the original input-relative path. If it is missing and a |
| fallback exists, Run Manager copies the archived asset into a unique ComfyUI |
| input filename and updates a compatible loader. Targets are matched by persistent |
| binding identity, archived node ID/type, then unambiguous compatible loaders. |
| Ambiguous targets remain unchanged and are reported. |
| |
| ## Run folder contents |
| |
| ```text |
| output/h3_chains/<run_name>/ |
| ├── plan.json |
| ├── workflow.json |
| ├── api_prompt.json |
| ├── manifest.json |
| ├── prompt_history/<scene_id>/ |
| ├── segments/clip_0001.<revision>.mp4 |
| ├── segments/clip_0001.<revision>.prompt.txt |
| ├── checkpoints/clip_0001.json |
| ├── checkpoints/clip_0001.<revision>.json |
| ├── checkpoints/clip_0001.<revision>.safetensors |
| ├── generated_audio/ |
| ├── reference_cache/ |
| │ ├── scene_0001.<scene-contract>.json |
| │ └── objects/<tensor-content-hash>.safetensors |
| ├── chapters/<number>_<chapter_id>/ |
| │ ├── manifests/<snapshot_id>.json |
| │ ├── final/ |
| │ ├── frames/ |
| │ └── upscaled/<profile>/ (including seedvr2/source/) |
| ├── upscaled/<profile>/ |
| └── final/<filename>.mp4 |
| ``` |
| |
| Regenerating a scene updates its active checkpoint pointer but retains all |
| earlier MP4s, prompt sidecars, metadata, safetensors, and generated WAVs. Each |
| revision records what it supersedes. |
| |
| Workflow and API graph metadata are embedded in segment/final files using |
| ComfyUI's standard tags. `workflow.json` is the preferred file to drag back |
| into ComfyUI; `plan.json` remains the authoritative effective render record. |
| Keep run folders private when workflows contain credentials. |
| |
| ## Assembly |
| |
| Assemble accepts completed or partial manifests, including an interrupted |
| prefix reconstructed by Manifest Load. Its filename supports date |
| tokens such as `%date:yyyy-MM-dd%`, `%year%`, `%month%`, `%day%`, `%hour%`, |
| `%minute%`, and `%second%`. Existing files are never overwritten; numbered |
| suffixes are added automatically. |
| |
| ### Recovery blend schedules |
| |
| `blend_schedule` can override the Plan's global visual blend only during |
| assembly. `plan` preserves the recorded setting. A comma-separated schedule is |
| applied to scene boundaries in timeline order: `5,30` uses five frames for the |
| first join and thirty for every later join because the last value repeats. |
| `0` produces hard cuts. This does not change checkpoints, prompts, seeds, or |
| generated frames. |
| |
| When the requested boundary fits inside the saved blend MP4, assembly reuses |
| that artifact directly. If it requests more overlap than Segment Save retained, |
| connect the original MiniMax H3 video VAE to `blend_video_vae`. Recovery then |
| re-decodes the existing safetensors checkpoint into a temporary lossless RGB |
| video and deletes it after assembly. Diffusion is never rerun. The final video |
| still receives the one H.264 encode required by any pixel-space crossfade. |
| |
| Each scheduled value must not exceed that incoming scene's repeated context. |
| For example, a chain whose first join has five context frames and later joins |
| have thirty-nine can use `5,30`; requesting thirty at the first join is rejected. |
| |
| ### Optional scene-one color stabilization |
| |
| Set Assemble's `color_stabilization` to `scene_1_anchor` to counter gradual |
| exposure or saturation drift in a completed chain. Assembly measures a |
| center-weighted sample of the first generated scene, then fits only a weak, |
| bounded luma/saturation correction for each later scene. A correction is capped |
| at six code values of luma and six percent of saturation, at half the measured |
| strength. |
| |
| The exact join inherits the preceding scene's accepted correction. Starting |
| after the retained overlap, that correction moves smoothly to the next scene's |
| target over 72 frames. Consequently the option cannot introduce a new grade |
| step at the boundary and does not change motion, timing, or audio. A prelude is |
| not used as the reference: the first generated scene remains the anchor. |
| |
| This is an assembly grade, not diffusion conditioning. It does not change |
| checkpoints or future continuation input. It is disabled by default. Enabling |
| it uses the same single pixel-processing encode as a visual blend; on a hard-cut |
| assembly it replaces the otherwise lossless stream copy with one encode. |
| |
| For an experimental correction that can influence later generation instead of |
| only the final MP4, choose **Color-Stable Drift AV** through Advanced Policy or |
| on a scene's incoming transition. It applies a bounded scene-one correction to |
| the disposable copied video latent as a VAE delta, tapering from zero to full |
| strength across the 39-frame context. Scene 1 remains the anchor, scene 2 is |
| neutral, and scene 3 onward can receive a corrected predecessor tail. It does |
| not alter the saved predecessor checkpoint or audio. Because this changes |
| generation conditioning, it is recorded in the incoming-boundary dependency |
| and is intentionally separate from this assembly-only option. |
| |
| Enable `copy_to_output` to keep the canonical final in the run folder and also |
| publish an MP4 into the regular ComfyUI output tree. `output_subfolder` is |
| relative to that output root, supports nested folders and the same date tokens, |
| and may be empty to place the copy directly in `output/`. The existing |
| `filename` value is used for both copies, and collisions are versioned. |
| |
| ## Stream pixel-upscale VIDEO to PNG, scene by scene |
| |
| **Export PNG Sequence + Audio** also has a VIDEO passthrough mode for pixel |
| upscales with no saved latent. Put it **inside** the scene loop, before the |
| lossy MP4 segment save: |
|
|
| ```text |
| Final pixel refiner VIDEO -> Export PNG.video -> Segment Save.video |
| -> Loop End.video |
| Current Scene.state -> Export PNG.state |
| ``` |
|
|
| Disconnect the exporter's `manifest`, `video_vae` and `audio_vae` in this mode. |
| Do not connect the final Loop End manifest back into the in-loop exporter. |
| The original four output positions are unchanged; the new `video` output is |
| the exact incoming VIDEO, released downstream after the current scene is saved. |
| Segment Save still preserves the original audio. The PNG node does not turn |
| compressed MP4s back into supposedly lossless originals. |
|
|
| Use `output_folder` for a chosen subfolder of ComfyUI output (relative or |
| absolute). When blank, the sequence goes under the upscale profile's |
| `frames/<export_name>/`, including the chapter scope when applicable. The first |
| exported scene starts at `first_frame_number`; subsequent scenes append without |
| resetting numbering. Each scene's repeated RAW context frames are removed using |
| the current state, just as in Segment Save. This is the sequential upscale |
| delivery clock, not a later editorial reordering or blend pass. |
|
|
| `png_bit_depth` is a user choice: **8** is the existing default; **16** preserves |
| the RGB16 file-backed intermediate's precision. Both use lossless PNG compression, |
| but 8-bit explicitly quantizes higher-precision input. Neither is an H3 latent |
| checkpoint; these are full-resolution pixel backups with provenance and hashes. |
| Keep the upscaler's file-backed VIDEO path for bounded memory. Native in-memory |
| VIDEO, lazy trims/crops, wrong frame counts and mismatched frame clocks are |
| rejected rather than silently materialized or exported incorrectly. |
|
|
| Existing controls remain: `png_compression`, `embed_workflow`, `save_workers`, |
| `checkpoint_verification`, and `reuse_existing`. Compression affects speed/size, |
| not precision. The decoder streams one frame at a time and never loads all |
| scenes; at most `save_workers` PNG jobs are in flight (0 chooses up to eight). |
| There is no VAE encode/decode or GPU work in this export path. |
|
|
| Each complete scene is committed to a continuous image sequence plus |
| `export.json` before passthrough. The index records source identity, RAW trim, |
| numbering, bit depth, profile, source manifest, and PNG hashes. Interrupted |
| decode/save operations roll back that scene and keep every earlier scene intact. |
| Resume at the next missing scene with the same folder/settings. Exact repeated |
| scenes can be reused; `cached` skips hashing when previous PNG size/mtime match, |
| but verifies SHA-256 if only the timestamp differs. `strict` always hashes. |
| A timestamp difference alone never invalidates byte-identical PNGs or WAVs. |
| Incoming VIDEO files are always hashed. Different takes, changed |
| settings, missing/modified PNGs, untracked frames or out-of-order scenes never |
| overwrite a sequence: select a new folder/export name, or resume the missing |
| scene. With reuse disabled, use a new folder for a fresh export. Abrupt process |
| death during publication can leave untracked frames; these are kept and reported, |
| not silently overwritten. Concurrent writers to one folder are rejected. |
|
|
| Hard links are an optional publishing optimization, not a storage requirement. |
| If a network share rejects them (including permission denied / errno 13), the |
| exporter falls back to an exclusive file copy with a 1 MiB buffer. Existing |
| files are never replaced, and genuine write-permission or storage failures |
| still stop the export; no filesystem permissions or project ownership change. |
|
|
| The sequence is a verified export, not an editable working copy. Editing a |
| saved PNG makes its checksum differ and prevents VIDEO-mode reuse or append |
| when detected, including when exporting a later scene. Even metadata-only edits |
| or recompressing identical pixels can change the file hash. Existing PNGs are |
| never overwritten. Keep intentional retouches in a separate working copy; |
| the VIDEO passthrough still contains the incoming video, not edits made to the |
| PNG files. This node does not currently adopt edits into its saved index. |
|
|
| ## Re-decode checkpoints to PNG and WAV |
|
|
| Connect a manifest to **Export PNG Sequence + Audio**, then connect the original |
| H3 video VAE, audio VAE, or both. Video-only writes PNGs, audio-only writes one |
| continuous `audio.wav`, and both inputs produce a synchronized image sequence |
| and soundtrack in the same folder. The WAV is decoded from the checkpointed H3 |
| audio latents, preserves the generated AV boundary ownership, and follows the |
| same selected scene order and latent-safe trims as the gap-free PNG sequence. |
|
|
| The node verifies each safetensors checkpoint, decodes one scene at a time, |
| removes repeated overlap, converts small frame chunks to the selected 8-bit or |
| 16-bit RGB depth in one |
| operation, and writes each chunk through bounded parallel atomic PNG workers. |
| ComfyUI's progress bar covers verification, GPU decode, and saving. The server |
| log reports verify, checkpoint-load, decode, conversion, and save timings. The |
| deliverables and `export.json` are written under: |
|
|
| ```text |
| output/h3_chains/<run_name>/frames/<export_name>/ |
| ``` |
|
|
| For a Chapter Delivery manifest the equivalent path is |
| `chapters/<number>_<chapter_id>/frames/<export_name>/`; `export.json` records |
| the chapter number and immutable snapshot id. |
|
|
| Chapter exports default to `reuse_existing = true`. A later export using the |
| same export name looks for a successful matching export and reuses its unchanged |
| PNG prefix. New scenes continue the existing frame numbering in that folder, |
| without decoding or rewriting the earlier PNGs. An identical export skips both |
| video and audio decoding. When new scenes extend the chapter, the synchronized |
| `audio.wav` is rebuilt and atomically replaced so audio joins remain correct; |
| WAV bytes are not blindly appended. |
|
|
| Changed checkpoint revisions, trims, placements, frame numbering, or relevant |
| export settings create a new numbered folder instead of mixing old and new |
| output. A shorter/older chapter snapshot never truncates a longer export. |
| Missing, modified, or untracked PNGs, interrupted exports, and legacy exports |
| without the new verification records also use a fresh folder; their existing |
| files are left untouched. `cached` checks recorded size and modification time; |
| `strict` additionally re-hashes the reusable PNGs and WAV. Concurrent appenders |
| to the same chapter/export name are rejected while the first export is running. |
|
|
| Set `reuse_existing = false` to force a fresh folder, especially after changing |
| VAE weights, precision, ComfyUI version, or decode settings. The reuse signature |
| identifies the VAE class, not the full weights. Whole-Run exports retain their |
| existing fresh-folder behaviour regardless of this switch. |
|
|
| Reused PNGs retain their original embedded workflow/manifest metadata. |
| `export.json` is the current export index and points to the latest selected |
| immutable chapter snapshot; earlier indexes remain in `export.history/`. |
| `complete` means that this export succeeded; `chapter_complete` separately |
| indicates whether all planned chapter scenes have been generated. The node's |
| frame count includes reused frames, and its status reports reused/new counts. |
| MP4 assembly still creates a new assembled movie; incremental PNG reuse does |
| not imply in-place MP4 appending. |
|
|
| PNG compression is lossless. Use the same VAE, ComfyUI version, precision, and |
| decode settings for the closest reconstruction. The checkpointed latent is |
| exact, but a new VAE decode is not guaranteed to be bit-identical to an older |
| decode made under different settings. New nodes use compression level 1 and |
| `save_workers = 0`, which automatically selects at most eight workers. Set the |
| worker count to 1 for serial saving or raise it explicitly only when the output |
| storage can sustain more concurrent writes. |
|
|
| `checkpoint_verification = cached` still performs a complete SHA-256 check the |
| first time. Later exports skip re-hashing only while the checkpoint's recorded |
| hash, byte size, and nanosecond modification time all match. Select `strict` to |
| re-hash every checkpoint on every export. During execution, |
| `export.partial.json` is updated after every converted chunk and retained if the |
| export fails or is interrupted; a successful export replaces it with |
| `export.json`, including the effective settings and per-scene timings. |
|
|
