reeln

Platform-agnostic CLI toolkit for livestreamers.

reeln handles video manipulation, segment/highlight management, and media lifecycle — generic by default, sport-specific through configuration. Built by Streamn Dad.

Requirements

• Python 3.11+
• ffmpeg 5.0+ with libx264, aac, and libass

Important: reeln requires ffmpeg installed on your system. It is used for all video processing — merging, rendering, overlays, and encoding. Install it before using reeln, then run reeln doctor to verify.

# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

# Windows
winget install ffmpeg

Install

# With pip
pip install reeln

# With uv (recommended)
uv tool install reeln

Verify everything is working:

reeln --version
reeln doctor          # checks ffmpeg, codecs, config, permissions, plugins

Features

• Game lifecycle management — init, segment processing, highlights, events, finish
• Short-form rendering — crop, scale, speed, LUT, overlays — landscape to vertical/square
• FFmpeg-powered merging — concat segments into highlight reels with smart re-encoding
• Sport-agnostic segments — hockey periods, basketball quarters, soccer halves, and more
• Render profiles — save and reuse rendering settings, chain them with iterations
• Smart zoom — AI-powered tracking that follows the action (via plugin)
• Player overlays — roster-aware goal overlays with jersey number lookup
• Render queue — stage renders for review, then selectively publish to YouTube, Instagram, TikTok
• Team logo overlays — automatic logo placement on goal shorts from team profiles
• Plugin architecture — lifecycle hooks for YouTube, Instagram, cloud uploads, and more
• Flexible configuration — JSON config, XDG paths, env var overrides, named profiles
• Cross-platform — macOS, Linux, Windows

Quick start

# Initialize a hockey game
reeln game init roseville mahtomedi --sport hockey

# Process segments as the game progresses
reeln game segment 1
reeln game segment 2
reeln game segment 3

# Merge into a full-game highlight reel
reeln game highlights

# Render a vertical short for social media
reeln render short clip.mkv --crop crop --speed 0.5

# Finish the game
reeln game finish

See the examples for detailed walkthroughs of every workflow.

Looking for a GUI? reeln dock is a cross-platform desktop companion for reeln — visual render profiles, clip review, and game management without touching the terminal. Coming soon.

Supported sports

CLI reference

System

Game lifecycle

Rendering

Queue

Configuration

Plugins

Configuration

reeln uses a layered JSON config system:

1. Bundled defaults — shipped with the package
2. User config — config.json in your XDG config directory
3. Game overrides — game.json in the game directory
4. Environment variables — REELN_<SECTION>_<KEY>

reeln config show

Smart zoom — AI-powered action tracking

reeln render short --smart uses the OpenAI plugin to analyse extracted frames and track the action — dynamically cropping and panning the camera to follow the play in your 9:16 short. Read What happened when I let AI edit my youth hockey videos for the full story.

Add --debug to see exactly what the AI sees: annotated frames with crosshair tracking, crop regions, the full zoom path, and every ffmpeg filter chain.

Live debug example — real game clip with 16-frame smart zoom tracking.

Documentation

• Full documentation — install, guides, CLI reference
• Examples — step-by-step walkthroughs for common workflows

License

GNU Affero General Public License v3.0 (AGPL-3.0)

Links

• streamn.dad — project home
• Documentation — full docs
• @streamn_dad — highlights on Instagram
• YouTube — livestreams and highlights