LivePortrait/readme.md

LivePortrait: Efficient Portrait Animation with Stitching and Retargeting Control

Jianzhu Guo ^1†  Dingyun Zhang ^1,2  Xiaoqiang Liu ¹  Zhizhou Zhong ^1,3  Yuan Zhang ¹ 

Pengfei Wan ¹  Di Zhang ¹ 

¹ Kuaishou Technology  ² University of Science and Technology of China  ³ Fudan University 

^† Corresponding author

🔥 For more results, visit our homepage 🔥

🔥 Updates

• 2024/08/02: 😸 We released a version of the Animals model, along with several other updates and improvements. Check out the details here!
• 2024/07/25: 📦 Windows users can now download the package from HuggingFace or BaiduYun. Simply unzip and double-click run_windows.bat to enjoy!
• 2024/07/24: 🎨 We support pose editing for source portraits in the Gradio interface. We’ve also lowered the default detection threshold to increase recall. Have fun!
• 2024/07/19: ✨ We support 🎞️ portrait video editing (aka v2v)! More to see here.
• 2024/07/17: 🍎 We support macOS with Apple Silicon, modified from jeethu's PR #143.
• 2024/07/10: 💪 We support audio and video concatenating, driving video auto-cropping, and template making to protect privacy. More to see here.
• 2024/07/09: 🤗 We released the HuggingFace Space, thanks to the HF team and Gradio!
• 2024/07/04: 😊 We released the initial version of the inference code and models. Continuous updates, stay tuned!
• 2024/07/04: 🔥 We released the homepage and technical report on arXiv.

Introduction 📖

This repo, named LivePortrait, contains the official PyTorch implementation of our paper LivePortrait: Efficient Portrait Animation with Stitching and Retargeting Control. We are actively updating and improving this repository. If you find any bugs or have suggestions, welcome to raise issues or submit pull requests (PR) 💖.

Getting Started 🏁

1. Clone the code and prepare the environment 🛠️

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

# create env using conda
conda create -n LivePortrait python=3.9
conda activate LivePortrait

# for Linux and Windows users
pip install -r requirements.txt
# for macOS with Apple Silicon users
pip install -r requirements_macOS.txt

Note

Make sure your system has git, conda, and FFmpeg installed. For details on FFmpeg installation, see how to install FFmpeg.

2. Download pretrained weights 📥

The easiest way to download the pretrained weights is from HuggingFace:

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

If you cannot access to Huggingface, you can use hf-mirror to download:

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

Alternatively, you can download all pretrained weights from Google Drive or Baidu Yun (WIP). Unzip and place them in ./pretrained_weights.

Ensuring the directory structure is as or contains this.

3. Inference 🚀

Fast hands-on (humans) 👤

# For Linux and Windows users
python inference.py

# For macOS users with Apple Silicon (Intel is not tested). NOTE: this maybe 20x slower than RTX 4090
PYTORCH_ENABLE_MPS_FALLBACK=1 python inference.py

If the script runs successfully, you will get an output mp4 file named animations/s6--d0_concat.mp4. This file includes the following results: driving video, input image or video, and generated result.

Or, you can change the input by specifying the -s and -d arguments:

# source input is an image
python inference.py -s assets/examples/source/s9.jpg -d assets/examples/driving/d0.mp4

# source input is a video ✨
python inference.py -s assets/examples/source/s13.mp4 -d assets/examples/driving/d0.mp4

# more options to see
python inference.py -h

Fast hands-on (animals) 🐱🐶

Animals mode is ONLY tested on Linux with NVIDIA GPU.

You need to build an OP named MultiScaleDeformableAttention first, which is used by X-Pose, a general keypoint detection framework.

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

Then

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

If the script runs successfully, you will get an output mp4 file named animations/s39--wink_concat.mp4.

Driving video auto-cropping 📢📢📢

Important

To use your own driving video, we recommend: ⬇️

• Crop it to a 1:1 aspect ratio (e.g., 512x512 or 256x256 pixels), or enable auto-cropping by --flag_crop_driving_video.
• Focus on the head area, similar to the example videos.
• Minimize shoulder movement.
• Make sure the first frame of driving video is a frontal face with neutral expression.

Below is a auto-cropping case by --flag_crop_driving_video:

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

If you find the results of auto-cropping is not well, you can modify the --scale_crop_driving_video, --vy_ratio_crop_driving_video options to adjust the scale and offset, or do it manually.

Motion template making

You can also use the auto-generated motion template files ending with .pkl to speed up inference, and protect privacy, such as:

python inference.py -s assets/examples/source/s9.jpg -d assets/examples/driving/d5.pkl # portrait animation
python inference.py -s assets/examples/source/s13.mp4 -d assets/examples/driving/d5.pkl # portrait video editing

4. Gradio interface 🤗

We also provide a Gradio interface for a better experience, just run by:

# For Linux and Windows users (and macOS with Intel??)
python app.py # humans mode

# For macOS with Apple Silicon users, Intel not supported, this maybe 20x slower than RTX 4090
PYTORCH_ENABLE_MPS_FALLBACK=1 python app.py # humans mode

We also provide a Gradio interface of animals mode, which is only tested on Linux with NVIDIA GPU:

python app_animals.py # animals mode 🐱🐶

You can specify the --server_port, --share, --server_name arguments to satisfy your needs!

🚀 We also provide an acceleration option --flag_do_torch_compile. The first-time inference triggers an optimization process (about one minute), making subsequent inferences 20-30% faster. Performance gains may vary with different CUDA versions.

# enable torch.compile for faster inference
python app.py --flag_do_torch_compile

Note: This method is not supported on Windows and macOS.

Or, try it out effortlessly on HuggingFace 🤗

5. Inference speed evaluation 🚀🚀🚀

We have also provided a script to evaluate the inference speed of each module:

# For NVIDIA GPU
python speed.py

The results are here.

Community Resources 🤗

Discover the invaluable resources contributed by our community to enhance your LivePortrait experience:

• ComfyUI-LivePortraitKJ by @kijai
• comfyui-liveportrait by @shadowcz007
• LivePortrait In ComfyUI by @Benji
• LivePortrait hands-on tutorial by @AI Search
• ComfyUI tutorial by @Sebastian Kamph
• Replicate Playground and cog-comfyui by @fofr

And many more amazing contributions from our community!

Acknowledgements 💐

We would like to thank the contributors of FOMM, Open Facevid2vid, SPADE, InsightFace repositories, for their open research and contributions.

Citation 💖

If you find LivePortrait useful for your research, welcome to 🌟 this repo and cite our work using the following 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}
}

Contact 📧

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