CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.0.39] - 2026-04-24

Added

• reeln init command — guided first-time setup with interactive sport selection, directory configuration, and config creation
• Non-interactive mode: reeln init --sport hockey --source-dir ~/replays --output-dir ~/games

Fixed

• Plugin install/uninstall now finds uv in common paths (~/.local/bin, ~/.cargo/bin, /opt/homebrew/bin) when shell PATH is minimal (fixes "No module named pip" in Tauri/GUI apps)

[0.0.38] - 2026-04-07

Added

• reeln queue command group for staged render-then-publish workflow: list, show, edit, publish, publish-all, remove, targets
• --queue / -q flag on render short and render apply — renders but queues for review instead of publishing immediately
• Per-target publish tracking — publish to YouTube, review, then selectively push to Instagram/TikTok without re-rendering
• ON_QUEUE and ON_PUBLISH lifecycle hooks for plugin integration with the queue workflow
• Centralized metadata generation (core/metadata.py) — auto-generates title and description from game/event context
• QueueItem stores config profile name — queue publish loads the same plugin settings used at queue time
• Queue persistence via render_queue.json (per-game directory) with advisory central index for cross-game listing
• QueueError exception class for queue operation errors
• Team logo overlay on goal shorts — resolves logo from TeamProfile.logo_path, scales to 80% of box height, right-aligned with text clipping. Supports all four filter chain paths (simple pad/crop, smart pad, speed segments, speed segments + smart pad)
• reeln plugins auth command — test authentication for plugins (--json for machine output, --refresh to force reauthentication)
• reeln plugins uninstall command — uninstall a plugin and remove from config (--force to skip confirmation, --dry-run to preview)
• Authenticator capability protocol — plugins implement auth_check() and auth_refresh() for credential verification and token renewal
• AuthCheckResult, AuthStatus, PluginAuthReport models (reeln/models/auth.py) for structured auth status reporting

[0.0.37] - 2026-04-03

Added

• reeln game list — list games in output directory with status badges (finished/in progress)
• reeln game info — show detailed game information (teams, venue, progress, livestreams)
• reeln game delete — delete a game directory with confirmation prompt (--force to skip)
• Colored CLI output: --version, plugins list, plugins search, plugins info, plugins inputs, game list, game info, game delete all use consistent styled output (bold names, green/red/yellow badges, dim labels)
• Shared reeln.commands.style module for consistent CLI formatting
• Plugin Input Contributions: plugins declare additional user inputs via input_schema class attribute (PluginInputSchema, InputField)
• --plugin-input KEY=VALUE (-I) repeatable option on game init, render short, and render preview
• Interactive prompts for plugin-contributed inputs (questionary-based, preset-first pattern)
• Conditional prompting: thumbnail and tournament only prompted when a plugin declares them
• InputCollector with conflict resolution (same-type dedup, cross-type namespacing)
• get_input_schema() method support: plugins can conditionally declare inputs based on feature flags (e.g., only prompt for thumbnail when create_livestream is enabled)
• Registry fallback: plugins without input_schema / get_input_schema() get inputs from ui_contributions.input_fields in registry JSON
• reeln plugins inputs introspection command (text + JSON output for reeln-dock)
• input_contributions field on RegistryEntry model, parsed from ui_contributions.input_fields
• Google plugin registry entry updated with thumbnail_image input field for game_init

Changed

• init_game() accepts plugin_inputs kwarg, included in ON_GAME_INIT / ON_GAME_READY hook data
• PRE_RENDER / POST_RENDER hook data includes plugin_inputs when present
• activate_plugins() now registers plugin input schemas with the InputCollector singleton
• game init checks for unfinished games before interactive prompts (fail fast instead of prompting then failing)
• _resolve_game_dir now sorts by created_at from game.json instead of filesystem mtime (which is unreliable due to Spotlight/Time Machine)
• _resolve_game_dir prefers unfinished games over finished ones, so reeln game finish finds the right game

[0.0.36] - 2026-04-02

Fixed

• Read the Docs example page links now navigate correctly (renamed wrapper files to match example filenames)

[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

• reeln hooks run and reeln hooks list CLI commands for non-interactive hook execution (JSON-in/JSON-out, designed for reeln-dock integration)
• reeln-native v0.2.0 as a required dependency (Rust-powered acceleration)
• native-dev and plugins Makefile targets for local development

Changed

• Goal overlay layout: dynamic box height when assists are present, adjusted assist Y-coordinates for better spacing
• probe_duration() now accepts single-arg form with auto-discovery (probe_duration(path))
• Overlay template documentation now covers ASS templates only (JSON templates deferred to native migration)

Removed

• Dead PNG overlay pipeline (ResolvedOverlay, resolve_overlay_for_profile, composite_video_overlay) — unreachable code from incomplete JSON template integration
• goal_overlay.json template (nothing loaded it)
• Shell completion Makefile targets (replaced by symlink install)

[0.0.33] - 2026-03-23

Added

• Branding overlay on rendered shorts: shows "reeln v{version} by https://streamn.dad" with a black-bordered white text at the top of the video for the first ~5 seconds with a smooth fade-out — enabled by default, configurable via branding config section, disable with --no-branding CLI flag
• BrandingConfig model (enabled, template, duration) for per-user branding customization
• Bundled branding.ass ASS template with \fad(300,800) animation and black outline for visibility over any background
• --no-branding flag on render short and render preview commands
• Branding renders only on the first iteration in multi-iteration mode
• Cross-fade transitions between iterations: uses ffmpeg xfade + acrossfade filters for smooth 0.5s fade transitions instead of hard cuts, with automatic fallback to concat demuxer if xfade fails
• Smart zoom support in the iteration pipeline: --smart --iterate now extracts frames once upfront and passes the zoom path through to each iteration's plan_short() call
• speed_segments in render profiles for variable speed within a single clip — e.g., normal speed → slow motion → normal speed, using the proven split/trim/concat ffmpeg pattern
• --player-numbers (-n) flag on render short, render preview, and render apply for roster-based player lookup: accepts comma-separated jersey numbers (e.g., --player-numbers 48,24,2), looks up names from the team roster CSV, and populates goal scorer and assist overlays automatically
• --event-type flag on render commands for scoring team resolution: HOME_GOAL/AWAY_GOAL determines which team's roster to look up
• RosterEntry data model and load_roster() / lookup_players() / resolve_scoring_team() core functions for roster management
• GameInfo now persists level, home_slug, and away_slug when game init --level is used, enabling roster lookup during rendering
• build_overlay_context() accepts optional scoring_team parameter to override the default (home team)
• Smart target zoom (--crop smart): extracts frames from clips, emits ON_FRAMES_EXTRACTED hook for vision plugins (e.g. reeln-plugin-openai) to detect action targets, then builds dynamic ffmpeg crop expressions that smoothly pan across detected targets
• ZoomPoint, ZoomPath, and ExtractedFrames data models for smart zoom contracts
• ON_FRAMES_EXTRACTED lifecycle hook for plugins to analyze extracted video frames
• extract_frames() method on the Renderer protocol and FFmpegRenderer for frame extraction
• build_piecewise_lerp() and build_smart_crop_filter() for dynamic ffmpeg crop expressions
• --zoom-frames option on render short and render preview (default 5, range 1-20)
• Zoom debug output: debug/zoom/zoom_path.json and frame symlinks when --debug is used with smart crop
• Smart pad mode (--crop smart_pad): follows action vertically like smart zoom but keeps black bars instead of filling the entire frame — falls back to static pad when no vision plugin provides data
• build_smart_pad_filter() for dynamic vertical pad positioning based on zoom path center_y
• Debug crosshair annotations: extracted frames in debug/zoom/ now include annotated copies with green crop box and red crosshair overlays showing detected center points
• --scale option on render short and render preview (0.5-3.0, default 1.0): zooms in by scaling up the intermediate frame before crop/pad — works with all crop modes including smart tracking
• --smart flag on render short and render preview: enables smart tracking via vision plugin as an orthogonal option, composable with --crop pad|crop and --scale
• build_overflow_crop_filter() for pad + scale > 1.0: crops overflow after scale-up before padding
• Automatic fallback from smart crop to center crop (or smart_pad to static pad) when no vision plugin provides zoom data
• --no-enforce-hooks global CLI flag to temporarily disable registry-based hook enforcement for plugins
• game finish now relocates segment and highlights outputs from the shared output directory into game_dir/outputs/, preventing file collisions across multiple games per day
• game init now blocks with a clear error if an unfinished game exists — run reeln game finish first
• GameState tracks segment_outputs and highlights_output for file relocation
• find_unfinished_games() helper scans for active game directories
• relocate_outputs() helper moves output files into the game directory
• reeln doctor now collects and runs health checks from plugins that implement doctor_checks()
• doctor capability added to plugin duck-type detection
• --tournament CLI flag on game init for optional tournament name/context — flows through to plugins via hook context and overlay templates
• tournament and level fields now included in template context (build_base_context()), available as {{tournament}} and {{level}} in ASS subtitle templates

Changed

• Scale, framing (crop/pad), and smart tracking are now orthogonal axes — any combination works without dedicated enum values
• Short/preview renders now output to a shorts/ subdirectory by default (e.g., period-2/shorts/clip_short.mp4) to prevent segment merges from picking up rendered files

Deprecated

• --crop smart — use --crop crop --smart instead (still works, shows deprecation warning)
• --crop smart_pad — use --crop pad --smart instead (still works, shows deprecation warning)

Fixed

• team_level in overlay context now uses the actual team level (e.g., "2016", "bantam") instead of the sport name — previously showed "hockey" instead of the level
• Segment merge and highlights merge output extension now matches input files instead of being hardcoded to .mkv
• Highlights merge now discovers segment files with any video extension (.mp4, .mkv, .mov, etc.), not just .mkv

[0.0.32] - 2026-03-15

Fixed

• --profile now resolves relative to the active config directory (parent of REELN_CONFIG) instead of the platform default, so profiles stored alongside a custom config file are found correctly
• --profile and --path CLI arguments now take strict priority over REELN_CONFIG and REELN_PROFILE environment variables

[0.0.31] - 2026-03-13

Added

• ON_POST_GAME_FINISH hook — fires after ON_GAME_FINISH with shared context, enabling cross-plugin data consumption at game finish (mirrors ON_GAME_INIT → ON_GAME_READY pattern)
• --log-level CLI option and REELN_LOG_LEVEL env var to control log verbosity (default: WARNING)
• enforce_hooks plugin config option — restricts plugins to hooks declared in the registry; set false for local plugin development
• Registry capability enforcement — plugins can only register hooks declared in their registry/plugins.json entry

Fixed

• Explicit --profile or --path to a nonexistent config file now fails immediately instead of silently using defaults

Changed

• Default log level changed from INFO to WARNING (reduces noise during normal operation)

[0.0.30] - 2026-03-11

Added

• ON_GAME_READY hook — fires after ON_GAME_INIT with shared context, enabling cross-plugin data consumption (e.g. OpenAI generates thumbnail during init, Google updates livestream during ready)
• config show now displays the full resolved configuration including all default values and plugin schema defaults
• Plugin registry entries for meta (Facebook Live/Instagram/Threads) and openai (LLM-powered metadata/thumbnails/translation)

Fixed

• PyPI Documentation link now points to correct URL (reeln-cli.readthedocs.io)

Changed

• Plugins that are not installed log at debug level instead of warning with traceback

[0.0.29] - 2026-03-06

Added

• --version / -V flag on reeln plugins install and reeln plugins update to pin a specific version (git tag or PyPI release)
• Logo on Read the Docs site (sidebar and favicon)

[0.0.28] - 2026-03-04

Added

• --description / -d flag on game init for broadcast description
• --thumbnail flag on game init for thumbnail image path
• GameInfo.description and GameInfo.thumbnail fields
• Interactive prompts for description and thumbnail (both optional)

[0.0.27] - 2026-03-04

Fixed

• PyPI logo: restore absolute URL for README image (lost during merge)

[0.0.26] - 2026-03-04

Added

• HookContext.shared dict for plugins to pass data back (e.g. livestream URLs)
• GameState.livestreams field — persists livestream URLs written by hook plugins
• resolve_config_path() — extracted config path resolution for reuse

Fixed

• Plugin install now uses git+{homepage} for GitHub/GitLab plugins instead of PyPI lookup
• Post-install verification catches silent uv pip install no-ops
• save_config() now respects REELN_CONFIG / REELN_PROFILE env vars (previously always wrote to default path)
• detect_installer() passes --python sys.executable to uv so plugins install into the correct environment
• Hardcoded version strings removed from tests (use __version__ dynamically)

[0.0.25] - 2026-03-04

Fixed

• Logo image on PyPI (use absolute URL for assets/logo.jpg)
• Add project URLs to PyPI sidebar (Homepage, Docs, Repo, Changelog, Issues)

[0.0.24] - 2026-03-04

Fixed

• Registry URL casing — raw.githubusercontent.com is case-sensitive (StreamnDad not streamn-dad)
• mypy errors in prompts.py (renamed shadowed variables)
• CI workflows use uv sync instead of uv pip install --system (PEP 668)
• Plugin registry: correct homepage URL and metadata for streamn-scoreboard

[0.0.23] - 2026-03-03

First feature-complete release of reeln — platform-agnostic CLI toolkit for livestreamers.

Added

CLI Commands

• reeln --version — show version, ffmpeg info, and installed plugin versions
• reeln doctor — comprehensive health check: ffmpeg, codecs, hardware acceleration, config, permissions
• reeln config show — display current configuration as JSON
• reeln config doctor — validate config, warn on issues
• reeln game init — initialize game workspace with sport-specific segment subdirectories
• reeln game segment <N> — merge replays in a segment directory into a highlight video
• reeln game highlights — merge all segment highlights into a full-game highlight reel
• reeln game finish — mark a game as finished with summary
• reeln game prune — remove generated artifacts from a finished game directory
• reeln game event list — list events with filters (--segment, --type, --untagged)
• reeln game event tag — tag an event with type, player, and metadata
• reeln game event tag-all — bulk-tag all events in a segment
• reeln game compile — compile raw event clips into a single video by criteria
• reeln render short — render a 9:16 short from a clip
• reeln render preview — fast low-res preview render
• reeln render apply — apply a named render profile to a clip (full-frame, no crop/scale)
• reeln render reel — assemble rendered shorts into a concatenated reel
• reeln media prune — scan and prune all finished game directories
• reeln plugins list — list installed plugins with version info
• reeln plugins search — search the plugin registry
• reeln plugins info <name> — show detailed plugin information
• reeln plugins install <name> — install a plugin from the registry with auto-enable
• reeln plugins update [name] — update a plugin or all installed plugins
• reeln plugins enable <name> / reeln plugins disable <name> — enable/disable plugins

Core Features

• Package skeleton: pyproject.toml, Makefile, .coveragerc, pytest.ini, python -m reeln support
• Structured logging module with JSON and human formatters
• Error hierarchy: ReelnError base with typed subclasses
• FFmpeg discovery with cross-platform support (PATH, brew, apt, choco), version checking (5.0+ minimum)
• Media probe helpers: duration, fps, resolution via ffprobe
• Deterministic ffmpeg command builders (concat, render) with golden test assertions
• FFmpegRenderer implementation with render() and preview() methods
• Config system: JSON loading, schema validation, config_version, XDG-compliant paths, env var overrides (REELN_<SECTION>_<KEY>), deep merge, atomic writes, named profiles
• Segment model: generic time division abstraction with sport alias registry (hockey, basketball, soccer, football, baseball, lacrosse, generic) and custom sport registration
• Game lifecycle: GameInfo, GameState, GameEvent models with JSON serialization, double-header auto-detection, game.json state tracking
• GameEvent model for first-class event tracking with UUID-based IDs, prefix matching, extensible metadata, and idempotent creation
• Render state tracking in game.json via RenderEntry with event auto-linking
• ShortConfig model with crop modes (pad, crop), output formats (vertical, square), anchor positions
• Filter graph builders: scale, pad, crop, speed, LUT, subtitle — composable and golden-tested
• Render profiles: named configuration sets for reusable rendering parameter overrides (speed, LUT, subtitle template, encoding)
• Multi-iteration rendering: run a clip through N render profiles sequentially and concatenate results
• Template engine: {{key}} placeholder substitution for .ass subtitle files
• TemplateContext, TemplateProvider protocol, build_base_context() for game/event context
• ASS subtitle helpers: rgb_to_ass(), format_ass_time()
• Bundled goal_overlay ASS subtitle template with dynamic font sizing and team-colored background
• builtin: prefix for subtitle_template in render profiles (e.g. "builtin:goal_overlay")
• build_overlay_context() for computing overlay-specific template variables from event metadata
• --player and --assists CLI flags on render short, render preview, and render apply — populate overlay template variables without game event tagging; override event data when both are present
• Default player-overlay render profile and goal iteration mapping in bundled config
• TeamProfile model with metadata (logo, roster, colors, jersey colors, period length)
• Team profile management: load, save, list, delete with atomic writes
• Interactive team selection and game time prompting in game init
• --game-time, --level, --period-length, --venue options on game init
• --debug flag on game and render commands — writes pipeline debug artifacts with ffmpeg commands, filter chains, and metadata
• HTML debug index (debug/index.html) with summary table and per-operation sections
• --dry-run support across all destructive and render commands
• PruneResult model, format_bytes(), find_game_dirs() helpers
• CompilationResult model for compilation output tracking
• questionary as optional dependency (pip install reeln[interactive])

Plugin System

• Plugin system foundation: lifecycle hooks, capability protocols, hook registry
• Hook enum with 11 lifecycle hooks: PRE_RENDER, POST_RENDER, ON_CLIP_AVAILABLE, ON_EVENT_CREATED, ON_EVENT_TAGGED, ON_GAME_INIT, ON_GAME_FINISH, ON_HIGHLIGHTS_MERGED, ON_ERROR, ON_SEGMENT_START, ON_SEGMENT_COMPLETE
• HookRegistry with safe emission — handler exceptions are caught and logged
• Capability protocols: Uploader, MetadataEnricher, Notifier, Generator
• Plugin orchestrator: sequential pipeline (Generator -> MetadataEnricher -> Uploader -> Notifier)
• Plugin loader: discover_plugins(), load_plugin(), load_enabled_plugins(), activate_plugins()
• Plugin config schema declaration with ConfigField and PluginConfigSchema
• Remote plugin registry with cache, search, install, update, and auto-enable
• author and license fields on plugin registry entries
• ThrottledReader for upload throughput limiting, upload_lock() for serialization
• filelock>=3.0 dependency

CI/CD & Docs

• GitHub Actions CI workflow (Python 3.11/3.12/3.13 matrix, lint, type check, tests, docs build)
• GitHub Actions release workflow (tag-based PyPI publish via trusted publisher)
• CI and docs badges in README
• Documentation infrastructure: Sphinx + MyST, Furo theme, Read the Docs config
• Full docs site: install guide, quickstart tutorial, CLI reference, configuration guide, sports guide

Fixed

• render short --render-profile now correctly resolves subtitle_template from the profile — previously the template was silently dropped in the single-profile path

Changed

• --rink CLI flag renamed to --venue for sport-agnostic terminology
• Segment merge and highlights merge output written to paths.output_dir for discoverability
• period_length moved from TeamProfile to GameInfo
• Full test suite with 100% line + branch coverage