MiniMax H3 Frame Rate Adjustment (Ac)

ComfyUI MiniMax H3 Frame Rate Adjustment (Ac)

中文 · Changelog · Issues

An experimental ComfyUI node for retiming native MiniMax H3 joint audio/video latents before sampling.

Node: MiniMax H3 Frame Rate Adjustment (Ac)

Category: Ac / MiniMax H3 / Experimental

This is not a mature high-frame-rate enhancer. The visible effect is often subtle, and quality is not guaranteed to improve. The released H3 configuration is 24 FPS; every other value is an out-of-distribution experiment and may cause flicker, color shifts, broken motion, or subject deformation.

What it does

MiniMax H3 packs video and audio into one sequence. Video uses the documented 24 FPS clock while the audio latent uses a 40 Hz clock. Given F generated video frames and the selected fps, this node computes:

video duration = F / fps
target audio latent T = round(video duration * 40)
video temporal-coordinate scale = 40 / fps

It then:

1. keeps the video latent and output frame count unchanged;
2. remaps video time coordinates in H3's PackedLayout.position_ids;
3. trims or zero-pads the audio latent before sampling to cover approximately the same duration.

The audio clock is quantized to 1/40 second, so the endpoint difference is normally at most about 12.5 ms. The exact value is exposed in report_json.

What it does not do

• It does not interpolate frames.
• It does not resample decoded audio or alter pitch.
• It does not give the model more compute per frame.
• It does not reduce steps, VRAM, or runtime.
• It does not guarantee that 31/36/48/60 FPS is cleaner than 24 FPS.

With the same frame count, raising FPS only shortens playback duration and leaves sampling cost approximately unchanged. Keeping the same duration while increasing the real frame count requires more H3 temporal tokens and therefore more memory and time.

Compatibility

Version 0.1.2 was prepared and tested against:

• ComfyUI 0.31.0;
• ComfyUI commit 43cb4fffc89bba20ab7bd61467a36d0339338dab;
• native MiniMaxH3ImageToVideo / MiniMaxH3ReferenceToVideo joint AV latents;
• video latent [B, 24, T, H, W];
• audio latent [B, 32, 2, T].

The implementation depends on internal ComfyUI H3 structures (PackedLayout, extra_conds, and minimax_payload). Compatibility guards reject unknown layouts instead of silently writing incorrect coordinates, but future ComfyUI changes may still require an update.

Recommended minimum: ComfyUI >= 0.31.0.

Installation

Clone into ComfyUI/custom_nodes and restart ComfyUI:

git clone https://github.com/AharaOoO/ComfyUI-MiniMaxH3-FrameRate-Adjustment-Ac.git

Search for:

MiniMax H3 Frame Rate Adjustment (Ac)

There are no additional pip dependencies. Do not install or upgrade torch for this node; PyTorch, comfy, and comfy_api are supplied by ComfyUI.

Example workflow

Drag example_workflows/MiniMaxH3_fps.json into ComfyUI. This is the complete example supplied with the project, rather than a simplified official-template conversion. It contains the H3 image-to-video path, Turbo LoRA, manual Sigmas, SageAttention, Sol-Attn, CFG guider, AV decoding, and video output.

Additional custom nodes used by the example:

• ComfyUI-KJNodes for the H3 SageAttention patch and preview override;
• ComfyUI-SolAttn_triton for SolAttnPatch;
• ComfyUI-VideoHelperSuite for VHS_VideoCombine.

The workflow references local H3 model, text-encoder, VAE, LoRA, and input-image filenames but does not bundle those files. Select the corresponding files available in your installation. The frame-rate node's model_fps output is already connected to the final video combiner, so one value controls both model timing and output playback FPS. The public copy has only had machine-local preview paths removed; its graph, links, and generation parameters are otherwise preserved.

Wiring

All three paths must pass through the node:

MODEL patch chain ────────> [model]  Frame Rate Adjustment  [model] ───────> BasicGuider
H3 positive ──────────────> [positive]              [positive] ────> BasicGuider
H3 joint AV latent ───────> [av_latent]             [av_latent] ───> SamplerCustomAdvanced

Frame Rate Adjustment [model_fps] ─────────────────────────────────> CreateVideo fps

Place it after LoRA/attention/model-sampling patches and before the guider. If BasicScheduler is used, the node's model output may feed both BasicScheduler and BasicGuider. The node does not modify Sigmas.

After sampling, decode video and audio through the normal H3 VAEs. Set CreateVideo/the save node to exactly the same FPS as model_fps; otherwise playback speed and AV duration will diverge again.

Frame count and duration

H3's valid decoded frame counts remain on the 17k + 5 grid:

5, 22, 39, 56, 73, 90, 107, 124, 141, 158, 175, 192, ...

To align a requested duration upward:

n = max(5, round(seconds * fps))
length = n + (5 - (n % 17)) % 17

The final duration is length / fps, which may differ from the requested duration after alignment.

| Frames | model_fps | Actual duration | |---:|---:|---:| | 124 | 24 | 5.1667 s | | 124 | 31 | 4.0000 s | | 192 | 48 | 4.0000 s | | 192 | 36 | 5.3333 s |

Use the node's duration_seconds output for downstream nodes that require the actual duration.

Practical recommendations

| model_fps | Guidance | |---:|---| | 24 | Safe baseline; should match native H3 timing | | 25–30 | Mild experiment; differences are often subtle | | 31–36 | Stronger retiming; compare with a fixed seed | | 37–48 | High risk of flicker, color drift, or unstable motion | | 49–120 | Research/boundary testing only; not recommended for quality |

For the first comparison, use the base H3 model, no distilled LoRA, the model-recommended sampler/Sigmas, exact attention, and a fixed prompt/reference/seed/resolution/frame count. Change only model_fps.

Distilled LoRAs and approximate attention are different techniques, but their errors can interact with out-of-distribution temporal coordinates. A distilled LoRA must use its exact trained step count, shifts, sampler, and sigma grid. If output breaks, return to 24 FPS and exact attention, then add one variable at a time.

Outputs

• model: H3 model with the layout patch;
• positive: conditioning tagged with frame count and selected FPS;
• av_latent: joint latent with adjusted audio T;
• model_fps: validated FPS for the video output node;
• duration_seconds: frame_count / model_fps;
• report_json: frame/audio timing, expected audio samples, endpoint error, and warnings.

Tests

Run from the ComfyUI root:

python -m unittest discover \
  -s custom_nodes/ComfyUI-MiniMaxH3-FrameRate-Adjustment-Ac/tests -v

The tests do not download models or run GPU inference. They validate node registration, H3 frame mapping, packed temporal coordinates, AV endpoint quantization, and compatibility guards.

Privacy and security

The node performs no network requests, telemetry, subprocess execution, or runtime package installation.

License

Project code is GPL-3.0-only. MiniMax H3, ComfyUI, custom nodes, and model weights retain their respective licenses. No model weights or third-party node code are included.