HeartMuLa Audio Decoder

The HeartMuLa Audio Decoder is the VAE-decode step of the whole music pipeline, and like every VAE decode it's the moment you stop trusting the process and actually hear the result. It takes the token sequence from a HeartMuLa Music Generator plus the codec from a HeartMuLa Codec Loader, and hands you real, playable AUDIO at 48 kHz.

You can't skip it and you can't replace it - the generator explicitly outputs tokens, not sound, because HeartMuLa generates music as codebook indices that only make sense to the HeartCodec. Think of tokens as the latent and this node as the decode that makes it listenable.

What it does

Two inputs, one output:

• tokens (HEARTMULA_TOKENS) - straight from the Music Generator.
• codec (HEARTMULA_CODEC) - from the Codec Loader.

Output is a standard AUDIO socket, the same type core ComfyUI audio nodes use. That means you can wire it into anything: PreviewAudio, SaveAudio, VHS audio outputs, the Lyrics Transcriber in this very pack, or the optional audio_input socket on HeartMuLa Style Embed (a fun loop - feed a generated track back in as a style reference).

Under the hood it moves the codec to the GPU, clamps token values to the codec's valid range (0–8191), runs decode_tokens, and returns a mono-or-stereo waveform with sample_rate: 48000. There's a progress bar across the decode chunks, and the codec is unloaded back to CPU when it's done so generation has VRAM room again.

The gotcha that looks like a bug

If the generator produced no tokens - which happens when a generation silently fails or the input is empty - the decoder doesn't error. It returns a one-second clip of silence at 48 kHz with a warning in the console. That's deliberate, so you get a clean "no output" instead of a crash, but it's also why "I got silence" usually means "check the generator," not "fix the decoder."

Install and models

The decoder itself ships with the pack, which you install like any custom node:

cd ComfyUI/custom_nodes
git clone https://github.com/Crono141/ComfyUI-JK-HeartMuLa.git
cd ComfyUI-JK-HeartMuLa
pip install -r requirements.txt

Restart ComfyUI; it lives under JK-HeartMuLa. The pack doesn't download weights, so the codec must exist before this node can do anything:

cd ComfyUI/models/HeartMuLa
git clone https://huggingface.co/HeartMuLa/HeartCodec-oss-20260123

When it's the problem vs. when it isn't

This is one of the more reliable nodes in the pack - there's not much to configure and not much to break. Most "decode failed" reports trace back to a codec model that never got cloned (check models/HeartMuLa/HeartCodec-oss-20260123/ exists) or to a generator run that crashed before producing tokens. If the decode itself is erroring, check you're feeding it the matching codec version - the old HeartCodec-oss and the 2026 codec aren't guaranteed to agree with the token stream the generator emitted. Keep everything on the defaults and you'll rarely look at this node twice, which is exactly what you want from a decode step.