HunyuanVideo Sampler

This is the KSampler-equivalent for kijai's Hunyuan wrapper - the node that actually runs the denoising loop and produces latents. It's also the hub of the whole pack: nearly every other settings node in this article series (TeaCache, block swap indirectly through the model, Enhance-A-Video, context options, FreSca, Skip Layer Guidance, loop args) plugs into an optional input here. That's the real draw of this wrapper over native ComfyUI Hunyuan support - you get several acceleration and quality techniques wired into one sampler that native support, as of this pack's last real update, still doesn't fully match.

The inputs that matter

Required: model (HYVIDEOMODEL) and hyvid_embeds (from one of the encode nodes) are non-negotiable. width/height default to 512, stepping by 16. num_frames defaults to 49 and steps by 4 - that's not arbitrary; HunyuanVideo's VAE compresses 4 pixel frames into 1 latent frame, so frame counts follow the "4n+1" convention common across video diffusion models. steps defaults to 30. embedded_guidance_scale (default 6) is HunyuanVideo's baked-in guidance - the model is guidance-distilled, meaning the classifier-free-guidance behavior is trained into the weights rather than requiring a real second forward pass every step, similar to how Flux works. flow_shift (default 9) is the timestep-shift knob that flow-matching models expose to control how sampling effort distributes between overall composition and fine detail.

Optional and worth knowing: samples (vid2vid init latent) and image_cond_latents (i2v init, from HyVideoEncode) cover the older/community image-to-video route; denoise_strength controls how much of that init survives. riflex_freq_index (default 0, disabled) is a real, community-verified technique for generating past the model's native ~129-frame training length without the output looping back on itself - the tooltip's own recommendation is 4 when you actually want it. i2v_mode switches between stability and dynamic image-conditioning behavior. scheduler offers five options, defaulting to FlowMatchDiscreteScheduler - the one matched to how this model was trained; the others exist for experimentation.

Output: samples, a LATENT that goes straight to HyVideoDecode.

How to install it

Ships with the pack. ComfyUI Manager: search ComfyUI-HunyuanVideoWrapper, install, restart. Manual:

cd ComfyUI/custom_nodes
git clone https://github.com/kijai/ComfyUI-HunyuanVideoWrapper
pip install -r ComfyUI-HunyuanVideoWrapper/requirements.txt

then restart. This node needs everything upstream working first: a loaded model, embeds from an encode node, and ideally a VAE ready downstream - it's the middle of the pipeline, not something you can test in isolation.

Common issues & troubleshooting

Out of memory as soon as you raise resolution or frame count. Video memory scales fast on both axes at once - width, height, and frame count all multiply together. Drop num_frames first (it's usually the cheapest lever), make sure the model loader has fp8 quantization and a HyVideoBlockSwap attached, and only then reach for lower resolution.

Motion looks mushy, or the model seems to ignore your prompt's dynamics. Check flow_shift - it's tuned for this specific model at its default of 9; wildly different values push the sampling trajectory somewhere the model wasn't trained to handle well.

Generation crashed at a frame count you didn't choose. num_frames snaps to steps of 4 - if you typed an arbitrary number, ComfyUI rounds it, and depending on your workflow the result you expected and the result you got can differ. Stick to the 4n+1 pattern (49, 65, 129...) deliberately.

Output loops or repeats past a certain length. That's a known limitation of this model at longer lengths, not a bug in your workflow. riflex_freq_index set to a nonzero value (try 4) is the documented fix for extending past the native training length without the repeat.