Metadata-Version: 2.4
Name: diffsinger-utau
Version: 0.3.8
Summary: DiffSinger UTAU inference toolkit with CLI
Author-email: Bingcheng Hu <bingcheng@nyu.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/bingcheng1998/diffsinger_utau
Project-URL: Repository, https://github.com/bingcheng1998/diffsinger_utau
Project-URL: Issues, https://github.com/bingcheng1998/diffsinger_utau/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: setuptools
Requires-Dist: numpy<2,>=1.21; python_version < "3.12"
Requires-Dist: scipy<1.14,>=1.7.3; python_version < "3.12"
Requires-Dist: numpy>=1.26; python_version >= "3.12"
Requires-Dist: scipy>=1.11; python_version >= "3.12"
Requires-Dist: librosa<1.0,>=0.8
Requires-Dist: PyYAML
Requires-Dist: onnxruntime<1.17,>=1.16.0; python_version < "3.12"
Requires-Dist: onnxruntime>=1.17; python_version >= "3.12"
Requires-Dist: torch<2.9,>=2.0; python_version < "3.14"
Requires-Dist: torch>=2.9; python_version >= "3.14"
Requires-Dist: pypinyin>=0.50
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Dynamic: license-file

# DiffSinger UTAU

DiffSinger UTAU 推理工具包，提供命令行工具和 Python API 进行语音合成。
基于 [diffsinger](https://github.com/openvpi/DiffSinger) 项目，兼容 OpenUtau 声库。

## 功能特性

- 完整的 DiffSinger 推理流程：时长预测 → 音高预测 → 方差预测 → 声学模型 → 声码器
- 支持多语言和多说话人
- 提供命令行工具和 Python API
- 支持音高移调、性别控制等参数调节

## 安装

由于[历史原因](https://github.com/openvpi/DiffSinger/blob/main/docs/GettingStarted.md#deployment)曾强依赖 PyTorch 1.13，但目前已支持 Python 3.9 及以上版本（含 3.9 – 3.14，全部版本均已实测推理通过）。

### 从 PyPI 安装

```bash
pip install diffsinger-utau
```
### 从源码安装

```bash
# 克隆仓库
git clone https://github.com/bingcheng1998/diffsinger_utau.git
cd diffsinger-utau

# 创建虚拟环境（推荐使用 Python 3.9 及以上版本，已验证 3.9 – 3.14）
conda create -n diffsinger python=3.12
conda activate diffsinger

# 安装依赖
pip install -e .
```

## 使用方法

### 下载声库

什么是声库？声库可以理解为歌唱者的模型，有着各自的音色等特性。

社区提供了[DiffSinger自制声库分享](https://docs.qq.com/sheet/DQXNDY0pPaEpOc3JN)，如果你不确定下载哪个，推荐从[zhibin club](https://www.zhibin.club/)下载[姜柯JiangKe](https://pan.quark.cn/s/254f030af8cb#/list/share/0929019064004907b7b95212c03066ed)声库开始尝试。

下载声库后，需要解压，解压缩后的路径可以作为程序参数进行推理。

### 下载示例 ds 文件

什么是 ds 文件？ds 文件是修改后缀后的标准json文件，内容为歌曲的内容，包含歌词、音高等内容。

社区提供了[示例文件](https://github.com/openvpi/DiffSinger/tree/main/samples)，建议从示例文件推理开始尝试。

### 命令行工具

```bash
# 基本用法
dsutau diffsinger_utau/samples/07_春江花月夜.ds

# 指定语音库和参数
dsutau diffsinger_utau/samples/07_春江花月夜.ds \
  --voice-bank /Users/bc/Music/Singers/Junninghua_v1.4.0_DiffSinger_OpenUtau  \
  --lang zh \
  --speaker "jiangke" \
  --key-shift 2 \
  --pitch-steps 10 \
  --variance-steps 10 \
  --acoustic-steps 20 \
  --gender 0.0 \
  --output output/pred_all
```

### Python API

```python
from pathlib import Path
from diffsinger_utau.voice_bank import PredAll
from diffsinger_utau.voice_bank.commons.ds_reader import DSReader

# 初始化预测器
voice_bank = Path("artifacts/JiangKe_DiffSinger_CE_25.06")
predictor = PredAll(voice_bank)

# 读取 DS 文件
ds = DSReader("samples/07_春江花月夜.ds").read_ds()[0]

# 修改歌词
ds.replace("SP 可爱小狗汪汪叫 SP")

# 执行完整推理
results = predictor.predict_full_pipeline(
    ds=ds,
    lang="zh",
    speaker=None,  # 随机选择说话人
    key_shift=0,
    pitch_steps=10,
    variance_steps=10,
    acoustic_steps=50,
    gender=0.0,
    output_dir="output/pred_all",
    save_intermediate=True,
)

print(f"生成音频: {results['audio_path']}")
```

## 参数说明

- `--voice-bank`: 语音库目录路径
- `--lang`: 语言代码（默认: zh）
- `--speaker`: 说话人名称（不指定则随机选择）
- `--key-shift`: 音高移调半音数（默认: 0）
- `--pitch-steps`: 音高扩散采样步数（默认: 10）
- `--variance-steps`: 方差扩散采样步数（默认: 10）
- `--acoustic-steps`: 声学模型扩散采样步数（默认: 50）
- `--gender`: 性别参数 [-1, 1]，-1为男性化，1为女性化（默认: 0）
- `--output`: 输出目录（默认: output/pred_all）
- `--no-intermediate`: 不保存中间结果文件

## 输出文件

推理完成后会在输出目录生成以下文件：

- `step1_duration.ds`: 时长预测结果
- `step2_pitch.ds`: 音高预测结果
- `step3_variance.ds`: 方差预测结果
- `step4_mel_data.json`: Mel数据（JSON格式）
- `step5_final_audio.wav`: 最终音频文件
- `complete_prediction.ds`: 完整预测结果

## 系统要求

- Python 3.9 – 3.14（全部版本已实测推理通过；onnxruntime 新版已修复 Apple Silicon 上的 segfault，原生支持 3.12/3.13/3.14 的 macOS arm64 wheel）
- 支持的操作系统：Windows, macOS, Linux
- 内存：建议 8GB 以上
- 存储：至少 2GB 可用空间

### 各 Python 版本实测依赖组合（macOS arm64）

| Python | numpy | scipy | onnxruntime | torch |
|--------|-------|-------|-------------|-------|
| 3.9 – 3.11 | 1.26.x | 1.13.x | 1.16.x | 2.8.x |
| 3.12 – 3.13 | 2.x | 1.11+ | 1.29.x | 2.8.x |
| 3.14 | 2.5.x | 1.11+ | 1.29.x | 2.13.x |

> 说明：3.9–3.11 的 onnxruntime 仅 1.16.x 提供 arm64 wheel，且要求 numpy<2、scipy<1.14；
> torch 锁定 2.8.x 是因为 >=2.9（如 2.13）在 3.10 上与 onnxruntime 1.16.x 推理崩溃，
> 而 torch 2.8 无 3.14 wheel，故 3.14 必须用 >=2.9。

## 依赖项

- numpy>=1.21,<2（Python < 3.12）；numpy>=1.26（Python >= 3.12）
- scipy>=1.7.3,<1.14（Python < 3.12）；scipy>=1.11（Python >= 3.12）
- librosa>=0.8,<1.0
- PyYAML>=6.0
- onnxruntime>=1.16.0,<1.17（Python < 3.12）；onnxruntime>=1.17（Python >= 3.12）
- torch>=2.0,<2.9（Python < 3.14）；torch>=2.9（Python >= 3.14）
- pypinyin>=0.50

## 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 代码格式化
black voice_bank/

# 代码检查
flake8 voice_bank/
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### v0.3.8
- torch 按 Python 版本区分：3.9–3.13 锁 2.8.x（torch>=2.9 在 3.10 上 segfault）；3.14 用 >=2.9（torch 2.8 无 3.14 wheel）
- 确认 3.12/3.13 可用 onnxruntime 1.29.0（Apple Silicon segfault 已修复），实测推理通过

### v0.3.7
- torch 锁定 2.8.x（torch>=2.9 如 2.13 在 Python 3.10 上与 onnxruntime 1.16.x 推理崩溃，实测 2.8.0 正常）

### v0.3.6
- 3.9–3.11 恢复 0.3.2 已验证组合（numpy<2 / scipy<1.14 / onnxruntime 1.16.x），torch 保持最新 2.x（1.x 在 3.10 segfault）；3.12+ 放开到最新库（numpy 2.x / scipy>=1.11 / onnxruntime>=1.17）

### v0.3.5
- 按 numpy ABI 兼容性细分：3.9–3.11 锁 numpy<2（onnxruntime 1.16.x 仅兼容 numpy 1.x，numpy 2.x 会 segfault）；3.12+ 放开 numpy 2.x。onnxruntime 仍按 wheel 可用性区分（1.16.x / >=1.17）。torch 全版本用最新 2.x

### v0.3.4
- 激进放宽依赖：全版本使用最新 torch>=2.0、numpy>=1.26、scipy>=1.11
- onnxruntime 按 wheel 可用性区分：3.9–3.11 用 1.16.x（唯一提供 arm64 wheel 的版本），3.12+ 用最新（>=1.17，待实测 Apple Silicon 是否仍 segfault）

### v0.3.3
- 放开支持范围至 Python 3.9 – 3.14（onnxruntime 新版已修复 Apple Silicon segfault，原生支持 3.12/3.13/3.14 的 macOS arm64 wheel）
- 按 Python 版本细化依赖约束：3.9–3.11 沿用已验证组合（numpy<2 / scipy<1.14 / onnxruntime 1.16.x / torch 1.x），3.12+ 使用 numpy 2.x / scipy>=1.11 / onnxruntime>=1.17 / torch>=2.0

### v0.3.2
- 明确支持范围：Python 3.9 – 3.11（Apple Silicon 上 onnxruntime<1.17 仅支持到 3.11，且 >=1.17 会 segfault）

### v0.3.1
- 锁定依赖版本范围，修复在 Apple Silicon 上的运行崩溃（onnxruntime<1.17、numpy<2、scipy<1.14）
- 最低支持 Python 3.9（`importlib.resources.files` 需 3.9+）

### v0.3.0
- 支持 Python 3.8 及以上版本（测试兼容至 Python 3.14）
- 使用 `importlib.resources` 替换已废弃的 `pkg_resources`

### v0.2.1
- 内置换词API，可以直接替换歌词
- 提升声库兼容性

### v0.1.2
- 兼容并测试通过声库[JiangKe, LuoXi, YunYe, ZhiBin](https://pan.quark.cn/s/254f030af8cb#/list/share/0929019064004907b7b95212c03066ed)

### v0.1.0
- 初始版本
- 支持完整的 DiffSinger 推理流程
- 提供命令行工具和 Python API
