Initial lip-sync service with command backend

README.md

@@ -0,0 +1,94 @@
+# 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` 字段，主项目就基本能拿到生成结果。