FL YuE2 · Prepare Dataset

What it is and why you'd reach for it

Every trainer has a preprocessing stage that you run once and then forget about, and this is YuE2's. Prepare Dataset takes the manifest from Dataset Maker plus the training assets, listens to your recordings with a frozen audio encoder, and writes out the token sequences the AR LoRA trainer actually learns from.

You reach for it exactly once per dataset. It's the slow node in the pipeline - no rendering, no sampling, just a pile of feature extraction you don't want to repeat on every queue. Which is precisely what the cache is for.

How it works

The mechanism is worth a paragraph, because "prepare" is vague enough to hide the weird part. YuE2's song model doesn't learn from waveforms or even from spectrograms. It learns from semantic tokens - a compressed, learned alphabet for music, the same way an image VAE hands a diffusion model latents instead of pixels. So the pack runs each recording through MERT-v2-FullSong, a music-understanding encoder, resamples to its rate, chunks the audio, and feeds those features to a small prediction head (tokenizer_head_joint_v4.pt) that outputs token IDs under bf16 autocast. That's your training sample: a sequence of integer tokens, plus the style text and the review-approved lyrics.

Everything it writes is content-addressed and cached under output/yue2_training/<cache_directory>, defaulting to a folder literally named prepared. Change the name to keep two different preparation variants around.

Before it does any of that, it re-checks the dataset manifest against the files on disk - every audio hash and every sidecar hash. Edit a caption after building the dataset and this node refuses to run until you re-queue Dataset Maker. Annoying the first time, genuinely valuable the third time, when you'd otherwise be training on tokens extracted from a file you've since replaced.

The optional align_lyrics path is a bigger machine. Turn it on and the worker separates vocals with Demucs and aligns the reviewed lyric text to the audio with an MMS CTC aligner, downloading those weights only when you ask for them. That gives the training run per-token lyric positions, which is what the trainer's cursor_weight loss hangs off. It costs real time and it's the part most likely to disappoint on dense or processed vocals, so the pack's own advice is blunt: for instrumentals, leave alignment off and set cursor weight to 0 later.

The inputs and outputs

dataset - the YUE2_DATASET from Dataset Maker. Not optional.

assets - the YUE2_TRAINING_ASSETS from Training Models. This is where the MERT weights and the tokenizer head come from, so that node has to be in the graph and queued at least once.

align_lyrics - the boolean you'll think about for a minute. Off = semantic tokens only, fast, fine for instrumental data and fine when your lyric transcript is shaky. On = vocal separation plus alignment, more downloads, more prep time, and a lyric-position signal for training.

cache_directory - a name, relative to output/yue2_training. Nothing exotic; it just namespaces the prepared artifacts.

One output: YUE2_PREPARED_DATASET, which feeds the LoRA Trainer's dataset input. It is not a folder widget and it is not a model - don't go looking for it in models/.

Install

Same pack install as the rest of the training pipeline:

cd ComfyUI/custom_nodes
git clone https://github.com/filliptm/ComfyUI-FL-YuE2.git
cd ComfyUI-FL-YuE2
python -m pip install -r requirements.txt
python -m pip install -r requirements-training.txt

Or install ComfyUI-FL-YuE2 from ComfyUI Manager, then add the training requirements in ComfyUI's own Python environment. This node is the reason you can't skip them: transformers loads MERT, soundfile reads your recordings, scipy handles the resampling, and demucs==4.0.1 exists purely for the optional alignment path. Restart after installing.

Model weights arrive through the Training Models node, not here - MERT and the tokenizer head are downloaded into models/yue2/ when a run with download_missing enabled is queued. The alignment weights are the exception: they download only if align_lyrics is on.

Where people get burned

Requeuing after every caption tweak. Not a bug, but it feels like one. Any sidecar edit invalidates the prepared cache and the dataset manifest, so the real workflow is: finish captioning, then prepare, then train.

Expecting it to be instant. Feature extraction over an album is a real GPU job, and it's the longest non-training step in the pipeline. Do it once with the settings you intend to train with.

Turning on alignment for instrumentals. No vocals, nothing to separate. You pay the download and the time for a signal that's zero anyway. Use cursor_weight 0 in Train Config instead.

Forgetting that assets must be queued. If Training Models has never run, this node fails looking for MERT or the head - with download_missing disabled, it fails instead of fetching.

Cache confusion after swapping hardware or precision. Prepared artifacts are meant to be reused, and different kernels can produce different sampled results on the training side. If a run looks inexplicably different from an identical earlier one, rebuild the cache from a clean directory name rather than debugging the trainer.