H3 Reference Audio (stereo guard):
H3ReferenceAudio prepares an audio clip for use as a MiniMax H3 reference audio signal, also known as a ref2va reference. It standardizes the clip into the format expected by the H3 audio-processing pipeline: two audio channels, a 32 kHz sample rate, and a configurable maximum duration. Mono audio is converted to stereo by duplicating its single channel, while audio with more than two channels is reduced to its first two channels. The node also uses only the first audio item when a batch contains multiple items and trims overly long clips. These adjustments help prevent channel-layout and sample-rate compatibility problems during sampling. Limiting the reference duration can also improve generation speed because the reference audio is included in the packed sequence during every sampling step.
H3 Reference Audio (stereo guard) Input Parameters:
audio
Provide the audio clip that you want to use as the H3 reference. The node reads the clip's waveform and sample-rate information, then prepares it for the H3 reference-audio format. If the waveform is mono, the node duplicates the channel to create stereo audio. If it contains more than two channels, only the first two channels are kept. When the supplied audio contains multiple items in a batch, only the first item is used. The audio is also resampled to 32 kHz when the required resampling support is available, and it may be shortened according to max_seconds. The input must be a valid AUDIO value produced by a compatible audio-loading or audio-processing node.
max_seconds
Set the maximum duration of the reference audio in seconds. The default is 10.0 seconds, the minimum is 0.5 seconds, the maximum is 60.0 seconds, and the control changes in 0.5-second steps. Audio longer than this limit is trimmed from the beginning so that only the first selected portion remains; shorter audio is not extended. A smaller value generally reduces the amount of reference data processed during every sampling step and can improve generation speed, while a longer value preserves more audio information when the reference depends on a longer musical phrase, spoken passage, or sound sequence. Set this value high enough to retain the important part of the reference, but avoid unnecessarily long clips because they increase the reference sequence length and can slow sampling.
H3 Reference Audio (stereo guard) Output Parameters:
audio
Returns the prepared reference audio as an AUDIO value. The waveform is returned in a contiguous format with one batch item, two channels when processing succeeds, and a 32 kHz sample rate when resampling is completed. Mono input is represented as duplicated left and right channels, and input with more than two channels contains only its first two channels. The output is trimmed to no more than the selected max_seconds duration. Connect this output to the H3 or MiniMax video-generation workflow that expects reference audio. This standardized result is important because the H3 sampler reserves space for two audio channels; passing an unprepared mono reference can cause a shape mismatch instead of producing a usable result.
H3 Reference Audio (stereo guard) Usage Tips:
- Use the default
max_secondsvalue of10.0for a general-purpose starting point. Reduce it to3.0to5.0seconds when you only need a short voice, rhythm, or sound-quality reference and want to reduce sampling cost. - Increase
max_secondstoward the60.0-second maximum when the reference depends on a longer progression, such as an extended musical phrase or a sequence whose important characteristics do not appear near the beginning. Longer references require more processing during every sampling step. - Use a stereo source when possible. Mono sources are supported and automatically duplicated into two channels, but duplication does not create real stereo information; it only satisfies the H3 channel-layout requirement.
- Keep the reference focused on the material you want H3 to follow. Because clips longer than
max_secondsare trimmed from the end, place the most important sound or speech at the beginning of the source clip. - Connect a valid audio output directly into
audio. The node expects audio data containing both a waveform and a sample rate, rather than a file path or an image. - Check the console message beginning with
[H3RefAudio]when troubleshooting. It reports the resulting channel count, sample rate, duration, and any conversions or trimming performed. - Ensure
torchaudiois installed and available in the runtime when the input is not already 32 kHz. Without it, the node records that resampling was skipped, and the downstream workflow may still receive audio at the original sample rate.
H3 Reference Audio (stereo guard) Common Errors and Solutions:
A MONO reference crashes the sampler with an unhelpful shape mismatch
- Explanation: The H3 sampler reserves space for two audio channels, but an unprepared mono reference contains only one. This creates an incompatible tensor shape during sampling.
- Solution: Pass the audio through H3ReferenceAudio before connecting it to the H3 sampler. The node duplicates mono audio into two channels. If the error continues, confirm that the sampler is receiving this node's
audiooutput rather than the original audio source.
shape mismatch
- Explanation: The downstream H3 sampler received audio with a channel layout or tensor shape it does not expect. This commonly happens when the original mono or multichannel audio bypasses the preparation node.
- Solution: Connect the original clip to
audioon H3ReferenceAudio and connect the node's output to the reference-audio input of the H3 workflow. Also verify that no later node changes the channel layout back to mono.
resample skipped (...)
- Explanation: The node attempted to convert audio to 32 kHz but could not complete the operation, usually because the
torchaudiopackage is unavailable or the source audio could not be processed. The node keeps the existing sample rate and notes that the downstream workflow may resample again. - Solution: Install or enable a compatible
torchaudiopackage in the environment, then restart the application and run the workflow again. You can also provide an audio source that is already 32 kHz. Check the full text inside the parentheses afterresample skippedfor the underlying reason.
torchaudio resampling error
- Explanation: The resampling library was available, but it could not process the waveform or sample-rate combination. Possible causes include an invalid audio tensor, an unsupported sample rate, or a damaged audio input.
- Solution: Reload or re-encode the source audio as a standard WAV, MP3, or compatible audio format, then try again. Confirm that the audio node produces a valid waveform and sample rate before it reaches H3ReferenceAudio.
audio input is missing or has the wrong type
- Explanation: H3ReferenceAudio requires an
AUDIOvalue. A file path, image, text value, or an unconnected input cannot provide the waveform and sample-rate data that the node needs. - Solution: Connect the output of an audio loader or another audio-processing node to
audio. Make sure the connection uses anAUDIOsocket and not an image, video, or text socket.
max_seconds is outside the allowed range
- Explanation: The node accepts values from
0.5through60.0seconds. Values below the minimum or above the maximum are invalid for the node interface. - Solution: Set
max_secondsto a value between0.5and60.0, preferably using increments of0.5. The default value of10.0is a suitable general starting point.
RuntimeError or tensor indexing error while preparing audio
- Explanation: The input waveform does not have the dimensional structure expected by the node. The node supports a two-dimensional waveform representing channels and samples, or a batched form that can be reduced to the first batch item.
- Solution: Reload the audio with a standard audio loader and ensure it produces a valid
AUDIOobject. Avoid passing a manually constructed or incomplete waveform. If the problem persists, inspect the source audio node and confirm that its waveform contains channel and sample dimensions.
