All manual download commands are broken (fixes suggested)

[Cartogg]

on the main readme.md in the download weights section the commands are different now. I suspect they should be the following but I'm still testing this stuff out and haven't gotten it working yet.

# Create checkpoint directory
mkdir -p ckpt

# Download HeartMuLa (3B model)
hf download HeartMuLa/HeartMuLa-oss-3B --local-dir ckpt/HeartMuLa-oss-3B

# Download HeartCodec
hf download HeartMuLa/HeartCodec-oss-20260123 --local-dir ckpt/HeartCodec-oss

# Download tokenizer
hf download HeartMuLa/HeartMuLaGen tokenizer.json --local-dir ckpt

[Cartogg]

I gave up after a few hours and GLM-5 summarized my progress. here are her details:

---

Issue: Weight conversion and generation problems on Apple Silicon

Environment

• macOS (Apple Silicon)
• MLX framework
• Following README setup instructions

Problem 1: Weight conversion instructions misleading

The README says:
python -m heartlib_mlx.utils.convert --src ./ckpt --dst ./ckpt-mlx

But --src needs to point to specific model directories, not the parent:
python -m heartlib_mlx.utils.convert --src ./ckpt/HeartMuLa-oss-3B --dst ./ckpt-mlx/heartmula
--model-type heartmula
python -m heartlib_mlx.utils.convert --src ./ckpt/HeartCodec-oss --dst ./ckpt-mlx/heartcodec --model-type
heartcodec

Problem 2: Memory issues during HeartMuLa conversion

Converting the ~15GB HeartMuLa model fails silently or crashes (exit 137) when loading all weights into
memory at once. Had to modify the conversion script to save weights in chunks.

Problem 3: Model loader only supports single safetensors file

The from_pretrained method expects a single model.safetensors file. Had to modify
src/heartlib_mlx/heartmula/modeling.py to load multiple safetensors files (chunks).

Problem 4: Generation produces poor output

After conversion, generation runs but produces ~1-2 seconds of musical sound followed by a sustained
"ahhh" tone for the remaining duration.

Weight verification shows correct shapes:

• audio_embeddings.weight: (65576, 3072) ✓
• audio_head.weight: (57379, 3072) ✓
• text_embeddings.weight: (128256, 3072) ✓
• Backbone layers: 28 found ✓
• Decoder layers: 3 found ✓

Generation parameters tried:

• --ignore-eos - same result
• --cfg-scale 2.5 - same result

Suspected cause

Possible subtle issue in weight key mapping or generation logic that isn't caught by shape checks. Would
need parity testing against PyTorch original to diagnose further.

[webbrain-one]

Hey! 👋

Thanks for the report. I've opened PR #4 to update the download commands in the README with the fixes you suggested. This should resolve the broken installation steps.

Thanks for helping improve the project! 🙌