FableCut: Instructions file for Claude Code

FableCut — browser video editor, drivable by Claude Code

A production-style non-linear video editor (Premiere-style) that runs in the browser. An AI agent edits videos by editing project.json (or calling the REST API / MCP tools) — the open browser UI live-reloads within ~150 ms via SSE. No build step, no npm dependencies.

This file is the master manual. Any model pointed at this document (or at the fablecut_docs MCP tool, which returns it) has everything needed to fully drive the editor.

MCP connection (preferred — works from any session, any directory)

Register the MCP server once at user scope as fablecut: claude mcp add -s user fablecut -- npx -y fablecut mcp (from npm, no path needed), or from a clone claude mcp add -s user fablecut -- node "<path-to>/fablecut/mcp-server.js". Every Claude Code session then has these tools:

• fablecut_status — auto-starts the editor server, returns URL + project summary. Call first.
• fablecut_docs — returns this document (section: "…" returns only matching ## sections).
• fablecut_get_project / fablecut_set_project — read / replace the timeline JSON. fablecut_get_project {compact:true} returns a one-line-per-clip summary instead.
• fablecut_patch_project — apply targeted ops (add/update/remove clip/media, set project fields, add and open sequences) without round-tripping the document. Prefer this for edits.
• fablecut_import_media — copy a local file (or download an https:// URL) into ./media/ and register it. The stored src is always /media/….
• fablecut_analyze_reference — turn a reference video into an edit blueprint (shots, beats, BPM, energy, drop) + extract its music. See "Remake a reference video".
• fablecut_frame — look at a moment and get back an actual image. {path, t} returns one frame of a source clip; {path, frames} returns a contact sheet across it; with no path, {time} renders the composed timeline. See "Look at the footage" below.
• fablecut_encode_profiles — list the delivery presets (YouTube, Shorts, Reels, TikTok, X, LinkedIn, Master, Broadcast, Web, Archive, saved ones) and the raw ffmpeg encoding profiles from encoding-profiles.json. {preset:"youtube"} returns one preset's spec. See "Export" below.
• fablecut_normalize_audio — measure clips (BS.1770 LUFS or sample peak, via ffmpeg) and set their clip gain to a loudness target. See "Audio mix" below.
• fablecut_auto_duck — find where the voice tracks speak and write duck keyframes that dip the music under it. See "Audio mix" below.
• fablecut_frame — see a moment. {path, t} → one JPEG frame of a source clip; {path, frames:12} → a contact sheet across it; {time} → the composed timeline, graded, as export renders it. Returns a real image, not numbers. See "Look at the footage" below.
• fablecut_denoise — reduce background noise on audio clips (renders a cleaned copy of the file and switches the clip's stems to it). See "Audio mix" below.
• fablecut_silence — find the pauses in speech and, with cut:true, cut them out (extract on the targeted tracks, stems in step). See "Audio mix" below.
• fablecut_beats — find a music clip's tempo, beat and drop; mark the beats, snap the cuts to them, or re-cut a track's clips on the beat. See "Audio mix" below.
• fablecut_reframe — reframe for another shape (9:16, 1:1, 4:5): a copy of the sequence on that canvas whose shots follow the subject. See "Sequences" below.
• fablecut_highlights — the best moments of long footage cut into a short edit, in a new sequence. See "Sequences" below.
• fablecut_transcribe — turn speech into words with times (Whisper, in the browser), read them on the timeline, find a phrase and cut it out. See "Transcripts and text-based editing" below.
• fablecut_captions — caption clips from the transcript, timed word by word (subtitle, karaoke, highlight, word pop); export or import SRT / WebVTT. See "Captions" below.
• fablecut_export — render the timeline to a file in exports/ with the editor's own Fast export (open tab, or headless Chrome / Edge). See "Export" below.
• fablecut_scopes — measure the graded picture at a moment (levels, clipping, colour cast), as the editor's scopes see it; also what a grade layer or a clip's masks select. See "Color" and "Masks" below.
• fablecut_track — motion tracking: follow a region of a video clip, store it as a track, and make a mask or another clip follow it. See "Tracking" below.
• fablecut_proxy — make, check or delete proxies: light copies of heavy footage the editor plays while editing (export always reads the originals). See "Media management" below.
• fablecut_projects — list, open, create (from a canvas or a saved template), duplicate, rename, annotate, archive and delete projects. ./project.json is always the open one. See "Projects" below.
• fablecut_versions — a project's saved versions: save one before big edits, compare a version with now, restore one (never destructive), mark the final cut. See "Versions" below.