H3 X2 Decode + Stream Save

What it replaces

This is the last node in an H3 workflow: decode, then save. ComfyUI's stock graph decodes to a full IMAGE batch - all 124 frames of 1088 × 1920 as float - and then encodes it to a file. That's your peak VRAM moment, and it decides whether a big clip fits at all.

H3 X2 Decode + Stream Save collapses those steps. It decodes the X2 latent with ComfyUI's native H3 spatial and temporal blending, in 256-pixel tiles with 64-pixel overlap, and each finished chunk goes straight to an H.264 NVENC encoder on a background thread. At any moment it holds the current chunk plus one in-flight encode. There's no IMAGE output at all - the video goes to disk.

That's the trade: need pixels for a downstream upscaler, reach for a conventional decoder instead. Want an MP4 of a 1088 × 1920 clip with audio on a 12 GB card? Exactly right.

How it works

The decode path stays ComfyUI's. The node sets the X2 VAE to 256/64 tile mode, tells the decoder to emit 12 channels instead of 3 (X2 Detail packs a 2 × 2 subpixel grid), and calls the native decode(..., output_buffer=...) interface. A sink object takes each finalized chunk, unpacks the frames, converts them to 8-bit, and hands them to a one-thread pool doing YUV conversion and the NVENC encode. Audio is muxed as AAC at the end, with the encoder pinned to ComfyUI's own sRGB settings (H.264, p4, hq, VBR, yuv420p, BT.709).

All of it sits in a context manager that puts the VAE's tiling flags, channel count, buffers and the float16-accumulation flag back when it's done, and no core ComfyUI file is patched. A crash can't leave a truncated MP4 either: the encode goes to a hidden .h3-x2-*.part.mp4 and is hard-linked into place only after a clean finish.

The inputs that matter

• samples - one H3 video latent, batch size 1 only. Frame count must sit on H3's 5 + 17*k grid: 124 yes, 123 no.
• vae - the INT8 X2 decoder VAE from H3 X2 Prepare INT8 VAE, not your conditioning VAE - the node errors clearly if you get it wrong. Width and height come from the latent × 32, so decode resolution isn't a setting here.
• nvenc_gpu - device index handed to FFmpeg/NVENC. Default 0, the only one validated. On multi-GPU boxes, check your encoder enumeration or you'll encode on the wrong card.
• cq - NVENC constant quality in VBR mode, 0-51, default 18. Lower is better and bigger; 24-28 is fine for previews.
• fps - default 24. It sets the muxer timebase and decides how much of your audio gets used.
• fp16_accumulation - default on; toggles torch.backends.cuda.matmul.allow_fp16_accumulation for the decode, then restores it. If your PyTorch lacks it, turn this off.
• audio (optional) - one mono or stereo waveform, trimmed to clip length. Longer is cut, shorter just ends early.
• filename_prefix - default H3_X2_Stream/video, so files land in output/H3_X2_Stream/.

There are no outputs. It's a terminal node, and the file it writes is the result.

Install and requirements

cd ComfyUI/custom_nodes
git clone https://github.com/sepiablue-ai/ComfyUI-H3-X2-Stream.git

# with ComfyUI's own Python, not a system one
.\python_embeded\python.exe -m pip install -r .\ComfyUI\custom_nodes\ComfyUI-H3-X2-Stream\requirements.txt

Requirements are av>=17.0.0 and safetensors>=0.7.0 - the av floor is because this node needs a PyAV build containing h264_nvenc. Manager works via Install via Git URL - the pack isn't in the registry. Beyond Python: an NVIDIA GPU with working H.264 NVENC, a CUDA VAE device, and a ComfyUI new enough for native H3 with the output_buffer decode interface (tested on 0.37.0). Windows/4070 was the validation platform; AMD, Apple, CPU-only and Linux were never validated.

Where people get burned

This PyAV/FFmpeg build lacks h264_nvenc. No software-encoding fallback - by design, since libx264 would eat the speed win. Reinstall av with ComfyUI's Python; on Windows, an old driver is the other half of this error.

"Connect the MiniMax H3 X2 video VAE." You wired in the conditioning or audio VAE. The X2 decoder belongs on this branch only.

OOM during decode. The node opts out of ComfyUI's generic tiled OOM fallback, because that fallback would change the H3 decode path - so it fails rather than degrading. Reduce generation size, or close whatever else is on the GPU.

Incomplete decode: N/M frames. What you get if a decode is interrupted partway; it stops a half-encoded file from being published.

Framing worth keeping: this pack landed in October 2026 and barely exists in community discussion, so its numbers - 59.7 s for a 5-second 1088 × 1920 clip with audio on a 4070 - are one author's benchmark on one machine, not a promise. And if audio quality is your problem rather than speed, the author also ships ComfyUI-H3-AudioFirst-X2-Stream.