Add README.md

README.md

@@ -0,0 +1,143 @@
+---
+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-bf16
+
+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 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` |
+| **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
+python -m venv .venv
+.venv/bin/pip install -U pip
+.venv/bin/pip install -r requirements.txt mlx safetensors huggingface_hub hf_transfer
+
+HF_HUB_ENABLE_HF_TRANSFER=1 .venv/bin/hf download mlx-community/SoulX-Singer-bf16 --local-dir ./models/SoulX-Singer-bf16
+```
+
+Run a short SVS bridge test:
+
+```bash
+PYTORCH_ENABLE_MPS_FALLBACK=1 \
+SOULX_WHISPER_MODEL=pretrained_models/openai__whisper-base \
+.venv/bin/python scripts/inference_mlx_bridge.py \
+  --model ./models/SoulX-Singer-bf16 \
+  --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 \
+.venv/bin/python scripts/inference_mlx_bridge.py \
+  --model ./models/SoulX-Singer-bf16 \
+  --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-bf16`](https://huggingface.co/mlx-community/SoulX-Singer-bf16) | 2.6G | recommended high-quality baseline |
+| [`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},
+}
+```