# ComfyUI-H3-Continuum 3.3.0 Native long-form MiniMax H3 video and audio continuation for ComfyUI. **Stable release:** V3.3.0. It adds chunk-local Timeline Video and guarded decoded-video seam correction while preserving the stable sampler, Run Storage contracts, and Spectrum Interop API v1. https://github.com/user-attachments/assets/bfa8c683-fc9d-48f1-9cdb-477ca110cdf2 **H3 Continuum Sampler V3.2** generates 1 to 16 linked H3 chunks, carries raw video/audio latent context between chunks, supports T2VA, I2VA, FL2VA and multi-image Reference conditioning, and can resume completed chunks from disk. V3 delegates video and audio decoding to normal **ComfyUI Core VAE Decode nodes**. No model weights or third-party accelerator code are bundled. ## Key features - Raw paired video/audio latent continuation without decode/re-encode between chunks. - One production sampler UI with normal controls first and infrequent controls marked Advanced. - T2VA, First Frame, Last Frame, First + Last Frame, and Reference conditioning. - Up to three active Reference images across every chunk, compacted in Core connection order. - One native Reference Audio item across every chunk. - Disk-backed Run Storage with automatic resume and compatible Revision reuse. - Fixed, List, and Timeline prompts through one Sequence Prompt input. - ComfyUI Core Video/Audio VAE Decode and a separate Continuum Assemble stage. - Chunk-local Timeline Video conditioning with an efficient 0.4 MP default. - Guarded Audio Seam and Video Seam correction after Core decode. - Optional Spectrum Actual Prefix 2 interoperability. - External SageAttention, LoRA, Turbo, and Spectrum MODEL chains remain composable. - Existing legacy node identifiers remain registered for saved-workflow compatibility. ## Installation From `ComfyUI/custom_nodes/`: ```bash git clone https://github.com/ukr8b3g-cmyk/ComfyUI-H3-Continuum.git ``` Restart ComfyUI and search for **H3 Continuum Sampler V3.2**. For ZIP installation, extract the repository as `ComfyUI-H3-Continuum` under `ComfyUI/custom_nodes/`, then restart ComfyUI. Use an up-to-date ComfyUI. ComfyUI v0.32.0 or later is recommended for the current MiniMax H3 Core VAE fixes and memory improvements. No additional Python package is required beyond a working ComfyUI MiniMax H3 environment. ## Standard connection ```text H3 MODEL Loader -> optional SageAttention -> optional Turbo/LoRA -> optional Spectrum -> H3 Continuum Sampler V3.2.model MiniMax H3 CLIP/Text Encoder ------> clip MiniMax H3 Video VAE -------------> video_vae Sampler --------------------------> sampler Sigmas ---------------------------> sigmas Text (Multiline) -----------------> Sequence Prompt Optional images ------------------> first_frame / last_frame / reference_image_1/2/3 video_latents --> Core VAE Decode -----------+ audio_latents --> Core VAE Decode Audio -----+--> H3 Continuum Assemble V3 assembly_plan -------------------------------+ H3 Continuum Assemble V3.images/audio --> Create Video ``` The square grid icon on `video_latents` and `audio_latents` means a list of chunk latents. Connect each output to one normal Core decode node; ComfyUI maps the decoder across the chunk list. The `video_vae` input is used for image conditioning when needed. Continuum does not perform final Video VAE decoding internally. ## Conditioning modes The sampler selects the mode from connected image inputs. | Connected images | Mode | | --- | --- | | None | T2VA + Continuation | | First Frame | I2VA + Continuation | | Last Frame | Last-frame-conditioned + Continuation | | First + Last Frame | FL2VA + Continuation | | Reference 1, optionally Reference 2 and 3 | Reference + Continuation | Reference images and First/Last Frame are mutually exclusive. Active Reference inputs are compacted in Core connection order; bypassed sockets are ignored. Reference Image 1, 1+2, or 1+2+3 may be connected. A single active image is treated as Picture 1, and active images are numbered without gaps. **Ref2VA** is the reference-specialized checkpoint and may provide stronger reference fidelity, while **FL2VA + Reference** is also allowed. Checkpoint classification is diagnostic only; the sampler never switches MODELs automatically. **Strict Compatibility** remains reserved for H3 contracts that are actually unsafe or unsupported. Reference prompts should identify the images explicitly: ```text defines the subject's face and identity. defines the subject's clothing, body design, and skateboard. optionally defines another ordered identity, object, or environment reference. ``` Reference images persist across all Continuum chunks. ### Reference Size - **Match Output**: preserve aspect ratio and downscale toward the output pixel area. - **Max Identity**: retain a larger identity reference, downscaling only when necessary. Both modes avoid stretching and use crop-free Reference preprocessing. ## Quick start 1. Add **H3 Continuum Sampler V3.2**. 2. Connect MODEL, CLIP, Video VAE, sampler, sigmas, and one Text (Multiline) node. 3. Set `Prompt Format = Auto`. 4. Start with `chunks = 3`, `chunk_seconds = 5.0`, and `Balanced - 22 frames`. 5. Connect the raw latent outputs to Core VAE Decode and Core VAE Decode Audio. 6. Connect decoded outputs and `assembly_plan` to **H3 Continuum Assemble V3**. 7. Connect Assemble images/audio to Create Video. Recommended safe defaults: | Setting | Starting value | | --- | --- | | Prompt Format | Auto | | Continuity | Balanced - 22 frames | | Audio Continuity | On | | Audio Seam | Auto | | Report Detail | Basic | | Regenerate From | Auto | | Run Storage | Off for short tests; Save + Auto Resume for long runs | | SageAttention | Auto when backend compatibility is unknown | ## Sequence Prompt ### Fixed One prompt is reused for all chunks. ```text A continuous cinematic shot. Preserve the same subject, camera direction, lighting, movement, voice, soundscape, and music across every continuation. ``` ### List Separate one prompt per chunk with a line containing three hyphens. ```text Opening action. --- Continue seamlessly from the exact previous movement. --- Complete the action naturally without a cut or pose reset. ``` If fewer sections are provided than `chunks`, the last section is repeated. ### Timeline ```text [0-5s] Opening action. [5-10s] Continuous middle action. [10-15s] Natural ending. ``` `Prompt Format = Auto` detects Fixed, List, or Timeline syntax. ## Run Storage and automatic resume For long generations: ```text Run Storage = Save + Auto Resume Regenerate From = Auto reroll_nonce = 0 ``` ![H3 Continuum chunk auto-resume settings](docs/images/v31b-auto-resume.png) Each completed raw AV chunk is atomically saved. If generation stops, Queue the same compatible workflow again: ```text Chunk 1 saved Chunk 2 saved Chunk 3 interrupted Next Queue: Chunk 1 reused Chunk 2 reused Chunk 3 generated ``` Run Storage creates deterministic Revisions from the sampling contract. When Run Name and Auto Resume ID are blank, a stable storage ID is derived from the sampler node. It tracks observable inputs including: - H3 MODEL loader and ordered MODEL patch/wrapper chain. - LoRA/Turbo enabled state, filename, and strength. - CLIP/Qwen encoder and Video VAE loaders. - Sampler, exact sigma schedule, resolution, duration, continuity, seed, and prompts. - Conditioning mode, First/Last Frame hashes, and Reference image hashes/settings. Changing FL2VA to Ref2VA, changing LoRA strength, or changing another tracked setting creates or selects a different Revision. Returning to an earlier compatible configuration reuses its earlier Revision. The upstream graph and runtime MODEL/CLIP/VAE weight probes are both retained. Unknown wrappers or incomplete runtime probes fail safe: chunks may still be saved, but automatic reuse is disabled when identity cannot be established reliably. Saved chunk files are verified by size and SHA-256 before reuse. Storage schema changes preserve old files but do not automatically reuse unverifiable older chunks. Even when all sampling chunks are reused, Core VAE Decode and final assembly run again. A reused 15-second test can therefore still take roughly one minute. ### Regenerate from a chunk Select `Chunk N` in `Regenerate From` to reuse chunks before N and regenerate N onward. Keep `Auto` for normal resume. Chunk regeneration requires `Run Storage = Save + Auto Resume`. `reroll_nonce = 0` uses automatic Revision behavior. A positive nonce is retained for compatibility and explicit branch selection. ## Spectrum-aware continuation With a compatible [ComfyUI Spectrum MiniMax H3](https://github.com/xmarre/ComfyUI-Spectrum-MiniMax-H3), Continuum requests **Actual Prefix 2** for continuation chunks through Interop API v1. Upstream integration is currently pending in [PR #52](https://github.com/xmarre/ComfyUI-Spectrum-MiniMax-H3/pull/52); until it is merged, use the validated PR/Fork receiver and confirm the acceptance log below. ```text Chunk 1: normal path Chunk 2+: inherited raw AV Context -> at least two Actual Transformer steps -> normal Spectrum forecast schedule ``` This does not add solver steps. It protects the first evaluations after a new continuation Context before forecasting begins. A compatible receiver logs: ```text Spectrum H3: accepted H3 Continuum API v1, actual prefix=2 ``` Actual Prefix 2 is active only when the Spectrum log reports that the Continuum API request was accepted. Older or incompatible Spectrum versions continue without that receiver behavior. ### Standard and Turbo profiles ```text Quality standard approximately 20-step H3 sampling Spectrum ON Actual Prefix 2 automatic Fast Turbo / 8-step profile Spectrum OFF Experimental Turbo + Spectrum ``` Turbo + Spectrum is not the recommended default because local testing showed a higher risk of artifacts. Sol-Attn is also not part of the current recommended continuity profile. ## Timeline Video `H3 Continuum Timeline Video` adds an optional `VIDEO` source to the existing continuation pipeline. The source is sliced per 5-second chunk, resized independently from the output, encoded only for chunks that must be generated, and released after use. - `Efficient - 0.4 MP` is the default and recommended starting point. - `Match Output` preserves more source detail but can be substantially slower and heavier. - Timeline-video audio is not used; connect Reference Audio separately when needed. - Results still depend on the checkpoint, prompt, source motion, and reference compatibility. ## Assemble + Seam Connect decoded chunk images, audio, and `assembly_plan` to `H3 Continuum Assemble + Seam`. - Default: `Audio Seam = Auto`, `Video Seam = Auto`, `Report Detail = Basic`. - Video modes: `Auto`, `Auto 2`, `Analyze Only`, `Off`. - `Auto` applies guarded transient and micro-flash correction without frame deletion. - `Auto 2` additionally enables guarded exposure-ramp correction and remains experimental. - `Analyze Only` reports the boundary classification without changing images or audio. ## Why Core Decode is external Continuum owns sampling, continuation planning, chunk metadata, context trimming, audio alignment, exact duration, and final assembly. ComfyUI Core owns Video/Audio VAE execution, tiled decode behavior, memory strategy, and future H3 VAE improvements. This allows the normal Core `VAE Decode` to benefit from ComfyUI updates without copying H3 VAE implementation code into Continuum. Use Core `VAE Decode (Tiled)` when the normal decode path is unsuitable for the selected resolution or available memory. Full raw chunks are decoded before Continuum trims repeated context. Trimming latents before decode would change temporal VAE conditioning. ## Validation summary V3.3.0 passed the automated suite and Windows runtime checks for the production sampler, Reference Image/Audio, Run Storage, Timeline Video, Spectrum Actual Prefix 2, Audio Seam Auto, and guarded Video Seam Auto. `Auto 2` is included as an experimental fallback when `Auto` does not sufficiently reduce a boundary exposure ramp. Detailed test conditions, results, and remaining limits are recorded in [docs/VALIDATION_RESULTS.md](docs/VALIDATION_RESULTS.md). ## Development checks ```bash python -m compileall -q . python -m pytest -q ``` The GitHub Actions workflow runs compileall and the full pytest suite with its explicit test dependencies. ## License MIT. Model files and third-party custom nodes retain their own licenses. MiniMax H3 weights are not redistributed.