---
name: rap-clone-workflow
description: 对标说唱视频全链路仿制总控 — 编排 5 个子技能：S1 下载(rap-clone-s1-download)→S2 节奏DNA拆解(rap-clone-s2-dna)→S3 仿写歌词(rap-clone-s3-lyrics)→S4 克隆音色TTS(rap-clone-s4-tts)→S5 对拍(rap-beat-align)→S6 交付。阶段间只认契约文件 dna_card.json / lyrics_final.json / tts_report.json。触发词：仿写说唱、克隆说唱、对标视频仿写、说唱全链路。
---

# rap-clone-workflow 总控（对标说唱全链路编排）

职责：**按顺序调度 5 个子技能 + 守 6 道关卡**。所有执行细节在各子技能内，本文件只管编排、契约、关卡。

**状态：v1。** 各环节单独已验证（下载 / DNA 拆解 / 对拍 / TTS），全链路串联请逐关卡人工验收后再放开自动执行。

## 编排链

```
S0 输入清单（本技能负责，缺则追问）
 ↓
S1 rap-clone-s1-download   → 01_download/{source_video.mp4, audio.wav}
 ↓ G1 视频完整
S2 rap-clone-s2-dna        → 02_analysis/{dna_card.json, vocals.wav, clone_sample.wav}
 ↓ G2 歌词人工校对 + DNA 卡确认
S3 rap-clone-s3-lyrics     → 03_lyrics/lyrics_final.json（frozen=true）
 ↓ G3 用户定稿冻结
S4 rap-clone-s4-tts        → 04_tts/{dry_vocal.wav, tts_report.json}
 ↓ G4 音色"像" / G5 失配<2%
S5 rap-beat-align          → 05_align/{mix, 纯人声, click, 验证图, report.json}
 ↓ G6 click 耳朵终审
S6 交付（本技能负责）：报全部文件绝对路径 + 交付清单
```

## S0 输入清单

1. 对标视频链接（抖音/B站/小红书等）；
2. 仿写要求：主题/产品/卖点 + 口吻 + 押韵偏好 + 想保留哪些原词梗；
3. 伴奏来源：默认用对标视频分离的伴奏（S2 的 no_vocals.wav）；用户自备则给路径；
4. 项目代号 slug（英文短横线）。

## 目录约定

每个项目一个独立目录（`<workspace>` 换成你的工作区根目录）：

```
<workspace>/rap_clone/<slug>/
  01_download/   source_video.mp4 / audio.wav / source_info.txt
  02_analysis/   demucs输出 / clone_sample.wav / dna_card.json / dna_card.md
  03_lyrics/     lyrics_draft.md / lyrics_final.json
  04_tts/        dry_vocal.wav / tts_report.json
  05_align/      mix / 纯人声 / check_click / 验证图 / align_report.json
```

## 三份契约文件（阶段间只认文件，不认口头）

| 契约文件 | 产出 | 消费 | 关键字段 |
|---|---|---|---|
| `02_analysis/dna_card.json` | S2 | S3 / S4 / S5 | tempo_bpm / beat_phase / beat_period / gap_beats / phrase_pattern / n_phrases / first_phrase_beat / lyrics / clone_sample / voice_notes |
| `03_lyrics/lyrics_final.json` | S3 | S4 / S5 | frozen=true 才可进 S4；phrases[{idx,chars,text}]（字数=phrase_pattern 逐项对应） |
| `04_tts/tts_report.json` | S4 | S5 | voice_id / speech_rate / measured_bpm / dna_bpm / mismatch_pct / iterations |

契约字段缺失 = 该阶段打回上游，不允许"先跑着后面补"。

## 验收关卡汇总

| 关卡 | 阶段 | 内容 | 通过标准 |
|---|---|---|---|
| G1 | S1 | 视频 | 完整可播、时长与平台一致 |
| G2 | S2 | DNA 卡 | 歌词人工校对 + 密度读数确认 + 克隆素材试听 |
| G3 | S3 | 歌词 | 字数模式程序核验 + 用户定稿冻结 |
| G4 | S4 | 音色 | 试听"像不像" |
| G5 | S4 | TTS | 试听无读错 + 速度失配 <2%（或明示接受 S5 拉伸） |
| G6 | S5 | 对拍 | click 耳朵终审 + median ≤10ms |

## 总控铁律

1. **顺序不可跳**：DNA 卡未确认不写词；歌词未冻结不合成；TTS 失配 >2% 且用户未接受拉伸方案不进 S5。
2. **每阶段完成立即向用户报文件绝对路径**，等关卡确认再进下一阶段。
3. **画面用户手动剪辑**——本工作流交付到音频为止。
4. 单站故障不跨站修补：某站验收不过，回到该站的技能重做，不允许下游"顺手改"上游产物。

## 依赖速查

- 子技能：`rap-clone-s1-download` / `rap-clone-s2-dna` / `rap-clone-s3-lyrics` / `rap-clone-s4-tts` / `rap-beat-align`
- 对拍代码：本仓库 `scripts/`（measure_tempo.py 测速 / global_tempo_fix.py 全局校正 / align_phrases.py 对齐终稿 / verify_alignment.py 复测 / diag_silence.py 阈值诊断）
- TTS：火山引擎豆包语音 API，调用封装 `scripts/tts.py`（Key 走环境变量 `DOUBAO_SPEECH_API_KEY`）
- 音色复刻：火山引擎控制台人工提交样本（`scripts/tts.py` 亦含 `clone_voice()` API 尝试，以控制台文档为准）
- demucs / faster-whisper / RubberBand 4.0.0（安装见 README）