Getting Started

OpenMontage is an agent-orchestrated video production platform. You produce videos by cloning the repository, running setup, and then working inside an AI coding assistant (Claude Code, Cursor, Copilot, or similar). The assistant reads pipeline manifests and stage-director skills, calls Python tools, writes checkpoints, and drives the entire flow. There is no standalone CLI or Python runtime orchestrator.

Prerequisites

You need:

• Python 3.10 or higher
• FFmpeg (used by many tools for analysis, mixing, and composition)
• Node.js 18 or higher (for Remotion and HyperFrames composition)
• An AI coding assistant

Install FFmpeg with brew install ffmpeg (macOS), sudo apt install ffmpeg (Debian/Ubuntu), or from ffmpeg.org. Install Node.js from nodejs.org.

Clone and Set Up

git clone https://github.com/calesthio/OpenMontage.git
cd OpenMontage
make setup

make setup runs:

• pip install -r requirements.txt
• cd remotion-composer && npm install
• pip install piper-tts (optional offline TTS)
• npx --yes hyperframes --version (caches the HyperFrames CLI)
• cp .env.example .env (if .env does not exist)

If you cannot use make, run the steps manually:

pip install -r requirements.txt
cd remotion-composer && npm install && cd ..
pip install piper-tts || echo "piper-tts optional"
npx --yes hyperframes --version || echo "HyperFrames cache optional"
cp .env.example .env || true

Windows note: If npm install fails with ERR_INVALID_ARG_TYPE, use npx --yes npm install.

Configure Your Environment

cp .env.example .env

For a first run with zero external cost, leave .env empty or with only free-stock keys. Local tools (Piper TTS, FFmpeg, Remotion, stock corpus) and free providers (Pexels, Pixabay) work without paid keys.

Verify Installation

Run the preflight check before any production:

make preflight

Or run the discovery command directly:

python -c "
from tools.tool_registry import registry
import json
registry.discover()
print(json.dumps(registry.provider_menu_summary(), indent=2))
"

This reports composition runtimes (ffmpeg, remotion, hyperframes), configured vs. total capabilities, setup offers, and runtime warnings.

Run a Zero-Key Demo

make demo

This renders a sample video using only local and free paths. Output appears under projects/<kebab-name>/renders/final.mp4 following the standard workspace layout.

Produce Your First Custom Video

1. Open the OpenMontage directory in your AI coding assistant.

2. Instruct the assistant to run a pipeline. Start with the minimal validation pipeline:

   "Run the framework-smoke pipeline and produce a short test video."

The assistant will:

• Load the manifest from pipeline_defs/
• Read the corresponding stage-director skill
• Call tools via the registry
• Write checkpoints under pipeline/<project-id>/
• Place assets and the final render under projects/<kebab-name>/

See the exact workspace layout and artifact locations in Project Workspace.

Next Steps

• Add API keys to .env for image, video, and voice providers. See Configuring Providers.
• Learn the full stage flow and how to guide the agent in Running Pipelines.
• Explore all available pipelines in Available Pipelines.
• Troubleshoot setup issues in Installation.

After the first successful render, run preflight again whenever you change .env or install new dependencies.