Home

Awesome

About this fork

This fork was created to provide a convenient web interface for using Hallo. The original code has been slightly modified to allow for more control over the generation process.

About colab

⚠️ To run the web interface, you need at least 12 GB of video memory (VRAM) and more than 12 GB of RAM. ⚠️

Unfortunately, I was unable to create a free tier Colab notebook as there is not enough RAM available.

Portable version

But you can try if you have pro colab

If you have windows and you don't want to bother with installing libs, you can download the portable version , unpack and launch run.bat

Screenshot

image

Installation

Docker

docker compose up -d 

this will start the gradio web ui and expose the port 7680 which is mapped to 8020 to teh container's host The app will be available at http://localhost:8020

Note : Be sure to use the correct cuda start image for your GPU driver version, if it doesn't build from the start.

Windows

  1. Clone this repository:

    git clone https://github.com/yourusername/hallo.git
    
  2. Run install.bat to set up the environment and download the pretrained models.

  3. Make sure ffmpeg is installed on your system. It doesn't matter where it's located, as long as the system can find it.

  4. Launch the web interface by running start.bat.

Linux

  1. Clone this repository:

    git clone https://github.com/yourusername/hallo.git
    
  2. Run install.sh to set up the environment and download the pretrained models.

  3. Ensure ffmpeg is installed on your system. You can install it with:

    sudo apt-get install ffmpeg
    
  4. Launch the web interface by running start.sh.

Manual Installation

If you prefer to install manually, here are the detailed steps:

  1. Clone the repository and pretrained models:

    git lfs install
    git clone https://github.com/yourusername/hallo.git
    git clone https://huggingface.co/fudan-generative-ai/hallo pretrained_models
    curl -L -o pretrained_models/hallo/net.pth https://huggingface.co/fudan-generative-ai/hallo/resolve/main/hallo/net.pth?download=true
    
  2. Create a virtual environment and activate it:

    python -m venv venv
    venv\Scripts\activate  # For Windows
    source venv/bin/activate  # For Linux
    
  3. Install the required packages:

    pip install -r requirements.txt
    pip install -e .
    pip install bitsandbytes-windows --force-reinstall  # For Windows only
    
  4. Install GPU libraries:

    pip install torch==2.2.2+cu121 torchaudio torchvision --index-url https://download.pytorch.org/whl/cu121
    pip install onnxruntime-gpu
    
  5. Launch the web interface:

    python app.py
    
  6. To share , use --share flag

     python app.py --share
    
<h1 align='Center'>Hallo: Hierarchical Audio-Driven Visual Synthesis for Portrait Image Animation</h1> <div align='Center'> <a href='https://github.com/xumingw' target='_blank'>Mingwang Xu</a><sup>1*</sup>&emsp; <a href='https://github.com/crystallee-ai' target='_blank'>Hui Li</a><sup>1*</sup>&emsp; <a href='https://github.com/subazinga' target='_blank'>Qingkun Su</a><sup>1*</sup>&emsp; <a href='https://github.com/NinoNeumann' target='_blank'>Hanlin Shang</a><sup>1</sup>&emsp; <a href='https://github.com/AricGamma' target='_blank'>Liwei Zhang</a><sup>1</sup>&emsp; <a href='https://github.com/cnexah' target='_blank'>Ce Liu</a><sup>3</sup>&emsp; </div> <div align='center'> <a href='https://jingdongwang2017.github.io/' target='_blank'>Jingdong Wang</a><sup>2</sup>&emsp; <a href='https://yoyo000.github.io/' target='_blank'>Yao Yao</a><sup>4</sup>&emsp; <a href='https://sites.google.com/site/zhusiyucs/home' target='_blank'>Siyu Zhu</a><sup>1</sup>&emsp; </div> <div align='Center'> <sup>1</sup>Fudan University&emsp; <sup>2</sup>Baidu Inc&emsp; <sup>3</sup>ETH Zurich&emsp; <sup>4</sup>Nanjing University </div> <br> <div align='Center'> <a href='https://github.com/fudan-generative-vision/hallo'><img src='https://img.shields.io/github/stars/fudan-generative-vision/hallo?style=social'></a> <a href='https://fudan-generative-vision.github.io/hallo/#/'><img src='https://img.shields.io/badge/Project-HomePage-Green'></a> <a href='https://arxiv.org/pdf/2406.08801'><img src='https://img.shields.io/badge/Paper-Arxiv-red'></a> <a href='https://huggingface.co/fudan-generative-ai/hallo'><img src='https://img.shields.io/badge/%F0%9F%A4%97%20HuggingFace-Model-yellow'></a> <a href='assets/wechat.jpeg'><img src='https://badges.aleen42.com/src/wechat.svg'></a> </div> <br>

Showcase

https://github.com/fudan-generative-vision/hallo/assets/17402682/294e78ef-c60d-4c32-8e3c-7f8d6934c6bd

Framework

abstract framework

News

Installation

Create conda environment:

  conda create -n hallo python=3.10
  conda activate hallo

Install packages with pip

  pip install -r requirements.txt
  pip install .

Besides, ffmpeg is also need:

  apt-get install ffmpeg

Inference

The inference entrypoint script is scripts/inference.py. Before testing your cases, there are two preparations need to be completed:

  1. Download all required pretrained models.
  2. Prepare source image and driving audio pairs.
  3. Run inference.

Download pretrained models

You can easily get all pretrained models required by inference from our HuggingFace repo.

Clone the the pretrained models into ${PROJECT_ROOT}/pretrained_models directory by cmd below:

git lfs install
git clone https://huggingface.co/fudan-generative-ai/hallo pretrained_models

Or you can download them separately from their source repo:

Finally, these pretrained models should be organized as follows:

./pretrained_models/
|-- audio_separator/
|   `-- Kim_Vocal_2.onnx
|-- face_analysis/
|   `-- models/
|       |-- face_landmarker_v2_with_blendshapes.task  # face landmarker model from mediapipe
|       |-- 1k3d68.onnx
|       |-- 2d106det.onnx
|       |-- genderage.onnx
|       |-- glintr100.onnx
|       `-- scrfd_10g_bnkps.onnx
|-- motion_module/
|   `-- mm_sd_v15_v2.ckpt
|-- sd-vae-ft-mse/
|   |-- config.json
|   `-- diffusion_pytorch_model.safetensors
|-- stable-diffusion-v1-5/
|   |-- feature_extractor/
|   |   `-- preprocessor_config.json
|   |-- model_index.json
|   |-- unet/
|   |   |-- config.json
|   |   `-- diffusion_pytorch_model.safetensors
|   `-- v1-inference.yaml
`-- wav2vec/
    |-- wav2vec2-base-960h/
    |   |-- config.json
    |   |-- feature_extractor_config.json
    |   |-- model.safetensors
    |   |-- preprocessor_config.json
    |   |-- special_tokens_map.json
    |   |-- tokenizer_config.json
    |   `-- vocab.json

Prepare Inference Data

Hallo has a few simple requirements for input data:

For the source image:

  1. It should be cropped into squares.
  2. The face should be the main focus, making up 50%-70% of the image.
  3. The face should be facing forward, with a rotation angle of less than 30° (no side profiles).

For the driving audio:

  1. It must be in WAV format.
  2. It must be in English since our training datasets are only in this language.
  3. Ensure the vocals are clear; background music is acceptable.

We have provided some samples for your reference.

Run inference

Simply to run the scripts/inference.py and pass source_image and driving_audio as input:

python scripts/inference.py --source_image examples/source_images/1.jpg --driving_audio examples/driving_audios/1.wav

Animation results will be saved as ${PROJECT_ROOT}/.cache/output.mp4 by default. You can pass --output to specify the output file name. You can find more examples for inference at examples folder.

For more options:

usage: inference.py [-h] [-c CONFIG] [--source_image SOURCE_IMAGE] [--driving_audio DRIVING_AUDIO] [--output OUTPUT] [--pose_weight POSE_WEIGHT]
                    [--face_weight FACE_WEIGHT] [--lip_weight LIP_WEIGHT] [--face_expand_ratio FACE_EXPAND_RATIO]

options:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
  --source_image SOURCE_IMAGE
                        source image
  --driving_audio DRIVING_AUDIO
                        driving audio
  --output OUTPUT       output video file name
  --pose_weight POSE_WEIGHT
                        weight of pose
  --face_weight FACE_WEIGHT
                        weight of face
  --lip_weight LIP_WEIGHT
                        weight of lip
  --face_expand_ratio FACE_EXPAND_RATIO
                        face region

Roadmap

StatusMilestoneETA
Inference source code meet everyone on GitHub2024-06-15
Pretrained models on Huggingface2024-06-15
🚀🚀🚀Traning: data preparation and training scripts2024-06-25
🚀🚀🚀Optimize inference performance in MandarinTBD

Citation

If you find our work useful for your research, please consider citing the paper:

@misc{xu2024hallo,
  title={Hallo: Hierarchical Audio-Driven Visual Synthesis for Portrait Image Animation},
	author={Mingwang Xu and Hui Li and Qingkun Su and Hanlin Shang and Liwei Zhang and Ce Liu and Jingdong Wang and Yao Yao and Siyu zhu},
	year={2024},
	eprint={2406.08801},
	archivePrefix={arXiv},
	primaryClass={cs.CV}
}

Opportunities available

Multiple research positions are open at the Generative Vision Lab, Fudan University! Include:

Interested individuals are encouraged to contact us at siyuzhu@fudan.edu.cn for further information.

Social Risks and Mitigations

The development of portrait image animation technologies driven by audio inputs poses social risks, such as the ethical implications of creating realistic portraits that could be misused for deepfakes. To mitigate these risks, it is crucial to establish ethical guidelines and responsible use practices. Privacy and consent concerns also arise from using individuals' images and voices. Addressing these involves transparent data usage policies, informed consent, and safeguarding privacy rights. By addressing these risks and implementing mitigations, the research aims to ensure the responsible and ethical development of this technology.