收录 Demucs 长视频分块与首音轨固定

[liuzhao1225]

变更说明

• 将 Demucs 改为按窗口流式分离：预先解码 PCM，携带重叠上下文，跨块线性交叉淡化，再按全局峰值流式写出最终 WAV。
• 抽取阶段显式使用 -map 0:a:0，保持多音轨视频固定使用第一条音频流。
• 新增 DEMUCS_CHUNK_SECONDS，默认 600 秒；空值使用默认值，非法值直接抛出明确错误。
• 成功与异常路径都会清理临时 PCM/float 文件；最终写入异常时删除两份半成品输出。
• 单块读取、推理和写出使用独立作用域，下一块推理前释放完整张量，仅保留 overlap tail；weakref 回归覆盖第二块入口。
• 临时输入启用 FFmpeg -rf64 auto，float32 stems 与最终 PCM16 输出使用 RF64，消除 4 GiB WAV 边界。
• 恢复旧 Demucs AudioFile 语义：固定首音轨、float32 解码、mono 复制为双声道，多声道只取前两路；真实 5.1 频率测试覆盖。
• 删除 handler 内基于两份 final 存在性的缓存短路；每次实际分离先清理旧 final/pending，完整生成两份同目录 pending 后再发布，异常会清除 pending 和已发布的单份 final，SIGKILL/掉电遗留会在 failed/running stage 恢复时完整重算。
• 中英文文档和示例环境变量说明内存边界、额外临时磁盘占用及 final/pending 发布与恢复策略。
• 已用普通 merge 同步 main 的 重做字幕、配音与组合输出模式 #125（6f78915）与 拒绝静默截短越界原音片段 #126（a139b74）变更。

原始实现致谢

感谢 @lyk-bit 在 #112 中提供初始实现和思路。本次按当前 main 重做并修正异常与配置边界，参考提交：

• 修复长视频人声分离耗尽内存
• 分离阶段抽音频时固定第一条音频流

提交中保留了 lyk-bit 的共同作者署名。

验证

• .venv/bin/python -m pytest backend/tests/test_demucs_adapter.py -q：27 passed。
• .venv/bin/python -m pytest backend/tests -q：395 passed，1 条既有 Python 3.12 audioop 弃用警告。
• Node 22.23.2 / npm 10.9.4：前端测试 13 passed；ESLint、TypeScript、Next 生产构建通过；生产依赖审计 0 vulnerabilities。
• 真实 FFmpeg 双音轨样本：第一轨 440 Hz、第二轨 880 Hz，抽取结果主频 440 Hz，输出 88,200 帧，确认第一音轨映射生效。
• 真实 FFmpeg 5.1 样本：前两路为 220/330 Hz，后置独有 440/550/880/990 Hz；输出只保留 220/330 Hz。mono float32 样本输出左右声道逐样本相同。

真实 Demucs 验收边界

本机复用的项目 .venv 已有 Torch 2.12.0，但缺少 torchaudio；导入 demucs.api 即以 ModuleNotFoundError: No module named 'torchaudio' 停止，因此本次没有声称完成真实 htdemucs_ft 推理。具备完整依赖和模型下载条件后可复现：

git submodule update --init --recursive
.venv/bin/pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
ffmpeg -hide_banner -loglevel error -f lavfi -i 'sine=frequency=440:sample_rate=44100:duration=15' -c:a pcm_s16le /tmp/demucs-sample.wav
DEMUCS_DEVICE=cpu DEMUCS_CHUNK_SECONDS=2 .venv/bin/python - <<'PY'
from pathlib import Path
from backend.app.adapters.demucs import separate_audio

print(separate_audio(
    Path('/tmp/demucs-sample.wav'),
    Path('/tmp/demucs-sample-session'),
    lambda progress, message: print(progress, message),
))
PY

首次运行需要下载 htdemucs_ft 模型权重。验收时应确认输出帧数为 661,500、日志出现多个 part、/tmp/demucs-sample-session/tmp 无 Demucs 临时文件，media 中只保留两份 final 且没有 .pending.wav。

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3e4cd0f2c7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".