README.md

---
license: apache-2.0
library_name: mlx
pipeline_tag: text-to-audio
base_model:
- Soul-AILab/SoulX-Singer
tags:
- mlx
- apple-silicon
- singing-voice-synthesis
- singing-voice-conversion
- soulx-singer
---

# SoulX-Singer

Apple MLX safetensors checkpoint for [`Soul-AILab/SoulX-Singer`](https://huggingface.co/Soul-AILab/SoulX-Singer), including both SoulX-Singer SVS and SoulX-Singer-SVC weights.

Collection: [https://huggingface.co/collections/mlx-community/soulx-singer-mlx-6a1c0525d0911ea400102840](https://huggingface.co/collections/mlx-community/soulx-singer-mlx-6a1c0525d0911ea400102840)

This default repository is the bf16 variant of [`mlx-community/SoulX-Singer-bf16`](https://huggingface.co/mlx-community/SoulX-Singer-bf16).

This is not a pure end-to-end MLX audio runtime yet. The weights are converted to an MLX-friendly safetensors layout, while full audio generation currently uses the official PyTorch model structure through [`ailuntx/SoulX-Singer-MLX`](https://github.com/ailuntx/SoulX-Singer-MLX).

## TL;DR

| | |
|---|---|
| **Precision** | `bf16` default |
| **Disk** | 2.6G |
| **Components** | `svs/` and `svc/` |
| **Runtime / bridge** | [`ailuntx/SoulX-Singer-MLX`](https://github.com/ailuntx/SoulX-Singer-MLX) |
| **Official model** | [`Soul-AILab/SoulX-Singer`](https://huggingface.co/Soul-AILab/SoulX-Singer) |
| **Official code** | [`Soul-AILab/SoulX-Singer`](https://github.com/Soul-AILab/SoulX-Singer) |

## Quick Start

```bash
git clone https://github.com/ailuntx/SoulX-Singer-MLX.git
cd SoulX-Singer-MLX
conda create -n soulxsinger-mlx -y python=3.10
conda activate soulxsinger-mlx
python -m pip install -U pip
python -m pip install -r requirements.txt mlx safetensors huggingface_hub hf_transfer

HF_HUB_ENABLE_HF_TRANSFER=1 hf download mlx-community/SoulX-Singer --local-dir ./models/SoulX-Singer
hf download openai/whisper-base --local-dir pretrained_models/openai__whisper-base
```

Run a short SVS bridge test:

```bash
PYTORCH_ENABLE_MPS_FALLBACK=1 \
SOULX_WHISPER_MODEL=pretrained_models/openai__whisper-base \
python scripts/inference_mlx_bridge.py \
  --model ./models/SoulX-Singer \
  --component svs \
  --device mps \
  --prompt_wav_path example/audio/zh_prompt.mp3 \
  --prompt_metadata_path example/audio/zh_prompt.json \
  --target_metadata_path example/audio/zh_target.json \
  --control melody \
  --n_steps 1 \
  --cfg 1 \
  --save_dir outputs_mlx_bridge/svs
```

Run an SVC bridge test:

```bash
PYTORCH_ENABLE_MPS_FALLBACK=1 \
SOULX_WHISPER_MODEL=pretrained_models/openai__whisper-base \
python scripts/inference_mlx_bridge.py \
  --model ./models/SoulX-Singer \
  --component svc \
  --device mps \
  --prompt_wav_path example/audio/zh_prompt.mp3 \
  --target_wav_path example/audio/music.mp3 \
  --prompt_f0_path example/audio/zh_prompt_f0.npy \
  --target_f0_path example/audio/music_f0.npy \
  --n_steps 1 \
  --cfg 1 \
  --save_dir outputs_mlx_bridge/svc
```

## Variants

| Variant | Disk | Notes |
|---|---:|---|
| [`SoulX-Singer-4bit`](https://huggingface.co/mlx-community/SoulX-Singer-4bit) | 774M | smallest checkpoint; MLX affine quantized |
| [`SoulX-Singer-8bit`](https://huggingface.co/mlx-community/SoulX-Singer-8bit) | 1.4G | smaller checkpoint; MLX affine quantized |
| [`SoulX-Singer`](https://huggingface.co/mlx-community/SoulX-Singer) | 2.6G | default bf16 checkpoint |
| [`SoulX-Singer-bf16`](https://huggingface.co/mlx-community/SoulX-Singer-bf16) | 2.6G | explicit bf16 checkpoint |
| [`SoulX-Singer-fp32`](https://huggingface.co/mlx-community/SoulX-Singer-fp32) | 5.6G | full-precision conversion baseline |

## Layout

```text
SoulX-Singer-bf16/
|-- config.json
|-- config.yaml
|-- mlx_manifest.json
|-- svs/
|   |-- model.safetensors.index.json
|   `-- model-00001-of-000xx.safetensors
`-- svc/
    |-- model.safetensors.index.json
    `-- model-00001-of-000xx.safetensors
```

This repo has 11 SVS shard(s) and 11 SVC shard(s).

## Validation

Local Apple Silicon validation:

| Test | Result |
|---|---|
| Official PyTorch/MPS SVS, `n_steps=1` | generated 6.71s WAV, 24kHz mono |
| `SoulX-Singer-bf16` component load | `svs/` and `svc/` safetensors are indexed and loadable |
| bf16 PyTorch bridge SVS, `n_steps=1` | generated 6.71s WAV, 24kHz mono, RMS about `0.029` |

For quantized checkpoints, the bridge loader dequantizes MLX affine tensors into the official PyTorch module shapes for compatibility testing. Native all-MLX inference is planned as a later runtime step.

## License

The converted weights follow the upstream SoulX-Singer Apache-2.0 release.

## Citation

```bibtex
@misc{soulx-singer-mlx,
  title  = {SoulX-Singer-MLX: Apple MLX safetensors port of SoulX-Singer},
  author = {ailuntx},
  year   = {2026},
  url    = {https://github.com/ailuntx/SoulX-Singer-MLX},
}

@misc{soulxsinger,
  title={SoulX-Singer: Towards High-Quality Zero-Shot Singing Voice Synthesis},
  author={Jiale Qian and Hao Meng and Tian Zheng and Pengcheng Zhu and Haopeng Lin and Yuhang Dai and Hanke Xie and Wenxiao Cao and Ruixuan Shang and Jun Wu and Hongmei Liu and Hanlin Wen and Jian Zhao and Zhonglin Jiang and Yong Chen and Shunshun Yin and Ming Tao and Jianguo Wei and Lei Xie and Xinsheng Wang},
  year={2026},
  eprint={2602.07803},
  archivePrefix={arXiv},
  primaryClass={eess.AS},
  url={https://arxiv.org/abs/2602.07803},
}
```