H3 Reference Registry:
The H3 Reference Registry organizes reference media into a consistent, structured catalog for an H3 context workflow. It gives each reference a predictable identity, records its position, and distinguishes special roles such as opening-frame anchors, closing-frame anchors, general references, and audio sources. It also explicitly records which supplied soundtrack belongs to which video, rather than leaving that relationship ambiguous. The node preserves the order within each media group and arranges the groups into a standard sequence, helping later workflow stages refer to the same assets consistently. Its catalog is immutable, meaning it is constructed as a fixed reference record rather than something later stages should modify in place. This node organizes references; it does not itself generate artwork, edit media, or interpret the artistic content of your references.
H3 Reference Registry Input Parameters:
first_frame
An optional IMAGE reference assigned the explicit first-frame role. Use it when you want to identify an image as an opening-frame anchor rather than as an ordinary visual reference; whether and how that anchor is applied depends on the later stages of your workflow. When present, its registry entry comes before all other media and uses the identifier first_frame_1. The allowed count is zero or one item. There is no preset image; the method default is None, so leaving this connection empty contributes no first-frame entry. This limit concerns the number of accepted reference items, not an image-resolution setting.
last_frame
An optional IMAGE reference assigned the explicit last-frame role. It distinguishes an intended ending-frame anchor from ordinary image references, making that role available to later H3 processing. When present, its entry follows the first-frame entry, if one exists, and precedes the general image references; its identifier is last_frame_1. The allowed count is zero or one item. There is no preset image, and the method default is None. Leaving this connection empty simply omits the last-frame entry; the node does not automatically select an ending image from your other references.
images
Optional ordered IMAGE references assigned the general reference role. These are cataloged after any explicit first-frame and last-frame anchors, preserving their supplied order and receiving identifiers such as image_1 and image_2. The allowed count is zero through nine items, as stated in the interface tooltip. The method default is None, with no preset media. Changing the order changes which image receives each numbered identity, so keep the sequence stable when other workflow stages depend on particular reference positions. These images are not automatically promoted to first-frame or last-frame anchors.
videos
Optional ordered VIDEO references assigned the general reference role, with identifiers such as video_1 and video_2. The allowed count is zero through three items, and the method default is None. Their supplied order is preserved. Each video can have a corresponding explicitly supplied paired soundtrack: paired audio item 1 belongs to video 1, item 2 belongs to video 2, and so on. In the resulting registry, each paired soundtrack is placed immediately before its corresponding video. During execution, the node also attempts to retain process-local source information for these videos for later authoring stages; failure of that source-binding step does not, by itself, invalidate an otherwise valid registry.
paired_audios
Optional ordered AUDIO items that explicitly represent soundtracks associated with the ordered video references. Item N pairs only with video N; the node records this relationship using an entry such as audio_pair_1 linked to video_1, and places that audio entry immediately before its video in the registry. The minimum count is zero, and the method default is None. The input declares its maximum through MAX_PAIRED_VIDEO_AUDIO, whose numeric value is not included in the supplied source excerpt; additionally, the paired-audio count must never exceed the video count, so the three-video limit gives an effective upper bound of three before any other capacity restrictions apply. Pairing is positional, not based on filenames or automatic audio matching. These items also pass through the core registry's audio-capacity validation, so the socket limit alone does not establish that every combination of paired and standalone audio is accepted.
audios
Optional ordered AUDIO references that are registered as standalone audio sources rather than soundtracks explicitly paired with videos. Their entries use identifiers such as audio_1 and audio_2 and appear after all video entries and their paired soundtracks, while preserving their own supplied order. The allowed socket count is zero through three items, as stated in the interface tooltip, and the method default is None. Use this group when you do not intend to establish a video-to-soundtrack pairing. The core registry also checks audio capacity across the constructed registry; the supplied excerpt does not expose the exact combined-capacity rule, so three standalone items should not be interpreted as a guarantee that every additional paired-audio combination will be valid.
H3 Reference Registry Output Parameters:
reference_registry
An H3_REFERENCE_REGISTRY value containing the immutable, structured reference catalog for compatible H3 workflow stages. Its entries describe each asset's identifier, media kind, assigned role, and one-based connection order; paired soundtrack entries also identify their corresponding video. The canonical sequence is first-frame anchor, last-frame anchor, ordered general images, ordered videos with each supplied paired soundtrack immediately before its video, and finally ordered standalone audio. Missing optional groups contribute no entries. For example, supplying one first-frame image, one general image, one video with a paired soundtrack, and one standalone audio produces the sequence first_frame_1, image_1, audio_pair_1, video_1, and audio_1. Interpret this output as the reference structure that later stages can use, not as a rendered image, video, audio mix, or text report. Execution also attempts to capture image and video source bindings separately for process-local authoring use; those bindings should not be confused with the catalog's descriptive entries.
H3 Reference Registry Usage Tips:
-
Use
first_frameandlast_framefor explicit opening and ending anchors. Place ordinary visual references inimagesso their roles remain distinct. -
Keep your media ordering intentional. Swapping two images or videos changes their numbered identities and, for videos, can change which paired soundtrack belongs to which clip.
-
Supply
paired_audiosonly for a consecutive leading set of videos: one paired item targets video 1, and two target videos 1 and 2. The shown interface does not provide a separate control for assigning a single paired item directly to video 2. -
Use
audiosfor audio that should remain standalone. Connecting audio there does not establish a soundtrack relationship with any video. -
Stay within the documented limits: one first-frame anchor, one last-frame anchor, nine general images, and three videos. Standalone audio has a three-item socket limit, while paired audio must also respect its configured limit and the number of supplied videos.
-
Check combined audio capacity when using both audio groups. If registry construction reports an audio-capacity error, reduce the audio references rather than assuming the separate socket limits can always be added together.
-
Connect
reference_registryto a compatibleH3_REFERENCE_REGISTRYinput in your H3 workflow. It is structured reference data, so it cannot substitute for an IMAGE, VIDEO, or AUDIO connection. -
Do not expect this node to enforce a visual result by itself. Its job is to record reference roles and relationships; later stages must interpret and apply them.
-
Expect the node to execute again when your workflow runs. Its change-checking deliberately avoids ordinary cache reuse because execution also captures process-local source information needed by later authoring stages.
H3 Reference Registry Common Errors and Solutions:
paired_audio_without_video: paired_audios item count cannot exceed the ordered videos item count
- Explanation: You supplied more paired soundtracks than videos. Every paired audio item needs a video at the same numbered position; for example, a second paired soundtrack requires a second video.
- Solution: Add the missing video references, remove excess paired audio items, or move audio that should not be paired into
audios, subject to the registry's audio-capacity rules.
Too many reference items for an input
- Explanation: This is a descriptive label, not a confirmed literal error message. The node expands and checks each media group against its configured maximum. Too many frame anchors, images, videos, or audio items can prevent construction; the helper's exact error wording is not included in the supplied source.
- Solution: Reduce the affected group to its supported size: at most one item for each frame anchor, nine general images, three videos, and three standalone audio items. For paired audio, also keep the count at or below the video count and the configured paired-audio limit.
ReferenceAudioCapacityError during registry construction
- Explanation: The core registry rejected the audio allocation. The node catches this error and reports its original error code and message, but the exact capacity rule and message strings are not shown in the supplied excerpt. Staying within each individual socket's maximum does not necessarily satisfy the combined audio rules.
- Solution: Read the reported message for the specific restriction, then reduce the number of paired or standalone audio references. If necessary, begin with only the essential audio and add items back gradually to identify the accepted combination.
invalid_reference_registry
- Explanation: The assembled references failed a core registry consistency check. This is the fallback error code used when construction raises a general
ReferenceRegistryError; the accompanying message provides the more specific reason. - Solution: Check that you are supplying compatible media types, valid group sizes, and no more paired soundtracks than videos. Try a minimal configuration and reconnect groups one at a time. If the failure persists, use the accompanying error text to diagnose the specific registry rule rather than relying on this general code alone.
Incompatible media connection
- Explanation: This is a descriptive troubleshooting label rather than a quoted node error. The interface requires IMAGE values for frame anchors and image references, VIDEO values for video references, and AUDIO values for both audio groups. A mismatched upstream output may be rejected by ComfyUI before this node executes.
- Solution: Use an upstream node that produces the exact required socket type. If conversion is necessary, perform it before connecting the media; this registry node does not expose media-conversion controls.
