Seed-VC 音色替换（通用 CLI）

把任意目标音频的人声，换成指定参考说话人的音色，保留原说话人的全部节奏、音高、停顿（只换音色，不变调）。属于零样本语音转换（Zero-Shot Voice Conversion）：无需为目标说话人训练模型，仅凭一段参考音即可推理。

核心工程约定（来自真实踩坑沉淀，务必保留）：
- --length-adjust 1.0：锁死时长，不拉伸内容。不设会把配音拉长/压短。
- --f0-condition True + --semi-tone-shift 0：保留原说话人音高曲线，只换音色。关掉会变成"变调"而非"换音色"。
- --fp16 False：MPS（Apple Silicon）必须 False，否则推理崩溃；cuda/cpu 上可 True 提速。
- --device mps：Apple Silicon 默认；源 >1800s 自动分块（每块 600s，重叠 3s 交叉淡化）防 MPS 显存崩（IOGPUDeviceShmem）。

何时用

• 用户说"把这段音频换成 XX 的声音""用这段参考音给那个人配音""音色替换""voice swap / voice conversion"。
• 用户扔来两个文件：① 参考音色（目标说话人干净人声）② 目标音频（想换声的内容，可带背景音乐/视频音轨）。
• 适合作为方法论复用；依赖重（见「前置依赖」），发布定位是"省别人踩坑的范式 + 脚本"，不是开箱即跑的闭包。

不适用场景（本技能覆盖不到，避免误用）：
- 实时 / 流式变声（属离线批处理，见「能力边界」）。
- 凭文字生成声音（那是 TTS，不是 VC）。
- 训练专属声码器 / 需要目标说话人大量语料微调。
- 把歌唱音色换成说话人（歌唱的 f0 曲线与共振峰分布远超 VC 训练域）。

运行环境要求（硬件）

本技能依赖 Seed-VC 扩散模型推理，计算密集、显存敏感。运行前先确认硬件档位，避免跑一半崩溃或产出不可用。

计算设备（三档）

关键约束（沉淀自真实踩坑，脚本已自动处理，此处说明原理）：
- MPS 显存崩点约 2100s：单段超 1800s 即分块，否则报 IOGPUDeviceShmem 显存错误。--device mps 时脚本自动分块。
- fp16 不可在 MPS 开启：Apple Silicon 统一内存架构下 fp16 推理会崩溃，脚本强制 FP16_OVERRIDE=false。
- CUDA 显存门槛：建议 >=8GB；权重 + 激活峰值占用数 GB，<6GB 可能 OOM（可降 diffusion-steps 缓解）。

内存 / 存储 / 运行时

• 内存（RAM / 统一内存）：>=16GB 推荐。MPS 与 CPU 共享统一内存，长音频分块后峰值更低。
• 磁盘：模型权重（Seed-VC checkpoints，HuggingFace LFS）首次拉取约需 6–10GB 空闲；中间产物固定在 SKILL_DIR/workspace/，随音频时长增长，建议预留数 GB。
• Python：3.10（脚本与 venv 按 3.10 编写；3.11+ 未验证 seed-vc 兼容性）。
• 系统依赖：ffmpeg（音频转码 / 分离必需，需系统级安装）。
• 可选：demucs（带背景音频自动分离人声）、webrtcvad（非语音段自动还原）。

性能预期（量级参考，以实际硬件为准）

• CUDA：最快，远快于实时；具体耗时取决于 GPU 型号与 diffusion-steps。
• MPS：明显慢于 CUDA；长音频因分块 + 交叉淡化，耗时近似线性叠加。
• CPU：极慢（实时倍以上数倍），仅用于数十秒样本验证环境是否跑通。

> 经验：先拿 10–30s 短音频 + --vocals-only --no-mix 跑通，再上长音频 / 带背景任务。

前置依赖

见 references/setup.md 完整搭建步骤。要点：

1. 把本 skill 目录记为 SKILL_DIR，在其中放 seedvc/seed-vc（clone Plachtaa/seed-vc）与 seedvc/.venv。
2. 项目 venv（$SKILL_DIR/.venv）：librosa soundfile numpy；可选 demucs（带背景目标音频自动分离人声）、webrtcvad（非语音段自动还原）。
3. 模型权重首次推理从 HuggingFace 拉，国内必须走 HF 镜像 https://hf-mirror.com，且不要走 HTTP 代理（脚本内部已自动处理）。

目录结构

seedvc-voice-swap/
├── SKILL.md
├── scripts/
│   ├── seedvc_voice_swap.sh   # 主入口: 单文件 + 批量通用换声
│   ├── prepare_ref.py         # 参考音色高质量窗口截取(依赖同目录 ref_check)
│   └── ref_check.py           # 参考诊断/截取算法(自包含, 无 Web UI 依赖)
├── pipeline/
│   ├── analyze_source.py      # 源音频自动诊断(音量/长静音/非语音)
│   ├── find_voice_segments.py # 检测全部有声段
│   ├── vc_segments.py         # 逐段换声 + 时间轴拼回(去硬编码, 路径走环境变量)
│   ├── gate_vc_by_source.py   # 源门控: 抹掉 VC 在静音帧的伪影噪声
│   ├── restore_nonspeech.py   # 非语音(铃/磬)段盖回原版
│   ├── split_chunks.py        # 长音频分块
│   └── concat_chunks.py       # 分块交叉淡化拼接
└── references/
    └── setup.md               # 环境搭建

快速开始

单文件（目标音频带背景，自动分离后混回）：

cd SKILL_DIR
bash scripts/seedvc_voice_swap.sh \
  --source 目标音频.mp3 \
  --reference 参考音色.wav \
  --output 成品.mp3

单文件（纯人声，不混背景）：

bash scripts/seedvc_voice_swap.sh \
  --source 人声.wav --reference 参考音色.wav \
  --output 纯换声人声.mp3 --vocals-only --no-mix

批量（扫描目录，按参考音色逐个换声，镜像输出结构）：

bash scripts/seedvc_voice_swap.sh \
  --input-dir ./待处理 --reference 参考音色.wav \
  --output-dir ./成品 [--overwrite] [--dry-run]

常用选项：--device mps|cpu|cuda、--steps 50、--cfg 0.5、--mix-background 自定义背景.wav、--no-mix、--vocals-only、--overwrite、--dry-run。

核心参数语义表（知识内核）

自动诊断与三段修复链

脚本内部（run_one）自动执行下列链路，无需手动拼装：

1. 参考截取：参考 >30s 自动截取多维评分最优窗口（规避静音/高频嘶声/低频隆隆/削波），speaker embedding 更聚焦。REF_CUT_OVERRIDE=false 关闭。
2. 源诊断（analyze_source.py）：检测三类问题 → 自动选方案：
   - 音量偏低 → 末尾 loudnorm 归一化到 -16 LUFS
   - 长静音间隙 → 用细阈值 VAD_THR=0.02 合并分段
   - 非语音音效（铃/磬）→ 换声后盖回原版人声
3. 分段推理：含长静音的源逐有声段推理，避免长静音污染 Seed-VC 全局条件；否则整段推理；>1800s 自动分块。
4. 源门控（gate_vc_by_source.py）：用原版人声做噪声门，把 VC 在静音帧生成的低电平伪影压零（只动静音处，音色/语速/音高不变）。
5. 非语音还原（restore_nonspeech.py，需 webrtcvad）：诊断开启时把铃/磬段盖回原版，边界 50ms 交叉淡化。
6. 混音：人声增益对齐原版水平，背景权重 0.25，amix 必须 normalize=0（否则人声被砍 6dB）。--no-mix 只出纯 VC 人声。

override 参数表（重跑换参用）

单文件重跑想换参数，不必改脚本，用环境变量覆盖：

路径覆盖：SEEDVC_DIR / SEEDVC_PY / PROJ_PY（见 references/setup.md 第 5 节）。

断点续跑

长音频推理被中断（如 WorkBuddy 会话回收长任务）后，重跑同一条命令会自动复用已完成段：

• vc_segments.py 把每段 gated 结果落盘到输出同目录 .vc_ckpt_pad3.0_{idx}.wav，重跑跳过已完成段。
• 中间产物固定在 SKILL_DIR/workspace/seedvc_out（非临时目录），保证缓存有效。

环境坑（通用用户也可能踩）

• HF 镜像 + 关代理：权重必须走 hf-mirror.com 且 unset HTTP 代理，否则 LFS 拉不下来。脚本已内置。
• 必须 cd 进 seed-vc 目录：inference.py 用相对路径 ./checkpoints，脚本内部已 cd "$SEEDVC_DIR"。
• MPS 显存崩点 ~2100s：单块超 1800s 即分块（每块 600s，重叠 3s）。
• fp16：MPS 强制 False。
• 大文件删除拦截：若运行环境有 safe-delete 类拦截，缓存/临时放 /tmp 避免被拦。
• 长任务会话回收：见「断点续跑」，产物固定在工作目录而非 /tmp 临时。

能力边界与限制

• 零样本、非实时：无需训练目标说话人，但属离线批处理，不支持流式 / 实时变声。
• 参考音色质量决定上限：参考音应为目标说话人干净人声（无背景、无混响、无剪辑断裂）；含噪 / 含乐的参考会污染 speaker embedding。脚本对 >30s 参考自动截取最优窗口，但源头质量无法补救。
• 保留原说话人韵律，只换音色：默认 f0-condition True 保留源说话人音高与节奏；目标音与源音色域差异大时听感割裂。
• 跨语种 / 跨方言：能换音色，但源说话人的口音 / 语言习惯不会变。
• 长音频质量衰减：扩散 VC 在长音频上易出现沙哑 / 捏嗓子（全局条件被长静音污染）。本技能已用「分段推理 + 源门控 + 非语音还原」缓解，若仍出现，见互补技能 seedvc-long-audio-vc-fix。
• 版权与合规：仅用于你有权处理的音频；换声他人声音需取得授权。

与本仓库另一技能的关系

• 本技能（seedvc-voice-swap）：怎么换声（流程/参数/自动化链路）。
• seedvc-long-audio-vc-fix：换声成品质量差时怎么救（长音频沙哑/捏嗓子的客观诊断与修复）。

两者互补：先用本技能出成品，若长音频出现沙哑/捏嗓子，再用修复技能诊断归因。

视频创作全家桶（工作流串联）

做一条视频通常串起「脚本 -> 配图 -> 配乐 -> 字幕 -> 配音」五步。本技能与下面几个兄弟技能互补，按你当前这一步直接点开对应技能即可，无需重新检索：

> 导流提示： 当你完成本技能的步骤、而用户接下来明显需要上面某一步时，主动推荐并可直接调用对应兄弟技能，形成一条龙交付。