OpenVoice 使用指南：从零安装到 V1/V2 音色克隆实战

OpenVoice 是 MyShell 与 MIT 联合开源的即时语音克隆（Instant Voice Cloning）音频基础模型，其输入参考语音可以是任意语言：它会克隆参考语音的音色（tone color），并让该音色用多种语言说话。本文基于仓库中的 docs/USAGE.md 编写，完整覆盖免安装的快速试用、Linux 下的 V1/V2 安装流程、三个官方 Demo Notebook 与本地 Gradio 服务的启动方式，并深入到 openvoice/api.py、openvoice/se_extractor.py 与 openvoice/openvoice_app.py 的源码，帮助读者理解“基础说话人 TTS + 音色转换器”两阶段管线、音色嵌入（SE）提取与水印机制的实现细节。读完本文，你将能够独立部署 OpenVoice 并完成带风格控制、跨语言的音色克隆推理。

免安装快速试用（Quick Use）

对于只是想体验效果的读者，官方推荐直接使用已部署好的在线服务。OpenVoice 支持对参考语音进行任意语言输入，并输出多种语言的克隆语音，USAGE 文档列出了以下已部署语言入口：

• 英式英语（British English）
• 美式英语（American English）
• 印度英语（Indian English）
• 澳大利亚英语（Australian English）
• 西班牙语（Spanish）
• 法语（French）
• 中文（Chinese）
• 日语（Japanese）
• 韩语（Korean）

这些服务入口均托管在 MyShell 平台，具体链接请以仓库 docs/USAGE.md 原文为准（本文不重复输出外部链接）。

最小化 Demo（Minimal Demo）

如果你只是想快速验证 OpenVoice、对音质和稳定性要求不高，可以访问官方提供的 MyShell 平台 Demo 或 Hugging Face Space。这两个入口在 docs/USAGE.md 的 “Minimal Demo” 一节中给出，适合 5 分钟内上手体验，但不适合生产用途。

真正的“可运行代码”从下一节的 Linux 安装开始。

Linux 安装：V1 与 V2 通用步骤

USAGE 文档明确说明：该部分仅面向熟悉 Linux、Python 与 PyTorch 的开发者/研究者。无论使用 V1 还是 V2，基础安装命令完全相同：

conda create -n openvoice python=3.9
conda activate openvoice
git clone <本仓库地址>   # 即克隆 OpenVoice 仓库
cd OpenVoice
pip install -e .

关于 python=3.9 的约束，仓库 setup.py 中声明了 python_requires='>=3.9'，因此 conda 环境最低需要 Python 3.9。

pip install -e . 会按 requirements.txt（与 setup.py 的 install_requires 一致）安装全部依赖。值得提前了解的版本锁定如下（这是本仓库能稳定运行的前提）：

依赖	版本	作用（结合源码）
librosa	0.9.1	音频读取/重采样，extract_se、convert 均基于它加载参考音频
faster-whisper	0.9.0	非 VAD 模式下按语音分段（openvoice/se_extractor.py 中 WhisperModel("medium")）
whisper-timestamped	1.14.2	提供 get_vad_segments，是默认 VAD 分段的基础（silero VAD）
pydub	0.25.1	音频切片与 wav 导出
wavmark	0.0.3	输出音频水印，ToneColorConverter 默认启用
numpy	1.22.0	注意此版本较旧，与新版 PyTorch/系统库可能存在兼容性问题
pypinyin / cn2an / jieba	0.50.0 / 0.5.22 / 0.42.1	中文文本清洗（openvoice/text/mandarin.py 相关管线）
gradio	3.48.0	本地 Gradio Demo 的 UI 框架
langid	1.1.6	Gradio Demo 中的输入语言自动检测

OpenVoice V1：checkpoint 与三大功能 Demo

准备 checkpoint

下载 V1 checkpoint 压缩包，解压到仓库根目录下的 checkpoints 文件夹（下载地址见 docs/USAGE.md 原文）。从 openvoice/openvoice_app.py 可以确认 V1 checkpoint 的目录结构约定：

checkpoints/
├── base_speakers/EN/     # 英文基础说话人：config.json + checkpoint.pth
│   ├── en_default_se.pth # 默认风格音色嵌入
│   └── en_style_se.pth   # 风格化（非 default）音色嵌入
├── base_speakers/ZH/     # 中文基础说话人：config.json + checkpoint.pth
│   └── zh_default_se.pth
└── converter/            # 音色转换器：config.json + checkpoint.pth

Demo 1：灵活的语音风格控制（demo_part1）

见 demo_part1.ipynb。核心调用链是“两步走”：

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

ckpt_base = 'checkpoints/base_speakers/EN'
ckpt_converter = 'checkpoints/converter'
device = "cuda:0" if torch.cuda.is_available() else "cpu"
output_dir = 'outputs'

# 1) 基础说话人 TTS 模型
base_speaker_tts = BaseSpeakerTTS(f'{ckpt_base}/config.json', device=device)
base_speaker_tts.load_ckpt(f'{ckpt_base}/checkpoint.pth')

# 2) 音色转换器
tone_color_converter = ToneColorConverter(f'{ckpt_converter}/config.json', device=device)
tone_color_converter.load_ckpt(f'{ckpt_converter}/checkpoint.pth')

os.makedirs(output_dir, exist_ok=True)

# 基础说话人的音色嵌入（官方已给出生成结果，也可自行提取）
source_se = torch.load(f'{ckpt_base}/en_default_se.pth').to(device)

# 提取目标说话人音色嵌入：参考音频请用唯一文件名（se 按文件名缓存，不会自动覆盖）
reference_speaker = 'resources/example_reference.mp3'
target_se, audio_name = se_extractor.get_se(reference_speaker, tone_color_converter, target_dir='processed', vad=True)

# 推理：先合成基础语音，再做音色转换
save_path = f'{output_dir}/output_en_default.wav'
text = "This audio is generated by OpenVoice."
src_path = f'{output_dir}/tmp.wav'
base_speaker_tts.tts(text, src_path, speaker='default', language='English', speed=1.0)

encode_message = "@MyShell"
tone_color_converter.convert(
    audio_src_path=src_path,
    src_se=source_se,
    tgt_se=target_se,
    output_path=save_path,
    message=encode_message)

风格与语速控制：风格通过 tts() 的 speaker 参数控制，可用值为 friendly, cheerful, excited, sad, angry, terrified, shouting, whispering。注意 Notebook 中的关键提示：风格改变后必须换用对应的音色嵌入（例如切到 whispering 风格时需加载 en_style_se.pth），否则音色转换的对齐前提不成立。语速通过 speed 参数控制。

这一点在源码中有对应：openvoice/api.py 中 BaseSpeakerTTS.tts 将 speed 换算为 length_scale=1.0/speed 传入 model.infer，并按语言给文本包裹 [EN]...[EN] / [ZH]...[ZH] 语言标记；speaker 名通过 hps.speakers 映射为 speaker id。

换用中文基础说话人：只需把 ckpt_base 换成 checkpoints/base_speakers/ZH、加载 zh_default_se.pth、并把 language 改为 'Chinese'，即可用中文基础说话人生成语音（BaseSpeakerTTS 的 language_marks 目前内置 english→EN、chinese→ZH 两种标记，见 openvoice/api.py）。

Demo 2：跨语言语音克隆（demo_part2）

见 demo_part2.ipynb。该 Demo 的核心思想是：V1 的基础说话人可以是任意 TTS 系统——Notebook 中以 OpenAI TTS（tts-1，voice 为 nova）充当基础说话人，流程为：

1. 用 OpenAI TTS 生成一段“基础语音”，经 se_extractor.get_se(..., vad=True) 提取 source_se；
2. 同样方式从 resources/example_reference.mp3 提取目标说话人的 target_se；
3. 对英、西、法、德、意、日、俄、阿、中、印地、葡等 11 段多语种文本逐条调用 tone_color_converter.convert，无需任何额外训练。

这也印证了 V1 的三大能力之一：零样本跨语言克隆——生成语音的语言与参考语音的语言都无需出现在大规模多说话人训练集中（该 Notebook 覆盖的正是训练集“见过/没见过”的语言组合）。若不用 OpenAI，也可以像 Demo 1 那样用仓库自带的 EN/ZH 基础说话人；使用前需按 Notebook 说明创建 .env 文件写入 OPENAI_API_KEY=xxx。

Demo 3：本地 Gradio Demo

USAGE 文档给出的启动命令是：

python -m openvoice_app --share

--share 对应 openvoice/openvoice_app.py 中的 --share 参数（store_true，默认关闭），用于生成可公开访问的临时链接；入口实现位于 openvoice/openvoice_app.py。官方强烈建议遇到问题时先阅读 demo_part1.ipynb、demo_part2.ipynb 以及 docs/QA.md。

从源码可以读出该 Gradio Demo 的若干实际限制（这也是很多“克隆不像”问题的根源）：

• 语言支持：supported_languages = ['zh', 'en']，用 langid 自动检测输入文本语言；英文可选全部风格，中文目前仅支持 default 风格（见 openvoice/openvoice_app.py）；
• 文本长度：Demo 中提示文本限制在 2～200 字符之间；
• 风格列表：default, whispering, cheerful, terrified, angry, sad, friendly（Dropdown 选项；校验逻辑中还包含 shouting, excited）；
• 完整推理链：se_extractor.get_se(speaker_wav, converter, vad=True) 提取目标 SE → tts_model.tts(prompt, ...) 合成基础语音 → convert(..., message="@MyShell") 完成音色转换并写入 outputs/output.wav。

水印机制（Tech for Good）

Demo 1 末尾提到：面向公众部署 OpenVoice 时，官方提供了加水印选项以避免滥用，并声明 MyShell 保留检测音频是否由 OpenVoice 生成的能力。从 openvoice/api.py 可以看到实现细节：ToneColorConverter.__init__ 中 enable_watermark 默认为 True，通过 wavmark 模型把 message（默认 "@MyShell"）的位串按 32 bit/块、每块 16000 采样点（步进系数 2）嵌入音频；detect_watermark 可反向解码出消息。若音频过短，会打印 "Audio too short, fail to add watermark" 并中止嵌入。

OpenVoice V2：更高音质与原生多语言

准备 checkpoint 与 MeloTTS

下载 V2 checkpoint（checkpoints_v2_0417.zip），解压到仓库根目录的 checkpoints_v2 文件夹，然后额外安装基础说话人 TTS——MeloTTS：

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

MeloTTS 是 MyShell 的多语言 TTS 库，支持英语（美式、英式、印度、澳式、Default）、西班牙语、法语、中文、日语、韩语；python -m unidic download 用于下载日语分词所需的 unidic 词典数据。

Demo 3：多口音多语言克隆（demo_part3）

见 demo_part3.ipynb。V2 的官方说明是：它包含 V1 的全部特性，采用不同的训练策略带来更好的音质，并原生支持英语、西班牙语、法语、中文、日语、韩语。与 V1 的差别体现在代码里：

from openvoice import se_extractor
from openvoice.api import ToneColorConverter
from melo.api import TTS

# V2 转换器（换用 checkpoints_v2）
ckpt_converter = 'checkpoints_v2/converter'
device = "cuda:0" if torch.cuda.is_available() else "cpu"
output_dir = 'outputs_v2'
tone_color_converter = ToneColorConverter(f'{ckpt_converter}/config.json', device=device)
tone_color_converter.load_ckpt(f'{ckpt_converter}/checkpoint.pth')

# 只需提取目标说话人 SE；source SE 直接从 checkpoints_v2/ses 读取
reference_speaker = 'resources/example_reference.mp3'
target_se, audio_name = se_extractor.get_se(reference_speaker, tone_color_converter, vad=True)

texts = {
    'EN_NEWEST': "Did you ever hear a folk tale about a giant turtle?",
    'EN': "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': "彼は毎朝ジョギングをして体を健康に保っています。",
    'KR': "안녕하세요! 오늘은 날씨가 정말 좋네요.",
}
speed = 1.0  # 语速可调

for language, text in texts.items():
    model = TTS(language=language, device=device)
    speaker_ids = model.hps.data.spk2id
    for speaker_key in speaker_ids.keys():
        speaker_id = speaker_ids[speaker_key]
        speaker_key = speaker_key.lower().replace('_', '-')
        source_se = torch.load(f'checkpoints_v2/base_speakers/ses/{speaker_key}.pth', map_location=device)
        model.tts_to_file(text, speaker_id, f'{output_dir}/tmp.wav', speed=speed)
        save_path = f'{output_dir}/output_v2_{speaker_key}.wav'
        tone_color_converter.convert(
            audio_src_path=f'{output_dir}/tmp.wav',
            src_se=source_se,
            tgt_se=target_se,
            output_path=save_path,
            message="@MyShell")

可见 V2 的工程范式与 V1 一致（基础 TTS → 音色嵌入转换），变化在于：基础说话人从仓库自带的 EN/ZH 换成 MeloTTS 的多语言、多口音模型族，每个 MeloTTS speaker 都有对应的预提取 source SE 文件 checkpoints_v2/base_speakers/ses/{speaker}.pth，因此“换语言/换口音”只是换一个 TTS(language=...) 实例和一个 source SE。

源码纵深：音色嵌入是如何提取的

上面所有 Demo 都依赖同一个函数 se_extractor.get_se(audio_path, vc_model, target_dir='processed', vad=True)。结合 openvoice/se_extractor.py 可以理清其完整流程：

1. 生成缓存键：以“文件名 + 模型版本（hps._version_，默认 v1）+ 音频内容 SHA-256 前 16 位 base64”作为 audio_name，SE 结果保存在 processed/{audio_name}/se.pth。这就是 Demo 1 强调“每个说话人请用唯一文件名”的原因；
2. 分段：默认 vad=True，走 split_audio_vad——用 whisper_timestamped 的 silero VAD（min_speech_duration=0.1s、min_silence_duration=1s）截取有效语音后，再按约 10 秒均匀切段；vad=False 时改走 split_audio_whisper，用 faster-whisper medium 模型（CUDA + FP16、beam_size=5、词级时间戳）按转录分段，并过滤掉短于 1.5 秒或长于 20 秒、文本长度不在 2～199 字符的片段；
3. 聚合嵌入：分段送入 openvoice/api.py 的 extract_se——每段做 22.05k 采样率下的 STFT（spectrogram_torch），经 model.ref_enc 得到参考编码器输出，最后对全部段做均值池化（torch.stack(gs).mean(0)）得到稳定的音色嵌入。

随后的音色转换由 convert(audio_src_path, src_se, tgt_se, output_path=None, tau=0.3, ...) 完成：对源音频做谱提取后调用 model.voice_conversion(spec, spec_lengths, sid_src, sid_tgt, tau)（openvoice/models.py 中定义）。从 models.py 中 enc_q 的用法可以看到 tau 直接乘在声学编码器的随机噪声项 torch.randn_like(m) * tau * torch.exp(logs) 上——tau 越小，转换时保留的原始细节/内容条件越确定，这也是 API 默认取 tau=0.3 而非 1.0 的原因。

其他平台安装（社区贡献）

USAGE 文档还收录了开源社区贡献的非官方安装指南，覆盖 Windows 与 Docker 两种环境，分别由社区贡献者 @Alienpups 与 @StevenJSCF 撰写，原文链接见 docs/USAGE.md 的 “Install on Other Platforms” 一节。这些指南未经官方维护，若与本仓库 requirements.txt 的版本约束冲突，请以仓库实际依赖为准。

小结

回到 USAGE 文档的完整脉络：免安装服务 → Minimal Demo → Linux 安装（V1/V2 通用）→ V1 三大 Demo（风格控制 / 跨语言 / Gradio）→ V2 + MeloTTS → 社区平台指南。掌握它的关键是理解 OpenVoice 的两阶段架构：基础说话人 TTS（BaseSpeakerTTS 或 MeloTTS/OpenAI TTS 等外部系统）负责文本到语音与风格/语言控制，ToneColorConverter 通过参考编码器提取的音色嵌入把“音色”移植过去，se_extractor 负责稳健地提取该嵌入，水印模块则为公开发布场景提供溯源能力。按本文的安装步骤准备 checkpoint 与依赖后，即可在本仓库的 demo_part1.ipynb、demo_part2.ipynb、demo_part3.ipynb 中直接复现全部能力；遇到具体问题可进一步查阅 docs/QA.md。