Vocal Remover（人声分离 / 去人声）
这是什么
用 Python 包 audio-separator 完成人声分离。该包使用的模型（MDX-Net、VR Arch、Demucs、MDXC/Roformer）与桌面软件 Ultimate Vocal Remover 5（UVR5） 完全同源——相当于把 UVR5 的引擎内核做成可自动调用的命令行。环境与依赖已全部预装在本机（隔离 venv），用户无需任何手动安装或云账号。四个模型（伴奏/人声/去混响/去噪）均未内置：首次使用时自动从 GitHub 下载并永久缓存到 models/ 目录，之后零联网。
用户怎么用（重点：不用敲命令）
本技能面向"不想碰命令行"的用户，触发方式就是大白话 + 文件：
- 用户直接说需求，例如：
- "帮我把这段视频的人声去掉"
- "提取这个音频的伴奏"
- "做一版卡拉OK"
- "用干净人声模型重跑"（默认模型伴奏更干净，人声那路可能带点伴奏残留，换人声向模型更纯） - 用户把音视频文件上传到对话，或给出本地路径。
- 我（助手）负责执行：调用本技能、运行分离脚本、把产物路径反馈给用户。
用户全程不需要知道 python、venv、命令行是什么。
> 一句话原则：用户只管"说要什么 + 给文件"，剩下全由我来做。
这个技能的优点（为什么用本地技能，而不是上云）
针对"去人声"这类需求，本地技能相比云端方案（如腾讯云 MPS 音频分离）有几个实打实的好处：
| 维度 | 本技能（本地离线） | 腾讯云 MPS 音频分离（云端产品） |
|---|---|---|
| 部署 | 跑在你本机，完全离线 | 腾讯云上跑，需注册账号、开通 MPS、做服务角色授权 |
| 费用 | 免费（只耗本机算力） | 按分钟计费：音频分离费 + 转码费两笔（国际文档约 0.0176 美元/分钟起，另加转码费；国内价以腾讯云计费页为准） |
| 数据流向 | 文件不出本机 | 要先上传到腾讯云 COS/URL，结果回传 COS/VOD——内部视频要出境 |
| 模型可控性 | 开源多模型可换（MDX/Roformer/VR），按质量挑 | 腾讯自研黑盒，不能换模型 |
| 输出 | 本地直接出 wav（伴奏/人声）+ 可选去人声版 mp4 | 输出回 COS/VOD，产物形态由模板定 |
| 速度 | 纯 CPU 较慢；本机有独显可开 GPU 自动加速 | 云端 GPU，量大时快 |
| 能力范围 | 专注去人声 / 人声提取这一件事 | 全家桶：转码、音画增强、媒体AI、字幕、智能擦除等，音频分离只是其中一项 |
| 适用 | 偶尔处理、隐私/合规敏感的内部素材 | 已在用腾讯云、要一站式媒体处理、大批量 |
对你（化工厂内部视频）最值的两条：一是数据不出本机（合规省心），二是零成本、随用随跑。MPS 的优势在"几十上百条视频批量上云做一套媒体处理流水线"那种团队型场景。
能处理什么 / 限制条件（格式 · 大小 · 时长 · 质量 · 其它）
输入格式（支持）
- 音频：wav / mp3 / flac / m4a / ogg / opus / aac / wma / wav 等 ffmpeg 能解码的格式。
- 视频：mp4 / mkv / mov / avi / webm / m4v / flv / ts（自动抽音轨；画面原样保留，去人声只换音轨）。
- 本质是先抽成 44.1kHz 立体声 WAV 再分离，所以只要是 ffmpeg 能解的文件基本都能吃。
输入格式（不支持 / 需先处理）
- 加密 / DRM 保护的音视频：如 Apple Music、Spotify、iTunes M4P、付费网课加密视频等，ffmpeg 解不开，直接失败——需先转成普通文件。
- 网络链接 / 在线流：B站、网盘分享页、直播流等链接不在处理范围，需你先下载成本地文件再给。
- 多音轨视频：视频里若有多条音轨（如原声+配音），只取默认第一条音轨处理，其它轨忽略。
- 极冷门编码：个别 ffmpeg 不支持的私有封装/编码会失败，属个例。
大小 / 时长（无硬上限，受算力与磁盘约束）
- 没有文件大小或时长的硬性上限。真正约束是内存与磁盘：
- 耗时与音频时长成正比：本机 53 秒视频约 19 秒（纯 CPU，约 2.8 倍实时）。粗估：几分钟的歌几十秒；几十分钟视频几分钟到十几分钟；1 小时视频约 20–30 分钟 CPU——可用，但别指望秒出。
- 内存：MDX 模型按块处理，常规文件不会爆内存；超过 1 小时或机器内存紧张时加
--chunk 600分块处理避免 OOM。 - 磁盘余量：视频会先抽成 WAV（约 10MB/分钟立体声），外加输出 wav。处理前确保输出盘有"源文件大小 + 时长×10MB×2"左右的空间。
- 采样率：模型固定 44.1kHz，其它采样率自动重采样，不影响结果。
- 声道：模型期望立体声；单声道会被上混为立体声处理。
质量边界（AI 估算，非无损切割）
- 分离是神经网络估算，不是物理切割。极端混音（人声与伴奏频谱严重重叠）可能残留少量人声或损失乐器细节，属正常；换更优模型（Roformer 系）可改善但非 100%。
- 人声类型：模型主要用音乐人声训练。对唱歌效果最好；对会议/播客类说话声通常也能分离，但未经专门训练，质量不如歌声稳定。
- 去混响/去噪：
Reverb_HQ_By_FoxJoy等模型可降低房间混响、环境噪声，但重度失真或底噪过大的录音改善有限，属"减轻"而非"消除"。 - 这是源分离（保音质），不是早期那种"反相消人声"——不会把伴奏也削掉，但也不可能像分轨工程那样彻底干净。
输出
- 默认 wav（无损），便于二次剪辑；可选
--format mp3/flac转码。 - 视频加
--mux-back产出去人声版 mp4：画面原样，音轨替换为伴奏；原片编码异常时会自动转成通用 h264/aac。 - 一次处理一个文件（批量文件夹模式尚未内置，需要可加）。
其它
- 语言无关：模型看的是音色特征，中/英/日等任何语种人声都能分离。
- 版权：你需自行确保对处理的音视频拥有合法权利，技能只负责技术处理。
技能包大小与内容（SkillHub ≤10MB 限制）
SkillHub 发布平台要求解压后文件夹 ≤10MB。本技能采用"纯代码 + 全量按需下载"：
发布包内容（zip 约 0.03MB / 解压约 0.09MB，远低于 10MB ✅）
SKILL.md+references/models.md：说明文档与模型选型指南。scripts/：主脚本separate.py+ 锁版本requirements.txt（约 20KB）。scripts/models/：仅引擎配套 JSON（各几 KB，离线预置，audio-separator 运行时必需）：mdx_model_data.json/vr_model_data.json/download_checks.json。- venv（torch / audio-separator 等约 300MB+）不进技能包，运行时由脚本在
~/.workbuddy/binaries下自动创建并走清华镜像安装。
为什么一个模型都不内置
最小模型 UVR-DeNoise-Lite.pth 也有 17.1MB，单个就超过 10MB 上限，因此无法内置任何模型。改为全部按需下载：
按需下载模型（首次使用时自动下载，之后永久缓存）
四个模型都不随技能包发布，首次使用对应 --model 时自动从 GitHub Releases 下载到 models/ 目录，之后复用、不再重复下载：
| 模型 | 大小 | 触发方式 | 用途 |
|---|---|---|---|
UVR-MDX-NET-Inst_HQ_3.onnx |
~67MB | 默认（不指定 --model）或 --model inst |
伴奏最干净（默认模型） |
UVR-MDX-NET-Voc_FT.onnx |
~67MB | --model vocal 或 --model vocals |
人声纯净 |
Reverb_HQ_By_FoxJoy.onnx |
~64MB | --model reverb 或 --model dereverb |
去房间混响/回声 |
UVR-DeNoise-Lite.pth |
~18MB | --model denoise 或 --model noise |
去底噪/嘶声（输出"去噪后"与"噪声"两轨） |
下载走 ghproxy.net 国内加速代理 + 分块并行（实测比 GitHub 官方 CDN 快约 17 倍），每个模型约 2–5 分钟（视网速）。下载失败自动回退直连。
还需联网的场景
- 首次安装技能时：venv 依赖从清华镜像下载（约 1–2 分钟）。
- 首次使用任一模型时：自动下载对应模型（约 2–5 分钟/个，仅一次）。
- 主动换用未内置的大模型（如 Roformer 系 300–640MB）：按需下载。
首次配置为什么慢 / 现在为什么快
首次搭建时确实下了不少东西，分两块：
- Python 依赖（torch 2.6.0、torchvision、audio-separator、onnxruntime、imageio-ffmpeg 等，约 300MB）：走清华镜像，1–2 分钟就好。
- 模型下载（四个模型都需要，均不内置）：
- 每个约 18–67MB，托管在 GitHub Releases CDN。
- 脚本自动走 ghproxy.net 国内加速 + 分块并行下载（比直连快约 17 倍），每个约 2–5 分钟。
- 只下一次，之后永久缓存在models/目录，不再重复。
> 最快上手路径：第一次用会触发一次模型下载（约 2–5 分钟），之后同模型秒开。
稳定性保障（本机已处理，重装也不踩坑）
以下坑已在脚本与依赖锁版本里解决，正常跑不会触发；换机器重装也会靠锁版本自动避开：
- 依赖锁版本：
scripts/requirements.txt锁定了全部依赖版本（含torch==2.6.0、torchvision==0.21.0），重装不会再去拉错配的新版。 - torch 钉 2.6.0+cpu：本机 CPU 上 torch 2.13 经 oneDNN 指令派发会段错误（exit 139）。脚本在 import torch 前已设
DNNL_MAX_CPU_ISA=SCALAR/ONEDNN_MAX_CPU_ISA=SCALAR规避；另设KMP_DUPLICATE_LIB_OK=TRUE容忍系统里多份冲突的libiomp5md.dll（Adobe/Altium 自带旧版）。 - torchvision 钉 0.21.0：与 torch 2.6 配套。venv 若自动装到 0.28（给 torch 2.8）会报
operator torchvision::nms does not exist，锁版本已杜绝。 - ffmpeg 命名：audio-separator 内部用
ffmpeg -version做检查，而 imageio-ffmpeg 自带二进制名不是ffmpeg.exe。脚本已把它复制为 venvScripts/ffmpeg.exe（在 PATH 上），保证命中。 - 模型配套 JSON 已预置：audio-separator 运行时还会去 raw.githubusercontent.com 拉三个 JSON（本机网络常被重置）。现已预置在
scripts/models/，运行时完全离线。 - 路径返回值是相对路径：
separator.separate()返回相对 output_dir 的路径，脚本已统一转绝对路径，否则合成视频/清理按 cwd 解析会失败。
GPU 自动加速
- 自动检测：audio-separator 内置 CUDA 检测——只要 venv 里装了
onnxruntime-gpu，运行时会自动用 CUDA Execution Provider 加速，无需改代码。脚本启动会打印当前用的是 GPU 还是 CPU（[device] 推理设备：...）。 - 如何开启 GPU：首次安装时加
--gpu（即python separate.py --setup-only --gpu），会在 CPU 依赖基础上安装onnxruntime-gpu并移除 CPU 版，之后自动加速。 - 本机实情（重要）：你的机器有 NVIDIA GTX 970（麦克斯韦架构，4GB），但当前为求稳定装的是 CPU 版 torch，
torch.cuda.is_available()为 False，实际走的是 CPU。而且本机 CPU 是 i7-13700KF（16 核），对这个任务比老旧的 GTX 970 更快——在你这台机器上，CPU 模式既稳又快，不建议换 GPU 包。GPU 加速在"有较强独显（如 RTX 系）的机器"上才有意义。
工作流（助手执行侧）
- 确认输入是本地音频/视频文件。若用户只给了视频链接（如 B站），先提示其下载为本地文件再处理（下载不在本技能范围）。
- 运行主脚本
scripts/separate.py。脚本自动用隔离 venv、配置 ffmpeg、执行分离并打印 JSON 结果：
- 音频输入：直接分离为人声/伴奏。
- 视频输入（mp4/mkv/mov/avi/webm/m4v/flv/ts）：脚本用内置 ffmpeg 自动抽音轨→分离；加--mux-back会再额外产出去人声版视频（保留原画面、音轨替换为伴奏）。
---format：伴奏/人声输出格式，默认 wav（无损、便于二次处理），可选 mp3/flac。
- 默认模型即满足绝大多数"去人声保伴奏"场景，无需指定--model。 - 解析脚本输出的 JSON：
instrumental=伴奏路径，vocals=人声路径，instrumental_video=去人声版视频（仅视频输入 + --mux-back 时），elapsed_sec=耗时。把路径反馈给用户，并按"伴奏/人声/去人声视频"分别说明。 - 大文件（>1 小时）或内存紧张时加
--chunk 600分块处理。 - 想要更纯净的人声：加
--model model_bs_roformer_ep_317_sdr_12.9755.ckpt（首次按需下载，约 300–640MB）。
高级：手动一行命令（仅当确实需要自己跑时）
python scripts/separate.py "<输入文件>" --mux-back
其余可选参数：--out 输出目录 --model 模型名 --stem instrumental|vocals|both --format wav|mp3|flac --chunk 秒数 --gpu（仅配合 --setup-only）。
模型选择（详见 references/models.md）
- 不指定
--model：默认UVR-MDX-NET-Inst_HQ_3.onnx（伴奏干净），首次使用时自动下载（约 2–5 分钟，之后缓存复用）。 - 想要更干净的人声：加
--model vocal（或vocals），对应UVR-MDX-NET-Voc_FT.onnx，首次自动下载，人声残留更少。 - 想去除房间混响 / 环境回声：加
--model reverb（或dereverb），对应Reverb_HQ_By_FoxJoy.onnx，首次自动下载。 - 想去除底噪 / 嘶声：加
--model denoise（或noise），对应UVR-DeNoise-Lite.pth，首次自动下载（约 2 分钟，适合现场、手机等带环境噪声的录音，输出"去噪后"与"噪声"两轨）。 - 默认模型偏"伴奏干净"，人声那路可能带少量伴奏残留；要更高纯净度换 Roformer 系（首次按需下载，未内置）。
局限与注意
- 四个模型均不内置，首次使用时自动下载（约 2–5 分钟/个），之后缓存在
models/目录复用。 - 分离是 AI 估算，极端混音可能残留少量人声或损失乐器细节，属正常。
- SkillHub 发布版为纯代码包（解压约 0.09MB，远低于 10MB 上限），不含任何模型、全量按需下载。如需完整四模型离线版（~193MB），走手动分发渠道（桌面
vocal-remover.zip）。
Resources
scripts/
separate.py：主脚本，自动建环境 + 分离 + 输出 JSON 结果（含各分轨路径、设备、耗时）。requirements.txt：锁版本依赖清单，保证重装稳定、可复现。
models/
- （该目录仅含 3 个引擎配套 JSON；模型文件不内置，首次用到时自动下载到此处）
mdx_model_data.json/vr_model_data.json/download_checks.json：引擎运行期配套 JSON（离线预置）。- 四个模型（Inst_HQ_3 / Voc_FT / Reverb / DeNoise-Lite）首次使用时自动下载到本目录缓存。
references/
models.md：模型清单、选型建议、GPU 加速与国内模型下载镜像配置。
发布与归档（v1.0.0 起）
本技能本体纯本地运行（UVR5 引擎本地缓存），不依赖云文档读写。版本发布/归档默认落地乐享知识库《7.workbuddy.skill》（由技能全生命周期管家执行）；用户特别说明"归档到 WPS 云文档"时走 WPS 版。
