ltx-video-mac

LTX Video Generator for Mac

Native SwiftUI macOS app for local AI video on Apple Silicon. v2.3.69 adds LTX-2.5 (ltx-2-mlx) and MiniMax H3 (h3.c) alongside existing LTX-2 / 2.3 generation via mlx-video-with-audio.

Features

• LTX-2, LTX-2.3, LTX-2.5, MiniMax H3 — 2.3 Distilled Q4 is the default; 2.5 via ltx-2-mlx (opt-in install); H3 via native h3.c
• Native macOS App - Built with SwiftUI for a seamless Mac experience
• Apple Silicon Native - Uses MLX (and H3 Metal) for M-series chips
• Text-to-Video Generation - Transform text prompts into video clips
• Image-to-Video - Animate images; first/last frame and multi-image keyframes on the LTX path
• Built-in Audio Generation - LTX AV models generate synchronized audio with video
• Voiceover Narration - Add TTS voiceover using ElevenLabs (cloud) or MLX-Audio (local)
• Background Music - Generate instrumental music with 54 genre presets via ElevenLabs Music API
• Local REST API - 127.0.0.1:8420 for queued generate (model_id includes ltx25_* and minimax_h3 / _int8 / _turbo)
• Auto Package Installer - Missing Python packages are detected and can be installed with one click
• Generation Queue - Queue multiple generations with real-time progress tracking
• History Management - Browse, preview, and manage all your generated videos
• Presets - Save and load generation parameter presets
• Customizable Parameters - Fine-tune resolution, frames, steps, guidance scale, and more

Requirements

• macOS 14.0 or later
• Apple Silicon Mac (M1, M2, M3, M4 series)
• 32GB RAM minimum (64GB+ recommended for higher resolutions)
• Python 3.10+ installed (via Homebrew, pyenv, or system)
• ~20-144GB disk space for model weights (depends on selected model; H3 is ~144GB)

Installation

1. Download the App

Download the latest release from the Releases page.

2. First Launch Setup

1. Open LTX Video Generator
2. Go to Preferences (⌘,)
3. Click Auto Detect to find your Python installation, or manually set the path
4. Click Validate Setup - the app will check for required packages

3. Install Python Packages

If packages are missing, the app will show an "Install Missing Packages" button. Click it to automatically install:

mlx mlx-vlm mlx-video-with-audio transformers safetensors huggingface_hub numpy opencv-python tqdm

Or install manually:

pip install mlx mlx-vlm mlx-video-with-audio transformers safetensors huggingface_hub numpy opencv-python tqdm

The mlx-video-with-audio package is available on PyPI and provides the unified audio-video generation.

4. First Generation - Model Download

Important: On first generation, the app downloads your selected model from Hugging Face. This is a one-time download that may take 15-30 minutes depending on model size and internet connection.

The model is cached in ~/.cache/huggingface/ by default and will not be re-downloaded on subsequent runs. To keep large model files on another disk, choose a Model Cache Directory under Settings > General > Storage before the first generation.

Progress is shown in the app during download.

Available models:

• LTX-2 Unified (notapalindrome/ltx2-mlx-av, ~42GB)
• LTX-2.3 Unified Beta (notapalindrome/ltx23-mlx-av, ~48GB)
• LTX-2.3 Distilled Q4 Beta (notapalindrome/ltx23-mlx-av-q4, ~22GB, default except ≤16GB Macs)
• LTX-2.3 12GB RAM Optimized (baa-ai/LTX-2.3-22B-RAM-12GB-MLX, ~19GB, ltx-2-mlx; default on ≤16GB)
• LTX-2.5 Distilled bf16 (notapalindrome/ltx25-mlx, ~110GB w/ Dev LoRA, ltx-2-mlx 0.15+)
• LTX-2.5 Distilled Q8 DiT (notapalindrome/ltx25-mlx + overlay notapalindrome/ltx25-mlx-ditq8)
• MiniMax H3 BF16 (minimax_h3, MiniMaxAI/MiniMax-H3, ~144GB, native h3.c)
• MiniMax H3 int8 (minimax_h3_int8, Comfy-Org DiT + MiniMaxAI TE/VAE, ~92GB)
• MiniMax H3 Turbo (minimax_h3_turbo, folded larryvrh v4 LoRA, fixed 6 steps)

Usage

1. Enter a descriptive prompt in the text field
2. Adjust parameters using presets or manual controls
3. Click Generate to start
4. Watch progress in the Queue sidebar
5. Find completed videos in your configured output directory (default: Application Support)

Local REST API

Enable API Server in the app sidebar. The server listens only on 127.0.0.1:8420.

Image-to-video requests use an absolute path to a readable local image:

curl -X POST http://127.0.0.1:8420/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "The camera slowly pushes forward as banners move in the wind",
    "source_image_path": "/absolute/path/to/source.png",
    "model_id": "ltx23_unified",
    "parameters": {
      "width": 1536,
      "height": 576,
      "num_frames": 125,
      "fps": 24,
      "num_inference_steps": 30,
      "guidance_scale": 3.0,
      "image_strength": 1.0
    }
  }'

Omit source_image_path for text-to-video generation. The source image path is resolved and validated before the request is queued.

Other model_id values: ltx23_distilled_q4 (default), ltx25_distilled, ltx25_dev, ltx25_distilled_ditq8, minimax_h3, minimax_h3_int8, minimax_h3_turbo. text_encoder_id is ignored for 2.5 and H3. ltx25_dev is official two-stage (dev DiT + fuse distilled LoRA bundled in notapalindrome/ltx25-mlx).

Gemma Prompt Enhancement

When enabled in Settings > Generation, Gemma rewrites your prompt before generation—expanding short descriptions into detailed, LTX-2–optimized prompts with visuals, audio, camera movement, and style. Use the Preview enhanced prompt button to see the rewritten prompt before generating.

Note: This enhancer is optional.
The core text encoder used for generation embeddings is still required even when prompt enhancement is off.

1. Go to Settings > Generation
2. Turn on Enable Gemma Prompt Enhancement
3. First run downloads the Gemma enhancer (~7GB)
4. In the prompt view, expand Prompt Enhancement (Gemma) and adjust sliders (Repetition Penalty, Top-P) if desired
5. Click Preview enhanced prompt to see the enhanced version before generating
6. Generate as usual—the enhanced prompt is used automatically

If enhancement fails for any reason, generation automatically falls back to your original prompt.

Tips for Better Results (LTX-2.5)

Official style: ltx.io prompt guide · docs.ltx.io.

• One flowing present-tense paragraph covering shot, scene/lighting, action, characters (physical cues), camera, audio
• Spoken lines only in "quotes"; pauses as action (he pauses), not bare Beat.
• Multishot: name cuts in prose (A hard cut transitions to…) — no START FRAME / JUMP CUT lists
• On Mac Distilled/Dev, prefer a single continuous take for dialogue reliability

Copy-paste examples: EXAMPLES.md.

Audio Features

Built-in Audio (Default)

Selected models generate synchronized audio alongside video automatically. No additional configuration needed - just generate and your video will have audio.

For best speech/lip-sync alignment, use 24 FPS.

You can still layer additional voiceover or background music on top of the built-in audio if desired.

Voiceover / Narration

Add text-to-speech voiceover to your videos:

1. Expand Voiceover / Narration in the generation view
2. Choose your source: MLX-Audio (local, free) or ElevenLabs (cloud, requires API key)
3. Select a voice from the dropdown
4. Enter your narration text
5. Audio generates with your video or can be added later from History

Background Music

Add AI-generated instrumental music (requires ElevenLabs API key):

1. Expand Background Music in the generation view
2. Toggle Generate background music
3. Choose from 54 genre presets:
   • Electronic: EDM, House, Techno, Ambient, Synthwave, etc.
   • Hip-Hop/R&B: Trap, Lo-Fi, Boom Bap, Soul, etc.
   • Rock: Classic, Alternative, Indie, Metal, etc.
   • Pop: Modern, Indie, Dance, Acoustic
   • Jazz/Blues: Smooth Jazz, Bebop, Lounge, Blues
   • Classical/Cinematic: Orchestral, Piano, Epic, Tense, Uplifting
   • World: Latin, Reggae, Afrobeat, Middle Eastern, Asian
   • Country/Folk: Modern, Classic, Acoustic, Indie
   • Functional: Corporate, Motivational, Relaxing, Suspense, Action, Romantic, etc.

Music automatically matches your video length and is mixed at background volume (30%) or ducked further (20%) when combined with voiceover.

Adding Audio to Existing Videos

Right-click any video thumbnail in Video Archive and select Add Audio to add voiceover, music, or both to previously generated videos.

Example

Here's an example video generated with LTX Video Generator:

Open video link

Prompt used:

Create a 15-second cinematic product commercial for a sleek, premium TIME MACHINE device called "ChronoShift One."

Overall style: glossy tech product ad, filmed in 4K, smooth dolly and slider shots, soft studio lighting, subtle retro‑futuristic aesthetic (think brushed aluminum, glowing rings, clean UI). The time machine looks like a compact desktop appliance about the size of a toaster: brushed metal body, circular time dial with glowing blue light, small display, and a single illuminated control knob.

Example (X/Twitter Link)

And a second run produced this one:

Open video link

Open X/Twitter post

Prompt used:

Scene tone: quiet, reflective, fragmented memory. Cinematic realism, muted natural colors. Overcast but DRY weather. No rain, no raindrops, no wet falling precipitation.

START FRAME (0-2.5s)
Extreme close-up (85mm) of the elderly man's face. He breathes slowly. A tiny tremor in the lower eyelid. Strands of white hair drift gently in a light breeze.
Dialogue (man, barely above a whisper):
"I remember."

Motion: micro push-in only.

JUMP CUT 1 (2.5-5s)
Hard cut to an extreme close-up of his hands: weathered fingers rubbing a small object (a coin / pebble / ring) in his palm.
Dialogue (man):
"Not the day..."

Motion: hands move slowly, deliberately.

JUMP CUT 2 (5-7.5s)
Hard cut to close-up (50-85mm) of his boots stepping into soft mud at the lake edge. The movement is careful, almost hesitant. No splashing, just a quiet press into wet ground.
Dialogue (man):
"The feeling."

Motion: one slow step, then stillness.

JUMP CUT 3 (7.5-10s)
Hard cut to close-up of the lake surface: perfectly still water with faint ripples spreading outward (from a dropped pebble or a gentle touch).
Dialogue (man):
"It stayed."

Building from Source

# Clone the repository
git clone https://github.com/james-see/ltx-video-mac.git
cd ltx-video-mac

# Open in Xcode
open LTXVideoGenerator/LTXVideoGenerator.xcodeproj

# Or build from command line
./scripts/build-local.sh

Technical Details

• Frontend: SwiftUI
• Python Bridge: Subprocess execution with progress streaming
• ML Framework: MLX (Apple's machine learning framework)
• Models:
  • LTX-2 Unified (~42GB, mlx-video-with-audio)
  • LTX-2.3 Unified Beta (~48GB)
  • LTX-2.3 Distilled Q4 (~22GB, default except ≤16GB)
  • LTX-2.3 12GB RAM Optimized (~19GB, ltx-2-mlx, mixed-precision)
  • LTX-2.5 Distilled (~110GB w/ LoRA, ltx-2-mlx 0.15+, Gemma 4 bundled)
  • LTX-2.5 Distilled Q8 DiT (same pack + DiT overlay)
  • MiniMax H3 (~144GB, native h3.c)
• Precision: bfloat16 (LTX); H3 is official BF16, Comfy-Org int8, or folded Turbo on the same Metal h3

Architecture

LTX-2 / 2.3 notapalindrome packs use a 2-stage pipeline (half-res then refine). ltx-2-mlx distilled (2.5 and the 12GB pack) is a fixed 8-step pass. H3 runs ./h3 (24 fps, frames snap to 5+17n). See Architecture.

Troubleshooting

"Model download stuck"

The download progress updates every 1%. Size depends on the selected model (~22GB Q4 default, ~100GB LTX-2.5, ~144GB H3). Be patient.

"Out of memory"

• Reduce resolution (512x320 is fastest)
• Reduce frame count (25/33/49 recommended)
• Use 24 FPS
• Set VAE tiling to aggressive
• Close other applications
• 32GB RAM minimum, 64GB recommended

"Python not found"

• Install Python via Homebrew: brew install [email protected]
• Or use pyenv: pyenv install 3.12
• Then click "Auto Detect" in Preferences

"LTX 2.3 conversion / LoRA compatibility"

• LTX-2 / 2.3 stay on mlx-video-with-audio. LTX-2.5 uses dgrauet/ltx-2-mlx (git, only when selected). H3 uses a local h3 binary.
• Converting additional upstream checkpoints can require package-level updates in mlx-video-with-audio before they run reliably here.
• Standard LTX LoRA workflows are not guaranteed to transfer directly to the MLX-converted AV path without conversion tooling support.

License

MIT License - see LICENSE for details.

Acknowledgments

• Lightricks for LTX-2 / LTX-2.5
• mlx-video-with-audio for LTX-2 / 2.3 unified AV
• dgrauet/ltx-2-mlx for LTX-2.5
• antirez/h3.c and MiniMax for H3
• MLX Community for the MLX-converted weights
• Blaizzy/mlx-video for the original MLX video generation code
• Hugging Face for model hosting