Initial lip-sync service with command backend

2026-06-20 17:16:11 +08:00
commit 8c6a222c38
25 changed files with 1226 additions and 0 deletions
@@ -0,0 +1,99 @@
+# 项目规格：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`。
+
+真实成功：
+
+- 接入真实模型后，输出视频口型与音频同步。
+- 同一输入重复运行稳定生成结果。
+- 错误时返回明确原因，不让主项目卡死。