YuE2 Official Model Loader

The name is a lie, and it's the most useful thing to know about this node. YuE2 Official Model Loader puts zero weights into ComfyUI's model manager. It checks that the official files are where they should be, then hands a small settings dictionary down the graph. The 3B backbone is loaded later, by the isolated YuE2 Python process, every time a stage actually runs.

That matters because it explains almost every surprise you'll hit: why the node instantiates instantly, why editing it invalidates everything downstream, and why your ComfyUI console shows a separate process doing the work.

What it's for

Every other node in the pack demands a YUE2_MODELS input and hard-validates it - miss it and you get "Run the YuE2 Model Loader and select an official model and decoder" instead of music. So this is the head of every graph, including all four of the pack's example workflows. It's where you answer the graph-level questions: which decoder, which GPU, how much memory, which runtime backend.

How it actually works

Under the hood it resolves model folders through an index file the conversion script writes, ComfyUI/models/diffusion_models/YuE2/official_models.json, and requires config.json and model.safetensors to be real regular files in each directory. It also refuses symlinks and Windows junctions anywhere along the model path - a deliberate choice, since the pack only ever resolves model locations from its own registered keys, never from a path handed to it by an upstream node.

The output is a plain dict: model_key, vae_key, device, memory_budget_gib, backend, quantization, offload_ar, vae_core_frames, verify_hashes. Every stage node merges that into the request it sends to the isolated worker. Right before launching, it calls ComfyUI's memory manager to free cached models on the target device - so if you queue a YuE2 stage after a Wan or Flux graph, expect the other models to get evicted.

The inputs that matter

model has exactly one choice, YuE2-3B. There is no second checkpoint to pick; YuE2 is a single joint transformer doing planning, semantics and acoustics, not a UNet plus a separate text encoder.

vae is the one you'll actually think about. YuE2-Vae is the current listening decoder and the default for generated music. YuE2-Vae-legacy exists to reproduce the published evaluation protocol - reach for it when you want to compare against paper numbers, not because it sounds better.

device is cuda:0, cuda:1, auto, cpu or mps. auto resolves to CUDA, then MPS, then CPU. cuda:1 only works if ComfyUI was started with --cuda-device all - the same flag that exposes a second GPU to this pack. Forget it and the second card just sits there.

Then the memory controls. memory_budget_gib defaults to 24, matching the official recommended floor of a BF16-capable 24 GB card. backend offers torch-eager, torch and vllm; keep torch-eager on Windows, because the official Torch build there lacks the FlashAttention kernel the CUDA Graph backend needs. vllm is Linux-GPU-only and needs sh setup-runtime.sh --fast. quantization is none or fp8, and the author is blunt about it: FP8 is an explicit quality trade, never a rescue for a memory failure. If you're out of VRAM, drop memory_budget_gib, turn on offload_ar, or shrink vae_core_frames (default 1024, chunked decoding) - don't reach for fp8 first.

verify_hashes defaults on and re-checks the pinned files. Leave it. On a 7 GB safetensors file it costs a few seconds once and saves you from a corrupted download masquerading as a sampler bug.

Wiring it up

One output, models. Fan it out to every stage node in the graph - Text Encode does not take it, but Generate Music, Generate ABC, Semantic Tokens, Synthesize and Decode all do.

Install

Drop the repo into ComfyUI/custom_nodes/ComfyUI_YuE2, then run the launchers in order - they're not optional, and each keeps its own console:

sh setup-runtime.sh                 # pinned official engine in .venv (Python 3.12)
sh scripts/download-models.sh       # revision-pinned files, SHA256 verified
sh convert-models.sh                # places them in ComfyUI's model folders

That's about 11.08 GB of models before runtime dependencies. On Windows use the .bat twins. ComfyUI Manager, if it lists the pack, gets you the clone and the restart; it does not run these scripts for you.

Where people get burned

The two errors you'll see are literal instructions. "YuE2 official models are not adapted yet" means you skipped the download or conversion launcher - the index file doesn't exist. "The isolated runtime is missing. Run setup-runtime.sh first" means .venv isn't there, usually because the runtime setup failed quietly behind a missing python3-venv on Debian/Ubuntu.

And the sneaky one: if you symlink your models directory onto another drive, this node rejects the path by design. Hard links are what the adapter uses internally to avoid a second copy - symlinks are treated as a boundary violation.