Sound Skill
能力
/sound-design//sd//音色设计— VoxCPM2 进程内 mlx_audio 音色生成/sound-extract//se//提取音色— 从视频/音频提取最佳音色片段/sound-clone//sc//克隆— IndexTTS-2 零样本音色克隆与配音/sound-asr//sa//转写— ASR 语音转文字、字级时间戳、FunASR/CAM++ 说话人分离（FunASR / Qwen3 / MiMo 混合模式）/sound-asr-engine//sa-engine//asr引擎— 查看/切换 ASR 引擎（funasr|qwen|hybrid）/sound-library//sl//音色库— 管理共享音色库/sound-jobs//sj//进度— 查看长任务（转写/克隆/设计/提取）的实时进度，是上述每个长任务指令的配套进度查看入口
指令路由
当用户消息以以下指令开头时，按对应能力处理。指令后的内容原样作为该能力的参数或自然语言需求解析。
在 Claude 中，真正注册 slash command 的文件位于 .claude/commands/*.md；本节是能力路由说明，不替代 Claude 命令文件。
| 指令 | 别名 | 能力 | 对应脚本 |
|---|---|---|---|
/sound-design |
/sd, /音色设计 |
VoxCPM2 音色设计 | scripts/voxcpm2_design.py |
/sound-clone |
/sc, /克隆, /配音 |
IndexTTS-2 声音克隆/长文本配音 | scripts/voice_clone.py |
/sound-asr |
/sa, /转写, /识别, /声音识别 |
ASR 声音识别/转录（FunASR / Qwen3 / MiMo 混合） | scripts/asr_transcribe.py |
/sound-asr-engine |
/sa-engine, /asr引擎 |
查看/切换 ASR 引擎 | scripts/asr_engine.py |
/sound-extract |
/se, /提取音色 |
视频/音频提取音色 | scripts/voice_extract.py |
/sound-library |
/sl, /音色库 |
音色库管理 | scripts/voice_library.py |
/sound-jobs |
/sj, /进度, /任务 |
长任务进度查看 | scripts/sound_jobs.py |
Claude 命令文件：
.claude/commands/sound-design.md和.claude/commands/sd.md.claude/commands/sound-clone.md和.claude/commands/sc.md.claude/commands/sound-asr.md和.claude/commands/sa.md.claude/commands/sound-extract.md和.claude/commands/se.md.claude/commands/sound-library.md和.claude/commands/sl.md.claude/commands/sound-jobs.md和.claude/commands/sj.md
路由要求：
/sound-clone必须调用 IndexTTS-2 声音克隆流程；长文本默认使用--split auto智能拆段、分批配音、最终合成。/sound-asr支持funasr、qwen、hybrid三种引擎。默认funasr使用已验证稳定的FunAudioLLM/Fun-ASR-Nano-2512+ FunASR/ModelScope：macOS 自动优先 MPS，Windows/其他主机可用 CPU；hybrid通过 MiMo-V2.5-ASR 在线转写，再用本地 Qwen3-ForcedAligner-0.6B-8bit 对齐，密钥只读MIMO_API_KEY；在线分段默认并发 4，可由mimo_asr.concurrency或--api-concurrency调整，本地对齐保持串行。默认引擎由processing.asr.engine决定，可用/sound-asr-engine切换。/sound-design必须调用 VoxCPM2 本地 mlx_audio 音色设计流程，生成结果登记到全局音色库。/sound-extract必须从视频/音频中截取最佳音色片段，并登记到全局音色库。/sound-library只做音色库查询、删除等管理操作。- 未带 slash 指令但意图明确时，也按上述五个能力匹配；不引入第六种能力或额外模型路径。
示例：
/sound-clone voice-elearning-20260623 -f long-script.txt
/sound-asr meeting.mp4 --granularity char --format srt,json
/sound-design -q "沉稳男声，中文，适合课程旁白"
/sound-extract lecture.mp4 --min 20 --max 30
/sound-library list
服务与目录
- 所有模型进程内加载（
mlx_audio），无 HTTP 服务。 - MLX 模型根目录:
~/.sound-skill/models/mlx-community（旧~/.omlx/models/mlx-community自动回退）；MLX 模型从 HuggingFace 下载，IndexTTS-2/FunASR 从魔搭下载。 - IndexTTS-2 模型:
~/.models/IndexTeam/IndexTTS-2 - 全局音色库:
~/.sound-skill/voices - 平台: Apple Silicon 上 Fun-ASR-Nano 优先 MPS，Qwen/VoxCPM2 优先 MLX；Windows 支持 Fun-ASR-Nano CPU；
lib.platform.detect_platform()会返回对应平台。
这些值都可在 config.yaml 修改。
音色设计 (/sound-design)
/sd -q "温柔的女声，青年，中文，适合朗读"
行为：
- 生成 VoxCPM2 prompt。
- 通过
mlx_audio本地调用 VoxCPM2 生成（instruct = 音色描述）。 - 模型固定为
VoxCPM2-bf16。 - 生成 WAV 后登记到全局音色库。
音色提取 (/sound-extract)
/sound-extract video.mp4
/se recording.wav --min 20 --max 30
/提取音色 /path/to/video.mp4
行为：
- 视频文件先提取音频（ffmpeg）。
- 逐帧分析 RMS 能量、ZCR、频谱质心。
- 检测静音节点作为自然切割点。
- 滑动窗口评分（能量动态、音高变化、音色丰富度、静音占比、边界质量）。
- 选取 20-30 秒最佳片段，归一化后保存。
- 自动登记到全局音色库。
参数：--min/--max 控制片段时长，--output 指定输出目录。
对应脚本：scripts/voice_extract.py
音色克隆 (/sound-clone)
/sound-clone <音色库ID或WAV路径> -t "要说的文本"
/sc voice-elearning-20260623 -t "大家好，欢迎来到今天的课程。"
/克隆 voice-elearning-20260623 -f scripts.txt
行为：
- 从音色库或文件加载参考音色（20-30 秒）。
- 本地加载魔搭
IndexTeam/IndexTTS-2权重。 - 通过
indextts.infer_v2.IndexTTS2做零样本克隆。 - 长文本按段落/句子/分句智能拆解，逐段配音。
- 分段 WAV 自动拼接成最终 WAV，同时保存 manifest。
- 支持 4 种情感控制模式。
- 自动将输出重采样至 24000Hz 系统标准。
参数：-t/--text 合成文本（可多次指定），-f/--text-file 批量配音文本文件，--split auto|on|off 长文本拆段，--max-segment-chars 控制每段长度，--segment-silence-ms 控制拼接静音，--speed 语速，--model-dir 指定模型目录，--check-local 检查本地运行环境。
情感控制参数：
- --emo-method 0 默认，从说话人音频提取情感
- --emo-method 1 --emo-ref-audio <path> 从独立音频提取情感
- --emo-method 2 --emo-vector <8d> 8 维情感向量 [开心,愤怒,悲伤,恐惧,厌恶,忧郁,惊喜,平静]
- --emo-method 3 --emo-text <描述> 自然语言情感描述
- --emo-alpha 0.0-1.0 情感强度（默认 0.6）
注意：IndexTTS-2 不支持直接的「声音转换」（voice conversion）。如需转换已有语音的音色，请先用 asr_transcribe.py 转写文本，再用克隆功能重新合成。
模型下载：
python scripts/download_indextts2_model.py --output-dir ~/.models
python scripts/install_indextts2_runtime.py
python scripts/voice_clone.py --check-local
IndexTTS-2 运行库默认安装到 ~/.sound-skill/runtimes/index-tts/.venv，与主 Python 环境隔离。
对应脚本：scripts/voice_clone.py
ASR (/sound-asr)
/sound-asr recording.wav --granularity char --format srt,json
/转写 meeting.mp4 --format md
/sound-asr meeting.mp4 --granularity sentence --speaker --format json
/sound-asr meeting.mp4 --engine hybrid --granularity char --format json
行为：
- 视频/音频先转成 16kHz mono WAV。
- 对长音频先做智能切分：基于 RMS/VAD、静音间隙和低能量谷选择边界；不是按固定时长硬切。
- 按引擎使用本地 Fun-ASR-Nano、本地 Qwen3-ASR，或 MiMo API 分段转写文本；混合模式要求环境变量
MIMO_API_KEY。 funasr默认使用FunAudioLLM/Fun-ASR-Nano-2512本地模型；macOS Apple Silicon 优先 MPS，Windows/其他 CPU 主机使用 CPU。qwen与hybrid使用本地Qwen3-ForcedAligner-0.6B-8bit分段对齐，再按--granularity char|sentence|paragraph输出单一粒度时间戳。- 默认不做人声分离；需要 speaker 时加
--speaker，不用时加--no-speaker或省略。 - 本地 Qwen3-ASR 不返回 speaker 字段；开启
--speaker时使用 FunASR/CAM++ 并按时间映射到输出粒度。 - 对齐覆盖率必须达到 100%：
text、timestamps、有效正时长时间戳数量必须一致；否则失败并继续重切，不能导出假成功结果。 - JSON 的
timestamps只包含请求的粒度，不同时导出字、句、段三套时间戳。 - 转写完成后自动校验输出 JSON（结构/覆盖/单调/跨度）并打印
校验: OK|FAIL报告；复检任意输出用python scripts/asr_validate.py <file.json>，不要每次重写校验代码。
音色库 (/sound-library)
/sound-library
/sl rm <name-or-id>
对应脚本：
python scripts/voice_library.py list
python scripts/voice_library.py delete <name-or-id>
代码入口
scripts/voxcpm2_design.py # VoxCPM2 进程内 mlx_audio 音色设计
scripts/voice_extract.py # 视频/音频音色片段提取
scripts/voice_clone.py # IndexTTS-2 零样本音色克隆/配音
scripts/asr_transcribe.py # Fun-ASR-Nano 默认转写，Qwen3/Hybrid 可选，FunASR/CAM++ speaker 分离
scripts/voice_library.py # 音色库管理 CLI
lib/voice_library.py # 音色库核心
lib/tag_system.py # VoxCPM2 标签系统
lib/model_loader.py # 配置读取
