OpenVoice 即时声音克隆实战指南：从 V1 风格控制到 V2 原生多语言克隆

OpenVoice 是 MIT 与 MyShell 联合开源的即时声音克隆（Instant Voice Cloning）音频基础模型，只需一段参考音频即可复刻该说话人的音色，并以该音色合成多种语言、多种风格的语音。本文基于仓库 README 与配套使用文档，覆盖 V1/V2 版本的核心能力、Linux 安装步骤、基音说话人（Base Speaker）与音色转换器（Tone Color Converter）的调用方式、V2 多语言支持，以及官方 QA 中总结的常见问题排查方法，帮助读者从零完成本地部署并深入理解其源码实现。

一、OpenVoice 能做什么：V1 与 V2 的能力边界

README 将 OpenVoice 的优势概括为三个方面，这也是理解整个仓库设计的关键：

1. 精确的音色克隆（Accurate Tone Color Cloning）：OpenVoice 能精确复刻参考音频的音色（tone color），并支持以该音色生成多种语言和口音的语音。
2. 灵活的语音风格控制（Flexible Voice Style Control）：可以细粒度控制情绪、口音等风格，以及节奏、停顿、语调（rhythm, pauses, intonation）等风格参数。
3. 零样本跨语言克隆（Zero-shot Cross-lingual Voice Cloning）：生成语音的语言、参考语音的语言都不需要出现在大规模多说话人多语言（MSML）训练集中。

V1 的三点优势在 README.md 的 Introduction 中定义；而 2024 年 4 月发布的 V2 在保留 V1 全部能力的基础上，README 明确列出了三项增强：

• 更好的音频质量：V2 采用了不同的训练策略（demo_part3.ipynb 中表述为“more aggressive augmentations”，即更强化的数据增强），从而在部分场景下具有更好的鲁棒性；
• 原生多语言支持：英语、西班牙语、法语、中文、日语、韩语六种语言原生支持；
• 免费商用：自 2024 年 4 月起，V1 与 V2 均以 MIT 协议发布，商业与科研使用均免费，详见 LICENSE。

一个重要的使用前提（来自 docs/QA.md 的 General Comments）：OpenVoice 是技术而非成品产品，其目标用户是开发者与研究人员，而不是期望“开箱即完美”的终端用户。QA 文档同时强调：OpenVoice 只克隆参考说话人的音色，不会克隆口音和情绪——口音与情绪由基音说话人 TTS 模型决定。理解这一分工，是后面所有用法的基础。

二、架构原理：Base Speaker + Tone Color Converter 两阶段流水线

从源码结构看，OpenVoice 的推理链路由 openvoice/api.py 中的两个类构成：BaseSpeakerTTS 负责“用某个基音说话人的声音朗读文本”，ToneColorConverter 负责“把朗读结果的音色转换到目标说话人”。

2.1 基音说话人：BaseSpeakerTTS

BaseSpeakerTTS（openvoice/api.py）内部是一个标准的 VITS 类合成器 SynthesizerTrn，构造时从 config.json 读取超参并实例化模型：

class OpenVoiceBaseClass(object):
    def __init__(self, config_path, device='cuda:0'):
        hps = utils.get_hparams_from_file(config_path)
        model = SynthesizerTrn(
            len(getattr(hps, 'symbols', [])),
            hps.data.filter_length // 2 + 1,
            n_speakers=hps.data.n_speakers,
            **hps.model,
        ).to(device)
        model.eval()

其 tts() 方法的关键逻辑：

def tts(self, text, output_path, speaker, language='English', speed=1.0):
    mark = self.language_marks.get(language.lower(), None)   # 语言标记 EN / ZH
    ...
    t = f'[{mark}]{t}[{mark}]'                              # 文本包裹语言标记
    ...
    audio = self.model.infer(x_tst, x_tst_lengths, sid=sid,
                              noise_scale=0.667, noise_scale_w=0.6,
                              length_scale=1.0 / speed)[0][0, 0]

可以推断三个要点：

• 语言通过 [EN] / [ZH] 标记嵌入文本序列（language_marks 目前只有 english→EN、chinese→ZH 两种，见 openvoice/api.py）；
• speaker 参数选择检查点内预置的说话人 id（self.hps.speakers[speaker]），这就是 V1 风格控制的实现入口——checkpoint 中预置了不同风格对应的说话人 id；
• speed 通过 length_scale=1.0/speed 作用于时长预测，实现语速控制。

noise_scale=0.667、noise_scale_w=0.6 是官方在 API 层固化的采样随机性参数，分别影响音质扰动与韵律扰动（对应 openvoice/models.py 中 infer() 的 z_p = m_p + randn * exp(logs_p) * noise_scale 与时长采样）。

2.2 音色转换：ToneColorConverter 与 voice_conversion

ToneColorConverter（openvoice/api.py）与基音说话人共用 SynthesizerTrn 模型类，但 n_speakers=0，因此模型内部不构建文本编码器，而是构建 ReferenceEncoder（ref_enc，见 openvoice/models.py），用于从参考频谱提取音色嵌入。核心转换逻辑在 openvoice/models.py：

def voice_conversion(self, y, y_lengths, sid_src, sid_tgt, tau=1.0):
    g_src = sid_src
    g_tgt = sid_tgt
    z, m_q, logs_q, y_mask = self.enc_q(y, y_lengths, g=..., tau=tau)   # 后验编码器
    z_p = self.flow(z, y_mask, g=g_src)                                 # 正向 flow 对齐源音色
    z_hat = self.flow(z_p, y_mask, g=g_tgt, reverse=True)              # 逆向 flow 注入目标音色
    o_hat = self.dec(z_hat * y_mask, g=g_tgt)                          # HiFi-GAN 声码器
    return o_hat, y_mask, (z, z_p, z_hat)

即：把源音频编码到潜在空间 → 用归一化流（Normalizing Flow）变换到语言潜变量 z_p（携带韵律、内容等与音色解耦的信息）→ 逆向流中注入目标说话人的音色条件 g_tgt，再经声码器 dec 重建音频。tau 是后验编码器 PosteriorEncoder 的采样温度（默认 convert(tau=0.3)，见 openvoice/api.py），控制重建时对后验分布的采样随机程度。

extract_se() 方法（openvoice/api.py）展示了音色嵌入的提取：对参考音频做频谱分析后经 ref_enc 编码，多段参考音频的嵌入取均值，并可 torch.save 落盘复用。

2.3 水印机制

值得注意的工程细节：ToneColorConverter 构造时默认 enable_watermark=True，加载 wavmark 模型（openvoice/api.py）；convert() 结束后会调用 add_watermark()，把 message（官方 Gradio 示例中为 "@MyShell"）的位串按 16000 采样/32 bit 的块写入音频（openvoice/api.py）。官方 Gradio 应用即以此机制标记生成音频（见 openvoice/openvoice_app.py）。若不需要水印，可传 enable_watermark=False 跳过。

三、环境要求与安装（V1 与 V2 通用）

按 docs/USAGE.md 的 Linux Install 章节，OpenVoice 面向熟悉 Linux、Python 与 PyTorch 的开发者与研究者，V1/V2 的安装方式相同：

conda create -n openvoice python=3.9
conda activate openvoice
git clone https://gitcode.com/GitHub_Trending/op/OpenVoice.git
cd OpenVoice
pip install -e .

安装方式由 setup.py 定义：包名为 MyShell-OpenVoice，python_requires='>=3.9'，依赖锁版本列表见 requirements.txt，其中与运行强相关的包括：

依赖	版本	作用（结合源码可确认）
librosa	0.9.1	音频读取与频谱分析（api.py、se_extractor.py）
faster-whisper	0.9.0	Whisper 语音切分（se_extractor.split_audio_whisper）
whisper-timestamped	1.14.2	提供 Silero VAD 分段函数 get_vad_segments（se_extractor.split_audio_vad）
pydub	0.25.1	音频切片与导出
wavmark	0.0.3	音频水印
gradio	3.48.0	本地 Demo 界面
pypinyin / jieba / cn2an	-	中文文本处理
langid	1.1.6	Gradio Demo 中自动检测输入语言

checkpoint 需从 docs/USAGE.md 中给出的官方下载地址获取（V1 为 checkpoints_1226.zip，V2 为 checkpoints_v2_0417.zip，链接以该文档为准），分别解压到 checkpoints/ 和 checkpoints_v2/ 目录。V1 解压后目录结构可从 openvoice/openvoice_app.py 的加载代码确认：

en_ckpt_base = 'checkpoints/base_speakers/EN'
zh_ckpt_base = 'checkpoints/base_speakers/ZH'
ckpt_converter = 'checkpoints/converter'
...
en_base_speaker_tts = BaseSpeakerTTS(f'{en_ckpt_base}/config.json', device=device)
en_base_speaker_tts.load_ckpt(f'{en_ckpt_base}/checkpoint.pth')
tone_color_converter = ToneColorConverter(f'{ckpt_converter}/config.json', device=device)
tone_color_converter.load_ckpt(f'{ckpt_converter}/checkpoint.pth')

即每个模型由 config.json + checkpoint.pth 组成，另有 en_default_se.pth、en_style_se.pth、zh_default_se.pth 等预提取的源音色嵌入文件。

四、OpenVoice V1 用法

V1 提供三类使用入口（docs/USAGE.md 的 OpenVoice V1 章节）：

4.1 灵活风格控制（demo_part1.ipynb）

demo_part1.ipynb 给出最小可运行的三步调用：初始化 → 提取目标音色嵌入 → 基音 TTS + 音色转换。

import os, torch
from openvoice import se_extractor
from openvoice.api import BaseSpeakerTTS, ToneColorConverter

# 1. 初始化
ckpt_base = 'checkpoints/base_speakers/EN'
ckpt_converter = 'checkpoints/converter'
device = "cuda:0" if torch.cuda.is_available() else "cpu"

base_speaker_tts = BaseSpeakerTTS(f'{ckpt_base}/config.json', device=device)
base_speaker_tts.load_ckpt(f'{ckpt_base}/checkpoint.pth')
tone_color_converter = ToneColorConverter(f'{ckpt_converter}/config.json', device=device)
tone_color_converter.load_ckpt(f'{ckpt_converter}/checkpoint.pth')

# 2. 提取参考说话人音色嵌入（target_se）
source_se = torch.load(f'{ckpt_base}/en_default_se.pth').to(device)  # 基音说话人嵌入，可直接加载
reference_speaker = 'resources/example_reference.mp3'               # 你想克隆的语音
target_se, audio_name = se_extractor.get_se(reference_speaker, tone_color_converter,
                                            target_dir='processed', vad=True)

# 3. 推理：先 TTS，再音色转换
text = "This audio is generated by OpenVoice."
src_path = 'outputs/tmp.wav'
base_speaker_tts.tts(text, src_path, speaker='default', language='English', speed=1.0)

tone_color_converter.convert(
    audio_src_path=src_path,
    src_se=source_se,
    tgt_se=target_se,
    output_path='outputs/output_en_default.wav',
    message="@MyShell")

风格与语速由 tts() 的 speaker 与 speed 参数控制。从 openvoice/openvoice_app.py 的参数校验可见，V1 英文基音说话人可用的风格取值为：default、whispering、shouting、excited、cheerful、terrified、angry、sad、friendly。

注意 demo_part1.ipynb 中的提醒：se_extractor 会以音频文件名为 key 保存提取的 target_se 且不会自动覆盖，使用自己的参考音频时请确保文件名唯一（这一点与 QA 中“忘记删除 processed 缓存目录”的问题直接相关）。

4.2 跨语言克隆（demo_part2.ipynb）

demo_part2.ipynb 演示 MSML 训练集中已见过与未见过语言的克隆效果。QA 文档补充了语言扩展策略（docs/QA.md Issues with Languages 一节）：OpenVoice 支持任何语言，前提是你拥有该语言的基音说话人 TTS 模型——音色转换器（最难训练的部分）官方已完成，基音说话人模型相对容易训练，可直接替换当前提供的基音说话人接入框架。

4.3 本地 Gradio Demo

启动命令（docs/USAGE.md）：

python -m openvoice_app --share

--share 参数定义在 openvoice/openvoice_app.py，作用是将 Gradio 链接公开（make link public）。该 Demo 的主要交互约束（均见 openvoice/openvoice_app.py 的 predict 函数）：

• 支持语言仅中文、英文（supported_languages = ['zh', 'en']，用 langid 自动检测）；
• 输入文本限制 200 字符以内（Demo 限制，非模型限制）；
• 中文仅支持 default 风格；英文支持上文列出的全部风格；
• 生成链路：get_se 提取目标音色 → tts 合成临时音频 → convert 转换并打上 "@MyShell" 水印，输出到 outputs/output.wav。

官方建议：遇到 Gradio Demo 问题时，先看 demo_part1/part2 与 docs/QA.md，而非直接排查 Demo 本身。

五、OpenVoice V2 用法：MeloTTS 作为多语言基音说话人

V2 的 checkpoint（checkpoints_v2_0417.zip）解压到 checkpoints_v2/ 目录后，按 docs/USAGE.md 还需安装多语言 TTS 库 MeloTTS：

pip install git+https://github.com/myshell-ai/MeloTTS.git
python -m unidic download

V2 的完整示例见 demo_part3.ipynb。其结构与 V1 类似，但区别明显：

# 初始化：只用 checkpoints_v2/converter
tone_color_converter = ToneColorConverter('checkpoints_v2/converter/config.json', device=device)
tone_color_converter.load_ckpt('checkpoints_v2/converter/checkpoint.pth')

# 提取目标音色嵌入（source 嵌入直接来自 checkpoints_v2/ses 目录）
target_se, audio_name = se_extractor.get_se('resources/example_reference.mp3',
                                            tone_color_converter, vad=True)

# 使用 MeloTTS 作为基音说话人
from melo.api import TTS
texts = {
    'EN_NEWEST': "Did you ever hear a folk tale about a giant turtle?",
    'ES': "El resplandor del sol acaricia las olas...",
    'FR': "La lueur dorée du soleil caresse les vagues...",
    'ZH': "在这次vacation中，我们计划去Paris欣赏埃菲尔铁塔和卢浮宫的美景。",
    'JP': "...",  # 日语示例
    # 韩语同理
}

从源码结构看，V2 复用同一套 ToneColorConverter 接口，版本区分通过配置中的 _version_ 字段传递（openvoice/api.py），并影响 se_extractor 的缓存目录命名（openvoice/se_extractor.py）。V2 原生支持的六种语言（英语、西班牙语、法语、中文、日语、韩语）由 MeloTTS 的基音模型覆盖；USAGE 文档同时给出了 myshell.ai 上已部署的各语言在线服务入口（英式/美式/印度/澳式英语、西语、法语、中文、日语、韩语），供不安装环境直接体验。

六、音色嵌入提取的内部流程（se_extractor）

se_extractor.get_se()（openvoice/se_extractor.py）是克隆质量的守门员，其内部流程值得了解，因为 QA 中的多数“音质问题”根源都在这一步：

1. 命名与缓存：以 文件名_版本_音频SHA256哈希前缀 作为缓存 key（hash_numpy_array），相同音频重复提取不会重算；但换了内容而保留同名文件会导致缓存混淆——这正是 QA 中“同名参考音频忘记删除 processed 文件夹”问题的成因之一；
2. 两种切分策略：
   • vad=True（默认，split_audio_vad）：调用 Silero VAD 去静音后，按 split_seconds=10.0 均匀切段（openvoice/se_extractor.py）；
   • vad=False（split_audio_whisper）：用 faster-whisper medium 模型转写并按词时间戳切分，仅保留时长 1.5s~20s、转写文本 2~200 字符的高置信度片段（openvoice/se_extractor.py）；
3. 多段均值：各段频谱经 ref_enc 编码后在 extract_se 中取均值，作为最终 target_se。

安装环境的一个已知坑（docs/QA.md Issues with Installation）：split_audio_vad 依赖的 Silero VAD 首次运行会从 github 下载 snakers4/silero-vad 到 ~/.cache/torch/hub/，若机器无法访问 github，下载会失败。解决办法是手动下载该 zip 并解压到 ~/.cache/torch/hub/snakers4_silero-vad_master 目录。

七、常见问题排查（源自官方 QA）

以下为 docs/QA.md 的要点整理，官方表示会持续更新该列表：

1. 生成语音的口音/情绪与参考语音不一致？ 这是设计使然而非 bug：OpenVoice 只克隆音色，口音与情绪由基音说话人 TTS 模型决定（技术细节见论文 arXiv:2312.01479）。想改变口音或情绪，需要换一个带该口音/情绪风格的基音说话人模型。

**2. 生成语音音质差？**按 QA 建议逐项检查：

• 参考音频是否干净、无背景噪音？
• 音频是否太短？
• 音频中是否混入了多个说话人？
• 参考音频是否包含较长空白段？
• 是否用了同名文件但忘记删除 processed 缓存文件夹？

**3. 想支持其他语言？**参见 demo_part2.ipynb 的多语言与跨语言示例。只要有对应语言的基音说话人即可，OpenVoice 团队已完成最难的部分（音色转换器训练）。

4. 定位“技术 vs 产品”：QA 开篇即声明，OpenVoice 是“versatile instant voice cloning technical approach”，不是开箱即用的完美产品；在正确使用前提下它适用于大多数声音，但不应期望所有 case 都完美。

八、引用、许可与致谢

• 许可证：V1 与 V2 均为 MIT License，商业与科研使用免费（LICENSE，README.md License 章节）。

• 引用：如需引用本项目，README 给出的 BibTeX 为：

  @article{qin2023openvoice,
    title={OpenVoice: Versatile Instant Voice Cloning},
    author={Qin, Zengyi and Zhao, Wenliang and Yu, Xumin and Sun, Xin},
    journal={arXiv preprint arXiv:2312.01479},
    year={2023}
  }
  

• 致谢：README 声明本实现基于 TTS（coqui-ai）、VITS（jaywalnut310）、VITS2（daniilrobnikov）三个开源项目。

• 社区贡献：Windows 与 Docker 安装为社区非官方指南，docs/USAGE.md 的 “Install on Other Platforms” 一节列出了贡献者指引；README 的 Main Contributors 列出了 MIT、清华大学与 MyShell 四位主要贡献者。

九、小结：关键路径速查

目标	入口	关键文件/目录
V1 风格控制	demo_part1.ipynb	checkpoints/base_speakers/{EN,ZH}、checkpoints/converter
V1 跨语言克隆	demo_part2.ipynb	同上
本地 Gradio	python -m openvoice_app --share	openvoice/openvoice_app.py
V2 多语言	demo_part3.ipynb + MeloTTS	checkpoints_v2/converter、checkpoints_v2/ses
音色嵌入提取	se_extractor.get_se	openvoice/se_extractor.py
核心推理 API	BaseSpeakerTTS.tts / ToneColorConverter.convert	openvoice/api.py
声学模型	SynthesizerTrn.infer / voice_conversion	openvoice/models.py
常见问题	官方 QnA	docs/QA.md

掌握“基音说话人合成 → 音色嵌入转换”这一两阶段范式后，你可以按 QA 文档的建议替换任意语言的基音说话人模型，把 OpenVoice 的零样本音色克隆能力扩展到任意语言场景。