RedbeardNZ/HunyuanVideo-Avatar
0
1---2pipeline_tag: image-to-video3language:4- en5---6<!-- ## **HunyuanVideo-Avatar** -->7 8<p align="center">9 <img src="https://cdn-uploads.huggingface.co/production/uploads/646d7592bb95b5d4001e5a04/HDZpvr8F-UaHAHlsF--fh.png" height=100>10</p>11 12<div align="center">13 <a href="https://github.com/Tencent-Hunyuan/HunyuanVideo-Avatar"><img src="https://img.shields.io/static/v1?label=HunyuanVideo-Avatar%20Code&message=Github&color=blue"></a>14 <a href="https://HunyuanVideo-Avatar.github.io/"><img src="https://img.shields.io/static/v1?label=Project%20Page&message=Web&color=green"></a>15 <a href="https://hunyuan.tencent.com/modelSquare/home/play?modelId=126"><img src="https://img.shields.io/static/v1?label=Playground&message=Web&color=green"></a>16 <a href="https://arxiv.org/pdf/2505.20156"><img src="https://img.shields.io/static/v1?label=Tech Report&message=Arxiv&color=red"></a>17 <a href="https://huggingface.co/tencent/HunyuanVideo-Avatar"><img src="https://img.shields.io/static/v1?label=HunyuanVideo-Avatar&message=HuggingFace&color=yellow"></a>18</div>19 20 21 2223 24> [**HunyuanVideo-Avatar: High-Fidelity Audio-Driven Human Animation for Multiple Characters**](https://arxiv.org/pdf/2505.20156) <be>25 26## **Abstract**27 28Recent years have witnessed significant progress in audio-driven human animation. However, critical challenges remain in (i) generating highly dynamic videos while preserving character consistency, (ii) achieving precise emotion alignment between characters and audio, and (iii) enabling multi-character audio-driven animation. To address these challenges, we propose HunyuanVideo-Avatar, a multimodal diffusion transformer (MM-DiT)-based model capable of simultaneously generating dynamic, emotion-controllable, and multi-character dialogue videos. Concretely, HunyuanVideo-Avatar introduces three key innovations: (i) A character image injection module is designed to replace the conventional addition-based character conditioning scheme, eliminating the inherent condition mismatch between training and inference. This ensures the dynamic motion and strong character consistency; (ii) An Audio Emotion Module (AEM) is introduced to extract and transfer the emotional cues from an emotion reference image to the target generated video, enabling fine-grained and accurate emotion style control; (iii) A Face-Aware Audio Adapter (FAA) is proposed to isolate the audio-driven character with latent-level face mask, enabling independent audio injection via cross-attention for multi-character scenarios. These innovations empower HunyuanVideo-Avatar to surpass state-of-the-art methods on benchmark datasets and a newly proposed wild dataset, generating realistic avatars in dynamic, immersive scenarios. The source code and model weights will be released publicly.29 30## **HunyuanVideo-Avatar Overall Architecture**31 3233 34We propose **HunyuanVideo-Avatar**, a multi-modal diffusion transformer(MM-DiT)-based model capable of generating **dynamic**, **emotion-controllable**, and **multi-character dialogue** videos.35 36## 🎉 **HunyuanVideo-Avatar Key Features**37 3839 40### **High-Dynamic and Emotion-Controllable Video Generation**41 42HunyuanVideo-Avatar supports animating any input **avatar images** to **high-dynamic** and **emotion-controllable** videos with simple **audio conditions**. Specifically, it takes as input **multi-style** avatar images at **arbitrary scales and resolutions**. The system supports multi-style avatars encompassing photorealistic, cartoon, 3D-rendered, and anthropomorphic characters. Multi-scale generation spanning portrait, upper-body and full-body. It generates videos with high-dynamic foreground and background, achieving superior realistic and naturalness. In addition, the system supports controlling facial emotions of the characters conditioned on input audio. 43 44### **Various Applications**45 46HunyuanVideo-Avatar supports various downstream tasks and applications. For instance, the system generates talking avatar videos, which could be applied to e-commerce, online streaming, social media video production, etc. In addition, its multi-character animation feature enlarges the application such as video content creation, editing, etc. 47 48## 🚀 Parallel Inference on Multiple GPUs49 50For example, to generate a video with 8 GPUs, you can use the following command:51 52```bash53cd HunyuanVideo-Avatar54 55JOBS_DIR=$(dirname $(dirname "$0"))56export PYTHONPATH=./57export MODEL_BASE="./weights"58checkpoint_path=${MODEL_BASE}/ckpts/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt59 60torchrun --nnodes=1 --nproc_per_node=8 --master_port 29605 hymm_sp/sample_batch.py \61 --input 'assets/test.csv' \62 --ckpt ${checkpoint_path} \63 --sample-n-frames 129 \64 --seed 128 \65 --image-size 704 \66 --cfg-scale 7.5 \67 --infer-steps 50 \68 --use-deepcache 1 \69 --flow-shift-eval-video 5.0 \70 --save-path ${OUTPUT_BASEPATH} 71```72 73## 🔑 Single-gpu Inference74 75For example, to generate a video with 1 GPU, you can use the following command:76 77```bash78cd HunyuanVideo-Avatar79 80JOBS_DIR=$(dirname $(dirname "$0"))81export PYTHONPATH=./82 83export MODEL_BASE=./weights84OUTPUT_BASEPATH=./results-single85checkpoint_path=${MODEL_BASE}/ckpts/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states_fp8.pt86 87export DISABLE_SP=1 88CUDA_VISIBLE_DEVICES=0 python3 hymm_sp/sample_gpu_poor.py \89 --input 'assets/test.csv' \90 --ckpt ${checkpoint_path} \91 --sample-n-frames 129 \92 --seed 128 \93 --image-size 704 \94 --cfg-scale 7.5 \95 --infer-steps 50 \96 --use-deepcache 1 \97 --flow-shift-eval-video 5.0 \98 --save-path ${OUTPUT_BASEPATH} \99 --use-fp8 \100 --infer-min101```102 103### Run with very low VRAM104 105```bash106cd HunyuanVideo-Avatar107 108JOBS_DIR=$(dirname $(dirname "$0"))109export PYTHONPATH=./110 111export MODEL_BASE=./weights112OUTPUT_BASEPATH=./results-poor113 114checkpoint_path=${MODEL_BASE}/ckpts/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states_fp8.pt115 116export CPU_OFFLOAD=1117CUDA_VISIBLE_DEVICES=0 python3 hymm_sp/sample_gpu_poor.py \118 --input 'assets/test.csv' \119 --ckpt ${checkpoint_path} \120 --sample-n-frames 129 \121 --seed 128 \122 --image-size 704 \123 --cfg-scale 7.5 \124 --infer-steps 50 \125 --use-deepcache 1 \126 --flow-shift-eval-video 5.0 \127 --save-path ${OUTPUT_BASEPATH} \128 --use-fp8 \129 --cpu-offload \130 --infer-min131```132 133 134## Run a Gradio Server135```bash136cd HunyuanVideo-Avatar137 138bash ./scripts/run_gradio.sh139 140```141 142## 🔗 BibTeX143 144If you find [HunyuanVideo-Avatar](https://arxiv.org/pdf/2505.20156) useful for your research and applications, please cite using this BibTeX:145 146```BibTeX147@misc{hu2025HunyuanVideo-Avatar,148 title={HunyuanVideo-Avatar: High-Fidelity Audio-Driven Human Animation for Multiple Characters}, 149 author={Yi Chen and Sen Liang and Zixiang Zhou and Ziyao Huang and Yifeng Ma and Junshu Tang and Qin Lin and Yuan Zhou and Qinglin Lu},150 year={2025},151 eprint={2505.20156},152 archivePrefix={arXiv},153 primaryClass={cs.CV},154 url={https://arxiv.org/pdf/2505.20156}, 155}156```157 158## Acknowledgements159 160We would like to thank the contributors to the [HunyuanVideo](https://github.com/Tencent/HunyuanVideo), [SD3](https://huggingface.co/stabilityai/stable-diffusion-3-medium), [FLUX](https://github.com/black-forest-labs/flux), [Llama](https://github.com/meta-llama/llama), [LLaVA](https://github.com/haotian-liu/LLaVA), [Xtuner](https://github.com/InternLM/xtuner), [diffusers](https://github.com/huggingface/diffusers) and [HuggingFace](https://huggingface.co) repositories, for their open research and exploration.