LivePortrait: Efficient Portrait Animation with Stitching and Retargeting Control

郭建珠 ^1†  张丁芸 ^1,2  刘晓强 ¹  钟智舟 ^1,3  张渊 ¹  万鹏飞 ¹  张迪 ¹ 

¹ 快手科技  ² 中国科学技术大学  ³ 复旦大学 

^* Equal contributions ^† Project lead

<a href="https://huggingface.co/cleardusk/LivePortrait-Windows/blob/main/LivePortrait-Windows-v20240829.zip" target="_blank"><img src="https://img.shields.io/badge/🖥 Windows 一键安装-v20240829-00BFFF?style=for-the-badge&logo=windows&logoColor=white" alt="Windows 一键安装包"></a>&nbsp;
<a href="https://huggingface.co/spaces/KlingTeam/LivePortrait" target="_blank"><img src="https://img.shields.io/badge/🌐 在线体验-FF6F00?style=for-the-badge&logo=huggingface&logoColor=white" alt="HuggingFace 在线体验"></a>








<a href="https://arxiv.org/pdf/2407.03168" target="_blank"><img src="https://img.shields.io/badge/arXiv-LivePortrait-red" alt="arXiv link"></a>&nbsp;
<a href="https://liveportrait.github.io" target="_blank"><img src="https://img.shields.io/badge/Project-Homepage-green" alt="project homepage"></a>&nbsp;
<a href="https://huggingface.co/spaces/KlingTeam/LivePortrait" target="_blank"><img src="https://img.shields.io/badge/🤗 Hugging Face-Spaces-blue" alt="HF space"></a>&nbsp;
<a href="https://hellogithub.com/repository/bed652ef02154dd7a434e0720125639e" target="_blank"><img src="https://abroad.hellogithub.com/v1/widgets/recommend.svg?rid=bed652ef02154dd7a434e0720125639e&claim_uid=XyBT2K9QJ7RZhej&theme=small" alt="Featured by HelloGitHub"></a>&nbsp;
<a href="https://github.com/KlingTeam/LivePortrait" target="_blank"><img src="https://img.shields.io/github/stars/KlingTeam/LivePortrait?style=social" alt="GitHub stars"></a>

English | 简体中文

🔥 更多效果，请访问我们的 主页 🔥

🔥 更新日志

• 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：✨ 我们支持🎞️ 人像视频编辑（aka v2v）！更多信息见这里。
• 2024/07/17：🍎 我们支持macOS搭载Apple Silicon，修改来自 jeethu 的PR #143 。
• 2024/07/10：💪我们支持音频和视频拼接、驱动视频自动裁剪以及制作模板以保护隐私。更多信息见这里。
• 2024/07/09：🤗 我们发布了HuggingFace Space，感谢HF团队和Gradio！
• 2024/07/04：😊 我们发布了初始版本的推理代码和模型。持续更新，敬请关注！
• 2024/07/04：🔥 我们发布了主页和在arXiv上的技术报告。

介绍 📖

此仓库名为LivePortrait，包含我们论文（LivePortrait: Efficient Portrait Animation with Stitching and Retargeting Control）的官方PyTorch实现。 我们正在积极更新和改进此仓库。如果您发现任何错误或有建议，欢迎提出问题或提交合并请求💖。

上手指南 🏁

1. 克隆代码和安装运行环境 🛠️

[!Note] 确保您的系统已安装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用户

X-Pose需要您的torch版本与CUDA版本兼容。

首先，通过以下命令检查您当前的CUDA版本：

nvcc -V # example versions: 11.1, 11.8, 12.1, etc.

然后，安装相应版本的torch。以下是不同CUDA版本的示例。如果您的CUDA版本未列出，请访问PyTorch官方网站获取安装命令：

# for 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
# for 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
# for 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
# ...

注意：在Windows系统上，一些过高版本的CUDA(12.4、12.6等)可能会导致未知的问题，您可以考虑降低您的CUDA版本到11.8，这是我们测试的一个较为稳定的版本。降级方法可以参考 @dimitribarbot 提供的文档.

最后，安装其余依赖项：

pip install -r requirements.txt

对于搭载Apple Silicon的macOS用户

X-Pose依赖项不支持macOS，因此您可以跳过其安装。人类模式照常工作，但不支持动物模式。使用为搭载Apple Silicon的macOS提供的requirements文件：

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

2. 下载预训练权重(Pretrained weights) 📥

从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或百度云（进行中）下载所有预训练权重。解压并将它们放置在./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

快速上手（动物模型） 🐱🐶

动物模式仅在Linux和Windows上经过测试，并且需要NVIDIA GPU。

您需要首先构建一个名为MultiScaleDeformableAttention的OP，该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文件。

驱动视频自动裁剪 📢📢📢

[!IMPORTANT] 使用您自己的驱动视频时，我们推荐： ⬇️

• 将其裁剪为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 # 人类模型模式

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

我们还为动物模式提供了Gradio界面，这仅在Linux上经过NVIDIA GPU测试：

python app_animals.py # animals mode 🐱🐶

您可以指定--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 GPU
python speed.py

结果在本仓库该文件展示.

社区资源 🤗

社区项目

仓库	描述	作者 / 链接
AVTR-1	实时对话式 talking-head 模型，支持双路音频输入，并采用 LivePortrait-style portrait-warping 渲染器。	@avaturn-live
ditto-talkinghead	实时音频驱动。	论文, 主页
FasterLivePortrait	基于TensorRT加速更快的实时版本。	@warmshao
AdvancedLivePortrait-WebUI	Dedicated gradio based WebUI started from ComfyUI-AdvancedLivePortrait	@jhj0517
FacePoke	一个实时的头部姿态表情控制应用，通过鼠标控制！	@jbilcke-hf
FaceFusion	FaceFusion 3.0 集成了 LivePortrait 作为 expression_restorer 和 face_editor 处理器。	@henryruhs
sd-webui-live-portrait	LivePortrait 的 WebUI 扩展，在原版 Stable Diffusion WebUI 中添加了一个标签以使用 LivePortrait 的功能。	@dimitribarbot
ComfyUI-LivePortraitKJ	一个用于 LivePortrait 的 ComfyUI 节点，使用 MediaPipe 作为 Insightface 的替代方案。	@kijai
ComfyUI-AdvancedLivePortrait	一个更快的 ComfyUI 节点，具有实时预览功能，启发了许多社区开发的工具和项目。	@PowerHouseMan
comfyui-liveportrait	一个用于 LivePortrait 的 ComfyUI 节点，支持多面部、表情插值等功能，并有教程。	@shadowcz007

Playgrounds, 🤗 HuggingFace Spaces 以及其它

• FacePoke Space
• Expression Editor Space
• Expression Editor Replicate
• Face Control Realtime Demo on FAL
• Replicate Playground
• Nuke 可以通过 CompyUI 节点使用 LivePortrait，详情见这里
• LivePortrait 在 Poe 上运行

视频教程

• LivePortrait 视频转视频的工作流程 由 @curiousrefuge 制作
• Google Colab 教程 由 @Planet Ai 制作
• 论文解读 由 @TwoMinutePapers 制作
• [ComfyUI 高级 LivePortrait 教程](https://you