声音克隆与音色设计 — VoxCPM2 协议 / Voice Clone & Voice Design — VoxCPM2 Protocol

你现在运行 voice-clone-design 技能。底层是开源 VoxCPM2（OpenBMB · 2B tokenizer-free TTS · Apache-2.0 · weights 商用免审），把以下两类输入变成 48 kHz 单声道录音棚级 .wav：

Voice Design —— 一句自然语言描述（例："a young woman in her early twenties, warm and slightly breathy"）→ 全新的角色音；
Voice Cloning —— 一段 6–30 秒的参考音 + 你想念的文本 → 用同一个音色读出来的新音频，可叠加 <calm> 等情绪标签或 0.7×–1.3× 速度控制。

支持 30 种语言、离线推理、零 API key、零云依赖（首次运行从 Hugging Face 自动下载一次 ~2 GB 权重，之后完全离线）。课程主页与文档：https://clawvard.school。

本课只覆盖 voice cloning + voice design + multilingual offline TTS。

不做：实时流式合成（即使官方支持也不教，避免与未来的实时课程混淆）；SFT / LoRA / 任何 fine-tuning（课程范围内仅做 inference）；phone agent / 对话回路 / 出站电话 use case（那是另一门 Dograh 课的窗口）。

与 ai-voiceover（Supertonic）的边界：ai-voiceover 做 text → 默认音色库（F1..M5）→ .wav；本课做 自定义新音色 / 克隆音色 → .wav，deliverable 是音色资产本身。

⚠️ 使用须知：参考音色必须由你本人录制，或你已获得声音所有者的明确授权；禁止用受版权保护的他人录音、名人/艺人声音、未授权他人声纹做克隆。生成的音频若用于商业、公开发布或代表他人发声，请遵守当地法律法规并附明显的"AI 生成"标识。Clawvard 与上游 VoxCPM 项目均不对滥用行为负责。

⚠️ Consent notice: the reference clip must be your own recording, or one you have explicit permission to use. Cloning copyrighted recordings, celebrity / artist voices, or any voiceprint you do not own is prohibited. If you publish or commercially use the output — or use it to speak on behalf of someone else — disclose that the audio is AI-generated and comply with local law. Neither Clawvard nor the upstream VoxCPM project is liable for misuse.

前置条件

Python 3.10–3.12、pip
PyTorch ≥ 2.5
强烈推荐 NVIDIA GPU + CUDA ≥ 12（~5 GB VRAM 起步，RTX 4090 RTF ≈ 0.3）。CPU 模式可跑，但 2B 体量较慢，仅用于试听；正式批量生成请上 GPU。
磁盘：首次运行会下载权重（约 2 GB）到 ~/.cache/huggingface/，预留 ~6 GB 较稳妥。
首次运行需联网下模型；之后断网也能跑。
Voice Cloning 任务需要一段 ≥ 6 秒、≤ 30 秒的参考音（用户拥有版权或本人录制；建议干声、无背景音乐、采样率 ≥ 16 kHz）。

零 API key，不消耗 Clawvard credits，不需要付费第三方服务，也不需要 clone 任何私有仓库 —— 全程本地。

无 GPU？ 跳到 §D. No-GPU 公共路径：用 OpenBMB 官方 Hugging Face Space 在浏览器里跑同一份 VoxCPM2 模型，无需本地装 Python / 下载权重，免费、公开、无需注册。两个 popularTask 都能用这条路径产出 —— Space 返回 .mp3，本地用一行 ffmpeg 转成 48 kHz 单声道 RIFF/WAVE .wav 即得 deliverable。

ffmpeg 是 No-GPU 路径的必备工具（公开免费、跨平台、零账号）。macOS：brew install ffmpeg；Ubuntu/Debian：sudo apt install -y ffmpeg；Windows：winget install Gyan.FFmpeg；或从 ffmpeg.org/download 取静态二进制。验证：ffmpeg -version。GPU 路径不需要 ffmpeg（voxcpm CLI / Python API 直接写 PCM 16-bit RIFF/WAVE）。

安装（官方 PyPI 包，一行）

pip install voxcpm

如果上游 PyPI 暂时只有 source dist 或你需要最新主线：

pip install git+https://github.com/OpenBMB/VoxCPM

PEP 668 系统（Ubuntu 24.04 / 较新 macOS）用 pipx install voxcpm 或在 venv 里装。

验证：

python -c "from voxcpm import VoxCPM; print('ok')"

两条调用面

VoxCPM2 安装完就有官方 voxcpm CLI，子命令 design 和 clone 直接对应本课的两个任务；想脚本化 / 批量 / 嵌入 agent 流水线就再走 Python API（from voxcpm import VoxCPM）。两条路径调的是同一份模型权重。

A. Voice Design（一句话造一把新音色）

CLI（最简，一行即出）：

voxcpm design \
  --hf-model-id openbmb/VoxCPM2 \
  --control "a young woman in her early twenties, warm and slightly breathy, mid-tempo, no accent" \
  --text "欢迎来到 Clawvard，今天我们一起把一句话变成你的下一个原创角色音。" \
  --normalize \
  --cfg-value 2.0 --inference-timesteps 10 \
  --output voice-design-zh.wav

voxcpm design \
  --hf-model-id openbmb/VoxCPM2 \
  --control "a young woman in her early twenties, warm and slightly breathy, mid-tempo, no accent" \
  --text "Welcome to Clawvard — let's turn one sentence into your next original character voice." \
  --normalize \
  --cfg-value 2.0 --inference-timesteps 10 \
  --output voice-design-en.wav

Python API（脚本化时用）：

# voice_design.py
from voxcpm import VoxCPM
import soundfile as sf

tts = VoxCPM.from_pretrained("openbmb/VoxCPM2")   # 默认就是这个 HF id
sr = tts.tts_model.sample_rate                    # VoxCPM2 = 48000 Hz

CONTROL = "a young woman in her early twenties, warm and slightly breathy, mid-tempo, no accent"

# 公共 API 只有一个入口：tts.generate。Voice Design 的实现 = 把 (CONTROL) 前置到 text
# 里、不传 reference_wav_path。模型返回 float32 numpy 波形，自己用 soundfile 落盘。
for lang, text in [
    ("zh", "欢迎来到 Clawvard，今天我们一起把一句话变成你的下一个原创角色音。"),
    ("en", "Welcome to Clawvard — let's turn one sentence into your next original character voice."),
]:
    wav = tts.generate(
        text=f"({CONTROL}){text}",
        cfg_value=2.0,
        inference_timesteps=10,
        normalize=True,
    )
    sf.write(f"voice-design-{lang}.wav", wav, sr)

要点：

(CONTROL) 用半角括号，紧贴目标文本前面；描述本身中英任写。不要用全角括号 （） —— 模型按半角括号拆 control / target。
同一个 CONTROL 字符串配不同目标文本，能拿到同一把声音念不同台词；想稳定复现，把它当常量复用。
没有 (CONTROL) 时模型自由发挥音色，每次结果会变。
想跨段把音色锁死（例如 zh 段先出来、再用同一把声音读 en 段）→ 把第一段产物当作 --reference-audio 喂给第二段（见 B 节），后续段完全继承第一段音色。

B. Voice Cloning（参考音克隆音色）

CLI（最简）：

voxcpm clone \
  --hf-model-id openbmb/VoxCPM2 \
  --reference-audio reference.wav \
  --text "大家好，欢迎收听本期节目，今天我们聊一聊本地音色克隆这个最近很火的话题。" \
  --normalize --denoise \
  --cfg-value 2.0 --inference-timesteps 10 \
  --output voice-clone-podcast.wav

可控克隆（保留音色 + 同时调情绪 / 语速）：

voxcpm clone \
  --hf-model-id openbmb/VoxCPM2 \
  --reference-audio reference.wav \
  --control "calm, slower" \
  --text "大家好，今天我们聊一个最近很火的话题。" \
  --normalize --denoise \
  --output voice-clone-calm.wav

Python API：

# voice_clone.py
from voxcpm import VoxCPM
import soundfile as sf

tts = VoxCPM.from_pretrained("openbmb/VoxCPM2")
sr = tts.tts_model.sample_rate

wav = tts.generate(
    text="大家好，欢迎收听本期节目，今天我们聊一聊本地音色克隆这个最近很火的话题。",
    reference_wav_path="reference.wav",   # 你本人录的 6–30s 干声
    cfg_value=2.0,
    inference_timesteps=10,
    normalize=True,
    denoise=True,                         # 让 ZipEnhancer 给参考音降噪，听感更稳
)
sf.write("voice-clone-podcast.wav", wav, sr)

要点：

reference.wav 必须是用户自录或已授权的人声（见上方 Consent 段，禁止用名人 / 艺人 / 受版权保护录音）。
6 秒以下太短，30 秒以上裁掉前 30 秒就够；干声为佳（无 BGM、无噪声）。
可控克隆：CLI 里同时给 --reference-audio 和 --control；Python 里在 text 前同样加 "(描述)" 前缀。描述里只写情绪 / 语速 / 风格，不要再描述音色（音色由 reference 决定）。
极致克隆（逐字复刻参考音所有细节）：传参考音的文字稿。CLI：--prompt-audio reference.wav --prompt-text "参考音里你说的那段话的文字稿"；Python：prompt_wav_path="reference.wav", prompt_text="..."。这条路径会禁用 (CONTROL) 控制；二者只能选一。

C. Multilingual offline TTS（多语种离线合成）

VoxCPM2 内置多语种识别 —— 直接把目标语言的 --text / text= 传进去即可，无需 lang 字段；模型从字符判断。常用：zh、en、ja、ko、es、fr、de、pt、ru、it、ar、hi、vi、th、id 等。

D. No-GPU 公共路径（OpenBMB 官方 Hugging Face Space）

没有 NVIDIA GPU、显存不够、或不想在本地装 Python？OpenBMB 官方维护一个公开、免费、无需登录的 Hugging Face Space，跑的就是同一份 VoxCPM2 模型，浏览器里点几下加一行 ffmpeg 就能产出真·48 kHz 单声道 .wav。许可证 Apache-2.0、由 OpenBMB（VoxCPM 的作者团队）直接托管，不是 Clawvard 基础设施。

打开：https://huggingface.co/spaces/openbmb/VoxCPM-Demo

⚠️ 重要：当前 Space 后端把生成音频返回为 .mp3 容器（Gradio Audio 播放器默认编码），不是 RIFF/WAVE。本课的 deliverable 契约是 48 kHz 单声道 .wav，所以下载后必须本地用 ffmpeg 转一次才算完成产物。ffmpeg 是公开免费、跨平台、零账号的工具（macOS：brew install ffmpeg；Ubuntu/Debian：sudo apt install -y ffmpeg；Windows：winget install Gyan.FFmpeg；或从 ffmpeg.org/download 下二进制包）。

Task 1 / Voice Design — UI 步骤（无需上传任何参考音）

让 🎤 Reference Audio (optional — upload for cloning) 留空（不要上传任何音频）。

🎛️ Control Instruction 里粘贴你的音色描述，例如：

a young woman in her early twenties, warm and slightly breathy, mid-tempo, no accent

✍️ Target Text 里粘贴你要让这把声音念的文本，例如：

欢迎来到 Clawvard，今天我们一起把一句话变成你的下一个原创角色音。

展开 ⚙️ Advanced Settings，勾选 Text normalization（处理数字 / 日期 / 缩写更稳）。CFG 保持默认 2.0、LocDiT steps 保持默认 10。
点 🔊 Generate Speech。
在 Generated Audio 播放器右上角点下载图标，把文件存到本地，命名 voice-design-zh.mp3（Space 返回的就是 mp3，先用 .mp3 后缀保留原始数据）。
本地转 wav（48 kHz、单声道、PCM 16-bit；这是 deliverable 契约）：
```
ffmpeg -y -i voice-design-zh.mp3 -ar 48000 -ac 1 -c:a pcm_s16le voice-design-zh.wav
```
跑完用 file voice-design-zh.wav 应该看到 RIFF (little-endian) data, WAVE audio, Microsoft PCM, 16 bit, mono 48000 Hz。
同样的 Control Instruction、换 Target Text（例如英文 slogan），再点一次 Generate → 存 voice-design-en.mp3 → 同样 ffmpeg ... voice-design-en.wav。两次保持同一 Control Instruction 字符串可拿到同一把声音念不同台词。

Task 2 / Voice Cloning — UI 步骤（上传参考音）

请先做合规自检：你即将上传的 reference.wav 是不是你本人录或已获明确授权？如果不是 —— 停下，按上方 Consent / Ethics 段处理；禁止用受版权保护的他人录音、名人 / 艺人声音。
🎤 Reference Audio：上传 6–30 秒的参考音（干声、采样率 ≥ 16 kHz、无 BGM 最佳）。
不要勾 🎙️ Ultimate Cloning Mode（开启那个会强制 ASR + 复刻所有细节，并禁用 Control Instruction）。
🎛️ Control Instruction：留空，或者写情绪 / 语速修饰（例如 calm, slower）—— 这里不要再描述音色，音色由你的参考音决定。

✍️ Target Text 粘贴你要它念的新内容，例如：

大家好，欢迎收听本期节目，今天我们聊一聊本地音色克隆这个最近很火的话题。

展开 ⚙️ Advanced Settings，勾 Text normalization 和 Reference audio enhancement（让 ZipEnhancer 给你的参考音做一次降噪）。
点 🔊 Generate Speech，等模型跑完（~10–30 秒），从 Generated Audio 下载到本地，命名 voice-clone-podcast.mp3。
本地转 wav：
```
ffmpeg -y -i voice-clone-podcast.mp3 -ar 48000 -ac 1 -c:a pcm_s16le voice-clone-podcast.wav
```
产物 voice-clone-podcast.wav 即 48 kHz 单声道 PCM 16-bit RIFF/WAVE，符合 deliverable 契约。

Space 路径的限制与回落

上传 / 下载延迟受网络影响；高峰期可能排队。
Space 当前返回 .mp3（容器 + codec 都是 mp3）；要拿到 deliverable 承诺的 RIFF/WAVE PCM 48 kHz 单声道，必须经过上面那一行 ffmpeg 转码。不要直接把下载下来的 .mp3 重命名成 .wav 就交差 —— 那只是改了后缀名、容器还是 mp3、ffprobe/file 会立刻识破。
Space 由 OpenBMB 自行托管，如果它临时离线（HTTP 503 或页面 404），先刷新；持续不可用就回到本机 voxcpm CLI / Python API（A、B 节）。
Space 不会缓存你的参考音 / 输出（无登录），但仍然遵守 OpenBMB / Hugging Face 的使用条款；不要把企业 / 法务敏感的参考音传上去。

Prompt 模板（用户给你）

用 VoxCPM2 完成下列任务之一。
有 GPU：CLI / Python（A、B 节）；无 GPU：OpenBMB 官方 Hugging Face Space（D 节，浏览器内跑同一份模型，无需本地装 Python）。

1) [Voice Design] 用一句自然语言描述设计一把新音色：{CONTROL 描述}；
   让这把声音念：{文本，中 / 英 / 多语言任一}；
   GPU CLI：voxcpm design --control "{CONTROL}" --text "{文本}" --normalize --output {voice-design-*.wav}
   GPU Python：tts.generate(text=f"({CONTROL}){文本}", normalize=True)
               → soundfile.write({voice-design-*.wav}, wav, tts.tts_model.sample_rate)
   No-GPU Space：打开 https://huggingface.co/spaces/openbmb/VoxCPM-Demo →
                Reference Audio 留空 → Control Instruction 写 {CONTROL} →
                Target Text 写 {文本} → 勾 Text normalization → Generate Speech →
                下载到 {voice-design-*.mp3}，再本地转 wav（48 kHz 单声道 PCM）：
                ffmpeg -y -i {voice-design-*.mp3} -ar 48000 -ac 1 -c:a pcm_s16le {voice-design-*.wav}

2) [Voice Cloning] 参考音 {reference.wav}（我本人录 / 我已授权，先做合规自检）；
   再让克隆出的音色念：{文本}（可选 (calm / slower / ...) 等情绪 / 语速修饰）；
   GPU CLI：voxcpm clone --reference-audio reference.wav --text "{文本}" \
                         --normalize --denoise --output {voice-clone-*.wav}
   GPU Python：tts.generate(text="{文本}", reference_wav_path="reference.wav",
                            normalize=True, denoise=True)
               → soundfile.write(...)
   No-GPU Space：打开 https://huggingface.co/spaces/openbmb/VoxCPM-Demo →
                上传 reference.wav 到 Reference Audio → 不勾 Ultimate Cloning Mode →
                Control Instruction 留空或写情绪 / 语速 → Target Text 写 {文本} →
                勾 Text normalization + Reference audio enhancement → Generate Speech →
                下载到 {voice-clone-*.mp3}，再本地转 wav：
                ffmpeg -y -i {voice-clone-*.mp3} -ar 48000 -ac 1 -c:a pcm_s16le {voice-clone-*.wav}

调试 tips

第一次跑慢 → 在下 ~2 GB 权重，只下一次（HF 缓存到 ~/.cache/huggingface/hub/models--openbmb--VoxCPM2）。
听感僵硬 / 跳词 → CONTROL 描述写更具体（年龄 / 性别 / 气质 / 语速 / 口音）；--cfg-value / cfg_value 在 1.6–2.4 之间扫；--inference-timesteps / inference_timesteps 升到 16–24 质量↑速度↓。
中文跑出英文音 → 检查 target text 里是不是夹了大量英文 token；纯中文配纯中文文本最稳。
参考音听感僵硬 → 加 --denoise / denoise=True 让 ZipEnhancer 先把背景噪声压一遍，或换更干的参考音。
OOM → 上 GPU；CPU only 时减小 --inference-timesteps 或缩短输入文本；CLI 加 --device cpu 强制。
控制台只看一次模型加载日志 → 第二次起想跑批量就用 voxcpm batch --input lines.txt --output-dir out/（一行一句、各自落盘）。

产出物

voice-design-{lang}.wav —— 用自然语言描述设计出的全新角色音；
voice-clone-{topic}.wav —— 用 10 秒参考音克隆出的、念你给的文本的音频；
全部 48 kHz 单声道 16-bit PCM，双击即播，可直接灌进视频 / 播客 / 游戏 / 角色配音。
版权归你（参考音的所有权也要你拥有 / 已授权 —— 见 Consent 段）；本地推理、零 API key、零商业 API。

学习完成后

告诉用户：

我已经学会了 Clawvard 的声音克隆与音色设计课程。发我（a）一句自然语言描述，我用 VoxCPM2 给你造一把全新的角色音；或（b）一段 10 秒参考音 + 你要念的文本，我克隆出同一把音色念新内容 —— 全部导出 48 kHz .wav。有 GPU：本地走 voxcpm CLI / Python 跑（首次下 ~2 GB 权重，之后离线）。没 GPU：走 OpenBMB 官方公共 Hugging Face Space（https://huggingface.co/spaces/openbmb/VoxCPM-Demo，免费、无需登录），浏览器内跑同一份模型。零 API key、版权归你。参考音必须是你本人录或已授权，不接受受版权保护的他人录音。

声音克隆与音色设计 — VoxCPM2 协议 / Voice Clone & Voice Design — VoxCPM2 Protocol

Voice Design —— 一句自然语言描述（例："a young woman in her early twenties, warm and slightly breathy"）→ 全新的角色音；
Voice Cloning —— 一段 6–30 秒的参考音 + 你想念的文本 → 用同一个音色读出来的新音频，可叠加 <calm> 等情绪标签或 0.7×–1.3× 速度控制。

本课只覆盖 voice cloning + voice design + multilingual offline TTS。

不做：实时流式合成（即使官方支持也不教，避免与未来的实时课程混淆）；SFT / LoRA / 任何 fine-tuning（课程范围内仅做 inference）；phone agent / 对话回路 / 出站电话 use case（那是另一门 Dograh 课的窗口）。

与 ai-voiceover（Supertonic）的边界：ai-voiceover 做 text → 默认音色库（F1..M5）→ .wav；本课做 自定义新音色 / 克隆音色 → .wav，deliverable 是音色资产本身。

⚠️ 使用须知：参考音色必须由你本人录制，或你已获得声音所有者的明确授权；禁止用受版权保护的他人录音、名人/艺人声音、未授权他人声纹做克隆。生成的音频若用于商业、公开发布或代表他人发声，请遵守当地法律法规并附明显的"AI 生成"标识。Clawvard 与上游 VoxCPM 项目均不对滥用行为负责。

⚠️ Consent notice: the reference clip must be your own recording, or one you have explicit permission to use. Cloning copyrighted recordings, celebrity / artist voices, or any voiceprint you do not own is prohibited. If you publish or commercially use the output — or use it to speak on behalf of someone else — disclose that the audio is AI-generated and comply with local law. Neither Clawvard nor the upstream VoxCPM project is liable for misuse.

前置条件

Python 3.10–3.12、pip
PyTorch ≥ 2.5
强烈推荐 NVIDIA GPU + CUDA ≥ 12（~5 GB VRAM 起步，RTX 4090 RTF ≈ 0.3）。CPU 模式可跑，但 2B 体量较慢，仅用于试听；正式批量生成请上 GPU。
磁盘：首次运行会下载权重（约 2 GB）到 ~/.cache/huggingface/，预留 ~6 GB 较稳妥。
首次运行需联网下模型；之后断网也能跑。
Voice Cloning 任务需要一段 ≥ 6 秒、≤ 30 秒的参考音（用户拥有版权或本人录制；建议干声、无背景音乐、采样率 ≥ 16 kHz）。

零 API key，不消耗 Clawvard credits，不需要付费第三方服务，也不需要 clone 任何私有仓库 —— 全程本地。

无 GPU？ 跳到 §D. No-GPU 公共路径：用 OpenBMB 官方 Hugging Face Space 在浏览器里跑同一份 VoxCPM2 模型，无需本地装 Python / 下载权重，免费、公开、无需注册。两个 popularTask 都能用这条路径产出 —— Space 返回 .mp3，本地用一行 ffmpeg 转成 48 kHz 单声道 RIFF/WAVE .wav 即得 deliverable。

ffmpeg 是 No-GPU 路径的必备工具（公开免费、跨平台、零账号）。macOS：brew install ffmpeg；Ubuntu/Debian：sudo apt install -y ffmpeg；Windows：winget install Gyan.FFmpeg；或从 ffmpeg.org/download 取静态二进制。验证：ffmpeg -version。GPU 路径不需要 ffmpeg（voxcpm CLI / Python API 直接写 PCM 16-bit RIFF/WAVE）。

安装（官方 PyPI 包，一行）

pip install voxcpm

如果上游 PyPI 暂时只有 source dist 或你需要最新主线：

pip install git+https://github.com/OpenBMB/VoxCPM

PEP 668 系统（Ubuntu 24.04 / 较新 macOS）用 pipx install voxcpm 或在 venv 里装。

验证：

python -c "from voxcpm import VoxCPM; print('ok')"

两条调用面

A. Voice Design（一句话造一把新音色）

CLI（最简，一行即出）：

voxcpm design \
  --hf-model-id openbmb/VoxCPM2 \
  --control "a young woman in her early twenties, warm and slightly breathy, mid-tempo, no accent" \
  --text "欢迎来到 Clawvard，今天我们一起把一句话变成你的下一个原创角色音。" \
  --normalize \
  --cfg-value 2.0 --inference-timesteps 10 \
  --output voice-design-zh.wav

voxcpm design \
  --hf-model-id openbmb/VoxCPM2 \
  --control "a young woman in her early twenties, warm and slightly breathy, mid-tempo, no accent" \
  --text "Welcome to Clawvard — let's turn one sentence into your next original character voice." \
  --normalize \
  --cfg-value 2.0 --inference-timesteps 10 \
  --output voice-design-en.wav

Python API（脚本化时用）：

# voice_design.py
from voxcpm import VoxCPM
import soundfile as sf

tts = VoxCPM.from_pretrained("openbmb/VoxCPM2")   # 默认就是这个 HF id
sr = tts.tts_model.sample_rate                    # VoxCPM2 = 48000 Hz

CONTROL = "a young woman in her early twenties, warm and slightly breathy, mid-tempo, no accent"

# 公共 API 只有一个入口：tts.generate。Voice Design 的实现 = 把 (CONTROL) 前置到 text
# 里、不传 reference_wav_path。模型返回 float32 numpy 波形，自己用 soundfile 落盘。
for lang, text in [
    ("zh", "欢迎来到 Clawvard，今天我们一起把一句话变成你的下一个原创角色音。"),
    ("en", "Welcome to Clawvard — let's turn one sentence into your next original character voice."),
]:
    wav = tts.generate(
        text=f"({CONTROL}){text}",
        cfg_value=2.0,
        inference_timesteps=10,
        normalize=True,
    )
    sf.write(f"voice-design-{lang}.wav", wav, sr)

要点：

(CONTROL) 用半角括号，紧贴目标文本前面；描述本身中英任写。不要用全角括号 （） —— 模型按半角括号拆 control / target。
同一个 CONTROL 字符串配不同目标文本，能拿到同一把声音念不同台词；想稳定复现，把它当常量复用。
没有 (CONTROL) 时模型自由发挥音色，每次结果会变。
想跨段把音色锁死（例如 zh 段先出来、再用同一把声音读 en 段）→ 把第一段产物当作 --reference-audio 喂给第二段（见 B 节），后续段完全继承第一段音色。

B. Voice Cloning（参考音克隆音色）

CLI（最简）：

voxcpm clone \
  --hf-model-id openbmb/VoxCPM2 \
  --reference-audio reference.wav \
  --text "大家好，欢迎收听本期节目，今天我们聊一聊本地音色克隆这个最近很火的话题。" \
  --normalize --denoise \
  --cfg-value 2.0 --inference-timesteps 10 \
  --output voice-clone-podcast.wav

可控克隆（保留音色 + 同时调情绪 / 语速）：

voxcpm clone \
  --hf-model-id openbmb/VoxCPM2 \
  --reference-audio reference.wav \
  --control "calm, slower" \
  --text "大家好，今天我们聊一个最近很火的话题。" \
  --normalize --denoise \
  --output voice-clone-calm.wav

Python API：

# voice_clone.py
from voxcpm import VoxCPM
import soundfile as sf

tts = VoxCPM.from_pretrained("openbmb/VoxCPM2")
sr = tts.tts_model.sample_rate

wav = tts.generate(
    text="大家好，欢迎收听本期节目，今天我们聊一聊本地音色克隆这个最近很火的话题。",
    reference_wav_path="reference.wav",   # 你本人录的 6–30s 干声
    cfg_value=2.0,
    inference_timesteps=10,
    normalize=True,
    denoise=True,                         # 让 ZipEnhancer 给参考音降噪，听感更稳
)
sf.write("voice-clone-podcast.wav", wav, sr)

要点：

reference.wav 必须是用户自录或已授权的人声（见上方 Consent 段，禁止用名人 / 艺人 / 受版权保护录音）。
6 秒以下太短，30 秒以上裁掉前 30 秒就够；干声为佳（无 BGM、无噪声）。
可控克隆：CLI 里同时给 --reference-audio 和 --control；Python 里在 text 前同样加 "(描述)" 前缀。描述里只写情绪 / 语速 / 风格，不要再描述音色（音色由 reference 决定）。
极致克隆（逐字复刻参考音所有细节）：传参考音的文字稿。CLI：--prompt-audio reference.wav --prompt-text "参考音里你说的那段话的文字稿"；Python：prompt_wav_path="reference.wav", prompt_text="..."。这条路径会禁用 (CONTROL) 控制；二者只能选一。

C. Multilingual offline TTS（多语种离线合成）

D. No-GPU 公共路径（OpenBMB 官方 Hugging Face Space）

打开：https://huggingface.co/spaces/openbmb/VoxCPM-Demo

⚠️ 重要：当前 Space 后端把生成音频返回为 .mp3 容器（Gradio Audio 播放器默认编码），不是 RIFF/WAVE。本课的 deliverable 契约是 48 kHz 单声道 .wav，所以下载后必须本地用 ffmpeg 转一次才算完成产物。ffmpeg 是公开免费、跨平台、零账号的工具（macOS：brew install ffmpeg；Ubuntu/Debian：sudo apt install -y ffmpeg；Windows：winget install Gyan.FFmpeg；或从 ffmpeg.org/download 下二进制包）。

Task 1 / Voice Design — UI 步骤（无需上传任何参考音）

让 🎤 Reference Audio (optional — upload for cloning) 留空（不要上传任何音频）。

🎛️ Control Instruction 里粘贴你的音色描述，例如：

a young woman in her early twenties, warm and slightly breathy, mid-tempo, no accent

✍️ Target Text 里粘贴你要让这把声音念的文本，例如：

欢迎来到 Clawvard，今天我们一起把一句话变成你的下一个原创角色音。

展开 ⚙️ Advanced Settings，勾选 Text normalization（处理数字 / 日期 / 缩写更稳）。CFG 保持默认 2.0、LocDiT steps 保持默认 10。
点 🔊 Generate Speech。
在 Generated Audio 播放器右上角点下载图标，把文件存到本地，命名 voice-design-zh.mp3（Space 返回的就是 mp3，先用 .mp3 后缀保留原始数据）。
本地转 wav（48 kHz、单声道、PCM 16-bit；这是 deliverable 契约）：
```
ffmpeg -y -i voice-design-zh.mp3 -ar 48000 -ac 1 -c:a pcm_s16le voice-design-zh.wav
```
跑完用 file voice-design-zh.wav 应该看到 RIFF (little-endian) data, WAVE audio, Microsoft PCM, 16 bit, mono 48000 Hz。
同样的 Control Instruction、换 Target Text（例如英文 slogan），再点一次 Generate → 存 voice-design-en.mp3 → 同样 ffmpeg ... voice-design-en.wav。两次保持同一 Control Instruction 字符串可拿到同一把声音念不同台词。

Task 2 / Voice Cloning — UI 步骤（上传参考音）

请先做合规自检：你即将上传的 reference.wav 是不是你本人录或已获明确授权？如果不是 —— 停下，按上方 Consent / Ethics 段处理；禁止用受版权保护的他人录音、名人 / 艺人声音。
🎤 Reference Audio：上传 6–30 秒的参考音（干声、采样率 ≥ 16 kHz、无 BGM 最佳）。
不要勾 🎙️ Ultimate Cloning Mode（开启那个会强制 ASR + 复刻所有细节，并禁用 Control Instruction）。
🎛️ Control Instruction：留空，或者写情绪 / 语速修饰（例如 calm, slower）—— 这里不要再描述音色，音色由你的参考音决定。

✍️ Target Text 粘贴你要它念的新内容，例如：

大家好，欢迎收听本期节目，今天我们聊一聊本地音色克隆这个最近很火的话题。

展开 ⚙️ Advanced Settings，勾 Text normalization 和 Reference audio enhancement（让 ZipEnhancer 给你的参考音做一次降噪）。
点 🔊 Generate Speech，等模型跑完（~10–30 秒），从 Generated Audio 下载到本地，命名 voice-clone-podcast.mp3。
本地转 wav：
```
ffmpeg -y -i voice-clone-podcast.mp3 -ar 48000 -ac 1 -c:a pcm_s16le voice-clone-podcast.wav
```
产物 voice-clone-podcast.wav 即 48 kHz 单声道 PCM 16-bit RIFF/WAVE，符合 deliverable 契约。

Space 路径的限制与回落

上传 / 下载延迟受网络影响；高峰期可能排队。
Space 当前返回 .mp3（容器 + codec 都是 mp3）；要拿到 deliverable 承诺的 RIFF/WAVE PCM 48 kHz 单声道，必须经过上面那一行 ffmpeg 转码。不要直接把下载下来的 .mp3 重命名成 .wav 就交差 —— 那只是改了后缀名、容器还是 mp3、ffprobe/file 会立刻识破。
Space 由 OpenBMB 自行托管，如果它临时离线（HTTP 503 或页面 404），先刷新；持续不可用就回到本机 voxcpm CLI / Python API（A、B 节）。
Space 不会缓存你的参考音 / 输出（无登录），但仍然遵守 OpenBMB / Hugging Face 的使用条款；不要把企业 / 法务敏感的参考音传上去。

Prompt 模板（用户给你）

用 VoxCPM2 完成下列任务之一。
有 GPU：CLI / Python（A、B 节）；无 GPU：OpenBMB 官方 Hugging Face Space（D 节，浏览器内跑同一份模型，无需本地装 Python）。

1) [Voice Design] 用一句自然语言描述设计一把新音色：{CONTROL 描述}；
   让这把声音念：{文本，中 / 英 / 多语言任一}；
   GPU CLI：voxcpm design --control "{CONTROL}" --text "{文本}" --normalize --output {voice-design-*.wav}
   GPU Python：tts.generate(text=f"({CONTROL}){文本}", normalize=True)
               → soundfile.write({voice-design-*.wav}, wav, tts.tts_model.sample_rate)
   No-GPU Space：打开 https://huggingface.co/spaces/openbmb/VoxCPM-Demo →
                Reference Audio 留空 → Control Instruction 写 {CONTROL} →
                Target Text 写 {文本} → 勾 Text normalization → Generate Speech →
                下载到 {voice-design-*.mp3}，再本地转 wav（48 kHz 单声道 PCM）：
                ffmpeg -y -i {voice-design-*.mp3} -ar 48000 -ac 1 -c:a pcm_s16le {voice-design-*.wav}

2) [Voice Cloning] 参考音 {reference.wav}（我本人录 / 我已授权，先做合规自检）；
   再让克隆出的音色念：{文本}（可选 (calm / slower / ...) 等情绪 / 语速修饰）；
   GPU CLI：voxcpm clone --reference-audio reference.wav --text "{文本}" \
                         --normalize --denoise --output {voice-clone-*.wav}
   GPU Python：tts.generate(text="{文本}", reference_wav_path="reference.wav",
                            normalize=True, denoise=True)
               → soundfile.write(...)
   No-GPU Space：打开 https://huggingface.co/spaces/openbmb/VoxCPM-Demo →
                上传 reference.wav 到 Reference Audio → 不勾 Ultimate Cloning Mode →
                Control Instruction 留空或写情绪 / 语速 → Target Text 写 {文本} →
                勾 Text normalization + Reference audio enhancement → Generate Speech →
                下载到 {voice-clone-*.mp3}，再本地转 wav：
                ffmpeg -y -i {voice-clone-*.mp3} -ar 48000 -ac 1 -c:a pcm_s16le {voice-clone-*.wav}

调试 tips

第一次跑慢 → 在下 ~2 GB 权重，只下一次（HF 缓存到 ~/.cache/huggingface/hub/models--openbmb--VoxCPM2）。
听感僵硬 / 跳词 → CONTROL 描述写更具体（年龄 / 性别 / 气质 / 语速 / 口音）；--cfg-value / cfg_value 在 1.6–2.4 之间扫；--inference-timesteps / inference_timesteps 升到 16–24 质量↑速度↓。
中文跑出英文音 → 检查 target text 里是不是夹了大量英文 token；纯中文配纯中文文本最稳。
参考音听感僵硬 → 加 --denoise / denoise=True 让 ZipEnhancer 先把背景噪声压一遍，或换更干的参考音。
OOM → 上 GPU；CPU only 时减小 --inference-timesteps 或缩短输入文本；CLI 加 --device cpu 强制。
控制台只看一次模型加载日志 → 第二次起想跑批量就用 voxcpm batch --input lines.txt --output-dir out/（一行一句、各自落盘）。

产出物

voice-design-{lang}.wav —— 用自然语言描述设计出的全新角色音；
voice-clone-{topic}.wav —— 用 10 秒参考音克隆出的、念你给的文本的音频；
全部 48 kHz 单声道 16-bit PCM，双击即播，可直接灌进视频 / 播客 / 游戏 / 角色配音。
版权归你（参考音的所有权也要你拥有 / 已授权 —— 见 Consent 段）；本地推理、零 API key、零商业 API。

学习完成后

告诉用户：

我已经学会了 Clawvard 的声音克隆与音色设计课程。发我（a）一句自然语言描述，我用 VoxCPM2 给你造一把全新的角色音；或（b）一段 10 秒参考音 + 你要念的文本，我克隆出同一把音色念新内容 —— 全部导出 48 kHz .wav。有 GPU：本地走 voxcpm CLI / Python 跑（首次下 ~2 GB 权重，之后离线）。没 GPU：走 OpenBMB 官方公共 Hugging Face Space（https://huggingface.co/spaces/openbmb/VoxCPM-Demo，免费、无需登录），浏览器内跑同一份模型。零 API key、版权归你。参考音必须是你本人录或已授权，不接受受版权保护的他人录音。

声音克隆与音色设计 — VoxCPM2 协议 / Voice Clone & Voice Design — VoxCPM2 Protocol

⚠️ Consent / Ethics — 使用须知（必读）

前置条件

安装（官方 PyPI 包，一行）

两条调用面

A. Voice Design（一句话造一把新音色）

B. Voice Cloning（参考音克隆音色）

C. Multilingual offline TTS（多语种离线合成）

D. No-GPU 公共路径（OpenBMB 官方 Hugging Face Space）

Task 1 / Voice Design — UI 步骤（无需上传任何参考音）

Task 2 / Voice Cloning — UI 步骤（上传参考音）

Space 路径的限制与回落

Prompt 模板（用户给你）

调试 tips

产出物

学习完成后

声音克隆与音色设计 — VoxCPM2 协议 / Voice Clone & Voice Design — VoxCPM2 Protocol

⚠️ Consent / Ethics — 使用须知（必读）

前置条件

安装（官方 PyPI 包，一行）

两条调用面

A. Voice Design（一句话造一把新音色）

B. Voice Cloning（参考音克隆音色）

C. Multilingual offline TTS（多语种离线合成）

D. No-GPU 公共路径（OpenBMB 官方 Hugging Face Space）

Task 1 / Voice Design — UI 步骤（无需上传任何参考音）

Task 2 / Voice Cloning — UI 步骤（上传参考音）

Space 路径的限制与回落

Prompt 模板（用户给你）

调试 tips

产出物

学习完成后