# music-separation

**Repository Path**: lp9906/music-separation

## Basic Information

- **Project Name**: music-separation
- **Description**: 本地运行的歌曲分离工具：上传一首歌 → **Demucs 分离为 4/6 条独立音轨**（人声/鼓/贝斯/其他 ± 吉他/钢琴 + 伴奏）→ 浏览器 **Web Audio 多轨同步试听**（采样级对齐），每轨可独立播放/音量/静音/独奏/下载。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-04
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 歌曲分离与混音编排台（music-analysis separation）

> 本地运行的**歌曲分离 + 多轨混音编排**工具：上传一首歌 → **Demucs 分离为 4/6 条独立音轨**（人声/鼓/贝斯/其他 ± 吉他/钢琴 + 伴奏）→ 浏览器 **Web Audio 多轨同步试听** → 用**时间脚本**编排每轨（音量/声像/静音、**音乐滤镜与均衡器**，可过渡、可跳转）→ **一键导出合成后的 WAV**。全程本地运行，音频不出机器。

**当前版本**：v1.1.0（纯分离产品形态；分析类功能已按产品定位裁剪）

---

## 核心功能

### ① 歌曲分离（Demucs，本地推理）
- **htdemucs（4 轨）**：人声 / 鼓 / 贝斯 / 其他（+ 伴奏 = 非人声之和）；
- **htdemucs_6s（6 轨）**：再独立出 **吉他 / 钢琴**；
- 模型权重自动下载（默认 hf-mirror.com 镜像，`HF_ENDPOINT` 可还原官方源）；首跑后离线可用；
- 坏音频文件**上传时即校验**（试解码前 2 秒），立即给出明确原因，不白跑任务。

### ② 多轨同步试听台（采样级对齐）
- Web Audio 全缓冲混合播放：全部轨道由同一时钟驱动，**采样级同步**；0.5~2x 变速、拖拽进度、m:ss 时间显示；
- 播放上下文**采样率跟随源文件**（离屏探测后同率建上下文，避免 44.1/48k 重采样差异）；
- 每轨**迷你波形（含播放进度层）+ 实时频谱**；任意轨独立下载 WAV；
- 每轨顶部工具栏一键 全部静音 / 全部恢复 / 全部重置。

### ③ 每轨"设置"弹窗（插件 + 滤镜，方便扩展）
- 行内点 **⚙** 打开该轨设置：**音量/声像/静音/独奏**（原曲轨同样可独奏）、**重置本轨**；
- **音乐滤镜**：下拉多选叠加 46 款效果——自研 21 款（滤波/均衡/动态/染色/调制/空间/成像，含黑胶、磁带、收音机、8-bit…）、Tone.js 开源 17 款、Pizzicato 开源 7 款、**10 段均衡器**（专用 EQ 面板：段滑杆/预设/旁路）；
- 内部为**插件/滤镜注册表**架构：新插件/滤镜注册后，弹窗、行内摘要、脚本键**自动出现**。

### ④ 时间脚本（自动混音编排，中英文皆可）

**语法速查（示例见下）**：
- 轨道：`人声/鼓/贝斯/伴奏/原曲/其他/吉他/钢琴`，`全部`=所有轨（英文原名同样可用）；
- 基础选项：`音量`（0~100% 或 0~1）、`声像`（-1~1）、`静音`（开/关/真/假）；
- 数值可带**过渡**：`300ms / 1.5s / 200毫秒`；支持**区间块** `0:30 ~ 1:00 { … }`；
- **进度跳转**：`0:45 { 进度 = 0:20 }`（段落循环/跳过前奏；触发点写 `0:00` 同样生效——开始播放或把进度拖回 0:00 即触发）；
- **滤镜集合**：`滤镜 = 黑胶、Tone 混响` / `滤镜 = 空`（整体替换当前生效滤镜）；
- **滤镜参数**（点号键 + 过渡）：`失真.失真量 = 35 300ms`、`黑胶.噪声 = 6`、`Tone混响.衰减 = 3`；
- **均衡器段键**：`均衡器.250Hz = -6 300ms`（10 段：31.5Hz~16kHz，dB 原域）。

```text
# ① 基础编排：音量/声像/静音（可过渡）
0:30 {
  人声, 鼓 {
    音量 = 40% 300ms      # 0.3s 线性过渡到 40%（不写时长=瞬时）
    声像 = -0.6
  }
  贝斯 { 静音 = 开 }
}

# ② 区间块：0:30~1:00 生效，1:00 自动回退区间前值
0:30 ~ 1:00 { 人声 { 音量 = 80% } }

# ③ 段落循环 / 起点跳转
0:45 { 进度 = 0:20 }              # 播到 0:45 自动跳回 0:20
0:00 { 进度 = 0:58 }              # 起点跳转：开始播放即跳到 0:58（跳过前奏）

# ④ 滤镜集合切换（F16.1）
1:05 { 人声 { 滤镜 = 黑胶、Tone 混响 } }    # 同组去重、顺序 = 链序
1:13 { 人声 { 滤镜 = 无 } }                 # 空 / 无 / 清除 = 清空全部滤镜

# ⑤ 滤镜参数（F16.2 点号键，值域与设置弹窗一致）
0:30 { 人声 {
  失真.失真量 = 35 300ms
  Tone混响.衰减 = 3          # UI 名去空格（或用规范键 t_reverb.decay）
  黑胶.单声道 = 开
} }

# ⑥ 均衡器段键（F17）
0:30 { 人声 { 均衡器.250Hz = -6 300ms  均衡器.2kHz = 3 } }
1:00 { 人声 { 均衡器.250Hz = 0  均衡器.2kHz = 0 } }
```
- 语法错误逐行定位（行:列 + 中文提示）；"校验 / 应用 / 停止 / 保存 / 导入导出"齐全；
- **手动拖动任何控件 = 临时覆盖脚本对应键**（状态列显示"手动优先/脚本控制"），停止脚本即恢复手动；
- 现成样例见 `scripts/`（林子祥曲集时间脚本 .txt），可在面板"导入 .txt"直接载入。

### ⑤ 下载"脚本合成的音乐"
- ⏱ 面板 **"导出混音 WAV"**：把当前脚本 + 手动混音 + **滤镜链**（含集合切换与参数自动化）**分段离屏渲染**成 44.1kHz 16bit 立体声 WAV 并下载；
- 自研/原生滤镜平滑近似过渡；Tone/Pizzicato 效果参数为阶梯近似（导出消息会提示）。

### ⑥ 历史任务即开即听
- 上传区下方 **"历史任务"**：已完成 Job 直接 **载入** 重建多轨台（源/分轨/波形原样），不必重新上传与分离；
- 任务元数据落盘 `job.json`（歌名/状态/耗时），重启后按 **job 数据**恢复历史（旧版仅产物目录不再凭空列出）。

---

## 使用场景

| 场景 | 做法 |
| --- | --- |
| **K 歌 / 消原声伴奏** | 上传歌曲 → 分离 → 下载 `accompaniment.wav`（或人声轨 Mute 后导出混音） |
| **扒谱 / 练耳** | 独奏（S）任一分轨跟听：只听鼓抓节奏、只听贝斯抓低音线、只听人声抓旋律；0.5x 变速跟练 |
| **乐器分轨练习** | 6 轨模型把吉他/钢琴独立出来，只留自己想练的声部当"伴奏" |
| **Remix / 混音素材** | 各轨单独下载，或先在多轨台调好平衡/声像再整体导出 |
| **段落循环跟练** | 脚本写 `进度`：反复 20~45s 副歌段自动循环跟唱跟练 |
| **音色实验 / 复古感** | 给原曲或任意轨加滤镜：黑胶、磁带、收音机、Tone 混响/回声…即听即调 |
| **成品导出分享** | 脚本应用后"导出混音 WAV"，编排好的版本直接当成品文件使用 |
| **曲库反复对比** | 历史任务列表随时载入旧歌，不需要重复跑模型 |

---

## 快速开始

### 环境

- Python ≥ 3.9 + [FFmpeg](https://ffmpeg.org/)（`PATH` 或 `MA_FFMPEG_BIN`/`MA_FFPROBE_BIN`）
- Node ≥ 18（仅前端构建需要）

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[web]"              # Web 服务
pip install -e ".[separation]"       # 分离引擎（torch/demucs，体积较大）
```

### 启动

```bash
python server/main.py                # 后端 http://127.0.0.1:8000（同源托管前端）
```

前端开发模式（可选热更）：

```bash
cd frontend && npm install && npm run dev   # http://127.0.0.1:5173（/api 代理到 8000）
```

### 使用

1. 打开页面，选择/拖入音频（mp3/wav/flac/m4a/ogg…；NCM/qmc 等加密壳请先转码）；
2. 选择模型：**htdemucs（4 轨）** 或 **htdemucs_6s（6 轨：吉他/钢琴）**；
3. 点"开始分离"——等待解码/推理（首跑自动下载模型权重，约几百 MB）；坏文件会在此之前被明确拒绝；
4. 完成后在"多轨同步试听台"：**拖动进度 / 变速** 熟悉全曲 → 任意轨 **⚙**（音量/声像/独奏/静音/**音乐滤镜**/**均衡器**）→ ⏱ 脚本编排（可先 **导入 .txt** 样例）→ **导出混音 WAV**；
5. 换歌？直接在 **历史任务** 载入已完成任务继续听/编。

## HTTP API（摘要）

| 端点 | 说明 |
| --- | --- |
| `GET /api/health` | 健康与能力检查（separation/ffmpeg/schema） |
| `POST /api/jobs` | 上传创建分离任务（multipart：file + model + config JSON；坏音频 → 400 BAD_AUDIO） |
| `GET /api/jobs` · `GET /api/jobs/{id}` | 任务列表 / 状态（stems/source/waveform URL、进度、错误） |
| `POST /api/jobs/{id}/cancel` · `DELETE /api/jobs/{id}` | 取消 / 删除任务 |
| `GET /api/jobs/{id}/source` | 原曲（Range 支持，播放/seek） |
| `GET /api/jobs/{id}/stems/{name}` | 分离轨 WAV（vocals/accompaniment/drums/bass/other/guitar/piano） |
| `GET /api/jobs/{id}/waveform?stem=` | 波形包络（min/max，按轨可选） |
| `GET /api/config/defaults` · `POST /api/config/validate` | 配置默认值 / 校验 |

任务生命周期：`queued → running → success | failed | cancelled`；单曲分离产物目录 `<data>/jobs/<id>/source/stems/*.wav`，任务元数据 `<data>/jobs/<id>/job.json`。

## 配置（环境变量）

| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `MA_WEB_HOST` / `MA_WEB_PORT` | `127.0.0.1` / `8000` | 服务监听 |
| `MA_WEB_DATA` | `webdata` | 任务数据根目录 |
| `MA_WEB_API_KEY` | 无 | 设置后所有 API 需 `X-Api-Key` |
| `MA_WEB_WORKERS` | `4` | 分离并发线程（建议 1~CPU 核数） |
| `HF_ENDPOINT` | `https://hf-mirror.com`（代码默认） | 模型下载源 |
| `MA_FFMPEG_BIN` / `MA_FFPROBE_BIN` | `ffmpeg`/`ffprobe` | FFmpeg 路径 |

## 许可与第三方

- 本项目代码：**MIT**（见 [LICENSE](LICENSE)）；
- 分离引擎 demucs 代码 MIT；**模型权重商用需自行确认**（训练数据含 MUSDB18 等）；
- 音乐滤镜：自研滤镜为原生 Web Audio 实现（零第三方依赖）；开源效果组直接引用 **Tone.js（MIT）** 与 **Pizzicato.js（MIT）**，噪声/IR 等素材程序化自生成，无外部音频资产——完整清单见 [THIRD_PARTY.md](THIRD_PARTY.md)。

## 目录

```text
server/                # FastAPI 分离服务（main/jobs/worker/settings）
music_analysis/        # 核心：io(解码/写出) + features/separation + config
frontend/              # Vite + 原生 TS 分离页（上传/多轨台/滤镜/时间脚本/导出）
  src/player/          # 播放引擎(engine)/滤镜(filters)/脚本(script)/设置弹窗(settingsdialog)
scripts/               # 时间脚本样例（.txt，面板可直接导入）
tests/                 # 解码 / 分离（门控真实推理）/ Web API 测试
docs/                  # 产品文档与设计归档（f15 脚本 / f16 滤镜 / f17 EQ 等，见 docs/README.md）
THIRD_PARTY.md / LICENSE / CHANGELOG.md
```

## 历史说明

本仓库早期版本包含音乐信息分析能力（节奏/调性/和弦/旋律/结构等，完整设计文档仍在 `docs/` 归档）；经产品定位调整，**代码已裁剪为纯分离链路**，历史文档保留供追溯。

## AI 协作

本项目在开发过程中由 AI 辅助完成，采用**双模型分工**：

- **DeepSeek v4 Pro**（`deepseek-v4-pro`）：负责**思考**——需求分析、方案设计（docs/design 文档）、代码审查、问题根因定位与决策；
- **DeepSeek v4 Flash**（`deepseek-v4-flash`）：负责**执行**——按定稿方案编码实现、单测与构建验证、拆分封装与文档同步；
- 协作模式：Pro 产出设计/结论 → Flash 落地实现 → 回归验证，形成"思考—执行—验证"闭环；
- **开发框架**：DeepSeek Harness（`deepseek-harness`）——双模型协同开发与验证的运行环境。