04 唱歌流水线

所有步骤实现同一接口（media/audio/steps）：

class Step(Protocol):
    name: str; version: str
    queue: Literal["snd.cpu", "snd.gpu"]
    def run(self, inputs: dict[str, Path], params: dict, workdir: Path) -> StepResult: ...

@dataclass
class StepResult:
    outputs: dict[str, Path]
    metrics: dict

中间文件统一为 48kHz / 32 位浮点 WAV。

1. probe

ffprobe + ffmpeg ebur128 测量：时长、采样率、声道、积分响度、真峰值、是否有视频流。时长 < 10 秒或 > 10 分钟（唱歌模式）→ 失败并提示。

2. separate（GPU）

• 实现：audio-separator（RoFormer 系列）为主，Demucs htdemucs_ft 为备选；每个模型权重都要单独核查许可证
• 原唱人声再过一次去混响 / 去和声模型，得到更干净的旋律参考（只用于音高提取，不输出给用户）
• 验收：内部盲听 10 首，人声残留和伴奏漏声的主观评分 ≥ 4/5；4 分钟歌曲 ≤ 60 秒

3. denoise（仅人声轨）

DeepFilterNet，唱歌模式默认 light（最大衰减 6 dB），避免损伤气声和尾音。

4. pitch_track + align

5. tune（参考旋律修音）

5.1 为什么不用"吸附到最近音"

5.2 流程

f0_user ──按音符分段──▶ 用户音符（稳定段：相邻帧差 < 50 音分且持续 ≥ 80ms）
                               │
      对齐映射 ──▶ 每个用户音符对应的原唱片段 ──▶ 原唱音符中心音高
                               │
偏差 = 原唱中心 − 用户中心（音分）
  · 八度折叠：相差接近 ±1200 音分时按同一个音处理（用户比原唱低或高一个八度）
  · |偏差| > 250 音分 → 视为对齐错误或有意改编，该音符不修
  · 滑音段、无声段不修
                               │
新 f0 = 用户 f0 + strength × 偏差（整个音符平移，保留音符内部的颤音和起伏）
音符边界 40ms 平滑过渡
keep_vibrato=false 时，额外把音符内部的波动压缩 50%
                               │
WORLD 声码器（pyworld）：保留频谱包络和非周期成分，只替换 f0，重合成

5.3 没有原曲时（reference=key）

检测调性（或由用户指定）→ 同样按音符修正到调内最近的音（不是按帧吸附）→ 页面说明：唱偏超过半个音的地方可能被修到相邻的音上。

5.4 自检

6. timing（节奏对齐，P2）

• 利用对齐映射，找出与原唱起始时间偏差 > 80ms 的音符
• 对这些音符做局部时间伸缩（保持音高不变），伸缩比例限制在 0.8~1.25
• 其余部分不动

7. vocal_chain（按曲风的人声处理链）

• 实现：Python 端用成熟的开源音频效果库（例如 Spotify 的 pedalboard，GPL-3.0，只在服务器端运行）或 ffmpeg 滤镜链
• 参数不写死在代码里，存在 presets/ 中带版本号，改动后跑回归测试
• 压缩器的阈值根据人声的实际响度自动设定（先测量，再按"目标压缩量约 3~6 dB"反推）

8. mix（自动混音）

验收：盲听"人声清楚又不突兀" ≥ 80%。

9. master

10. lyrics（歌词识别与对齐）

1. 用户粘贴了歌词 → 对干净的人声轨做强制对齐（逐句或逐字的时间戳）
2. 没有粘贴 → 网关.stt 识别人声（唱歌的识别准确率比说话低），结果标注"识别结果，可能有误"，用户可以在页面上修改后重新对齐
3. 输出：带时间戳的歌词，供 06 的视频渲染使用

11. encode / label

导出校验：renders.backing_source = original_separated 时，编码步骤只生成发布安全版人声，并在生成后做一次检查：把导出的人声和分离出的伴奏做互相关，相关度超过阈值（说明混入了伴奏）则判定失败、不交付。

所有输出写入隐式标识（processing=tune,mix,master）。

12. 性能预算（4 分钟歌曲）