# 后端适配指南

## 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 端口被占用。