fablecut 1.14.0 → 1.15.0

package/CLAUDE.md

@@ -26,12 +26,22 @@ Every Claude Code session then has these tools:
   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_encode_profiles` — list export presets from `encoding-profiles.json` (each is a
-  raw ffmpeg args list). Set `project.encodeProfile` via patch to pin a project default.
+- `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_export` — render the timeline to a file in `exports/` with the editor's own
@@ -41,6 +51,9 @@ Every Claude Code session then has these tools:
   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.
 
 ### Token-efficient editing (important for agents)
 
@@ -59,8 +72,12 @@ Editing via full get→modify→set costs thousands of tokens per change. Cheape
    Re-check the clips, then retry with that revision.
 3. **Docs**: request `fablecut_docs {section:"schema"}` (or "Recipes", "Remake", …)
    instead of the whole manual; skip it entirely if the schema is already in context.
-4. **Media questions** (duration, fps, size): read them from the registered media
-   entries — don't shell out to ffprobe; the browser probes and writes them back.
+4. **Media questions** (duration, resolution, fps, codec, audio channels, file
+   size, how often it is used): read them from the registered media entries or
+   the compact view's MEDIA lines — don't shell out to ffprobe; the editor
+   probes every file and writes them back (see "Media management").
+   For what the footage *looks like*, use `fablecut_frame` — it is far cheaper
+   than reading a file, and far more reliable than inferring from a number.
 5. Batch related changes into ONE patch call (ops apply in order, one revision bump).
 6. **Cut and trim with the edit ops** (next section) rather than recomputing
    `start` / `in` / `duration` by hand — they keep linked stems in sync.
@@ -133,6 +150,9 @@ reports the real paths.
 Tests (and nothing else) may set **`FABLECUT_NO_FS_WATCH=1`** to skip `fs.watch`.
 On Windows, libuv can abort the process when a file is created under a temp
 data dir. Production leaves watching on so the UI live-reloads.
+Tests may also set **`FABLECUT_NO_AUTOSTART=1`** so `ensureUIServer()` reports
+a missing editor server instead of spawning one — the auto-start is detached,
+so a test that triggers it would leave a `server.js` running after it finishes.
 
 ## Run
 
@@ -254,6 +274,10 @@ Examples in `library/svg/`: `sparkles.svg` (loop), `lower-third.svg`,
   "untargetedTracks": [ "V2" ],
   // ^ optional — lanes edits skip (split, insert, ripple, close gap…); default: all targeted
   "encodeProfile": "hq",  // optional — fast-export profile id (see encoding-profiles.json)
+  "delivery": { "preset": "youtube", "width": 1920, "height": 1080, "…": "…" },
+  // ^ optional — the delivery spec exports use by default (see "Delivery presets"); setProject takes a preset id
+  "outputs": [ { "id": "o_1", "on": true, "preset": "master", "…": "…" } ],
+  // ^ optional — batch outputs: files made together, one render per frame rate (see "Batch outputs and the export queue")
   "master": { "gain": -1.5, "fx": [ { "type": "limiter", "ceiling": -1 } ] },
   // ^ optional — master fader, dB (−60 = silence … +12; omit = 0 dB) and master effects (see "Audio mix")
   "tracks": [                          // optional — timeline lanes (default V3…V1 + A1…A4)
@@ -268,6 +292,8 @@ Examples in `library/svg/`: `sparkles.svg` (loop), `lower-third.svg`,
     { "id": "A4", "kind": "audio" }
   ],
   "buses": [ { "id": "B1", "name": "Dialogue", "gain": -2, "fx": [ { "type": "compressor" } ] } ],
+  "collections": [ { "id": "col_sel", "name": "Selects", "media": [ "m_abc" ] } ],
+  // ^ optional — Project-bin collections: media grouped across folders; see "Media management"
   "comps": [ { "id": "lt", "name": "Lower third", "width": 1280, "height": 720, "duration": 5, "clips": [ /* … */ ] } ],
   // ^ optional — compositions (nested sequences), placed with kind:"comp" clips; see "Compositions (nested sequences)"
   // ^ optional — submix buses B1…B8: name, gain (dB), pan, mute, fx; tracks route in with `out`
@@ -275,6 +301,9 @@ Examples in `library/svg/`: `sparkles.svg` (loop), `lower-third.svg`,
     { "id": "m_abc", "name": "intro.mp4", "kind": "video",  // video|audio|image|svg
       "src": "/media/intro.mp4",             // path under ./media or ./library (never a raw https:// URL)
       "duration": 12.4, "width": 1920, "height": 1080,
+      "fps": 29.97, "codec": "h264", "audioCodec": "aac", "audioChannels": 2, "sampleRate": 48000,
+      "size": 45200000, "bitrate": 29300000, // probed from the file (read-only; see "Media management")
+      "favorite": true, "tags": [ "interview", "day 1" ],   // optional: bin organization
       "folderId": null },                    // optional: id of a folders[] entry
     { "id": "m_abd", "name": "intro.denoise-medium.flac", "kind": "audio", "src": "/media/intro.denoise-medium.flac",
       "derivedFrom": "m_abc", "denoise": "medium" }  // a noise-reduced copy of m_abc (see "Audio mix")
@@ -1346,6 +1375,140 @@ with `fields:{logo:"<your logo's media id>", brand, accent}` at 0;
 it in every project; **titles that arrive and leave the same way** —
 `applyPreset` an In and an Out on every title in one patch.
 
+### Media management
+
+The Project bin knows each file's details and helps find, group and track
+footage. Everything here is organization: none of it changes what plays or
+exports.
+
+**Metadata.** The editor reads every file in `media/` and `library/` with
+ffprobe (via `GET /api/media-info`) and writes what it finds onto the media
+entry. These fields are read-only — they describe the file:
+
+| key | does |
+|---|---|
+| `fps` | video frame rate (29.97, 25, 59.94 …); absent for stills and audio |
+| `codec` | video codec (`h264`, `hevc`, `prores`, `vp9` …), or the image format (`png`, `mjpeg`) |
+| `audioCodec` · `audioChannels` · `sampleRate` | first audio stream: codec, channel count (`0` = the file has no audio), Hz |
+| `size` · `bitrate` | file size in bytes · overall bitrate, bits per second |
+| `width` · `height` · `duration` | as before; filled in when missing (phone footage shot rotated reports its upright size) |
+
+Without ffprobe on PATH only `size` is filled in; the browser still probes
+`duration`, `width` and `height`.
+
+**Organizing.** `favorite: true` stars a file; `tags` is a list of free-form
+labels (at most 24, each up to 32 characters, matched without regard to case).
+`collections` at the top of the document group media across folders — a file
+can be in any number of them, while it sits in one folder (`folderId`).
+
+**Usage.** A file's *placements* are the clips that show it, on the main
+timeline and inside every composition. A video and the audio stems linked to it
+count as one placement, so a shot used twice reads "used 2×".
+
+In the editor, the Project tab has:
+
+- **Search** — every word must match the name, kind, extension, codec,
+  resolution (`3840x2160`, `2160p`) or a tag; `#word` matches tags only. Esc clears it.
+- **Show** — All media · ★ Favorites · Used in the edit · Unused · a kind · a
+  collection · a tag. While searching or filtering, the bin lists the hits flat
+  (each with its folder), with a count and **Clear**; a collection's view also
+  has **Rename** and **Delete** (its media stay).
+- **Sort** — name (natural: `shot 2` before `shot 10`), kind, duration,
+  resolution, frame rate, codec, audio channels, file size or times used, with
+  ↑ / ↓. Files missing a value sort last either way. Folders keep their tree;
+  the sort applies inside each.
+- **☰ List view** — one row per file with columns: name, duration, resolution,
+  FPS, codec, audio, size and uses; click a column heading to sort by it. On a
+  narrow bin the columns drop out right to left; widen the panel to see them all.
+- On each file: **☆** stars it, the **uses** badge opens its placements.
+  Right-click a file → **Open in Source**, **Find timeline instances** (every
+  placement, main timeline and comps, with track and time — click one to jump
+  there, opening its comp if needed), **Media info…**, favorites, **Tags…**,
+  **Add to / Remove from** a collection, **New collection…**, **Remove from project**.
+- Right-click a clip on the timeline → **Reveal in project** scrolls the bin to
+  its file (or its comp), opening folders and clearing a search that hides it.
+
+**Offline media.** A file is *offline* when its `src` names nothing under
+`media/` or `library/` — it was moved, renamed or deleted. The editor checks
+on load and whenever those folders change. An offline file's clips stay where
+they are: the timeline hatches them red (**⚠ Offline**), the monitor and the
+export draw a **Media offline** slate in the picture's place, and its audio is
+silent. The bin marks the file **OFFLINE**, says how many are missing, and the
+Show filter gains **⚠ Offline**. The Export dialog warns before rendering one.
+Files under `media/` may sit in subfolders (`/media/archive/a.mp4`).
+
+- **Relink** points a media entry at the same footage where it is now; clips
+  keep their In points, edits and everything else. Right-click the file →
+  **Relink…** (or **Relink…** on the offline banner for all of them). The
+  dialog looks through `media/` and `library/` for each file — same name, the
+  same name with another extension, a similar name, the same size — and
+  picks a same-name match for you. **Browse…** picks one file and **Choose
+  folder…** matches a whole folder by name; either copies the chosen files
+  into `media/`. A relinked file whose length differs from the original gets
+  a warning (is it really the same footage?).
+- **Replace file…** (right-click a file) puts a *different* file behind the
+  media entry — a new render, a better take. Every clip using it switches;
+  each keeps its In point and timing, trimmed to fit a shorter file. The name
+  and details follow the new file; favorites, tags and collections stay. To
+  swap the file of one clip only, use the Inspector's **Source** menu instead.
+- Relink and replace are one undo step each.
+
+**Proxies.** Heavy footage — 4K, HEVC, ProRes, long phone clips — can stutter
+while you scrub and play. A *proxy* is a light copy the editor plays instead
+while you edit: H.264 at 540p (or 720p / 1080p, never larger than the
+source), a keyframe every 12 frames so seeking is quick, the source's own
+timestamps (frame for frame — no frames added or dropped) and its first audio
+stream. The edit always refers to the original: the timeline, `project.json`
+and every clip stay the same whether proxies are on or off.
+
+**Export always reads the originals**, and so do `fablecut_frame` (timeline
+mode), `fablecut_scopes`, tracking and every other measurement — the
+players switch to the original files for the render and back afterwards. A
+proxy only changes how smoothly the preview runs, never the result.
+
+- Right-click a video in the bin → **Create proxy (540p)** / **(720p)**;
+  right-click the **Project** tab → **Create proxies for N videos**. ffmpeg
+  makes them on the server one at a time in the background; the bin shows
+  each file's progress (**P 42%**), then a green **P** once it is ready.
+  **Delete proxy** removes one. The bin's list view has a **Proxy** column,
+  Show has **Has a proxy** / **Video without a proxy**, and **Media info**
+  says which file is playing.
+- The monitor's **Proxy** button turns proxy playback on and off (on by
+  default; remembered in this browser). The Source monitor follows it too.
+- Proxies live in `analysis/proxies/`, a disposable cache: each is named
+  after its source file *and that file's size and modification time*, so a
+  re-rendered or replaced original simply has no proxy until you make a new
+  one. Deleting the folder loses nothing but time. Proxies need ffmpeg.
+
+**Agents:**
+
+- `{op:"updateMedia", id | ids, set:{name?, favorite?, tags?, folderId?}, addTags?, removeTags?}`
+  — organize files (`favorite:false` unstars; `tags:[]` clears). Metadata keys
+  are refused: they come from the file.
+- `{op:"setCollection", id?, name?, media?, add?, remove?}` creates a collection
+  (a new `id`, or a `name` no collection has) or changes one: `media` replaces
+  its list, `add` / `remove` edit it. `{op:"removeCollection", id}` deletes it;
+  its media stay. `removeMedia` takes a file out of every collection.
+- The compact view lists each file with its metadata, ★, tags, folder and
+  `uses:N`, and the collections on one line:
+  `m_abc video "intro.mp4" 12.4s 1920×1080 29.97 fps h264 stereo 48 kHz 45 MB ★ #interview uses:2`.
+- `fablecut_import_media` probes the file as it imports it, so the entry it
+  returns already has these fields.
+- `fablecut_status` lists offline media, and the compact view marks each
+  `OFFLINE (file missing — relinkMedia)` and each video with a proxy `proxy:540p`.
+- `fablecut_proxy {}` reports every video's proxy; `{create:true, mediaIds?, height?}`
+  makes them (waits until done unless `wait:false`); `{delete:true, mediaIds?}`
+  removes them. Proxies never change what you measure or export, so an agent
+  only needs them when the user asks for smoother playback.
+- `{op:"relinkMedia", id, src:"/media/…", name?}` — the same footage found
+  elsewhere: put the file in `media/` (copy it, or `fablecut_import_media` and
+  `removeMedia` the extra entry it registers), then relink. The note warns when
+  the new file's length differs.
+- `{op:"replaceMedia", id, src, name?}` — a different file behind the entry;
+  clips keep their timing, trimmed to fit (the note says how many). `src` must
+  be an existing file under `/media/` or `/library/` of the same kind (an
+  audio entry may use a video container).
+
 ### Semantics
 
 - Rendering order: V1 is drawn first, then V2, V3, … on top. SVG/image/text clips
@@ -1441,6 +1604,44 @@ it in every project; **titles that arrive and leave the same way** —
 - `bgRemove` and `chromaKey` can combine with all filters; heavy pixel work is
   automatic (only runs when those props are set).
 
+## Look at the footage (`fablecut_frame`)
+
+`fablecut_analyze_reference` gives you the **ears** — where the cuts are, how hard
+each shot hits. `fablecut_frame` gives you the **eyes**. It answers with a real
+image (an MCP `image` content block), so you can judge a shot instead of
+inferring it from an `energy` value.
+
+| call | returns |
+|---|---|
+| `{path:"/media/x.mp4", t:3.2}` | that exact frame |
+| `{path:"/media/x.mp4", frames:12}` | a 4×3 contact sheet across the whole clip |
+| `{path:"/media/x.mp4", frames:12, from:30, to:90}` | a contact sheet across part of it |
+| `{time:8.5}` (no `path`) | the **composed timeline** at 8.5 s, graded, all tracks |
+| `{path}` with an absolute path | the file is read in place without copying into `media/` |
+| `{path, text:true}` | text-only statistics (luma, colors, texture, saturation, motion) for non-vision agents |
+
+Each answer leads with a text line naming the source, the timestamp(s) and (in
+timeline mode) the clips on screen, so you always know what you are looking at.
+`width` sets the pixel width (default 768 for one frame, 320 per contact-sheet
+cell); `text:true` returns descriptive statistics instead of an image block, for
+agents without vision capability — luma levels (min, p1, median, mean, p99, max,
+all 0–1 like `fablecut_scopes`), dominant colors, texture, saturation and
+per-cell motion; `where`/`timeout` apply to timeline mode only.
+
+The REST endpoint `/api/frame` accepts `src`, `t`, `frames`, `from`, `to`, `w`,
+`q` (JPEG quality 1–31) and `text=1` (statistics mode) as query parameters.
+
+**When it pays.** Before choosing a clip's `in` point, sample a few candidate
+moments — the blueprint tells you a shot spans 2.1 s–4.9 s and reads
+`energy: 88`, but only a frame tells you whether that is a car jump or a pan
+across a landscape. Contact sheets are the cheap survey: one call shows you
+what a whole 3-minute clip holds, then you grab single frames where it matters.
+Timeline mode answers "what did I actually build?" — the same picture the user
+sees and export renders, grades and transitions included.
+
+Needs ffmpeg on PATH for the source modes. Timeline mode runs in the open editor
+tab, else a headless browser, like `fablecut_export`.
+
 ## Remake a reference video (analyze → blueprint → rebuild)
 
 Given a reference edit (a reel/montage the user likes), FableCut can analyze it
@@ -1480,6 +1681,8 @@ obvious cuts were missed, raise it if motion is being misread as cuts.
    (hard cuts by default — that's what shot detection saw). Pick source footage
    whose motion matches each shot's `energy` (calm ≤40, action ≥70), and choose
    each clip's `in` so something interesting happens inside the window.
+   **Then look**: `fablecut_frame {path, frames:12}` to survey a candidate clip,
+   `{path, t}` at the exact moment you want, before committing to an `in`.
 4. The `drop`: put the hero shot there; classic garnish = a speed ramp landing
    on it, an impact `adjust` layer (shake+rgbSplit), or a whip transition.
 5. Pacing garnish to taste: shots shorter than ~0.6 s read as beat-flashes;
@@ -1495,6 +1698,23 @@ obvious cuts were missed, raise it if motion is being misread as cuts.
   Append `?force=1` to overwrite unconditionally. Writes are atomic (tmp file +
   rename), so a crashed write never corrupts the file.
 - `GET  /api/media`   — list files in ./media (name, src, size)
+- `GET  /api/media-info?src=/media/x.mp4` → `{src, info}` · `POST /api/media-info {srcs:[…], stat?}` →
+  `{info:{src: info}}` (up to 2000; `stat:true` answers only `{size, mtimeMs}`, no ffprobe —
+  how the editor checks for offline files) — a file's metadata from ffprobe: `size`, `fps`, `codec`,
+  `audioCodec`, `audioChannels`, `sampleRate`, `bitrate`, `duration`, `width`, `height` and
+  `probe` (`"ffprobe"`, or `"stat"` when only the size could be read). `info` is `null` when
+  the src names no file under `/media/` or `/library/`. Cached per file version.
+- `POST /api/proxy {srcs:[…], height?:540|720|1080}` → `{status:{src: status}}` queues proxies
+  (ffmpeg, one at a time); `POST /api/proxy/status {srcs}` → `{status:{src: status | null}}`;
+  `POST /api/proxy/delete {srcs}` → `{deleted:{src: n}}`. A status is
+  `{state:"ready", src:"/proxies/…", width, height, size}`, `{state:"queued"|"running", progress, height}`,
+  `{state:"failed", error}` or `{state:"none"}` (`null` = no such source file). Progress and
+  results are also pushed as SSE event `proxy` (`{src, status}`). `GET /proxies/<name>` serves
+  a proxy file from `analysis/proxies/`. `/api/proxy` answers 503 without ffmpeg.
+- `POST /api/relink/candidates {media:[{id, name, src?, size?, kind?}]}` →
+  `{candidates:{id:[{src, name, size, score, why}]}}` — where a missing file might be now:
+  files under `media/` and `library/` (subfolders included) of the same kind, ranked by
+  name (same name, same name with another extension, similar name) and size, best 5 each.
 - `GET  /api/library?dir=sfx|elements|svg|fonts|presets|templates` — list library assets
 - `GET  /api/presets` · `GET /api/templates` — the saved presets / templates, validated (bad files skipped);
   `POST /api/presets {preset}` · `POST /api/templates {template}` — validate one and save it as
@@ -1520,9 +1740,27 @@ obvious cuts were missed, raise it if motion is being misread as cuts.
 - `POST /api/analyze` — body `{src:"/media/ref.mp4", threshold?, music?}`: analyze a
   reference video into an edit blueprint (see "Remake a reference video"); extracts
   its music into ./media. `GET /api/analyze?src=…` returns the cached blueprint.
+- `GET  /api/frame?src=/media/x.mp4&t=3.2` — one JPEG still of a source clip, the
+  "eyes" to go with `/api/analyze`'s ears (see "Look at the footage"). Optional
+  `w` (pixel width, default 768) and `q` (ffmpeg `-q:v` 1–31, default 4).
+  `&frames=N[&cols=][&from=][&to=][&w=320]` instead returns one N-up **contact
+  sheet** across the clip (N 2–60; `cols` omitted → the squarest layout, so 6
+  frames give 3×2 rather than 4×2 with two black cells). `src` must name an
+  existing file under `/media/` or `/library/` (404 otherwise). `?path=` reads
+  any file on the machine but only with the `X-FableCut-Client: mcp` request
+  header, which only the local MCP client sends — without it the request is
+  refused (403) before the path is even resolved. Results are cached in
+  `analysis/frames/` keyed by source path, size and mtime; the cache is capped
+  (500 files / 128 MB, oldest first). The response carries
+  `X-FableCut-Frame-Times` (comma-separated sample times, so a sheet's cells can
+  be mapped back to timestamps) and `X-FableCut-Frame-Source`.
+- `POST /api/scopes/request` also takes `{"image":true}`, which makes the editor
+  return the measured still as a JPEG data URL in `result.image` — how
+  `fablecut_frame {time}` shows an agent the composed program picture.
 - `GET  /api/events`  — SSE: named event `change` when project.json, ./media or
   ./library changes; named event `profiles` when `encoding-profiles.json` changes
-  (UI refreshes the export-profile list only — no project reload)
+  (UI refreshes the export-profile list only — no project reload); named event
+  `proxy` as a proxy is queued, makes progress, finishes or is deleted
 - Fast / WebCodecs export (browser compositor → server ffmpeg):
   `GET /api/export/ffmpeg` → `{available}` · `GET /api/export/profiles[?detail=1]` →
   `{default, profiles, issues}` · `POST /api/export/begin`
@@ -1765,12 +2003,135 @@ agent last wrote, so an export right after a patch includes that patch.
 
 - `fablecut_export {}` — waits, then returns the file path under `exports/`.
   Range: `inPoint`→`outPoint` when either is set, else the whole timeline;
-  `range:"entire"|"in-out"` overrides. `profile:"hq"` picks an encoding profile.
+  `range:"entire"|"in-out"` overrides.
+- `preset:"instagram-reels"` picks a delivery preset; `delivery:{…}` changes any of its
+  settings (`{preset:"youtube", delivery:{fps:60, video:{rate:"vbr", bitrate:16000}}}`).
+  `profile:"hq"` picks a raw encoding profile instead. With neither, `project.delivery`
+  is used when set, else `project.encodeProfile`, else the server's default profile.
+- `outputs:true` exports the project's checked batch outputs; `outputs:[{preset:"master"},
+  {preset:"youtube"}, {preset:"instagram-reels"}, …]` exports a list. One render per
+  frame rate; the reply lists every file (or why one failed).
 - `where:"headless"` renders in the background and leaves the user's tab alone;
   `where:"tab"` refuses if no tab is open.
 - Long edits: `wait:false` returns a job id at once; poll with `{job:"x_…"}`
   and stop one with `{cancel:"x_…"}`. One export runs at a time.
 
+### Delivery presets
+
+The Export dialog's **Preset** list. Each preset is a structured spec — no ffmpeg
+arguments to write — that `delivery.js` turns into one ffmpeg pass:
+
+| Preset | Output |
+|---|---|
+| `youtube` | 1920×1080, H.264 CRF 18, keyframe every 0.5 s, AAC 384k 48 kHz |
+| `youtube-shorts` | 1080×1920, as YouTube; warns past 3 min |
+| `instagram-reels` | 1080×1920, H.264 CRF 19 capped at 25 Mb/s, AAC 256k; ≤ 60 fps, warns past 3 min |
+| `tiktok` | 1080×1920, H.264 CRF 19 capped at 20 Mb/s, AAC 256k; warns past 10 min |
+| `x` | 1920×1080, H.264 CRF 20 capped at 25 Mb/s, AAC 192k; warns past 2:20 and 512 MB |
+| `linkedin` | 1920×1080, H.264 CRF 20 capped at 20 Mb/s, AAC 192k; warns past 15 min and 5 GB |
+| `master` (default) | the picture's own size, H.264 CRF 16, AAC 320k |
+| `broadcast` | 1920×1080 ProRes 422 HQ MOV, PCM 24-bit 48 kHz, Rec. 709, normalized to −23 LUFS / −1 dBTP (EBU R128); warns off 25 / 29.97 / 50 / 59.94 fps |
+| `web` | 1280×720 H.264 CRF 23, AAC 128k, fast start |
+| `archive` | the picture's own size, lossless FFV1 4:2:2 10-bit MKV, PCM 24-bit |
+| `custom` | your own settings |
+
+A spec (every key optional — what is left out comes from its `preset`):
+
+```jsonc
+{
+  "preset": "youtube",
+  "width": 1920, "height": 1080,   // null = the picture's own size (the export frame, else the canvas)
+  "fps": null,                     // null = the project's; 23.976 / 29.97 / 59.94 are exact NTSC rates
+  "reframe": "fill",               // another shape: fill crops the middle (or the export frame), fit pads, stretch
+  "container": "mp4",              // mp4 · mov · mkv · webm · mxf
+  "video": {
+    "codec": "h264",               // h264 · hevc · av1 · vp9 · prores · dnxhr · mpeg2 (XDCAM HD422) · ffv1
+    "encoder": "libx264",          // or h264_nvenc / h264_qsv / h264_amf … — listed only when they work here
+    "rate": "crf",                 // crf · vbr · cbr (ProRes, DNxHR, XDCAM, FFV1 are fixed)
+    "crf": 18, "bitrate": 12000, "maxrate": null,   // kb/s; maxrate caps a CRF or VBR encode
+    "keyint": 2,                   // seconds between keyframes, 0 = the encoder's default
+    "speed": "balanced",           // fast · balanced · best
+    "pixFmt": "yuv420p",           // 4:2:0 / 4:2:2 / 4:4:4, 8 or 10 bit, as the codec allows
+    "profile": null                // ProRes: proxy lt standard hq 4444 4444xq · DNxHR: lb sq hq hqx 444
+  },
+  "audio": { "codec": "aac", "bitrate": 320, "sampleRate": 48000, "channels": 2,
+             "loudness": null, "truePeak": -1 },
+                                   // aac · opus · mp3 · pcm16 · pcm24 · flac · none
+                                   // loudness: a LUFS target (−14 streaming, −16 podcast, −23 EBU R128, −24 ATSC) or null
+  "color": "bt709",                // bt709 · bt709-full · bt601-625 (PAL) · bt601-525 (NTSC)
+  "filename": "{project}_{preset}_{res}",
+  // tokens: {project} {preset} {res} (1080p, 1080x1920, 1080sq) {w} {h} {fps} {codec} {date} {time} {range} {n}
+  "metadata": { "title": "", "artist": "", "description": "", "copyright": "", "date": "", "keywords": "" }
+}
+```
+
+- **Impossible combinations are corrected, and the reply says how** — ProRes moves to MOV,
+  WebM takes Opus, Quick Sync gets 4:2:0. The dialog shows the same notes.
+- **Reframing happens in ffmpeg**: the browser sends the whole canvas and ffmpeg crops
+  the export frame (or the middle, for another shape) and scales. The dialog warns
+  when the output is upscaled or cropped, when a platform's length, size or frame-rate
+  limit is passed, and estimates the file size where it can (bitrate and fixed-rate
+  codecs; CRF cannot know).
+- Outputs that keep more than 4:2:0 8-bit (ProRes, DNxHR, FFV1, 10-bit, 4:2:2, 4:4:4)
+  get raw RGBA frames instead of JPEG, so no chroma is lost on the way. Slower to send.
+- The audio is cut to exactly the frames' length.
+- **Loudness** (`audio.loudness`): the mix is measured and turned to the target with
+  ffmpeg's two-pass `loudnorm` — one linear gain, and a true-peak limiter at `truePeak`.
+  When the peaks leave no room for the gain it compresses instead and may land under the
+  target; the check after the export says so. Off (null) leaves the mix as mixed —
+  except Broadcast, which normalizes to −23 LUFS / −1 dBTP. Mixes shorter than 3 s may
+  not reach the target.
+- **Checked after the export.** Every file is read back with ffprobe and measured
+  (BS.1770 integrated loudness and true peak) and compared with what was asked:
+  size, frame rate, frame count, codec, color tags, audio codec / rate / channels,
+  length, loudness against the target (±1 LU) and the true-peak ceiling, and file size
+  against the platform's limit. Without a target the report says where the platform
+  plays it ("YouTube plays it 4.2 dB quieter"). The report shows in the queue, a toast
+  after a single export, and the `fablecut_export` reply.
+- **Saved presets**: "Save preset…" in the dialog writes `library/delivery/<id>.json`,
+  listed under "Saved" in every project (`GET / POST /api/export/presets`,
+  `POST /api/export/presets/delete {id}`).
+- The settings are checked by a 0.1 s ffmpeg dry run before anything renders.
+- The dialog remembers the last settings in this browser. `setProject {delivery:"youtube"}`
+  (or a spec) pins them in the project, for the dialog and for `fablecut_export`.
+- Fast export only — WebCodecs and Realtime export encode their own way.
+
+### Batch outputs and the export queue
+
+**One project → many files.** `project.outputs` is the project's list of files to make
+(up to 16), each a delivery spec plus `{id, on}`. In the Export dialog, **Batch outputs**
+lists them: **+ Add these settings** adds the preset shown above, **+ Typical set** adds
+Master, YouTube 1080p, Reel 1080×1920, Square 1080 and a 720p preview, the checkbox picks
+which go out, **Load** shows one's settings above. **Export checked** queues the checked
+ones and starts.
+
+```jsonc
+// setProject {outputs:[…]} — a preset id or a spec each; stored complete with an id
+{"op":"setProject","set":{"outputs":[
+  "master", "youtube",
+  {"preset":"instagram-reels"},
+  {"preset":"custom","width":1080,"height":1080,"filename":"{project}_square_{res}"},
+  {"preset":"web","filename":"{project}_preview_{res}","on":false}
+]}}
+```
+
+- **Rendered once.** Outputs with the same frame rate and range go out in ONE render:
+  the compositor draws each frame once and every output's ffmpeg encodes it (up to 8 per
+  render). Four 1080p files take about as long as one. Outputs at another frame rate get
+  their own render. When any output needs full chroma (ProRes, 10-bit, lossless) the
+  frames go as RGBA to all of them.
+- **The export frame** is the picture for outputs of its own shape (and for the
+  picture's own size). An output of another shape reframes the whole canvas — a project
+  framed for 9:16 still makes a proper 16:9 file.
+- **The export queue** (Export dialog → **Add to queue**, or **Queue**) runs waiting
+  outputs back to back with a progress bar each, **Stop**, **Retry** for a failed one,
+  **Open** for a finished file and **Clear finished**. It lives in the tab: a reload
+  empties it. One output that fails does not stop the others in its render.
+- REST: `POST /api/export/begin {deliveries:[{delivery, name}, …], canvasW, canvasH,
+  region?, duration, fps, hasAudio}` → `{id, input, jpegQuality, outputs:[{file, spec,
+  summary, notes, size}]}`; frames and audio as for one output; `/api/export/end` →
+  `{src, outputs:[{file, ok, src, report:{ok, checks:[{ok, text}], line}, mixLoudness?} | {file, ok:false, error}]}`.
+
 ### Encoding profiles (`encoding-profiles.json`)
 
 User-editable at the repo root. A profile is a **raw ffmpeg argument list** plus the
@@ -1834,11 +2195,12 @@ ffmpeg -y -f image2pipe -framerate <fps> -i - [-i audio.wav] <jpeg-color> <args
 not `-i source.mp4`. Filters and codec settings apply to that frame stream. To transcode
 an existing file verbatim, run ffmpeg directly — that is outside the compositor path.
 
-**Which profile is used (priority):**
-1. Profile picked in the Export dialog (one-off; saved to browser settings unless overridden)
-2. `project.encodeProfile` — set via UI reload or `{op:"setProject", set:{encodeProfile:"hq"}}`
-3. Browser setting `encodeProfile` in localStorage (set when you change the Export dropdown)
-4. `default` in `encoding-profiles.json`
+Encoding profiles are listed at the bottom of the Export dialog's Preset list.
+
+**What the Export dialog opens on (priority):**
+1. `project.delivery`, then `project.encodeProfile` — set with `setProject`
+2. The last preset or profile used in this browser
+3. The `master` delivery preset
 
 **MCP:** `fablecut_encode_profiles` lists profiles; `{detail:true}` includes each `args`
 array; `{profile:"hq"}` returns one profile. `fablecut_status` shows the effective profile.

package/README.md

@@ -120,6 +120,8 @@ same time.
   ffmpeg; the clip's audio switches to it and **Off** switches back. Agents
   use `fablecut_denoise`.
 - **Project bin folders** — tree view with expand/collapse; drag media or folders to nest; right-click the **Project** tab → New folder; drop files onto a folder to import into it
+- **Media management** — each file's frame rate, codecs, audio channels and size (ffprobe); search by name, codec, resolution or `#tag`; filter by favorites, used / unused, kind, tag or collection; sort by any detail or by times used; a list view with metadata columns; favorites, tags and collections; **Find timeline instances** and **Reveal in project**; offline files flagged with a "Media offline" slate, **Relink…** (finds moved files by name and size) and **Replace file…**
+- **Proxies** — light, frame-accurate H.264 copies of 4K / HEVC / ProRes footage made in the background (ffmpeg); edit on the proxy with the monitor's **Proxy** button, export always renders the originals
 - **Import from URL** — **+ URL** downloads an HTTPS video/audio/image into
   `./media/` (same-origin after import). Remote SVG is refused. Agents use
   `fablecut_import_media` with an `https://` path. The URL is not kept as
@@ -287,6 +289,20 @@ same time.
   `node analyze.js ref.mp4`, `POST /api/analyze`, or the
   `fablecut_analyze_reference` MCP tool.
 
+**Look at the footage**
+
+- An agent (or you, over REST) can fetch an actual **image** of any moment:
+  `GET /api/frame?src=/media/x.mp4&t=3.2` returns a JPEG of that frame, and
+  `&frames=12` returns a 4×3 **contact sheet** across the clip — a cheap survey
+  of everything a 3-minute take holds. Grabs are cached under `analysis/frames/`.
+- The `fablecut_frame` MCP tool wraps it and returns the image inline, so a
+  multimodal model can *look*. Pass a `time` instead of a `path` and it renders
+  the **composed timeline** through the editor's own compositor — graded, all
+  tracks, identical to what export produces — so "is this grade right?" and "what
+  did I actually build?" have a visual answer.
+- Together with the analyzer above, agents pick footage by looking at it instead
+  of guessing from an energy number.
+
 **Asset library**
 
 - `library/` folders surface as tabs in the UI: **Elements** (overlay art),
@@ -294,18 +310,36 @@ same time.
 
 **Export**
 
+- **Delivery presets**: YouTube, YouTube Shorts, Instagram Reels, TikTok, X,
+  LinkedIn, Master, Broadcast (ProRes 422 HQ), Web, Archive (lossless FFV1) and
+  Custom. Every setting is a control: resolution and reframing (crop, fit or
+  stretch to another shape), frame rate, codec (H.264, HEVC, AV1, VP9, ProRes,
+  DNxHR, XDCAM HD422, FFV1) and hardware encoder, CRF / VBR / CBR, max rate,
+  keyframe interval, pixel format, color, container, audio codec, bitrate and
+  rate, loudness normalization (−14 / −16 / −23 / −24 LUFS with a true-peak
+  ceiling), a file-name template and metadata. Save your own presets; the
+  dialog warns about upscaling, crops and platform limits before it renders,
+  and every finished file is read back and checked — size, frame rate, frame
+  count, codecs, length, loudness, true peak and file size
+- **Batch export**: one project → many files (master, YouTube 1080p, a 9:16
+  reel, a square, a 720p preview…) from **one render per frame rate and
+  range** (up to 8 outputs each) — every frame is drawn once and each output's ffmpeg
+  encodes it. Batch outputs are saved with the
+  project; an **export queue** runs them back to back with progress, stop,
+  retry and open
 - Fast export: browser renders every frame + an offline audio mix; ffmpeg
-  encodes **JPEG frames** via an **encoding profile** from
+  encodes them with a delivery preset, or a raw **encoding profile** from
   `encoding-profiles.json` (keeps rendering if you switch tabs). Encode and
   upload run ahead of the compositor so a fast timeline is not stalled by
-  `toBlob`. The Export dialog has a profile selector; pin a project default
-  with `encodeProfile` in `project.json`
+  `toBlob`
 - WebCodecs export: the browser HW-encodes Annex-B H.264; the server
   stream-copies and muxes audio. Faster uploads; bitrate/VBR-CBR in the
   Export dialog. Unavailable while an export frame is set (use Fast)
 - Realtime MediaRecorder fallback when ffmpeg or WebCodecs isn't available
 - Agents export too: `fablecut_export` runs the Fast export in the open editor,
-  or in a headless Chrome / Edge the server starts, and returns the file path
+  or in a headless Chrome / Edge the server starts, and returns the file path;
+  `preset` and `delivery` pick and adjust a delivery preset; `outputs` makes
+  several files in one go
 - Export **Range** dropdown: Entire timeline or IN–OUT (defaults to IN–OUT when
   markers are set). Effective IN/OUT export bounds are clamped to `projDur()`.
 
@@ -412,7 +446,7 @@ Three equivalent control surfaces:
 
    Tools: `fablecut_status` (auto-starts the editor), `fablecut_docs`,
    `fablecut_get_project`, `fablecut_set_project`, `fablecut_patch_project`,
-   `fablecut_import_media`, `fablecut_analyze_reference`,
+   `fablecut_import_media`, `fablecut_analyze_reference`, `fablecut_frame`,
    `fablecut_encode_profiles`, `fablecut_normalize_audio`, `fablecut_auto_duck`,
    `fablecut_denoise`, `fablecut_export`, `fablecut_scopes`, `fablecut_track`.
 
@@ -441,6 +475,15 @@ my clips, same music"*. The agent calls `fablecut_analyze_reference`, gets the
 blueprint (cuts, beats, BPM, energy, drop, extracted music), and rebuilds the
 structure shot-for-shot with your footage.
 
+**The agent can see, not just measure.** `fablecut_analyze_reference` gives it
+the *ears* — where the cuts land, which shots hit hard. `fablecut_frame` gives it
+the *eyes*: ask for any moment of any clip (`{path, t:3.2}`) and the call comes
+back with an actual image the model can look at, or ask for a 12-frame contact
+sheet to survey a whole clip in one call (`{path, frames:12}`). Pass a `time`
+with no `path` and it renders the composed timeline — graded, all tracks, exactly
+as export would. So footage gets chosen by looking at it rather than guessing
+from a number, and a grade gets checked against the real picture.
+
 **Conflict-safe concurrent editing**: the UI, the MCP tools, and direct
 `project.json` writes all agree on a `revision` counter. If you edit a clip in
 the UI while an agent is mid-task, the agent's next write is rejected (409 from