Release H3 Continuum V3.2.1
This commit is contained in:
@@ -1,686 +1,323 @@
|
||||
# ComfyUI-H3-Continuum 2.1.7
|
||||
|
||||
|
||||
https://github.com/user-attachments/assets/bfa8c683-fc9d-48f1-9cdb-477ca110cdf2
|
||||
|
||||
|
||||
# ComfyUI-H3-Continuum 3.2.1
|
||||
|
||||
Native long-form MiniMax H3 video and audio continuation for ComfyUI.
|
||||
|
||||
**H3 Continuum Sampler** generates 1 to 16 H3 chunks as one sequence. It carries the previous raw video and audio latent into the next chunk, keeps accepted chunk latents on CPU, and defers VAE decoding until sampling is complete.
|
||||
https://github.com/user-attachments/assets/bfa8c683-fc9d-48f1-9cdb-477ca110cdf2
|
||||
|
||||
## Spectrum-aware continuation
|
||||
**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.
|
||||
|
||||
**A key difference in H3 Continuum is its explicit interoperability contract with compatible builds of [ComfyUI Spectrum MiniMax H3](https://github.com/xmarre/ComfyUI-Spectrum-MiniMax-H3).**
|
||||
|
||||
For continuation chunks, Continuum requests **Actual Prefix 2** through H3 Continuum Interop API v1. Spectrum can then keep the first two solver steps after inherited Context on Actual Transformer evaluation before continuing with its normal forecast schedule.
|
||||
|
||||
```text
|
||||
Chunk 1
|
||||
-> normal sampling
|
||||
|
||||
Chunk 2+
|
||||
-> previous raw AV latent Context
|
||||
-> Actual Transformer prefix (minimum 2 steps)
|
||||
-> normal Spectrum acceleration
|
||||
-> next chunk
|
||||
```
|
||||
|
||||
This is more than simply placing Spectrum before the sampler: Continuum explicitly tells a compatible Spectrum receiver that the current branch is a continuation chunk and requests the protected Actual prefix for the new Context.
|
||||
|
||||
Among the public MiniMax H3 continuation implementations reviewed, Continuum is the only one found with an explicit Spectrum interoperability contract that requests Actual Prefix 2 for continuation chunks. This is deliberately a scoped comparison, not a claim about every H3 implementation.
|
||||
|
||||
Older or unsupported Spectrum builds ignore the hint and continue normally. The `Spectrum H3: accepted H3 Continuum API v1, actual prefix=2` log confirms that a compatible receiver accepted it.
|
||||
|
||||
### Important: Turbo LoRA + Spectrum
|
||||
|
||||
**When using a Turbo LoRA, disabling Spectrum is strongly recommended.** Local testing found that Turbo + Spectrum was more prone to visible artifacts.
|
||||
|
||||
Recommended starting profiles:
|
||||
|
||||
```text
|
||||
Quality
|
||||
Standard ~20-step sampling
|
||||
+ Spectrum ON
|
||||
+ Continuum Actual Prefix 2
|
||||
|
||||
Fast
|
||||
Turbo / 8-step profile
|
||||
+ Spectrum OFF <- strongly recommended
|
||||
|
||||
Experimental
|
||||
Turbo
|
||||
+ Spectrum ON
|
||||
-> may produce artifacts
|
||||
```
|
||||
|
||||
Spectrum remains optional. Continuum does not require Spectrum for continuation.
|
||||
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 AV latent continuation** — carries native MiniMax H3 video and audio latent Context directly into the next chunk without decode/re-encode between chunks.
|
||||
- **Spectrum-aware continuation** — emits H3 Continuum Interop API v1 and requests Actual Prefix 2 for continuation chunks.
|
||||
- **1 to 16 chunks in one sequence** — one sampler coordinates prompts, seeds, Context, sampling, and final assembly.
|
||||
- **CPU-backed accepted chunks** — completed full chunk latents leave the active VRAM sampling path.
|
||||
- **Deferred VAE decoding** — video/audio VAE decoding is postponed until sampling is complete.
|
||||
- **Fixed, List, and Timeline prompts** — one Sequence Prompt can control the complete multi-chunk sequence.
|
||||
- **State, Session, and reroll support** — advanced workflows can save continuation state, resume compatible sessions, and regenerate from a selected chunk.
|
||||
- **Composable accelerator chain** — SageAttention, Sol-Attn, LoRA, and Spectrum stay external to Continuum and can be connected through the normal ComfyUI MODEL chain.
|
||||
|
||||
## Chunk auto-resume (V3.1B+)
|
||||
|
||||
For long generations, enable Run Storage and let Continuum save each completed chunk in order. For normal automatic resume, use:
|
||||
|
||||
- `Run Storage`: `Save + Auto Resume`
|
||||
- `Regenerate From`: `Auto`
|
||||
- `reroll_nonce`: `0`
|
||||
|
||||

|
||||
|
||||
With `Run Storage` set to `Save + Auto Resume` and `Regenerate From` set to `Auto`, Continuum checks the saved Manifest and resumes from the first chunk that is not continuously available and valid.
|
||||
|
||||
If generation stops, simply Queue the same workflow again.
|
||||
|
||||
```text
|
||||
Chunk 1 saved
|
||||
Chunk 2 saved
|
||||
Chunk 3 saved
|
||||
Chunk 4 interrupted while generating
|
||||
Chunk 5 not generated
|
||||
```
|
||||
|
||||
On the next Queue, Continuum resumes from **Chunk 4**. Chunks 1-3 are reused and are not sampled again.
|
||||
|
||||
If no saved chunks are available, generation starts from Chunk 1. If the Prompt, Seed, model/patch chain, resolution, Reference images, or other sampling-contract inputs change, incompatible saved chunks are not automatically reused and the affected generation is treated as a new compatible revision.
|
||||
|
||||
### Regenerate from a specific chunk
|
||||
|
||||
To intentionally try a different result from partway through a sequence, select the starting chunk in `Regenerate From`.
|
||||
|
||||
```text
|
||||
Regenerate From = Chunk 3
|
||||
```
|
||||
|
||||
Chunk 1-2 are reused and Chunk 3 onward is regenerated. Changing `reroll_nonce` allows another random result from the same regeneration point; keep it at `0` for normal automatic resume.
|
||||
|
||||
**Important:** `Prompt Format` controls how `Sequence Prompt` is parsed (`Fixed`, `List`, or `Timeline`). It does **not** select the resume position. Resume and regeneration position are controlled by `Regenerate From`.
|
||||
|
||||
<!-- h3-standard-workflow -->
|
||||
## Standard workflow
|
||||
|
||||
[Download the standard **H3 Continuum V2** template bundle](examples/H3_Continuum_V2.zip) (recommended).
|
||||
|
||||
[Download the workflow JSON only](examples/H3_Continuum_V2.json).
|
||||
|
||||
The ZIP contains the workflow, its reference image, and a short setup guide. Extract it, copy `H3_Continuum_V2_reference.webp` into `ComfyUI/input/`, then drag `H3_Continuum_V2.json` onto the ComfyUI canvas.
|
||||
|
||||
It is a practical 3 x 5-second starting point for compatible MiniMax H3 ComfyUI systems. The bundled profile was validated on an RTX 5060 Ti 16GB system with 64GB of system RAM, but the workflow is not limited to that GPU. Adjust `chunks`, `chunk_seconds`, resolution, seed, prompts, and optional accelerators to suit the available hardware. The graph uses the stable facade nodes and keeps session, reroll, and report wiring optional.
|
||||
|
||||
Related projects:
|
||||
|
||||
- [ComfyUI Spectrum MiniMax H3](https://github.com/xmarre/ComfyUI-Spectrum-MiniMax-H3) is the optional sampling accelerator used by the bundled graph.
|
||||
|
||||
### Models referenced by the workflow
|
||||
|
||||
All model URLs stored in the JSON point to the `Comfy-Org/MiniMax-H3` distribution used for ComfyUI workflows. No third-party checkpoint host is referenced:
|
||||
|
||||
- `diffusion_models/minimax/minimax_h3_fl2va_pruned_int8_convrot.safetensors`
|
||||
- `text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors`
|
||||
- `vae/minimax_h3_video_vae_fp16.safetensors`
|
||||
- `vae/minimax_h3_audio_vae_fp32.safetensors`
|
||||
|
||||
No model weights are bundled in this repository. The workflow also contains optional/custom helper nodes from Spectrum, KJNodes (Sage Attention), rgthree, and ComfyUI-Easy-Use. Install those packages or replace/bypass their helper nodes.
|
||||
|
||||
## Why H3 Continuum exists
|
||||
|
||||
**H3 Continuum Sampler is an integrated sampler that includes H3 sampling, deferred Video/Audio VAE decoding, Context trimming, and automatic multi-chunk assembly.** The VAE model weights are not bundled or loaded internally; connect externally loaded `video_vae` and `audio_vae` inputs.
|
||||
|
||||
Continuum was created to make SVI-style long-form continuation practical with native MiniMax H3: generate several manageable chunks, carry motion and audio context forward, and assemble one result without manually rebuilding the graph for every clip.
|
||||
|
||||
The main benefit is not only continuity. A native monolithic 15-second H3 generation can put substantial pressure on VRAM. Continuum samples shorter chunks separately, carries only the required raw AV latent context, stores completed chunk data outside the active sampling path, and defers decoding until sampling is complete. This can make a 3 x 5-second sequence less likely to run out of VRAM on a 16GB GPU, although resolution, model precision, accelerators, offload settings, and available system RAM still determine the actual limit.
|
||||
|
||||
The standard workflow uses the INT8 ConvRot H3 checkpoint, SageAttention CUDA++, and optional Spectrum acceleration as the validated reference profile. On different GPUs or software stacks, start with SageAttention `Auto` or bypass optional accelerators and confirm compatibility locally. Spectrum is not required for continuity and should be disabled for native-trajectory quality comparisons. When using a Turbo LoRA, disabling Spectrum is strongly recommended because local testing showed a higher risk of visible artifacts with the combined Turbo + Spectrum path.
|
||||
|
||||
Continuum was developed independently around its integrated multi-chunk workflow, AV timeline validation, and compatibility requirements. Other H3 continuation approaches are discussed only where their workflow and implementation differences are relevant.
|
||||
|
||||
## Recommended quality-first profile
|
||||
|
||||
Continuum targets a useful reduction in long-form generation time while retaining comparatively high quality. It does not select every available accelerator for maximum speed.
|
||||
|
||||
| Component | Bundled RTX 5060 Ti profile | General recommendation |
|
||||
| --- | --- | --- |
|
||||
| MiniMax H3 model | `minimax_h3_fl2va_pruned_int8_convrot.safetensors` | Use a compatible official H3 model; the INT8 ConvRot build is the tested 16GB profile. |
|
||||
| SageAttention | `sageattn_qk_int8_pv_fp8_cuda++`, compile off | Use `Auto` when the installed SageAttention build and GPU-specific backend are unknown. |
|
||||
| Spectrum | Enabled with the settings below | Recommended for the standard non-Turbo profile. Disable it for a native-trajectory reference and strongly prefer OFF when using a Turbo LoRA. |
|
||||
| Sol-Attn | Disabled | Currently not recommended in the standard continuity profile. Local A/B runs showed more visible boundary artifacts in some outputs; this is not a universal incompatibility claim. |
|
||||
| Turbo LoRA | Disabled in the quality profile | For a fast Turbo/8-step profile, use Spectrum OFF. Turbo + Spectrum is experimental because local testing showed a higher risk of visible artifacts. |
|
||||
| Seam Correction | `Auto` | Safe general starting point. In the current local A/B sample, `Off` produced the least noticeable visual boundary. Compare `Auto` and `Off` first. |
|
||||
|
||||
Recommended Spectrum values used by this profile:
|
||||
|
||||
```text
|
||||
blend_weight = 0.50
|
||||
warmup_steps = 1
|
||||
offline_smoothing_replay = true
|
||||
bootstrap_first_forecast = true
|
||||
audio_blend_weight = 0.00
|
||||
```
|
||||
|
||||
Continuum automatically requests Actual Prefix 2 for continuation chunks. This is not an extra user-facing Spectrum setting and does not increase the configured solver-step count.
|
||||
|
||||
### Seam Correction A/B note
|
||||
|
||||
The bundled workflow keeps `Auto` as a conservative general default. In the current 3 x 5-second local comparison, however, `Off` gave the most natural-looking join. `Auto` may apply a measured color adjustment or short blend that improves its numeric seam score but is not always preferred by visual inspection.
|
||||
|
||||
For a new model, prompt, resolution, or accelerator combination, render the same seed with `Auto` and `Off`. Prefer `Off` when Native Continuity already produces a clean boundary; use `Auto` when it visibly reduces a remaining luminance, color, or audio discontinuity.
|
||||
|
||||
## Quick start
|
||||
|
||||
1. Install the custom node and restart ComfyUI.
|
||||
2. Add **H3 Continuum Sampler**.
|
||||
3. Connect the normal H3 model, CLIP, VAEs, sampler, and sigmas.
|
||||
4. Connect one **Text (Multiline)** node to **Sequence Prompt**.
|
||||
5. For image-to-video, connect the source image to **first_frame**.
|
||||
6. Connect **images** and **audio** to your normal video output node.
|
||||
7. Start with two 5-second chunks and the settings shown below.
|
||||
|
||||
Most users only need **H3 Continuum Sampler**. The helper nodes are optional.
|
||||
- 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 two persistent Reference images 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.
|
||||
- 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
|
||||
|
||||
### Git installation
|
||||
From `ComfyUI/custom_nodes/`:
|
||||
|
||||
From the ComfyUI custom_nodes directory:
|
||||
|
||||
~~~bash
|
||||
```bash
|
||||
git clone https://github.com/ukr8b3g-cmyk/ComfyUI-H3-Continuum.git
|
||||
~~~
|
||||
```
|
||||
|
||||
Restart ComfyUI, then search for **H3 Continuum Sampler**.
|
||||
Restart ComfyUI and search for **H3 Continuum Sampler V3.2**.
|
||||
|
||||
For Stability Matrix, the destination is normally similar to:
|
||||
For ZIP installation, extract the repository as `ComfyUI-H3-Continuum` under `ComfyUI/custom_nodes/`, then restart ComfyUI.
|
||||
|
||||
~~~text
|
||||
D:\StabilityMatrix\Data\Packages\<ComfyUI package>\custom_nodes\
|
||||
~~~
|
||||
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.
|
||||
|
||||
### ZIP or Windows installer
|
||||
|
||||
1. Extract the repository as **ComfyUI-H3-Continuum**.
|
||||
2. Place it in **ComfyUI/custom_nodes/**.
|
||||
3. Run **install_windows.bat** if you want the included Windows installer to copy and validate the package.
|
||||
4. Restart ComfyUI.
|
||||
|
||||
If an older **ComfyUI-H3-Continuum-Join** folder exists, remove or rename it before starting ComfyUI. Do not load both folders at the same time.
|
||||
|
||||
No additional pip packages are required beyond the normal ComfyUI MiniMax H3 environment.
|
||||
No additional Python package is required beyond a working ComfyUI MiniMax H3 environment.
|
||||
|
||||
## Standard connection
|
||||
|
||||
~~~text
|
||||
H3 MODEL loader
|
||||
|
|
||||
+-> optional SageAttention
|
||||
+-> optional Sol-Attn
|
||||
+-> optional LoRA
|
||||
+-> optional Spectrum
|
||||
|
|
||||
v
|
||||
H3 Continuum Sampler.model
|
||||
```text
|
||||
H3 MODEL Loader
|
||||
-> optional SageAttention
|
||||
-> optional Turbo/LoRA
|
||||
-> optional Spectrum
|
||||
-> H3 Continuum Sampler V3.2.model
|
||||
|
||||
CLIP loader -----------------------> clip
|
||||
MiniMax H3 CLIP/Text Encoder ------> clip
|
||||
MiniMax H3 Video VAE -------------> video_vae
|
||||
MiniMax H3 Audio VAE -------------> audio_vae
|
||||
Sampler --------------------------> sampler
|
||||
Sigmas ---------------------------> sigmas
|
||||
Text (Multiline) -----------------> Sequence Prompt
|
||||
Load Image -----------------------> first_frame
|
||||
Optional images ------------------> first_frame / last_frame / reference_image_1/2
|
||||
|
||||
H3 Continuum Sampler.images ------> Create Video.images
|
||||
H3 Continuum Sampler.audio -------> Create Video.audio
|
||||
~~~
|
||||
video_latents --> Core VAE Decode -----------+
|
||||
audio_latents --> Core VAE Decode Audio -----+--> H3 Continuum Assemble V3
|
||||
assembly_plan -------------------------------+
|
||||
|
||||
The accelerator chain is optional. A typical accelerated order is:
|
||||
H3 Continuum Assemble V3.images/audio --> Create Video
|
||||
```
|
||||
|
||||
~~~text
|
||||
H3 MODEL -> SageAttention -> Sol-Attn -> LoRA -> Spectrum
|
||||
~~~
|
||||
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.
|
||||
|
||||
When troubleshooting, start with fewer accelerators and add them back one at a time.
|
||||
The `video_vae` input is used for image conditioning when needed. Continuum does not perform final Video VAE decoding internally.
|
||||
|
||||
### Main inputs
|
||||
## Conditioning modes
|
||||
|
||||
| Input | Connect |
|
||||
The sampler selects the mode from connected image inputs.
|
||||
|
||||
| Connected images | Mode |
|
||||
| --- | --- |
|
||||
| **model** | The final MODEL from the normal H3 model or accelerator chain |
|
||||
| **clip** | MiniMax H3 text encoder / CLIP output |
|
||||
| **video_vae** | MiniMax H3 Video VAE |
|
||||
| **audio_vae** | MiniMax H3 Audio VAE |
|
||||
| **sampler** | The sampler used by the normal H3 workflow |
|
||||
| **sigmas** | The corresponding sigma schedule |
|
||||
| **Sequence Prompt** | One external Text (Multiline) STRING |
|
||||
| **first_frame** | Source image for image-to-video |
|
||||
| **prompt_overrides** | Optional H3 Continuum Clip Overrides pack |
|
||||
| **advanced** | Optional H3 Continuum Advanced pack |
|
||||
| None | T2VA + Continuation |
|
||||
| First Frame | I2VA + Continuation |
|
||||
| Last Frame | Last-frame-conditioned + Continuation |
|
||||
| First + Last Frame | FL2VA + Continuation |
|
||||
| Reference 1, optionally Reference 2 | Reference + Continuation |
|
||||
|
||||
### Main outputs
|
||||
Reference images and First/Last Frame are mutually exclusive. `Reference 2` cannot be used without `Reference 1`.
|
||||
|
||||
| Output | Use |
|
||||
For the formally supported Reference path, connect a MiniMax H3 **Ref2VA** MODEL upstream. FL2VA MODEL + Reference conditioning has also worked in local testing, but should be treated as experimental rather than an official checkpoint pairing.
|
||||
|
||||
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.
|
||||
```
|
||||
|
||||
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 |
|
||||
| --- | --- |
|
||||
| **images** | Connect directly to the image/video frames input of the output node |
|
||||
| **audio** | Connect directly to the audio input of the output node |
|
||||
| **result** | Optional packed State, Session, and report data |
|
||||
|
||||
<!-- h3-node-guide -->
|
||||
## Sampler and Advanced controls
|
||||
|
||||
### Input image scaling
|
||||
|
||||

|
||||
|
||||
The bundled workflow uses **Scale Image to Total Pixels** before `first_frame`:
|
||||
|
||||
- `upscale_method: area` is appropriate for reducing a larger source image with stable averaging.
|
||||
- `megapixels: 0.50` preserves the source aspect ratio while targeting approximately 0.5 million pixels.
|
||||
- `resolution_steps: 32` rounds width and height to model-friendly multiples of 32.
|
||||
- The bundled portrait is reduced from 848 x 1264 to approximately 576 x 864; the exact rounded size is supplied to the Continuum sampler through the image-size nodes.
|
||||
- If a 16GB GPU runs out of VRAM, reduce this first to `0.30 MP`, which is approximately 448 x 672 for the same portrait.
|
||||
|
||||
This node changes generation resolution, not the Continuum context length. Increasing megapixels raises VRAM use and generation time for every chunk.
|
||||
|
||||
The screenshot shows the same control at 0.60 MP for illustration. The current bundled JSON uses 0.50 MP.
|
||||
|
||||

|
||||
|
||||
The main sampler is sufficient for a normal first run:
|
||||
|
||||
- `Sequence Prompt`: one fixed prompt, a `---`-separated list, or a timeline prompt.
|
||||
- `Prompt Format`: `Auto` is the recommended default.
|
||||
- `chunks`: number of generated clips.
|
||||
- `chunk_seconds`: requested duration of each clip.
|
||||
- `width` / `height`: inherited from the connected image-size path when linked.
|
||||
- `continuity`: `Balanced - 22 frames` is the general-purpose default.
|
||||
- `base_seed` and `control after generate`: define the chunk seed sequence.
|
||||
- `seam_correction`: `Auto` is the safe default; it keeps the legacy video seam when correction does not improve the measured boundary.
|
||||
- `prompt_overrides`: optional sparse per-clip replacement pack.
|
||||
- `advanced`: optional settings pack. Leave it disconnected to use normal defaults.
|
||||
|
||||

|
||||
|
||||
Use **H3 Continuum Advanced** only when the basic node is not enough:
|
||||
|
||||
- `last_frame`: optional final-frame anchor.
|
||||
- `session`: resumes or reuses a Continuum session.
|
||||
- `initial_state`: begins from a saved Continuum state.
|
||||
- `prompt_plan`: accepts an externally prepared prompt plan.
|
||||
- `audio_continuity`: keeps audio context across chunk boundaries.
|
||||
- `exact_total_duration`: trims or pads the assembled result to the requested duration.
|
||||
- `Report Detail`: `Basic` is the standard default. Use Detailed Report only for troubleshooting.
|
||||
- `reroll_from_chunk`: regenerates from a selected chunk; `0` disables reroll.
|
||||
- `reroll_nonce`: changes a reroll without replacing the main seed.
|
||||
- `strict_compatibility`: fails closed when the native H3 layout contract is incompatible.
|
||||
- `debug`: enables additional diagnostic logging.
|
||||
- `show_preview`: enables the sampling preview.
|
||||
|
||||
### Wiring reminder
|
||||
|
||||
For a standard graph, connect the patched MODEL path to `model`, the MiniMax H3 text encoder to `clip`, the video/audio VAEs to their matching inputs, the sampler and sigmas, a multiline text node to `Sequence Prompt`, and the scaled source image to `first_frame`. Connect `images` and `audio` to Create Video or Save Video.
|
||||
|
||||
`prompt_overrides`, `advanced`, and the Result helper are optional. Use **H3 Continuum Result** only when you need `last_state`, `session`, or the text report.
|
||||
|
||||
## Recommended first run
|
||||
|
||||
| Setting | Recommended value |
|
||||
| --- | --- |
|
||||
| **Prompt Format** | Auto |
|
||||
| **chunks** | 2 |
|
||||
| **chunk_seconds** | 5.0 |
|
||||
| **width / height** | Match the intended H3 generation resolution |
|
||||
| **continuity** | Balanced - 22 frames |
|
||||
| **base_seed** | Fixed while comparing settings |
|
||||
| **control after generate** | fixed for A/B testing |
|
||||
| **seam_correction** | Auto for normal use |
|
||||
|
||||
This produces approximately 10 seconds.
|
||||
|
||||
For a native-continuity comparison, use the same prompt and seed and compare:
|
||||
|
||||
~~~text
|
||||
Seam Correction = Off
|
||||
Seam Correction = Auto
|
||||
~~~
|
||||
|
||||
**Auto** is the normal recommendation. It keeps the native seam unless the guarded correction produces a safely measurable improvement.
|
||||
|
||||
### Seam Correction modes
|
||||
|
||||
- **Auto**: Native-first mode. Applies post-decode correction only when the guarded candidate improves the measured seam.
|
||||
- **Off**: No post-decode seam correction. Use this to inspect Native Continuity directly.
|
||||
- **Basic**: Runs the V2.1 seam-correction path directly.
|
||||
|
||||
### Continuity profiles
|
||||
|
||||
- **Auto - conservative**: Chooses a conservative context profile from the previous state.
|
||||
- **Fast - 5 frames**: Lowest overlap and lowest continuity cost.
|
||||
- **Balanced - 22 frames**: Recommended starting point.
|
||||
- **Strong - 39 frames**: More context, with higher cost and a greater risk of over-constraining motion.
|
||||
| Prompt Format | Auto |
|
||||
| Continuity | Balanced - 22 frames |
|
||||
| Audio Continuity | On |
|
||||
| Audio Seam | Off |
|
||||
| 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
|
||||
|
||||
Connect a single **Text (Multiline)** node to **Sequence Prompt**.
|
||||
|
||||
### Auto
|
||||
|
||||
Auto detects Fixed, List, or Timeline syntax. This is recommended for normal use.
|
||||
|
||||
### Fixed
|
||||
|
||||
One prompt is used for every chunk.
|
||||
One prompt is reused for all chunks.
|
||||
|
||||
~~~text
|
||||
A single continuous cinematic performance. Preserve the same person,
|
||||
lighting, camera direction, motion, voice, and music across every chunk.
|
||||
~~~
|
||||
```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
|
||||
The woman begins singing while the camera slowly pushes in.
|
||||
```text
|
||||
Opening action.
|
||||
---
|
||||
She continues the same phrase without a cut, reset, or pose jump.
|
||||
Continue seamlessly from the exact previous movement.
|
||||
---
|
||||
She resolves the final note naturally and releases a soft breath.
|
||||
~~~
|
||||
Complete the action naturally without a cut or pose reset.
|
||||
```
|
||||
|
||||
If fewer List sections are supplied than the configured chunk count, the last section is reused.
|
||||
If fewer sections are provided than `chunks`, the last section is repeated.
|
||||
|
||||
### Timeline
|
||||
|
||||
Use time or chunk sections in one multiline prompt.
|
||||
|
||||
~~~text
|
||||
```text
|
||||
[0-5s]
|
||||
The woman begins singing. The piano phrase remains unresolved.
|
||||
|
||||
[5-10s]
|
||||
Continue from the exact preceding breath, pose, camera movement, and melody.
|
||||
|
||||
[10-15s]
|
||||
Complete the melody naturally during the final second.
|
||||
~~~
|
||||
|
||||
Chunk headers are also accepted:
|
||||
|
||||
~~~text
|
||||
[Chunk 1]
|
||||
Opening action.
|
||||
|
||||
[Chunk 2]
|
||||
[5-10s]
|
||||
Continuous middle action.
|
||||
|
||||
[Chunk 3]
|
||||
[10-15s]
|
||||
Natural ending.
|
||||
~~~
|
||||
|
||||
## How continuation works
|
||||
|
||||
For every continuation chunk, Continuum:
|
||||
|
||||
1. Reads the accepted previous raw H3 video and audio latent.
|
||||
2. Extracts a phase-valid video and audio context window.
|
||||
3. Adds that context as fixed reference rows.
|
||||
4. Keeps new target audio and video rows separate and writable.
|
||||
5. Clones the workflow MODEL once for the current chunk.
|
||||
6. Samples the next chunk without decoding and re-encoding the prior result.
|
||||
7. Stores the accepted full chunk latent on CPU.
|
||||
8. Decodes and assembles all accepted chunks after sampling finishes.
|
||||
|
||||
The workflow input MODEL is not modified. Each chunk clone has its own Spectrum runtime/history.
|
||||
|
||||
When valid continuation context exists, Continuum emits Spectrum Interop API v1 with an Actual Prefix request of 2. Older or unsupported Spectrum versions ignore the hint and continue normally.
|
||||
|
||||
## Optional helper nodes
|
||||
|
||||
These nodes are not needed for the basic workflow.
|
||||
|
||||
### H3 Continuum Clip Overrides
|
||||
|
||||
Use this only when selected clips need prompts different from the main Sequence Prompt.
|
||||
|
||||
Connect one **Text (Multiline)** to **Override Script** and use explicit sparse sections:
|
||||
|
||||
~~~text
|
||||
[Clip 2]
|
||||
Move to a closer shot while preserving the same motion and voice.
|
||||
|
||||
[Clip 5]
|
||||
Finish the song naturally and hold the final note.
|
||||
~~~
|
||||
|
||||
Only Clip 2 and Clip 5 are replaced. All unspecified clips continue using the main Sequence Prompt.
|
||||
|
||||
**[Chunk N]** is also accepted. Duplicate clip numbers and clip numbers outside the configured chunk count are rejected.
|
||||
|
||||
Connect the pack output to **H3 Continuum Sampler.prompt_overrides**.
|
||||
|
||||
### H3 Continuum Advanced
|
||||
|
||||
Use this node for resume data and infrequent controls. Connect its output to **H3 Continuum Sampler.advanced**.
|
||||
|
||||
Important controls include:
|
||||
|
||||
- **last_frame**: Optional final-frame anchor for the final chunk.
|
||||
- **session**: Continue or reroll from a prior V2 Session.
|
||||
- **initial_state**: Start from a compatible saved State. Do not connect both Session and Initial State.
|
||||
- **prompt_plan**: Advanced or compatibility prompt-plan input.
|
||||
- **audio_continuity**: Continue the prior raw audio latent.
|
||||
- **exact_total_duration**: Correct the assembled output to the requested total duration.
|
||||
- **diagnostics**: Basic, Detailed Report, or Off.
|
||||
- **reroll_from_chunk**: Keep accepted earlier chunks and regenerate from this one-based chunk number.
|
||||
- **reroll_nonce**: Derive a different reroll seed without changing the base seed.
|
||||
- **strict_compatibility**: Stop on unknown or unsafe H3 layout contracts.
|
||||
- **debug**: Enable internal diagnostic logging.
|
||||
- **show_preview**: Enable the normal sampling preview.
|
||||
|
||||
### H3 Continuum Result
|
||||
|
||||
Connect the Sampler **result** output when you need to expose:
|
||||
|
||||
- **last_state**
|
||||
- **session**
|
||||
- **report**
|
||||
|
||||
For ordinary final video generation, this node is unnecessary.
|
||||
|
||||
## Sessions and rerolling
|
||||
|
||||
A Session stores accepted CPU latents, prompts, seeds, dimensions, and continuation metadata.
|
||||
|
||||
Typical advanced use:
|
||||
|
||||
~~~text
|
||||
H3 Continuum Sampler.result
|
||||
-> H3 Continuum Result.session
|
||||
-> H3 Continuum Save Session
|
||||
~~~
|
||||
|
||||
Later:
|
||||
|
||||
~~~text
|
||||
H3 Continuum Load Session
|
||||
-> H3 Continuum Advanced.session
|
||||
-> H3 Continuum Sampler.advanced
|
||||
~~~
|
||||
|
||||
Resolution changes are rejected rather than silently resizing State or Session data.
|
||||
|
||||
## Diagnostics and debugging
|
||||
|
||||
Use **Basic** diagnostics for normal testing. Use **Detailed Report** when inspecting seam scores, selected cuts, audio correlation, correction fallback, and per-chunk context.
|
||||
|
||||
Set **debug=true** only when deeper runtime information is needed. The single-clone implementation reports object IDs without retaining the objects:
|
||||
|
||||
~~~text
|
||||
Continuum model lifetime: input=<id> chunk=<id> parent=<id> base=<id>
|
||||
~~~
|
||||
|
||||
For the expected single-clone path, every chunk parent should be the same workflow input MODEL:
|
||||
|
||||
~~~text
|
||||
chunk1.parent -> input MODEL
|
||||
chunk2.parent -> input MODEL
|
||||
chunk3.parent -> input MODEL
|
||||
~~~
|
||||
|
||||
With a compatible Spectrum version, continuation chunks should also log:
|
||||
|
||||
~~~text
|
||||
Spectrum H3: accepted H3 Continuum API v1, actual prefix=2
|
||||
~~~
|
||||
|
||||
**0 models unloaded** by itself is normal model-management information. The relevant leak warnings are:
|
||||
|
||||
~~~text
|
||||
Potential memory leak detected with model MiniMaxH3
|
||||
WARNING, memory leak with model MiniMaxH3
|
||||
~~~
|
||||
|
||||
If those warnings occur, compare identical one-chunk and two-chunk runs, then test Spectrum, Sol-Attn, and Sage individually.
|
||||
|
||||
## Special and compatibility nodes
|
||||
|
||||
The following nodes remain available for advanced workflows or saved-workflow compatibility:
|
||||
|
||||
- **H3 Continuum Sampler V2**: Legacy/Core identifier used by older V2 workflows.
|
||||
- **H3 Continuum Prompt Plan**: Explicit prompt-plan construction and inspection.
|
||||
- **H3 Continuum Save Session**
|
||||
- **H3 Continuum Load Session**
|
||||
- **H3 Continuum Session Info**
|
||||
- V1 Join, Finish, Assemble, Save State, and Load State nodes.
|
||||
|
||||
New workflows should normally use the compact **H3 Continuum Sampler** facade.
|
||||
|
||||
## Compatibility and safety
|
||||
|
||||
- Native H3 PackedLayout is preserved.
|
||||
- layout.position_ids identity is preserved when MM-RoPE coordinates are adjusted.
|
||||
- State and Session schema remain compatible.
|
||||
- V1 node identifiers remain registered.
|
||||
- Video and audio VAEs are not run between H3 chunks.
|
||||
- Full accepted chunk latents are stored on CPU.
|
||||
- SageAttention, Sol-Attn, LoRA, and Spectrum remain external packages.
|
||||
- Unknown H3 layout contracts fail clearly instead of producing a subtly incorrect continuation.
|
||||
|
||||
<!-- h3-related-projects -->
|
||||
## Related projects and implementation scope
|
||||
|
||||
| Project | Primary purpose | Workflow model | Main technical difference |
|
||||
| --- | --- | --- | --- |
|
||||
| **H3 Continuum** | Generate and assemble 1-16 H3 chunks | One integrated sampler with optional facade packs | Carries raw paired AV latent context, manages prompts/seeds/session/reroll, defers decode, and can apply post-decode seam correction. |
|
||||
| **H3 Motion Context** | Continue motion and sound from one clip into another | Explicit context, trim, and optional save/load nodes across runs | Pins prior video/audio context into the next native H3 generation and trims the repeated context from the delivered clip. |
|
||||
| **Spectrum MiniMax H3** | Reduce H3 sampling time | MODEL wrapper before the guider/sampler | Forecasts selected post-transformer hidden features. It is an approximate accelerator, not a clip-continuity system, and may change the generated result. |
|
||||
|
||||
Continuum does not copy, vendor, or bundle source code from Spectrum or H3 Motion Context. Compatibility uses ComfyUI's MODEL/payload behavior. For a supported Spectrum build, Continuum emits a small API v1 metadata hint requesting at least two actual solver steps at the start of a continuation chunk; unsupported builds ignore it and continue normally.
|
||||
|
||||
## Spectrum Actual Prefix 2 interoperability
|
||||
|
||||
Spectrum accelerates sampling by forecasting selected post-transformer hidden features from Actual H3 evaluations. A continuation chunk introduces a new AV Context and Packed Layout. Forecasting immediately after that transition could start before Spectrum has enough Actual features for the new context.
|
||||
|
||||
Continuum avoids that conflict without disabling or modifying Spectrum:
|
||||
|
||||
```text
|
||||
Stable input MODEL
|
||||
-> call-local MODEL clone for the chunk
|
||||
-> build and validate the continuation AV Context
|
||||
-> freeze the branch-specific Packed Layout signature
|
||||
-> Actual solver step 0
|
||||
-> Actual solver step 1
|
||||
-> allow the normal Spectrum forecast schedule
|
||||
```
|
||||
|
||||
- The input MODEL is not mutated; every chunk receives an isolated clone and Spectrum runtime.
|
||||
- The read-only `h3_continuum` API v1 hint is emitted only when valid previous Context exists.
|
||||
- The effective prefix is the larger of Spectrum's own warmup and Continuum's requested prefix, clamped to the configured solver-step count.
|
||||
- Context rows and generated Target rows remain separate in the native H3 Packed Layout.
|
||||
- The Packed Layout is checked per logical branch and must remain structurally stable during Native Actual calls.
|
||||
- Chunk 1 emits no hint and follows the normal Spectrum path.
|
||||
- Offline Replay reuses the recorded Actual anchors and does not apply the prefix a second time.
|
||||
- Older or unsupported Spectrum builds ignore the metadata and continue normally.
|
||||
`Prompt Format = Auto` detects Fixed, List, or Timeline syntax.
|
||||
|
||||
Actual Prefix 2 does not add two solver steps and does not run the whole sample twice. With a 20-step schedule, the result still uses 20 solver steps. Under the standard Spectrum `warmup_steps=1` profile, it normally replaces one early forecast with one additional Actual Transformer evaluation. If the configured warmup is already two or more, it adds no evaluation.
|
||||
## Run Storage and automatic resume
|
||||
|
||||
This design gives Spectrum two Context-specific Actual anchors before forecasting. It trades a small amount of the maximum possible acceleration for more stable continuation behavior.
|
||||
|
||||
### Report output and optional Detailed Report
|
||||
|
||||

|
||||
|
||||
The bundled workflow uses `Basic` reporting and leaves `H3 Continuum Result.report` unconnected. No additional report-display extension is required for the standard workflow.
|
||||
|
||||
The screenshot above is an optional troubleshooting example using `Detailed Report` and an external text display node. That display node is not included in the bundled template.
|
||||
For long generations:
|
||||
|
||||
```text
|
||||
Continuum report:
|
||||
interop=emitted actual_prefix=2 consumer=not_observable
|
||||
Run Storage = Save + Auto Resume
|
||||
Regenerate From = Auto
|
||||
reroll_nonce = 0
|
||||
```
|
||||
|
||||
Spectrum log:
|
||||

|
||||
|
||||
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. 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.
|
||||
|
||||
Unknown upstream wrappers fail safe: chunks may still be saved, but automatic reuse is disabled when the graph cannot be identified reliably.
|
||||
|
||||
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.
|
||||
|
||||
`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.
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
`consumer=not_observable` is not an error. Interop API v1 is deliberately a one-way, read-only hint without an acknowledgement side channel. Spectrum's `accepted` log confirms that the hint was consumed.
|
||||
Older Spectrum versions ignore the hint and continue normally.
|
||||
|
||||
### Independently developed scope
|
||||
### Standard and Turbo profiles
|
||||
|
||||
The general idea of continuing one clip from another is not claimed as unique. Continuum's AV timeline validation, branch-local Packed Layout guard, call-local MODEL isolation, Spectrum Actual Prefix 2 contract, integrated multi-chunk orchestration, and seam-correction pipeline were developed independently for this project. No Spectrum or H3 Motion Context source code is copied or bundled.
|
||||
```text
|
||||
Quality
|
||||
standard approximately 20-step H3 sampling
|
||||
Spectrum ON
|
||||
Actual Prefix 2 automatic
|
||||
|
||||
### License and external-content boundaries
|
||||
Fast
|
||||
Turbo / 8-step profile
|
||||
Spectrum OFF
|
||||
|
||||
- This repository is licensed under [GPL-3.0](LICENSE).
|
||||
- [Spectrum MiniMax H3](https://github.com/xmarre/ComfyUI-Spectrum-MiniMax-H3/blob/main/LICENSE) is GPL-3.0.
|
||||
- [H3 Motion Context](https://github.com/NikoDemon80/ComfyUI-H3-Motion-Context/blob/main/LICENSE) is GPL-3.0.
|
||||
- The separate [ComfyUI workflow templates repository](https://github.com/Comfy-Org/workflow_templates) is MIT-licensed.
|
||||
- Model files, model cards, and other custom-node packages remain external and keep their own licenses and usage terms.
|
||||
Experimental
|
||||
Turbo + Spectrum
|
||||
```
|
||||
|
||||
The MIT license of the template repository does not change the licenses of model weights or third-party custom nodes. This project does not redistribute MiniMax H3 weights.
|
||||
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.
|
||||
|
||||
### Tested environment
|
||||
## Why Core Decode is external
|
||||
|
||||
- GPU: NVIDIA GeForce RTX 5060 Ti 16GB.
|
||||
- System memory: 64GB RAM.
|
||||
- Runtime: Python 3.13.12, PyTorch 2.13.0+cu130, CUDA 13.0.
|
||||
- SageAttention: 2.2.0+cu130, using KJNodes FP8 CUDA++ with compile disabled.
|
||||
- Verified baseline environment: 3 x 5-second runs at approximately 448 x 672 (0.3 MP), using the INT8 ConvRot checkpoint and SageAttention CUDA++.
|
||||
- Bundled template profile: 3 x 5 seconds at 0.5 MP. Treat this higher-resolution profile as a starting point and monitor VRAM on the first run.
|
||||
- Longer-than-15-second chains are supported by the node design but have not yet been validated in this environment.
|
||||
- OOM avoidance is not guaranteed; peak usage depends on resolution, precision, model patches, Spectrum settings, ComfyUI offload behavior, and other loaded nodes.
|
||||
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.
|
||||
|
||||
## Tested results
|
||||
|
||||
Local validation environment:
|
||||
|
||||
```text
|
||||
GPU: NVIDIA GeForce RTX 5060 Ti 16GB
|
||||
System RAM: 64GB
|
||||
ComfyUI: v0.32.0 generation
|
||||
```
|
||||
|
||||
Observed successful runs include:
|
||||
|
||||
- 3 x 5 seconds at approximately 0.3 MP, 0.5 MP, and 0.6 MP.
|
||||
- 6 x 5 seconds (30 seconds) at approximately 0.3 MP.
|
||||
- 12 x 5 seconds (60 seconds) at approximately 0.3 MP.
|
||||
- 12 x 5 seconds at approximately 0.5 MP without OOM; generation was substantially slower.
|
||||
- Reference + Continuation with two images using both FL2VA and Ref2VA MODEL tests.
|
||||
- V3.2.1 Revision switching: FL2VA -> Ref2VA -> FL2VA.
|
||||
- LoRA strength change created a new Revision; restoring the prior strength reused the earlier Revision.
|
||||
- Complete 3-chunk reuse reported `3 reused / 0 generated`; Core decode/assembly took about 58-61 seconds at 736 x 416.
|
||||
|
||||
These are local results, not minimum hardware guarantees. Resolution, model precision, patches, offload behavior, and other loaded nodes determine actual limits.
|
||||
|
||||
## Diagnostics
|
||||
|
||||
`status` is a normal STRING output. Connect it to Core **Preview as Text** when you need the sampling and Run Storage report.
|
||||
|
||||
Useful lines include:
|
||||
|
||||
```text
|
||||
Conditioning mode: Reference + Continuation.
|
||||
interop=emitted actual_prefix=2
|
||||
3 reused, 0 generated
|
||||
resume=complete
|
||||
```
|
||||
|
||||
`accelerator markers not detected (informational only)` is not an error. It only means the optional accelerator marker was not observable.
|
||||
|
||||
Use `Report Detail = Basic` normally. Enable detailed diagnostics and `debug` only when troubleshooting.
|
||||
|
||||
## Compatibility and scope
|
||||
|
||||
- Native MiniMax H3 PackedLayout is preserved.
|
||||
- Video and audio VAEs are not run between sampling chunks.
|
||||
- Accepted raw chunk latents are retained on CPU.
|
||||
- MODEL input is cloned once per chunk; the workflow MODEL is not mutated.
|
||||
- SageAttention, LoRA/Turbo, Spectrum, and model weights remain external.
|
||||
- Unknown H3 layout contracts fail clearly.
|
||||
- Legacy V1/V2/V3 node identifiers remain registered for older workflows but are not the recommended starting point.
|
||||
|
||||
Continuum is independently implemented. It does not copy or bundle source code from Spectrum or [H3 Motion Context](https://github.com/NikoDemon80/ComfyUI-H3-Motion-Context).
|
||||
|
||||
## Development checks
|
||||
|
||||
Use the same Python environment as ComfyUI:
|
||||
|
||||
~~~bash
|
||||
```bash
|
||||
python -m compileall -q .
|
||||
pytest -q
|
||||
~~~
|
||||
python -m pytest -q
|
||||
```
|
||||
|
||||
Current local validation for this change:
|
||||
Current V3.2.1 runtime validation:
|
||||
|
||||
~~~text
|
||||
74 passed
|
||||
~~~
|
||||
|
||||
GPU validation should compare identical prompts, seeds, resolutions, samplers, and sigmas across:
|
||||
|
||||
~~~text
|
||||
Native
|
||||
Sage
|
||||
Sage + Sol-Attn
|
||||
Sage + Spectrum
|
||||
Sage + Sol-Attn + Spectrum
|
||||
~~~
|
||||
```text
|
||||
112 passed
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
GPL-3.0-or-later. External accelerator source code is not bundled.
|
||||
GPL-3.0-or-later. Model files and third-party custom nodes retain their own licenses. MiniMax H3 weights are not redistributed.
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
|
||||
CONDITIONING_MODE_T2VA = "t2va"
|
||||
CONDITIONING_MODE_I2VA = "i2va"
|
||||
CONDITIONING_MODE_LAST_ONLY = "last_only"
|
||||
CONDITIONING_MODE_FL2VA = "fl2va"
|
||||
CONDITIONING_MODE_REFERENCE = "reference"
|
||||
|
||||
CONDITIONING_MODES = frozenset(
|
||||
{
|
||||
CONDITIONING_MODE_T2VA,
|
||||
CONDITIONING_MODE_I2VA,
|
||||
CONDITIONING_MODE_LAST_ONLY,
|
||||
CONDITIONING_MODE_FL2VA,
|
||||
CONDITIONING_MODE_REFERENCE,
|
||||
}
|
||||
)
|
||||
|
||||
_MODE_LABELS = {
|
||||
CONDITIONING_MODE_T2VA: "T2VA + Continuation",
|
||||
CONDITIONING_MODE_I2VA: "I2VA + Continuation",
|
||||
CONDITIONING_MODE_LAST_ONLY: "Last Frame + Continuation",
|
||||
CONDITIONING_MODE_FL2VA: "FL2VA + Continuation",
|
||||
CONDITIONING_MODE_REFERENCE: "Reference + Continuation",
|
||||
}
|
||||
|
||||
|
||||
def conditioning_mode_from_presence(
|
||||
*, has_first: bool, has_last: bool, has_reference: bool
|
||||
) -> str:
|
||||
if has_reference and (has_first or has_last):
|
||||
raise ValueError(
|
||||
"Reference Images cannot be combined with First Frame or Last Frame"
|
||||
)
|
||||
if has_reference:
|
||||
return CONDITIONING_MODE_REFERENCE
|
||||
if has_first and has_last:
|
||||
return CONDITIONING_MODE_FL2VA
|
||||
if has_first:
|
||||
return CONDITIONING_MODE_I2VA
|
||||
if has_last:
|
||||
return CONDITIONING_MODE_LAST_ONLY
|
||||
return CONDITIONING_MODE_T2VA
|
||||
|
||||
|
||||
def detect_conditioning_mode(
|
||||
*, first_frame: Any, last_frame: Any, reference_assets: Any
|
||||
) -> str:
|
||||
return conditioning_mode_from_presence(
|
||||
has_first=first_frame is not None,
|
||||
has_last=last_frame is not None,
|
||||
has_reference=reference_assets is not None,
|
||||
)
|
||||
|
||||
|
||||
def conditioning_mode_label(mode: str) -> str:
|
||||
try:
|
||||
return _MODE_LABELS[str(mode)]
|
||||
except KeyError as exc:
|
||||
raise ValueError(f"unknown conditioning mode: {mode!r}") from exc
|
||||
|
||||
|
||||
def conditioning_mode_uses_video_vae(mode: str) -> bool:
|
||||
if mode not in CONDITIONING_MODES:
|
||||
raise ValueError(f"unknown conditioning mode: {mode!r}")
|
||||
return mode != CONDITIONING_MODE_T2VA
|
||||
@@ -0,0 +1,151 @@
|
||||
"""Deterministic, fail-closed fingerprints for ComfyUI upstream loader graphs."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
from typing import Any
|
||||
|
||||
|
||||
GRAPH_CONTRACT_VERSION = 1
|
||||
|
||||
# Keep this deliberately explicit. New loader/patch nodes must be audited before
|
||||
# their saved chunks can be resumed automatically.
|
||||
_KNOWN_MODEL_NODES = {
|
||||
"UNETLoader",
|
||||
"LoraLoader",
|
||||
"LoraLoaderModelOnly",
|
||||
"Power Lora Loader (rgthree)",
|
||||
"PathchSageAttentionKJ",
|
||||
"PatchSageAttentionKJ",
|
||||
"SpectrumApplyMiniMaxH3",
|
||||
"MiniMaxH3MemoryEfficientSageAttention",
|
||||
"MiniMaxH3MemoryEfficientSageAttentionPatch",
|
||||
}
|
||||
_KNOWN_CLIP_NODES = {"CLIPLoader", "DualCLIPLoader", "TripleCLIPLoader"}
|
||||
_KNOWN_VAE_NODES = {"VAELoader"}
|
||||
_KNOWN_SHARED_NODES = {
|
||||
"Reroute",
|
||||
"Any Switch (rgthree)",
|
||||
}
|
||||
|
||||
|
||||
def _canonical(value: Any) -> str:
|
||||
return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
|
||||
|
||||
|
||||
def _sha256(value: Any) -> str:
|
||||
return hashlib.sha256(_canonical(value).encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
def _literal(value: Any) -> tuple[Any, bool]:
|
||||
if value is None or isinstance(value, (bool, int, float, str)):
|
||||
return value, True
|
||||
if isinstance(value, (list, tuple)):
|
||||
result = []
|
||||
safe = True
|
||||
for item in value:
|
||||
rendered, item_safe = _literal(item)
|
||||
result.append(rendered)
|
||||
safe = safe and item_safe
|
||||
return result, safe
|
||||
if isinstance(value, dict):
|
||||
result = {}
|
||||
safe = True
|
||||
for key in sorted(value, key=str):
|
||||
rendered, item_safe = _literal(value[key])
|
||||
result[str(key)] = rendered
|
||||
safe = safe and item_safe
|
||||
return result, safe
|
||||
return {"type": f"{type(value).__module__}.{type(value).__qualname__}"}, False
|
||||
|
||||
|
||||
def _node(prompt: dict[str, Any], node_id: str, *, allowed: set[str], stack: set[str]) -> tuple[dict[str, Any], bool, list[str]]:
|
||||
if node_id in stack:
|
||||
return {"node_id": node_id, "error": "cycle"}, False, [f"upstream graph contains a cycle at node {node_id}"]
|
||||
raw = prompt.get(str(node_id))
|
||||
if not isinstance(raw, dict):
|
||||
return {"node_id": node_id, "error": "missing"}, False, [f"upstream node {node_id} is missing"]
|
||||
class_type = str(raw.get("class_type", ""))
|
||||
safe = class_type in allowed or class_type in _KNOWN_SHARED_NODES
|
||||
reasons = [] if safe else [f"unknown upstream node class: {class_type or '<missing>'}"]
|
||||
inputs = raw.get("inputs") or {}
|
||||
if not isinstance(inputs, dict):
|
||||
return {"node_id": node_id, "class_type": class_type, "error": "invalid inputs"}, False, reasons + [f"upstream node {node_id} inputs are invalid"]
|
||||
rendered_inputs: dict[str, Any] = {}
|
||||
next_stack = set(stack)
|
||||
next_stack.add(node_id)
|
||||
for name in sorted(inputs):
|
||||
value = inputs[name]
|
||||
if (
|
||||
isinstance(value, (list, tuple))
|
||||
and len(value) == 2
|
||||
and isinstance(value[0], (str, int))
|
||||
and isinstance(value[1], int)
|
||||
and str(value[0]) in prompt
|
||||
):
|
||||
child, child_safe, child_reasons = _node(
|
||||
prompt, str(value[0]), allowed=allowed, stack=next_stack
|
||||
)
|
||||
rendered_inputs[str(name)] = {"output": int(value[1]), "node": child}
|
||||
safe = safe and child_safe
|
||||
reasons.extend(child_reasons)
|
||||
else:
|
||||
rendered, literal_safe = _literal(value)
|
||||
rendered_inputs[str(name)] = rendered
|
||||
safe = safe and literal_safe
|
||||
if not literal_safe:
|
||||
reasons.append(f"upstream node {node_id}.{name} is not serializable")
|
||||
return {
|
||||
"node_id": str(node_id),
|
||||
"class_type": class_type,
|
||||
"inputs": rendered_inputs,
|
||||
}, safe, reasons
|
||||
|
||||
|
||||
def build_upstream_graph_contract(
|
||||
prompt: Any, unique_id: Any, *, require_video_vae: bool
|
||||
) -> tuple[dict[str, Any], bool, list[str]]:
|
||||
"""Fingerprint MODEL/CLIP/VAE routes feeding the Continuum sampler."""
|
||||
if not isinstance(prompt, dict):
|
||||
return {"version": GRAPH_CONTRACT_VERSION}, False, ["ComfyUI PROMPT graph is unavailable"]
|
||||
node_id = str(unique_id)
|
||||
sampler_node = prompt.get(node_id)
|
||||
if not isinstance(sampler_node, dict):
|
||||
return {"version": GRAPH_CONTRACT_VERSION}, False, ["Continuum sampler node is absent from PROMPT graph"]
|
||||
inputs = sampler_node.get("inputs") or {}
|
||||
routes: dict[str, Any] = {}
|
||||
safe = True
|
||||
reasons: list[str] = []
|
||||
specs = (
|
||||
("model", _KNOWN_MODEL_NODES, True),
|
||||
("clip", _KNOWN_CLIP_NODES, True),
|
||||
("video_vae", _KNOWN_VAE_NODES, bool(require_video_vae)),
|
||||
)
|
||||
for name, allowed, required in specs:
|
||||
if not required:
|
||||
continue
|
||||
link = inputs.get(name)
|
||||
if not (
|
||||
isinstance(link, (list, tuple))
|
||||
and len(link) == 2
|
||||
and isinstance(link[0], (str, int))
|
||||
and isinstance(link[1], int)
|
||||
):
|
||||
routes[name] = {"error": "input is not connected"}
|
||||
safe = False
|
||||
reasons.append(f"{name} upstream connection is unavailable")
|
||||
continue
|
||||
route, route_safe, route_reasons = _node(
|
||||
prompt, str(link[0]), allowed=allowed, stack={node_id}
|
||||
)
|
||||
routes[name] = {"output": int(link[1]), "node": route}
|
||||
safe = safe and route_safe
|
||||
reasons.extend(route_reasons)
|
||||
descriptor = {
|
||||
"version": GRAPH_CONTRACT_VERSION,
|
||||
"sampler_class_type": str(sampler_node.get("class_type", "")),
|
||||
"routes": routes,
|
||||
}
|
||||
descriptor["sha256"] = _sha256(descriptor)
|
||||
return descriptor, safe, list(dict.fromkeys(reasons))
|
||||
@@ -377,9 +377,8 @@ NODE_DISPLAY_NAME_MAPPINGS.update(V3_NODE_DISPLAY_NAME_MAPPINGS)
|
||||
# every older identifier registered so saved workflows still load, while
|
||||
# ComfyUI's native deprecated-node filter hides legacy building blocks.
|
||||
_primary_node_ids = {
|
||||
"H3ContinuumSamplerV3",
|
||||
"H3ContinuumSamplerProduction",
|
||||
"H3ContinuumAssembleV3",
|
||||
"H3ContinuumAdvancedV3",
|
||||
"H3ContinuumClipOverrides",
|
||||
"H3ContinuumResult",
|
||||
}
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[project]
|
||||
name = "comfyui-h3-continuum"
|
||||
version = "3.0.1"
|
||||
version = "3.2.0"
|
||||
description = "Integrated N-chunk continuation for ComfyUI native MiniMax H3 video and audio"
|
||||
readme = "README.md"
|
||||
requires-python = ">=3.10"
|
||||
|
||||
+225
@@ -0,0 +1,225 @@
|
||||
"""MiniMax H3 image-reference adapter for the V3 production sampler.
|
||||
|
||||
This module only builds the public Core conditioning contract. It does not
|
||||
own model loading, sampling, VAE decoding, or any optimizer implementation.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, replace
|
||||
import hashlib
|
||||
import json
|
||||
import math
|
||||
import re
|
||||
from typing import Any
|
||||
|
||||
import torch
|
||||
|
||||
|
||||
REFERENCE_CONTRACT_VERSION = 1
|
||||
REFERENCE_SIZE_MATCH_OUTPUT = "Match Output"
|
||||
REFERENCE_SIZE_MAX_IDENTITY = "Max Identity"
|
||||
REFERENCE_SIZE_OPTIONS = (
|
||||
REFERENCE_SIZE_MATCH_OUTPUT,
|
||||
REFERENCE_SIZE_MAX_IDENTITY,
|
||||
)
|
||||
_CANVAS_MULTIPLE = 32
|
||||
_MAX_IDENTITY_SHORT_EDGE = 2048
|
||||
_PICTURE_TAG = re.compile(r"<Picture\s+(\d+)>")
|
||||
|
||||
|
||||
class ReferenceConditioningError(ValueError):
|
||||
pass
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ReferenceAssets:
|
||||
images: tuple[torch.Tensor, ...]
|
||||
latents: tuple[torch.Tensor | None, ...]
|
||||
image_hashes: tuple[str, ...]
|
||||
combined_hash: str
|
||||
size_mode: str
|
||||
|
||||
@property
|
||||
def count(self) -> int:
|
||||
return len(self.images)
|
||||
|
||||
@property
|
||||
def contract(self) -> dict[str, Any]:
|
||||
return {
|
||||
"reference_contract_version": REFERENCE_CONTRACT_VERSION,
|
||||
"count": self.count,
|
||||
"size_mode": self.size_mode,
|
||||
"image_hashes": list(self.image_hashes),
|
||||
"combined_hash": self.combined_hash,
|
||||
}
|
||||
|
||||
|
||||
def _canonical_hash(value: Any) -> str:
|
||||
payload = json.dumps(
|
||||
value, sort_keys=True, separators=(",", ":"), ensure_ascii=True
|
||||
).encode("utf-8")
|
||||
return hashlib.sha256(payload).hexdigest()
|
||||
|
||||
|
||||
def _tensor_hash(value: torch.Tensor) -> str:
|
||||
tensor = value.detach().to(device="cpu").contiguous()
|
||||
digest = hashlib.sha256()
|
||||
digest.update(str(tuple(int(v) for v in tensor.shape)).encode("ascii"))
|
||||
digest.update(str(tensor.dtype).encode("ascii"))
|
||||
digest.update(tensor.numpy().tobytes(order="C"))
|
||||
return digest.hexdigest()
|
||||
|
||||
|
||||
def _round_canvas(value: float) -> int:
|
||||
return max(_CANVAS_MULTIPLE, int(round(value / _CANVAS_MULTIPLE)) * _CANVAS_MULTIPLE)
|
||||
|
||||
|
||||
def _validate_image(name: str, image: torch.Tensor) -> torch.Tensor:
|
||||
if not torch.is_tensor(image) or image.ndim != 4:
|
||||
raise ReferenceConditioningError(f"{name} must be a ComfyUI IMAGE tensor")
|
||||
if int(image.shape[0]) < 1 or int(image.shape[1]) < 1 or int(image.shape[2]) < 1:
|
||||
raise ReferenceConditioningError(f"{name} is empty")
|
||||
if int(image.shape[-1]) < 3:
|
||||
raise ReferenceConditioningError(f"{name} must have RGB channels")
|
||||
return image[:1, :, :, :3]
|
||||
|
||||
|
||||
def _resize_reference(
|
||||
image: torch.Tensor,
|
||||
*,
|
||||
output_width: int,
|
||||
output_height: int,
|
||||
size_mode: str,
|
||||
) -> torch.Tensor:
|
||||
if size_mode not in REFERENCE_SIZE_OPTIONS:
|
||||
raise ReferenceConditioningError(f"unknown Reference Size: {size_mode!r}")
|
||||
source_height = int(image.shape[1])
|
||||
source_width = int(image.shape[2])
|
||||
if size_mode == REFERENCE_SIZE_MATCH_OUTPUT:
|
||||
target_area = float(int(output_width) * int(output_height))
|
||||
scale = min(1.0, math.sqrt(target_area / float(source_width * source_height)))
|
||||
else:
|
||||
scale = min(1.0, float(_MAX_IDENTITY_SHORT_EDGE) / min(source_width, source_height))
|
||||
target_width = _round_canvas(source_width * scale)
|
||||
target_height = _round_canvas(source_height * scale)
|
||||
if target_width == source_width and target_height == source_height:
|
||||
return image.contiguous()
|
||||
try:
|
||||
import comfy.utils
|
||||
except Exception as exc:
|
||||
raise ReferenceConditioningError(
|
||||
"ComfyUI Core image resize support is unavailable"
|
||||
) from exc
|
||||
channels_first = image.movedim(-1, 1)
|
||||
resized = comfy.utils.common_upscale(
|
||||
channels_first,
|
||||
target_width,
|
||||
target_height,
|
||||
"lanczos",
|
||||
"disabled",
|
||||
)
|
||||
return resized.movedim(1, -1).contiguous()
|
||||
|
||||
|
||||
def prepare_reference_assets(
|
||||
*,
|
||||
reference_image_1: torch.Tensor | None,
|
||||
reference_image_2: torch.Tensor | None,
|
||||
output_width: int,
|
||||
output_height: int,
|
||||
size_mode: str,
|
||||
) -> ReferenceAssets | None:
|
||||
if reference_image_1 is None:
|
||||
if reference_image_2 is not None:
|
||||
raise ReferenceConditioningError(
|
||||
"Reference Image 2 requires Reference Image 1"
|
||||
)
|
||||
return None
|
||||
inputs = [reference_image_1]
|
||||
if reference_image_2 is not None:
|
||||
inputs.append(reference_image_2)
|
||||
images = tuple(
|
||||
_resize_reference(
|
||||
_validate_image(f"Reference Image {index}", image),
|
||||
output_width=int(output_width),
|
||||
output_height=int(output_height),
|
||||
size_mode=size_mode,
|
||||
)
|
||||
for index, image in enumerate(inputs, start=1)
|
||||
)
|
||||
image_hashes = tuple(_tensor_hash(image) for image in images)
|
||||
combined_hash = _canonical_hash(
|
||||
{
|
||||
"reference_contract_version": REFERENCE_CONTRACT_VERSION,
|
||||
"size_mode": size_mode,
|
||||
"image_hashes": list(image_hashes),
|
||||
}
|
||||
)
|
||||
return ReferenceAssets(
|
||||
images=images,
|
||||
latents=tuple(None for _ in images),
|
||||
image_hashes=image_hashes,
|
||||
combined_hash=combined_hash,
|
||||
size_mode=size_mode,
|
||||
)
|
||||
|
||||
|
||||
def encode_reference_latents(video_vae: Any, assets: ReferenceAssets) -> ReferenceAssets:
|
||||
if all(latent is not None for latent in assets.latents):
|
||||
return assets
|
||||
latents = tuple(video_vae.encode(image) for image in assets.images)
|
||||
return replace(assets, latents=latents)
|
||||
|
||||
|
||||
def validate_reference_prompts(prompts: list[str], reference_count: int) -> str:
|
||||
found: set[int] = set()
|
||||
for prompt in prompts:
|
||||
found.update(int(value) for value in _PICTURE_TAG.findall(str(prompt)))
|
||||
invalid = sorted(value for value in found if value < 1 or value > reference_count)
|
||||
if invalid:
|
||||
raise ReferenceConditioningError(
|
||||
f"Prompt references unavailable <Picture {invalid[0]}>; "
|
||||
f"connected reference count is {reference_count}"
|
||||
)
|
||||
if not found:
|
||||
return (
|
||||
"Reference images are connected but the prompt contains no "
|
||||
"<Picture N> tag; images still condition generation, but explicit "
|
||||
"identity references are recommended."
|
||||
)
|
||||
return ""
|
||||
|
||||
|
||||
def encode_reference_prompt(
|
||||
clip: Any,
|
||||
prompt: str,
|
||||
assets: ReferenceAssets,
|
||||
) -> list[list[Any]]:
|
||||
if any(latent is None for latent in assets.latents):
|
||||
raise ReferenceConditioningError("reference latents were not encoded")
|
||||
reference_items = [
|
||||
{"type": "image", "data": image}
|
||||
for image in assets.images
|
||||
]
|
||||
try:
|
||||
tokens = clip.tokenize(str(prompt), minimax_ref_items=reference_items)
|
||||
except TypeError as exc:
|
||||
raise ReferenceConditioningError(
|
||||
"This ComfyUI Core/CLIP does not support MiniMax H3 image references"
|
||||
) from exc
|
||||
conditioning = clip.encode_from_tokens_scheduled(tokens)
|
||||
refs = []
|
||||
for image, latent in zip(assets.images, assets.latents, strict=True):
|
||||
refs.append(
|
||||
{
|
||||
"kind": "image",
|
||||
"latent_h": int(image.shape[1]) // 16,
|
||||
"latent_w": int(image.shape[2]) // 16,
|
||||
"latent": latent,
|
||||
}
|
||||
)
|
||||
return [
|
||||
[tensor, {**dict(metadata), "minimax_refs": list(refs)}]
|
||||
for tensor, metadata in conditioning
|
||||
]
|
||||
+990
@@ -0,0 +1,990 @@
|
||||
"""Crash-safe V3.1B raw-latent storage and deterministic auto-resume."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import contextvars
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import shutil
|
||||
import socket
|
||||
import uuid
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import torch
|
||||
from safetensors import safe_open
|
||||
from safetensors.torch import save_file
|
||||
|
||||
from .constants import CONTINUUM_ACTUAL_PREFIX_STEPS
|
||||
from .v2.session import make_session, validate_chunk_entry
|
||||
|
||||
|
||||
RUN_STORAGE_SCHEMA_VERSION = 1
|
||||
from .conditioning import (
|
||||
CONDITIONING_MODES,
|
||||
conditioning_mode_from_presence,
|
||||
conditioning_mode_uses_video_vae,
|
||||
)
|
||||
|
||||
|
||||
SAMPLING_CONTRACT_VERSION = 4
|
||||
RUN_STORAGE_OFF = "Off"
|
||||
RUN_STORAGE_AUTO = "Save + Auto Resume"
|
||||
RUN_STORAGE_OPTIONS = (RUN_STORAGE_OFF, RUN_STORAGE_AUTO)
|
||||
|
||||
_ACTIVE: contextvars.ContextVar["RunStorageController | None"] = contextvars.ContextVar(
|
||||
"h3_continuum_run_storage", default=None
|
||||
)
|
||||
_RESERVED = {
|
||||
"CON", "PRN", "AUX", "NUL",
|
||||
*(f"COM{i}" for i in range(1, 10)),
|
||||
*(f"LPT{i}" for i in range(1, 10)),
|
||||
}
|
||||
_ADDRESS = re.compile(r"0x[0-9a-fA-F]+")
|
||||
|
||||
|
||||
class RunStorageError(RuntimeError):
|
||||
pass
|
||||
|
||||
|
||||
def _now() -> str:
|
||||
return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
|
||||
|
||||
|
||||
def _canonical(value: Any) -> str:
|
||||
return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
|
||||
|
||||
|
||||
def _hash(value: Any) -> str:
|
||||
return hashlib.sha256(_canonical(value).encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
def sanitize_run_name(value: str) -> str:
|
||||
name = str(value)
|
||||
if not name or name != name.strip() or len(name) > 96:
|
||||
raise RunStorageError("Run Name must be 1-96 characters without surrounding spaces")
|
||||
if any(ord(char) < 32 or char in '<>:"/\\|?*' for char in name):
|
||||
raise RunStorageError("Run Name contains a reserved path character")
|
||||
if name.endswith((".", " ")) or name in {".", ".."}:
|
||||
raise RunStorageError("Run Name must not be a relative path or end with dot/space")
|
||||
if name.split(".", 1)[0].upper() in _RESERVED:
|
||||
raise RunStorageError(f"Run Name {name!r} is reserved by Windows")
|
||||
return name
|
||||
|
||||
|
||||
def resolve_run_storage_name(*, project_id: str, legacy_run_name: str = "") -> str:
|
||||
"""Resolve a stable storage folder while preserving old Run Name workflows."""
|
||||
legacy = str(legacy_run_name)
|
||||
if legacy:
|
||||
return sanitize_run_name(legacy)
|
||||
raw_project_id = str(project_id).strip()
|
||||
try:
|
||||
parsed = uuid.UUID(raw_project_id)
|
||||
except (ValueError, AttributeError, TypeError) as exc:
|
||||
raise RunStorageError(
|
||||
"Automatic Project ID is missing or invalid; reload ComfyUI and the workflow"
|
||||
) from exc
|
||||
if parsed.int == 0:
|
||||
raise RunStorageError("Automatic Project ID must not be the nil UUID")
|
||||
return f"run_{parsed.hex}"
|
||||
|
||||
|
||||
def _output_root() -> Path:
|
||||
try:
|
||||
import folder_paths
|
||||
|
||||
return Path(folder_paths.get_output_directory())
|
||||
except Exception:
|
||||
return Path.cwd() / "output"
|
||||
|
||||
|
||||
def _fsync_file(path: Path) -> None:
|
||||
# Windows requires a writable descriptor for fsync(). The file contents
|
||||
# are already complete at this point; opening r+b does not modify them.
|
||||
with path.open("r+b") as handle:
|
||||
os.fsync(handle.fileno())
|
||||
|
||||
|
||||
def _fsync_dir(path: Path) -> None:
|
||||
if os.name == "nt":
|
||||
return
|
||||
descriptor = os.open(str(path), os.O_RDONLY)
|
||||
try:
|
||||
os.fsync(descriptor)
|
||||
finally:
|
||||
os.close(descriptor)
|
||||
|
||||
|
||||
def _write_json(path: Path, payload: dict[str, Any]) -> None:
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
temporary = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
|
||||
try:
|
||||
with temporary.open("w", encoding="utf-8", newline="\n") as handle:
|
||||
json.dump(payload, handle, ensure_ascii=False, sort_keys=True, indent=2)
|
||||
handle.write("\n")
|
||||
handle.flush()
|
||||
os.fsync(handle.fileno())
|
||||
os.replace(temporary, path)
|
||||
_fsync_dir(path.parent)
|
||||
finally:
|
||||
if temporary.exists():
|
||||
temporary.unlink()
|
||||
|
||||
|
||||
def _read_json(path: Path) -> dict[str, Any]:
|
||||
value = json.loads(path.read_text(encoding="utf-8"))
|
||||
if not isinstance(value, dict):
|
||||
raise RunStorageError(f"{path.name} must contain a JSON object")
|
||||
return value
|
||||
|
||||
|
||||
def _qualified(value: Any) -> str:
|
||||
if value is None:
|
||||
return "none"
|
||||
target = value if isinstance(value, type) or callable(value) else type(value)
|
||||
module = getattr(target, "__module__", "")
|
||||
name = getattr(target, "__qualname__", getattr(target, "__name__", type(target).__name__))
|
||||
return f"{module}.{name}"
|
||||
|
||||
|
||||
def _tensor_probe(tensor: torch.Tensor) -> dict[str, Any]:
|
||||
flat = tensor.detach().reshape(-1)
|
||||
count = int(flat.numel())
|
||||
positions = sorted({0, count // 4, count // 2, 3 * count // 4, count - 1}) if count else []
|
||||
if positions:
|
||||
index = torch.tensor(positions, device=flat.device)
|
||||
sample = flat[index].contiguous().cpu().view(torch.uint8).numpy().tobytes()
|
||||
else:
|
||||
sample = b""
|
||||
return {
|
||||
"shape": list(tensor.shape),
|
||||
"dtype": str(tensor.dtype),
|
||||
"sample_sha256": hashlib.sha256(sample).hexdigest(),
|
||||
}
|
||||
|
||||
|
||||
def _tensor_exact(tensor: torch.Tensor) -> dict[str, Any]:
|
||||
value = tensor.detach().contiguous().cpu()
|
||||
raw = value.view(torch.uint8).numpy().tobytes()
|
||||
return {
|
||||
"shape": list(value.shape),
|
||||
"dtype": str(value.dtype),
|
||||
"exact_sha256": hashlib.sha256(raw).hexdigest(),
|
||||
}
|
||||
|
||||
|
||||
def _observe(value: Any, *, depth: int = 0) -> tuple[Any, bool]:
|
||||
if depth > 10:
|
||||
return {"type": _qualified(value), "truncated": True}, False
|
||||
if value is None or isinstance(value, (bool, int, float, str)):
|
||||
return value, True
|
||||
if isinstance(value, Path):
|
||||
return str(value), True
|
||||
if torch.is_tensor(value):
|
||||
try:
|
||||
return {"tensor": _tensor_probe(value)}, True
|
||||
except Exception:
|
||||
return {"tensor_type": _qualified(value)}, False
|
||||
if isinstance(value, dict):
|
||||
result: dict[str, Any] = {}
|
||||
safe = True
|
||||
for key in sorted(value, key=lambda item: str(item)):
|
||||
observed, item_safe = _observe(value[key], depth=depth + 1)
|
||||
result[str(key)] = observed
|
||||
safe = safe and item_safe
|
||||
return result, safe
|
||||
if isinstance(value, (list, tuple)):
|
||||
result = []
|
||||
safe = True
|
||||
for item in value:
|
||||
observed, item_safe = _observe(item, depth=depth + 1)
|
||||
result.append(observed)
|
||||
safe = safe and item_safe
|
||||
return result, safe
|
||||
if callable(value):
|
||||
code = getattr(value, "__code__", None)
|
||||
descriptor: dict[str, Any] = {"callable": _qualified(value)}
|
||||
safe = True
|
||||
if code is not None:
|
||||
descriptor["code_sha256"] = hashlib.sha256(code.co_code).hexdigest()
|
||||
defaults, defaults_safe = _observe(getattr(value, "__defaults__", None), depth=depth + 1)
|
||||
kwdefaults, kw_safe = _observe(getattr(value, "__kwdefaults__", None), depth=depth + 1)
|
||||
closure_values = tuple(cell.cell_contents for cell in (getattr(value, "__closure__", None) or ()))
|
||||
closure, closure_safe = _observe(closure_values, depth=depth + 1)
|
||||
descriptor.update(defaults=defaults, kwdefaults=kwdefaults, closure=closure)
|
||||
safe = defaults_safe and kw_safe and closure_safe
|
||||
elif hasattr(value, "__dict__"):
|
||||
attributes, safe = _observe(vars(value), depth=depth + 1)
|
||||
descriptor["attributes"] = attributes
|
||||
else:
|
||||
safe = False
|
||||
return descriptor, safe
|
||||
if hasattr(value, "__dict__"):
|
||||
attributes, safe = _observe(vars(value), depth=depth + 1)
|
||||
return {"type": _qualified(value), "attributes": attributes}, safe
|
||||
rendered = _ADDRESS.sub("0x...", repr(value))
|
||||
return {"type": _qualified(value), "repr": rendered[:256]}, False
|
||||
|
||||
|
||||
def _model_signature(model: Any, legacy_fingerprint: str) -> tuple[dict[str, Any], bool]:
|
||||
base = getattr(model, "model", None)
|
||||
inner = getattr(base, "diffusion_model", None)
|
||||
wrappers, wrappers_safe = _observe(getattr(model, "wrappers", {}) or {})
|
||||
patches, patches_safe = _observe(getattr(model, "patches", {}) or {})
|
||||
options = getattr(model, "model_options", {}) or {}
|
||||
transformer = options.get("transformer_options", {}) or {}
|
||||
transformer_values = {
|
||||
str(key): transformer[key]
|
||||
for key in transformer
|
||||
if key not in {"h3_continuum_join_context"}
|
||||
}
|
||||
observed_transformer, transformer_safe = _observe(transformer_values)
|
||||
weights: list[dict[str, Any]] = []
|
||||
weights_safe = True
|
||||
try:
|
||||
parameters = list(inner.named_parameters()) if inner is not None else []
|
||||
for position in sorted({0, len(parameters) // 2, len(parameters) - 1}) if parameters else []:
|
||||
name, parameter = parameters[position]
|
||||
weights.append({"name": str(name), **_tensor_probe(parameter)})
|
||||
except Exception:
|
||||
weights_safe = False
|
||||
descriptor = {
|
||||
"legacy_fingerprint": str(legacy_fingerprint),
|
||||
"model_patcher": _qualified(model),
|
||||
"base": _qualified(base),
|
||||
"inner": _qualified(inner),
|
||||
"dtype": str(getattr(model, "model_dtype", lambda: "unknown")()),
|
||||
"model_size": int(getattr(model, "model_size", lambda: 0)() or 0),
|
||||
"wrappers": wrappers,
|
||||
"transformer_options": observed_transformer,
|
||||
"patches": patches,
|
||||
"weight_probe": weights,
|
||||
}
|
||||
return descriptor, wrappers_safe and patches_safe and transformer_safe and weights_safe
|
||||
|
||||
|
||||
def _sampler_signature(sampler: Any) -> tuple[dict[str, Any], bool]:
|
||||
function = getattr(sampler, "sampler_function", None)
|
||||
observed, safe = _observe({
|
||||
"extra_options": getattr(sampler, "extra_options", {}) or {},
|
||||
"inpaint_options": getattr(sampler, "inpaint_options", {}) or {},
|
||||
})
|
||||
return {
|
||||
"type": _qualified(sampler),
|
||||
"function": _qualified(function) if function is not None else "unknown",
|
||||
"options": observed,
|
||||
}, function is not None and safe
|
||||
|
||||
|
||||
def _module_signature(module: Any) -> tuple[dict[str, Any], bool]:
|
||||
descriptor: dict[str, Any] = {"type": _qualified(module)}
|
||||
if module is None or not hasattr(module, "named_parameters"):
|
||||
descriptor["error"] = "named_parameters unavailable"
|
||||
return descriptor, False
|
||||
try:
|
||||
parameters = list(module.named_parameters())
|
||||
except Exception as exc:
|
||||
descriptor["error"] = f"named_parameters failed: {type(exc).__name__}"
|
||||
return descriptor, False
|
||||
layout = [
|
||||
{
|
||||
"name": str(name),
|
||||
"shape": list(parameter.shape),
|
||||
"dtype": str(parameter.dtype),
|
||||
}
|
||||
for name, parameter in parameters
|
||||
]
|
||||
descriptor.update(
|
||||
tensor_count=len(parameters),
|
||||
parameter_count=sum(int(parameter.numel()) for _, parameter in parameters),
|
||||
parameter_layout_sha256=_hash(layout),
|
||||
)
|
||||
probes = []
|
||||
probes_safe = bool(parameters)
|
||||
for position in sorted({0, len(parameters) // 2, len(parameters) - 1}) if parameters else []:
|
||||
name, parameter = parameters[position]
|
||||
try:
|
||||
probes.append({"name": str(name), **_tensor_probe(parameter)})
|
||||
except Exception as exc:
|
||||
probes.append({"name": str(name), "error": type(exc).__name__})
|
||||
probes_safe = False
|
||||
descriptor["weight_probe"] = probes
|
||||
return descriptor, probes_safe
|
||||
|
||||
|
||||
def _patcher_signature(patcher: Any) -> tuple[dict[str, Any], bool]:
|
||||
if patcher is None:
|
||||
return {"type": "missing"}, False
|
||||
state, safe = _observe({
|
||||
"wrappers": getattr(patcher, "wrappers", {}) or {},
|
||||
"patches": getattr(patcher, "patches", {}) or {},
|
||||
"object_patches": getattr(patcher, "object_patches", {}) or {},
|
||||
"model_options": getattr(patcher, "model_options", {}) or {},
|
||||
})
|
||||
return {
|
||||
"type": _qualified(patcher),
|
||||
"model_type": _qualified(getattr(patcher, "model", None)),
|
||||
"state": state,
|
||||
}, safe
|
||||
|
||||
|
||||
def _clip_signature(clip: Any) -> tuple[dict[str, Any], bool]:
|
||||
cond_stage = getattr(clip, "cond_stage_model", None)
|
||||
tokenizer = getattr(clip, "tokenizer", None)
|
||||
tokenizer_wrapper = getattr(tokenizer, "qwen3vl_32b", None)
|
||||
tokenizer_core = getattr(tokenizer_wrapper, "tokenizer", None)
|
||||
module_value, module_safe = _module_signature(cond_stage)
|
||||
patcher_value, patcher_safe = _patcher_signature(getattr(clip, "patcher", None))
|
||||
options, options_safe = _observe({
|
||||
"tokenizer_options": getattr(clip, "tokenizer_options", {}) or {},
|
||||
"layer_idx": getattr(clip, "layer_idx", None),
|
||||
"use_clip_schedule": bool(getattr(clip, "use_clip_schedule", False)),
|
||||
})
|
||||
tokenizer_config = {
|
||||
"wrapper_type": _qualified(tokenizer),
|
||||
"model_wrapper_type": _qualified(tokenizer_wrapper),
|
||||
"core_type": _qualified(tokenizer_core),
|
||||
}
|
||||
for name in (
|
||||
"name_or_path", "vocab_size", "model_max_length", "padding_side",
|
||||
"truncation_side", "bos_token_id", "eos_token_id", "pad_token_id",
|
||||
):
|
||||
value = getattr(tokenizer_core, name, None)
|
||||
if value is None or isinstance(value, (bool, int, float, str)):
|
||||
tokenizer_config[name] = value
|
||||
tokenizer_safe = tokenizer is not None and tokenizer_wrapper is not None and tokenizer_core is not None
|
||||
return {
|
||||
"wrapper_type": _qualified(clip),
|
||||
"conditioner": module_value,
|
||||
"patcher": patcher_value,
|
||||
"tokenizer": tokenizer_config,
|
||||
"options": options,
|
||||
}, module_safe and patcher_safe and options_safe and tokenizer_safe
|
||||
|
||||
|
||||
def _video_vae_signature(video_vae: Any, *, required: bool) -> tuple[dict[str, Any], bool]:
|
||||
if not required:
|
||||
return {"required": False}, True
|
||||
first_stage = getattr(video_vae, "first_stage_model", None)
|
||||
module_value, module_safe = _module_signature(first_stage)
|
||||
patcher_value, patcher_safe = _patcher_signature(getattr(video_vae, "patcher", None))
|
||||
config = {
|
||||
"required": True,
|
||||
"wrapper_type": _qualified(video_vae),
|
||||
"first_stage": module_value,
|
||||
"patcher": patcher_value,
|
||||
"vae_dtype": str(getattr(video_vae, "vae_dtype", "unknown")),
|
||||
"latent_channels": getattr(video_vae, "latent_channels", None),
|
||||
"downscale_ratio": getattr(video_vae, "downscale_ratio", None),
|
||||
"upscale_ratio": getattr(video_vae, "upscale_ratio", None),
|
||||
"chunked_io": bool(getattr(first_stage, "comfy_has_chunked_io", False)),
|
||||
}
|
||||
observed, config_safe = _observe(config)
|
||||
return observed, module_safe and patcher_safe and config_safe
|
||||
|
||||
|
||||
def _apply_nonce_contract(
|
||||
contract: dict[str, Any], *, requested_nonce: int, effective_nonce: int,
|
||||
) -> dict[str, Any]:
|
||||
result = dict(contract)
|
||||
boundary = int(result["reroll_from_chunk"])
|
||||
if boundary <= 0:
|
||||
mode = "inactive"
|
||||
requested_nonce = 0
|
||||
effective_nonce = 0
|
||||
else:
|
||||
mode = "explicit" if int(requested_nonce) >= 1 else "auto"
|
||||
global_hash = _hash(result["global"])
|
||||
chunk_contracts = []
|
||||
chunk_hashes = []
|
||||
for position, prompt_hash in enumerate(result["prompt_hashes"]):
|
||||
number = position + 1
|
||||
affected = boundary > 0 and number >= boundary
|
||||
chunk_contract = {
|
||||
"global_hash": global_hash,
|
||||
"chunk_number": number,
|
||||
"prompt_hash": str(prompt_hash),
|
||||
"reroll_boundary": boundary if affected else 0,
|
||||
"effective_reroll_nonce": int(effective_nonce) if affected else 0,
|
||||
"last_frame_hash": str(result["last_frame_hash"]) if number == int(result["chunk_count"]) else "",
|
||||
}
|
||||
chunk_contracts.append(chunk_contract)
|
||||
chunk_hashes.append(_hash(chunk_contract))
|
||||
result.update(
|
||||
effective_reroll_nonce=int(effective_nonce),
|
||||
chunk_contracts=chunk_contracts,
|
||||
chunk_contract_hashes=chunk_hashes,
|
||||
nonce_lifecycle={
|
||||
"mode": mode,
|
||||
"requested_nonce": int(requested_nonce),
|
||||
"effective_nonce": int(effective_nonce),
|
||||
"lineage_sha256": str(result["nonce_lineage_sha256"]),
|
||||
"request_sha256": str(result["nonce_request_sha256"]),
|
||||
},
|
||||
)
|
||||
return result
|
||||
|
||||
|
||||
def build_sampling_contract(
|
||||
*, model: Any, model_fingerprint_value: str, clip: Any, video_vae: Any,
|
||||
sampler: Any,
|
||||
sigmas: torch.Tensor, prompt_plan: dict[str, Any], width: int,
|
||||
height: int, chunk_seconds: float, continuity: str,
|
||||
audio_continuity: bool, base_seed: int, reroll_from_chunk: int,
|
||||
reroll_nonce: int, first_frame_hash: str, last_frame_hash: str,
|
||||
strict_compatibility: bool, reference_contract: dict[str, Any] | None = None,
|
||||
conditioning_mode: str | None = None,
|
||||
upstream_graph_contract: dict[str, Any] | None = None,
|
||||
upstream_graph_safe: bool | None = None,
|
||||
upstream_graph_reasons: list[str] | None = None,
|
||||
) -> tuple[dict[str, Any], bool, list[str]]:
|
||||
model_value, model_safe = _model_signature(model, model_fingerprint_value)
|
||||
clip_value, clip_safe = _clip_signature(clip)
|
||||
inferred_mode = conditioning_mode_from_presence(
|
||||
has_first=str(first_frame_hash).lower() not in {"", "none", "null"},
|
||||
has_last=str(last_frame_hash).lower() not in {"", "none", "null"},
|
||||
has_reference=reference_contract is not None,
|
||||
)
|
||||
conditioning_mode = inferred_mode if conditioning_mode is None else str(conditioning_mode)
|
||||
if conditioning_mode not in CONDITIONING_MODES:
|
||||
raise RunStorageError(f"unknown conditioning mode: {conditioning_mode!r}")
|
||||
if conditioning_mode != inferred_mode:
|
||||
raise RunStorageError(
|
||||
"conditioning mode does not match the connected image inputs: "
|
||||
f"declared={conditioning_mode}, inferred={inferred_mode}"
|
||||
)
|
||||
uses_video_vae = conditioning_mode_uses_video_vae(conditioning_mode)
|
||||
if uses_video_vae:
|
||||
video_vae_value, video_vae_safe = _video_vae_signature(
|
||||
video_vae, required=True
|
||||
)
|
||||
else:
|
||||
video_vae_value, video_vae_safe = None, True
|
||||
sampler_value, sampler_safe = _sampler_signature(sampler)
|
||||
if not torch.is_tensor(sigmas) or sigmas.ndim != 1:
|
||||
raise RunStorageError("Run Storage requires a one-dimensional SIGMAS tensor")
|
||||
chunks = int(prompt_plan["chunks"])
|
||||
prompt_hashes = [str(value) for value in prompt_plan["hashes"]]
|
||||
boundary = int(reroll_from_chunk)
|
||||
graph_authoritative = upstream_graph_contract is not None
|
||||
if graph_authoritative:
|
||||
model_value = {"source": "comfy_prompt_graph", "route": upstream_graph_contract.get("routes", {}).get("model")}
|
||||
clip_value = {"source": "comfy_prompt_graph", "route": upstream_graph_contract.get("routes", {}).get("clip")}
|
||||
if uses_video_vae:
|
||||
video_vae_value = {"source": "comfy_prompt_graph", "route": upstream_graph_contract.get("routes", {}).get("video_vae")}
|
||||
model_safe = clip_safe = video_vae_safe = bool(upstream_graph_safe)
|
||||
global_contract = {
|
||||
"sampling_contract_version": SAMPLING_CONTRACT_VERSION,
|
||||
"conditioning_mode": conditioning_mode,
|
||||
"model": model_value,
|
||||
"clip": clip_value,
|
||||
"sampler": sampler_value,
|
||||
"sigmas": _tensor_exact(sigmas),
|
||||
"width": int(width), "height": int(height),
|
||||
"chunk_seconds": float(chunk_seconds),
|
||||
"continuity": str(continuity),
|
||||
"audio_continuity": bool(audio_continuity),
|
||||
"base_seed": int(base_seed),
|
||||
"strict_compatibility": bool(strict_compatibility),
|
||||
"continuum_interop_api": 1,
|
||||
"actual_prefix_steps": CONTINUUM_ACTUAL_PREFIX_STEPS,
|
||||
}
|
||||
if graph_authoritative:
|
||||
global_contract["upstream_graph"] = dict(upstream_graph_contract)
|
||||
if uses_video_vae:
|
||||
global_contract["video_vae"] = video_vae_value
|
||||
if conditioning_mode in {"i2va", "fl2va"}:
|
||||
global_contract["first_frame_hash"] = str(first_frame_hash)
|
||||
if reference_contract is not None:
|
||||
global_contract["reference"] = dict(reference_contract)
|
||||
lineage_sha256 = _hash({
|
||||
"global_hash": _hash(global_contract),
|
||||
"chunk_count": chunks,
|
||||
"prompt_mode": str(prompt_plan["mode"]),
|
||||
"prompt_hashes": prompt_hashes,
|
||||
"last_frame_hash": str(last_frame_hash),
|
||||
})
|
||||
contract = {
|
||||
"global": global_contract,
|
||||
"chunk_count": chunks,
|
||||
"prompt_mode": str(prompt_plan["mode"]),
|
||||
"prompt_hashes": prompt_hashes,
|
||||
"reroll_from_chunk": boundary,
|
||||
"last_frame_hash": str(last_frame_hash),
|
||||
"nonce_lineage_sha256": lineage_sha256,
|
||||
"nonce_request_sha256": _hash({
|
||||
"lineage_sha256": lineage_sha256,
|
||||
"reroll_from_chunk": boundary,
|
||||
}),
|
||||
}
|
||||
contract = _apply_nonce_contract(
|
||||
contract,
|
||||
requested_nonce=int(reroll_nonce),
|
||||
effective_nonce=int(reroll_nonce) if boundary > 0 else 0,
|
||||
)
|
||||
reasons = list(upstream_graph_reasons or []) if graph_authoritative else []
|
||||
if not graph_authoritative and not model_safe:
|
||||
reasons.append("MODEL wrapper/patch contract is not completely observable")
|
||||
if not sampler_safe:
|
||||
reasons.append("SAMPLER function/options are not completely observable")
|
||||
if not graph_authoritative and not clip_safe:
|
||||
reasons.append("CLIP/Qwen encoder contract is not completely observable")
|
||||
if not graph_authoritative and not video_vae_safe:
|
||||
reasons.append("Video VAE contract is not completely observable")
|
||||
graph_safe = bool(upstream_graph_safe) if graph_authoritative else True
|
||||
return contract, model_safe and clip_safe and video_vae_safe and sampler_safe and graph_safe, reasons
|
||||
|
||||
|
||||
def revision_identity(contract: dict[str, Any]) -> tuple[str, str]:
|
||||
full = _hash(contract)
|
||||
return full[:16], full
|
||||
|
||||
|
||||
def _pid_exists(pid: int) -> bool:
|
||||
if pid <= 0:
|
||||
return False
|
||||
if pid == os.getpid():
|
||||
return True
|
||||
try:
|
||||
os.kill(pid, 0)
|
||||
except ProcessLookupError:
|
||||
return False
|
||||
except PermissionError:
|
||||
return True
|
||||
except OSError:
|
||||
return False
|
||||
return True
|
||||
|
||||
|
||||
class _RunLock:
|
||||
def __init__(self, path: Path):
|
||||
self.path = path
|
||||
self.token = uuid.uuid4().hex
|
||||
self.acquired = False
|
||||
|
||||
def acquire(self) -> None:
|
||||
self.path.parent.mkdir(parents=True, exist_ok=True)
|
||||
payload = {
|
||||
"pid": os.getpid(), "hostname": socket.gethostname(),
|
||||
"started_utc": _now(), "token": self.token,
|
||||
}
|
||||
encoded = (_canonical(payload) + "\n").encode("utf-8")
|
||||
for _ in range(2):
|
||||
try:
|
||||
descriptor = os.open(self.path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
|
||||
except FileExistsError:
|
||||
try:
|
||||
existing = _read_json(self.path)
|
||||
except Exception as exc:
|
||||
raise RunStorageError(f"Run Storage lock exists and is unreadable: {self.path}") from exc
|
||||
if str(existing.get("hostname", "")) == socket.gethostname() and not _pid_exists(int(existing.get("pid", -1))):
|
||||
self.path.unlink()
|
||||
continue
|
||||
raise RunStorageError(
|
||||
f"Run Name is locked by pid={existing.get('pid')} host={existing.get('hostname')}"
|
||||
)
|
||||
else:
|
||||
try:
|
||||
os.write(descriptor, encoded)
|
||||
os.fsync(descriptor)
|
||||
finally:
|
||||
os.close(descriptor)
|
||||
self.acquired = True
|
||||
return
|
||||
raise RunStorageError("failed to recover stale Run Storage lock")
|
||||
|
||||
def release(self) -> None:
|
||||
if not self.acquired:
|
||||
return
|
||||
try:
|
||||
existing = _read_json(self.path)
|
||||
if existing.get("token") == self.token:
|
||||
self.path.unlink()
|
||||
finally:
|
||||
self.acquired = False
|
||||
|
||||
|
||||
def _entry_metadata(entry: dict[str, Any]) -> dict[str, Any]:
|
||||
return {
|
||||
"sequence_index": int(entry["sequence_index"]),
|
||||
"clip_index": int(entry["clip_index"]),
|
||||
"prompt_hash": str(entry["prompt_hash"]),
|
||||
"seed": int(entry["seed"]),
|
||||
"context_frames": int(entry["context_frames"]),
|
||||
"motion_score": float(entry["motion_score"]),
|
||||
"plan": dict(entry["plan"]),
|
||||
}
|
||||
|
||||
|
||||
class RunStorageController:
|
||||
def __init__(self, run_name: str):
|
||||
self.run_name = sanitize_run_name(run_name)
|
||||
self.run_root = _output_root() / "h3_continuum" / "runs" / self.run_name
|
||||
self.revisions_root = self.run_root / "revisions"
|
||||
self.lock = _RunLock(self.run_root / ".lock")
|
||||
self.context_token = None
|
||||
self.contract: dict[str, Any] | None = None
|
||||
self.contract_sha256 = ""
|
||||
self.revision_id = ""
|
||||
self.revision_root: Path | None = None
|
||||
self.manifest: dict[str, Any] | None = None
|
||||
self.prompts: list[str] = []
|
||||
self.reused_count = 0
|
||||
self.generated_count = 0
|
||||
self.disabled_reasons: list[str] = []
|
||||
self.notes: list[str] = []
|
||||
self.resume_safe = False
|
||||
self.effective_reroll_nonce = 0
|
||||
self.nonce_decision = "inactive"
|
||||
self.prompt_graph: dict[str, Any] | None = None
|
||||
self.sampler_node_id: str | None = None
|
||||
|
||||
def set_prompt_graph(self, prompt: Any, unique_id: Any) -> None:
|
||||
self.prompt_graph = prompt if isinstance(prompt, dict) else None
|
||||
self.sampler_node_id = None if unique_id is None else str(unique_id)
|
||||
|
||||
def __enter__(self) -> "RunStorageController":
|
||||
self.lock.acquire()
|
||||
self.context_token = _ACTIVE.set(self)
|
||||
return self
|
||||
|
||||
def __exit__(self, exc_type, exc, traceback) -> None:
|
||||
try:
|
||||
if exc is not None and self.manifest is not None:
|
||||
self.manifest.update(status="interrupted", updated_utc=_now(), last_error=f"{type(exc).__name__}: {exc}"[:2048])
|
||||
self._write_manifest()
|
||||
finally:
|
||||
if self.context_token is not None:
|
||||
_ACTIVE.reset(self.context_token)
|
||||
self.context_token = None
|
||||
self.lock.release()
|
||||
|
||||
def _manifest_path(self) -> Path:
|
||||
if self.revision_root is None:
|
||||
raise RunStorageError("Run Storage revision is not prepared")
|
||||
return self.revision_root / "manifest.json"
|
||||
|
||||
def _write_manifest(self) -> None:
|
||||
if self.manifest is not None:
|
||||
_write_json(self._manifest_path(), self.manifest)
|
||||
|
||||
def _write_project(self) -> None:
|
||||
revisions = []
|
||||
if self.revisions_root.exists():
|
||||
for path in sorted(self.revisions_root.glob("*/manifest.json")):
|
||||
try:
|
||||
value = _read_json(path)
|
||||
lifecycle = value.get("nonce_lifecycle") or {}
|
||||
revision = {key: value.get(key) for key in ("revision_id", "contract_sha256", "status", "updated_utc", "resume_safe")}
|
||||
revision.update(
|
||||
nonce_mode=lifecycle.get("mode"),
|
||||
effective_reroll_nonce=lifecycle.get("effective_nonce"),
|
||||
reroll_from_chunk=(value.get("contract") or {}).get("reroll_from_chunk"),
|
||||
)
|
||||
revisions.append(revision)
|
||||
except Exception:
|
||||
continue
|
||||
_write_json(self.run_root / "project.json", {
|
||||
"run_storage_schema_version": RUN_STORAGE_SCHEMA_VERSION,
|
||||
"run_name": self.run_name, "updated_utc": _now(), "revisions": revisions,
|
||||
})
|
||||
|
||||
def _load_entry(self, record: dict[str, Any], prompt: str) -> dict[str, Any]:
|
||||
source = str(record["storage_revision_id"])
|
||||
filename = str(record["filename"])
|
||||
if Path(filename).name != filename:
|
||||
raise RunStorageError("stored chunk filename is invalid")
|
||||
path = self.revisions_root / source / "chunks" / filename
|
||||
if path.stat().st_size != int(record["file_size"]):
|
||||
raise RunStorageError(f"stored chunk size mismatch: {filename}")
|
||||
with safe_open(str(path), framework="pt", device="cpu") as handle:
|
||||
if set(handle.keys()) != {"audio", "video"}:
|
||||
raise RunStorageError(f"stored chunk tensors are invalid: {filename}")
|
||||
video, audio = handle.get_tensor("video"), handle.get_tensor("audio")
|
||||
entry = dict(record["entry"])
|
||||
entry.update(prompt=str(prompt), video=video, audio=audio, reused=False)
|
||||
return validate_chunk_entry(entry)
|
||||
|
||||
def _valid_prefix(self, manifest: dict[str, Any], hashes: list[str]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
|
||||
stored = list((manifest.get("contract") or {}).get("chunk_contract_hashes") or [])
|
||||
records = list(manifest.get("chunks") or [])
|
||||
entries, accepted = [], []
|
||||
for position, current in enumerate(hashes):
|
||||
if position >= len(stored) or stored[position] != current:
|
||||
break
|
||||
if position >= len(records) or int(records[position].get("sequence_index", -1)) != position:
|
||||
break
|
||||
try:
|
||||
entry = self._load_entry(records[position], self.prompts[position])
|
||||
except Exception as exc:
|
||||
self.notes.append(f"stored chunk {position + 1} rejected: {exc}")
|
||||
break
|
||||
entries.append(entry)
|
||||
accepted.append(records[position])
|
||||
return entries, accepted
|
||||
|
||||
def _resolve_effective_nonce(
|
||||
self, contract: dict[str, Any], *, requested_nonce: int, resume_safe: bool,
|
||||
) -> tuple[int, str]:
|
||||
boundary = int(contract["reroll_from_chunk"])
|
||||
requested = int(requested_nonce)
|
||||
if boundary <= 0:
|
||||
return 0, "inactive"
|
||||
if requested >= 1:
|
||||
return requested, "explicit"
|
||||
lineage = str(contract["nonce_lineage_sha256"])
|
||||
request = str(contract["nonce_request_sha256"])
|
||||
highest = 0
|
||||
matching: dict[int, dict[str, Any]] = {}
|
||||
if self.revisions_root.exists():
|
||||
for path in self.revisions_root.glob("*/manifest.json"):
|
||||
try:
|
||||
manifest = _read_json(path)
|
||||
lifecycle = manifest.get("nonce_lifecycle") or (manifest.get("contract") or {}).get("nonce_lifecycle") or {}
|
||||
if str(lifecycle.get("lineage_sha256", "")) != lineage:
|
||||
continue
|
||||
nonce = int(lifecycle.get("effective_nonce", 0))
|
||||
highest = max(highest, nonce)
|
||||
if str(lifecycle.get("request_sha256", "")) == request:
|
||||
current = matching.get(nonce)
|
||||
if current is None or str(manifest.get("updated_utc", "")) >= str(current.get("updated_utc", "")):
|
||||
matching[nonce] = manifest
|
||||
except Exception:
|
||||
continue
|
||||
if resume_safe and matching:
|
||||
latest_nonce = max(matching)
|
||||
latest = matching[latest_nonce]
|
||||
if latest_nonce == highest and str(latest.get("status", "")) != "complete":
|
||||
return latest_nonce, "resume_interrupted"
|
||||
return highest + 1, "new_revision"
|
||||
|
||||
def prepare(
|
||||
self, *, model: Any, model_fingerprint_value: str, clip: Any,
|
||||
video_vae: Any, sampler: Any,
|
||||
sigmas: torch.Tensor, prompt_plan: dict[str, Any], width: int,
|
||||
height: int, chunk_seconds: float, continuity: str,
|
||||
audio_continuity: bool, base_seed: int, reroll_from_chunk: int,
|
||||
reroll_nonce: int, first_frame_hash: str, last_frame_hash: str,
|
||||
identity_hash: str, strict_compatibility: bool,
|
||||
existing_session: dict[str, Any] | None,
|
||||
reference_contract: dict[str, Any] | None = None,
|
||||
conditioning_mode: str | None = None,
|
||||
) -> dict[str, Any] | None:
|
||||
if existing_session is not None:
|
||||
raise RunStorageError("Run Storage cannot be combined with an explicit Session")
|
||||
self.prompts = [str(value) for value in prompt_plan["prompts"]]
|
||||
from .graph_contract import build_upstream_graph_contract
|
||||
graph_contract, graph_safe, graph_reasons = build_upstream_graph_contract(
|
||||
self.prompt_graph,
|
||||
self.sampler_node_id,
|
||||
require_video_vae=conditioning_mode_uses_video_vae(
|
||||
str(conditioning_mode)
|
||||
),
|
||||
)
|
||||
contract, safe, reasons = build_sampling_contract(
|
||||
model=model, model_fingerprint_value=model_fingerprint_value,
|
||||
clip=clip, video_vae=video_vae,
|
||||
sampler=sampler, sigmas=sigmas, prompt_plan=prompt_plan,
|
||||
width=width, height=height, chunk_seconds=chunk_seconds,
|
||||
continuity=continuity, audio_continuity=audio_continuity,
|
||||
base_seed=base_seed, reroll_from_chunk=reroll_from_chunk,
|
||||
reroll_nonce=reroll_nonce, first_frame_hash=first_frame_hash,
|
||||
last_frame_hash=last_frame_hash,
|
||||
strict_compatibility=strict_compatibility,
|
||||
reference_contract=reference_contract,
|
||||
conditioning_mode=conditioning_mode,
|
||||
upstream_graph_contract=graph_contract,
|
||||
upstream_graph_safe=graph_safe,
|
||||
upstream_graph_reasons=graph_reasons,
|
||||
)
|
||||
effective_nonce, nonce_decision = self._resolve_effective_nonce(
|
||||
contract, requested_nonce=int(reroll_nonce), resume_safe=safe
|
||||
)
|
||||
contract = _apply_nonce_contract(
|
||||
contract,
|
||||
requested_nonce=int(reroll_nonce),
|
||||
effective_nonce=effective_nonce,
|
||||
)
|
||||
self.resume_safe = bool(safe)
|
||||
self.effective_reroll_nonce = int(effective_nonce)
|
||||
self.nonce_decision = nonce_decision
|
||||
if not safe:
|
||||
contract = dict(contract)
|
||||
contract["reuse_policy"] = "disabled_unobservable_contract"
|
||||
contract["execution_nonce"] = uuid.uuid4().hex
|
||||
self.disabled_reasons = reasons
|
||||
self.contract = contract
|
||||
self.revision_id, self.contract_sha256 = revision_identity(contract)
|
||||
|
||||
self.revision_root = self.revisions_root / self.revision_id
|
||||
self.revision_root.mkdir(parents=True, exist_ok=True)
|
||||
exact = None
|
||||
if self._manifest_path().exists():
|
||||
try:
|
||||
exact = _read_json(self._manifest_path())
|
||||
except Exception as exc:
|
||||
self.notes.append(f"exact manifest rejected: {exc}")
|
||||
if exact is not None and exact.get("contract_sha256") != self.contract_sha256:
|
||||
raise RunStorageError(f"short revision id collision: {self.revision_id}")
|
||||
|
||||
hashes = list(contract["chunk_contract_hashes"])
|
||||
best_entries: list[dict[str, Any]] = []
|
||||
best_records: list[dict[str, Any]] = []
|
||||
candidates = [exact] if exact is not None and safe else []
|
||||
if safe and exact is None and self.revisions_root.exists():
|
||||
for path in self.revisions_root.glob("*/manifest.json"):
|
||||
try:
|
||||
candidates.append(_read_json(path))
|
||||
except Exception:
|
||||
continue
|
||||
for candidate in candidates:
|
||||
if int(candidate.get("run_storage_schema_version", -1)) != RUN_STORAGE_SCHEMA_VERSION:
|
||||
continue
|
||||
entries, records = self._valid_prefix(candidate, hashes)
|
||||
if len(entries) > len(best_entries):
|
||||
best_entries, best_records = entries, records
|
||||
|
||||
self.reused_count = len(best_entries)
|
||||
now = _now()
|
||||
self.manifest = {
|
||||
"run_storage_schema_version": RUN_STORAGE_SCHEMA_VERSION,
|
||||
"sampling_contract_version": SAMPLING_CONTRACT_VERSION,
|
||||
"run_name": self.run_name,
|
||||
"revision_id": self.revision_id,
|
||||
"contract_sha256": self.contract_sha256,
|
||||
"contract": contract,
|
||||
"resume_safe": bool(safe),
|
||||
"resume_disabled_reasons": list(reasons),
|
||||
"nonce_lifecycle": dict(contract["nonce_lifecycle"]),
|
||||
"status": "in_progress",
|
||||
"created_utc": (exact or {}).get("created_utc", now),
|
||||
"updated_utc": now,
|
||||
"chunks": best_records,
|
||||
"report_summary": (exact or {}).get("report_summary", ""),
|
||||
}
|
||||
self._write_manifest()
|
||||
self._write_project()
|
||||
if not best_entries:
|
||||
return None
|
||||
return make_session(
|
||||
chunks=best_entries, width=int(width), height=int(height),
|
||||
chunk_seconds=float(chunk_seconds), identity_hash=str(identity_hash),
|
||||
model_fingerprint_value=str(model_fingerprint_value),
|
||||
parent_session_id=None, reroll_from_chunk=0,
|
||||
settings={
|
||||
"run_storage_validated_prefix": True,
|
||||
"revision_id": self.revision_id,
|
||||
"first_frame_hash": str(first_frame_hash),
|
||||
"last_frame_hash": str(last_frame_hash),
|
||||
},
|
||||
)
|
||||
|
||||
def commit_chunk(self, entry: dict[str, Any], *, position: int) -> None:
|
||||
if self.manifest is None or self.revision_root is None:
|
||||
return
|
||||
validated = validate_chunk_entry(entry)
|
||||
if isinstance(position, bool) or not isinstance(position, int):
|
||||
raise RunStorageError("Run Storage chunk position must be an integer")
|
||||
expected = int((self.contract or {}).get("chunk_count", 0))
|
||||
if position < 0 or position >= expected:
|
||||
raise RunStorageError(
|
||||
f"Run Storage chunk position {position} is outside 0..{expected - 1}"
|
||||
)
|
||||
existing_records = list(self.manifest.get("chunks") or [])
|
||||
if len(existing_records) < position:
|
||||
raise RunStorageError(
|
||||
f"Run Storage cannot commit chunk {position + 1} before chunk {position}"
|
||||
)
|
||||
chunks_root = self.revision_root / "chunks"
|
||||
chunks_root.mkdir(parents=True, exist_ok=True)
|
||||
filename = f"chunk_{position + 1:04d}.safetensors"
|
||||
target = chunks_root / filename
|
||||
temporary = chunks_root / f".{filename}.{uuid.uuid4().hex}.tmp"
|
||||
tensors = {
|
||||
"video": validated["video"].detach().to("cpu").contiguous(),
|
||||
"audio": validated["audio"].detach().to("cpu").contiguous(),
|
||||
}
|
||||
try:
|
||||
save_file(tensors, str(temporary), metadata={
|
||||
"h3_continuum_run_storage": str(RUN_STORAGE_SCHEMA_VERSION),
|
||||
"revision_id": self.revision_id,
|
||||
"chunk_number": str(position + 1),
|
||||
})
|
||||
_fsync_file(temporary)
|
||||
os.replace(temporary, target)
|
||||
_fsync_dir(chunks_root)
|
||||
finally:
|
||||
if temporary.exists():
|
||||
temporary.unlink()
|
||||
storage_entry = dict(validated)
|
||||
storage_entry["sequence_index"] = position
|
||||
record = {
|
||||
"sequence_index": position,
|
||||
"storage_revision_id": self.revision_id,
|
||||
"filename": filename,
|
||||
"file_size": target.stat().st_size,
|
||||
"entry": _entry_metadata(storage_entry),
|
||||
}
|
||||
records = existing_records[:position]
|
||||
records.append(record)
|
||||
self.manifest.update(chunks=records, updated_utc=_now(), status="in_progress")
|
||||
self._write_manifest()
|
||||
self.generated_count += 1
|
||||
|
||||
def summary(self, *, detailed: bool = False) -> str:
|
||||
total = int((self.contract or {}).get("chunk_count", 0))
|
||||
resume = self.reused_count + 1 if self.reused_count < total else "complete"
|
||||
policy = (" auto-resume disabled: " + "; ".join(self.disabled_reasons) + ".") if self.disabled_reasons else ""
|
||||
note = (" " + " ".join(self.notes)) if self.notes else ""
|
||||
basic = (
|
||||
f"Run Storage: {self.run_name} / revision {self.revision_id}; "
|
||||
f"{self.reused_count} reused, {self.generated_count} generated, "
|
||||
f"{total} total; resume={resume}; nonce={self.effective_reroll_nonce} "
|
||||
f"({self.nonce_decision}).{policy}{note}"
|
||||
)
|
||||
if not detailed or self.manifest is None:
|
||||
return basic
|
||||
records = list(self.manifest.get("chunks") or [])
|
||||
lines = [basic, f"Run Storage path: {self.revision_root}"]
|
||||
for record in records:
|
||||
lines.append(
|
||||
f"stored chunk {int(record['sequence_index']) + 1}: "
|
||||
f"{record['storage_revision_id']}/chunks/{record['filename']} "
|
||||
f"({int(record['file_size']) / (1024.0 ** 2):.1f} MiB)"
|
||||
)
|
||||
try:
|
||||
free_gib = shutil.disk_usage(self.run_root).free / (1024.0 ** 3)
|
||||
lines.append(f"Run Storage free disk: {free_gib:.2f} GiB")
|
||||
except OSError:
|
||||
lines.append("Run Storage free disk: unknown")
|
||||
first_invalid = self.reused_count + 1 if self.reused_count < total else "none"
|
||||
lines.append(f"Run Storage first regenerated chunk: {first_invalid}")
|
||||
return "\n".join(lines)
|
||||
|
||||
def finalize(self, *, session: dict[str, Any], report: str) -> None:
|
||||
if self.manifest is None:
|
||||
return
|
||||
expected = int((self.contract or {}).get("chunk_count", 0))
|
||||
status = "complete" if len(self.manifest.get("chunks") or []) == expected else "interrupted"
|
||||
self.manifest.update(
|
||||
status=status, updated_utc=_now(),
|
||||
session_id=str(session.get("session_id", "")),
|
||||
report_summary=str(report)[-8192:],
|
||||
)
|
||||
self._write_manifest()
|
||||
self._write_project()
|
||||
|
||||
|
||||
def get_active_run_storage() -> RunStorageController | None:
|
||||
return _ACTIVE.get()
|
||||
|
||||
|
||||
def run_storage_scope(
|
||||
run_name: str, *, prompt: Any = None, unique_id: Any = None
|
||||
) -> RunStorageController:
|
||||
controller = RunStorageController(run_name)
|
||||
controller.set_prompt_graph(prompt, unique_id)
|
||||
return controller
|
||||
@@ -0,0 +1,38 @@
|
||||
import pytest
|
||||
|
||||
from ComfyUI_H3_Continuum_Join.conditioning import (
|
||||
conditioning_mode_from_presence,
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("has_first", "has_last", "has_reference", "expected"),
|
||||
[
|
||||
(False, False, False, "t2va"),
|
||||
(True, False, False, "i2va"),
|
||||
(False, True, False, "last_only"),
|
||||
(True, True, False, "fl2va"),
|
||||
(False, False, True, "reference"),
|
||||
],
|
||||
)
|
||||
def test_conditioning_mode_matrix(
|
||||
has_first, has_last, has_reference, expected
|
||||
):
|
||||
assert conditioning_mode_from_presence(
|
||||
has_first=has_first,
|
||||
has_last=has_last,
|
||||
has_reference=has_reference,
|
||||
) == expected
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("has_first", "has_last"),
|
||||
[(True, False), (False, True), (True, True)],
|
||||
)
|
||||
def test_reference_rejects_first_or_last_frame(has_first, has_last):
|
||||
with pytest.raises(ValueError, match="cannot be combined"):
|
||||
conditioning_mode_from_presence(
|
||||
has_first=has_first,
|
||||
has_last=has_last,
|
||||
has_reference=True,
|
||||
)
|
||||
@@ -139,4 +139,4 @@ def test_v217_result_pack_expands_legacy_outputs():
|
||||
def test_v217_has_no_frontend_display_controller():
|
||||
assert not (ROOT / "web" / "h3_continuum_v2.js").exists()
|
||||
version_source = (ROOT / "version.py").read_text(encoding="utf-8")
|
||||
assert 'PACKAGE_VERSION = "3.0.1"' in version_source
|
||||
assert 'PACKAGE_VERSION = "3.2.1"' in version_source
|
||||
|
||||
@@ -57,7 +57,7 @@ def test_auto_keeps_a_clean_legacy_video_boundary():
|
||||
assert torch.equal(corrected, current[2:])
|
||||
assert decision.cut_rewind_frames == 0
|
||||
assert decision.corrected_score == decision.legacy_score
|
||||
assert decision.fallback_reason.startswith("Auto kept the legacy video seam")
|
||||
assert decision.fallback_reason.startswith("Auto kept native video")
|
||||
assert patch is None
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,477 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import copy
|
||||
import json
|
||||
from types import SimpleNamespace
|
||||
|
||||
import torch
|
||||
|
||||
from ComfyUI_H3_Continuum_Join.run_storage import (
|
||||
RunStorageController,
|
||||
_apply_nonce_contract,
|
||||
_fsync_file,
|
||||
build_sampling_contract,
|
||||
revision_identity,
|
||||
)
|
||||
from ComfyUI_H3_Continuum_Join.graph_contract import build_upstream_graph_contract
|
||||
from ComfyUI_H3_Continuum_Join.state import make_plan
|
||||
from ComfyUI_H3_Continuum_Join.v2.session import make_chunk_entry
|
||||
|
||||
|
||||
class _Nested:
|
||||
def __init__(self, parts):
|
||||
self.parts = parts
|
||||
|
||||
def unbind(self):
|
||||
return self.parts
|
||||
|
||||
|
||||
def _entry(position: int, *, prompt: str = "same fixed prompt"):
|
||||
continuation = position > 0
|
||||
frame_count = 141 if continuation else 124
|
||||
video_t = 42 if continuation else 37
|
||||
audio_t = 235 if continuation else 207
|
||||
plan = make_plan(
|
||||
continuation=continuation,
|
||||
clip_index=position + 1,
|
||||
total_frames=frame_count,
|
||||
trim_frames=22 if continuation else 0,
|
||||
width=96,
|
||||
height=64,
|
||||
context_frames=22 if continuation else 0,
|
||||
state_capacity_frames=39,
|
||||
requested_extend_seconds=5,
|
||||
debug=False,
|
||||
)
|
||||
return make_chunk_entry(
|
||||
latent={
|
||||
"samples": _Nested(
|
||||
(
|
||||
torch.full((1, 24, video_t, 4, 6), float(position)),
|
||||
torch.full((1, 32, 2, audio_t), float(position)),
|
||||
)
|
||||
)
|
||||
},
|
||||
plan=plan,
|
||||
prompt=prompt,
|
||||
prompt_hash=str(position + 1) * 64,
|
||||
seed=100 + position,
|
||||
context_frames=22 if continuation else 0,
|
||||
motion_score=float(position),
|
||||
reused=False,
|
||||
)
|
||||
|
||||
|
||||
def _controller(tmp_path, *, chunk_count: int = 3):
|
||||
controller = RunStorageController("run-storage-test")
|
||||
controller.revisions_root = tmp_path / "revisions"
|
||||
controller.revision_id = "revision-test"
|
||||
controller.revision_root = controller.revisions_root / controller.revision_id
|
||||
hashes = [f"contract-{position}" for position in range(chunk_count)]
|
||||
controller.contract = {
|
||||
"chunk_count": chunk_count,
|
||||
"chunk_contract_hashes": hashes,
|
||||
}
|
||||
controller.prompts = ["same fixed prompt"] * chunk_count
|
||||
controller.manifest = {
|
||||
"contract": controller.contract,
|
||||
"chunks": [],
|
||||
"status": "in_progress",
|
||||
}
|
||||
return controller, hashes
|
||||
|
||||
|
||||
def test_three_chunks_are_committed_to_distinct_files(tmp_path):
|
||||
controller, _ = _controller(tmp_path)
|
||||
source_entries = [_entry(position) for position in range(3)]
|
||||
|
||||
for position, entry in enumerate(source_entries):
|
||||
controller.commit_chunk(entry, position=position)
|
||||
|
||||
chunks_root = controller.revision_root / "chunks"
|
||||
assert [path.name for path in sorted(chunks_root.glob("*.safetensors"))] == [
|
||||
"chunk_0001.safetensors",
|
||||
"chunk_0002.safetensors",
|
||||
"chunk_0003.safetensors",
|
||||
]
|
||||
records = controller.manifest["chunks"]
|
||||
assert [record["sequence_index"] for record in records] == [0, 1, 2]
|
||||
assert [record["entry"]["sequence_index"] for record in records] == [0, 1, 2]
|
||||
assert [entry["sequence_index"] for entry in source_entries] == [0, 0, 0]
|
||||
|
||||
persisted = json.loads(controller._manifest_path().read_text(encoding="utf-8"))
|
||||
assert [record["filename"] for record in persisted["chunks"]] == [
|
||||
"chunk_0001.safetensors",
|
||||
"chunk_0002.safetensors",
|
||||
"chunk_0003.safetensors",
|
||||
]
|
||||
|
||||
|
||||
def test_interrupted_fixed_prompt_run_resumes_the_correct_prefix(tmp_path):
|
||||
first, hashes = _controller(tmp_path)
|
||||
first.commit_chunk(_entry(0), position=0)
|
||||
first.commit_chunk(_entry(1), position=1)
|
||||
|
||||
resumed, _ = _controller(tmp_path)
|
||||
resumed.manifest = json.loads(first._manifest_path().read_text(encoding="utf-8"))
|
||||
entries, records = resumed._valid_prefix(resumed.manifest, hashes)
|
||||
|
||||
assert [entry["seed"] for entry in entries] == [100, 101]
|
||||
assert [entry["clip_index"] for entry in entries] == [1, 2]
|
||||
assert [record["filename"] for record in records] == [
|
||||
"chunk_0001.safetensors",
|
||||
"chunk_0002.safetensors",
|
||||
]
|
||||
|
||||
resumed.commit_chunk(_entry(2), position=2)
|
||||
assert [record["filename"] for record in resumed.manifest["chunks"]] == [
|
||||
"chunk_0001.safetensors",
|
||||
"chunk_0002.safetensors",
|
||||
"chunk_0003.safetensors",
|
||||
]
|
||||
|
||||
|
||||
def test_fsync_file_accepts_a_completed_file_on_windows(tmp_path):
|
||||
target = tmp_path / "chunk.tmp"
|
||||
target.write_bytes(b"complete")
|
||||
_fsync_file(target)
|
||||
|
||||
|
||||
def _sample_function(*args, **kwargs):
|
||||
return None
|
||||
|
||||
|
||||
class _Sampler:
|
||||
sampler_function = _sample_function
|
||||
extra_options = {}
|
||||
inpaint_options = {}
|
||||
|
||||
|
||||
class _Patcher:
|
||||
def __init__(self, model):
|
||||
self.model = model
|
||||
self.wrappers = {}
|
||||
self.patches = {}
|
||||
self.object_patches = {}
|
||||
self.model_options = {}
|
||||
|
||||
|
||||
class _Model:
|
||||
def __init__(self):
|
||||
self.model = SimpleNamespace(diffusion_model=torch.nn.Linear(2, 2))
|
||||
self.wrappers = {}
|
||||
self.patches = {}
|
||||
self.model_options = {}
|
||||
|
||||
def model_dtype(self):
|
||||
return torch.float32
|
||||
|
||||
def model_size(self):
|
||||
return 4
|
||||
|
||||
|
||||
class _Clip:
|
||||
def __init__(self):
|
||||
self.cond_stage_model = torch.nn.Linear(2, 2)
|
||||
self.patcher = _Patcher(self.cond_stage_model)
|
||||
core = SimpleNamespace(
|
||||
name_or_path="minimax-qwen",
|
||||
vocab_size=100,
|
||||
model_max_length=1024,
|
||||
padding_side="right",
|
||||
truncation_side="right",
|
||||
bos_token_id=1,
|
||||
eos_token_id=2,
|
||||
pad_token_id=0,
|
||||
)
|
||||
self.tokenizer = SimpleNamespace(
|
||||
qwen3vl_32b=SimpleNamespace(tokenizer=core)
|
||||
)
|
||||
self.tokenizer_options = {}
|
||||
self.layer_idx = None
|
||||
self.use_clip_schedule = False
|
||||
|
||||
|
||||
class _VideoVAE:
|
||||
def __init__(self):
|
||||
self.first_stage_model = torch.nn.Linear(2, 2)
|
||||
self.patcher = _Patcher(self.first_stage_model)
|
||||
self.vae_dtype = torch.float16
|
||||
self.latent_channels = 24
|
||||
self.downscale_ratio = 16
|
||||
self.upscale_ratio = 16
|
||||
|
||||
|
||||
def _sampling_contract(
|
||||
*, model=None, clip=None, video_vae=None, sampler=None, reroll_nonce=0,
|
||||
conditioning_mode="i2va", first_frame_hash="a" * 64,
|
||||
last_frame_hash="", reference_contract=None,
|
||||
):
|
||||
return build_sampling_contract(
|
||||
model=model or _Model(),
|
||||
model_fingerprint_value="f" * 64,
|
||||
clip=clip or _Clip(),
|
||||
video_vae=video_vae or _VideoVAE(),
|
||||
sampler=sampler or _Sampler(),
|
||||
sigmas=torch.tensor([1.0, 0.0]),
|
||||
prompt_plan={
|
||||
"chunks": 3,
|
||||
"hashes": ["1" * 64, "2" * 64, "3" * 64],
|
||||
"mode": "list",
|
||||
},
|
||||
width=96,
|
||||
height=64,
|
||||
chunk_seconds=5.0,
|
||||
continuity="Balanced",
|
||||
audio_continuity=True,
|
||||
base_seed=1,
|
||||
reroll_from_chunk=2,
|
||||
reroll_nonce=reroll_nonce,
|
||||
first_frame_hash=first_frame_hash,
|
||||
last_frame_hash=last_frame_hash,
|
||||
strict_compatibility=True,
|
||||
reference_contract=reference_contract,
|
||||
conditioning_mode=conditioning_mode,
|
||||
)
|
||||
|
||||
|
||||
def test_clip_and_required_video_vae_are_part_of_sampling_contract():
|
||||
clip = _Clip()
|
||||
vae = _VideoVAE()
|
||||
first, safe, reasons = _sampling_contract(clip=clip, video_vae=vae)
|
||||
assert safe, reasons
|
||||
|
||||
with torch.no_grad():
|
||||
clip.cond_stage_model.weight.add_(1)
|
||||
changed_clip, safe, reasons = _sampling_contract(clip=clip, video_vae=vae)
|
||||
assert safe, reasons
|
||||
assert revision_identity(first) != revision_identity(changed_clip)
|
||||
|
||||
with torch.no_grad():
|
||||
vae.first_stage_model.weight.add_(1)
|
||||
changed_vae, safe, reasons = _sampling_contract(clip=clip, video_vae=vae)
|
||||
assert safe, reasons
|
||||
assert revision_identity(changed_clip) != revision_identity(changed_vae)
|
||||
|
||||
|
||||
def test_t2va_contract_omits_video_vae_signature():
|
||||
model = _Model()
|
||||
clip = _Clip()
|
||||
vae = _VideoVAE()
|
||||
sampler = _Sampler()
|
||||
first, safe, reasons = _sampling_contract(
|
||||
model=model,
|
||||
clip=clip,
|
||||
video_vae=vae,
|
||||
sampler=sampler,
|
||||
conditioning_mode="t2va",
|
||||
first_frame_hash="",
|
||||
)
|
||||
assert safe, reasons
|
||||
assert first["global"]["conditioning_mode"] == "t2va"
|
||||
assert "video_vae" not in first["global"]
|
||||
assert "first_frame_hash" not in first["global"]
|
||||
|
||||
with torch.no_grad():
|
||||
vae.first_stage_model.weight.add_(1)
|
||||
changed, safe, reasons = _sampling_contract(
|
||||
model=model,
|
||||
clip=clip,
|
||||
video_vae=vae,
|
||||
sampler=sampler,
|
||||
conditioning_mode="t2va",
|
||||
first_frame_hash="",
|
||||
)
|
||||
assert safe, reasons
|
||||
assert revision_identity(first) == revision_identity(changed)
|
||||
|
||||
|
||||
def test_conditioning_mode_change_invalidates_all_chunk_contracts():
|
||||
i2va, safe, reasons = _sampling_contract()
|
||||
assert safe, reasons
|
||||
t2va, safe, reasons = _sampling_contract(
|
||||
conditioning_mode="t2va",
|
||||
first_frame_hash="",
|
||||
)
|
||||
assert safe, reasons
|
||||
assert i2va["chunk_contract_hashes"] != t2va["chunk_contract_hashes"]
|
||||
assert all(
|
||||
left != right
|
||||
for left, right in zip(
|
||||
i2va["chunk_contract_hashes"], t2va["chunk_contract_hashes"]
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
def test_unobservable_clip_disables_resume_but_preserves_contract():
|
||||
clip = _Clip()
|
||||
clip.tokenizer = None
|
||||
contract, safe, reasons = _sampling_contract(clip=clip)
|
||||
assert not safe
|
||||
assert contract["global"]["clip"]
|
||||
assert any("CLIP/Qwen" in reason for reason in reasons)
|
||||
|
||||
|
||||
def _write_nonce_manifest(root, name, contract, status):
|
||||
target = root / name
|
||||
target.mkdir(parents=True)
|
||||
(target / "manifest.json").write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"run_storage_schema_version": 1,
|
||||
"status": status,
|
||||
"updated_utc": "2026-08-13T00:00:00+00:00",
|
||||
"contract": contract,
|
||||
"nonce_lifecycle": contract["nonce_lifecycle"],
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
|
||||
def test_auto_nonce_resumes_interrupted_revision(tmp_path):
|
||||
controller, _ = _controller(tmp_path)
|
||||
draft, safe, reasons = _sampling_contract()
|
||||
assert safe, reasons
|
||||
interrupted = _apply_nonce_contract(
|
||||
draft, requested_nonce=0, effective_nonce=2
|
||||
)
|
||||
_write_nonce_manifest(
|
||||
controller.revisions_root, "interrupted", interrupted, "interrupted"
|
||||
)
|
||||
|
||||
nonce, decision = controller._resolve_effective_nonce(
|
||||
draft, requested_nonce=0, resume_safe=True
|
||||
)
|
||||
assert (nonce, decision) == (2, "resume_interrupted")
|
||||
|
||||
|
||||
def test_auto_nonce_increments_only_after_completed_revision(tmp_path):
|
||||
controller, _ = _controller(tmp_path)
|
||||
draft, safe, reasons = _sampling_contract()
|
||||
assert safe, reasons
|
||||
completed = _apply_nonce_contract(
|
||||
draft, requested_nonce=0, effective_nonce=2
|
||||
)
|
||||
_write_nonce_manifest(
|
||||
controller.revisions_root, "completed", completed, "complete"
|
||||
)
|
||||
|
||||
nonce, decision = controller._resolve_effective_nonce(
|
||||
draft, requested_nonce=0, resume_safe=True
|
||||
)
|
||||
assert (nonce, decision) == (3, "new_revision")
|
||||
|
||||
|
||||
def test_explicit_nonce_is_never_auto_incremented(tmp_path):
|
||||
controller, _ = _controller(tmp_path)
|
||||
draft, safe, reasons = _sampling_contract(reroll_nonce=7)
|
||||
assert safe, reasons
|
||||
|
||||
nonce, decision = controller._resolve_effective_nonce(
|
||||
draft, requested_nonce=7, resume_safe=True
|
||||
)
|
||||
assert (nonce, decision) == (7, "explicit")
|
||||
|
||||
|
||||
def _prompt_graph(model_name="minimax_h3_fl2va.safetensors"):
|
||||
return {
|
||||
"10": {
|
||||
"class_type": "UNETLoader",
|
||||
"inputs": {"unet_name": model_name, "weight_dtype": "default"},
|
||||
},
|
||||
"11": {
|
||||
"class_type": "PathchSageAttentionKJ",
|
||||
"inputs": {"model": ["10", 0], "sage_attention": "auto"},
|
||||
},
|
||||
"12": {
|
||||
"class_type": "SpectrumApplyMiniMaxH3",
|
||||
"inputs": {"model": ["11", 0], "enabled": True, "warmup_steps": 1},
|
||||
},
|
||||
"20": {
|
||||
"class_type": "CLIPLoader",
|
||||
"inputs": {"clip_name": "qwen3vl_h3.safetensors", "type": "minimax_h3"},
|
||||
},
|
||||
"30": {
|
||||
"class_type": "VAELoader",
|
||||
"inputs": {"vae_name": "minimax_h3_video_vae_fp16.safetensors"},
|
||||
},
|
||||
"42": {
|
||||
"class_type": "H3ContinuumSamplerProduction",
|
||||
"inputs": {"model": ["12", 0], "clip": ["20", 0], "video_vae": ["30", 0]},
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def test_upstream_graph_fingerprint_tracks_loader_and_patch_order():
|
||||
graph, safe, reasons = build_upstream_graph_contract(
|
||||
_prompt_graph(), "42", require_video_vae=True
|
||||
)
|
||||
assert safe, reasons
|
||||
changed, changed_safe, changed_reasons = build_upstream_graph_contract(
|
||||
_prompt_graph("minimax_h3_ref2va.safetensors"),
|
||||
"42",
|
||||
require_video_vae=True,
|
||||
)
|
||||
assert changed_safe, changed_reasons
|
||||
assert graph["sha256"] != changed["sha256"]
|
||||
model_route = graph["routes"]["model"]["node"]
|
||||
assert model_route["class_type"] == "SpectrumApplyMiniMaxH3"
|
||||
assert model_route["inputs"]["model"]["node"]["class_type"] == "PathchSageAttentionKJ"
|
||||
|
||||
|
||||
def test_upstream_graph_fingerprint_accepts_runtime_turbo_and_sage_nodes():
|
||||
prompt = _prompt_graph()
|
||||
prompt["11"] = {
|
||||
"class_type": "MiniMaxH3MemoryEfficientSageAttentionPatch",
|
||||
"inputs": {"model": ["10", 0]},
|
||||
}
|
||||
prompt["12"] = {
|
||||
"class_type": "Power Lora Loader (rgthree)",
|
||||
"inputs": {
|
||||
"model": ["11", 0],
|
||||
"lora_1": {
|
||||
"on": True,
|
||||
"lora": "minimax_h3_fl2v_turbo_8step.safetensors",
|
||||
"strength": 1.0,
|
||||
"strengthTwo": 0.0,
|
||||
},
|
||||
},
|
||||
}
|
||||
graph, safe, reasons = build_upstream_graph_contract(
|
||||
prompt, "42", require_video_vae=True
|
||||
)
|
||||
assert safe, reasons
|
||||
changed_prompt = copy.deepcopy(prompt)
|
||||
changed_prompt["12"]["inputs"]["lora_1"]["strength"] = 0.8
|
||||
changed, changed_safe, changed_reasons = build_upstream_graph_contract(
|
||||
changed_prompt, "42", require_video_vae=True
|
||||
)
|
||||
assert changed_safe, changed_reasons
|
||||
assert graph["sha256"] != changed["sha256"]
|
||||
model_route = graph["routes"]["model"]["node"]
|
||||
assert model_route["class_type"] == "Power Lora Loader (rgthree)"
|
||||
assert (
|
||||
model_route["inputs"]["model"]["node"]["class_type"]
|
||||
== "MiniMaxH3MemoryEfficientSageAttentionPatch"
|
||||
)
|
||||
|
||||
|
||||
def test_unknown_upstream_wrapper_disables_resume():
|
||||
prompt = _prompt_graph()
|
||||
prompt["12"]["class_type"] = "UnknownExperimentalWrapper"
|
||||
_, safe, reasons = build_upstream_graph_contract(
|
||||
prompt, "42", require_video_vae=True
|
||||
)
|
||||
assert not safe
|
||||
assert any("UnknownExperimentalWrapper" in reason for reason in reasons)
|
||||
|
||||
|
||||
def test_t2va_graph_contract_does_not_require_video_vae_route():
|
||||
prompt = _prompt_graph()
|
||||
del prompt["42"]["inputs"]["video_vae"]
|
||||
graph, safe, reasons = build_upstream_graph_contract(
|
||||
prompt, "42", require_video_vae=False
|
||||
)
|
||||
assert safe, reasons
|
||||
assert "video_vae" not in graph["routes"]
|
||||
@@ -0,0 +1,53 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import pytest
|
||||
import torch
|
||||
|
||||
from ComfyUI_H3_Continuum_Join.reference import (
|
||||
REFERENCE_SIZE_MATCH_OUTPUT,
|
||||
ReferenceAssets,
|
||||
ReferenceConditioningError,
|
||||
validate_reference_prompts,
|
||||
)
|
||||
|
||||
|
||||
def test_reference_size_is_appended_after_v31_widgets():
|
||||
from pathlib import Path
|
||||
|
||||
source = (Path(__file__).resolve().parents[1] / "v3" / "nodes.py").read_text(
|
||||
encoding="utf-8"
|
||||
)
|
||||
production = source.split("class H3ContinuumSamplerProduction", 1)[1]
|
||||
required = production.split('"optional": {', 1)[0]
|
||||
assert required.index('"run_name"') < required.index('"reference_size"')
|
||||
|
||||
|
||||
def _assets(count: int = 2) -> ReferenceAssets:
|
||||
images = tuple(torch.zeros((1, 32, 32, 3)) for _ in range(count))
|
||||
hashes = tuple(str(index) * 64 for index in range(1, count + 1))
|
||||
return ReferenceAssets(
|
||||
images=images,
|
||||
latents=tuple(None for _ in range(count)),
|
||||
image_hashes=hashes,
|
||||
combined_hash="a" * 64,
|
||||
size_mode=REFERENCE_SIZE_MATCH_OUTPUT,
|
||||
)
|
||||
|
||||
|
||||
def test_reference_contract_contains_metadata_only():
|
||||
contract = _assets().contract
|
||||
assert contract["count"] == 2
|
||||
assert contract["size_mode"] == REFERENCE_SIZE_MATCH_OUTPUT
|
||||
assert contract["image_hashes"] == ["1" * 64, "2" * 64]
|
||||
assert not any(torch.is_tensor(value) for value in contract.values())
|
||||
|
||||
|
||||
def test_picture_tags_must_match_connected_references():
|
||||
assert validate_reference_prompts(["Use <Picture 1> and <Picture 2>."], 2) == ""
|
||||
with pytest.raises(ReferenceConditioningError, match="Picture 2"):
|
||||
validate_reference_prompts(["Use <Picture 2>."], 1)
|
||||
|
||||
|
||||
def test_missing_picture_tag_is_a_warning_not_an_error():
|
||||
warning = validate_reference_prompts(["The same person walks forward."], 1)
|
||||
assert "no <Picture N> tag" in warning
|
||||
@@ -24,6 +24,16 @@ class IdentityAssets:
|
||||
last_latent: torch.Tensor | None
|
||||
identity_hash: str
|
||||
|
||||
@property
|
||||
def first_frame_hash(self) -> str:
|
||||
"""Version-neutral alias retained alongside the legacy identity hash."""
|
||||
return self.identity_hash
|
||||
|
||||
@property
|
||||
def last_frame_hash(self) -> str:
|
||||
"""Fingerprint the resized final keyframe independently from identity."""
|
||||
return _tensor_fingerprint(self.last_image)
|
||||
|
||||
|
||||
def _tensor_fingerprint(tensor: torch.Tensor | None) -> str:
|
||||
if tensor is None:
|
||||
|
||||
@@ -304,6 +304,7 @@ class H3ContinuumSamplerV2:
|
||||
sequence_prompt=None,
|
||||
show_preview=True,
|
||||
latent_only=False,
|
||||
reference_assets=None,
|
||||
**clip_prompt_inputs,
|
||||
):
|
||||
(
|
||||
@@ -369,6 +370,7 @@ class H3ContinuumSamplerV2:
|
||||
session=session,
|
||||
initial_state=initial_state,
|
||||
latent_only=bool(latent_only),
|
||||
reference_assets=reference_assets,
|
||||
)
|
||||
|
||||
|
||||
@@ -487,6 +489,7 @@ class H3ContinuumSessionInfo:
|
||||
|
||||
|
||||
class H3ContinuumClipOverrides:
|
||||
DEPRECATED = True
|
||||
"""Build a static prompt-override pack without per-clip sockets."""
|
||||
|
||||
@classmethod
|
||||
@@ -790,6 +793,8 @@ class H3ContinuumSampler:
|
||||
class H3ContinuumResult:
|
||||
"""Expand the compact facade result pack only when advanced outputs are needed."""
|
||||
|
||||
DEPRECATED = True
|
||||
|
||||
@classmethod
|
||||
def INPUT_TYPES(cls):
|
||||
return {"required": {"result": ("H3_CONTINUUM_RESULT",)}}
|
||||
|
||||
+42
-13
@@ -67,15 +67,22 @@ def _preserved_prefix(*,session,prompt_hashes,chunks,reroll_from_chunk,width,hei
|
||||
elif reroll_from_chunk>0: notes.append(f"preserved chunks 1-{len(preserved)}; regenerated from chunk {reroll_from_chunk}")
|
||||
return preserved,notes
|
||||
|
||||
def _conditioning_cache(*,clip,prompts,assets,final_has_last_frame):
|
||||
def _conditioning_cache(*,clip,prompts,assets,final_has_last_frame,reference_assets=None):
|
||||
cache={}; final_index=len(prompts)-1
|
||||
for index,prompt in enumerate(prompts):
|
||||
include_last=bool(final_has_last_frame and index==final_index); key=(prompt,include_last)
|
||||
if key in cache: continue
|
||||
cache[key]=encode_prompt_conditioning(clip,prompt,first_image=assets.first_image,last_image=assets.last_image if include_last else None)
|
||||
if reference_assets is not None:
|
||||
from ..reference import encode_reference_prompt
|
||||
cache[key]=encode_reference_prompt(clip,prompt,reference_assets)
|
||||
else:
|
||||
cache[key]=encode_prompt_conditioning(clip,prompt,first_image=assets.first_image,last_image=assets.last_image if include_last else None)
|
||||
return cache
|
||||
|
||||
def run_sequence(*,model:Any,clip:Any,video_vae:Any,audio_vae:Any,sampler:Any,sigmas:torch.Tensor,first_frame:torch.Tensor|None,last_frame:torch.Tensor|None,prompt_plan:dict[str,Any],width:int,height:int,continuity:str,base_seed:int,audio_continuity:bool,exact_total_duration:bool,diagnostics_mode:str,reroll_from_chunk:int,reroll_nonce:int,strict_compatibility:bool,debug:bool,seam_correction:str=SEAM_CORRECTION_OFF,enable_preview:bool=True,session:dict[str,Any]|None=None,initial_state:dict[str,Any]|None=None,latent_only:bool=False):
|
||||
def run_sequence(*,model:Any,clip:Any,video_vae:Any,audio_vae:Any,sampler:Any,sigmas:torch.Tensor,first_frame:torch.Tensor|None,last_frame:torch.Tensor|None,prompt_plan:dict[str,Any],width:int,height:int,continuity:str,base_seed:int,audio_continuity:bool,exact_total_duration:bool,diagnostics_mode:str,reroll_from_chunk:int,reroll_nonce:int,strict_compatibility:bool,debug:bool,seam_correction:str=SEAM_CORRECTION_OFF,enable_preview:bool=True,session:dict[str,Any]|None=None,initial_state:dict[str,Any]|None=None,latent_only:bool=False,reference_assets=None):
|
||||
from ..conditioning import detect_conditioning_mode, conditioning_mode_label
|
||||
from ..run_storage import get_active_run_storage
|
||||
storage_controller=get_active_run_storage()
|
||||
diagnostics_mode=normalize_diagnostics_mode(diagnostics_mode); plan=validate_prompt_plan(prompt_plan); chunks=int(plan["chunks"]); chunk_seconds=float(plan["chunk_seconds"]); prompts=list(plan["prompts"]); prompt_hashes=list(plan["hashes"]); width,height=int(width),int(height)
|
||||
if width<=0 or height<=0 or width%32 or height%32: raise SequenceRuntimeError("width and height must be positive multiples of 32")
|
||||
if session is not None and initial_state is not None: raise SequenceRuntimeError("connect either a session or an initial_state, not both")
|
||||
@@ -83,21 +90,41 @@ def run_sequence(*,model:Any,clip:Any,video_vae:Any,audio_vae:Any,sampler:Any,si
|
||||
if seam_correction not in SEAM_CORRECTION_OPTIONS: raise SequenceRuntimeError(f"unknown seam correction mode: {seam_correction!r}")
|
||||
if not 0<=int(reroll_from_chunk)<=chunks: raise SequenceRuntimeError("reroll_from_chunk must be 0 or a valid one-based chunk index")
|
||||
if initial_state is not None and int(reroll_from_chunk) not in (0,1): raise SequenceRuntimeError("with initial_state, reroll_from_chunk can only be 0 or 1")
|
||||
try: conditioning_mode=detect_conditioning_mode(first_frame=first_frame,last_frame=last_frame,reference_assets=reference_assets)
|
||||
except ValueError as exc: raise SequenceRuntimeError(str(exc)) from exc
|
||||
reference_warning=""
|
||||
if reference_assets is not None:
|
||||
from ..reference import validate_reference_prompts
|
||||
if first_frame is not None or last_frame is not None: raise SequenceRuntimeError("Reference images cannot be combined with First Frame or Last Frame in V3.2")
|
||||
reference_warning=validate_reference_prompts(prompts,reference_assets.count)
|
||||
decode_estimate_gib=0.0; available_ram_gib=None
|
||||
if not latent_only: decode_estimate_gib,available_ram_gib=_check_decode_memory_budget(width=width,height=height,chunks=chunks,chunk_seconds=chunk_seconds)
|
||||
issues=check_comfy_h3_runtime()
|
||||
if issues and strict_compatibility: raise SequenceRuntimeError("H3 runtime is incompatible: "+"; ".join(issues))
|
||||
assets=prepare_identity_assets(video_vae,width=width,height=height,first_frame=first_frame,last_frame=last_frame,encode_latents=False)
|
||||
sequence_identity_hash=reference_assets.combined_hash if reference_assets is not None else assets.identity_hash
|
||||
current_model_fingerprint=model_fingerprint(model,extra_wrapper_keys=("h3_continuum_join.apply_model.v1",))
|
||||
if storage_controller is not None:
|
||||
stored_session=storage_controller.prepare(model=model,model_fingerprint_value=current_model_fingerprint,clip=clip,video_vae=video_vae,sampler=sampler,sigmas=sigmas,prompt_plan=plan,width=width,height=height,chunk_seconds=chunk_seconds,continuity=continuity,audio_continuity=audio_continuity,base_seed=base_seed,reroll_from_chunk=reroll_from_chunk,reroll_nonce=reroll_nonce,first_frame_hash=assets.first_frame_hash,last_frame_hash=assets.last_frame_hash,identity_hash=sequence_identity_hash,strict_compatibility=strict_compatibility,existing_session=session,reference_contract=reference_assets.contract if reference_assets is not None else None,conditioning_mode=conditioning_mode)
|
||||
reroll_nonce=storage_controller.effective_reroll_nonce
|
||||
if stored_session is not None: session=stored_session
|
||||
accelerators=accelerator_summary(model)
|
||||
if "Continuum APPLY_MODEL wrapper installed" not in accelerators: accelerators+="; Continuum APPLY_MODEL wrapper installed"
|
||||
preserved,reuse_notes=_preserved_prefix(session=session,prompt_hashes=prompt_hashes,chunks=chunks,reroll_from_chunk=int(reroll_from_chunk),width=width,height=height,chunk_seconds=chunk_seconds,identity_hash=assets.identity_hash)
|
||||
effective_reroll_from_chunk=0 if storage_controller is not None and session is not None and bool((session.get("settings") or {}).get("run_storage_validated_prefix")) else int(reroll_from_chunk)
|
||||
preserved,reuse_notes=_preserved_prefix(session=session,prompt_hashes=prompt_hashes,chunks=chunks,reroll_from_chunk=effective_reroll_from_chunk,width=width,height=height,chunk_seconds=chunk_seconds,identity_hash=sequence_identity_hash)
|
||||
if reference_assets is not None:
|
||||
reuse_notes.insert(0,f"Reference conditioning: {reference_assets.count} image(s), size={reference_assets.size_mode}; persistent across all chunks.")
|
||||
if reference_warning: reuse_notes.append("Warning: "+reference_warning)
|
||||
if session is not None:
|
||||
old_fingerprint=str(session.get("model_fingerprint",""))
|
||||
if old_fingerprint and old_fingerprint!=current_model_fingerprint: reuse_notes.append("model/accelerator fingerprint differs from the saved session; accepted chunks were kept")
|
||||
cache={}
|
||||
if len(preserved)<chunks:
|
||||
assets=encode_identity_latents(video_vae,assets); cache=_conditioning_cache(clip=clip,prompts=prompts,assets=assets,final_has_last_frame=last_frame is not None)
|
||||
assets=encode_identity_latents(video_vae,assets)
|
||||
if reference_assets is not None:
|
||||
from ..reference import encode_reference_latents
|
||||
reference_assets=encode_reference_latents(video_vae,reference_assets)
|
||||
cache=_conditioning_cache(clip=clip,prompts=prompts,assets=assets,final_has_last_frame=last_frame is not None,reference_assets=reference_assets)
|
||||
entries=preserved[:]; previous_state=None
|
||||
if entries: previous_state=entry_to_state(entries[-1])
|
||||
elif initial_state is not None:
|
||||
@@ -105,7 +132,7 @@ def run_sequence(*,model:Any,clip:Any,video_vae:Any,audio_vae:Any,sampler:Any,si
|
||||
if int(previous_state["width"])!=width or int(previous_state["height"])!=height: raise SequenceRuntimeError(f"initial_state is {previous_state['width']}x{previous_state['height']} but V2 is configured for {width}x{height}")
|
||||
initial_frame_count=align_frame_count_up(int(round(chunk_seconds*FPS))); retained_frames=sum(int(entry["plan"]["net_frames"]) for entry in entries); sampling_reports=[]
|
||||
for sequence_index in range(len(entries),chunks):
|
||||
prompt=prompts[sequence_index]; prompt_hash_value=prompt_hashes[sequence_index]; is_final=sequence_index==chunks-1; seed=derive_chunk_seed(base_seed,sequence_index,reroll_nonce); motion_score=0.0; video_context=None; audio_context=None; context_before=None
|
||||
prompt=prompts[sequence_index]; prompt_hash_value=prompt_hashes[sequence_index]; is_final=sequence_index==chunks-1; effective_reroll_nonce=int(reroll_nonce) if int(reroll_from_chunk)>0 and sequence_index+1>=int(reroll_from_chunk) else 0; seed=derive_chunk_seed(base_seed,sequence_index,effective_reroll_nonce); motion_score=0.0; video_context=None; audio_context=None; context_before=None
|
||||
if previous_state is None:
|
||||
total_frames=initial_frame_count; latent=empty_h3_latent(width,height,total_frames); conditioning=attach_keyframes(cache[(prompt,bool(last_frame is not None and is_final))],frame_count=total_frames,first_latent=assets.first_latent,last_latent=assets.last_latent if is_final else None); clip_index=1; context_frames=0
|
||||
chunk_plan=make_plan(continuation=False,clip_index=clip_index,total_frames=total_frames,trim_frames=0,width=width,height=height,context_frames=5,state_capacity_frames=largest_context_capacity(total_frames),requested_extend_seconds=chunk_seconds,debug=debug); reason="initial clip"
|
||||
@@ -118,15 +145,17 @@ def run_sequence(*,model:Any,clip:Any,video_vae:Any,audio_vae:Any,sampler:Any,si
|
||||
chunk_model=clone_model_for_chunk(model,strict=bool(strict_compatibility),debug=bool(debug),chunk_index=clip_index,context_frames=context_frames if previous_state is not None else None)
|
||||
sampled=sample_chunk(model=chunk_model,conditioning=conditioning,latent=latent,sampler=sampler,sigmas=sigmas,seed=seed,enable_preview=bool(enable_preview))
|
||||
if context_before is not None and video_context is not None: assert_context_unchanged(video_context,audio_context,context_before)
|
||||
entry=make_chunk_entry(latent=sampled,plan=chunk_plan,prompt=prompt,prompt_hash=prompt_hash_value,seed=seed,context_frames=context_frames,motion_score=motion_score,reused=False); previous_state=entry_to_state(entry); entries.append(entry); retained_frames+=int(chunk_plan["net_frames"])
|
||||
entry=make_chunk_entry(latent=sampled,plan=chunk_plan,prompt=prompt,prompt_hash=prompt_hash_value,seed=seed,context_frames=context_frames,motion_score=motion_score,reused=False); previous_state=entry_to_state(entry); entries.append(entry)
|
||||
if storage_controller is not None: storage_controller.commit_chunk(entry, position=sequence_index)
|
||||
retained_frames+=int(chunk_plan["net_frames"])
|
||||
sampling_reports.append(f"chunk {sequence_index+1}/{chunks}: seed={seed}, frames={chunk_plan['total_frames']}, trim={chunk_plan['trim_frames']}, retained_total={retained_frames}, context={context_frames} ({reason}), motion={motion_score:.6f}, "+(f"interop=emitted actual_prefix={CONTINUUM_ACTUAL_PREFIX_STEPS} consumer=not_observable" if context_before is not None else "interop=not_emitted"))
|
||||
del sampled,latent,conditioning,chunk_model
|
||||
if len(entries)!=chunks: raise SequenceRuntimeError(f"internal sequence length mismatch: expected {chunks}, got {len(entries)}")
|
||||
if latent_only:
|
||||
last_state=entry_to_state(entries[-1]); parent_id=session.get("session_id") if session is not None else None
|
||||
settings={"continuity":continuity,"audio_continuity":bool(audio_continuity),"exact_total_duration":False,"prompt_mode":plan["mode"],"base_seed":int(base_seed),"reroll_nonce":int(reroll_nonce),"diagnostics_mode":diagnostics_mode,"initial_state_source":initial_state is not None,"latent_first":True}
|
||||
new_session=make_session(chunks=entries,width=width,height=height,chunk_seconds=chunk_seconds,identity_hash=assets.identity_hash,model_fingerprint_value=current_model_fingerprint,parent_session_id=parent_id,reroll_from_chunk=int(reroll_from_chunk),settings=settings)
|
||||
report_lines=[f"H3 Continuum V3 {PACKAGE_VERSION}",prompt_plan_report(plan),"Decode: external ComfyUI Core VAE nodes; full raw AV chunks retained.",accelerators,"Execution: conditioning precomputed; single call-local MODEL clone per chunk; no internal VAE decode.",*reuse_notes]
|
||||
settings={"continuity":continuity,"audio_continuity":bool(audio_continuity),"exact_total_duration":False,"prompt_mode":plan["mode"],"conditioning_mode":conditioning_mode,"base_seed":int(base_seed),"reroll_nonce":int(reroll_nonce),"diagnostics_mode":diagnostics_mode,"initial_state_source":initial_state is not None,"latent_first":True,"first_frame_hash":assets.first_frame_hash,"last_frame_hash":assets.last_frame_hash,"reference_contract":reference_assets.contract if reference_assets is not None else None}
|
||||
new_session=make_session(chunks=entries,width=width,height=height,chunk_seconds=chunk_seconds,identity_hash=sequence_identity_hash,model_fingerprint_value=current_model_fingerprint,parent_session_id=parent_id,reroll_from_chunk=int(reroll_from_chunk),settings=settings)
|
||||
report_lines=[f"H3 Continuum V3 {PACKAGE_VERSION}",f"Conditioning mode: {conditioning_mode_label(conditioning_mode)}.",prompt_plan_report(plan),"Decode: external ComfyUI Core VAE nodes; full raw AV chunks retained.",accelerators,"Execution: conditioning precomputed; single call-local MODEL clone per chunk; no internal VAE decode.",*reuse_notes]
|
||||
if diagnostics_mode!=DIAGNOSTICS_OFF: report_lines.extend(sampling_reports)
|
||||
report_lines.extend([session_summary(new_session),f"Output: {len(entries)} raw AV latent chunk(s); connect Core VAE Decode nodes, then H3 Continuum Assemble V3."])
|
||||
return entries,last_state,new_session,"\n".join(report_lines)
|
||||
@@ -136,8 +165,8 @@ def run_sequence(*,model:Any,clip:Any,video_vae:Any,audio_vae:Any,sampler:Any,si
|
||||
if exact_total_duration:
|
||||
target_frames=int(round(chunks*chunk_seconds*FPS)); images,audio,duration_report=enforce_total_frames(images,audio,target_frames=target_frames,preserve_final_frame=last_frame is not None)
|
||||
last_state=entry_to_state(entries[-1]); parent_id=session.get("session_id") if session is not None else None
|
||||
settings={"continuity":continuity,"audio_continuity":bool(audio_continuity),"exact_total_duration":bool(exact_total_duration),"prompt_mode":plan["mode"],"base_seed":int(base_seed),"reroll_nonce":int(reroll_nonce),"diagnostics_mode":diagnostics_mode,"initial_state_source":initial_state is not None}
|
||||
new_session=make_session(chunks=entries,width=width,height=height,chunk_seconds=chunk_seconds,identity_hash=assets.identity_hash,model_fingerprint_value=current_model_fingerprint,parent_session_id=parent_id,reroll_from_chunk=int(reroll_from_chunk),settings=settings)
|
||||
settings={"continuity":continuity,"audio_continuity":bool(audio_continuity),"exact_total_duration":bool(exact_total_duration),"prompt_mode":plan["mode"],"base_seed":int(base_seed),"reroll_nonce":int(reroll_nonce),"diagnostics_mode":diagnostics_mode,"initial_state_source":initial_state is not None,"first_frame_hash":assets.first_frame_hash,"last_frame_hash":assets.last_frame_hash,"reference_contract":reference_assets.contract if reference_assets is not None else None}
|
||||
new_session=make_session(chunks=entries,width=width,height=height,chunk_seconds=chunk_seconds,identity_hash=sequence_identity_hash,model_fingerprint_value=current_model_fingerprint,parent_session_id=parent_id,reroll_from_chunk=int(reroll_from_chunk),settings=settings)
|
||||
decoded_gib=float(images.shape[0])*float(width)*float(height)*3.0*4.0/(1024.0**3)
|
||||
report_lines=[f"H3 Continuum V2 {PACKAGE_VERSION}",prompt_plan_report(plan),f"Seam correction: {seam_correction}.",accelerators,"Execution: conditioning precomputed; single call-local MODEL clone per chunk; decode deferred until sampling completed.",*reuse_notes]
|
||||
if diagnostics_mode!=DIAGNOSTICS_OFF: report_lines.extend([f"Decode RAM estimate: {decode_estimate_gib:.2f} GiB including transient headroom"+(f"; available at start {available_ram_gib:.2f} GiB." if available_ram_gib is not None else "."),*sampling_reports,*decode_reports])
|
||||
@@ -151,4 +180,4 @@ _run_sequence_v300 = run_sequence
|
||||
|
||||
|
||||
def run_sequence(*args, **kwargs):
|
||||
return _run_sequence_with_hardening(_run_sequence_v300, args, kwargs)
|
||||
return _run_sequence_with_hardening(_run_sequence_v300, args, kwargs)
|
||||
|
||||
+335
-3
@@ -16,6 +16,33 @@ from .assembly import H3ContinuumAssembleV3
|
||||
from .plan import make_assembly_plan
|
||||
|
||||
|
||||
REGENERATE_AUTO = "Auto"
|
||||
REGENERATE_OPTIONS = (REGENERATE_AUTO,) + tuple(
|
||||
f"Chunk {index}" for index in range(1, 17)
|
||||
)
|
||||
|
||||
|
||||
def _regenerate_from_value(value, *, chunks: int) -> int:
|
||||
if isinstance(value, str):
|
||||
text = value.strip()
|
||||
if text == REGENERATE_AUTO:
|
||||
resolved = 0
|
||||
elif text.startswith("Chunk ") and text[6:].isdigit():
|
||||
resolved = int(text[6:])
|
||||
elif text.isdigit():
|
||||
resolved = int(text)
|
||||
else:
|
||||
raise ValueError(f"unknown Regenerate From value: {value!r}")
|
||||
else:
|
||||
resolved = int(value)
|
||||
if resolved < 0 or resolved > int(chunks):
|
||||
raise ValueError(
|
||||
f"Regenerate From Chunk {resolved} is outside the configured "
|
||||
f"1-{int(chunks)} chunk range"
|
||||
)
|
||||
return resolved
|
||||
|
||||
|
||||
class H3ContinuumAdvancedV3:
|
||||
DESCRIPTION = (
|
||||
"Optional continuation, session, reroll, and diagnostics settings for V3."
|
||||
@@ -116,8 +143,8 @@ class H3ContinuumSamplerV3:
|
||||
"VAE",
|
||||
{
|
||||
"tooltip": (
|
||||
"Used only to encode first/last-frame conditioning; "
|
||||
"V3 never decodes with it."
|
||||
"Used only to encode image conditioning. T2VA does "
|
||||
"not use it; V3 never decodes with it."
|
||||
),
|
||||
},
|
||||
),
|
||||
@@ -168,7 +195,10 @@ class H3ContinuumSamplerV3:
|
||||
),
|
||||
},
|
||||
"optional": {
|
||||
"first_frame": ("IMAGE",),
|
||||
"first_frame": (
|
||||
"IMAGE",
|
||||
{"tooltip": "Optional. Leave image inputs disconnected for T2VA."},
|
||||
),
|
||||
"prompt_overrides": ("H3_CONTINUUM_CLIP_OVERRIDES",),
|
||||
"advanced": ("H3_CONTINUUM_ADVANCED_V3",),
|
||||
},
|
||||
@@ -208,6 +238,7 @@ class H3ContinuumSamplerV3:
|
||||
first_frame=None,
|
||||
prompt_overrides=None,
|
||||
advanced=None,
|
||||
reference_assets=None,
|
||||
):
|
||||
if prompt_overrides is not None and not isinstance(prompt_overrides, dict):
|
||||
raise TypeError(
|
||||
@@ -277,6 +308,7 @@ class H3ContinuumSamplerV3:
|
||||
sequence_prompt=sequence_prompt,
|
||||
show_preview=advanced_values["show_preview"],
|
||||
latent_only=True,
|
||||
reference_assets=reference_assets,
|
||||
**clip_prompt_inputs,
|
||||
)
|
||||
|
||||
@@ -295,13 +327,313 @@ class H3ContinuumSamplerV3:
|
||||
return video_latents, audio_latents, assembly_plan, result
|
||||
|
||||
|
||||
class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
|
||||
"""Stable single-entry sampler UI for V3.2 and later releases."""
|
||||
|
||||
DEPRECATED = False
|
||||
CATEGORY = CATEGORY
|
||||
DESCRIPTION = (
|
||||
"Production H3 Continuum sampler with first/last-frame or image-reference conditioning and "
|
||||
"ComfyUI-native advanced widgets. Video/audio VAE decoding remains in "
|
||||
"ComfyUI Core."
|
||||
)
|
||||
SEARCH_ALIASES = [
|
||||
"H3 Continuum Sampler V3.2",
|
||||
"H3 Continuum Production",
|
||||
"MiniMax H3 long video",
|
||||
]
|
||||
RETURN_TYPES = (
|
||||
"LATENT",
|
||||
"LATENT",
|
||||
"H3_CONTINUUM_ASSEMBLY_PLAN",
|
||||
"STRING",
|
||||
)
|
||||
RETURN_NAMES = (
|
||||
"video_latents",
|
||||
"audio_latents",
|
||||
"assembly_plan",
|
||||
"status",
|
||||
)
|
||||
|
||||
@classmethod
|
||||
def INPUT_TYPES(cls):
|
||||
advanced = {"advanced": True}
|
||||
return {
|
||||
"required": {
|
||||
"model": ("MODEL",),
|
||||
"clip": ("CLIP",),
|
||||
"video_vae": (
|
||||
"VAE",
|
||||
{
|
||||
"tooltip": (
|
||||
"Used only to encode image conditioning. T2VA does "
|
||||
"not use it; Continuum never decodes with it."
|
||||
),
|
||||
},
|
||||
),
|
||||
"sampler": ("SAMPLER",),
|
||||
"sigmas": ("SIGMAS",),
|
||||
"sequence_prompt": (
|
||||
"STRING",
|
||||
{
|
||||
"forceInput": True,
|
||||
"display_name": "Sequence Prompt",
|
||||
"tooltip": (
|
||||
"Connect one Text (Multiline) for the complete sequence."
|
||||
),
|
||||
},
|
||||
),
|
||||
"prompt_mode": (
|
||||
PROMPT_FORMAT_OPTIONS,
|
||||
{
|
||||
"default": PROMPT_FORMAT_OPTIONS[0],
|
||||
"display_name": "Prompt Format",
|
||||
**advanced,
|
||||
},
|
||||
),
|
||||
"chunks": ("INT", {"default": 3, "min": 1, "max": 16, "step": 1}),
|
||||
"chunk_seconds": (
|
||||
"FLOAT",
|
||||
{"default": 5.0, "min": 4.0, "max": 15.0, "step": 0.1},
|
||||
),
|
||||
"width": (
|
||||
"INT",
|
||||
{"default": 1344, "min": 32, "max": 16384, "step": 32},
|
||||
),
|
||||
"height": (
|
||||
"INT",
|
||||
{"default": 768, "min": 32, "max": 16384, "step": 32},
|
||||
),
|
||||
"continuity": (
|
||||
V2_CONTINUITY_OPTIONS,
|
||||
{"default": V2_CONTINUITY_OPTIONS[1]},
|
||||
),
|
||||
"base_seed": (
|
||||
"INT",
|
||||
{
|
||||
"default": 0,
|
||||
"min": 0,
|
||||
"max": 0xFFFFFFFFFFFFFFFF,
|
||||
"control_after_generate": True,
|
||||
},
|
||||
),
|
||||
"audio_continuity": (
|
||||
"BOOLEAN",
|
||||
{"default": True, "advanced": True},
|
||||
),
|
||||
"diagnostics": (
|
||||
DIAGNOSTICS_OPTIONS,
|
||||
{
|
||||
"default": DIAGNOSTICS_OPTIONS[0],
|
||||
"display_name": "Report Detail",
|
||||
"advanced": True,
|
||||
},
|
||||
),
|
||||
"reroll_from_chunk": (
|
||||
REGENERATE_OPTIONS,
|
||||
{
|
||||
"default": REGENERATE_AUTO,
|
||||
"display_name": "Regenerate From",
|
||||
"advanced": True,
|
||||
"tooltip": (
|
||||
"Auto resumes the longest compatible saved prefix. "
|
||||
"Choosing a chunk reuses earlier chunks and regenerates "
|
||||
"that chunk and everything after it."
|
||||
),
|
||||
},
|
||||
),
|
||||
"reroll_nonce": (
|
||||
"INT",
|
||||
{
|
||||
"default": 0,
|
||||
"min": 0,
|
||||
"max": 0xFFFFFFFF,
|
||||
"step": 1,
|
||||
"advanced": True,
|
||||
},
|
||||
),
|
||||
"strict_compatibility": (
|
||||
"BOOLEAN",
|
||||
{"default": True, "advanced": True},
|
||||
),
|
||||
"debug": (
|
||||
"BOOLEAN",
|
||||
{"default": False, "advanced": True},
|
||||
),
|
||||
"show_preview": (
|
||||
"BOOLEAN",
|
||||
{"default": True, "advanced": True},
|
||||
),
|
||||
"run_storage": (
|
||||
("Off", "Save + Auto Resume"),
|
||||
{
|
||||
"default": "Off",
|
||||
"display_name": "Run Storage",
|
||||
"advanced": True,
|
||||
"tooltip": "Atomically save raw AV chunks and resume a compatible Run Name.",
|
||||
},
|
||||
),
|
||||
"run_name": (
|
||||
"STRING",
|
||||
{
|
||||
"default": "",
|
||||
"display_name": "Run Name (Required for Storage)",
|
||||
"advanced": True,
|
||||
"tooltip": "Enter a stable name for this saved run. Compatible chunks are selected automatically.",
|
||||
},
|
||||
),
|
||||
"reference_size": (
|
||||
("Match Output", "Max Identity"),
|
||||
{
|
||||
"default": "Match Output",
|
||||
"display_name": "Reference Size",
|
||||
"advanced": True,
|
||||
"tooltip": "Match Output is the practical default; Max Identity preserves more reference detail.",
|
||||
},
|
||||
),
|
||||
"project_id": (
|
||||
"STRING",
|
||||
{
|
||||
"default": "",
|
||||
"display_name": "Auto Resume ID (Automatic)",
|
||||
"advanced": True,
|
||||
"tooltip": "Created automatically and saved with the workflow. It identifies which saved chunks can be resumed.",
|
||||
},
|
||||
),
|
||||
},
|
||||
"optional": {
|
||||
"first_frame": (
|
||||
"IMAGE",
|
||||
{"tooltip": "Optional. Leave all image inputs disconnected for T2VA."},
|
||||
),
|
||||
"last_frame": ("IMAGE",),
|
||||
"reference_image_1": ("IMAGE",),
|
||||
"reference_image_2": ("IMAGE",),
|
||||
},
|
||||
"hidden": {
|
||||
"prompt": "PROMPT",
|
||||
"unique_id": "UNIQUE_ID",
|
||||
},
|
||||
}
|
||||
|
||||
def run(
|
||||
self,
|
||||
model,
|
||||
clip,
|
||||
video_vae,
|
||||
sampler,
|
||||
sigmas,
|
||||
sequence_prompt,
|
||||
prompt_mode,
|
||||
chunks,
|
||||
chunk_seconds,
|
||||
width,
|
||||
height,
|
||||
continuity,
|
||||
base_seed,
|
||||
audio_continuity,
|
||||
diagnostics,
|
||||
reroll_from_chunk,
|
||||
reroll_nonce,
|
||||
strict_compatibility,
|
||||
debug,
|
||||
show_preview,
|
||||
run_storage="Off",
|
||||
run_name="",
|
||||
reference_size="Match Output",
|
||||
project_id="",
|
||||
first_frame=None,
|
||||
last_frame=None,
|
||||
reference_image_1=None,
|
||||
reference_image_2=None,
|
||||
prompt_overrides=None,
|
||||
prompt=None,
|
||||
unique_id=None,
|
||||
):
|
||||
from ..reference import prepare_reference_assets
|
||||
regenerate_from = _regenerate_from_value(
|
||||
reroll_from_chunk,
|
||||
chunks=int(chunks),
|
||||
)
|
||||
reference_assets = prepare_reference_assets(
|
||||
reference_image_1=reference_image_1,
|
||||
reference_image_2=reference_image_2,
|
||||
output_width=int(width),
|
||||
output_height=int(height),
|
||||
size_mode=reference_size,
|
||||
)
|
||||
if reference_assets is not None and (first_frame is not None or last_frame is not None):
|
||||
raise ValueError(
|
||||
"V3.2 Reference Images cannot be combined with First Frame or Last Frame"
|
||||
)
|
||||
|
||||
def execute():
|
||||
return super(H3ContinuumSamplerProduction, self).run(
|
||||
model=model,
|
||||
clip=clip,
|
||||
video_vae=video_vae,
|
||||
sampler=sampler,
|
||||
sigmas=sigmas,
|
||||
sequence_prompt=sequence_prompt,
|
||||
prompt_mode=prompt_mode,
|
||||
chunks=chunks,
|
||||
chunk_seconds=chunk_seconds,
|
||||
width=width,
|
||||
height=height,
|
||||
continuity=continuity,
|
||||
base_seed=base_seed,
|
||||
first_frame=first_frame,
|
||||
prompt_overrides=prompt_overrides,
|
||||
reference_assets=reference_assets,
|
||||
advanced={
|
||||
"audio_continuity": bool(audio_continuity),
|
||||
"diagnostics": diagnostics,
|
||||
"reroll_from_chunk": regenerate_from,
|
||||
"reroll_nonce": int(reroll_nonce),
|
||||
"strict_compatibility": bool(strict_compatibility),
|
||||
"debug": bool(debug),
|
||||
"show_preview": bool(show_preview),
|
||||
"last_frame": last_frame,
|
||||
},
|
||||
)
|
||||
|
||||
if run_storage == "Off":
|
||||
video_latents, audio_latents, assembly_plan, result = execute()
|
||||
return (
|
||||
video_latents,
|
||||
audio_latents,
|
||||
assembly_plan,
|
||||
str(result["report"]),
|
||||
)
|
||||
if run_storage != "Save + Auto Resume":
|
||||
raise ValueError(f"unknown Run Storage mode: {run_storage!r}")
|
||||
from ..run_storage import resolve_run_storage_name, run_storage_scope
|
||||
storage_name = resolve_run_storage_name(
|
||||
project_id=project_id,
|
||||
legacy_run_name=run_name,
|
||||
)
|
||||
with run_storage_scope(
|
||||
storage_name, prompt=prompt, unique_id=unique_id
|
||||
) as storage:
|
||||
video_latents, audio_latents, assembly_plan, result = execute()
|
||||
result = dict(result)
|
||||
report = str(result["report"]) + "\n" + storage.summary(
|
||||
detailed=diagnostics == DIAGNOSTICS_OPTIONS[-1]
|
||||
)
|
||||
result["report"] = report
|
||||
storage.finalize(session=result["session"], report=report)
|
||||
return video_latents, audio_latents, assembly_plan, report
|
||||
|
||||
|
||||
NODE_CLASS_MAPPINGS = {
|
||||
"H3ContinuumSamplerProduction": H3ContinuumSamplerProduction,
|
||||
"H3ContinuumSamplerV3": H3ContinuumSamplerV3,
|
||||
"H3ContinuumAdvancedV3": H3ContinuumAdvancedV3,
|
||||
"H3ContinuumAssembleV3": H3ContinuumAssembleV3,
|
||||
}
|
||||
|
||||
NODE_DISPLAY_NAME_MAPPINGS = {
|
||||
"H3ContinuumSamplerProduction": "H3 Continuum Sampler V3.2",
|
||||
"H3ContinuumSamplerV3": "H3 Continuum Sampler V3",
|
||||
"H3ContinuumAdvancedV3": "H3 Continuum Advanced V3",
|
||||
"H3ContinuumAssembleV3": "H3 Continuum Assemble V3",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
"""Package version and public schema identifiers."""
|
||||
|
||||
PACKAGE_VERSION = "3.0.1"
|
||||
PACKAGE_VERSION = "3.2.1"
|
||||
STATE_SCHEMA_VERSION = 1
|
||||
PLAN_SCHEMA_VERSION = 1
|
||||
PUBLIC_API_VERSION = 3
|
||||
|
||||
Reference in New Issue
Block a user