Thelocallab/HeartMuLa-oss-ComfyUI

HeartMuLa for ComfyUI — merged single-file checkpoints

Every ComfyUI-ready build of HeartMuLa in one place, including half-precision versions that halve the download.

The official weights ship as fp32 across 6 shards, which ComfyUI can't load directly. These are consolidated into one file per model, with config and tokenizer embedded so each file loads on its own.

Which files do I need?

You need one language model + one codec. Start with the half-precision pair.

File	Size	Precision	Notes
HeartMuLa-oss-3B-merged-bf16.safetensors	7.34 GB	bfloat16	Recommended LM
HeartCodec-oss-merged-fp16.safetensors	3.09 GB	float16	Recommended codec
HeartMuLa-oss-3B-merged.safetensors	14.68 GB	float32	Full precision LM
HeartCodec-oss-merged.safetensors	6.18 GB	float32	Full precision codec

10.4 GB for the recommended pair versus 20.9 GB for fp32. Both pairs were tested and generate fine; I could not hear a difference.

Quick start

1. Install the custom node

cd ComfyUI/custom_nodes
git clone https://github.com/crazyma99/ComfyUI-HeartMuLa

Follow that repo's README for its Python dependencies.

2. Download the pair you want into ComfyUI/models/checkpoints/

hf download Thelocallab/HeartMuLa-oss-ComfyUI \
  HeartMuLa-oss-3B-merged-bf16.safetensors \
  HeartCodec-oss-merged-fp16.safetensors \
  --local-dir ComfyUI/models/checkpoints

(On older huggingface_hub this is huggingface-cli download.) Or grab them from the Files tab above.

3. Set the loader like this — this is the bit people get wrong:

HeartMuLaLoader field	Half precision	Full precision
model	...-3B-merged-bf16.safetensors	...-3B-merged.safetensors
codec	...-Codec-oss-merged-fp16.safetensors	...-Codec-oss-merged.safetensors
model type	3B-merged	3B-merged
model dtype	bfloat16	float32
codec dtype	float16	float32

Then wire HeartMuLaLoader → HeartMuLaGenerator → SaveAudioAdvanced.

Why the two half precisions differ

The loader exposes bfloat16 for the language model but only fp32 / fp16 for the codec. So a bf16 codec would be cast to fp16 at load time anyway — sending the weights fp32 → bf16 → fp16, losing mantissa precision on the way and risking overflow past fp16's ~65504 ceiling.

Storing the codec as fp16 skips that. Same file size, one conversion instead of two. Match each file to the precision the loader actually offers for it and there's no conversion at load at all.

Provenance

Two different origins — worth being clear about which is which.

The half-precision files are my own builds, merged from the official HuggingFace repos:

• weights from HeartMuLa/HeartMuLa-oss-3B (4 shards) and HeartMuLa/HeartCodec-oss-20260123 (2 shards)
• embedded metadata: config.json from each model's own repo, plus tokenizer.json and gen_config.json from HeartMuLa/HeartMuLaGen
• modifications: shards consolidated; config/tokenizer/gen-config embedded into the safetensors __metadata__; weights cast fp32 → bf16 (LM) and fp32 → fp16 (codec)
• tensor names unchanged — 289 for the LM, 818 for the codec, matching upstream exactly

Verified before publishing: tensor counts match upstream, every embedded JSON is byte-identical to its official source, declared torch_dtype matches the actual tensor dtype, and both files generate audio end-to-end in ComfyUI.

The fp32 files are mirrored from AIGCCrazyMa/HeartMuLa-oss_ComfyUI on ModelScope, which produced them first. They are unmodified — re-hosted here because they weren't previously available on HuggingFace. All credit for that packaging is theirs.

Credits

• HeartMuLa by the HeartMuLa team — the model, the training, and the research. Apache 2.0. (paper)
• ComfyUI-HeartMuLa by crazyma99 — the custom node these files are built for.
• AIGCCrazyMa — the single-file-for-ComfyUI packaging approach, and the fp32 files themselves.

All credit for the underlying work belongs upstream. These are repackaged weights, nothing more.

Licence

Apache 2.0, inherited from HeartMuLa. Redistribution and modification are permitted with attribution; modifications are stated above.

Guides

Written walkthroughs and more local AI tutorials: https://www.locallabdigest.com