# Digital Human Lip-Sync Service

这是给 `aIzhinengti` 数字人 `自主算力机` 模式使用的独立服务项目。它提供 Gradio `/process_single` 接口，输入一段音频和一段人物视频，输出生成后的视频。

> 当前项目不内置或下载大模型权重。默认 `ffmpeg_mux` 后端只用于验证接入链路：把音频封装进原视频，不做真实口型同步。真实效果需要接入 Wav2Lip、MuseTalk、LstmSync 等模型推理命令。

## 开发接力入口

如果你在新窗口继续开发，建议按这个顺序看：

1. `AGENTS.md`：给开发 agent 的项目规则。
2. `PROJECT_SPEC.md`：项目目标、接口契约、成功标准。
3. `TASKS.md`：分阶段任务清单。
4. `docs/backend-adapter-guide.md`：如何接真实口型同步模型。
5. `docs/aizhinengti-integration.md`：如何接回主项目。
6. `docs/testing-and-acceptance.md`：测试和验收标准。
7. `docs/model-selection.md`：模型选型建议。

## 接口兼容性

主项目调用方式等价于：

```python
from gradio_client import Client, handle_file

client = Client("http://127.0.0.1:7860/")
result = client.predict(
    audio_file=handle_file("C:/test/audio.wav"),
    video_file={"video": handle_file("C:/test/avatar.mp4")},
    api_name="/process_single",
)
```

期望返回：

```json
{"video": "生成后的视频文件路径", "subtitles": null}
```

## 快速启动

先安装 `uv`：https://docs.astral.sh/uv/getting-started/installation/

```powershell
cd D:\WYF-project\digital-human-lipsync-service
uv sync
.\scripts\start.ps1
```

启动后访问：`http://127.0.0.1:7860/`

也可以直接运行模块：

```powershell
uv run python -m digital_human_lipsync_service
```

## 接入 aIzhinengti

1. 打开数字人页面设置。
2. `数字人模型` 选择 `自主算力机`。
3. `数字人API地址` 填 `http://127.0.0.1:7860/` 或局域网 GPU 机器地址。
4. 如果不用 CompShare，只需手动启动本服务；服务器 ID 可先填一个占位值用于通过界面校验。

## 接入真实口型同步模型

设置 `command` 后端，让服务调用你自己的推理脚本：

```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}`：适合直接放进命令行的已转义路径，Windows 路径含空格时建议优先使用

`command` 后端会校验模型命令退出码、输出文件是否存在且非空。失败时错误信息会包含退出码、耗时、命令和 `stderr` 尾部，方便定位 CUDA、ffmpeg、模型路径或人脸检测问题。

## 验证

```powershell
.\scripts\test-client.ps1 -Audio C:\test\audio.wav -Video C:\test\avatar.mp4
```

如果返回里有 `video` 字段，主项目就基本能拿到生成结果。