From 79a1aac008ba5c740d97eeed36307954fd2cbd8f Mon Sep 17 00:00:00 2001 From: jremitz Date: Thu, 2 Apr 2026 09:38:50 -0500 Subject: [PATCH] docs: add examples directory, update README and Read the Docs for v0.0.35 Add 10 step-by-step example walkthroughs covering the full reeln workflow from install through smart zoom. Rewrite README to reflect current CLI state and prominently call out the ffmpeg dependency. Integrate examples into Read the Docs via include wrappers. Co-Authored-By: Claude --- .gitignore | 3 + CHANGELOG.md | 11 ++ README.md | 166 ++++++++++++-------- docs/conf.py | 4 + docs/examples/configuration.md | 5 + docs/examples/game-finish-and-cleanup.md | 5 + docs/examples/getting-started.md | 5 + docs/examples/highlights-and-reels.md | 5 + docs/examples/index.md | 19 +++ docs/examples/plugins.md | 5 + docs/examples/profiles-and-iterations.md | 5 + docs/examples/rendering-shorts.md | 5 + docs/examples/segments-and-events.md | 5 + docs/examples/smart-zoom.md | 5 + docs/examples/starting-a-game.md | 5 + docs/index.md | 23 ++- examples/01-getting-started.md | 160 +++++++++++++++++++ examples/02-configuration.md | 144 +++++++++++++++++ examples/03-starting-a-game.md | 128 +++++++++++++++ examples/04-segments-and-events.md | 137 ++++++++++++++++ examples/05-rendering-shorts.md | 173 +++++++++++++++++++++ examples/06-highlights-and-reels.md | 98 ++++++++++++ examples/07-profiles-and-iterations.md | 190 +++++++++++++++++++++++ examples/08-game-finish-and-cleanup.md | 100 ++++++++++++ examples/09-plugins.md | 141 +++++++++++++++++ examples/10-smart-zoom.md | 142 +++++++++++++++++ examples/README.md | 38 +++++ reeln/__init__.py | 2 +- 28 files changed, 1660 insertions(+), 69 deletions(-) create mode 100644 docs/examples/configuration.md create mode 100644 docs/examples/game-finish-and-cleanup.md create mode 100644 docs/examples/getting-started.md create mode 100644 docs/examples/highlights-and-reels.md create mode 100644 docs/examples/index.md create mode 100644 docs/examples/plugins.md create mode 100644 docs/examples/profiles-and-iterations.md create mode 100644 docs/examples/rendering-shorts.md create mode 100644 docs/examples/segments-and-events.md create mode 100644 docs/examples/smart-zoom.md create mode 100644 docs/examples/starting-a-game.md create mode 100644 examples/01-getting-started.md create mode 100644 examples/02-configuration.md create mode 100644 examples/03-starting-a-game.md create mode 100644 examples/04-segments-and-events.md create mode 100644 examples/05-rendering-shorts.md create mode 100644 examples/06-highlights-and-reels.md create mode 100644 examples/07-profiles-and-iterations.md create mode 100644 examples/08-game-finish-and-cleanup.md create mode 100644 examples/09-plugins.md create mode 100644 examples/10-smart-zoom.md create mode 100644 examples/README.md diff --git a/.gitignore b/.gitignore index f6338af..7213e0e 100644 --- a/.gitignore +++ b/.gitignore @@ -37,6 +37,9 @@ docs/_build/ CLAUDE.md AGENTS.md +# Video demo notes — presenter-only, not published +examples/_video-talking-points.md + # IDE .idea/ .vscode/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 0e17886..6591099 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/). +## [0.0.35] - 2026-04-02 + +### Added +- `examples/` directory with 10 step-by-step walkthrough pages covering install, OBS setup, game lifecycle, rendering, profiles, plugins, and smart zoom +- Examples integrated into Read the Docs via `docs/examples/` section +- Video demo talking points (gitignored, presenter-only) + +### Changed +- README.md rewritten: prominent ffmpeg dependency callout, updated CLI reference (removed stale "coming soon" section), added examples link +- Docs index updated with ffmpeg admonition, current feature list, and examples toctree entry + ## [0.0.34] - 2026-04-02 ### Added diff --git a/README.md b/README.md index 4da31b6..cb20cd8 100644 --- a/README.md +++ b/README.md @@ -12,38 +12,81 @@ reeln handles video manipulation, segment/highlight management, and media lifecycle — generic by default, sport-specific through configuration. Built by [Streamn Dad](https://streamn.dad). -## Features - -- **Game lifecycle management** — init, segment, highlights, finish -- **FFmpeg-powered video merging** — concat segments into highlight reels, no re-encoding -- **Sport-agnostic segment model** — hockey periods, basketball quarters, soccer halves, and more -- **Flexible configuration** — JSON config with XDG-compliant paths, env var overrides, named profiles -- **Pipeline debugging** — `--debug` flag captures ffmpeg commands, filter chains, and metadata for troubleshooting -- **Plugin-ready architecture** — lifecycle hooks, typed capability interfaces, and config schema declarations -- **Cross-platform** — macOS, Linux, Windows +## Requirements -## Quick start +- **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. +> +> ```bash +> # macOS +> brew install ffmpeg +> +> # Ubuntu / Debian +> sudo apt install ffmpeg +> +> # Windows +> winget install ffmpeg +> ``` + +## Install ```bash -# Install +# With pip pip install reeln -# Verify it works +# With uv (recommended) +uv tool install reeln +``` + +Verify everything is working: + +```bash reeln --version +reeln doctor # checks ffmpeg, codecs, config, permissions, plugins +``` -# View your configuration -reeln config show +## 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 +- **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 + +```bash # 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 ``` -More commands are being built — rendering and media management are on the roadmap. See the [CLI reference](#cli-reference) below for what's available and what's coming. +See the [examples](examples/) for detailed walkthroughs of every workflow. ## Supported sports -reeln adapts its directory structure and terminology to your sport: - | Sport | Segment name | Count | Example directories | |---|---|---|---| | hockey | period | 3 | `period-1/`, `period-2/`, `period-3/` | @@ -54,39 +97,56 @@ reeln adapts its directory structure and terminology to your sport: | lacrosse | quarter | 4 | `quarter-1/` through `quarter-4/` | | generic | segment | 1 | `segment-1/` | -Custom sports can be registered in your config file. - ## CLI reference -**Available now:** +### System | Command | Description | |---|---| -| `reeln --version` | Show version | -| `reeln --help` | Show help and available commands | -| `reeln config show` | Display current configuration | -| `reeln config doctor` | Validate config, warn on issues | -| `reeln game init` | Set up game directory with sport-specific segments | - -| `reeln plugins search` | Search the plugin registry | -| `reeln plugins info ` | Show detailed plugin information | -| `reeln plugins install ` | Install a plugin from the registry | -| `reeln plugins update [name]` | Update a plugin or all installed plugins | -| `reeln plugins list` | List installed plugins with version info | -| `reeln plugins enable ` | Enable a plugin | -| `reeln plugins disable ` | Disable a plugin | +| `reeln --version` | Show version and ffmpeg info | +| `reeln doctor` | Health check: ffmpeg, codecs, config, permissions, plugins | -**Coming soon** (command groups are registered, implementation in progress): +### Game lifecycle | Command | Description | |---|---| -| `reeln game segment ` | Move replays and merge segment highlights | +| `reeln game init` | Set up game directory with sport-specific segments | +| `reeln game segment ` | Collect replays and merge segment highlights | | `reeln game highlights` | Merge all segments into full-game highlight reel | -| `reeln game finish` | Finalize game, cleanup temp files | -| `reeln render short` | Render 9:16 short from clip | +| `reeln game compile` | Compile event clips by type, segment, or player | +| `reeln game finish` | Finalize game and show summary | +| `reeln game prune` | Remove generated artifacts | +| `reeln game event list` | List registered events | +| `reeln game event tag` | Tag an event with type, player, metadata | + +### Rendering + +| Command | Description | +|---|---| +| `reeln render short` | Render 9:16 or 1:1 short from clip | | `reeln render preview` | Fast low-res preview render | -| `reeln media prune` | Artifact cleanup (supports `--dry-run`) | -| `reeln doctor` | Health check: ffmpeg, config, permissions | +| `reeln render apply` | Apply a render profile (full-frame, no crop) | +| `reeln render reel` | Assemble rendered shorts into a reel | + +### Configuration + +| Command | Description | +|---|---| +| `reeln config show` | Display resolved configuration | +| `reeln config doctor` | Validate config and warn on issues | +| `reeln config event-types` | Manage event types | + +### Plugins + +| Command | Description | +|---|---| +| `reeln plugins search` | Search the plugin registry | +| `reeln plugins info ` | Show plugin details and config schema | +| `reeln plugins install ` | Install a plugin from the registry | +| `reeln plugins update [name]` | Update a plugin or all installed | +| `reeln plugins list` | List installed plugins | +| `reeln plugins enable ` | Enable a plugin | +| `reeln plugins disable ` | Disable a plugin | ## Configuration @@ -98,37 +158,13 @@ reeln uses a layered JSON config system: 4. **Environment variables** — `REELN_
_` ```bash -# Override any config value via env var -export REELN_VIDEO_FFMPEG_PATH=/opt/ffmpeg/bin/ffmpeg -export REELN_PATHS_OUTPUT_DIR=~/custom-output - -# View the resolved config reeln config show ``` -## Requirements - -- Python 3.11+ -- [ffmpeg 5.0+](https://ffmpeg.org/) - -## Installation - -```bash -# With pip -pip install reeln - -# With uv -uv tool install reeln - -# Development -git clone https://github.com/StreamnDad/reeln-cli.git -cd reeln-cli -make dev-install -``` - ## Documentation -Full documentation is available at [reeln-cli.readthedocs.io](https://reeln-cli.readthedocs.io). +- [Full documentation](https://reeln-cli.readthedocs.io) — install, guides, CLI reference +- [Examples](examples/) — step-by-step walkthroughs for common workflows ## License diff --git a/docs/conf.py b/docs/conf.py index ac38e41..65cf85c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -50,6 +50,10 @@ } exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +# Suppress warnings for relative links in included example files — these links +# work on GitHub (primary consumption) but can't resolve in the Sphinx build. +suppress_warnings = ["myst.xref_missing"] + # -- Intersphinx mapping ---------------------------------------------------- intersphinx_mapping = { diff --git a/docs/examples/configuration.md b/docs/examples/configuration.md new file mode 100644 index 0000000..974bc29 --- /dev/null +++ b/docs/examples/configuration.md @@ -0,0 +1,5 @@ +# Configuration & OBS Setup + +```{include} ../../examples/02-configuration.md +:start-line: 2 +``` diff --git a/docs/examples/game-finish-and-cleanup.md b/docs/examples/game-finish-and-cleanup.md new file mode 100644 index 0000000..a1bafeb --- /dev/null +++ b/docs/examples/game-finish-and-cleanup.md @@ -0,0 +1,5 @@ +# Game Finish & Cleanup + +```{include} ../../examples/08-game-finish-and-cleanup.md +:start-line: 2 +``` diff --git a/docs/examples/getting-started.md b/docs/examples/getting-started.md new file mode 100644 index 0000000..2c92f81 --- /dev/null +++ b/docs/examples/getting-started.md @@ -0,0 +1,5 @@ +# Getting Started + +```{include} ../../examples/01-getting-started.md +:start-line: 2 +``` diff --git a/docs/examples/highlights-and-reels.md b/docs/examples/highlights-and-reels.md new file mode 100644 index 0000000..1e14765 --- /dev/null +++ b/docs/examples/highlights-and-reels.md @@ -0,0 +1,5 @@ +# Highlights & Reels + +```{include} ../../examples/06-highlights-and-reels.md +:start-line: 2 +``` diff --git a/docs/examples/index.md b/docs/examples/index.md new file mode 100644 index 0000000..1fe72f6 --- /dev/null +++ b/docs/examples/index.md @@ -0,0 +1,19 @@ +# Examples + +Step-by-step walkthroughs for common reeln workflows. Each example is +self-contained — start from the top or jump to whatever fits your use case. + +```{toctree} +:maxdepth: 1 + +getting-started +configuration +starting-a-game +segments-and-events +rendering-shorts +highlights-and-reels +profiles-and-iterations +game-finish-and-cleanup +plugins +smart-zoom +``` diff --git a/docs/examples/plugins.md b/docs/examples/plugins.md new file mode 100644 index 0000000..756b066 --- /dev/null +++ b/docs/examples/plugins.md @@ -0,0 +1,5 @@ +# Plugins + +```{include} ../../examples/09-plugins.md +:start-line: 2 +``` diff --git a/docs/examples/profiles-and-iterations.md b/docs/examples/profiles-and-iterations.md new file mode 100644 index 0000000..45d7d36 --- /dev/null +++ b/docs/examples/profiles-and-iterations.md @@ -0,0 +1,5 @@ +# Profiles & Iterations + +```{include} ../../examples/07-profiles-and-iterations.md +:start-line: 2 +``` diff --git a/docs/examples/rendering-shorts.md b/docs/examples/rendering-shorts.md new file mode 100644 index 0000000..e899b2f --- /dev/null +++ b/docs/examples/rendering-shorts.md @@ -0,0 +1,5 @@ +# Rendering Shorts + +```{include} ../../examples/05-rendering-shorts.md +:start-line: 2 +``` diff --git a/docs/examples/segments-and-events.md b/docs/examples/segments-and-events.md new file mode 100644 index 0000000..2665add --- /dev/null +++ b/docs/examples/segments-and-events.md @@ -0,0 +1,5 @@ +# Segments & Events + +```{include} ../../examples/04-segments-and-events.md +:start-line: 2 +``` diff --git a/docs/examples/smart-zoom.md b/docs/examples/smart-zoom.md new file mode 100644 index 0000000..d02a191 --- /dev/null +++ b/docs/examples/smart-zoom.md @@ -0,0 +1,5 @@ +# Smart Zoom + +```{include} ../../examples/10-smart-zoom.md +:start-line: 2 +``` diff --git a/docs/examples/starting-a-game.md b/docs/examples/starting-a-game.md new file mode 100644 index 0000000..0b7df09 --- /dev/null +++ b/docs/examples/starting-a-game.md @@ -0,0 +1,5 @@ +# Starting a Game + +```{include} ../../examples/03-starting-a-game.md +:start-line: 2 +``` diff --git a/docs/index.md b/docs/index.md index b2183b1..759184e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,9 +9,18 @@ reeln handles video manipulation, segment/highlight management, and media lifecy - **FFmpeg foundation** — cross-platform ffmpeg discovery, version checking, probe helpers, deterministic command building - **Flexible configuration** — JSON config with XDG-compliant paths, env var overrides, named profiles - **Sport-agnostic segment model** — built-in support for 7 sports with custom sport registration -- **Game lifecycle management** — initialize game directories, process segments, merge highlights, finalize *(in progress)* -- **Short-form rendering** — crop, scale, and reframe clips into vertical/square formats with speed control, LUT grading, and subtitle overlays -- **Plugin-ready architecture** — lifecycle hooks and capability interfaces for future extensions +- **Game lifecycle management** — initialize game directories, process segments, merge highlights, tag events, finalize +- **Short-form rendering** — crop, scale, speed, LUT, overlays — landscape to vertical/square +- **Render profiles & iterations** — save and reuse render settings, chain them for multi-pass output +- **Smart zoom** — AI-powered tracking that follows the action (via plugin) +- **Player overlays** — roster-aware goal overlays with jersey number lookup +- **Plugin architecture** — lifecycle hooks for YouTube, Instagram, cloud uploads, and more +- **Cross-platform** — macOS, Linux, Windows + +:::{important} +reeln requires **ffmpeg 5.0+** installed on your system for all video processing. +See {doc}`install` for setup instructions, then run `reeln doctor` to verify. +::: ## Getting started @@ -46,6 +55,14 @@ cli/config cli/plugins ``` +## Examples + +```{toctree} +:maxdepth: 1 + +examples/index +``` + ## Project ```{toctree} diff --git a/examples/01-getting-started.md b/examples/01-getting-started.md new file mode 100644 index 0000000..07b5b0e --- /dev/null +++ b/examples/01-getting-started.md @@ -0,0 +1,160 @@ +# Getting Started + +This guide walks through setting up reeln from scratch on a fresh machine. +All commands work on macOS, Linux, and Windows. + +## 1. Open a terminal + +| Platform | How | +|----------|-----| +| macOS | Spotlight (`Cmd+Space`) → type "Terminal" → Enter | +| Windows | Start menu → "Terminal" or "PowerShell" | +| Linux | `Ctrl+Alt+T` (most distros) or find "Terminal" in your app launcher | + +## 2. Check Python + +reeln requires **Python 3.11 or later**. + +```bash +python3 --version +``` + +If you see `3.11.x` or higher, you're good — skip to [step 3](#3-install-ffmpeg). + +### Install or upgrade Python + +**Option A — Official installer** (all platforms): + +Download from [python.org/downloads](https://www.python.org/downloads/) and run +the installer. Make sure "Add Python to PATH" is checked on Windows. + +**Option B — Package manager:** + +```bash +# macOS (Homebrew) +brew install python@3.13 + +# Ubuntu / Debian +sudo apt update && sudo apt install python3.13 + +# Windows (winget) +winget install Python.Python.3.13 +``` + +**Option C — pyenv** (manage multiple versions): + +```bash +# Install pyenv (macOS/Linux) +curl https://pyenv.run | bash + +# Install Python +pyenv install 3.13 +pyenv global 3.13 +``` + +After installing, verify: + +```bash +python3 --version +# Python 3.13.x +``` + +## 3. Install ffmpeg + +reeln uses ffmpeg for all video processing. You need version **5.0 or later** +with these capabilities: + +- **libx264** — H.264 video encoding +- **aac** — audio encoding +- **libass** — subtitle/overlay rendering + +Most standard ffmpeg packages include all of these. + +```bash +# macOS +brew install ffmpeg + +# Ubuntu / Debian +sudo apt install ffmpeg + +# Windows +winget install ffmpeg +# or: choco install ffmpeg +``` + +Verify your install: + +```bash +ffmpeg -version +``` + +Look for the version number in the first line — it should be `5.x` or higher. + +## 4. Install reeln + +### With pip + +```bash +pip install reeln +``` + +### With uv (recommended) + +[uv](https://docs.astral.sh/uv/) is a fast Python package installer. If you +don't have it: + +```bash +# Install uv +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +Then install reeln as a tool: + +```bash +uv tool install reeln +``` + +### Verify + +```bash +reeln --version +``` + +This prints the reeln version and detected ffmpeg info. + +## 5. Run health checks + +```bash +reeln doctor +``` + +`doctor` checks everything reeln needs to run: + +- ffmpeg discovery and version +- Codec availability (libx264, aac, libass) +- Hardware acceleration support +- Config file validity +- Directory permissions +- Plugin health (if any are installed) + +Each check reports **PASS**, **WARN**, or **FAIL** with actionable hints. + +## 6. Set up shell completion (optional) + +```bash +# zsh (default on macOS) +reeln --install-completion zsh + +# bash +reeln --install-completion bash + +# fish +reeln --install-completion fish +``` + +Restart your shell after installing completion. + +## Next steps + +- [Configuration & OBS Setup](02-configuration.md) — connect reeln to your OBS replay buffer +- [Starting a Game](03-starting-a-game.md) — jump straight into a game workflow diff --git a/examples/02-configuration.md b/examples/02-configuration.md new file mode 100644 index 0000000..d27b000 --- /dev/null +++ b/examples/02-configuration.md @@ -0,0 +1,144 @@ +# Configuration & OBS Setup + +reeln uses a layered JSON config system. This guide covers initial setup and +connecting reeln to OBS for automatic replay collection. + +## View your config + +```bash +reeln config show +``` + +This displays the fully resolved configuration after merging: +bundled defaults → user config → environment variable overrides. + +## Config file location + +| Platform | Path | +|----------|------| +| macOS | `~/Library/Application Support/reeln/config.json` | +| Linux | `~/.config/reeln/config.json` | +| Windows | `%APPDATA%\reeln\config.json` | + +The file is created automatically with defaults on first run. Edit it directly +or override individual values with environment variables. + +## Connecting to OBS + +If you use OBS for livestreaming or recording, you likely have a **Replay Buffer** +that saves clips when you press a hotkey. reeln can automatically pick up those +clips. + +### 1. Find your OBS output directory + +In OBS: **Settings → Output → Recording → Recording Path** + +Common defaults: + +| Platform | Typical path | +|----------|-------------| +| macOS | `~/Movies` or `~/Videos/OBS` | +| Linux | `~/Videos` | +| Windows | `C:\Users\\Videos` | + +For the Replay Buffer specifically, check: +**Settings → Output → Replay Buffer** — the output path is usually the same +as your recording path. + +### 2. Configure reeln paths + +Edit your config file and set `source_dir` to your OBS output directory: + +```json +{ + "config_version": 1, + "sport": "hockey", + "paths": { + "source_dir": "~/Movies", + "source_glob": "Replay_*.mkv", + "output_dir": "~/Movies/games" + } +} +``` + +| Key | What it does | +|-----|-------------| +| `source_dir` | Directory where OBS saves replay clips | +| `source_glob` | Pattern to match replay files (default: `Replay_*.mkv`) | +| `output_dir` | Where reeln creates game directories and writes output | + +### 3. Match your replay file pattern + +OBS names replay files based on your settings. Check what pattern your replays +use and adjust `source_glob` to match: + +```json +"source_glob": "Replay_*.mkv" +``` + +Common patterns: +- `Replay_*.mkv` — OBS default with MKV container +- `Replay_*.mp4` — if you record to MP4 +- `*.mkv` — match all MKV files in the directory + +### 4. Verify the connection + +```bash +# Check config is valid +reeln config doctor + +# Show resolved paths +reeln config show +``` + +Now when you run `reeln game segment 1`, reeln will automatically find and +collect replay clips from your OBS output directory. + +## Environment variable overrides + +Any config value can be overridden with `REELN_
_`: + +```bash +export REELN_SPORT=hockey +export REELN_VIDEO_CRF=22 +export REELN_PATHS_SOURCE_DIR=~/Videos/OBS +``` + +This is useful for CI, automation, or per-session overrides without editing the +config file. + +## Named profiles + +Create alternate configs for different setups (e.g., tournament vs. league): + +```bash +# Default config +~/Library/Application Support/reeln/config.json + +# Tournament profile +~/Library/Application Support/reeln/config.tournament.json +``` + +Use a profile: + +```bash +reeln game init --sport hockey --home east --away west --profile tournament + +# Or set it for the whole session +export REELN_PROFILE=tournament +``` + +## Validate your setup + +```bash +# Full health check (ffmpeg, config, permissions, plugins) +reeln doctor + +# Config-only validation +reeln config doctor +``` + +## Next steps + +- [Starting a Game](03-starting-a-game.md) — initialize your first game workspace +- [Rendering Shorts](05-rendering-shorts.md) — render clips without a game context diff --git a/examples/03-starting-a-game.md b/examples/03-starting-a-game.md new file mode 100644 index 0000000..08a0097 --- /dev/null +++ b/examples/03-starting-a-game.md @@ -0,0 +1,128 @@ +# Starting a Game + +A "game" in reeln is a workspace directory that tracks segments, events, renders, +and game state. This guide covers creating one. + +## Initialize a game + +Provide the two team names and your sport: + +```bash +reeln game init roseville mahtomedi --sport hockey +``` + +This creates a game directory in your configured `output_dir` (or current +directory): + +``` +2026-04-02_roseville_vs_mahtomedi/ +├── game.json # game state and metadata +├── period-1/ # segment directories +├── period-2/ +└── period-3/ +``` + +The segment directories use sport-specific names: + +| Sport | Segments created | +|-------|-----------------| +| hockey | `period-1/` `period-2/` `period-3/` | +| basketball | `quarter-1/` `quarter-2/` `quarter-3/` `quarter-4/` | +| soccer | `half-1/` `half-2/` | +| football | `half-1/` `half-2/` | +| baseball | `inning-1/` through `inning-9/` | +| lacrosse | `quarter-1/` through `quarter-4/` | + +## Preview before creating + +Use `--dry-run` to see what would be created without writing anything: + +```bash +reeln game init roseville mahtomedi --sport hockey --dry-run +``` + +## Additional options + +```bash +reeln game init roseville mahtomedi \ + --sport hockey \ + --venue "Guidant John Rose Arena" \ + --game-time "7:00 PM" \ + --level 2016 \ + --tournament "Presidents Day Classic" \ + --description "Pool play round 1" +``` + +| Flag | Purpose | +|------|---------| +| `--venue` | Arena or field name | +| `--game-time` | Scheduled start time | +| `--level` | Competition level or birth year (loads team profiles) | +| `--tournament` | Tournament name | +| `--description` | Free-form game notes | +| `--date` | Override date (default: today) | +| `--output-dir` | Override where the game directory is created | + +## Interactive mode + +Run without arguments for guided prompts: + +```bash +reeln game init +``` + +This walks you through each field interactively. + +> **Note:** Interactive mode requires the `interactive` extra: +> `pip install reeln[interactive]` + +## Double-headers + +Running `game init` twice for the same teams on the same date automatically +creates a `_g2` suffix: + +```bash +reeln game init roseville mahtomedi --sport hockey +# Creates: 2026-04-02_roseville_vs_mahtomedi/ + +reeln game init roseville mahtomedi --sport hockey +# Creates: 2026-04-02_roseville_vs_mahtomedi_g2/ +``` + +## Team profiles + +When `--level` is provided, reeln looks up team profiles from your config +directory. Profiles store team metadata — name, abbreviation, colors, logo, +and roster — so you don't have to re-enter them for each game. + +```bash +reeln game init eagles bears --sport hockey --level bantam +``` + +Team profiles are stored at: + +``` +{config_dir}/teams/{level}/{team_slug}.json +``` + +See [Configuration](02-configuration.md) for config directory locations. + +## Other sports + +The same workflow applies to any supported sport: + +```bash +# Basketball +reeln game init lakers celtics --sport basketball + +# Soccer +reeln game init city united --sport soccer + +# Baseball +reeln game init twins yankees --sport baseball +``` + +## Next steps + +- [Segments & Events](04-segments-and-events.md) — process game segments and tag events +- [Rendering Shorts](05-rendering-shorts.md) — render clips into short-form video diff --git a/examples/04-segments-and-events.md b/examples/04-segments-and-events.md new file mode 100644 index 0000000..fa071df --- /dev/null +++ b/examples/04-segments-and-events.md @@ -0,0 +1,137 @@ +# Segments & Events + +After initializing a game, you process segments (periods, quarters, halves) and +tag events within them. This guide covers the full workflow. + +## Process a segment + +When a period ends, merge the replay clips for that segment: + +```bash +reeln game segment 1 +``` + +If you configured `paths.source_dir` (see [Configuration](02-configuration.md)), +reeln automatically finds matching replay files, moves them into the segment +directory, and merges them into a single highlight clip. + +If `source_dir` is not set, place your replay files in the segment directory +first (e.g., `period-1/`) and then run the command. + +The merged output is saved as: `period-1/period-1_2026-04-02.mkv` + +### Process all segments in a game + +```bash +reeln game segment 1 +reeln game segment 2 +reeln game segment 3 +``` + +### Preview without merging + +```bash +reeln game segment 1 --dry-run +``` + +## How merging works + +reeln uses ffmpeg to concatenate segment clips: + +- **Same container format** → stream copy (fast, no re-encoding) +- **Mixed containers** → re-encode to match (slower, ensures compatibility) + +## Events + +Each replay clip collected during segment processing is automatically registered +as an **event** in `game.json`. Events track clips, tags, and metadata throughout +the game lifecycle. + +### List events + +```bash +reeln game event list -o . +``` + +The `-o .` flag tells reeln where the game directory is. Use the path to your +game directory, or run from within it. + +Filter by segment or type: + +```bash +# Events in period 1 only +reeln game event list -o . --segment 1 + +# Only goal events +reeln game event list -o . --type goal + +# Untagged events +reeln game event list -o . --untagged +``` + +### Tag an event + +Add type, player, and metadata to an event: + +```bash +reeln game event tag abc123 --type goal --player "#17 Smith" +``` + +Add assists or other metadata: + +```bash +reeln game event tag abc123 \ + --type goal \ + --player "#17 Smith" \ + --meta "assists=#22 Jones, #5 Brown" +``` + +### Bulk-tag events + +Tag all events in a segment at once: + +```bash +reeln game event tag-all 1 --type goal +``` + +## Configure event types + +See what event types are available: + +```bash +# Show configured event types +reeln config event-types list + +# Show defaults for your sport +reeln config event-types defaults +``` + +Add or remove event types: + +```bash +reeln config event-types add save +reeln config event-types remove penalty +``` + +## Compile clips by criteria + +Combine raw event clips matching specific criteria into a single video: + +```bash +# All goals +reeln game compile --type goal -o . + +# All of one player's clips +reeln game compile --player "#17" -o . + +# Clips from period 2 +reeln game compile --segment 2 -o . + +# Preview without compiling +reeln game compile --type goal --dry-run -o . +``` + +## Next steps + +- [Rendering Shorts](05-rendering-shorts.md) — turn event clips into short-form video +- [Highlights & Reels](06-highlights-and-reels.md) — merge segments into a full-game reel diff --git a/examples/05-rendering-shorts.md b/examples/05-rendering-shorts.md new file mode 100644 index 0000000..bacf5ef --- /dev/null +++ b/examples/05-rendering-shorts.md @@ -0,0 +1,173 @@ +# Rendering Shorts + +reeln's render commands transform landscape clips into portrait (9:16) or square +(1:1) short-form video — ready for Instagram Reels, TikTok, YouTube Shorts, etc. + +## Basic render + +```bash +reeln render short clip.mkv +``` + +This produces a 1080x1920 vertical video using the default **pad** framing mode. + +If you have `paths.source_dir` configured, you can omit the clip path — reeln +auto-discovers the most recent replay: + +```bash +reeln render short +``` + +## Quick preview + +Generate a fast, low-resolution preview before committing to a full render: + +```bash +reeln render preview clip.mkv +``` + +Preview accepts all the same options as `render short`. + +## Framing modes + +### Pad (default) + +Scales the source to fit the width, then adds bars top and bottom. The full +frame is visible but letterboxed. + +```bash +reeln render short clip.mkv --crop pad +``` + +### Crop + +Scales the source to fill the height, then trims the sides. The frame is fully +filled but edges are lost. + +```bash +reeln render short clip.mkv --crop crop +``` + +### Anchor + +Control where the crop window is positioned: + +```bash +# Center (default) +reeln render short clip.mkv --crop crop --anchor center + +# Follow the left side of the frame +reeln render short clip.mkv --crop crop --anchor left + +# Custom position (x,y from 0.0 to 1.0) +reeln render short clip.mkv --crop crop --anchor 0.3,0.5 +``` + +## Output formats + +```bash +# Vertical — 1080x1920 (default) +reeln render short clip.mkv --format vertical + +# Square — 1080x1080 +reeln render short clip.mkv --format square + +# Custom size +reeln render short clip.mkv --size 720x1280 +``` + +## Speed + +```bash +# Half speed (slow motion) +reeln render short clip.mkv --speed 0.5 + +# Double speed +reeln render short clip.mkv --speed 2.0 +``` + +## Scale / zoom + +Zoom into the content before framing: + +```bash +# 1.5x zoom with crop — tighter on the action +reeln render short clip.mkv --crop crop --scale 1.5 + +# 2x zoom with pad — zoomed in, remaining space padded +reeln render short clip.mkv --crop pad --scale 2.0 +``` + +## Color grading + +Apply a LUT (Look-Up Table) for color grading: + +```bash +reeln render short clip.mkv --lut warm.cube +``` + +LUT files (`.cube` or `.3dl`) are standard color grading files supported by +most video tools. + +## Subtitle overlays + +Overlay an ASS subtitle file: + +```bash +reeln render short clip.mkv --subtitle overlay.ass +``` + +## Pad color + +Change the letterbox bar color (pad mode only): + +```bash +reeln render short clip.mkv --crop pad --pad-color "#1a1a1a" +``` + +## Combining options + +Options compose freely: + +```bash +reeln render short clip.mkv \ + --crop crop \ + --scale 1.3 \ + --speed 0.5 \ + --lut cinematic.cube \ + --format vertical +``` + +## Render within a game context + +When you provide a game directory, renders are tracked in `game.json`: + +```bash +reeln render short clip.mkv --game-dir . +reeln render short clip.mkv --game-dir . --event abc123 +``` + +## Dry run + +Preview the render plan without producing output: + +```bash +reeln render short clip.mkv --crop crop --speed 0.5 --dry-run +``` + +## Debug mode + +See the full ffmpeg command and filter chain: + +```bash +reeln render short clip.mkv --debug +``` + +This writes debug artifacts to `debug/` including the ffmpeg command, filter +graph, and input/output metadata. + +## Next steps + +- [Profiles & Iterations](07-profiles-and-iterations.md) — save render settings as reusable profiles +- [Highlights & Reels](06-highlights-and-reels.md) — combine rendered shorts into reels +- [Smart Zoom](10-smart-zoom.md) — AI-powered tracking that follows the action diff --git a/examples/06-highlights-and-reels.md b/examples/06-highlights-and-reels.md new file mode 100644 index 0000000..5c89e43 --- /dev/null +++ b/examples/06-highlights-and-reels.md @@ -0,0 +1,98 @@ +# Highlights & Reels + +After processing individual segments, reeln can merge them into a full-game +highlight reel or assemble rendered shorts into a compilation. + +## Full-game highlights + +Merge all processed segments into a single "story of the game" video: + +```bash +reeln game highlights +``` + +This concatenates all segment highlight clips in order. The output is placed in +the game directory: + +``` +2026-04-02_roseville_vs_mahtomedi/ +├── roseville_vs_mahtomedi_2026-04-02.mkv ← full-game highlights +├── period-1/ +│ └── period-1_2026-04-02.mkv ← segment highlight +├── period-2/ +│ └── period-2_2026-04-02.mkv +└── period-3/ + └── period-3_2026-04-02.mkv +``` + +### With iterations + +Apply render profiles to the highlights merge: + +```bash +# Apply a single profile +reeln game highlights --render-profile slowmo + +# Apply iteration profiles +reeln game highlights --iterate +``` + +### Preview first + +```bash +reeln game highlights --dry-run +``` + +## Assemble a reel from rendered shorts + +After rendering individual shorts, combine them into a compilation reel: + +```bash +reeln render reel --game-dir . +``` + +### Filter by segment or event type + +```bash +# Only period 1 renders +reeln render reel --game-dir . --segment 1 + +# Only goal renders +reeln render reel --game-dir . --event-type goal + +# Combine filters +reeln render reel --game-dir . --segment 2 --event-type goal +``` + +### Custom output path + +```bash +reeln render reel --game-dir . --output my_reel.mkv +``` + +## Typical end-of-game workflow + +```bash +# 1. Process all segments +reeln game segment 1 +reeln game segment 2 +reeln game segment 3 + +# 2. Merge into full-game highlights +reeln game highlights + +# 3. Render individual event shorts +reeln render short period-1/clip1.mkv --crop crop --speed 0.5 --game-dir . +reeln render short period-2/clip2.mkv --crop crop --speed 0.5 --game-dir . + +# 4. Assemble rendered shorts into a reel +reeln render reel --game-dir . + +# 5. Finish the game +reeln game finish +``` + +## Next steps + +- [Game Finish & Cleanup](08-game-finish-and-cleanup.md) — finalize and clean up +- [Profiles & Iterations](07-profiles-and-iterations.md) — automate render settings diff --git a/examples/07-profiles-and-iterations.md b/examples/07-profiles-and-iterations.md new file mode 100644 index 0000000..c6d6579 --- /dev/null +++ b/examples/07-profiles-and-iterations.md @@ -0,0 +1,190 @@ +# Profiles & Iterations + +Render profiles save reusable rendering settings. Iterations chain multiple +profiles together for multi-pass rendering from a single command. + +## Render profiles + +Add profiles to the `render_profiles` section of your config: + +```json +{ + "render_profiles": { + "fullspeed": { + "speed": 1.0 + }, + "slowmo": { + "speed": 0.5 + }, + "goal-overlay": { + "speed": 0.5, + "subtitle_template": "builtin:goal_overlay" + }, + "cinematic": { + "crop_mode": "crop", + "scale": 1.3, + "speed": 0.5, + "lut": "~/.config/reeln/luts/cinematic.cube", + "crf": 16 + } + } +} +``` + +### Use a profile + +```bash +reeln render short clip.mkv --render-profile slowmo +reeln render short clip.mkv --render-profile cinematic +``` + +### Available profile fields + +| Field | Type | Description | +|-------|------|-------------| +| `speed` | float | Playback speed (0.5 = half, 2.0 = double) | +| `speed_segments` | array | Variable speed timeline (see below) | +| `crop_mode` | string | `"pad"` or `"crop"` | +| `scale` | float | Zoom level (0.5–3.0) | +| `anchor_x` | float | Horizontal crop anchor (0.0–1.0) | +| `anchor_y` | float | Vertical crop anchor (0.0–1.0) | +| `pad_color` | string | Letterbox bar color | +| `lut` | string | Path to LUT file | +| `subtitle_template` | string | Path to `.ass` file or `builtin:` | +| `smart` | bool | Enable smart tracking | +| `codec` | string | Video codec override | +| `preset` | string | Encoder preset override | +| `crf` | int | Quality override | + +All fields are optional — omitted fields inherit from the base config or CLI flags. + +## Variable speed (speed segments) + +Create variable-speed effects within a single clip — normal speed for the +approach, slow motion for the action, back to normal: + +```json +{ + "render_profiles": { + "slowmo-middle": { + "speed_segments": [ + {"until": 5.0, "speed": 1.0}, + {"until": 8.0, "speed": 0.5}, + {"speed": 1.0} + ] + } + } +} +``` + +This plays: +1. First 5 seconds at normal speed +2. Seconds 5–8 at half speed +3. Remainder at normal speed + +Rules: +- At least 2 segments required +- The last segment must omit `until` (runs to end of clip) +- `until` values must be strictly increasing +- Speeds must be in the range 0.25–4.0 +- Cannot be combined with the scalar `speed` field + +Speed segments are config-only — there is no CLI flag. Use +`--render-profile ` to apply them. + +## Iterations + +Iterations run a single clip through multiple profiles and concatenate the +results into one output. Configure them in the `iterations` section: + +```json +{ + "iterations": { + "default": ["fullspeed"], + "goal": ["fullspeed", "slowmo", "goal-overlay"], + "save": ["slowmo"] + } +} +``` + +Activate with `--iterate`: + +```bash +reeln render short clip.mkv --iterate --game-dir . --event abc123 +``` + +reeln looks up the event type (e.g., "goal"), finds the matching profile list, +and runs the clip through each profile in sequence. The outputs are concatenated +into a single video. + +A goal event with `["fullspeed", "slowmo", "goal-overlay"]` produces: +1. Full-speed playback of the clip +2. Slow-motion replay +3. Slow-motion with goal overlay + +All stitched together automatically. + +### Iterations on game commands + +```bash +# Apply iterations after segment merge +reeln game segment 1 --iterate + +# Apply iterations after highlights merge +reeln game highlights --iterate +``` + +### Single profile vs. iterations + +`--render-profile` applies one profile. `--iterate` applies a sequence. +When both are provided, `--render-profile` takes precedence. + +## Full-frame rendering + +Apply profiles without cropping or scaling to the target aspect ratio: + +```bash +reeln render apply clip.mkv --render-profile slowmo +``` + +This applies speed, LUT, subtitle, and encoding settings but keeps the +original frame dimensions. + +## Builtin templates + +reeln ships with a `goal_overlay` template that renders a lower-third banner +with scorer name, assists, and team. Reference it with the `builtin:` prefix: + +```json +{ + "render_profiles": { + "player-overlay": { + "speed": 0.5, + "subtitle_template": "builtin:goal_overlay" + } + } +} +``` + +### Player overlays with roster lookup + +If you have team profiles with rosters configured (see +[Starting a Game](03-starting-a-game.md)), pass jersey numbers and reeln +resolves names automatically: + +```bash +reeln render short clip.mkv \ + --render-profile player-overlay \ + --player-numbers 17,22,5 \ + --event-type HOME_GOAL \ + --game-dir . +``` + +This looks up jersey numbers from the home team roster and fills in the overlay: +`#17 Smith` (scorer), assists `#22 Jones` and `#5 Brown`. + +## Next steps + +- [Rendering Shorts](05-rendering-shorts.md) — individual render options reference +- [Smart Zoom](10-smart-zoom.md) — AI tracking composes with profiles +- [Plugins](09-plugins.md) — extend rendering with plugins diff --git a/examples/08-game-finish-and-cleanup.md b/examples/08-game-finish-and-cleanup.md new file mode 100644 index 0000000..b4b595a --- /dev/null +++ b/examples/08-game-finish-and-cleanup.md @@ -0,0 +1,100 @@ +# Game Finish & Cleanup + +After processing all segments and rendering shorts, finalize the game and +optionally clean up generated artifacts. + +## Finish a game + +```bash +reeln game finish +``` + +This marks the game as finished in `game.json` and shows a summary: + +- Segments processed +- Events (tagged and untagged counts) +- Renders produced +- Highlight reel status + +### Preview before finishing + +```bash +reeln game finish --dry-run +``` + +### Specify the game directory + +```bash +reeln game finish -o ~/Movies/games/2026-04-02_roseville_vs_mahtomedi +``` + +## Clean up artifacts + +Remove generated files (merges, highlights, renders) while keeping raw event +clips: + +```bash +reeln game prune -o . +``` + +Also remove raw event clips: + +```bash +reeln game prune --all -o . +``` + +### Preview what would be deleted + +```bash +reeln game prune --dry-run -o . +``` + +> **Note:** Prune only works on finished games. Run `game finish` first. + +## Global cleanup + +Clean up all finished games in a directory: + +```bash +reeln media prune -o ~/Movies/games + +# Preview +reeln media prune --dry-run -o ~/Movies/games +``` + +## Complete game lifecycle + +Here's the full flow from start to finish: + +```bash +# 1. Initialize +reeln game init roseville mahtomedi --sport hockey + +# 2. Process segments as the game progresses +reeln game segment 1 +reeln game segment 2 +reeln game segment 3 + +# 3. Tag notable events +reeln game event tag abc123 --type goal --player "#17 Smith" + +# 4. Merge full-game highlights +reeln game highlights + +# 5. Render shorts for social media +reeln render short clip.mkv --crop crop --speed 0.5 --game-dir . + +# 6. Assemble a reel +reeln render reel --game-dir . + +# 7. Finish +reeln game finish + +# 8. Clean up when done +reeln game prune -o . +``` + +## Next steps + +- [Plugins](09-plugins.md) — automate uploads and metadata with plugins +- [Configuration](02-configuration.md) — customize paths and settings diff --git a/examples/09-plugins.md b/examples/09-plugins.md new file mode 100644 index 0000000..20f75c5 --- /dev/null +++ b/examples/09-plugins.md @@ -0,0 +1,141 @@ +# Plugins + +Plugins extend reeln with integrations for platforms like YouTube, Instagram, +and cloud storage — plus AI-powered features like smart zoom. + +## Browse the registry + +```bash +# List all available plugins +reeln plugins search + +# Search by keyword +reeln plugins search youtube +reeln plugins search upload + +# Get detailed info about a plugin +reeln plugins info google +``` + +## Available plugins + +| Plugin | Package | What it does | +|--------|---------|-------------| +| **google** | `reeln-plugin-google` | YouTube livestream creation, video uploads, playlists, comments | +| **meta** | `reeln-plugin-meta` | Facebook Live, Instagram Reels, Threads posting | +| **cloudflare** | `reeln-plugin-cloudflare` | R2 video uploads with CDN URL sharing | +| **openai** | `reeln-plugin-openai` | AI metadata generation, smart zoom via vision | +| **streamn-scoreboard** | `reeln-plugin-streamn-scoreboard` | OBS scoreboard text file bridge | + +## Install a plugin + +```bash +reeln plugins install google +``` + +This installs the package and enables the plugin. Plugin default settings are +automatically seeded into your config. + +### Preview before installing + +```bash +reeln plugins install google --dry-run +``` + +### Specify an installer + +```bash +# Use uv instead of pip +reeln plugins install google --installer uv +``` + +## List installed plugins + +```bash +reeln plugins list +``` + +Shows installed plugins with version info and enabled/disabled status. + +## Enable and disable + +```bash +reeln plugins disable google +reeln plugins enable google +``` + +## Update plugins + +```bash +# Update a specific plugin +reeln plugins update google + +# Update all installed plugins +reeln plugins update +``` + +## Configure a plugin + +Plugin settings live in your config file under `plugins.settings`: + +```json +{ + "plugins": { + "enabled": ["google", "openai"], + "settings": { + "google": { + "create_livestream": true, + "upload_highlights": true, + "playlist_id": "PLxxxxxxxx" + }, + "openai": { + "api_key": "sk-...", + "smart_zoom_enabled": true + } + } + } +} +``` + +Every plugin capability is **off by default** — you explicitly opt in to each +feature via config flags. + +### View a plugin's config schema + +```bash +reeln plugins info google +``` + +This shows all available settings, their types, defaults, and descriptions. + +## How plugins hook into the game lifecycle + +Plugins respond to lifecycle events. For example, with the google plugin +enabled and configured: + +```bash +reeln game init roseville mahtomedi --sport hockey +# → google plugin creates a YouTube livestream + +reeln game finish +# → google plugin updates the livestream status + +reeln game highlights +# → google plugin uploads the highlight reel +``` + +The same CLI commands — plugins add behavior without changing the interface. + +## Verify plugin health + +```bash +reeln doctor +``` + +After installing plugins, `doctor` includes plugin-specific health checks +alongside the standard ffmpeg and config checks. + +## Next steps + +- [Smart Zoom](10-smart-zoom.md) — AI-powered tracking (requires openai plugin) +- [Configuration](02-configuration.md) — plugin settings reference diff --git a/examples/10-smart-zoom.md b/examples/10-smart-zoom.md new file mode 100644 index 0000000..14f80c3 --- /dev/null +++ b/examples/10-smart-zoom.md @@ -0,0 +1,142 @@ +# Smart Zoom + +Smart zoom uses AI vision to track the action in your clips and dynamically +adjust the crop or pan position throughout the video. + +## Prerequisites + +Smart zoom requires a vision plugin. Install the OpenAI plugin: + +```bash +reeln plugins install openai +``` + +Configure it in your config file: + +```json +{ + "plugins": { + "enabled": ["openai"], + "settings": { + "openai": { + "api_key": "sk-...", + "smart_zoom_enabled": true, + "smart_zoom_model": "gpt-4o" + } + } + } +} +``` + +## Basic usage + +Add `--smart` to any render command: + +```bash +reeln render short clip.mkv --smart +``` + +## How it works + +1. reeln extracts frames from the clip (default: 5 keyframes) +2. The vision plugin analyzes each frame to find the action point +3. A zoom path is built from the detected positions +4. ffmpeg uses dynamic expressions to smoothly track the action + +## Smart + crop + +The crop window follows the action — both horizontally and vertically: + +```bash +reeln render short clip.mkv --crop crop --smart +``` + +## Smart + pad + +Pillarbox bars pan horizontally to center the action. Vertical position stays +fixed: + +```bash +reeln render short clip.mkv --crop pad --smart +``` + +## Control keyframe density + +More keyframes = smoother tracking but more API calls: + +```bash +# Fewer keyframes (faster, cheaper) +reeln render short clip.mkv --smart --zoom-frames 3 + +# More keyframes (smoother tracking) +reeln render short clip.mkv --smart --zoom-frames 15 +``` + +Default is 5 keyframes. Maximum is 20. + +## Combine with other options + +Smart zoom composes with all other render options: + +```bash +reeln render short clip.mkv \ + --crop crop \ + --smart \ + --speed 0.5 \ + --scale 1.3 \ + --lut cinematic.cube +``` + +## Debug mode + +See exactly what the AI detected and how the zoom path was built: + +```bash +reeln render short clip.mkv --smart --debug +``` + +This creates a `debug/zoom/` directory with: + +- `frame_NNNN.png` — extracted source frames +- `annotated_NNNN.png` — frames with crosshair and crop box overlay +- `zoom_path.json` — full zoom data and generated ffmpeg expressions + +## Smart zoom with profiles + +Enable smart tracking in a render profile: + +```json +{ + "render_profiles": { + "smart-crop": { + "crop_mode": "crop", + "smart": true, + "speed": 0.5 + } + } +} +``` + +```bash +reeln render short clip.mkv --render-profile smart-crop +``` + +## Smart zoom with iterations + +When `--smart` is used with `--iterate`, the vision analysis runs once and the +zoom path is reused (and remapped for speed changes) across all iterations: + +```bash +reeln render short clip.mkv --smart --iterate --game-dir . --event abc123 +``` + +## Without a vision plugin + +If you use `--smart` without a vision plugin installed, reeln falls back to +static center positioning and logs a warning. No error — just no tracking. + +## Next steps + +- [Rendering Shorts](05-rendering-shorts.md) — all render options reference +- [Profiles & Iterations](07-profiles-and-iterations.md) — save smart zoom settings in profiles +- [Plugins](09-plugins.md) — install and manage the OpenAI plugin diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..3783f79 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,38 @@ +# reeln Examples + +Step-by-step walkthroughs for common reeln workflows. Each example is +self-contained — start from the top or jump to whatever fits your use case. + +## Getting Started + +| # | Example | Description | +|---|---------|-------------| +| 01 | [Getting Started](01-getting-started.md) | Install Python, ffmpeg, and reeln from scratch | +| 02 | [Configuration & OBS Setup](02-configuration.md) | Configure reeln and connect it to your OBS replay buffer | + +## Game Workflow + +| # | Example | Description | +|---|---------|-------------| +| 03 | [Starting a Game](03-starting-a-game.md) | Initialize a game workspace with teams and sport | +| 04 | [Segments & Events](04-segments-and-events.md) | Process game segments and tag events | +| 05 | [Rendering Shorts](05-rendering-shorts.md) | Turn clips into vertical or square short-form video | +| 06 | [Highlights & Reels](06-highlights-and-reels.md) | Merge segments into highlight reels | +| 07 | [Profiles & Iterations](07-profiles-and-iterations.md) | Reusable render profiles and multi-pass rendering | +| 08 | [Game Finish & Cleanup](08-game-finish-and-cleanup.md) | Finalize games and clean up artifacts | + +## Plugins & Advanced + +| # | Example | Description | +|---|---------|-------------| +| 09 | [Plugins](09-plugins.md) | Discover, install, and manage plugins | +| 10 | [Smart Zoom](10-smart-zoom.md) | AI-powered tracking that follows the action | + +## Prerequisites + +- **Python 3.11+** — see [Getting Started](01-getting-started.md) for install options +- **ffmpeg 5.0+** — with libx264, aac, and libass support +- **reeln** — `pip install reeln` or `uv tool install reeln` + +If you're a livestreamer using OBS, start with [Configuration & OBS Setup](02-configuration.md) +to connect reeln to your replay buffer output. diff --git a/reeln/__init__.py b/reeln/__init__.py index 6c75c49..eadb412 100644 --- a/reeln/__init__.py +++ b/reeln/__init__.py @@ -2,4 +2,4 @@ from __future__ import annotations -__version__ = "0.0.34" +__version__ = "0.0.35"