Initial release

README.md

@@ -0,0 +1,134 @@
+# LTX-2 on Apple Silicon (MPS)
+
+Run [Lightricks LTX-2](https://huggingface.co/Lightricks/LTX-2) video generation on Mac with Apple Silicon using Metal Performance Shaders (MPS).
+
+## The Problem
+
+LTX-2 uses `float64` (double precision) for rotary position embeddings (RoPE), but Apple's MPS backend doesn't support float64 - only float32. This causes the error:
+
+```
+TypeError: Cannot convert a MPS Tensor to float64 dtype as the MPS framework doesn't support float64
+```
+
+## The Solution
+
+This repo provides a patch that forces `float32` for RoPE calculations. The quality difference is negligible, and it enables LTX-2 to run on Mac.
+
+## Requirements
+
+- **macOS** with Apple Silicon (M1, M2, M3, M4 - any variant)
+- **Python 3.11+**
+- **64GB+ RAM recommended** (model is ~40GB, 128GB ideal for max settings)
+- **PyTorch 2.0+**
+
+## Quick Start
+
+```bash
+# 1. Clone this repo
+git clone https://github.com/YOUR_USERNAME/ltx2-mps.git
+cd ltx2-mps
+
+# 2. Create virtual environment
+python3 -m venv venv
+source venv/bin/activate
+
+# 3. Install dependencies
+pip install torch torchvision torchaudio
+pip install git+https://github.com/huggingface/diffusers.git
+pip install transformers accelerate safetensors sentencepiece
+pip install imageio imageio-ffmpeg
+
+# 4. Apply MPS patches
+python patch_mps.py
+
+# 5. Generate a video!
+python generate.py "A cat walking through grass" -o output.mp4
+```
+
+## Usage
+
+```bash
+python generate.py "Your prompt here" -o output.mp4 [options]
+```
+
+### Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--width` | 512 | Video width (must be divisible by 32) |
+| `--height` | 320 | Video height (must be divisible by 32) |
+| `--frames` | 25 | Number of frames (must be 8n+1: 9, 17, 25, 33, 41, 49, 57, 65, 73, 81, 89, 97) |
+| `--steps` | 20 | Inference steps (more = better quality, slower) |
+| `--guidance` | 5.0 | Guidance scale |
+| `--fps` | 24 | Output video FPS |
+| `--seed` | random | Random seed for reproducibility |
+| `-n` | "" | Negative prompt |
+
+### Examples
+
+```bash
+# Quick preview (fast)
+python generate.py "A sunset over mountains" -o preview.mp4 --frames 25 --steps 10 --width 512 --height 320
+
+# Standard quality
+python generate.py "A dog running on the beach" -o standard.mp4 --frames 49 --steps 20 --width 768 --height 448
+
+# High quality (slow, needs 128GB RAM)
+python generate.py "Cinematic shot of a forest" -o hq.mp4 --frames 97 --steps 30 --width 1024 --height 576
+```
+
+## Performance
+
+Tested on Mac with M-series chips:
+
+| Resolution | Frames | Steps | Time (approx) | RAM Usage |
+|------------|--------|-------|---------------|-----------|
+| 512x320 | 25 | 10 | ~1 min | ~45GB |
+| 768x448 | 49 | 20 | ~10 min | ~60GB |
+| 1024x576 | 97 | 30 | ~30 min | ~80GB |
+
+## How the Patch Works
+
+Two files in diffusers are patched:
+
+### 1. `diffusers/pipelines/ltx2/connectors.py`
+```python
+# Before:
+freqs_dtype = torch.float64 if self.double_precision else torch.float32
+
+# After:
+freqs_dtype = torch.float32  # MPS fix
+```
+
+### 2. `diffusers/models/transformers/transformer_ltx2.py`
+```python
+# Before:
+freqs_dtype = torch.float64 if self.double_precision else torch.float32
+
+# After:
+freqs_dtype = torch.float32  # MPS fix
+```
+
+## Troubleshooting
+
+### "MPS backend out of memory"
+- Reduce resolution, frames, or close other apps
+- Try `--width 512 --height 320 --frames 25`
+
+### Model download fails
+- Check your internet connection
+- The model is ~40GB, first run takes a while to download
+
+### Import errors
+- Make sure you installed diffusers from git (dev version needed for LTX2Pipeline)
+- Run `pip install git+https://github.com/huggingface/diffusers.git`
+
+## Credits
+
+- [Lightricks](https://github.com/Lightricks) for LTX-2
+- [Hugging Face](https://github.com/huggingface/diffusers) for diffusers
+- MPS patch discovered while debugging with Claude
+
+## License
+
+MIT