Metadata-Version: 2.4
Name: RvcPyInfer
Version: 0.2.2
Summary: Rvc 的 ONNX 模型导出格式推理实现
Project-URL: Homepage, https://github.com/TwoCreepers/RvcPyInfer
Project-URL: Repository, https://github.com/TwoCreepers/RvcPyInfer
Author: 观赏鱼
License-Expression: MIT
Requires-Python: >=3.13
Requires-Dist: numpy>=2.3
Requires-Dist: pyworld>=0.3.5
Requires-Dist: samplerate>=0.2.4
Requires-Dist: soundfile>=0.14.0
Provides-Extra: cpu
Requires-Dist: onnxruntime>=1.27.0; extra == 'cpu'
Provides-Extra: cuda
Requires-Dist: onnxruntime-gpu>=1.27.0; extra == 'cuda'
Provides-Extra: dev
Requires-Dist: pyright>=1.1.411; extra == 'dev'
Requires-Dist: ruff>=0.15.21; extra == 'dev'
Provides-Extra: dml
Requires-Dist: onnxruntime-directml>=1.24.4; extra == 'dml'
Provides-Extra: index
Requires-Dist: faiss-cpu>=1.14.3; extra == 'index'
Provides-Extra: openvino
Requires-Dist: openvino>=2026.2.1; extra == 'openvino'
Provides-Extra: optimize
Requires-Dist: onnx>=1.22.0; extra == 'optimize'
Requires-Dist: onnxsim>=0.6.5; extra == 'optimize'
Description-Content-Type: text/markdown

# [RvcPyInfer](https://github.com/TwoCreepers/RvcPyInfer)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://mit-license.org/)  
[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)  
[![PyPI Version](https://img.shields.io/pypi/v/RvcPyInfer)](https://pypi.org/project/RvcPyInfer/)  
![ONNX](https://img.shields.io/badge/ONNX-supported-blue)  

[RVC](https://github.com/RVC-Project/Retrieval-based-Voice-Conversion-WebUI) 的 ONNX 模型导出格式推理实现。  

- 支持原 RVC 项目的 ONNX 模型推理。  
- 跨平台支持多种推理引擎（CPU, CUDA, DirectML, OpenVINO）。  
- 提供 Windows 下一键导出 ONNX 模型的 CLI 工具。  
- 兼容原项目的 `.index` 特征索引文件。  

## Python 版本需求
本项目要求 Python 版本 `>= 3.13`。由于项目代码中使用了 `Python 3.12+` 引入的 `TypeParam` 等现代语法特性，因此无法向下兼容更低版本的 Python。  
~~并且推理真的很难测试欸。~~

## 安装
本库已上传至 [PyPI](https://pypi.org/project/RvcPyInfer/)，你可以直接使用我们构建好的轮子。  
`pip` 安装示例：  
```shell
pip install RvcPyInfer[cpu]
```
使用 `uv` 添加到项目依赖示例：  
```shell
uv add RvcPyInfer[cpu]
```

## 关于特征模型
你可以在[这里](https://huggingface.co/NaruseMioShirakana/MoeSS-SUBModel/tree/main)找到 `MoeSS` 使用的 `onnx` 特征模型。它们是通用的。  
**通常情况下最常见的 `v2` 版本的生成器模型使用的是 `vec-768-layer-12.onnx`**

## 关于推理引擎
你可能已经看到了那个未安装任何推理引擎的警告或者错误。  
请在安装命令后面添加 `[xxx]` 来安装可选依赖。  
例如：  
```shell
pip install RvcPyInfer[dml]
```
目前我们支持以下推理引擎：

- `onnxruntime`
  - `[cpu]`：ONNX Runtime (CPU)，通用
  - `[cuda]`：ONNX Runtime (CUDA)，Nvidia GPU 加速
  - `[dml]`：ONNX Runtime (DML)，Windows DirectML 加速
- `openvino`
  - `[openvino]`：OpenVINO，Intel 硬件加速

请注意 `onnxruntime` 的三个可选依赖是互斥的，你只能选择其中的一个。  
关于 `openvino` 的 `IR` 格式，本库会转换 `IR` 格式并存档在 `.onnx` 同目录下的同名文件中，以便在下一次加载时加速，该行为目前无法被禁用。

## 关于特征索引
原项目的 `.index` 文件可直接使用，无需转换。  
但你需要使用 `[index]` 来安装我们需要用于读取特征索引的依赖—— `faiss`。  
例如同时安装特征索引支持和 `CPU`：  
```shell
pip install RvcPyInfer[cpu,index]
```

## 快速使用
一个简单的示例：
```python
import RvcPyInfer

context = RvcPyInfer.RvcContext() # 创建一个上下文

task = context.build_task(
    "./你的特征模型.onnx",
    "./你的 Rvc 生成器模型.onnx",
    48000, # 你的 Rvc 生成器模型的生成采样率
    "./你要推理的源文件.wav", # 可以填多个源文件
    # 后续可选参数需显式写明名称，例如: 
    sid=1,    # 说话者 id，一般情况下就是 0
    seed=4321 # 噪声种子，默认 1234
)
task.run_and_save(
    "./你要保存的结果.wav" # 请注意，它不会自动创建目录
)
```

## build_task 函数和原项目有关的参数
由于参数过多，这里只介绍一些我认为你应该知道的。

### sid: int = 0
说话者 id，与你训练模型填的 sid 一致，一般为0。

### seed: int | None = 1234
生成噪声用的种子，一般可不管，用于可复现~~和抽卡~~。

### index_path: PathLike | None = None
特征索引的路径，可直接用原项目生成的 `added.index`

### index_rate: float = 0.33
使用特征索引的比例，越大音色越接近训练集数据，但也有可能会出现口糊等情况。  
**推荐范围: [0.0, 1.0]**

### index_consonant_protect: float = 0.66
对清音的原始特征进行保护，不受特征索引影响的比例，与原项目的 `protect` 参数对应，关系为 `consonant_protect=1-protect`。  
**对于小于 `0.5` 的值将直接跳过处理。**  
**推荐范围: [0.0, 1.0]**

### f0_median_filter_win_size: int = -1
对 `f0` 值进行中值滤波的窗口大小，小于 3 则不进行中值滤波，必须为奇数，与原项目的 `filter_radius` 参数对应。

### rms_match_mix: float = 1.0
输出音频匹配输入音频 `rms` 包络的匹配率，通常来说：越大输出音频越接近输入音频的音量。  
**推荐范围: [0.0, 1.0]**

## f0 提取方法
你应该已经注意到了 `build_task` 函数的 `f0extract_algorithm` 参数。  
它是一个 `Literal["dio", "harvest", "rmvpe"]`  
- `dio`: 默认选择。精度在干声下足够看，很快
- `harvest`: 精度相对 `dio` 更高，但只能使用 CPU 计算，导致速度甚至不如 `rmvpe`
- `rmvpe`: 精度非常高，有一定抗和声能力，可以使用 `GPU` 加速，但需要单独下载 [`RMVPE.onnx`](https://huggingface.co/NaruseMioShirakana/MoeSS-SUBModel/blob/main/RMVPE.onnx)，并给到 `RvcContext(rmvpe="<你的 rmvpe 模型路径>")`。**如果不怕麻烦的话非常推荐。**

为什么只有这些？我的 `pm`、`fcpe`、`crepe` 呢？  
`pm` 是 `parselmouth` 库的传统算法方法，效果和 `pyworld` 不会差很多，并且额外引入不必要的 `parselmouth` 依赖。  
~~`fcpe` 和 `crepe` 是因为懒。~~  

## CLI
我们已经预制了一些 `CLI` 在库中了，并随库一并打包。  
以下是库内置的命令：  
- `rvc-infer`：用以快速推理模型而无需编写代码
- `rvc-model`：与模型相关的命令

### rvc-infer
最简格式： `rvc-infer --vec-model <你的特征模型路径> --gen-model <你的生成器模型路径> --gen-model-sr <你的生成器模型的输出采样率> -i <输入音频文件路径> -o <输出音频文件路径>`  
**Tips：可出现多个 -i 和 -o，只要它们的数量一致，多个 -i 和 -o 按出现顺序一一对应。**

### rvc-model
该命令用于查看原项目的 `.pth` 模型的生成采样率，和在 `Windows` 上快速导出 onnx 模型，以及优化导出的 onnx 模型。

#### rvc-model show-sr
安全地查看原项目的 `.pth` 模型的采样率  
格式： `rvc-model show-sr -m <你的pth模型路径>`  

#### rvc-model export
导出 ONNX 模型  
**⚠️注意：你必须安装原项目的整合包或至少有一个能运行原项目的环境以便 `PyTorch` 导出 `.onnx` 模型。**  
它并不依赖项目内置的 `tools/export_onnx.py` 我们有自己的方法。  
~~事实上原项目的 export_onnx.py 甚至没有做 v2 版本的支持~~  
格式： `rvc-model export -m <你的pth模型路径> -t <你希望输出到哪> -r <rvc 原项目的根路径> --runtime <可选的导出用的 python 解释器路径，默认使用 rvc 原项目整合包自带的解释器>`  

#### rvc-model optimize
优化导出的 ONNX 模型  
**⚠️注意：你必须安装 [optimize] 可选依赖，否则该子命令将不会出现在 `-h` 输出上**  
格式： `rvc-model optimize -m <你的 onnx 模型路径> -t <你希望输出到哪>`  

## 未来的计划
暂无，欢迎各位提出 issue  

## 许可证
在文件头部或文件所在目录未有额外说明的情况下，本项目代码部分使用 [`MIT`](https://mit-license.org/) 许可证授权于你，非代码部分使用 `CC BY 4.0` 授权于你。  

## 🎉鸣谢

- [原项目组的所有成员](https://github.com/RVC-Project)  
没有TA们的付出就没有 RVC 模型，该项目也不会出现  
- [提前打好特征模型 ONNX 的 MoeSS](https://github.com/Miuzarte/MoeSS)  
省去了诸多导出特征模型的麻烦  
- [帮了作者很多的 GLM AI](https://chatglm.cn)  
省去了很多查资料和写 CLI 的时间  