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：模型选型建议。

接口兼容性

主项目调用方式等价于：

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",
)

期望返回：

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

快速启动

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

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

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

也可以直接运行模块：

uv run python -m digital_human_lipsync_service

接入 aIzhinengti

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

接入真实口型同步模型

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

$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、模型路径或人脸检测问题。

验证

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

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