h3-relay Introduction
h3-relay provides steerable, resumable MiniMax H3 video-and-audio generation in ComfyUI. It helps you build a sequence one shot at a time, review the results, and apply optional finishing work only after you are happy with the underlying footage.
Instead of treating an entire movie as one large generation, h3-relay separates the work into manageable stages:
- Generate a native H3 shot.
- Review or reroll that shot.
- Enhance approved footage with H3 Ultimate or LTX 2.5.
- Interpolate frames if you want smoother playback.
- Assemble the finished sequence.
This is useful when you want to avoid spending additional processing time on an upscale of a shot you will later discard. Accepted results are saved to disk, allowing unchanged work to be reused rather than regenerated.
The extension also includes workflows for:
- Character replacement: use character references to guide source-aligned video editing.
- Person removal: remove a tracked person using a dedicated adapter and a clean first frame.
- Video preparation: normalize source footage for H3-compatible editing.
- Longer sequences: process shots as separate jobs to keep memory use more predictable.
Compatibility matters: the native toolkit workflows require ComfyUI 0.37.0 or later. The qualified toolkit environment uses Linux, an RTX 4090, ComfyUI commit
79be670e2d9be63e238785af307369d2b9039ed1, and frontend1.53.6. Experimental FastH3 has additional requirements and separate validation limits.
How h3-relay Works
Think of it as an editing timeline with saved checkpoints
Imagine making a short film from several clips. You would normally approve the action and composition before spending time on final polish. h3-relay follows the same approach.
Start sequence → Generate shot 1 → Generate shot 2 → …
↓ ↓
Optional enhance Optional enhance
↓ ↓
Optional smooth Optional smooth
└────── Assemble ──────┘
Each accepted H3 shot has a saved checkpoint containing its generated video-and-audio information. These checkpoints allow you to resume work and reuse approved material.
Generation and finishing are separate
The graph has two distinct streams:
| Connection | What it carries |
|---|---|
sequence | Native H3 continuation state: the information used to generate subsequent shots. |
enhanced | Finishing state used by H3 Ultimate, LTX, interpolation, and assembly. |
The important consequence is that the next H3 shot continues from accepted raw H3 work, not from an upscaled or interpolated version.
You can therefore review native 480p footage before loading finishing models.
Overlap helps connect shots
For continuation, H3 carries a short section of previous video and audio into the next generation window. Think of this as giving the model the end of the previous clip so it has context for what should happen next.
The supported h3_overlap_frames values are:
- 18 frames: the default.
- 35 frames
- 52 frames
- 69 frames
Larger overlaps provide more matched visual and audio history, but leave less room for new footage within the same generation window. The allowed values follow H3’s required temporal structure; arbitrary frame counts are not supported.
Finishing stages manage their own overlap and remove duplicated prefixes before publishing their segments.
Saved results are checked before reuse
h3-relay uses disk-backed records identified by their inputs and model settings. Before restoring accepted results, it checks their recorded integrity.
In everyday terms:
- Unchanged inputs can reuse an existing result.
- Rerolling a shot creates a new revision.
- Finishing work derived from that changed revision must be rebuilt.
- A missing or mismatched checkpoint is rejected rather than silently treated as valid.
Staged execution keeps long sequences manageable
The Assemble node provides Run staged · bounded RAM.
This action reads the visible workflow and queues generation, enhancement, interpolation, and assembly as separate jobs. Between jobs, a release barrier clears ComfyUI’s executor cache and unloads models.
This trades some model-reloading time for more predictable memory use. If a stage fails, dependent stages are not queued.
Use staged execution for long Relay shot sequences. Ordinary ComfyUI queueing remains available, but runs the graph as one larger prompt.
This bounded-memory behavior does not describe every workflow in the extension: Person Remover, for example, uses ordinary graph execution and its RAM use grows with clip length.
h3-relay Features
Reviewable, resumable shot generation
The main generation nodes include:
- Sequence Start
- Generate Shot
- Assemble Raw Sequence
- Assemble
Use Assemble Raw Sequence when you want a finished native H3 chain without enhancement or interpolation.
A practical approach is to generate one shot, inspect its motion and audio, and only then continue or finish it.
Native ComfyUI toolkit workflows
The reusable toolkit separates source preparation, window planning, history management, mask conversion, assembly, and durable review into individual nodes.
ComfyUI’s native nodes remain responsible for model loading, reference conditioning, guides, sampling, VAE encoding and decoding, loops, and ordinary video saving.
Available examples include:
- Character Swap: defaults to the V1.5 character LoRA and FL2V Turbo 8-step adapter.
- Person Removal: uses Person Remover V1, a clean first frame, native SAM tracking, and durable window rerolls.
See the toolkit usage guide and node contracts and migration guide.
H3 Ultimate 2× enhancement
H3 Ultimate 2× Enhance turns an accepted H3 shot into a doubled-resolution result using the learned H3 latent upscaler and tiled, one-step FastH3 refinement.
For example:
832 × 480 → 1664 × 960
The node:
- Reuses the connected FastH3 VSA H3 model bundle.
- Reuses the accepted shot’s global and scene prompts.
- Reconnects up to nine H3 reference inputs.
- Preserves the necessary history during refinement.
- Removes the continuation prefix before publishing the enhanced segment.
- Connects directly to another Ultimate node, Interpolate, or Assemble.
Tile width, height, and overlap are maximum requests, not fixed output dimensions. The node calculates the doubled canvas and clamps tile settings to fit. For example, a 1024 × 1024 tile request on a 1664 × 960 canvas becomes 1024 × 960.
The FastH3 finishing defaults are:
| Setting | Default |
|---|---|
| Temporal window | 136 frames |
| Temporal overlap | 17 frames |
| Spatial tile | 1024 × 1024 |
| Spatial overlap | 128 pixels |
These are finishing settings, not additional raw-generation steps.
External dependency: this feature requires Comfyui-MMH3-UltimateUpscale and its H3 latent-upscaler model. Other Relay nodes remain usable without that pack.
The external engine processes overlapping time chunks and spatial tiles rather than sampling the entire high-resolution clip at once. Its H3 path carries the audio latent through unchanged. This helps control memory use, but does not establish that Relay’s complete workflow has been validated on every smaller GPU.
LTX 2.5 enhancement
LTX 2× Enhance offers another finishing path.
It combines:
- A learned latent upscaler that expands the video representation by 2×.
- A pixel-spatial IC-LoRA that guides generative refinement from the original low-resolution video.
This is one 2× pipeline, not two successive doublings.
Because the refinement is generative, you should inspect fine details and continuity rather than assume every source detail will remain unchanged. See LTX upscaling guidance for window-size explanations, the validated RTX 4090 preset, and fidelity limitations.
Frame interpolation
Interpolate creates additional frames for smoother playback.
- Bypass all interpolation nodes to assemble enhanced footage at 24 fps.
- In the three-shot FastH3 example, enable all three interpolation nodes for 48 fps.
Interpolation processes overlapping source chunks, using 48 source frames by default, and encodes each chunk immediately. This avoids keeping the entire high-resolution float-frame sequence in system RAM.
For RIFE, chunk boundaries preserve the same adjacent-frame calculations as a single full pass. Changing chunk size is a memory-management adjustment and does not invalidate an otherwise identical cached interpolation result.
Flexible sampling for standard H3
Sequence Start exposes ComfyUI’s native sampler and BasicScheduler lists independently.
The default combination is:
- Sampler: Euler
- Scheduler:
beta57 - Spectrum: enabled
beta57 uses the exact manual H3 curve at 16 steps and an alpha 0.5 / beta 0.7 curve otherwise.
You can mix other available samplers and schedulers for standard H3 bundles. These controls affect generation behavior, so treat changes as creative experiments rather than guaranteed improvements.
The locked FastH3 profile overrides these controls.
Model bundles and advanced controls
h3-relay passes related model components through a single typed connection, reducing repeated wiring across shots.
Relevant nodes include:
| Node | Purpose |
|---|---|
| H3 Hybrid Model Loader / H3 Model Loader | Supply H3 model bundles. |
| LTX Upscale Model Loader | Supply the LTX finishing bundle. |
| Apply Model LoRA | Apply an adapter to a supported bundle. |
| Attention Backend | Select an attention implementation available in your environment. |
| Pack LTX Model | Convert a custom native ComfyUI LTX stack into a Relay bundle. |
Relay’s LoRA and attention nodes update the bundle’s cache identity automatically.
The attention selector only shows registered backends. For example, Sage appears only when its optional backend is available.
Advanced cache controls have specific purposes:
manual_cache_revision: update this when replacing model contents without changing filenames.cache_identityon Pack LTX Model: change this whenever the custom native model stack changes.
Accepted Raw Latent bridge
Accepted Raw Latent exposes an approved shot as ComfyUI’s standard nested H3 LATENT type.
A latent is the model’s internal representation of video and audio before decoding into ordinary media. This bridge lets compatible finishers reuse reviewed H3 work without hard-coded cache paths or regeneration.
Choose a sequence position, or use -1 for the latest accepted shot. Missing shots, absent hashes, or mismatched content are rejected.
Cache management, previews, and publishing
New Relay generation and finishing runs store intermediate results under:
ComfyUI/user/__h3_relay_cache
Browser previews use hard-linked files in ComfyUI’s temp directory. Previewing a result does not automatically publish it to your output folder.
To publish footage:
- Connect a native Save Video node to a stage’s
VIDEOoutput. - Use Assemble to publish the final movie under
output/.
Cache Manager reports usage and can prune superseded rerolls while retaining current metadata references and the configured recent revisions.
Legacy run names continue using their established output/h3_chains and output/h3_relay locations.
Encoding quality without repeating generation
output_crf controls the cached H.264 segment’s encoding quality, not the model’s creative generation.
- Lower CRF generally means higher image quality and larger files.
- Higher CRF generally means smaller files and more compression.
Changing output_crf creates a derived encoding without repeating inference. H3 retains a fixed internal source segment, while LTX and interpolation retain CRF-18 masters.
Audio-aware previews
Raw H3 checkpoints keep picture and lossless generated WAV audio separately internally. Relay combines them into a dedicated preview MP4 without re-encoding the H3 picture.
As a result, the raw VIDEO output and connected core Save Video nodes include audio.
Character-swap video preparation
The included helpers are:
- H3 Prepare Video · Auto Size & Length
- H3 Trim Output to Source Length
Some workflows title the preparation node Resolution budget & output duration.
The preparation node runs on CPU and:
- Normalizes footage to 24 fps.
- Preserves aspect ratio with a small center crop to a 32-pixel grid.
- Uses pixel budgets of 500,000 for
480or 1,000,000 for768. - Keeps the full clip when duration is
0. - Uses the nearest supported
17n+5frame length for positive durations without extending the actual source.
reference_frames may include repeated tail padding for H3. source_frames is the unpadded count: connect it to the windowed-edit node’s source_count, or to the trim node after a single-window decode.
These helpers require FFmpeg, FFprobe, and ComfyUI’s VIDEO API, but do not load generation models or submit generation jobs.
h3-relay Models and Profiles
h3-relay connects several model families rather than providing one universal model. Consult MODELS.md for exact filenames and the reference configuration.
| Model or profile | Role | When to use it |
|---|---|---|
| MiniMax H3 FL2VA / Ref2VA | Standard H3 generation and reference-conditioned workflows. | Use the standard profile as the fallback for reference work and continuation when experimental FastH3 behavior is unsuitable. |
| FastH3 VSA checkpoint | Experimental accelerated H3 generation using Kijai’s INT8 ConvRot repack of FastVideo’s step-1300 checkpoint. | Use the dedicated examples to evaluate the locked four-forward generation profile. |
| H3 latent 2× upscaler | Learned spatial enlargement for H3 Ultimate finishing. | Use with the external MMH3 Ultimate Upscale pack and Relay’s Ultimate node. |
| LTX 2.5 finishing stack | Alternative generative 2× enhancement. | Use the LTX finishing branch for approved raw shots. |
| Compatible interpolation checkpoint, such as RIFE | Creates intermediate frames. | Use when smoother playback is wanted; unnecessary for 24 fps assembly. |
| V1.5 character LoRA + FL2V Turbo 8-step adapter | Default adapters in the native toolkit Character Swap example. | Use that workflow for character-reference editing. |
| Person Remover V1 LoRA | Dedicated person-removal adapter for standard H3 Ref2VA. | Use with a clean first frame and tracked person mask. Its public model release is pending. |
H3 also needs its text encoder and video/audio VAEs. The LTX bundle includes its model, VAE, latent upscaler, text encoder, and required LoRAs.
Experimental FastH3 limitations
FastH3 VSA Profile owns its inference settings:
- Euler sampler and simple scheduler.
- Four transformer forwards.
- CFG 1 through
BasicGuider. - Video/audio shifts of 12/3.
- Spectrum disabled.
- VSA with 10% video-cube keep across the denoising range.
Standard h3_steps and Sequence Start sampler settings are overridden by this profile. Applying another Relay LoRA or Attention Backend after it is rejected.
Important limitations:
- FastVideo documents the preview checkpoint as T2VA-only.
- Reference conditioning and sliding continuation are experimental.
- Stock ComfyUI alone is insufficient.
- Validation used Linux, an RTX 4090, the official
comfy-kitchen==0.2.33wheel, and the pinned VSA-capable ComfyUI commit. - Windows GPU inference remains unvalidated.
- Upstream Sol-Attention edge-case tests have known failures.
See the FastH3 environment reference and validation record.
Model licensing
h3-relay does not redistribute model weights. Its GPL-3.0 source-code license does not grant permission to use MiniMax H3, LTX, RIFE, text encoders, or other model weights.
Review each upstream model license and any authorization requirements, especially before commercial use.
h3-relay Person Removal and Windowed Editing
Person Remover V1
The Person Remover V1 workflow automates short, source-aligned removal clips.
A typical session is:
- Supply a short, single-shot 24 fps video whose dimensions are divisible by 32.
- Supply a clean version of its first frame, with the same dimensions and framing. Create this externally using an image editor or image model.
- Describe the target person in CLIP Text Encode.
- Inspect the green SAM3 tracking mask before rendering.
- Start with the documented baseline: B2000 LoRA strength 1, 12 steps, and 22-frame windows.
- Review completed windows in the preview grid. Hover to play, or tap on touch screens.
The graph uses er_sde / simple, CFG 1, and native Select CLIP Device → gpu:0 for Qwen. It carries generated boundary anchors and 18 frames of video/audio history, trims overlaps, and preserves the source frame count.
Review controls behave differently:
| Action | Behavior |
|---|---|
| Run | Reuses matching current results. |
| Reroll | Keeps earlier windows and rebuilds the selected window onward. Enter a seed first for an exact value; otherwise leave it unchanged for a fresh seed. |
| Regenerate all | Rebuilds every window with new seeds. |
Prepared sources, exact generated frames, and audio persist under:
ComfyUI/output/__h3_removal_cache/
Unchanged rerolls reuse SAM detection and tracking, including after a server restart. Cache files remain on the serving machine and are not embedded in saved workflow JSON.
Limitations: the adapter’s public release is pending; 22-frame windows are the validated default; larger windows are experimental. The model regenerates whole frames, so backgrounds, motion, and joins still need review. Output is silent by default, but original audio can be connected to the final Create Video node.
See the complete removal guide and validation evidence.
Windowed Character Swap
H3 Relay Windowed Edit · Character Swap reuses the durable checkpoints, preview grid, prefix reuse, and reroll controls from Person Remover.
Unlike removal, it keeps the character image and original-video Ref2VA conditioning in every window rather than pinning the source person’s pixels as a removal guide. Window size and history are independently adjustable.
See the windowed editing guide.
What's New with h3-relay
The supplied documentation describes the following changes, but does not provide a complete version-by-version release history.
| Documented change | Why it matters |
|---|---|
| Native toolkit workflows and canonical package consolidation | Source preparation, history, review, and assembly can be combined with native ComfyUI nodes. Legacy Relay identifiers remain available. |
| Bounded-RAM staged execution | Long shot sequences can run as separate jobs with model release between stages. |
| Accepted Raw Latent bridge | Reviewed H3 results can be reused by compatible latent-aware finishers. |
| Integrated H3 Ultimate 2× finishing | Ultimate enhancement participates in Relay’s staged, cached workflow. |
| Streamed interpolation | High-resolution interpolation avoids retaining the entire float-frame clip in RAM. |
| Protected cache and explicit publishing | Intermediates and browser previews are separated from published outputs. |
Per-stage output_crf controls | Compression changes no longer require repeating model inference. |
| Independent sampler and scheduler controls | Standard H3 workflows have more explicit sampling choices, alongside separate Spectrum control. |
| Experimental FastH3 profile and tiered examples | You can test raw generation, one-shot finishing, and multi-shot continuation separately. |
| Windowed removal and character editing | Completed windows can be inspected, reused, and selectively rerolled. |
| Integrated video-preparation helpers | Existing workflows no longer need the separate labs-video-prep package. |
The validation record also documents live RTX 4090 staged-cache and reference-output checks for version 0.1.0. Automated CPU tests do not replace GPU generation or audiovisual-output validation.
Troubleshooting h3-relay
Ultimate enhancement reports missing MMH3 classes
- Confirm that the external MMH3 Ultimate Upscale pack is available in your ComfyUI environment.
- Restart ComfyUI if that dependency was recently added or changed.
- Check that the required H3 latent-upscaler model is available.
- Use a
.safetensorsmodel: the external pack rejects pickle-based.pth,.pt, and.ckptupscalers. - Follow the missing-class details in the error message.
Other Relay nodes remain available without this dependency. A previously cached, verified Ultimate result may also be restored without loading the external engine.
FastH3 reports missing VSA support or CUDA kernels
- Compare your environment with the pinned FastH3 reference.
- Verify the required ComfyUI revision and official
comfy-kitchen==0.2.33runtime. - Check the reported CUDA
sol_attncapability. - Remove any Relay LoRA or Attention Backend node applied after the locked FastH3 profile.
- Use a standard H3 workflow if the experimental runtime is unavailable.
Relay intentionally stops rather than silently substituting dense attention.
A long sequence runs out of memory
- Use Run staged · bounded RAM on Assemble rather than ordinary queueing.
- Review raw shots before running enhancement and interpolation.
- Avoid assuming full model residency will fit: the tested toolkit workflows required normal offloading on the 24 GB RTX 4090.
- For tiled Ultimate processing, reduce the temporal window or tile dimensions using the relevant controls.
- Consult LTX_UPSCALING.md for LTX-specific window settings.
Smaller pieces can reduce memory demand but increase repeated overlap work. They do not guarantee compatibility with every GPU.
For Person Remover, remember that ordinary graph RAM use grows with clip length.
A preview plays, but no file appears in output/
- Check whether you are viewing an intermediate cached result.
- Connect a native Save Video node to the desired
VIDEOoutput. - Run Assemble when you want the final sequence published.
Changing CRF does not change the scene
This is expected. output_crf changes compression, not motion, composition, or model generation.
Change the relevant prompt, seed, generation settings, or reroll controls when you want different content.
An accepted checkpoint fails integrity checks
- Confirm that the requested shot exists in the sequence.
- Check whether cache files or metadata were moved, edited, or removed.
- Restore the matching complete cache, or regenerate the affected shot.
- Do not bypass the integrity check: later stages depend on the accepted checkpoint matching its recorded identity.
Saving workflow JSON alone does not preserve cached media.
Person removal targets the wrong area or looks inconsistent
- Inspect the SAM3 mask before H3 rendering.
- Refine the target description if the wrong person is tracked.
- Check that the clean first frame matches the source framing and dimensions.
- Return to the validated 22-frame window baseline.
- Reroll the affected window, understanding that subsequent windows will also rebuild.
Because the whole frame is regenerated, some background or motion changes remain possible even with a correct mask.
Character-edit output contains repeated tail frames
- Check whether the preparation node supplied padded
reference_frames. - Connect unpadded
source_framestosource_countin windowed editing. - For a single-window decode, use H3 Trim Output to Source Length.
Video preparation fails or an older helper appears
- Confirm that both
ffmpegandffprobeare available on the system PATH. - Confirm that your ComfyUI build provides the VIDEO API.
- Restart ComfyUI and refresh the browser after updating Relay.
- If the separate
labs-video-preppackage is present, remove the duplicate so ComfyUI does not select its older implementation.
Frequently asked questions
Do I need every finishing model?
No. Use only the components required by your workflow. Native raw assembly does not require LTX or RIFE. Person removal does not require LTX, RIFE, MMH3 Ultimate, or the FastH3 runtime.
Can I change compression without regenerating the video?
Yes. Change output_crf to encode a derived variant without repeating inference.
Does interpolation change the H3 continuation history?
No. Native continuation uses accepted raw H3 checkpoints, independently of finishing.
Why is person-removal output silent?
That workflow is silent by default. Connect original audio to the final Create Video node if you want it included.
Is FastH3 generally validated on Windows?
No. Windows GPU inference remains unvalidated for the experimental FastH3 path.
Will the cache travel with my saved workflow?
Do not assume so. Cached media remains on the serving machine; Person Remover explicitly does not embed cache files in workflow JSON.
Learn More about h3-relay
Start with a workflow matching your goal
- Example workflow guide — comparison of the supplied examples.
- Four-shot Orbital Storm example — the original 58-second Spectrum-16 reference configuration.
- FastH3 one-shot example — the smallest five-second FastH3 generation graph.
- FastH3 one-shot with Ultimate 2× — adds finishing while keeping the same prompt and seed.
- FastH3 three-window Akatz example — three 10-second generation windows with references, raw assembly, optional 2× enhancement, and bypassed-by-default interpolation.
The Akatz reference images are included in the example assets folder and need to be available in ComfyUI/input/ for that workflow.
Guides for editing and finishing
- Native toolkit guide — usage and workflow context.
- Windowed editing guide — character/reference editing and timing.
- Person Remover V1 guide — requirements, controls, and limitations.
- LTX upscaling guide — temporal windows and generative fidelity.
- Model manifest — exact model files and reference configuration.
- Validation record — tested behavior and known limits.
- MMH3 Ultimate Upscale — the external engine used for Ultimate finishing.
h3-relay License and Attribution
h3-relay’s source code is licensed under GPL-3.0.
For attribution and retained upstream licensing information, see:
- NOTICE.md
- UPSTREAMS.md
- Retained licenses under
h3_relay/vendor/
Model weights and external dependencies have their own licenses. Review those separately before using them in your projects.
