voxcpm

name	voxcpm
description	本地文字转语音 / 配音（VoxCPM2 跑在 Apple MLX 上，离线、可商用 Apache-2.0）。当用户要「配音 / 语音合成 / 文字转语音 / 给视频配旁白 / 念稿 / 做音频 / 声音克隆 / 造一个音色 / text-to-speech / TTS / voice over / narrate」，且未指定其他音频后端时使用。三模式：say 零样本内置音色、design 用文字描述造音色、clone 用参考音克隆音色；支持 30 语言 + 中文多方言、48kHz、长文本按句切分拼接，适合 5 分钟级旁白。是媒体生态里继出图(comfyui/codex/gemini)之后的第一条音频后端。

voxcpm —— 本地配音 / TTS（VoxCPM2 on Apple MLX）

给 Claude 补「音频自由」：在这台 Mac 上离线把文字合成成 48kHz 录音棚级语音，速度快过实时（M3 实测 RTF ≈ 0.4~0.6），能力对标出图生态——文字描述造音色、参考音克隆、长旁白一把出。

角色边界：本 skill = MLX VoxCPM 运行时（zero-shot 克隆 / 内置 / 造音色 + media-studio 出片管线的 TTS 引擎）。要给某频道训练一个稳定的专属音色（录音 → LoRA 微调 → 合并 → MLX），去 voice-lab 音色工作台（~/Coding/Archer/voice-lab·管训练与生产模型）。二者分工：voice-lab 产模型、本 skill 管运行——训好的合并模型直接 clone/say --model <voice-lab>/models/<名>/mlx-8bit 就能跑（load_model 已放行 trust_remote_code·支持加载本地微调/合并模型）。

一条命令的三模式

入口 scripts/voxcpm_gen.py，任意 python 调用即可（脚本会自动重定向到专用 venv ~/.venvs/mlx-audio，并把模型经魔搭解析好）。stdout 只吐产物 wav 路径，进度走 stderr。

自动出厂清理（每段生成后）：① edge_fade 首尾去咔哒 ② denoise 逐段去底噪（默认开·--no-denoise 关·长稿停顿易产音乐噪声时关它、交给出片管线 tone_even）。注：不做「段尾毛刺裁剪」——那个会误伤以短字收尾的正常句（把结尾字裁掉）；VoxCPM 的段尾毛刺应在训练数据端根治（见 voice-lab prepare_dataset 裁 clip 尾），而非推理时补。

SK=~/.claude/skills/voxcpm/scripts/voxcpm_gen.py   # 或 skill 真身 .../media/audio/voxcpm/scripts/

# ① say —— 零样本，内置音色
python3 "$SK" say --text "大家好，欢迎收看本期视频。" --out out.wav --play

# ② design —— 文字描述造音色（无需参考音，最适合定一个频道音色后大量配音）
python3 "$SK" design --instruct "温柔甜美的年轻女性主播" \
  --text "今天我们聊聊苹果芯片上的本地语音合成。" --out out.wav

# ③ clone —— 参考音 + 逐字转写，复刻音色
python3 "$SK" clone --ref-audio voice.wav --ref-text "参考音频里说的原话" \
  --text "这句话会用参考音色说出来。" --out out.wav

# ③' clone（频道固定音色首选）—— 自动读 _channel/channel.json 的 voice.profiles[default]
#     在频道目录内 / 设 $MEDIA_STUDIO_CHANNEL 即可，连 --voice 都不用；多音色用 --voice-profile <key>。
#     LoRA 型 profile（engine=voxcpm2-mlx-lora）会**自动加载专属合并模型**（mlx_model）+
#     prompt_wav/prompt_text 提示条——出片管线（voicegen）走的就是这条，不必手传 --model
python3 "$SK" clone --text-file script.txt --out narration.wav

# ③'' clone --voice —— 显式指一份 voice.md（channel.json 缺失时的兜底）
python3 "$SK" clone --voice path/to/voice.md --text-file script.txt --out narration.wav

# 长旁白：文本入文件，自动按句切分逐段生成再拼接
python3 "$SK" say --text-file script.txt --out narration.wav

info 子命令打印 venv / 模型路径 / 采样率 / engine（+ 解析到的频道音色 profile）。音色解析优先级：显式 --ref-audio/--ref-text（及显式 --model）> 频道 _channel/channel.json 的 voice.profiles[default]（经 _shared/ms_channel.py 读取，--voice-profile 选 key）> --voice 指的 voice.md frontmatter。

频道 profile 两型（engine 字段路由·resolve_channel_ref）：

型	engine	字段	行为
LoRA 型（生产推荐）	voxcpm2-mlx-lora	mlx_model + 可选 prompt_wav/prompt_text	--model 自动取 mlx_model（voice-lab 训 LoRA→合并→转 MLX 的专属音色模型·音色烤进权重·稳定不抽卡）；提示条可选（提声纹相似度 0.866→0.889·prompt_text 为内联转写文本，也兼容文件路径）；无提示条也能出声（音色在权重）。mlx_model 目录缺失 / engine 未知 → 清晰报错 fail-fast，不静默降级到基座冒充频道音色
零样本型	缺省 / voxcpm-mlx	ref_wav/ref_text（文件路径）	原行为·基座 + 参考音克隆·向后兼容。相对路径文件若还没就位（P3 物理迁移前）自动回落 voice.md 解析出的旧路径——零回归

⚠ 音色字段可指向频道外绝对路径（如 voice-lab 工作台）= 外部依赖：风格卡打包分发时音色不自包含。

关键参数

参数	默认	说明
--timesteps	10	CFM 扩散步数。越低越快；7 是速度/质量平衡点；要更快可降到 5
--cfg	2.0	无分类器引导强度，越高越贴指令、可能越僵
--model	频道 LoRA 型 profile 的 mlx_model → 否则 mlx-community/VoxCPM2-8bit	可显式传 repo id 或本地目录覆盖；基座可换 -4bit（更小更快）/ -bf16（更高质量）
--max-chars	120	长文本分句打包的单段上限
--no-chunk	关	短文本不切分
--no-denoise	关	关闭逐段去噪（默认开，见下「去噪是固定步」）
--play	关	生成后 afplay 试听

去噪是固定步（raw 层稳定铁律）

每段生成后都过一遍 RNNoise 去噪，默认开，不是可选项。 VoxCPM2 的 CFM 扩散逐段随机，克隆 v2 参考音（本身底噪 ≈ -64dB）时会逐幕飘——同一参考音、同一参数，有的段干净（-99dB）、有的段带底噪（-54/-60dB）。去噪不做就翻车。

• 怎么修的：synthesize() 里每段生成后立刻调 denoise_segment()，经 ffmpeg highpass=f=50,arnndn=m=assets/rnnoise/sh.rnnn（RNNoise speech 专用模型）压底噪，再拼接。highpass 砍次声轰鸣，arnndn 做 VAD 门控去噪。
• 验收标准：每段 raw 底噪 ≤ -80dB（实测多到 -inf）。校验：ffmpeg -i seg.wav -af astats=metadata=1 -f null - 2>&1 | grep "Noise floor dB"。
• 不伤音色：RMS 与 4kHz+ 高频能量去噪前后差 < 0.05dB（实测），不闷、不截语音、时长不变。
• 逃生口：--no-denoise 关掉（会退回逐幕不稳的 raw 行为，仅调试用）。ffmpeg 缺失或去噪失败时自动原样返回，不阻断出片。

速度与选型（重要）

• say / design 是快路（RTF ≈ 0.40.5）：5 分钟旁白约 23 分钟出。做自媒体批量配音优先用 design 定个音色 + 长文本切分。
• 零样本 clone 偏慢（RTF ≈ 3）：每次都要编码参考音；只在必须复刻特定嗓音时用，长稿会成倍变慢。频道 LoRA 型 profile 的 clone 不受此累（音色在权重·提示条编码开销小·RTF ≈ 0.5-0.9，生产出片走这条）。
• 想要中文方言（粤语 / 四川话 / 东北话等）或调情感语速：写进 --instruct 描述里（design 模式）。

模型管理（别乱放）

• 模型 mlx-community/VoxCPM2-8bit（3.0GB）走魔搭 ModelScope下载，落标准缓存 ~/.cache/modelscope——脚本里固定用 snapshot_download，幂等、按 repo id 引用，不硬编码路径。换模型只改 --model。
• 推理环境是专用 venv ~/.venvs/mlx-audio（装了 mlx-audio + modelscope），不污染日常 current。
• 下载渠道为什么不走 HF：本机 huggingface.co 不可达、hf-mirror 对该 repo 会 308 跳回被墙 origin。完整规约见 ~/.claude/rules/model-download.md。

兜底：高质量 PyTorch 路线

需要更高保真、或 MLX 版异常时，可退回原版 VoxCPM2（PyTorch）在 $VOXCPM_HOME（默认 ~/Coding/Hub/VoxCPM，模型在其 pretrained_models/VoxCPM2，4.6GB）。但慢得多（MPS RTF ≈ 11，降噪器还卡 CPU），仅作高质量兜底，不做日常批量。

排错

• ModuleNotFoundError: mlx_audio：说明没跑在专用 venv 里。脚本靠 sys.prefix 判重定向；若你手动指定了别的 venv，直接用 ~/.venvs/mlx-audio/bin/python 调。
• 不要用 voxcpm 这个命令本身（原项目的 shim 会用 pkg_resources.requires 误报 torchcodec 缺失而秒退）——本 skill 完全绕开它，直接调 mlx-audio。
• 下载卡住 / 报 “not on huggingface.co”：确认走的是魔搭而非 HF（脚本已设 HF_HUB_OFFLINE=1）。

更多：音色描述写法、方言、长稿编排见 reference/voice-design.md。