Skip to content

Latest commit

 

History

History
105 lines (80 loc) · 3.34 KB

README.md

File metadata and controls

105 lines (80 loc) · 3.34 KB

HunyuanVideo MLX

A streamlined, Mac-native port of Tencent's text-to-video AI model, optimized specifically for Apple Silicon. Generate high-quality videos from text descriptions with native performance on your M1/M2/M3 Mac.

Why This Port?

This project makes HunyuanVideo accessible on Apple Silicon Macs by:

  • Leveraging native Metal acceleration through MLX
  • Optimizing memory usage for Mac hardware
  • Simplifying the setup process
  • Providing Mac-specific performance tuning

Setup & Usage

# One-line setup
curl -s https://raw.githubusercontent.com/gregcmartin/HunyuanVideo_MLX/main/install_mlx.sh | bash

# Download model weights (requires Hugging Face token)
python download_weights.py

# Generate your first video
python sample_video_mps.py \
    --video-size 720 1280 \
    --prompt "a cat is running, realistic." \
    --save-path ./results

Before running download_weights.py, make sure you have:

  1. A Hugging Face account and access token (get it from https://huggingface.co/settings/tokens)
  2. Created a .env file with your token: HF_TOKEN=your_token_here

Key Features

  • Mac-Native Performance: Built specifically for Apple Silicon using Metal acceleration
  • Memory Optimization: Efficient implementation that works well with Mac memory architecture
  • Multiple Resolutions: Support for various video sizes and aspect ratios
    • 540p (544x960, 960x544, etc.)
    • 720p (720x1280, 1280x720, etc.)
  • Real-time Monitoring: Built-in resource monitoring for optimal performance
  • Easy Setup: Streamlined installation process for Mac users
  • MMGP Optimization: Mixed Model Generation Pipeline optimized for each Mac model

Hardware Requirements & Optimization

M3 Max/Ultra with 64GB+ RAM

  • Direct 720p generation with float32 precision
  • Higher watermark ratio (0.8) for better performance
  • Batch processing enabled
  • 40 inference steps for optimal quality

Other M-series with 32GB RAM

  • Two-phase generation (540p → 720p)
  • Float16 precision for memory efficiency
  • Balanced watermark ratio (0.7)
  • Memory-efficient processing

Minimum Requirements

  • Apple Silicon Mac (M1/M2/M3)
  • macOS 12.3 or later
  • 32GB RAM minimum
  • Python 3.10 or later

Example Configurations

# High-quality 720p video (M3 Max/Ultra 64GB)
python sample_video_mps.py \
    --video-size 720 1280 \
    --prompt "your prompt here"

# Memory-efficient 540p video (32GB RAM)
python sample_video_mps.py \
    --video-size 544 960 \
    --prompt "your prompt here"

# Square video
python sample_video_mps.py \
    --video-size 720 720 \
    --prompt "your prompt here"

Performance Tips

  • Use appropriate settings for your Mac model (see Hardware Requirements)
  • Close memory-intensive applications before generating videos
  • Monitor system resources with python monitor_resources.py
  • First generation may be slower due to Metal shader compilation
  • Set memory ratio for optimal performance: 
    # For 64GB RAM configurations:
export PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.8

# For 32GB RAM configurations:
export PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.7

License

Licensed under the Tencent Hunyuan Community License - see LICENSE.txt for details.

Acknowledgements