garveyhu 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/card.json 的 voice.profiles[default]
# 在频道目录内 / 设 $CHANNEK_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（card.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/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()，经 ffmpeghighpass=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。