sound-split（声音分裂）

Sound Split — AI 智能音频分离工具

一句话说明

上传一段音频或视频，AI 自动将其中的人声、伴奏、鼓点、贝斯、钢琴等音轨一一分离出来，支持在线预览每条音轨并单独下载。

附件文件说明

本 Skill 附带完整的核心实现代码（位于 rules/ 目录）：

这些文件是纯文本，可直接复制到本地使用。部署方式见下方「使用流程」。

核心能力一览

前置条件

环境要求

Python 包安装（必须执行一次）

pip install fastapi uvicorn demucs ffmpeg-python

⚠️ 首次运行时会自动下载 AI 分离模型（约 300~500MB），请确保网络通畅。下载完成后会缓存到本地 ~/.cache/demucs/ 目录，后续运行不再重复下载。

验证环境是否就绪

# 1. 验证 FFmpeg 安装
ffmpeg -version | head -1

# 2. 验证 demucs 可用（首次会触发模型下载）
python3 -m demucs --version

# 3. 如果以上两个命令都正常输出，说明环境已就绪

使用流程（完整操作步骤）

第一步：启动服务

cd <skill_path>/audio-separator
python3 server.py

预期结果：终端显示以下内容说明启动成功：

╔══════════════════════════════════════════════╗
║   🎵 音频分离工具 - AI 智能分轨              ║
║   http://127.0.0.1:8765                       ║
╚══════════════════════════════════════════════╝
[init] 已从历史记录恢复 N 个任务

服务监听地址：http://127.0.0.1:8765

失败处理：

• 若报错 ModuleNotFoundError: No module named 'demucs' → 先执行 pip install demucs 再重启
• 若报错 ffmpeg not found → 先安装 FFmpeg 再重启
• 若端口 8765 被占用 → 终端执行 lsof -i :8765 | grep LISTEN | awk '{print $2}' | xargs kill -9 释放端口后重试

第二步：打开操作页面

浏览器访问以下地址：

💡 推荐直接使用 /app.html 主页面，所有核心操作都在一个界面完成。

第三步：上传文件并配置参数

在主页面（app.html）上按以下顺序操作：

1. 点击上传区域或拖拽文件到虚线框内

- 支持格式：MP3, WAV, FLAC, OGG, M4A（音频）；MP4, MOV, AVI, MKV, FLV（视频） - 文件大小建议 ≤ 100MB - 音频时长建议 ≤ 10 分钟（过长会显著增加处理时间）

1. 选择分离轨道数

- 2 轨道（默认）：输出「人声」+「伴奏」，适合翻唱、去人声场景 - 4 轨道：输出「人声」+「鼓」+「贝斯」+「其他」，适合编曲分析、混音练习 - 5 轨道：输出「人声」+「鼓」+「贝斯」+「钢琴」+「其他」，适合专业音乐制作

1. 选择处理精度

- 推荐模式（默认）：均衡质量与速度，适合大多数场景 - 高品质模式：更精细的分离效果，处理时间稍长 - 经典模式：基础分离能力，速度最快 - 增强模式：针对特定类型优化

1. 点击「开始分离」按钮

第四步：等待处理完成

• 页面会自动显示进度条（0% ~ 100%）
• 进度阶段说明：

• 典型耗时参考：

- 3 分钟歌曲（2 轨道）：约 30~60 秒 - 5 分钟歌曲（5 轨道）：约 1~3 分钟 - 10 分钟视频（4 轨道）：约 3~8 分钟 - > 10 分钟的文件不推荐，可能需要 10 分钟以上

• 异常情况处理：

- 进度卡住超过 5 分钟无变化 → 刷新页面后在历史记录中查看任务是否已完成 - 显示错误信息 → 查看终端 server.py 的错误日志，常见原因：文件损坏、磁盘空间不足、FFmpeg 未安装

第五步：预览与下载

分离完成后页面自动展示结果：

每条音轨提供以下操作：

输出文件位置：<skill_path>/audio-separator/outputs/{task_id}/ 下包含各音轨的 MP3 文件

输出文件命名规则：

API 接口详细说明

如需通过程序调用（而非浏览器界面），本工具提供完整的 RESTful API：

接口清单总览

1. 上传并分离 — POST /api/separate

请求格式：

POST /api/separate
Content-Type: multipart/form-data

请求参数：

model 可选值：

成功响应（HTTP 200）：

{
  "task_id": "a1b2c3d4e5f6",
  "status": "pending",
  "message": "任务已提交，请用 task_id 轮询进度"
}

错误响应：

• HTTP 400：不支持的模式: xxx 或 不支持的轨道数: xxx — 检查 model 和 stems 参数值
• HTTP 500：服务器内部错误 — 查看 server.py 终端日志

2. 查询任务状态 — GET /api/status/{task_id}

请求：GET /api/status/a1b2c3d4e5f6

成功响应示例（处理中）：

{
  "status": "processing",
  "progress": 65,
  "message": "Separating... 65% (30 lines processed)",
  "model": "htdemucs",
  "stems": "2stems",
  "filename": "song.mp3",
  "result": null
}

成功响应示例（完成）：

{
  "status": "completed",
  "progress": 100,
  "message": "Done!",
  "model": "htdemucs",
  "stems": "2stems",
  "filename": "song.mp3",
  "result": {
    "tracks": {
      "vocals": "vocals.mp3",
      "accompaniment": "accompaniment.mp3"
    },
    "output_dir": "outputs/a1b2c3d4e5f6"
  }
}

状态字段含义：

错误响应：HTTP 404 { "detail": "任务不存在" } — 检查 task_id 是否正确

3. 下载音轨 — GET /api/download/{task_id}/{track_name}

请求示例：

GET /api/download/a1b2c3d4e5f6/vocals
GET /api/download/a1b2c3d4e5f6/accompaniment

响应：直接返回对应音轨的 MP3 文件（Content-Type: audio/mpeg）

错误响应：

• HTTP 404：任务目录不存在或音轨文件不存在 — 先确认任务已完成且 track_name 正确

4. 裁剪音轨片段 — POST /api/trim

请求格式：

POST /api/trim
Content-Type: application/x-www-form-urlencoded

请求参数：

请求示例：

POST /api/trim
task_id=a1b2c3d4e5f6&track_name=vocals&start_time=30&end_time=90

响应：返回裁剪后的 MP3 文件，文件名格式为 {track_name}_{起始时间}_{结束时间}.mp3（例如 vocals_0030_0130.mp3）

错误响应：

• HTTP 400：缺少必要参数，或 end_time <= start_time
• HTTP 404：task_id 或 track_name 对应的文件不存在
• HTTP 500：FFmpeg 裁剪过程出错

5. 获取历史记录 — GET /api/history

响应示例：

[
  {
    "task_id": "a1b2c3d4e5f6",
    "filename": "song.mp3",
    "model": "htdemucs",
    "stems": "2stems",
    "status": "completed",
    "track_count": 2,
    "created_at": "2026-04-15T11:30:00",
    "exists": true
  }
]

其中 exists: true/false 表示该任务的输出文件在磁盘上是否仍然存在（可能已被清理删除）。

6. 清理任务文件 — DELETE /api/cleanup/{task_id}

响应：{ "message": "已清理 N 个文件" }

⚠️ 此操作会永久删除该任务的所有输出文件和原始上传文件，不可恢复。建议仅在确认不再需要结果时使用。

项目文件结构

sound-split/
├── SKILL.md                          # 本说明文档
├── audio-separator/                  # ★ 主程序目录（核心实现全部在此）
│   ├── server.py                     # ★ Web 服务主程序（FastAPI 应用）
│   │                                 #   包含：API 路由、后台分离逻辑、
│   │                                 #   历史管理、进度追踪、FFmpeg 调用
│   ├── static/
│   │   ├── index.html                # ★ 工具主操作页面（上传 + 配置 + 分离 + 结果展示）
│   │   ├── editor.html               # ★ 音频裁剪编辑器（波形可视化 + 时间选区 + 导出）
│   │   └── landing.html              # 产品介绍页（Demo 试听 + 场景说明）
│   ├── uploads/                      # 上传文件临时存储目录（运行时自动创建）
│   ├── outputs/                      # 分离结果输出目录（每个任务一个子文件夹）
│   ├── trims/                        # 裁剪片段临时存储目录
│   └── history.json                  # 任务历史持久化记录（最多保留 50 条）
├── scripts/                          # 技能脚本目录
└── assets/                           # 技能资源目录

标记 ★ 的为核心实现文件，缺一不可。其余目录均为运行时自动创建，不需要手动准备。

关键约束与注意事项

1. 隐私安全：所有音频处理均在本地机器完成，数据不会上传到任何外部服务器。AI 模型仅在本地运行。

1. 资源需求：

- 内存：建议至少 4GB RAM（处理长音频时峰值可达 2~3GB） - 磁盘空间：模型缓存 ~500MB + 输出文件（每首歌曲约 10~50MB） - CPU/GPU：优先使用 GPU 加速（需 NVIDIA CUDA），无 GPU 时自动回退 CPU 运行（速度慢 3~10 倍）

1. 并发限制：同一时间只处理一个任务。提交新任务时会排队等待当前任务完成。

1. 文件限制：

- 单文件大小：建议 ≤ 100MB - 单次时长：建议 ≤ 10 分钟 - 超出限制不会报错但可能导致处理极慢或内存不足

1. 输出格式：固定输出 MP3（320kbps），不支持自定义码率或格式（如需 WAV 可通过 FFmpeg 手动转码）。

1. 服务生命周期：关闭终端窗口或 Ctrl+C 会停止服务。已完成的任务结果保存在 outputs/ 和 history.json 中，重启服务后会自动恢复。

常见问题排查

适用场景举例

场景一：翻唱伴奏提取

1. 打开 http://127.0.0.1:8765/app.html
2. 上传原唱歌曲 MP3
3. 选择 2 轨道 + 推荐模式
4. 点击「开始分离」，等待完成
5. 下载 accompaniment.mp3 作为伴奏使用

场景二：视频 BGM 替换

1. 打开工具页面
2. 直接上传 MP4 视频文件（无需预先提取音频）
3. 选择 2 轨道
4. 完成后下载 accompaniment.mp3（原背景音乐）
5. 在视频剪辑软件中替换为自己的 BGM

场景三：编曲学习分析

1. 上传想学习的歌曲
2. 选择 5 轨道 + 高品质模式（更精准的乐器分离）
3. 分别下载 drums.mp3（鼓点）、bass.mp3（贝斯线）、piano.mp3（钢琴部分）
4. 反复聆听单轨，学习每种乐器的编排方式