🌀 BV Reference Registry

BV Reference Registry is the identity backbone of BV Node Pack's reference-driven regional editing - the feature the pack's 1.4.0 release built everything around. You collect up to a hundred native images, audio clips and videos (generated media included), and the registry pins each one to a stable, persistent identity. Downstream, regional editors and the Krea 2 Identity Edit path point at those media by name - inline @ mentions in your prompts - instead of hoping some image wire still points where you think it does.

Why should you care? If your regional workflow uses reference media for character or identity consistency, the usual experience is: load an image, wire it to a branch, pray the order matches, re-wire after any edit. The registry kills that whole class of fiddling. Load your reference shots once, name-stabilize them, and the rest of the workflow refers to them by identity. Reload the workflow and the identities survive - they live in the saved node config, not in the luck of your graph layout.

How it works

Mechanically it's a collector with a contract. On the frontend it's built with ComfyUI's newer node authoring style: an Autogrow media input that expands into up to 100 sockets, each accepting native IMAGE, AUDIO or VIDEO. Everything you connect is written by the UI into a hidden config_json widget - schema bv.reference_registry_config v1, with a UUID collector_id and one UUID identity per entry. On execution it builds a runtime resource-provider object that maps those identities to the actual media. Crucially, it catalogs without copying or decoding anything: video in particular stays lazy, which is a real courtesy for long clips.

That provider object is the single resource_provider output (typed BV_RUNTIME_RESOURCE_PROVIDER), and it's the thing you wire onward. The regional compile nodes in the same pack - Native Conditioning, the model-specific attention nodes like the Krea 2 attention path, the detailers - expose resource_provider_1 through resource_provider_20 sockets precisely to accept these providers, and they resolve references only against what you actually connected to them.

The inputs that matter

• media: the Autogrow inputs - this is where the actual work happens. Add one per reference; each accepts image, audio or video. Mixed types in one registry is fine and intended.
• config_json: socketless and auto-managed. A beginner should basically never touch it - connect and disconnect media and the frontend reconciles the config for you. Only hand-edit if you understand the schema, and then brace for validation errors.

Gotchas and real failure modes

• Compatibility is per model path, not global. A registry identity only means something where the model path supports applying references. Run a prompt carrying saved @ mentions through a plain, non-compatible path and BV refuses loudly - its own code raises "use a compatible edit mode or remove the reference mentions." That's a guard, not a bug; the reference-driven Krea 2 mode is the headline consumer.
• "Connected media and persisted reference entries differ." The registry validates that whatever is wired up matches its saved config. It normally reconciles itself live, but if you hand-edit config_json or restore a half-wired workflow, you'll trip this. Save the workflow after arranging your references.
• Native media only. Load Image tensors, VAE-decoded outputs, proper native video/audio objects - not arbitrary dicts you built in Python land.
• Version. This node is a 1.4.0 feature. Restart ComfyUI and hard-refresh the browser after updating, and because the pack's Registry review is still open, Manager may offer an older build - clone the repo if you want the reference features at all.

Install

From ComfyUI Manager, search "BV Node Pack", or:

cd ComfyUI/custom_nodes
git clone https://github.com/BlackVortexAI/bv_nodepack

Restart ComfyUI and hard-refresh. No model downloads or heavy dependencies for this node itself - the pack's LUT/LLM extras are separate and entirely optional for registry use. Worth knowing before you commit a workflow to it: the pack is GPL-3.0, and its README is upfront that it's developed with extensive generative-AI assistance under human direction, with registry security review still pending.