{"name":"HunyuanVideo-Avatar: High-Fidelity Audio-Driven Human Animation","description":"HunyuanVideo-Avatar is a cutting-edge project by Tencent-Hunyuan for high-fidelity, audio-driven human animation. Utilizing a multimodal diffusion transformer, it generates dynamic, emotion-controllable, and multi-character dialogue videos. This innovative system addresses critical challenges in character consistency, emotion alignment, and multi-character animation, making it suitable for diverse applications like e-commerce and social media.","github":"https://github.com/Tencent-Hunyuan/HunyuanVideo-Avatar","url":"https://osrepos.com/repo/tencent-hunyuan-hunyuanvideo-avatar","source":"osrepos.com","sourceDescription":"This repository profile is provided by osrepos.com, an open source repository discovery platform.","repositoryProfile":"https://osrepos.com/repo/tencent-hunyuan-hunyuanvideo-avatar","generatedFor":"open source discovery and AI-assisted research","markdown":"https://osrepos.com/repo/tencent-hunyuan-hunyuanvideo-avatar.md","json":"https://osrepos.com/repo/tencent-hunyuan-hunyuanvideo-avatar.json","topics":["Python","AI","Machine Learning","Video Generation","Audio-Driven Animation","Diffusion Models","Avatar Generation","Computer Vision"],"keywords":["Python","AI","Machine Learning","Video Generation","Audio-Driven Animation","Diffusion Models","Avatar Generation","Computer Vision"],"stars":null,"summary":"HunyuanVideo-Avatar is a cutting-edge project by Tencent-Hunyuan for high-fidelity, audio-driven human animation. Utilizing a multimodal diffusion transformer, it generates dynamic, emotion-controllable, and multi-character dialogue videos. This innovative system addresses critical challenges in character consistency, emotion alignment, and multi-character animation, making it suitable for diverse applications like e-commerce and social media.","content":"## Introduction\n\nHunyuanVideo-Avatar is an advanced open-source project by Tencent-Hunyuan that enables high-fidelity, audio-driven human animation for multiple characters. Built upon a multimodal diffusion transformer (MM-DiT), this model excels at generating dynamic, emotion-controllable, and multi-character dialogue videos. It tackles key challenges in the field by ensuring strong character consistency, precise emotion alignment between characters and audio, and facilitating multi-character animation.\n\nThe project introduces three core innovations:\n*   **Character Image Injection Module**: Replaces conventional addition-based conditioning to eliminate condition mismatch, ensuring dynamic motion and strong character consistency.\n*   **Audio Emotion Module (AEM)**: Extracts and transfers emotional cues from a reference image to the generated video, enabling fine-grained emotion style control.\n*   **Face-Aware Audio Adapter (FAA)**: Isolates audio-driven characters with a latent-level face mask, allowing independent audio injection via cross-attention for multi-character scenarios.\n\nThese innovations allow HunyuanVideo-Avatar to produce realistic avatars in dynamic, immersive scenarios, surpassing state-of-the-art methods.\n\n## Installation\n\nTo get started with HunyuanVideo-Avatar, follow these installation steps, primarily for Linux environments. CUDA versions 12.4 or 11.8 are recommended.\n\nFirst, clone the repository:\n\nshell\ngit clone https://github.com/Tencent-Hunyuan/HunyuanVideo-Avatar.git\ncd HunyuanVideo-Avatar\n\n\nThen, set up the Conda environment and install dependencies:\n\nshell\n# 1. Create conda environment\nconda create -n HunyuanVideo-Avatar python==3.10.9\n\n# 2. Activate the environment\nconda activate HunyuanVideo-Avatar\n\n# 3. Install PyTorch and other dependencies using conda\n# For CUDA 11.8\nconda install pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=11.8 -c pytorch -c nvidia\n# For CUDA 12.4\nconda install pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=12.4 -c pytorch -c nvidia\n\n# 4. Install pip dependencies\npython -m pip install -r requirements.txt\n# 5. Install flash attention v2 for acceleration (requires CUDA 11.8 or above)\npython -m pip install ninja\npython -m pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.6.3\n\n\nFor specific GPU types encountering float point exceptions, refer to the repository's README for additional solutions, including CUDA 12.4/CUBLAS/CUDNN updates or explicit CUDA 11.8 compiled PyTorch installations.\n\nAlternatively, you can use the provided Docker images:\n\nshell\n# For CUDA 12.4\ndocker pull hunyuanvideo/hunyuanvideo:cuda_12\ndocker run -itd --gpus all --init --net=host --uts=host --ipc=host --name hunyuanvideo --security-opt=seccomp=unconfined --ulimit=stack=67108864 --ulimit=memlock=-1 --privileged hunyuanvideo/hunyuanvideo:cuda_12\npip install gradio==3.39.0 diffusers==0.33.0 transformers==4.41.2\n\n# For CUDA 11.8\ndocker pull hunyuanvideo/hunyuanvideo:cuda_11\ndocker run -itd --gpus all --init --net=host --uts=host --ipc=host --name hunyuanvideo --security-opt=seccomp=unconfined --ulimit=stack=67108864 --ulimit=memlock=-1 --privileged hunyuanvideo/hunyuanvideo:cuda_11\npip install gradio==3.39.0 diffusers==0.33.0 transformers==4.41.2\n\n\nPretrained models can be downloaded as detailed in the `weights/README.md` file within the repository.\n\n## Examples\n\nHunyuanVideo-Avatar supports both parallel inference on multiple GPUs and single-GPU inference, including options for very low VRAM environments.\n\n**Parallel Inference on Multiple GPUs (e.g., 8 GPUs):**\n\nbash\ncd HunyuanVideo-Avatar\n\nJOBS_DIR=$(dirname $(dirname \"$0\"))\nexport PYTHONPATH=./\nexport MODEL_BASE=\"./weights\"\ncheckpoint_path=${MODEL_BASE}/ckpts/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt\n\ntorchrun --nnodes=1 --nproc_per_node=8 --master_port 29605 hymm_sp/sample_batch.py \\\n    --input 'assets/test.csv' \\\n    --ckpt ${checkpoint_path} \\\n    --sample-n-frames 129 \\\n    --seed 128 \\\n    --image-size 704 \\\n    --cfg-scale 7.5 \\\n    --infer-steps 50 \\\n    --use-deepcache 1 \\\n    --flow-shift-eval-video 5.0 \\\n    --save-path ${OUTPUT_BASEPATH} \n\n\n**Single-GPU Inference:**\n\nbash\ncd HunyuanVideo-Avatar\n\nJOBS_DIR=$(dirname $(dirname \"$0\"))\nexport PYTHONPATH=./\n\nexport MODEL_BASE=./weights\nOUTPUT_BASEPATH=./results-single\ncheckpoint_path=${MODEL_BASE}/ckpts/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states_fp8.pt\n\nexport DISABLE_SP=1 \nCUDA_VISIBLE_DEVICES=0 python3 hymm_sp/sample_gpu_poor.py \\\n    --input 'assets/test.csv' \\\n    --ckpt ${checkpoint_path} \\\n    --sample-n-frames 129 \\\n    --seed 128 \\\n    --image-size 704 \\\n    --cfg-scale 7.5 \\\n    --infer-steps 50 \\\n    --use-deepcache 1 \\\n    --flow-shift-eval-video 5.0 \\\n    --save-path ${OUTPUT_BASEPATH} \\\n    --use-fp8 \\\n    --infer-min\n\n\n**Run with very low VRAM (e.g., 10GB VRAM with TeaCache):**\n\nbash\ncd HunyuanVideo-Avatar\n\nJOBS_DIR=$(dirname $(dirname \"$0\"))\nexport PYTHONPATH=./\n\nexport MODEL_BASE=./weights\nOUTPUT_BASEPATH=./results-poor\n\ncheckpoint_path=${MODEL_BASE}/ckpts/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states_fp8.pt\n\nexport CPU_OFFLOAD=1\nCUDA_VISIBLE_DEVICES=0 python3 hymm_sp/sample_gpu_poor.py \\\n    --input 'assets/test.csv' \\\n    --ckpt ${checkpoint_path} \\\n    --sample-n-frames 129 \\\n    --seed 128 \\\n    --image-size 704 \\\n    --cfg-scale 7.5 \\\n    --infer-steps 50 \\\n    --use-deepcache 1 \\\n    --flow-shift-eval-video 5.0 \\\n    --save-path ${OUTPUT_BASEPATH} \\\n    --use-fp8 \\\n    --cpu-offload \\\n    --infer-min\n\n\n**Run a Gradio Server:**\n\nbash\ncd HunyuanVideo-Avatar\n\nbash ./scripts/run_gradio.sh\n\n\n## Why Use HunyuanVideo-Avatar?\n\nHunyuanVideo-Avatar offers a robust solution for generating high-quality, dynamic human animations from audio input. Its key advantages include:\n\n*   **High-Fidelity and Dynamic Video Generation**: Produces realistic and natural videos with high-dynamic foreground and background, preserving strong character consistency.\n*   **Emotion-Controllable Animation**: Allows precise control over facial emotions, driven by input audio and emotion reference images.\n*   **Multi-Character Support**: Capable of animating multiple characters simultaneously, making it ideal for dialogue videos and complex scene creation.\n*   **Versatile Avatar Styles**: Supports a wide range of avatar images, including photorealistic, cartoon, 3D-rendered, and anthropomorphic characters, at arbitrary scales and resolutions (portrait, upper-body, full-body).\n*   **Optimized for Performance**: Includes features like DeepCache and TeaCache for efficient inference, even on single GPUs with limited VRAM (as low as 10GB).\n*   **Broad Applications**: Suitable for various downstream tasks such as e-commerce, online streaming, social media video production, and general video content creation and editing.\n\n## Links\n\n*   **GitHub Repository**: <a href=\"https://github.com/Tencent-Hunyuan/HunyuanVideo-Avatar\" target=\"_blank\">https://github.com/Tencent-Hunyuan/HunyuanVideo-Avatar</a>\n*   **Project Page**: <a href=\"https://HunyuanVideo-Avatar.github.io/\" target=\"_blank\">https://HunyuanVideo-Avatar.github.io/</a>\n*   **Playground**: <a href=\"https://hunyuan.tencent.com/modelSquare/home/play?modelId=126\" target=\"_blank\">https://hunyuan.tencent.com/modelSquare/home/play?modelId=126</a>\n*   **ArXiv Paper**: <a href=\"https://arxiv.org/pdf/2505.20156\" target=\"_blank\">https://arxiv.org/pdf/2505.20156</a>\n*   **Hugging Face**: <a href=\"https://huggingface.co/tencent/HunyuanVideo-Avatar\" target=\"_blank\">https://huggingface.co/tencent/HunyuanVideo-Avatar</a>","metrics":{"detailViews":1,"githubClicks":1},"dates":{"published":null,"modified":"2025-12-30T00:00:58.000Z"}}