digital-human-lipsync-service/PROJECT_SPEC.md

项目规格：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 侧可以读取到：

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

5. 后端模式

ffmpeg_mux

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

command

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

$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。

真实成功：

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