H3 Audio Reference:
H3RCAudioReference turns a selected recording into a named audio reference for an H3 workflow. It can use audio already connected in ComfyUI or load an eligible media file, then select a portion of the recording without changing the saved source. The node packages that selection with a role and guidance about what to retain or change, so you can refer to the sound consistently when describing a scene. It also provides the selected audio for listening or use elsewhere in your workflow. The node prepares a reference; it does not itself generate or transform a soundtrack.
H3 Audio Reference Input Parameters:
source
Choose Connected input or Load file. Connected input uses the optional audio connection; Load file loads the file named in file and takes precedence over any connected audio. There is no numeric range or separate default specified in the interface.
file
Enter the media file to load when source is Load file. The file must exist in ComfyUI’s input, output, or temp directory. This field does not select the recording when source is Connected input. Type: STRING; default: empty; no minimum or maximum length is specified.
tag
Give the reference a short name that you can use in a scene prompt, such as voice_ref. The node processes the name as an alias and includes it in the selection report. Type: STRING; default: voice_ref; no minimum or maximum length is specified.
role
Choose what the recording represents: character voice, ambience, music, sound effect, complete soundtrack, or custom. The role labels the reference for the H3 workflow; it does not edit the recording. Select custom when the available categories do not describe your audio, and explain it in descriptor. No separate default is specified.
associated_character
Optionally name the character associated with the audio, particularly when the reference is a voice. A nonempty name is processed as an alias and stored as the reference’s target; leaving it empty leaves the target unset. Type: STRING; default: empty; no minimum or maximum length is specified.
use_instructions
A multiline field presented in the interface for instructions about using the reference. In the supplied implementation, this field is accepted but is not passed into the resulting audio reference; retain and change supply its stored instructions instead. Do not rely on this field to guide the result. Type: STRING; default: empty; no minimum or maximum length is specified.
reference_type
Choose the prompt indicator for the intended degree of reuse: reference borrows sound characteristics, weak_reference borrows atmosphere, partially_copy requests selected layers or intervals, and fully_copy requests the complete recording as the final soundtrack. This setting describes the intended use; it does not itself alter or copy audio. Use retain and change to make the request more specific. No separate default is declared in the interface; the implementation falls back to reference when this setting is absent.
descriptor
Describe what the audio represents, especially when role is custom. For a custom role, this description is stored with the reference to help identify it in the H3 workflow. For other roles, the supplied implementation stores an empty descriptor even if you enter text here. Type: STRING; default: empty; no minimum or maximum length is specified.
start_seconds
Set where the selected portion begins, measured in seconds from the start of the recording. A value of 0 starts at the beginning. The value must be nonnegative and must leave at least one audio sample to select. Type: FLOAT; minimum: 0; default: 0; no maximum is specified.
duration_seconds
Set how many seconds to select after start_seconds. A value of 0 selects the rest of the recording; a positive value selects up to that duration and stops at the recording’s end if necessary. The resulting selection must contain audio. Type: FLOAT; minimum: 0; default: 0; no maximum is specified.
retain
Describe the sound qualities or content you want H3 to keep, such as a speaker’s voice timbre. Nonempty text becomes a Retain: instruction in the reference. It does not change the audio samples selected by this node. Type: multiline STRING; default: empty; no minimum or maximum length is specified.
change
Describe what you want H3 to change or exclude, such as generating new dialogue rather than using the source words. Nonempty text becomes a Change: instruction in the reference. It does not edit the saved source or the selected audio. Type: multiline STRING; default: empty; no minimum or maximum length is specified.
audio
Optionally connect an AUDIO value when source is Connected input. The node selects a range from this audio and passes that selection onward. The connection is ignored when source is Load file. Type: AUDIO; optional; no default or numeric range is specified.
H3 Audio Reference Output Parameters:
named_reference
An H3RC_REFERENCE containing the selected audio and its reference details, including the tag, role, associated character when supplied, intended reference type, selected duration, source range, and retain/change guidance. Pass this to a compatible H3 reference workflow when you want the recording considered as a named source. Its settings describe intended use; this output is not evidence that H3 has generated audio.
selected_audio
The selected AUDIO segment, retaining the source sample rate. Use it to listen to or pass along exactly the portion chosen by start_seconds and duration_seconds. A shorter-than-requested segment means the selection reached the end of the recording.
selection_report
A STRING summarizing the processed tag and the selected start and end times in seconds, displayed to three decimal places. Use it to confirm which interval was selected; it is a report, not another audio file.
H3 Audio Reference Usage Tips:
- For a connected recording, choose
Connected inputand attachaudio. To work from a file instead, chooseLoad fileand enter an existing file in a permitted ComfyUI directory. - To reference only a useful passage, set
start_secondsto its beginning andduration_secondsto its approximate length. Checkselection_reportand listen toselected_audioto confirm the actual selection. - For a voice reference, choose
character voice, supplyassociated_characterwhen relevant, and describe the qualities to keep inretain. - Use
weak_referencefor broad atmosphere, orpartially_copywhen you need to specify particular layers or intervals. Explain the intended distinction inretainandchangerather than relying on the option name alone. - Use
customwith a cleardescriptorfor audio that does not fit the listed roles. For other roles, put actionable guidance inretainandchangebecause their entereddescriptortext is not stored by this implementation. - Do not use
use_instructionsas your only instruction field: the supplied implementation does not carry its text intonamed_reference.
H3 Audio Reference Common Errors and Solutions:
Connect AUDIO or select Load file.
- Explanation:
sourceisConnected input, but no audio is connected. - Solution: Connect an
AUDIOoutput toaudio, or chooseLoad fileand provide a valid file.
Select an existing media file in ComfyUI input, output, or temp.
- Explanation: The chosen file does not exist or resolves outside the permitted ComfyUI directories.
- Solution: Check the filename and select an existing file in ComfyUI’s input, output, or temp directory.
Invalid audio source.
- Explanation: The received
sourcevalue is neitherConnected inputnorLoad file. - Solution: Select one of the two listed source options.
Use a positive sample rate and nonnegative range.
- Explanation: The supplied audio has a sample rate of zero or less, or a start or duration value is negative.
- Solution: Use audio with a valid positive sample rate and set
start_secondsandduration_secondsto zero or greater.
Audio range contains no samples.
- Explanation: The requested start falls at or beyond the available audio, or the selected interval contains no samples.
- Solution: Move
start_secondsearlier, choose a longer recording, or setduration_secondsto0to use the remaining audio.
File loading or audio preview fails.
- Explanation: A file can pass the location check but still fail when the audio loader reads it; preview creation can also fail after a selection is made. The exact message depends on the loader or preview component.
- Solution: Confirm the file contains readable audio and try a known working audio file or a connected
AUDIOinput. If selection succeeds but preview fails, check the ComfyUI error details to identify the failing stage.
