基于 DDSP 的 VST 乐器合成模型训练工具，在 Docker 容器中运行，支持 GPU 加速。
自动将音频文件转换为 TFRecord 训练数据集、使用 DDSP 框架训练 VST 合成模型并导出为 TFLite 格式，
将你的乐器录音文件放入 dataset/ 目录：
dataset/
├── violin_01.wav
├── violin_02.wav
└── violin_03.mp3
数据建议：
- 时长：10-30 分钟（越长效果越好）
- 质量：干净的单音轨录音，无混响/效果器
- 内容：覆盖乐器的常用音域和演奏技法
如果录音文件是长段连续演奏，可先用切分工具按静音和片段时长自动分割，增加数据集文件数量：
# 将 ./dataset 下的长音频切分成 6~15 秒的短片段，输出到 ./dataset_split
python split_audio.py --input-dir ./dataset --output-dir ./dataset_split
# 自定义时长范围
python split_audio.py --input-dir ./dataset \
--output-dir ./dataset_split \
--min-duration 8 \
--max-duration 20
# 先预览切分计划，不实际生成文件
python split_audio.py --input-dir ./dataset --dry-run
切分参数说明：
| 参数 | 默认值 | 说明 |
|---|---|---|
--input-dir | ./dataset | 输入音频目录 |
--output-dir | ./dataset_split | 输出目录 |
--min-duration | 6.0 | 最小片段时长（秒），短于此值会合并到相邻片段 |
--max-duration | 15.0 | 最大片段时长（秒），超出此值会进一步切分 |
--silence-threshold | -40 | 静音检测阈值（dBFS） |
--silence-min-duration | 0.4 | 静音最小时长（秒），小于此值的静音不切分 |
--sample-rate | 0 | 输出采样率，0 表示使用输入音频的原始采样率 |
--format | wav | 输出格式（wav/mp3/flac/ogg） |
--no-merge-last-segment | — | 不合并过短的最后一个片段 |
--dry-run | — | 仅预览切分计划，不生成文件 |
切分完成后，将输出的片段目录作为训练输入即可。
# 构建 Docker 镜像
docker build -t ddsp-vst .
# 运行训练（挂载 dataset 目录）
docker run --gpus all \
-v /path/to/your/dataset:/workspace/dataset \
-v ./output:/workspace/output \
ddsp-vst \
--audio-dir /workspace/dataset \
--name my_instrument
训练完成后，模型会导出到 output/ddsp-training-<timestamp>/ddsp_vst_model.zip：
ls -la output/
# output/ddsp-training-2026-05-13-1430/
# └── my_instrument.zip ← 这就是你要的模型文件
将 my_instrument.zip 解压后放入 DDSP 插件的 model 目录即可使用。
python train_ddsp_vst.py --help
| 参数 | 说明 | 默认值 |
|---|---|---|
--audio-dir | 音频文件目录 | ./dataset |
--name | 模型名称 | ddsp_vst_model |
--steps | 训练步数（推荐 30000-50000） | 30000 |
--batch-size | 训练批次大小（L40 可增至 64-128） | 16 |
--learning-rate | 初始学习率（loss 发散至 NaN 时降低此值） | 0.001 |
--grad-clip-norm | 梯度裁剪阈值（loss 发散时适当增大） | 3.0 |
--ignore-previous | 忽略已有检查点重新训练 | 关闭 |
--sample-rate | 采样率 | 16000 |
--output-dir | 输出目录 | /workspace/output |
# 基础用法
python train_ddsp_vst.py --audio-dir ./dataset --name guitar
# 自定义训练步数
python train_ddsp_vst.py --audio-dir ./audio --steps 50000 --name piano
# 忽略之前的训练结果从头开始
python train_ddsp_vst.py --audio-dir ./dataset --ignore-previous --name flute
# 自定义输出目录和采样率
python train_ddsp_vst.py --audio-dir ./recordings --output-dir ./results --sample-rate 22050 --name saxophone
# 训练发散(NaN)时降低学习率并增大梯度裁剪
python train_ddsp_vst.py --audio-dir ./dataset --name my_model --learning-rate 0.0003 --grad-clip-norm 5.0
# 高 GPU 利用率
python train_ddsp_vst.py --audio-dir ./dataset --name my_model --batch-size 64 --learning-rate 0.0005
# 高训练轮数
python train_ddsp_vst.py --audio-dir ./dataset --name my_model --batch-size 48 --steps 50000
整个训练分为三个阶段：
Stage 1: 数据准备 (~20-30 min/10min音频)
音频文件 → TFRecord 格式
Stage 2: 模型训练 (~30-60 min, 取决于 steps 和 GPU)
TFRecord → DDSP-VST 模型检查点
Stage 3: 模型导出 (~2-5 min)
检查点 → TFLite 模型 (.zip)
.
├── Dockerfile # Docker 构建配置
├── train_ddsp_vst.py # 训练脚本（主程序）
├── split_audio.py # 音频切分工具
├── start_tensorboard.sh # TensorBoard 监控脚本
├── export_checkpoint.sh # 模型导出脚本
├── Train_DDSP_VST.ipynb # Jupyter Notebook 版本
├── .cnb.yml # CNB 云开发环境配置
├── dataset/ # 放置原始音频文件
├── dataset_split/ # 切分后的音频片段（运行 split_audio.py 后生成）
└── output/ # 训练输出（运行后生成）
└── ddsp-training-*/
├── checkpoints/ # 模型检查点
├── <model_name>/ # 导出的模型
└── <model_name>.zip # 打包的模型文件
本项目已配置 CNB 云原生构建，可一键启动 GPU 开发环境：
- Fork 本仓库到 CNB 平台
- 自动分配 NVIDIA L40 GPU
- 将音频数据上传至
dataset/目录 - 运行训练命令即可
训练过程中可使用 TensorBoard 实时查看 loss 曲线：
# 启动 TensorBoard（默认端口 6006）
./start_tensorboard.sh
# 指定端口
./start_tensorboard.sh --port 6007
在 CNB VSCode 环境中，使用 "Ports" 面板转发端口 6006，即可通过浏览器访问 TensorBoard 仪表盘。
# 查看有哪些训练目录和检查点
ls -la /workspace/output/ddsp-training-*/
# 导出最新训练目录的最新检查点（自动检测）
./export_checkpoint.sh
# 指定要导出的训练目录和具体检查点（推荐，选 NaN 之前的）
./export_checkpoint.sh \
--model-dir /workspace/output/ddsp-training-2026-05-13-1418 \
--checkpoint ckpt-26100 \
--name dadada-F04A
Q: 训练需要多长时间？ A: 10 分钟音频 + 30000 步训练，在 L40 GPU 上约需 60-90 分钟。
Q: 显存不够怎么办？
A: 减小 batch size：通过命令行参数或修改 train_ddsp_vst.py 中的 DEFAULT_BATCH_SIZE。
Q: 可以用 MP3 吗？
A: 可以，脚本支持 .wav 和 .mp3 格式。但 WAV 无损音质更佳。
Q: 训练出现 loss = nan 怎么办？ A: 这是训练发散现象。使用降低的学习率和增大的梯度裁剪重新训练：
python train_ddsp_vst.py --audio-dir ./dataset --name my_model \
--ignore-previous --learning-rate 0.0003 --grad-clip-norm 5.0
如果仍然发散，继续降低 --learning-rate 至 0.0001 或增大 --grad-clip-norm 至 10.0。
Q: 如何提高模型质量？ A: 增加训练音频时长（20-30+ 分钟）、增加训练步数（50000+）、确保音频干净无杂音。
基于 Google DDSP，遵循 Apache License 2.0。
