| 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
python3 "$SK" say --text "大家好，欢迎收看本期视频。" --out out.wav --play
python3 "$SK" design --instruct "温柔甜美的年轻女性主播" \
--text "今天我们聊聊苹果芯片上的本地语音合成。" --out out.wav
python3 "$SK" clone --ref-audio voice.wav --ref-text "参考音频里说的原话" \
--text "这句话会用参考音色说出来。" --out out.wav
python3 "$SK" clone --text-file script.txt --out narration.wav
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/card.json 的 voice.profiles[default]（经 _shared/channek.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.4
0.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。
