ReelEel

Local-first, FOSS youth-sports video intelligence. Import a game, point at your kid, let ReelEel follow the action, review the suggested moments, and export a shareable highlight reel.

Soccer is the first supported sport. Everything runs on your machine: no account, no upload, no proprietary AI API, and CPU-only is a supported path, not a degraded one.

Product principle — ReelEel should make a cheap tripod and an ordinary camera feel like an automated youth-sports camera crew, without forcing families to upload their kids' footage to someone else's AI cloud.

---

Status

Area	State
Monorepo, storage, project model, jobs, sport plugins	working
CLI (reeleel) — full command surface	working
HTTP API (Hono)	working
Web app (Hono JSX SSR + client islands)	working
Moment scoring, Virtual Cameraman crop paths, FFmpeg render	working (needs tracks + FFmpeg installed)
Dataset export/import (COCO, YOLO, ReelEel JSON)	working
Detection + tracking (Python CV worker)	contract defined, not implemented (PRD phase 3)
Desktop packaging	scaffold (PRD phase 9)

Without the CV worker you can still create projects, import and probe footage, build proxies and thumbnails, mark moments yourself, trim and order clips, assemble reels and export MP4s. What you cannot do yet is have ReelEel find the moments for you.

Install

The reeleel command line, in one line:

curl -fsSL https://reeleel.com/install.sh | sh

It uses bun if you have it, otherwise npm (Node.js 22.5+), and installs into ~/.local rather than asking for sudo. Re-run it to upgrade. The package is @profullstack/reeleel if you would rather npm install -g it yourself. You still need FFmpeg (below).

Requirements

• Node.js 22.5+
• FFmpeg and ffprobe on your PATH (not bundled — see THIRD_PARTY_LICENSES.md)
• Bun 1.4+ (package manager and production runtime; vitest still uses Node)

Check everything at once:

reeleel doctor

Quick start

From a checkout, bun install && bun run build builds everything, then bun run cli <command> runs the CLI from source. With the CLI installed:

# 1. make a project
reeleel project create "Spring Cup QF" --sport soccer --opponent "Rivals"

# 2. bring in the footage (referenced in place, not copied)
reeleel import ~/Videos/spring-cup-qf.mp4

# 3. say who to follow
reeleel athlete add --name "Sam" --number 7 --focal

# 4. analyze, then review
reeleel analyze --preset fast
reeleel moments list
reeleel moments update 3 --include
reeleel moments update 5 --exclude

# 5. assemble and export
reeleel clips from-moments
reeleel reel create highlights --aspect 9:16
reeleel export --reel highlights

Full command reference: docs/cli.md.

The web UI covers the same review flow in a browser:

bun run --filter @reeleel/web dev # http://127.0.0.1:8788

Repository layout

apps/
  cli/        @profullstack/reeleel  the `reeleel` command (published to npm)
  api/        @reeleel/api      Hono HTTP API over the core services
  web/        @reeleel/web      Hono JSX SSR pages + client islands (SPA)
  desktop/    @reeleel/desktop  native shell (scaffold, phase 9)
packages/
  core/       @reeleel/core     project model, storage, FFmpeg, jobs, scoring, datasets
  db/         @reeleel/db       libSQL (projects) + Postgres (registry) clients, SQL migrations
  sports/     @reeleel/sports   sport plugins (soccer ships today)
workers/
  cv/         reeleel-cv        Python detection/tracking worker (contract only)
scripts/      db-migrate.mjs    standalone migration runner

Every app is a thin shell over @reeleel/core. That is the architectural rule that keeps the GUI and CLI honest about being the same product — logic that lands in an app instead of in core is logic the other surfaces silently lose.

A project is a folder

my-game/
├── project.json     portable manifest (human readable, diffable)
├── project.db       libSQL: jobs, detections, tracks, moments, clips…
├── source/          imported media (referenced in place by default)
├── proxies/         low-res editing proxies
├── thumbnails/      scrub thumbnails
├── analysis/        detector/tracker intermediates
├── annotations/     human corrections and dataset exports
├── clips/           rendered clip segments
├── models/          project-pinned model copies
└── exports/         finished reels

Copy the folder and everything travels with it. reeleel project import <dir> registers it on another machine.

Storage: local first, Postgres for the registry

Project databases are always local libSQL files. Syncing a family's game metadata to the cloud has to be a deliberate choice, never a default.

Only the machine-wide registry (which projects and models this install knows about, plus the accounts of a hosted deployment) can live on a server, in Postgres through @profullstack/libsql-pg:

export DATABASE_URL=postgres://user:pass@host:5432/reeleel
bun run db:migrate            # applies packages/db/migrations-pg/global

With no DATABASE_URL the registry is a plain local file and nothing touches the network. A server listening on a non-loopback host refuses to start without it, and anything other than a postgres:// URL is refused rather than falling back to a file. The old Turso setting (REELEEL_DB_URL) is refused with the copy recipe:

npx libsql-pg copy --from "$REELEEL_DB_URL" --token "$REELEEL_DB_AUTH_TOKEN" \
  --to "$DATABASE_URL" --verify

Migrations are forward-only .sql files under packages/db/migrations/, tracked in a schema_migrations table:

bun run db:migrate          # global database
bun run db:status           # show applied vs pending
bun run db:migrate --scope project --path ./my-game/project.db

以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗