Initial lip-sync service with command backend

docs/backend-adapter-guide.md

@@ -0,0 +1,120 @@
+# 后端适配指南
+
+## 1. 后端必须满足的条件
+
+无论接入哪个模型，最终都要满足：
+
+- 输入：一个音频文件路径、一个视频文件路径。
+- 输出：一个 mp4 文件路径。
+- 失败：抛出异常或返回非零退出码，错误信息要能定位原因。
+
+## 2. `command` 后端接入方式
+
+`command` 后端是最推荐的第一步，因为它不要求立刻改 Python 代码。只要你的模型有命令行推理脚本，就可以接入。
+
+示例：
+
+```powershell
+$env:LIPSYNC_BACKEND = "command"
+$env:LIPSYNC_COMMAND_CWD = "D:\models\Wav2Lip"
+$env:LIPSYNC_COMMAND_TIMEOUT_SECONDS = "1800"
+$env:LIPSYNC_COMMAND_TEMPLATE = 'python inference.py --checkpoint_path D:\models\Wav2Lip\checkpoints\wav2lip_gan.pth --face {video_q} --audio {audio_q} --outfile {output_q}'
+.\scripts\start.ps1 -Backend command
+```
+
+模板变量：
+
+- `{audio}`：音频路径
+- `{video}`：视频路径
+- `{output}`：输出路径，模型必须写到这里
+- `{workdir}`：临时工作目录
+- `{cwd}`：命令执行目录，来自 `LIPSYNC_COMMAND_CWD`
+- `{audio_q}` / `{video_q}` / `{output_q}` / `{workdir_q}` / `{cwd_q}`：已按当前系统 shell 转义的路径，推荐在命令模板中使用
+
+## 3. Wav2Lip 接入提示
+
+适合快速验证，生态资料多。
+
+典型命令形态：
+
+```powershell
+python D:\models\Wav2Lip\inference.py `
+  --checkpoint_path D:\models\Wav2Lip\checkpoints\wav2lip_gan.pth `
+  --face {video_q} `
+  --audio {audio_q} `
+  --outfile {output_q}
+```
+
+注意点：
+
+- 原始 Wav2Lip 对高清视频和复杂脸部姿态效果有限。
+- 需要确认 ffmpeg 可用。
+- 输出路径必须是 `{output}`，否则服务会认为失败。
+- 如果模型脚本依赖相对路径资源，把 `LIPSYNC_COMMAND_CWD` 设为模型仓库根目录。
+- 真实推理耗时较长时，设置 `LIPSYNC_COMMAND_TIMEOUT_SECONDS`；`0` 表示不限时。
+
+## 3.1 命令后端失败诊断
+
+`command` 后端会检查：
+
+- 模板变量是否存在。
+- `LIPSYNC_COMMAND_CWD` 是否是有效目录。
+- 命令退出码是否为 0。
+- `{output}` 指向的 mp4 是否存在且非空。
+
+失败时会返回命令、退出码、耗时、stdout 尾部和 stderr 尾部。错误信息会隐藏常见 token、secret、password 字段，但不要把密钥写进命令模板；需要密钥时优先让模型脚本自己从环境变量读取。
+
+## 4. MuseTalk 接入提示
+
+效果通常比传统 Wav2Lip 更好，但环境更重。
+
+你需要先在模型仓库中跑通官方 demo，再把官方命令改造成模板。重点确认：
+
+- 是否支持直接传入任意视频。
+- 是否需要预处理 avatar。
+- 输出是否能指定到 `{output}`。
+- 是否需要长驻服务或预热。
+
+## 5. LstmSync 接入提示
+
+主项目已有 `resources/lstmsync` 配置，说明它是项目期望的本地数字人口型同步方案之一。可选路线：
+
+- 直接复用主项目 LstmSync 资源包作为独立服务后端。
+- 或把 LstmSync 封成命令行脚本，再通过 `command` 后端调用。
+
+需要确认：
+
+- 模型权重位置。
+- Python/CUDA/PyTorch 版本。
+- 输入参数名和输出路径参数。
+- 是否支持 `256m`、`256o`、`384m` 等权重选择。
+
+## 6. 新增专用后端建议
+
+当 `command` 后端跑通后，可以把逻辑固化成专用后端：
+
+```python
+class Backend:
+    name = "wav2lip"
+
+    def process(self, audio_path, video_path, output_path, settings):
+        ...
+        return output_path
+```
+
+专用后端需要补充：
+
+- 环境变量配置。
+- 模型路径检查。
+- 预热逻辑。
+- 明确的异常类型。
+- 最小单元测试。
+
+## 7. 常见失败原因
+
+- CUDA / PyTorch 版本不匹配。
+- ffmpeg 不在 PATH。
+- 视频里没有可检测的人脸。
+- 输入视频分辨率过高导致显存不足。
+- 模型脚本输出到了其它路径，没有写入 `{output}`。
+- Gradio 端口被占用。