Ditto：基于运动-空间扩散的可控实时说话头合成

📌 更新

• [2025.11.12] 🔥🔥 我们注意到社区对开源训练代码的热情。训练代码现已开放，由于版本较多且整理时间有限，可能与论文中的版本略有不同。
• [2025.07.11] 🔥 PyTorch模型现已可用。
• [2025.07.07] 🔥 Ditto已被ACM MM 2025接收。
• [2025.01.21] 🔥 我们更新了Colab演示，欢迎试用。
• [2025.01.10] 🔥 我们发布了推理代码和模型。
• [2024.11.29] 🔥 我们的论文已在arXiv上公开。

🔍 概述

这是推理分支。如需训练代码，请切换到train分支。

🛠️ 安装

测试环境

• 系统：Centos 7.2
• GPU：A100
• Python：3.10
• tensorRT：8.6.1

从Github克隆代码：

git clone https://github.com/antgroup/ditto-talkinghead
cd ditto-talkinghead

Conda

创建conda环境：

conda env create -f environment.yaml
conda activate ditto

Pip

如果在创建conda环境时遇到问题，也可以参考我们的Colab。正确安装pytorch、cuda和cudnn后，只需使用pip安装少量包：

pip install \
    tensorrt==8.6.1 \
    librosa \
    tqdm \
    filetype \
    imageio \
    opencv_python_headless \
    scikit-image \
    cython \
    cuda-python \
    imageio-ffmpeg \
    colored \
    polygraphy \
    numpy==2.0.1

如果不使用conda, 还需要根据官方网站安装ffmpeg。

📥 下载检查点

从HuggingFace下载检查点，并将其放入checkpoints目录：

git lfs install
git clone https://huggingface.co/digital-avatar/ditto-talkinghead checkpoints

checkpoints目录应如下所示：

./checkpoints/
├── ditto_cfg
│   ├── v0.4_hubert_cfg_trt.pkl
│   └── v0.4_hubert_cfg_trt_online.pkl
├── ditto_onnx
│   ├── appearance_extractor.onnx
│   ├── blaze_face.onnx
│   ├── decoder.onnx
│   ├── face_mesh.onnx
│   ├── hubert.onnx
│   ├── insightface_det.onnx
│   ├── landmark106.onnx
│   ├── landmark203.onnx
│   ├── libgrid_sample_3d_plugin.so
│   ├── lmdm_v0.4_hubert.onnx
│   ├── motion_extractor.onnx
│   ├── stitch_network.onnx
│   └── warp_network.onnx
└── ditto_trt_Ampere_Plus
    ├── appearance_extractor_fp16.engine
    ├── blaze_face_fp16.engine
    ├── decoder_fp16.engine
    ├── face_mesh_fp16.engine
    ├── hubert_fp32.engine
    ├── insightface_det_fp16.engine
    ├── landmark106_fp16.engine
    ├── landmark203_fp16.engine
    ├── lmdm_v0.4_hubert_fp32.engine
    ├── motion_extractor_fp32.engine
    ├── stitch_network_fp16.engine
    └── warp_network_fp16.engine

• ditto_cfg/v0.4_hubert_cfg_trt_online.pkl为在线配置
• ditto_cfg/v0.4_hubert_cfg_trt.pkl为离线配置

🚀 推理

运行inference.py：

python inference.py \
    --data_root "<path-to-trt-model>" \
    --cfg_pkl "<path-to-cfg-pkl>" \
    --audio_path "<path-to-input-audio>" \
    --source_path "<path-to-input-image>" \
    --output_path "<path-to-output-mp4>" 

例如：

python inference.py \
    --data_root "./checkpoints/ditto_trt_Ampere_Plus" \
    --cfg_pkl "./checkpoints/ditto_cfg/v0.4_hubert_cfg_trt.pkl" \
    --audio_path "./example/audio.wav" \
    --source_path "./example/image.png" \
    --output_path "./tmp/result.mp4" 

❗注意：

我们提供了硬件兼容性级别为Ampere_Plus的tensorRT模型（checkpoints/ditto_trt_Ampere_Plus/）。如果您的GPU不支持该型号，请执行cvt_onnx_to_trt.py脚本，将通用onnx模型（checkpoints/ditto_onnx/）转换为tensorRT模型。

python scripts/cvt_onnx_to_trt.py --onnx_dir "./checkpoints/ditto_onnx" --trt_dir "./checkpoints/ditto_trt_custom"

然后使用--data_root=./checkpoints/ditto_trt_custom运行inference.py。

⚡ PyTorch 模型

基於社區的興趣以及更好地支持後續開發，我們現已開放模型的 PyTorch 版本源碼。

我們已將 PyTorch 模型及相應的配置文件上傳至 HuggingFace。請參閱下載檢查點以準備模型文件。

checkpoints 目錄結構應如下所示：

./checkpoints/
├── ditto_cfg
│   ├── ...
│   └── v0.4_hubert_cfg_pytorch.pkl
├── ...
└── ditto_pytorch
    ├── aux_models
    │   ├── 2d106det.onnx
    │   ├── det_10g.onnx
    │   ├── face_landmarker.task
    │   ├── hubert_streaming_fix_kv.onnx
    │   └── landmark203.onnx
    └── models
        ├── appearance_extractor.pth
        ├── decoder.pth
        ├── lmdm_v0.4_hubert.pth
        ├── motion_extractor.pth
        ├── stitch_network.pth
        └── warp_network.pth

要運行推理，請執行以下命令：

python inference.py \
    --data_root "./checkpoints/ditto_pytorch" \
    --cfg_pkl "./checkpoints/ditto_cfg/v0.4_hubert_cfg_pytorch.pkl" \
    --audio_path "./example/audio.wav" \
    --source_path "./example/image.png" \
    --output_path "./tmp/result.mp4" 

📧 致謝

我們的實現基於 S2G-MDDiffusion 和 LivePortrait。感謝他們傑出的貢獻和公開的代碼！若我們遺漏了任何開源項目或相關文獻，將立即補充致謝。

⚖️ 授權條款

本倉庫根據 LICENSE 文件中的 Apache-2.0 許可證發布。

📚 引用

若您認為此代碼庫對您的研究有所幫助，請使用以下引用格式。

@article{li2024ditto,
    title={Ditto: Motion-Space Diffusion for Controllable Realtime Talking Head Synthesis},
    author={Li, Tianqi and Zheng, Ruobing and Yang, Minghui and Chen, Jingdong and Yang, Ming},
    journal={arXiv preprint arXiv:2411.19509},
    year={2024}
}

🌟 星標歷史

Ditto Talking Head 快速上手指南

Ditto 是一个基于运动空间扩散模型的可控实时数字人说话头合成工具，支持通过单张图片和音频生成逼真的说话视频。

环境准备

推荐配置

• 系统: Linux (测试环境为 Centos 7.2)
• GPU: NVIDIA A100 (或其他支持 TensorRT 的显卡)
• Python: 3.10
• TensorRT: 8.6.1
• CUDA/cuDNN: 需预先正确安装以匹配 PyTorch 版本

前置依赖

• 确保已安装 git 和 git-lfs (用于下载大模型文件)。
• 建议安装 ffmpeg (用于视频处理)。

安装步骤

1. 克隆代码库

git clone https://github.com/antgroup/ditto-talkinghead
cd ditto-talkinghead

2. 创建运行环境

方式一：使用 Conda (推荐)

conda env create -f environment.yaml
conda activate ditto

方式二：使用 Pip (若无 Conda) 在安装好 PyTorch、CUDA 和 cuDNN 后，执行以下命令安装依赖：

pip install \
    tensorrt==8.6.1 \
    librosa \
    tqdm \
    filetype \
    imageio \
    opencv_python_headless \
    scikit-image \
    cython \
    cuda-python \
    imageio-ffmpeg \
    colored \
    polygraphy \
    numpy==2.0.1

注意：如果不使用 Conda，请根据 ffmpeg 官网 手动安装 ffmpeg。

3. 下载模型权重

使用 git-lfs 从 HuggingFace 下载模型至 checkpoints 目录：

git lfs install
git clone https://huggingface.co/digital-avatar/ditto-talkinghead checkpoints

注：国内用户若访问 HuggingFace 困难，可尝试配置镜像源或使用代理。

基本使用

场景一：使用 TensorRT 加速推理 (推荐)

适用于拥有 Ampere 架构及以上 GPU (如 A100, RTX 30/40 系列) 的用户。

python inference.py \
    --data_root "./checkpoints/ditto_trt_Ampere_Plus" \
    --cfg_pkl "./checkpoints/ditto_cfg/v0.4_hubert_cfg_trt.pkl" \
    --audio_path "./example/audio.wav" \
    --source_path "./example/image.png" \
    --output_path "./tmp/result.mp4"

注意：如果您的显卡不支持预提供的 Ampere_Plus 模型，需先转换模型：

python scripts/cvt_onnx_to_trt.py --onnx_dir "./checkpoints/ditto_onnx" --trt_dir "./checkpoints/ditto_trt_custom"

然后运行推理时将 --data_root 改为 ./checkpoints/ditto_trt_custom。

场景二：使用 PyTorch 原生推理

适用于希望兼容性更好或进行二次开发的用户。

python inference.py \
    --data_root "./checkpoints/ditto_pytorch" \
    --cfg_pkl "./checkpoints/ditto_cfg/v0.4_hubert_cfg_pytorch.pkl" \
    --audio_path "./example/audio.wav" \
    --source_path "./example/image.png" \
    --output_path "./tmp/result.mp4"

参数说明：

• --data_root: 模型文件所在目录路径。
• --cfg_pkl: 配置文件路径 (.pkl)。
• --audio_path: 输入音频文件路径 (如 .wav)。
• --source_path: 参考人物图片路径 (如 .png)。
• --output_path: 输出视频文件保存路径 (如 .mp4)。