Installation

Arena is an AI-powered, open-source, local-first video clipping engine for the terminal that automatically finds the best moments in your videos and exports platform-ready clips for TikTok, Reels, and Shorts.

Quick start — try it without installing

npx @whitegodkingsley/arena-cli process video.mp4 -n 5

Requires Node.js 22–24, Python 3.10–3.12, and FFmpeg. Set OPENAI_API_KEY first.

Choose your install method

The quickest way to get started. Requires Node.js 22–24.

1. Install globally

Terminal

npm install -g @whitegodkingsley/arena-cli

2. Verify installation

Terminal

arena --version

3. Run setup wizard

Terminal

arena init

Permission issues? Configure npm to use a writable directory:

Terminal

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g @whitegodkingsley/arena-cli

Add the export PATH line to your ~/.bashrc or ~/.zshrc to make it permanent.

Clone the repo and build from source. Best for development and contributing.

Terminal

# Clone the repository
git clone https://github.com/iamwhitegod/arena.git
cd arena

# Install CLI dependencies
cd cli && npm install

# Build TypeScript
npm run build

# Link globally for development
npm link

# Build Arena's managed Python runtime
arena setup

Verify

Terminal

arena --version

Run Arena without installing any dependencies locally. Docker handles everything.

Prerequisites

Set your OpenAI API key before running Docker commands:

export OPENAI_API_KEY="sk-..."

Option 1: Docker Compose (recommended)

Terminal

git clone https://github.com/iamwhitegod/arena.git
cd arena
docker compose build
docker compose run arena process video.mp4 -n 5

Docker Compose automatically mounts your current directory and passes your OPENAI_API_KEY.

Option 2: Docker Hub

Terminal

docker pull whitegodkingsley/arena:latest
docker run -v $(pwd):/workspace \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  whitegodkingsley/arena process video.mp4 -n 5

Option 3: Build yourself

Terminal

docker build -t arena .
docker run -v $(pwd):/workspace \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  arena process video.mp4

What's included in the Docker image

Dependency	Version	Purpose
Python	3.10	AI engine, video processing
Node.js	22	CLI runtime
FFmpeg	System	Video encoding, clip extraction

Note: yt-dlp is installed from Arena's Python requirements. yt-dlp uses the included Node.js runtime for YouTube's JavaScript challenge solving; Deno is not required.

Install dependencies

If you installed via npm or source (not Docker), you need these dependencies on your system.

FFmpeg (required)

Terminal

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg

# Verify
ffmpeg -version

Python (required)

Terminal

# macOS
brew install python3

# Ubuntu/Debian
sudo apt install python3 python3-pip

# Verify
python3 --version

Run arena setup to create Arena's isolated Python runtime, install yt-dlp and the engine dependencies, and verify FFmpeg. You do not need to install Arena packages into global Python:

Terminal

arena setup

Set up your API key

Terminal

# Option 1: Environment variable (add to ~/.bashrc or ~/.zshrc)
export OPENAI_API_KEY="sk-..."

# Option 2: Owner-only Arena credential store (interactive prompt)
arena config set openai_api_key

# Verify
arena config get openai_api_key

Run the setup wizard

Terminal

arena init

The wizard helps you configure your workflow type, clip duration preferences, and quality vs cost balance.

Quick start

Terminal

# Process a local video
arena process video.mp4 -n 5

# Process a YouTube URL
arena process "https://www.youtube.com/watch?v=VIDEO_ID" -n 5

# Transcribe audio
arena transcribe podcast.mp3

# Process with captions for TikTok
arena process video.mp4 --captions -p tiktok