From 3eb7d5514c9d2d9136b31c9ab4e71ec29142d732 Mon Sep 17 00:00:00 2001
From: yumoqing <yumoqing@gmail.com>
Date: Mon, 6 Jul 2026 11:55:45 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20update=20demucs-separate=20=E2=80=94=20?=
 =?UTF-8?q?add=20separate=5Ffull=20MIDI=20replace=20mode?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 wwwroot/api_doc.md | 42 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)

diff --git a/wwwroot/api_doc.md b/wwwroot/api_doc.md
index ad4bc5f..e942b87 100644
--- a/wwwroot/api_doc.md
+++ b/wwwroot/api_doc.md
@@ -1886,20 +1886,54 @@ curl -X POST 'https://token.opencomputing.cn/llmage/v1/pipeline/submit' \
 
 ### 2. 音频分离 — ky-demucs-separate
 
-分离音频中的人声和伴奏。
+分离音频中的人声和伴奏。支持两种模式。
+
+**分离模式：**
+
+| mode | `task_type` | 说明 |
+|------|-------------|------|
+| 两轨分离（默认） | `separate` | 分离人声(vocals)和伴奏(no_vocals)，返回2个文件 |
+| 全轨MIDI替换 | `separate_full` | 分离人声+drums+bass+other四轨，每个乐器轨转MIDI后用GM音源替换，混音为伴奏 |
+
+**全轨MIDI替换流程：**
+1. demucs 4轨分离 → vocals / drums / bass / other
+2. 每个乐器轨 basic-pitch → MIDI
+3. MIDI 用 FluidR3_GM SoundFont 渲染（drums=ch10鼓组, bass=prog34电贝司, other=prog1钢琴）
+4. ffmpeg 混音 → accompaniment.wav
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `audio_url` | string | 是 | 音频文件URL |
+| `task_type` | string | 否 | `separate`（默认，两轨）或 `separate_full`（全轨MIDI替换） |
 
 ```bash
+# 两轨分离（默认）
 curl -X POST 'https://token.opencomputing.cn/llmage/v1/pipeline/submit' \
   -H 'Authorization: Bearer ***' \
   -H 'Content-Type: application/json' \
   -d '{"model":"ky-demucs-separate","audio_url":"https://example.com/music.mp3"}'
+
+# 全轨MIDI替换
+curl -X POST 'https://token.opencomputing.cn/llmage/v1/pipeline/submit' \
+  -H 'Authorization: Bearer ***' \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"ky-demucs-separate","audio_url":"https://example.com/music.mp3","task_type":"separate_full"}'
 ```
 
-**响应：**
+**响应（两轨模式）：**
+
+```json
+{
+    "taskid": "luid_xxx",
+    "taskstatus": "SUCCEEDED",
+    "vocals_url": "https://token.opencomputing.cn/.../vocals.wav",
+    "accompaniment_url": "https://token.opencomputing.cn/.../no_vocals.wav",
+    "mode": "2stem",
+    "usage": {"audio_seconds": 240.0}
+}
+```
+
+**响应（全轨MIDI替换模式）：**
 
 ```json
 {
@@ -1907,6 +1941,10 @@ curl -X POST 'https://token.opencomputing.cn/llmage/v1/pipeline/submit' \
     "taskstatus": "SUCCEEDED",
     "vocals_url": "https://token.opencomputing.cn/.../vocals.wav",
     "accompaniment_url": "https://token.opencomputing.cn/.../accompaniment.wav",
+    "drums_midi_url": "https://token.opencomputing.cn/.../drums.wav",
+    "bass_midi_url": "https://token.opencomputing.cn/.../bass.wav",
+    "other_midi_url": "https://token.opencomputing.cn/.../other.wav",
+    "mode": "full",
     "usage": {"audio_seconds": 240.0}
 }
 ```