Appearance
ADR 0011: Clipper: a downloadable clipping app that connects to the web server by API key
- Status: Accepted
- Date: 2026-11-20
- Spec version: 1.1.0
Context
Editors turn long raw footage (streams, gameplay, interviews) into many short vertical clips. Opus Pro does this as a service; Clips Kitty (AGPL) and Reroot's ingest do parts of it locally. We want editors to have a tool of that quality, usable on their own machine with and without the internet, that is tied to our web app so we can see who uses it, what it costs and what it produced. A Cloudflare Worker cannot run ffmpeg or hold a 20 GB file, and uploading raw footage to it is neither cheap nor necessary.
Decision
- Two halves.
apps/clipperis a single executable (Bun--compile) with a command line and a local studio in the browser. It runs ffmpeg and whisper.cpp on the editor's machine and renders the clips there.packages/clipperis the engine behind it. The server half ispackages/api/src/clipperand the/clipper/v1routes. - Offline and online are the same pipeline with different backends. Offline: whisper.cpp transcribes, the signal fusion and a heuristic score pick the moments, templates write titles. Online (a valid API key and a reachable server): compressed audio goes to the server for transcription, candidate windows with their transcript and signals go to the server for model scoring, and titles, descriptions and hashtags are written by the model. Any online step that fails falls back to its offline twin and says so; nothing is silently skipped.
- Video never leaves the machine. The server receives audio (about 3 MB for 20 minutes), transcript text, numbers and clip metadata.
- Authentication is a Better Auth API key (
@better-auth/api-key, prefixsgc_,x-api-keyheader). Owners, managers, editors and videographers create keys in the web app; one key per person or machine. Keys have an expiry, are revocable, and carry the plugin's rate limit. Monthly quotas are settings (clipper.*). - Every AI request is metered.
clipper_usagestores one row per call (who, which key and machine, kind, provider, model, units, latency, status). Key creation and revocation go toaudit_log; what the app reports (exports, renders, errors) goes toclipper_event. The owner sees usage, latency, errors, clients and audit in the web app. - Organisation of output. Every project writes
clips/<category>/NN-title.mp4, a thumbnail, subtitles, a per-clip JSON, amanifest.jsonand anupload-queue.csv/upload.jsonwith the title, description and hashtags per platform. Metadata also syncs to the library in the web app. - Clean-room. Clips Kitty is AGPL-3.0. Its design (signal fusion, windowed scoring, rerank, word-synced captions) informed ours; no code was copied.
Consequences
- Heavy processing is on the editor's machine, so a slow laptop means slow renders. A server-side render worker can run the same engine later; it is not built.
- Production needs a transcription backend (Cloudflare Workers AI binding
AI, or an OpenAI-compatible key) andANTHROPIC_API_KEYfor scoring. Without themfeatures.transcribe/features.scoreare false and the app stays offline-capable. - The executable needs ffmpeg and a whisper model.
clipper doctorchecks,clipper setupdownloads the model. - Releases are built per platform and served from R2 through the web app.
Revisit when
Editors need clips rendered without a capable machine (server-side render worker), or per-client billing of AI usage is wanted (the usage rows already carry the cost drivers).