LivePortrait：基于拼接与重定向控制的高效人像动画

🔥 更新

• 2025/06/01: 🌍 过去一年里，LivePortrait 已经🚀成为各大视频平台（如快手、抖音、剪映、微信视频号）以及众多初创公司和创作者广泛采用的高效人像动画解决方案。🎉
• 2025/01/01: 🐶 我们更新了动物模型的新版本，使用了更多数据，详情请见这里。
• 2024/10/18: ❗ 我们已更新 transformers 和 gradio 库的版本，以避免安全漏洞。详细信息请见此处。
• 2024/08/29: 📦 我们更新了 Windows 一键安装包，并支持自动更新，详情请见变更日志。
• 2024/08/19: 🖼️ 我们新增了图像驱动模式和区域控制功能。详情请见这里。
• 2024/08/06: 🎨 我们在 Gradio 界面中支持精确的人像编辑功能，灵感来源于 ComfyUI-AdvancedLivePortrait。详情请见这里。
• 2024/08/05: 📦 Windows 用户现在可以下载适用于人类模式和动物模式的一键安装包！详情请见这里。
• 2024/08/02: 😸 我们发布了动物模型版本，并伴随多项更新和改进。详情请见这里！
• 2024/07/25: 📦 Windows 用户现在可以从 HuggingFace 下载安装包。只需解压并双击 run_windows.bat 即可开始使用！
• 2024/07/24: 🎨 我们在 Gradio 界面中支持对源人像进行姿态编辑。同时，我们降低了默认检测阈值以提高召回率。尽情体验吧！
• 2024/07/19: ✨ 我们新增了🎥 **人像视频编辑（即 v2v）**功能！更多内容请见这里。
• 2024/07/17: 🍎 我们支持搭载 Apple Silicon 芯片的 macOS 系统，该实现基于 jeethu 的 PR #143 修改而成。
• 2024/07/10: 💪 我们新增了音视频拼接、视频自动裁剪以及模板制作等功能，以保护用户隐私。更多细节请见这里。
• 2024/07/09: 🤗 我们上线了 HuggingFace Space，感谢 HF 团队和 Gradio 的支持！
• 2024/07/04: 😊 我们发布了推理代码和模型的初始版本。后续将持续更新，敬请关注！
• 2024/07/04: 🔥 我们同时发布了项目主页以及在 arXiv 上的技术报告。

简介 📖

本仓库名为 LivePortrait，包含了我们论文《LivePortrait：基于拼接与重定向控制的高效人像动画》（https://arxiv.org/pdf/2407.03168）的官方 PyTorch 实现。 我们正在积极维护和改进此仓库。如果您发现任何问题或有改进建议，欢迎提出 issue 或提交 pull request (PR) 💖。

快速入门 🏁

1. 克隆代码并准备环境 🛠️

[!提示] 请确保您的系统已安装 git、conda 和 FFmpeg。有关 FFmpeg 的安装详情，请参阅 如何安装 FFmpeg。

git clone https://github.com/KlingTeam/LivePortrait
cd LivePortrait

# 使用 conda 创建环境
conda create -n LivePortrait python=3.10
conda activate LivePortrait

对于 Linux 🐧 或 Windows 🪟 用户

Animals 模式所需的依赖库 X-Pose 需要单独安装。如果您仅想运行 Humans 模式，则 检查 CUDA 版本 这一步骤是 可选 的。

nvcc -V # 示例版本：11.1、11.8、12.1 等。

# 对于 CUDA 11.1
pip install torch==1.10.1+cu111 torchvision==0.11.2 torchaudio==0.10.1 -f https://download.pytorch.org/whl/cu111/torch_stable.html
# 对于 CUDA 11.8
pip install torch==2.3.0 torchvision==0.18.0 torchaudio==2.3.0 --index-url https://download.pytorch.org/whl/cu118
# 对于 CUDA 12.1
pip install torch==2.3.0 torchvision==0.18.0 torchaudio==2.3.0 --index-url https://download.pytorch.org/whl/cu121
# ...

最后，安装剩余的依赖项：

pip install -r requirements.txt

对于搭载 Apple Silicon 的 macOS  用户

X-Pose 依赖库不支持 macOS，因此可以跳过其安装。Humans 模式仍可正常使用，但 Animals 模式则不受支持。请使用为搭载 Apple Silicon 的 macOS 准备的依赖文件：

# 对于搭载 Apple Silicon 的 macOS 用户
pip install -r requirements_macOS.txt

2. 下载预训练权重 📥

下载预训练权重最简单的方式是从 HuggingFace 获取：

# !pip install -U "huggingface_hub[cli]"
huggingface-cli download KlingTeam/LivePortrait --local-dir pretrained_weights --exclude "*.git*" "README.md" "docs"

如果您无法访问 HuggingFace，可以使用 hf-mirror 来下载：

# !pip install -U "huggingface_hub[cli]"
export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download KlingTeam/LivePortrait --local-dir pretrained_weights --exclude "*.git*" "README.md" "docs"

或者，您也可以从 Google Drive 或 Baidu Yun 下载所有预训练权重。解压后将其放入 ./pretrained_weights 目录中。

请确保目录结构与 此处 一致或包含该结构。

3. 推理 🚀

快速上手（人类） 👤

# 对于 Linux 和 Windows 用户
python inference.py

# 对于搭载 Apple Silicon 的 macOS 用户（尚未测试 Intel 版本）。注意：这可能比 RTX 4090 慢 20 倍
PYTORCH_ENABLE_MPS_FALLBACK=1 python inference.py

如果脚本成功运行，您将得到一个名为 animations/s6--d0_concat.mp4 的输出 MP4 文件。该文件包含驱动视频、输入图像或视频以及生成的结果。

您也可以通过指定 -s 和 -d 参数来更改输入：

# 输入源为一张图片
python inference.py -s assets/examples/source/s9.jpg -d assets/examples/driving/d0.mp4

# 输入源为一段视频 ✨
python inference.py -s assets/examples/source/s13.mp4 -d assets/examples/driving/d0.mp4

# 更多选项请查看
python inference.py -h

快速上手（动物） 🐱🐶

Animals 模式仅在配备 NVIDIA 显卡的 Linux 和 Windows 系统上经过测试。

您需要先构建一个名为 MultiScaleDeformableAttention 的 OP（如有需要，请参考 检查 CUDA 版本），该 OP 由通用关键点检测框架 X-Pose 使用。

cd src/utils/dependencies/XPose/models/UniPose/ops
python setup.py build install
cd - # 等同于 cd ../../../../../../../

然后：

python inference_animals.py -s assets/examples/source/s39.jpg -d assets/examples/driving/wink.pkl --driving_multiplier 1.75 --no_flag_stitching

如果脚本成功运行，您将得到一个名为 animations/s39--wink_concat.mp4 的输出 MP4 文件。

自动裁剪驱动视频 📢📢📢

[!重要提示] 如果您想使用自己的驱动视频，我们 建议：⬇️

• 将其裁剪为 1:1 的宽高比例（例如 512x512 或 256x256 像素），或启用自动裁剪功能 --flag_crop_driving_video。
• 聚焦于头部区域，类似于示例视频。
• 尽量减少肩膀的移动。
• 确保驱动视频的第一帧是正面人脸，且表情 中性。

以下是使用 --flag_crop_driving_video 进行自动裁剪的示例：

python inference.py -s assets/examples/source/s9.jpg -d assets/examples/driving/d13.mp4 --flag_crop_driving_video

如果您发现自动裁剪的效果不够理想，可以调整 --scale_crop_driving_video 和 --vy_ratio_crop_driving_video 参数来改变裁剪的比例和偏移量，或者手动进行裁剪。

制作运动模板

您还可以使用自动生成的以 .pkl 结尾的运动模板文件来加速推理，并 保护隐私，例如：

python inference.py -s assets/examples/source/s9.jpg -d assets/examples/driving/d5.pkl # 人像动画
python inference.py -s assets/examples/source/s13.mp4 -d assets/examples/driving/d5.pkl # 人像视频编辑

4. Gradio 界面 🤗

我们还提供了一个基于 Gradio 的界面，以提升用户体验。只需运行以下命令即可启动：

# 对于 Linux 和 Windows 用户（以及搭载 Intel 的 macOS??）
python app.py # humans 模式

# 对于使用 Apple Silicon 的 macOS 用户，不支持 Intel 芯片，这可能会比 RTX 4090 慢 20 倍
PYTORCH_ENABLE_MPS_FALLBACK=1 python app.py # 人类模式

我们还提供了动物模式的 Gradio 界面，该界面仅在配备 NVIDIA 显卡的 Linux 系统上进行了测试：

python app_animals.py # 动物模式 🐱🐶

您可以指定 --server_port、--share 和 --server_name 参数来满足您的需求！

🚀 我们还提供了一个加速选项 --flag_do_torch_compile。首次推理会触发优化过程（大约一分钟），从而使后续推理速度提升 20% 到 30%。性能提升效果可能因不同的 CUDA 版本而异。

# 启用 torch.compile 以加快推理速度
python app.py --flag_do_torch_compile

注意：此方法不适用于 Windows 和 macOS。

或者，您也可以在 HuggingFace 上轻松体验 🤗

5. 推理速度评估 🚀🚀🚀

我们还提供了一个脚本来评估每个模块的推理速度：

# 适用于 NVIDIA 显卡
python speed.py

结果请见 这里。

社区资源 🤗

探索由社区贡献的宝贵资源，以提升您的 LivePortrait 使用体验。

社区开发的项目

试用平台、HuggingFace Spaces 及其他

• FacePoke Space
• Expression Editor Space
• Expression Editor Replicate
• Face Control 实时演示 在 FAL 上
• Replicate Playground
• Nuke 可以通过 CompyUI 节点使用 LivePortrait，详情请见 这里
• LivePortrait 也在 Poe 上运行。

视频教程

• LivePortrait 视频转视频工作流程 由 @curiousrefuge 制作
• Google Colab 教程 由 @Planet Ai 制作
• 论文解读 由 @TwoMinutePapers 制作
• ComfyUI Advanced LivePortrait 由 TutoView 制作
• LivePortarit 探索 和 深入 LivePortrait 由 TheoreticallyMedia 制作
• LivePortrait 实操教程 由 @AI Search 制作
• ComfyUI 教程 由 @Sebastian Kamph 制作
• BiliBili 上的教程

此外，我们的社区还有许多令人惊叹的贡献，多到无法一一列举 💖

致谢 💐

我们衷心感谢 FOMM、Open Facevid2vid、SPADE、InsightFace 和 X-Pose 项目的贡献者们，感谢他们开放的研究成果和无私的贡献。

伦理考量 🛡️

肖像动画技术伴随着社会风险，尤其是可能被滥用于制作深度伪造内容。为降低这些风险，遵循伦理准则并采取负责任的使用方式至关重要。目前，合成结果中存在一些视觉伪影，有助于识别深度伪造。请注意，我们不对使用本项目生成的结果承担任何法律责任。

引用 💖

如果您发现 LivePortrait 对您的项目或研究有所帮助，请为本仓库点赞并使用以下 BibTeX 格式引用我们的工作：

@article{guo2024liveportrait,
  title   = {LivePortrait: Efficient Portrait Animation with Stitching and Retargeting Control},
  author  = {Guo, Jianzhu and Zhang, Dingyun and Liu, Xiaoqiang and Zhong, Zhizhou and Zhang, Yuan and Wan, Pengfei and Zhang, Di},
  journal = {arXiv preprint arXiv:2407.03168},
  year    = {2024}
}

愿它在 arXiv 上长存。

联系方式 📧

郭建珠 (Jianzhu Guo); guojianzhu1994@gmail.com

星星历史 🌟

LivePortrait 快速上手指南

LivePortrait 是一个高效的人像动画生成工具，支持通过驱动视频让人物或动物照片“动起来”，具备拼接（Stitching）和重定向（Retargeting）控制功能。

1. 环境准备

系统要求

• 操作系统: Linux, Windows, 或 macOS (Apple Silicon)
• Python: 3.10
• GPU: 推荐使用 NVIDIA GPU（Animals 模式必需）。macOS 仅支持 Humans 模式。
• 前置依赖:
  • git
  • conda
  • FFmpeg (用于视频处理，安装教程)

注意事项

• Windows 用户: 若遇到高版本 CUDA (如 12.4+) 导致的未知问题，建议降级至 CUDA 11.8 以保证稳定性。
• Animals 模式: 仅支持 Linux 和 Windows (NVIDIA GPU)，需要编译 X-Pose 依赖。macOS 不支持此模式。

2. 安装步骤

第一步：克隆代码并创建环境

git clone https://github.com/KlingTeam/LivePortrait
cd LivePortrait

# 创建 conda 环境
conda create -n LivePortrait python=3.10
conda activate LivePortrait

第二步：安装依赖库

Linux / Windows 用户

如果需要运行 Animals 模式，请先检查并安装对应 CUDA 版本的 PyTorch（可选，仅当默认安装不兼容时）：

nvcc -V # 查看当前 CUDA 版本
# 示例：CUDA 11.8
pip install torch==2.3.0 torchvision==0.18.0 torchaudio==2.3.0 --index-url https://download.pytorch.org/whl/cu118

安装核心依赖：

pip install -r requirements.txt

Animals 模式额外步骤：需编译 MultiScaleDeformableAttention 算子。

cd src/utils/dependencies/XPose/models/UniPose/ops
python setup.py build install
cd -

macOS (Apple Silicon) 用户

macOS 不支持 Animals 模式，请使用专用依赖文件：

pip install -r requirements_macOS.txt

第三步：下载预训练模型

推荐方式：使用国内镜像源加速下载。

# 安装 huggingface_hub (如果未安装)
pip install -U "huggingface_hub[cli]"

# 设置国内镜像地址
export HF_ENDPOINT=https://hf-mirror.com

# 下载模型到 pretrained_weights 目录
huggingface-cli download KlingTeam/LivePortrait --local-dir pretrained_weights --exclude "*.git*" "README.md" "docs"

备选方案：若上述失败，可手动从 百度网盘 下载，解压后放入 ./pretrained_weights 目录。

3. 基本使用

快速体验 (Humans 模式)

运行默认示例，生成包含驱动视频、输入图和结果的视频文件 (animations/s6--d0_concat.mp4)。

Linux / Windows:

python inference.py

macOS (Apple Silicon):

PYTORCH_ENABLE_MPS_FALLBACK=1 python inference.py

自定义输入

指定源图片/视频 (-s) 和驱动视频 (-d)：

# 源输入为图片
python inference.py -s assets/examples/source/s9.jpg -d assets/examples/driving/d0.mp4

# 源输入为视频
python inference.py -s assets/examples/source/s13.mp4 -d assets/examples/driving/d0.mp4

# 查看更多参数选项
python inference.py -h

快速体验 (Animals 模式)

仅限 Linux/Windows + NVIDIA GPU

python inference_animals.py -s assets/examples/source/s39.jpg -d assets/examples/driving/wink.pkl --driving_multiplier 1.75 --no_flag_stitching