SyncTalk

环境要求

• Ubuntu 18.04（官方测试环境，另已添加 Windows 支持）
• CUDA 11.3 与对应的 NVIDIA 显卡驱动
• Anaconda/Miniconda（用于创建 conda 环境）
• Python 3.8.8、PyTorch 1.12.1+cu113
• 系统需可执行 sudo apt-get 安装 portaudio19-dev

安装与启动步骤

1. 1克隆项目仓库

   把 SyncTalk 官方仓库拉到本地并进入项目根目录，后续所有命令都在这层目录执行。

   git clone https://github.com/ZiqiaoPeng/SyncTalk.git
   cd SyncTalk

   复制

2. 2创建并激活环境

   用 conda 建一个 Python 3.8.8 的独立环境，避免与系统 Python 冲突。

   conda create -n synctalk python==3.8.8
   conda activate synctalk

   复制

3. 3安装 PyTorch

   按官方测试版本安装 torch / torchvision / torchaudio 的 cu113 版本，需匹配本机 CUDA。

   pip install torch==1.12.1+cu113 torchvision==0.13.1+cu113 torchaudio==0.12.1 --extra-index-url https://download.pytorch.org/whl/cu113

   复制

4. 4安装系统音频库

   安装 portaudio19-dev，供音频处理相关依赖编译使用，需要 sudo 权限。

   sudo apt-get install portaudio19-dev

   复制

5. 5安装 Python 依赖

   在项目根目录按 requirements.txt 安装其余 Python 包。

   pip install -r requirements.txt

   复制

6. 6安装 PyTorch3D

   使用官方预编译 wheel 安装 pytorch3d（对应 py38/cu113/torch1.12.1）。若失败可改用项目自带脚本安装。

   pip install --no-index --no-cache-dir pytorch3d -f https://dl.fbaipublicfiles.com/pytorch3d/packaging/wheels/py38_cu113_pyt1121/download.html

   复制

7. 7安装 TF 与扩展模块

   安装 tensorflow-gpu 2.8.1，并本地编译安装 freqencoder、shencoder、gridencoder、raymarching 四个 CUDA 扩展。

   pip install tensorflow-gpu==2.8.1
   pip install ./freqencoder
   pip install ./shencoder
   pip install ./gridencoder
   pip install ./raymarching

   复制

8. 8运行评估推理

   在仓库根目录执行评估脚本，加载预训练模型对 May 数据做测试；加 --portrait 可把生成人脸贴回原图提升质量。

   python main.py data/May --workspace model/trial_may -O --test --asr_model ave
   python main.py data/May --workspace model/trial_may -O --test --asr_model ave --portrait

   复制

关键配置

如何确认成功

命令正常跑完后会输出评估指标表格，含 PSNR、LPIPS、LMD；Portrait 模式应得到 PSNR 37.644、LPIPS 0.0117、LMD 2.825。

常见问题

注意事项

• 官方在 Ubuntu 18.04 + PyTorch 1.12.1 + CUDA 11.3 上测试通过，其他版本组合可能编译失败。
• 四个 CUDA 扩展（freqencoder、shencoder、gridencoder、raymarching）需在项目根目录下用 pip install ./xxx 本地编译。
• 代码与预训练模型已于 2024-03-04 发布，2024-04-28 补充了预处理代码。
• README 未给出具体的训练命令与参数，如需自定义数据集训练请查阅仓库内脚本与文档。