Installation

macOS (Recommended)

Install via Homebrew, then run the first-run setup:

brew install theSamPadilla/montaj/montaj
montaj doctor               # diagnose what's missing — gives exact next steps
montaj install ui           # build the UI bundle (cached at ~/.cache/montaj/)
montaj install whisper      # transcription model weights (optional)

montaj doctor is the source of truth for what your install needs — it prints the exact commands to fix each missing piece.

PyPI

pip install montaj
montaj doctor               # diagnose what's missing
montaj install ui           # build UI bundle

pip install montaj ships the CLI plus all bundled assets (steps, workflows, skills, render engine source, UI source, MCP server source). montaj install ui builds the Node.js bundles into ~/.cache/montaj/. Use a venv (or pipx install montaj) so site-packages stays isolated.

Linux / Manual

git clone https://github.com/theSamPadilla/montaj
cd montaj
pip install -e .

This installs Python dependencies (including a bundled ffmpeg). Install Node.js >= 18 separately, then build the UI bundle:

# Install Node.js >= 18: https://nodejs.org
montaj install whisper   # whisper-cpp binary + model weights
montaj install ui        # npm deps + UI build

Optional Dependencies

montaj install rvm          # background removal (torch + RVM weights)
montaj install connectors   # pyjwt, requests, google-genai, openai (for API steps)
montaj install credentials  # interactive setup for API keys
montaj install all          # everything above

Dependency Groups

Group	What it installs	Required for
`whisper`	whisper-cli (via `brew install whisper-cpp` on macOS) + base.en model weights	`transcribe`, `rm_fillers`, `rm_nonspeech`, `waveform_trim`, render pipeline
`ui`	npm deps for `render/` and `ui/`; production UI build	`montaj serve`, render engine
`rvm`	torch, torchvision, av (pip) + RVM model weights	`remove_bg`
`connectors`	pyjwt, requests, google-genai, openai	`kling_generate`, `analyze_media`, `generate_image`, `generate_voiceover`, `generate_music`

Whisper Models

By default, montaj install whisper downloads the base.en model. To install a different model:

montaj install whisper --model medium.en

montaj install whisper is safe to re-run — it short-circuits if whisper-cli is already on PATH and skips the model download if already cached. On macOS it delegates to brew install whisper-cpp (bottled, fast). On Linux it prints build-from-source instructions, since upstream (ggml-org/whisper.cpp) stopped publishing pre-built tarballs as of v1.7.5.

Verify Installation

montaj doctor
# Checks ffmpeg (version + required filters), ffprobe, node, python3, whisper
# Exit 0 = all good, exit 1 = issues found

If montaj doctor reports missing zscale filter (needed for HDR normalization):

montaj install ffmpeg
# Rebuilds ffmpeg with libzimg (macOS/Homebrew only)

Build cache

montaj install ui builds the render engine, UI bundle, and MCP server into ~/.cache/montaj/. The cache is invalidated automatically when you upgrade montaj (a .version stamp keeps it in sync with the installed package). To force a rebuild:

rm -rf ~/.cache/montaj
montaj install ui

Upgrade

montaj update            # upgrade everything (whisper binary, pip packages)
montaj update whisper    # brew upgrade whisper-cpp on macOS; build-from-source hint on Linux
montaj update pip        # pip install --upgrade montaj

System Requirements

Tool	Purpose
`ffmpeg` + `ffprobe`	Core video processing (bundled via pip/brew)
`whisper.cpp`	Local speech-to-text with word-level timestamps
`Python 3.x`	Script + step runtime
`Node.js >= 18`	Render engine (React + Puppeteer) + UI server

Installation

On this page