# 项目规格：Digital Human Lip-Sync Service

## 1. 背景

`aIzhinengti` 的数字人 `自主算力机` 模式并不是大语言模型调用。它会把：

- 一段音频文件
- 一段数字人/真人形象视频

提交给一个 Gradio 服务，通过 `/process_single` 生成口型同步后的视频。

本项目就是这个服务的独立实现与适配层。

## 2. 目标

实现一个本地或远程可部署的音频驱动视频口型同步服务，满足：

- 可被 `gradio_client.Client(api_url).predict(..., api_name="/process_single")` 调用。
- 可先用 `ffmpeg_mux` 验证链路。
- 可通过 `command` 后端接入真实模型。
- 未来可扩展为专用 Python 后端，例如 `wav2lip`、`musetalk`、`lstmsync`。

## 3. 非目标

- 本项目不内置模型权重。
- 本项目不负责训练模型。
- 本项目不负责 CompShare 云主机启停 API。
- 本项目不负责文本生成、TTS、ASR、字幕排版等上游/下游能力。

## 4. 输入输出契约

### 输入

- `audio_file`：音频文件路径，常见格式 `wav`、`mp3`、`m4a`。
- `video_file`：视频文件或 Gradio 视频对象，常见格式 `mp4`、`mov`。

### 输出

输出一个可被 Gradio `Video` 组件处理的视频结果。主项目期望 Gradio client 侧可以读取到：

```json
{
  "video": "D:/path/to/output.mp4",
  "subtitles": null
}
```

## 5. 后端模式

### `ffmpeg_mux`

当前默认模式。只把上传音频封装到原视频中，用于验证主项目到服务的调用链路，不做真实口型同步。

### `command`

核心开发目标。用命令模板调用外部真实模型推理脚本：

```powershell
$env:LIPSYNC_BACKEND = "command"
$env:LIPSYNC_COMMAND_TEMPLATE = 'python D:\models\Wav2Lip\inference.py --checkpoint_path D:\models\Wav2Lip\checkpoints\wav2lip_gan.pth --face "{video}" --audio "{audio}" --outfile "{output}"'
```

可用变量：

- `{audio}`：服务收到并规范化后的音频路径
- `{video}`：服务收到并规范化后的视频路径
- `{output}`：模型必须写入的输出 mp4 路径
- `{workdir}`：临时工作目录

### 专用后端

后续可以新增：

- `wav2lip`
- `musetalk`
- `lstmsync`

专用后端应复用统一输入输出契约。

## 6. 部署约束

- Windows 优先。
- NVIDIA GPU 场景优先。
- 服务端口默认 `7860`。
- 局域网访问时使用 `LIPSYNC_HOST=0.0.0.0`。
- 公网暴露时必须自行增加访问控制、反向代理或防火墙限制。

## 7. 成功定义

最小成功：

- `scripts/test-client.ps1` 能调用服务，返回可播放视频。
- `aIzhinengti/scripts/digital_human_process.py` 能调用服务，返回 `success: true`。

真实成功：

- 接入真实模型后，输出视频口型与音频同步。
- 同一输入重复运行稳定生成结果。
- 错误时返回明确原因，不让主项目卡死。