HeartMuLa Audio Decoder

If you've wired up a HeartMuLa generation workflow you've seen the moment: the HeartMuLaMusicGenerator finishes, spits out a box of tokens, and nothing has made a sound yet. The HeartMuLaAudioDecoder is the node that closes that gap. It takes the generator's tokens plus the loaded codec and hands you a real, playable AUDIO waveform. It's the unskippable middle of the whole pack - a token stream is worthless until it passes through this.

What it does, mechanically

The generator's output is a sequence of discrete codes - a compressed token representation of the music, not audio. The codec (loaded by HeartMuLaCodecLoader) knows how to invert that. So the decoder is mostly plumbing: it takes the two sockets, moves the codec onto the GPU, clamps the token values into the codec's valid range, decodes in fixed ~29.76-second chunks with a progress bar, and returns a standard ComfyUI audio dict.

A couple of details in the source are worth knowing because they affect what you feel:

• It calls unload_all_models() first and returns the codec to CPU when done. That's deliberate VRAM hygiene - the decoder expects to work on a card that's already got a 3B LLM resident, and this keeps the spike as small as it can be.
• The output is a plain AUDIO object at 48 kHz. That means it plugs into anything that speaks ComfyUI's audio format - PreviewAudio for a quick listen, a save node, a video-combine node's audio track, or this pack's own Audio Post-Processor.

The inputs and output

There are no knobs here. Two required inputs, one output, zero configuration:

• tokens (HEARTMULA_TOKENS) - from the HeartMuLaMusicGenerator.
• codec (HEARTMULA_CODEC) - from the HeartMuLaCodecLoader.
• AUDIO - the decoded waveform, ready for the rest of your graph.

If you open the pack's example workflow, this is the node between the generator and PreviewAudio. That's the whole shape of it.

Setup and gotchas

Installation is the pack install - ComfyUI Manager search "HeartMuLa", or clone it:

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

The decoder itself loads no weights, so the only model work is making sure the codec is downloaded into ComfyUI/models/HeartMuLa/ and the version matches the generator you used. Mismatch shows up here as noise or a failed decode, and it's the first thing to check when a generation "succeeds" but sounds wrong.

The most common failure is honestly anticlimactic: an empty token stream. If the generator returned nothing, the decoder warns and returns 1 second of digital silence rather than crashing - which looks like a broken decode until you notice your generator never actually produced tokens. Also keep expectations in line with the model: community consensus is that HeartMuLa is the best open music option but not Suno - think "Suno v3-ish," great for ideas, and generation genuinely needs a 12–16GB card. This node isn't the bottleneck; the generator is. But it is the moment you find out whether you got the whole pipeline right.