fablecut 1.14.0 → 1.15.0

package/server.js

@@ -16,11 +16,13 @@
    ═══════════════════════════════════════════════════════════════════════════ */
 "use strict";
 const http = require("http");
+const crypto = require("crypto");
 const fs = require("fs");
+const os = require("os");
 const path = require("path");
 const { spawn, spawnSync, execFile } = require("child_process");
 
-const { analyze } = require("./analyze");
+const { analyze, frame, frameGrid } = require("./analyze");
 const {
   PROFILES_FILE,
   loadEncodeProfiles,
@@ -32,14 +34,19 @@ const {
   dryRunProfile,
 } = require("./encode-profiles");
 const { downloadImportUrl, maybeFaststart } = require("./import-url");
+const { pruneCache } = require("./frame-cache");
 const { createExportJobs } = require("./export-jobs");
 const { denoiseFile, AMOUNT_IDS: DENOISE_AMOUNTS } = require("./denoise");
 
 const {
   APP_DIR, DATA_DIR, MEDIA_DIR, EXPORTS_DIR, ANALYSIS_DIR, LIBRARY_DIR,
-  PROJECT_FILE, LIBRARY_SUBDIRS, ensureDirs, readSaved, writeSaved,
+  PROJECT_FILE, LIBRARY_SUBDIRS, FRAMES_DIR, PROXIES_DIR, ensureDirs, readSaved, writeSaved,
 } = require("./paths");
 const Templates = require("./templates");
+const { probeFile } = require("./media-probe");
+const MediaLib = require("./media-lib");
+const { createProxies } = require("./proxy");
+const Delivery = require("./delivery");
 
 /* Static app files are served from the install dir; everything the user creates
    lives under DATA_DIR. The two are the same unless FABLECUT_DATA_DIR is set. */
@@ -102,6 +109,7 @@ function broadcast(event = "change", data = event) {
   const payload = `event: ${event}\ndata: ${data}\n\n`;
   for (const res of sseClients) res.write(payload);
 }
+const proxies = createProxies({ dir: PROXIES_DIR, resolveSrc, probe: probeFile, broadcast: (ev, data) => broadcast(ev, data) });
 let debounce = null;
 let profilesDebounce = null;
 function onFsChange() {
@@ -176,6 +184,32 @@ function run(cmd, args) {
   });
 }
 
+/** A "/media/…" or "/library/…" src → an existing file inside that root, or null.
+ *  Every src-accepting endpoint resolves through here: basename alone is not
+ *  enough (library has subfolders) and a bare join is a traversal hole. */
+function resolveSrc(src) {
+  const p = decodeURIComponent(String(src || "").split("?")[0]);
+  const [root, rel] = p.startsWith("/media/") ? [MEDIA_DIR, p.slice(7)]
+    : p.startsWith("/library/") ? [LIBRARY_DIR, p.slice(9)] : [null, null];
+  if (!root || !rel) return null;
+  const file = path.normalize(path.join(root, rel));
+  if (!file.startsWith(path.normalize(root + path.sep))) return null;
+  try { return fs.statSync(file).isFile() ? file : null; } catch { return null; }
+}
+
+/** An explicit absolute/relative path argument → an existing file, or null.
+ *  Used by /api/frame only. This deliberately reaches outside media/ and
+ *  library/: looking at a clip must not require putting it in the project
+ *  folder. The caller is the local MCP server or the user's own fetch, both
+ *  already able to read any file the user can — and unlike resolveSrc() it
+ *  never turns a request string into a path *inside* a served root, so there
+ *  is no traversal to defend. It is deliberately NOT how a src is resolved. */
+function resolvePathArg(p) {
+  if (!p || typeof p !== "string") return null;
+  let file = path.resolve(p);
+  try { return fs.statSync(file).isFile() ? file : null; } catch { return null; }
+}
+
 /* Remux MP4-family uploads with `+faststart` so the moov atom leads the file —
    without it <video> stalls for seconds probing over Range requests. */
 function faststart(file) { return maybeFaststart(file); }
@@ -210,6 +244,140 @@ function attachProc(sess, proc) {
   proc.stdin.on("error", () => {}); // EPIPE if ffmpeg dies mid-stream
   sess.done = new Promise((res) => proc.on("close", res));
 }
+/* Delivery presets (delivery.js) — structured settings instead of raw args.
+   Which encoders exist: `ffmpeg -encoders`, and for the hardware ones a 2-frame
+   test encode, because a build lists h264_nvenc / _qsv / _amf whether or not
+   this machine has the GPU. Asked once, in the background, on first use. */
+let deliveryEncodersP = null;
+function runFfmpeg(args, timeout = 15000) {
+  return new Promise((resolve) => {
+    execFile("ffmpeg", args, { timeout, maxBuffer: 8 * 1024 * 1024, windowsHide: true },
+      (err, stdout, stderr) => resolve({ code: err ? (err.code ?? 1) : 0, stdout: String(stdout || ""), stderr: String(stderr || "") }));
+  });
+}
+function deliveryEncoders() {
+  if (!HAS_FFMPEG) return Promise.resolve(new Set());
+  if (deliveryEncodersP) return deliveryEncodersP;
+  deliveryEncodersP = (async () => {
+    const listed = Delivery.parseEncoders((await runFfmpeg(["-hide_banner", "-encoders"])).stdout);
+    const usable = new Set([...listed].filter((e) => !Delivery.ENCODERS[e]?.hw));
+    await Promise.all([...listed].filter((e) => Delivery.ENCODERS[e]?.hw).map(async (e) => {
+      const r = await runFfmpeg(["-hide_banner", "-v", "error", "-f", "lavfi", "-i", "color=c=black:s=256x144:r=30:d=0.1",
+        "-frames:v", "2", "-c:v", e, "-pix_fmt", Delivery.ENCODERS[e].hw === "nvenc" ? "yuv420p" : "nv12", "-f", "null", "-"]);
+      if (r.code === 0) usable.add(e);
+    }));
+    return usable;
+  })();
+  return deliveryEncodersP;
+}
+/** Saved delivery presets: library/delivery/<id>.json, each a spec plus a label. */
+function savedDeliveryPresets() { return Delivery.savedPresets(readSaved("delivery")); }
+/* One render, several files: `deliveries:[{delivery, name}, …]` (up to 8) or a
+   single `delivery` + name. Every output gets its own ffmpeg, fed the same
+   frames; the browser renders each frame once. Frames are raw RGBA when any
+   output needs more than 4:2:0 8-bit, else JPEG at the highest quality asked. */
+const MAX_OUTPUTS = 8;
+async function beginDeliveryExport(rate, name, hasAudio, extra) {
+  const available = await deliveryEncoders();
+  const presets = savedDeliveryPresets();
+  const list = Array.isArray(extra.deliveries) ? extra.deliveries : [{ delivery: extra.delivery, name }];
+  if (!list.length) throw new Error("deliveries is empty");
+  if (list.length > MAX_OUTPUTS) throw new Error(`at most ${MAX_OUTPUTS} outputs per render`);
+  const canvasW = extra.canvasW | 0, canvasH = extra.canvasH | 0;
+  if (canvasW < 2 || canvasH < 2 || canvasW > 16384 || canvasH > 16384) throw new Error("export width/height required (canvasW, canvasH)");
+  const r = extra.region;
+  const region = r && typeof r === "object" && [r.x, r.y, r.w, r.h].every(Number.isFinite) && r.w > 0 && r.h > 0 &&
+    r.x >= 0 && r.y >= 0 && r.x + r.w <= canvasW + 0.5 && r.y + r.h <= canvasH + 0.5 ? r : null;
+  const outs = list.map((d) => {
+    const { spec, notes } = Delivery.normalize(d && d.delivery !== undefined ? d.delivery : d, { available, presets });
+    return { spec, notes, name: d && typeof d.name === "string" ? d.name : name, frame: Delivery.reframe(spec, canvasW, canvasH, region) };
+  });
+  // one render has one frame rate: an output asking for another needs a render of its own
+  const off = outs.map((o, i) => [o, i]).filter(([o]) => o.spec.fps != null && Math.abs(o.spec.fps - rate) > 0.01);
+  if (off.length) throw new Error(off.map(([o, i]) => `output ${i + 1} asks for ${o.spec.fps} fps but this render is ${rate} fps`).join("; ") + " — render each frame rate separately");
+  const input = outs.some((o) => Delivery.frameInput(o.spec) === "rgba") ? "rgba" : "jpeg";
+  // check every output on a 0.1 s synthetic canvas before the browser renders anything
+  const dryDir = fs.mkdtempSync(path.join(os.tmpdir(), "fablecut-dry-"));
+  try {
+    const dry = await Promise.all(outs.map((o, i) => runFfmpeg(Delivery.ffmpegArgs(o.spec, { fps: rate, input, canvasW, canvasH, frame: o.frame,
+      hasAudio, dry: true, outPath: path.join(dryDir, `probe${i}` + Delivery.CONTAINERS[o.spec.container].ext) }), 30000)));
+    const bad = dry.map((d, i) => [d, outs[i]]).filter(([d]) => d.code !== 0);
+    if (bad.length) {
+      throw new Error(bad.map(([d, o]) => {
+        const why = d.stderr.trim().split("\n").filter(Boolean).slice(-3).map((l) => l.trim()).join(" · ");
+        return `ffmpeg rejected these settings (${Delivery.describe(o.spec)}): ${why || "exit " + d.code}`;
+      }).join("\n"));
+    }
+  } finally { try { fs.rmSync(dryDir, { recursive: true, force: true }); } catch {} }
+  const id = Date.now().toString(36) + Math.random().toString(36).slice(2, 7);
+  const dir = fs.mkdtempSync(path.join(EXPORTS_DIR, "fablecut-"));
+  const duration = Number.isFinite(+extra.duration) && +extra.duration > 0 ? +extra.duration : null;
+  for (const o of outs) {
+    const ext = Delivery.CONTAINERS[o.spec.container].ext;
+    Object.assign(o, reserveExportPaths(EXPORTS_DIR, safeName(o.name || "export"), ext), { proc: null, stderr: "", done: null, failed: null });
+    o.err = () => o.stderr.trim().split("\n").filter(Boolean).slice(-3).map((l) => l.trim()).join(" · ");
+  }
+  const sess = {
+    mode: "jpeg", proc: null, fps: rate, outputs: outs, input, canvasW, canvasH, duration,
+    hasAudio: !!hasAudio, dir, wav: null, partPath: null, outPath: null,
+    stderr: "", done: null, lastTouch: Date.now(), err: () => "",
+  };
+  sess.writeLock = Promise.resolve();
+  exportSessions.set(id, sess);
+  const jpegQuality = Math.max(...outs.map((o) => Delivery.jpegQuality(o.spec)));
+  const view = outs.map((o) => ({ file: path.basename(o.outPath), spec: o.spec, notes: o.notes, summary: Delivery.describe(o.spec), size: { w: o.frame.outW, h: o.frame.outH } }));
+  // the single-output fields stay as they were for one delivery
+  return { id, mode: "jpeg", input, jpegQuality, outputs: view, ...view[0] };
+}
+/** Integrated loudness and true peak of a file's first audio stream (ffmpeg ebur128). */
+async function measureLoudness(file, timeout = 10 * 60 * 1000) {
+  const r = await runFfmpeg(Delivery.LOUDNESS_ARGS(file), timeout);
+  return r.code === 0 ? Delivery.parseEbur128(r.stderr) : null;
+}
+function ffprobeJSON(file) {
+  return new Promise((resolve) => {
+    execFile("ffprobe", ["-v", "error", "-show_streams", "-show_format", "-of", "json", file], { timeout: 60000, maxBuffer: 8 * 1024 * 1024, windowsHide: true },
+      (err, stdout) => { try { resolve(err ? null : JSON.parse(stdout)); } catch { resolve(null); } });
+  });
+}
+/** Check a finished output against its spec: size, frames, fps, codecs, length, loudness, file size. */
+const VERIFY_LOUDNESS_MS = 120 * 1000;   // the file is already saved; a long re-measure must not hold the reply
+async function verifyDeliveryOutput(sess, o, file) {
+  const failed = (text) => ({ ok: false, checks: [{ ok: false, text }], line: "⚠ " + text });
+  try {
+    const loudWanted = o.spec.audio.codec !== "none" && !!sess.wav;
+    const [probe, loud] = await Promise.all([ffprobeJSON(file), loudWanted ? measureLoudness(file, VERIFY_LOUDNESS_MS) : null]);
+    if (!probe) return failed("could not read the file back to check it (ffprobe)");
+    let size = 0;
+    try { size = fs.statSync(file).size; } catch {}
+    return Delivery.verify(o.spec, probe, {
+      fps: sess.fps, frames: sess.frames || (sess.duration ? Math.round(sess.duration * sess.fps) : null), duration: sess.duration,
+      size, loud, loudWanted, frame: o.frame, hasAudio: !!sess.wav,
+    });
+  } catch (e) { return failed("could not check the file: " + (e.message || e)); }
+}
+/** Spawn one ffmpeg per output of a delivery session. */
+function startDeliveryEncoders(sess) {
+  for (const o of sess.outputs) {
+    const proc = spawn("ffmpeg", Delivery.ffmpegArgs(o.spec, {
+      fps: sess.fps, input: sess.input, canvasW: sess.canvasW, canvasH: sess.canvasH, frame: o.frame,
+      wavPath: sess.wav, outPath: o.partPath, duration: sess.duration, loudnorm: o.loudnorm,
+    }), { stdio: ["pipe", "ignore", "pipe"] });
+    proc.stderr.on("data", (d) => { o.stderr = (o.stderr + d).slice(-2000); });
+    proc.stdin.on("error", () => { });
+    o.proc = proc;
+    o.done = new Promise((res) => proc.on("close", res));
+  }
+  sess.proc = sess.outputs[0].proc; // "started"
+}
+/** The same frames to every output still running. One that fails is marked and
+ *  left behind; the render goes on for the rest, and fails only when none is left. */
+async function writeDeliveryFrame(sess, body) {
+  const live = sess.outputs.filter((o) => !o.failed);
+  await Promise.all(live.map((o) => writeExportFrame(o, body).catch((e) => { o.failed = String(e.message || e); })));
+  if (!sess.outputs.some((o) => !o.failed))
+    throw new Error(sess.outputs.map((o) => `${path.basename(o.outPath)}: ${o.failed}`).join(" · "));
+}
 async function beginExport(fps, name, profileId, hasAudio, mode, extra = {}) {
   const m = mode === "annexb" ? "annexb" : "jpeg";
   const rate = Number(fps);
@@ -222,6 +390,7 @@ async function beginExport(fps, name, profileId, hasAudio, mode, extra = {}) {
   if (pixelFormat === "rgba" && (width < 2 || height < 2)) {
     throw new Error("export width/height required for rgba");
   }
+  if (m === "jpeg" && (extra.delivery || extra.deliveries)) return beginDeliveryExport(rate, name, hasAudio, extra);
   const id = Date.now().toString(36) + Math.random().toString(36).slice(2, 7);
   const safe = safeName(name || "export");
   // Same filesystem as the finished file so renameSync(partPath, out) cannot EXDEV.
@@ -263,10 +432,12 @@ async function beginExport(fps, name, profileId, hasAudio, mode, extra = {}) {
 /* Encode into the paths reserved at /begin; rename .part → final on clean exit
    so an aborted render never leaves something that looks like a finished file. */
 function startEncoder(sess) {
-  const proc = spawn("ffmpeg", buildExportArgs(sess.profile, {
+  if (sess.outputs) return startDeliveryEncoders(sess);
+  const args = buildExportArgs(sess.profile, {
     fps: sess.fps, wavPath: sess.wav, outPath: sess.partPath,
     pixelFormat: sess.pixelFormat, width: sess.width, height: sess.height,
-  }), { stdio: ["pipe", "ignore", "pipe"] });
+  });
+  const proc = spawn("ffmpeg", args, { stdio: ["pipe", "ignore", "pipe"] });
   proc.stderr.on("data", (d) => { sess.stderr = (sess.stderr + d).slice(-2000); });
   // EPIPE on end()/late writes is normal once ffmpeg has exited; writeExportFrame
   // attaches its own error listener while a backpressured write is in flight.
@@ -332,6 +503,10 @@ function cleanupExport(id) {
   if (!s) return;
   exportSessions.delete(id);
   try { s.proc?.kill(); } catch {}
+  for (const o of s.outputs || []) {
+    try { o.proc?.kill(); } catch {}
+    if (o.partPath) try { fs.rmSync(o.partPath, { force: true }); } catch {}
+  }
   try { fs.rmSync(s.dir, { recursive: true, force: true }); } catch {}
   if (s.partPath) try { fs.rmSync(s.partPath, { force: true }); } catch {}
 }
@@ -443,6 +618,91 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
+  /* API: media metadata (ffprobe; size only without it).
+       GET  /api/media-info?src=/media/x.mp4 → {src, info} (info null = file missing)
+       POST /api/media-info {srcs:[…], stat?} → {info:{src: info | null}} — up to 2000 per call;
+       stat:true answers {size, mtimeMs} without ffprobe (the editor's offline check) */
+  if (p === "/api/media-info" && (req.method === "GET" || req.method === "POST")) {
+    try {
+      if (req.method === "GET") {
+        const src = url.searchParams.get("src") || "";
+        const file = resolveSrc(src);
+        sendJSON(res, 200, { src, info: file ? await probeFile(file) : null });
+        return;
+      }
+      const body = JSON.parse((await readBody(req)).toString("utf8") || "{}");
+      const srcs = Array.isArray(body.srcs) ? body.srcs.slice(0, 2000).map(String) : [];
+      const info = Object.create(null);   // any src is a plain key, "__proto__" too
+      // probed side by side (media-probe.js caps how many ffprobes run at once)
+      await Promise.all(srcs.map(async (src) => {
+        const file = resolveSrc(src);
+        if (!file) { info[src] = null; return; }
+        // stat:true only asks "is it there?" (offline checks) — no ffprobe
+        if (body.stat) { const st = await fs.promises.stat(file); info[src] = { size: st.size, mtimeMs: Math.round(st.mtimeMs) }; }
+        else info[src] = await probeFile(file);
+      }));
+      sendJSON(res, 200, { info });
+    } catch (e) { sendJSON(res, 400, { error: String(e.message || e) }); }
+    return;
+  }
+
+  /* API: where might a missing file be now? Body {media:[{id, name, size?}]} →
+     {candidates:{id:[{src, name, size, score, why}]}} — files under media/ and
+     library/ ranked by name and size (MediaLib.relinkScore), best first, at most 5 each. */
+  if (p === "/api/relink/candidates" && req.method === "POST") {
+    try {
+      const body = JSON.parse((await readBody(req)).toString("utf8") || "{}");
+      const want = Array.isArray(body.media) ? body.media.slice(0, 2000) : [];
+      const files = [];
+      const walk = (root, prefix, d, depth) => {
+        let list = [];
+        try { list = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+        for (const e of list) {
+          if (e.name.startsWith(".")) continue;
+          const full = path.join(d, e.name);
+          if (e.isDirectory()) { if (depth < 6 && !(root === LIBRARY_DIR && /^(presets|templates|fonts)$/.test(e.name) && depth === 0)) walk(root, prefix, full, depth + 1); continue; }
+          let size = 0;
+          try { size = fs.statSync(full).size; } catch { continue; }
+          const rel = path.relative(root, full).split(path.sep).map(encodeURIComponent).join("/");
+          files.push({ src: prefix + rel, name: e.name, size });
+        }
+      };
+      walk(MEDIA_DIR, "/media/", MEDIA_DIR, 0);
+      walk(LIBRARY_DIR, "/library/", LIBRARY_DIR, 0);
+      const candidates = Object.create(null);
+      for (const m of want) {
+        if (!m || !m.id) continue;
+        candidates[m.id] = files.map((f) => ({ ...f, ...MediaLib.relinkScore(m, f) }))
+          .filter((f) => f.score > 0).sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, 5);
+      }
+      sendJSON(res, 200, { candidates });
+    } catch (e) { sendJSON(res, 400, { error: String(e.message || e) }); }
+    return;
+  }
+
+  /* API: proxies (see proxy.js).
+       POST /api/proxy {srcs:[…], height?:540|720|1080} → {status:{src: status}} — queue them
+       POST /api/proxy/status {srcs:[…]} → {status:{src: status | null}}
+       POST /api/proxy/delete {srcs:[…]} → {deleted:{src: n}}
+     Progress and results also arrive as SSE event "proxy". */
+  if ((p === "/api/proxy" || p === "/api/proxy/status" || p === "/api/proxy/delete") && req.method === "POST") {
+    try {
+      const body = JSON.parse((await readBody(req)).toString("utf8") || "{}");
+      const srcs = Array.isArray(body.srcs) ? body.srcs.slice(0, 2000).map(String) : [];
+      if (p === "/api/proxy/delete") {
+        const deleted = {};
+        for (const src of srcs) deleted[src] = proxies.remove(src);
+        sendJSON(res, 200, { deleted });
+        return;
+      }
+      if (p === "/api/proxy" && !HAS_FFMPEG) { sendJSON(res, 503, { error: "proxies need ffmpeg on PATH" }); return; }
+      const status = {};
+      for (const src of srcs) status[src] = p === "/api/proxy" ? await proxies.start(src, body.height) : await proxies.status(src);
+      sendJSON(res, 200, { status });
+    } catch (e) { sendJSON(res, 400, { error: String(e.message || e) }); }
+    return;
+  }
+
   /* API: default-asset library listing (./library/{sfx,elements,svg,fonts}) */
   if (p === "/api/library" && req.method === "GET") {
     const dir = url.searchParams.get("dir");
@@ -537,9 +797,39 @@ const server = http.createServer(async (req, res) => {
       const opts = JSON.parse((await readBody(req)).toString("utf8") || "{}");
       if (!HAS_FFMPEG) { sendJSON(res, 400, { error: "ffmpeg not found on PATH — export needs it" }); return; }
       if (opts.profile) resolveProfile(String(opts.profile));
+      if (opts.profile && (opts.preset || opts.delivery || opts.outputs)) { sendJSON(res, 400, { error: "pass a profile (raw ffmpeg args) or a preset / delivery spec / outputs, not both" }); return; }
+      // several files from one render: outputs:true = the project's checked batch outputs, or a list of specs
+      let deliveries = null, outNotes = [];
+      if (opts.outputs) {
+        let list = opts.outputs;
+        if (list === true) {
+          let proj = {};
+          try { proj = JSON.parse(fs.readFileSync(PROJECT_FILE, "utf8").replace(/^\uFEFF/, "")); } catch {}
+          list = (Array.isArray(proj.outputs) ? proj.outputs : []).filter((o) => o && o.on !== false);
+          if (!list.length) { sendJSON(res, 400, { error: "the project has no checked batch outputs — pass outputs:[{preset…}, …], or add some with setProject {outputs}" }); return; }
+        }
+        if (!Array.isArray(list) || !list.length) { sendJSON(res, 400, { error: "outputs is true or a list of delivery specs" }); return; }
+        if (list.length > 16) { sendJSON(res, 400, { error: "at most 16 outputs" }); return; }
+        const available = await deliveryEncoders(), presets = savedDeliveryPresets();
+        deliveries = list.map((o, i) => {
+          const n = Delivery.normalize(typeof o === "string" ? o : o, { available, presets });
+          for (const note of n.notes) outNotes.push(`output ${i + 1}: ${note}`);
+          return n.spec;
+        });
+      }
+      // a delivery preset with overrides → one complete spec, checked against this ffmpeg
+      let delivery = null, notes = [];
+      if (opts.preset || opts.delivery) {
+        const d = opts.delivery && typeof opts.delivery === "object" ? opts.delivery : {};
+        const n = Delivery.normalize({ ...d, preset: opts.preset || d.preset || undefined },
+          { available: await deliveryEncoders(), presets: savedDeliveryPresets() });
+        delivery = n.spec; notes = n.notes;
+      }
       let revision = null;
       try { revision = JSON.parse(fs.readFileSync(PROJECT_FILE, "utf8").replace(/^\uFEFF/, "")).revision ?? null; } catch {}
-      sendJSON(res, 200, exportJobs.request({ range: opts.range, profile: opts.profile, where: opts.where, revision }));
+      const job = exportJobs.request({ range: opts.range, profile: opts.profile, delivery: deliveries ? null : delivery, deliveries, where: opts.where, revision });
+      sendJSON(res, 200, deliveries ? { ...job, delivery: `${deliveries.length} outputs from one render`, notes: outNotes }
+        : delivery ? { ...job, delivery: Delivery.describe(delivery), notes } : job);
     } catch (e) {
       const code = e.code === 409 || e.code === 400 ? e.code : /^Unknown encoding profile/.test(e.message || "") ? 400 : 500;
       sendJSON(res, code, { error: String(e.message || e) });
@@ -564,7 +854,7 @@ const server = http.createServer(async (req, res) => {
       if (mk != null && (typeof mk !== "object" || typeof mk.clip !== "string")) {
         sendJSON(res, 400, { error: "mask must be {clip: \"<clip id>\"}" }); return;
       }
-      sendJSON(res, 200, exportJobs.request({ kind: "scopes", time, where: opts.where, revision, matte: m || null, mask: mk || null }));
+      sendJSON(res, 200, exportJobs.request({ kind: "scopes", time, where: opts.where, revision, matte: m || null, mask: mk || null, image: opts.image === true }));
     } catch (e) {
       sendJSON(res, e.code === 409 || e.code === 400 ? e.code : 500, { error: String(e.message || e) });
     }
@@ -618,6 +908,40 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { sendJSON(res, 500, { error: String(e) }); }
     return;
   }
+  /* API: delivery presets — GET lists the saved ones and the encoders this
+     ffmpeg can use (the built-in presets live in delivery.js, which the page
+     loads too); POST {name, spec} saves one to library/delivery/; POST
+     /api/export/presets/delete {id} removes it. */
+  if (p === "/api/export/presets" && req.method === "GET") {
+    const encoders = [...(await deliveryEncoders())].filter((e) => Delivery.ENCODERS[e]).sort();
+    sendJSON(res, 200, { ffmpeg: HAS_FFMPEG, encoders, saved: savedDeliveryPresets(), builtin: Delivery.PRESET_IDS });
+    return;
+  }
+  if ((p === "/api/export/presets" || p === "/api/export/presets/delete") && req.method === "POST") {
+    try {
+      const opts = JSON.parse((await readBody(req)).toString("utf8") || "{}");
+      if (p.endsWith("/delete")) {
+        const id = Delivery.presetId(opts.id);
+        const file = path.join(LIBRARY_DIR, "delivery", id + ".json");
+        if (!id || !fs.existsSync(file)) { sendJSON(res, 404, { error: "no saved delivery preset " + JSON.stringify(opts.id) }); return; }
+        fs.unlinkSync(file);
+        broadcast("delivery-presets");
+        sendJSON(res, 200, { ok: true, id });
+        return;
+      }
+      const label = String(opts.name || "").trim().slice(0, 60);
+      const id = Delivery.presetId(label);
+      if (!id) { sendJSON(res, 400, { error: "name the preset (letters or digits)" }); return; }
+      if (Delivery.PRESETS[id]) { sendJSON(res, 400, { error: `"${label}" is a built-in preset — pick another name` }); return; }
+      // what the spec leaves out comes from the preset it names (built-in or saved), not from Custom
+      const { spec, notes } = Delivery.normalize(opts.spec || {}, { presets: savedDeliveryPresets() });
+      delete spec.preset;
+      writeSaved("delivery", id, { id, label, ...spec });
+      broadcast("delivery-presets");
+      sendJSON(res, 200, { ok: true, id, label, notes });
+    } catch (e) { sendJSON(res, 400, { error: String(e.message || e) }); }
+    return;
+  }
   if (p === "/api/export/begin" && req.method === "POST") {
     try {
       const opts = JSON.parse((await readBody(req)).toString("utf8") || "{}");
@@ -627,7 +951,7 @@ const server = http.createServer(async (req, res) => {
       sendJSON(res, 200, await beginExport(opts.fps, opts.name, opts.profile, opts.hasAudio !== false, mode, opts));
     } catch (e) {
       // an unusable profile is the caller's problem, not a server fault
-      const bad = /^Unknown encoding profile|was rejected by ffmpeg|export fps required|export width\/height required/.test(e.message || "");
+      const bad = /^Unknown encoding profile|was rejected by ffmpeg|ffmpeg rejected these settings|at most \d+ outputs|deliveries is empty|render each frame rate separately|export fps required|export width\/height required/.test(e.message || "");
       sendJSON(res, bad ? 400 : 500, { error: String(e.message || e) });
     }
     return;
@@ -646,7 +970,7 @@ const server = http.createServer(async (req, res) => {
       // queue behind any in-flight write so concurrent POSTs cannot interleave stdin
       const run = async () => {
         if (!sess.proc) sess.mode === "annexb" ? startAnnexbEncoder(sess) : startEncoder(sess);
-        await writeExportFrame(sess, body);
+        await (sess.outputs ? writeDeliveryFrame(sess, body) : writeExportFrame(sess, body));
       };
       const writeJob = sess.writeLock.then(run, run);
       sess.writeLock = writeJob.catch(() => {}); // keep the chain alive after a failed write
@@ -665,6 +989,14 @@ const server = http.createServer(async (req, res) => {
     try {
       const wavPath = path.join(sess.dir, "audio.wav");
       fs.writeFileSync(wavPath, await readBody(req));
+      // outputs that normalize loudness need the mix measured (loudnorm pass one) before ffmpeg starts
+      const byTarget = new Map();
+      for (const o of sess.outputs || []) {
+        if (o.spec.audio.loudness == null || o.spec.audio.codec === "none") continue;
+        const k = `${o.spec.audio.loudness}/${o.spec.audio.truePeak}`;
+        if (!byTarget.has(k)) byTarget.set(k, runFfmpeg(Delivery.LOUDNORM_ARGS(wavPath, o.spec), 10 * 60 * 1000).then((r) => Delivery.parseLoudnorm(r.stderr)));
+        o.loudnorm = await byTarget.get(k);
+      }
       sess.wav = wavPath;
       touchExport(sess);
       sendJSON(res, 200, { ok: true });
@@ -679,6 +1011,30 @@ const server = http.createServer(async (req, res) => {
       if (url.searchParams.get("discard")) { cleanupExport(id); sendJSON(res, 200, { ok: true }); return; }
       touchExport(sess); // keep alive through final mux
       if (!sess.proc) throw new Error("no frames were uploaded");
+      if (sess.outputs) {
+        // every output finishes on its own; the reply lists each file or why it failed
+        const results = await Promise.all(sess.outputs.map(async (o) => {
+          const file = path.basename(o.outPath);
+          if (!o.failed) {
+            o.proc.stdin.end();
+            const code = await o.done;
+            if (code !== 0) o.failed = "ffmpeg encode failed: " + o.err();
+          }
+          if (o.failed) return { file, ok: false, error: o.failed };
+          // a file that cannot be put in place fails alone; the others keep finishing
+          try { fs.renameSync(o.partPath, o.outPath); }
+          catch (e) { return { file, ok: false, error: "could not save the file: " + (e.message || e) }; }
+          o.partPath = null; // renamed — cleanup must not delete the finished file
+          const report = await verifyDeliveryOutput(sess, o, o.outPath);
+          return { file, ok: true, src: "/exports/" + encodeURIComponent(file), ...(report ? { report } : {}),
+            ...(o.loudnorm ? { mixLoudness: o.loudnorm.input_i } : {}) };
+        }));
+        cleanupExport(id);
+        const ok = results.filter((x) => x.ok);
+        if (!ok.length) throw new Error(results.map((x) => `${x.file}: ${x.error}`).join(" · "));
+        sendJSON(res, 200, { ok: true, src: ok[0].src, outputs: results });
+        return;
+      }
       sess.proc.stdin.end();
       const code = await sess.done;
       if (code !== 0) throw new Error("ffmpeg encode failed: " + sess.err());
@@ -723,6 +1079,127 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
+  /* API: one frame of a source clip, or an N-up contact sheet across it —
+     the "eyes" to go with /api/analyze's ears, so an agent can look at a
+     moment instead of guessing from an energy number. JPEG in, JPEG out.
+
+       GET /api/frame?src=/media/x.mp4&t=3.2[&w=768][&q=4]
+       GET /api/frame?src=/media/x.mp4&frames=12[&cols=][&from=0][&to=30][&w=320]
+     (cols omitted → the squarest layout: 6 frames give 3×2, 12 give 4×3)
+       GET /api/frame?path=C:\clips\x.mp4&t=3.2
+
+     `src` is a served /media/ or /library/ path. `path` is any readable path on
+     this machine — it does NOT copy the file into media/, because looking at a
+     clip must not change the user's project folder. `path` is answered only
+     with the `X-FableCut-Client: mcp` request header, which only the local MCP
+     client sends: without it a web page could otherwise probe which files
+     exist (`onload` vs `onerror`), make ffmpeg decode them, and fill the cache
+     below with junk. resolveSrc() remains the guard for anything that turns a
+     request string into a path inside a served root.
+
+     &text=1 returns JSON statistics instead of the image, for agents (or
+     models) that cannot see one. Needs ffmpeg on PATH.
+
+     Results are cached under analysis/frames/ by a hash of every argument, so
+     polling the same timestamp costs nothing and the mtime/size of the cached
+     file answers "did the source change underneath this?". The cache is capped
+     (500 files / 128 MB, oldest mtime first — see frame-cache.js), so no
+     combination of arguments can fill the disk. */
+  if (p === "/api/frame" && req.method === "GET") {
+    const pathArg = url.searchParams.get("path");
+    /* `path=` reads any file on this machine, so it is only answered for the
+       local MCP client, which proves itself with a custom header. An <img> or
+       <form> on a web page cannot set one, and a cross-site fetch() that sets
+       one needs a CORS preflight this server never grants — so a page in the
+       user's browser can neither render a frame nor probe which files exist
+       (a missing header is refused before the path is even resolved, so the
+       answer leaks nothing). `src=` needs no header: those files are already
+       served over HTTP at /media/ and /library/. */
+    if (pathArg && req.headers["x-fablecut-client"] !== "mcp") {
+      sendJSON(res, 403, { error: "path= needs the X-FableCut-Client: mcp request header — only the local MCP client may read files outside media/ and library/" });
+      return;
+    }
+    /* The path is resolved next: whether a file is readable never depends on
+       whether ffmpeg happens to be installed. */
+    const src = url.searchParams.get("src") || "";
+    const file = pathArg ? resolvePathArg(pathArg) : resolveSrc(src);
+    if (!file) {
+      sendJSON(res, 404, { error: pathArg
+        ? "path must be an existing file on this machine"
+        : "src must name an existing file under /media/ or /library/" });
+      return;
+    }
+    if (!HAS_FFMPEG) { sendJSON(res, 400, { error: "ffmpeg not found on PATH — frame extraction needs it" }); return; }
+    const num = (k, dflt) => {
+      const raw = url.searchParams.get(k);
+      if (raw === null || raw === "") return dflt;
+      const n = Number(raw);
+      if (!Number.isFinite(n)) throw new Error(`${k} must be a number`);
+      return n;
+    };
+    try {
+      fs.mkdirSync(FRAMES_DIR, { recursive: true });
+      const isSheet = url.searchParams.get("frames") != null;
+      const opts = isSheet
+        ? { frames: num("frames"), cols: num("cols", null), from: num("from", 0), to: num("to", undefined), width: num("w", 320), quality: url.searchParams.get("q") }
+        : { t: num("t", 0), width: num("w", 768), quality: url.searchParams.get("q") };
+      // Key on the source's identity + size + mtime so an overwritten file
+      // never serves a stale grab.
+      const st = fs.statSync(file);
+      const key = crypto.createHash("sha1")
+        .update(JSON.stringify([file, st.size, Math.round(st.mtimeMs), opts])).digest("hex");
+      const cache = path.join(FRAMES_DIR, key + ".jpg");
+      let meta = null;
+      try {
+        meta = JSON.parse(fs.readFileSync(cache.replace(/\.jpg$/, ".json"), "utf8"));
+      } catch { /* render below */ }
+      // Self-healing: if the JPEG exists but meta doesn't, re-render so both are
+      // written together. A partial write (JPEG with no meta) otherwise serves
+      // 500 forever because meta stays null.
+      if (!fs.existsSync(cache) || !meta) {
+        const r = isSheet ? await frameGrid(file, opts) : await frame(file, opts);
+        meta = isSheet
+          ? { frames: r.frames, cols: r.cols, rows: r.rows, times: r.times, duration: r.duration, cellWidth: r.width, stats: r.stats }
+          : { frames: 1, times: [r.time], stats: r.stats };
+        meta.source = pathArg ? pathArg : src;
+        const tmp = cache + ".tmp";
+        fs.writeFileSync(tmp, r.jpeg);
+        fs.renameSync(tmp, cache); // atomic: a half-written jpeg never gets cached
+        fs.writeFileSync(cache.replace(/\.jpg$/, ".json"), JSON.stringify(meta));
+        /* Bound the cache: every distinct argument set mints a file, so cap
+           the directory oldest-first rather than letting it grow forever. */
+        try { pruneCache(FRAMES_DIR); } catch { /* a prune failure is not the request's problem */ }
+      } else {
+        // Refresh LRU order so hot entries survive the prune above.
+        try { fs.utimesSync(cache, new Date(), new Date()); } catch {}
+      }
+      /* text=1 answers JSON measurements instead of the picture, for agents and
+         models that cannot see one. Same decode, no pixels over the wire. */
+      if (url.searchParams.get("text") === "1") {
+        sendJSON(res, 200, {
+          source: meta.source, frames: meta.frames, times: meta.times,
+          cols: meta.cols || null, rows: meta.rows || null, duration: meta.duration ?? null,
+          stats: meta.stats || null,
+        });
+        return;
+      }
+      res.writeHead(200, {
+        "Content-Type": "image/jpeg",
+        "Content-Length": fs.statSync(cache).size,
+        "Cache-Control": "no-cache",
+        "X-FableCut-Frame-Times": (meta.times || []).join(","),
+        "X-FableCut-Frame-Source": encodeURI(meta.source || src),
+      });
+      fs.createReadStream(cache).pipe(res);
+    } catch (e) {
+      const msg = e && e.message ? e.message : String(e);
+      /* A bad argument, a missing file, or a timestamp past the end is the
+         caller's problem; anything else is ours. */
+      sendJSON(res, /must be|File not found|no video|no frame|past the end/.test(msg) ? 400 : 500, { error: msg });
+    }
+    return;
+  }
+
   /* API: noise reduction — POST {src:"/media/…"|"/library/…", amount:"light"|"medium"|"strong"}
      writes a denoised FLAC of the whole file into media/ (reused if it exists)
      and returns {src, name, duration, channels}. Registering it is the caller's job. */
@@ -731,11 +1208,8 @@ const server = http.createServer(async (req, res) => {
     try {
       const opts = JSON.parse((await readBody(req)).toString("utf8") || "{}");
       if (!DENOISE_AMOUNTS.includes(opts.amount)) { sendJSON(res, 400, { error: `amount must be one of ${DENOISE_AMOUNTS.join(", ")}` }); return; }
-      const src = decodeURIComponent(String(opts.src || "").split("?")[0]);
-      const [root, rel] = src.startsWith("/media/") ? [MEDIA_DIR, src.slice(7)]
-        : src.startsWith("/library/") ? [LIBRARY_DIR, src.slice(9)] : [null, null];
-      const file = root && path.normalize(path.join(root, rel));
-      if (!file || !file.startsWith(path.normalize(root + path.sep)) || !fs.existsSync(file)) {
+      const file = resolveSrc(opts.src);
+      if (!file) {
         sendJSON(res, 404, { error: "src must name an existing file under /media/ or /library/" });
         return;
       }
@@ -757,9 +1231,18 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
-  /* Media files */
+  /* Media files (subfolders too — relinked footage can sit in one) */
   if (p.startsWith("/media/")) {
-    const file = path.join(MEDIA_DIR, path.basename(p));
+    const file = path.normalize(path.join(MEDIA_DIR, p.slice("/media/".length)));
+    if (!file.startsWith(MEDIA_DIR + path.sep)) { res.writeHead(403); res.end(); return; }
+    serveFile(req, res, file);
+    return;
+  }
+
+  /* Proxies (analysis/proxies) */
+  if (p.startsWith("/proxies/")) {
+    const file = proxies.file(p.slice("/proxies/".length));
+    if (!file) { res.writeHead(404); res.end(); return; }
     serveFile(req, res, file);
     return;
   }