299 lines
12 KiB
Markdown
299 lines
12 KiB
Markdown
# 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
|
|
<Picture 1> defines the subject's face and identity.
|
|
<Picture 2> defines the subject's clothing, body design, and skateboard.
|
|
<Picture 3> 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
|
|
```
|
|
|
|

|
|
|
|
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.
|