如何在10分钟内安装并跑通SoulX-Singer:新手保姆级快速上手教程
如何在10分钟内安装并跑通SoulX-Singer:新手保姆级快速上手教程
SoulX-Singer 是一个高保真的零样本歌唱合成(Singing Voice Synthesis, SVS)开源模型:给它一段参考人声,就能用完全相同的声音风格唱出任何新歌,还支持旋律(F0)和乐谱(MIDI)双重控制。本教程手把手带你从零开始,在 10 分钟内完成 SoulX-Singer 的安装、模型下载,并跑通第一次推理 Demo。
SoulX-Singer 是什么:为什么值得关注
在开始动手之前,先花 30 秒了解它的核心能力:
- 🎤 零样本音色克隆:只需一段参考音频,无需微调即可生成未见歌手的演唱
- 🎵 灵活控制:支持旋律(F0 轮廓)与乐谱(MIDI 音符)两种条件控制,音高和节奏更精准
- 🗣️ 多语言合成:覆盖普通话、英语、粤语等,支持跨语言演唱
- 🔄 歌唱变声(SVC):配套的 SoulX-Singer-SVC 模型可直接把一段演唱转成目标音色,无需歌词和 MIDI
它的效果在多语言 SVS 基准上全面领先同类模型,下图是官方技术报告中的性能雷达图对比:
💡 硬件建议:推理脚本默认使用
--device cuda --fp16,建议准备一块 NVIDIA GPU(CUDA 环境),这也是本教程 10 分钟跑通的前提。
10 分钟快速上手:整体路线一览
| 步骤 | 内容 | 预计耗时 |
|---|---|---|
| ① 克隆仓库 | 获取代码与示例音频 | 约 1 分钟 |
| ② 搭建环境 | Conda + Python 3.10 + 依赖 | 约 3 分钟 |
| ③ 下载模型 | SVS 与 SVC 预训练权重 | 3~5 分钟(视网速) |
| ④ 跑通 Demo | 命令行推理或 WebUI | 约 1 分钟 |
第一步:一键克隆 SoulX-Singer 仓库
打开终端,执行以下命令克隆仓库并进入目录:
git clone https://gitcode.com/gh_mirrors/so/SoulX-Singer
cd SoulX-Singer
仓库里已经内置了中英文示例音频和配套的元数据文件(位于 example/audio/ 目录,例如 zh_prompt.json 记录了参考音频的歌词、音素、音高和 F0 信息),跑通 Demo 不需要额外准备数据。
第二步:创建 Python 3.10 环境并安装依赖
如果你还没装过 Conda,先安装 Miniconda,然后执行:
conda create -n soulxsinger -y python=3.10
conda activate soulxsinger
pip install -r requirements.txt
🇨🇳 国内用户加速:如果 pip 下载慢,换用镜像源:
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com
⚠️ 注意两点:
- 依赖清单 requirements.txt 中锁定了
torch==2.2.0,安装前请确认你的 CUDA 版本与之匹配,否则会报 torch 加载错误。 - 环境名建议统一叫
soulxsinger,后续预处理流程文档中也会直接激活这个环境。
第三步:下载预训练模型
安装并升级 huggingface_hub,然后下载两组模型权重:
pip install -U huggingface_hub
# 下载 SoulX-Singer 主模型(SVS + SVC)
hf download Soul-AILab/SoulX-Singer --local-dir pretrained_models/SoulX-Singer
# 下载预处理所需模型(人声分离、音高提取等)
hf download Soul-AILab/SoulX-Singer-Preprocess --local-dir pretrained_models/SoulX-Singer-Preprocess
下载完成后,项目根目录会生成 pretrained_models/SoulX-Singer/(内含 model.pt 和 model-svc.pt)。示例脚本默认就是从这两个路径加载权重的,目录名不要改。
第四步:跑通第一次推理 Demo
命令行方式(最快速验证)
仓库提供了现成的一键脚本,直接执行:
bash example/infer.sh
该脚本会以 example/audio/zh_prompt.mp3 为参考音色,按照 music.json 中的歌词和乐谱信息合成新歌曲,结果保存在 example/generated/music/ 目录,打开听听看——恭喜你,已经跑通了!
SVC 变声 Demo 也同样一条命令搞定:
bash example/infer_svc.sh
它会把目标演唱直接转换参考音色的声音,输出在 example/generated/music_svc/。
📌 示例脚本的核心参数(模型路径、配置文件 soulxsinger.yaml、
--auto_shift自动调音等)都写在 example/infer.sh 中,之后想换示例音频,照着改路径即可。
WebUI 方式(更适合新手)
如果你更喜欢图形界面,直接在项目根目录执行:
# 歌唱合成 SVS 界面
python webui.py
# 歌唱变声 SVC 界面(音频转音频)
python webui_svc.py
启动后浏览器会自动打开 Gradio 界面,内置了普通话、英语、粤语三组示例(定义在 webui.py 的 EXAMPLES_LIST 中),点击示例按钮即可一键试听。
常见问题与避坑指南
| 问题 | 解决方法 |
|---|---|
| pip 下载极慢 | 使用上面的阿里云镜像源安装 |
| 报 torch / CUDA 相关错误 | 确认 GPU 驱动与 torch 2.2.0 对应的 CUDA 版本匹配 |
hf download 报错 |
先执行 pip install -U huggingface_hub 升级工具 |
| 想用自己的音频生成 | 需要先跑预处理流水线生成元数据,见下文 |
🎼 用自己的音乐合成? 仓库内置了完整的预处理工具链(preprocess/pipeline.py),一条命令即可完成人声分离、F0 提取、歌词识别和音高转录:
bash example/preprocess.sh
详细说明见 preprocess/README.md。官方特别提醒:自动转录的歌词与音符对齐可能有误差,对合成质量影响较大,建议用仓库内置的 MIDI Editor(位于 preprocess/tools/midi_editor/)手动校正后再推理。
项目结构速查表
跑通之后,这几个目录会是你最常打交道的地方:
- soulxsinger/:模型主体,含配置与音素表
- cli/inference.py:SVS 推理入口(WebUI 也是调用它)
- example/:示例音频、元数据与一键脚本
- preprocess/:歌词与乐谱预处理流水线
- webui.py / webui_svc.py:两个图形界面入口
总结
回顾一下这条 10 分钟路线:克隆仓库 → 建 soulxsinger 环境装依赖 → 下载两组模型权重 → bash example/infer.sh 听第一首歌。至此,SoulX-Singer 零样本歌唱合成工具已完全就绪。下一步不妨试试 WebUI 里切换不同语言组合,或运行 example/preprocess.sh 用自己的歌曲生成元数据,体验"给任何歌换声音"的完整流程。
