@pixerate/editor 0.89.0 → 0.91.0

package/dist/video-editor/index.js

@@ -852,12 +852,33 @@ function parseVideoAsset(v, path = "asset") {
     height: num(v.height, `${path}.height`, { optional: true, positive: true }),
     hasAudio: bool(v.hasAudio, `${path}.hasAudio`),
     poster: str(v.poster, `${path}.poster`, true),
-    transcript: parseVideoTranscriptWords(v.transcript, `${path}.transcript`)
+    transcript: parseVideoTranscriptWords(v.transcript, `${path}.transcript`),
+    proxies: parseVideoAssetProxies(v.proxies, `${path}.proxies`)
   });
+  if (kind !== "video" && asset.proxies) fail(`${path}.proxies`, "are only for video assets");
   if (kind === "image" && asset.transcript) fail(`${path}.transcript`, "is only for video and audio assets");
   if (kind === "image" && asset.duration !== void 0) fail(`${path}.duration`, "is only for video and audio assets");
   return asset;
 }
+function parseVideoAssetProxies(v, path) {
+  if (v === void 0) return void 0;
+  if (!Array.isArray(v)) return fail(path, "must be a list of { scale, src }");
+  const out = v.map((p, i) => {
+    const at = `${path}[${i}]`;
+    if (!isObject(p)) return fail(at, "must be an object { scale, src }");
+    const unknown = Object.keys(p).find((k) => !["scale", "src", "width", "height"].includes(k));
+    if (unknown) fail(`${at}.${unknown}`, "is not a proxy setting; use scale, src, width, height");
+    const scale = num(p.scale, `${at}.scale`, { positive: true });
+    if (scale >= 1) fail(`${at}.scale`, "must be less than 1 (0.5 is half size)");
+    return compact({ scale, src: str(p.src, `${at}.src`), width: num(p.width, `${at}.width`, { optional: true, positive: true }), height: num(p.height, `${at}.height`, { optional: true, positive: true }) });
+  });
+  const scales = /* @__PURE__ */ new Set();
+  for (const [i, p] of out.entries()) {
+    if (scales.has(p.scale)) fail(`${path}[${i}].scale`, `repeats ${p.scale}; give each proxy its own scale`);
+    scales.add(p.scale);
+  }
+  return out.length ? out : void 0;
+}
 function parseVideoClip(v, path = "clip") {
   if (!isObject(v)) return fail(path, "must be an object");
   const type = oneOf(v.type ?? "media", VIDEO_CLIP_TYPES, `${path}.type`, false);
@@ -3219,7 +3240,7 @@ var color = (c) => {
   const h = hex[1].length === 3 ? [...hex[1]].map((x) => x + x).join("") : hex[1];
   return `0x${h.slice(0, 6)}${h.length === 8 ? `@${(parseInt(h.slice(6), 16) / 255).toFixed(3)}` : ""}`;
 };
-var shellQuote = (s) => /^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+var videoShellQuote = (s) => /^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
 function atempo(speed) {
   const out = [];
   let s = speed;
@@ -3515,7 +3536,7 @@ function buildFfmpeg(project, options, measure) {
   const filterComplex = graph.join(";");
   if (measure) {
     const args2 = ["-hide_banner", "-nostats", ...inputs.flat(), "-filter_complex", filterComplex, "-map", "[aout]", "-f", "null", "-"];
-    return { args: args2, command: ["ffmpeg", ...args2].map(shellQuote).join(" "), filterComplex, duration: D, notes };
+    return { args: args2, command: ["ffmpeg", ...args2].map(videoShellQuote).join(" "), filterComplex, duration: D, notes };
   }
   const args = [
     "-y",
@@ -3536,7 +3557,333 @@ function buildFfmpeg(project, options, measure) {
     sec(D),
     options.output ?? "output.mp4"
   ];
-  return { args, command: ["ffmpeg", ...args].map(shellQuote).join(" "), filterComplex, duration: D, notes };
+  return { args, command: ["ffmpeg", ...args].map(videoShellQuote).join(" "), filterComplex, duration: D, notes };
+}
+
+// src/video-editor/proxy.ts
+var VIDEO_PROXY_SCALES = [0.5, 0.25];
+function videoAssetProxy(asset, scale) {
+  if (!asset?.proxies?.length || !(scale > 0) || scale >= 1) return null;
+  let best = null;
+  for (const p of asset.proxies) if (p.scale >= scale - 1e-9 && p.scale < 1 && (!best || p.scale < best.scale)) best = p;
+  return best;
+}
+var videoPreviewSrc = (asset, scale, fallback = asset?.src ?? "") => videoAssetProxy(asset, scale)?.src ?? fallback;
+function resolveVideoPreviewScale(scale, shown) {
+  if (scale === void 0 || scale === "auto") return Math.min(1, Math.max(0, shown));
+  if (scale === "full") return 1;
+  return Math.min(1, Math.max(0, scale));
+}
+function videoProxyName(src, scale = 0.5) {
+  const clean = src.replace(/[?#].*$/, "");
+  const base = clean.replace(/\.[^./\\]+$/, "");
+  return `${base}.proxy-${Math.round(scale * 100)}.mp4`;
+}
+function videoProxyFfmpeg(asset, options = {}) {
+  if (asset.kind !== "video") throw new Error(`Asset "${asset.id}" is ${asset.kind === "image" ? "an image" : "audio"}; only video assets have proxies.`);
+  const scale = options.scale ?? 0.5;
+  if (!(scale > 0 && scale < 1)) throw new Error(`A proxy's scale must be between 0 and 1 (not including either), not ${scale}; 0.5 is half size.`);
+  const gop = Math.max(1, Math.round(options.gop ?? 12));
+  const output = options.output ?? videoProxyName(asset.src, scale);
+  const src = options.resolve ? options.resolve(asset) : asset.src;
+  const size = `scale=trunc(iw*${scale}/2)*2:trunc(ih*${scale}/2)*2`;
+  const args = [
+    "-y",
+    "-i",
+    src,
+    "-vf",
+    size,
+    "-c:v",
+    "libx264",
+    "-preset",
+    "veryfast",
+    "-tune",
+    "fastdecode",
+    "-crf",
+    String(options.crf ?? 28),
+    "-g",
+    String(gop),
+    "-keyint_min",
+    String(gop),
+    "-sc_threshold",
+    "0",
+    "-bf",
+    "0",
+    "-pix_fmt",
+    "yuv420p",
+    ...asset.hasAudio === false ? ["-an"] : ["-c:a", "aac", "-b:a", "128k"],
+    "-movflags",
+    "+faststart",
+    output
+  ];
+  const proxy = { scale, src: output, ...asset.width && asset.height ? { width: Math.trunc(asset.width * scale / 2) * 2, height: Math.trunc(asset.height * scale / 2) * 2 } : {} };
+  return { asset: asset.id, args, command: ["ffmpeg", ...args].map(videoShellQuote).join(" "), proxy };
+}
+function videoProxyPlan(project, options = {}) {
+  const scale = options.scale ?? 0.5;
+  const wanted = options.assets ? new Set(options.assets) : null;
+  if (options.assets) for (const id of options.assets) {
+    const a = project.assets.find((x) => x.id === id);
+    if (!a) throw new Error(`There is no asset "${id}"; the assets are ${project.assets.map((x) => `"${x.id}"`).join(", ") || "none"}.`);
+    if (a.kind !== "video") throw new Error(`Asset "${id}" is ${a.kind === "image" ? "an image" : "audio"}; only video assets have proxies.`);
+  }
+  return project.assets.filter((a) => a.kind === "video" && (!wanted || wanted.has(a.id)) && !a.proxies?.some((p) => Math.abs(p.scale - scale) < 1e-9)).map((a) => videoProxyFfmpeg(a, { ...options, scale }));
+}
+var VIDEO_PREVIEW_SCALE_OPTIONS = [
+  { value: "auto", label: "Auto", scale: "auto" },
+  { value: "full", label: "Full", scale: "full" },
+  ...VIDEO_PROXY_SCALES.map((s) => ({ value: String(s), label: s === 0.5 ? "\xBD" : s === 0.25 ? "\xBC" : `${s * 100}%`, scale: s }))
+];
+var parseVideoPreviewScale = (value) => value === "full" ? "full" : Number(value) > 0 && Number(value) <= 1 ? Number(value) : "auto";
+var videoProjectHasProxies = (project) => project.assets.some((a) => !!a.proxies?.length);
+
+// src/video-editor/frame-cache.ts
+var videoSourceFrame = (sourceTime, fps) => Math.max(0, Math.floor(sourceTime * fps / 1e3 + 1e-6));
+var videoSourceFrameTime = (frame, fps) => (frame + 0.5) * 1e3 / fps;
+var videoFrameCacheKey = (src, frame) => `${frame}@${src}`;
+function videoFrameRequestsAt(project, time, srcFor = (l) => l.src) {
+  const out = [];
+  for (const layer of videoFrameAt(project, time).layers) {
+    if (layer.type !== "media" || layer.assetKind !== "video") continue;
+    const src = srcFor(layer);
+    if (!src) continue;
+    const frame = videoSourceFrame(layer.sourceTime ?? 0, project.fps);
+    out.push({ key: videoFrameCacheKey(src, frame), src, frame, sourceTime: videoSourceFrameTime(frame, project.fps), time });
+  }
+  return out;
+}
+function planVideoPrefetch(project, time, options = {}) {
+  const window2 = options.window ?? 2e3;
+  const dir = options.direction ?? 1;
+  const step = 1e3 / project.fps;
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (let i = 0; i * step <= window2 + 1e-6; i++) {
+    const t = time + dir * i * step;
+    if (t < 0) break;
+    for (const r of videoFrameRequestsAt(project, t, options.srcFor)) {
+      if (seen.has(r.key)) continue;
+      seen.add(r.key);
+      out.push(r);
+    }
+  }
+  return out;
+}
+function videoCacheEvictions(entries, options) {
+  let total = entries.reduce((n2, e) => n2 + e.bytes, 0);
+  if (total <= options.maxBytes) return [];
+  const dir = options.direction ?? 1;
+  const behind = options.behind ?? 2;
+  const cost = (e) => {
+    const d = (e.time - options.playhead) * dir;
+    return d >= 0 ? d : -d * behind;
+  };
+  const out = [];
+  for (const e of entries.filter((x) => !options.protect?.has(x.key)).sort((a, b) => cost(b) - cost(a))) {
+    if (total <= options.maxBytes) break;
+    out.push(e.key);
+    total -= e.bytes;
+  }
+  return out;
+}
+var defaultCapture = async (source) => {
+  if (typeof createImageBitmap !== "function") return null;
+  const image = await createImageBitmap(source);
+  return { image, width: image.width, height: image.height };
+};
+var VideoFrameCache = class {
+  constructor(options = {}) {
+    this.options = options;
+    this.maxBytes = options.maxBytes ?? 512 * 1024 * 1024;
+    this.prefetch = options.prefetch ?? 2e3;
+    this.decode = options.decode !== void 0 ? options.decode : typeof document !== "undefined" ? createVideoElementDecoder() : null;
+  }
+  options;
+  entries = /* @__PURE__ */ new Map();
+  inFlight = /* @__PURE__ */ new Set();
+  queue = [];
+  protect = /* @__PURE__ */ new Set();
+  listeners = /* @__PURE__ */ new Set();
+  playhead = 0;
+  direction = 1;
+  hits = 0;
+  misses = 0;
+  bytes = 0;
+  generation = 0;
+  destroyed = false;
+  srcFor;
+  maxBytes;
+  prefetch;
+  decode;
+  /** The cached frame of `src` showing at a source time (ms), on the project's `fps` grid. Counts a hit or a miss. */
+  get(src, sourceTime, fps) {
+    const entry = this.entries.get(videoFrameCacheKey(src, videoSourceFrame(sourceTime, fps)));
+    if (entry) this.hits++;
+    else this.misses++;
+    return entry?.frame.image;
+  }
+  /** Whether a frame is cached, without counting it. */
+  has(src, sourceTime, fps) {
+    return this.entries.has(videoFrameCacheKey(src, videoSourceFrame(sourceTime, fps)));
+  }
+  /** Keeps a decoded frame (replacing any with the same key), then evicts to the budget. */
+  put(request, frame) {
+    if (this.destroyed) return void frame.image.close?.();
+    const old = this.entries.get(request.key);
+    if (old) this.drop(old);
+    const bytes = Math.max(1, frame.width * frame.height * 4);
+    this.entries.set(request.key, { key: request.key, time: request.time, bytes, frame });
+    this.bytes += bytes;
+    this.evict();
+    this.emit();
+  }
+  /** Keeps what a ready media element shows now as the frame of `src` at `sourceTime` (async; does nothing if it is cached). */
+  capture(src, sourceTime, fps, time, source) {
+    const frame = videoSourceFrame(sourceTime, fps);
+    const key = videoFrameCacheKey(src, frame);
+    if (this.entries.has(key) || this.inFlight.has(key)) return;
+    this.inFlight.add(key);
+    void (this.options.capture ?? defaultCapture)(source).then((f) => {
+      if (f) this.put({ key, time }, f);
+    }).catch(() => {
+    }).finally(() => this.inFlight.delete(key));
+  }
+  /**
+   * Follows the playhead: protects the prefetch window, evicts to the budget, and queues the
+   * window's missing frames for decoding (nearest first). `srcFor` gives the file a layer plays.
+   */
+  update(project, time, options = {}) {
+    if (this.destroyed) return;
+    this.direction = options.direction ?? (time < this.playhead && !options.playing ? -1 : 1);
+    this.playhead = time;
+    this.srcFor = options.srcFor;
+    const plan = this.prefetch > 0 ? planVideoPrefetch(project, time, { window: this.prefetch, direction: this.direction, srcFor: options.srcFor }) : videoFrameRequestsAt(project, time, options.srcFor);
+    this.protect = new Set(plan.map((r) => r.key));
+    for (const r of plan) {
+      const e = this.entries.get(r.key);
+      if (e) e.time = r.time;
+    }
+    this.evict();
+    this.generation++;
+    this.queue = this.decode ? plan.filter((r) => !this.entries.has(r.key) && !this.inFlight.has(r.key)) : [];
+    this.pump();
+  }
+  /**
+   * The stretches of the timeline whose video frames are all cached, between `from` and `to` (ms),
+   * for the files the preview last played (its `srcFor`, e.g. proxies) unless `srcFor` is given.
+   * `step` (ms, at least a frame) samples more coarsely.
+   */
+  cachedRanges(project, options = {}) {
+    const step = Math.max(1e3 / project.fps, options.step ?? 0);
+    const from = Math.max(0, options.from ?? 0);
+    const to = options.to ?? Math.max(...project.tracks.flatMap((t) => t.clips.map((c) => c.start + c.duration)), 0);
+    const out = [];
+    for (let t = from; t < to - 1e-6; t += step) {
+      const requests = videoFrameRequestsAt(project, t, options.srcFor ?? this.srcFor);
+      const cached = requests.length > 0 && requests.every((r) => this.entries.has(r.key));
+      const last = out[out.length - 1];
+      if (!cached) continue;
+      const end = Math.min(to, t + step);
+      if (last && Math.abs(last.end - t) < 1e-6) last.end = end;
+      else out.push({ start: t, end });
+    }
+    return out.map((r) => ({ start: Math.round(r.start * 10) / 10, end: Math.round(r.end * 10) / 10 }));
+  }
+  stats() {
+    return { frames: this.entries.size, bytes: this.bytes, maxBytes: this.maxBytes, hits: this.hits, misses: this.misses, pending: this.inFlight.size + this.queue.length, prefetch: this.prefetch };
+  }
+  /** Called when frames arrive or leave. */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /** Drops every frame (closing them) and the queue. */
+  clear() {
+    for (const e of [...this.entries.values()]) this.drop(e);
+    this.queue = [];
+    this.generation++;
+    this.emit();
+  }
+  /** Clears and stops decoding for good. */
+  destroy() {
+    this.clear();
+    this.destroyed = true;
+    this.listeners.clear();
+  }
+  pump() {
+    const limit = Math.max(1, this.options.concurrency ?? 2);
+    while (this.decode && this.inFlight.size < limit && this.queue.length) {
+      const r = this.queue.shift();
+      if (this.entries.has(r.key) || this.inFlight.has(r.key)) continue;
+      if (this.bytes >= this.maxBytes && [...this.entries.keys()].every((k) => this.protect.has(k))) {
+        this.queue = [];
+        break;
+      }
+      const generation = this.generation;
+      this.inFlight.add(r.key);
+      this.decode(r.src, r.sourceTime).then(
+        (frame) => {
+          this.inFlight.delete(r.key);
+          if (generation === this.generation || this.bytes + frame.width * frame.height * 4 <= this.maxBytes) this.put(r, frame);
+          else frame.image.close?.();
+        },
+        () => this.inFlight.delete(r.key)
+      ).finally(() => this.pump());
+    }
+  }
+  evict() {
+    const drop = videoCacheEvictions([...this.entries.values()], { playhead: this.playhead, maxBytes: this.maxBytes, direction: this.direction, behind: this.options.behind, protect: this.protect });
+    for (const key of drop) this.drop(this.entries.get(key));
+  }
+  drop(e) {
+    this.entries.delete(e.key);
+    this.bytes -= e.bytes;
+    e.frame.image.close?.();
+  }
+  emit() {
+    for (const l of [...this.listeners]) l();
+  }
+};
+function createVideoElementDecoder(options = {}) {
+  const videos = /* @__PURE__ */ new Map();
+  const make = options.createVideo ?? (() => {
+    const el = document.createElement("video");
+    el.muted = true;
+    el.preload = "auto";
+    el.crossOrigin = "anonymous";
+    el.playsInline = true;
+    return el;
+  });
+  const timeout = options.timeout ?? 5e3;
+  const once = (el, type) => new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`The video did not ${type} within ${timeout} ms.`)), timeout);
+    el.addEventListener(type, () => (clearTimeout(timer), resolve()), { once: true });
+    el.addEventListener("error", () => (clearTimeout(timer), reject(new Error("The video could not be loaded."))), { once: true });
+  });
+  return (src, sourceTime) => {
+    let v = videos.get(src);
+    if (!v) {
+      const el2 = make();
+      el2.src = src;
+      v = { el: el2, chain: el2.readyState >= 1 ? Promise.resolve() : once(el2, "loadedmetadata") };
+      videos.set(src, v);
+    }
+    const { el } = v;
+    const next = v.chain.then(async () => {
+      const presented = "requestVideoFrameCallback" in el ? new Promise((r) => el.requestVideoFrameCallback(() => r())) : null;
+      const seeked = once(el, "seeked");
+      el.currentTime = sourceTime / 1e3;
+      await seeked;
+      if (presented) await Promise.race([presented, new Promise((r) => setTimeout(r, 100))]);
+      const image = await createImageBitmap(el);
+      return { image, width: image.width, height: image.height };
+    });
+    v.chain = next.catch(() => {
+    });
+    return next;
+  };
 }
 
 // src/video-editor/preview.ts
@@ -3550,6 +3897,9 @@ var VideoPreviewEngine = class {
     this.lutCache = options.luts !== void 0 ? options.luts : source.luts ?? null;
     this.unsubscribeLuts = this.lutCache ? this.lutCache.subscribe(() => this.redraw()) : () => {
     };
+    this.frameCache = options.frameCache !== void 0 ? options.frameCache : source.frameCache ?? null;
+    this.unsubscribeFrames = this.frameCache ? this.frameCache.subscribe(() => this.redraw()) : () => {
+    };
     const pixels = options.pixels !== void 0 ? options.pixels : source.previewPixels;
     this.detachPixels = pixels ? pixels.attach(() => this.readPixels()) : () => {
     };
@@ -3572,6 +3922,11 @@ var VideoPreviewEngine = class {
   drawn = null;
   complete = true;
   lutCache;
+  frameCache;
+  unsubscribeFrames;
+  srcFor = (layer) => layer.src;
+  playing = false;
+  fps = 30;
   unsubscribeLuts;
   scratchCanvas;
   /** The canvas's pixels and the frame they show, or `null` when its context cannot be read. */
@@ -3622,8 +3977,15 @@ var VideoPreviewEngine = class {
   /** Brings the media elements in step with the editor and draws the frame. */
   update() {
     if (this.destroyed) return;
-    const { project, time, playing } = this.source.getState();
+    const state = this.source.getState();
+    const { project, time, playing } = state;
     const frame = videoFrameAt(project, time);
+    const scale = resolveVideoPreviewScale(this.options.previewScale ?? state.previewScale, this.resolutionFor(project.width));
+    const assets = new Map(project.assets.map((a) => [a.id, a]));
+    this.srcFor = (layer) => videoPreviewSrc(assets.get(layer.asset ?? ""), scale, layer.src);
+    this.playing = playing;
+    this.fps = project.fps;
+    this.frameCache?.update(project, time, { playing, srcFor: this.srcFor });
     const tolerance = (this.options.tolerance ?? 200) / 1e3;
     const active = /* @__PURE__ */ new Set();
     const sync = (clip, src, kind, sourceTime, speed, gain) => {
@@ -3650,7 +4012,7 @@ var VideoPreviewEngine = class {
     for (const layer of frame.layers) {
       if (layer.type !== "media" || layer.assetKind !== "video" || !layer.src) continue;
       const sound = sounding.get(layer.clip);
-      sync(layer.clip, layer.src, "video", layer.sourceTime ?? 0, sound?.speed ?? 1, sound ? sound.gain : null);
+      sync(layer.clip, this.srcFor(layer), "video", layer.sourceTime ?? 0, sound?.speed ?? 1, sound ? sound.gain : null);
       sounding.delete(layer.clip);
     }
     for (const a of sounding.values()) sync(a.clip, a.src, "audio", a.sourceTime, a.speed, a.gain);
@@ -3671,15 +4033,29 @@ var VideoPreviewEngine = class {
       return img.complete ? img : null;
     }
     const entry = this.media.get(layer.clip);
-    if (!entry || entry.media.readyState < 2) return null;
+    const ready = !!entry && entry.media.readyState >= 2;
+    const cache = this.frameCache;
+    const src = entry?.src ?? this.srcFor(layer);
+    const sourceTime = layer.sourceTime ?? 0;
+    if (cache && src && (!this.playing || !ready || entry.media.seeking)) {
+      const hit = cache.get(src, sourceTime, this.fps);
+      if (hit) return hit;
+    }
+    if (!ready) return null;
     if (entry.media.seeking) this.complete = false;
+    else if (cache && !this.playing) cache.capture(entry.src, sourceTime, this.fps, this.source.getState().time, entry.media);
     return entry.media;
   };
+  /** Canvas pixels per frame pixel: the option, else the displayed width at the device pixel ratio (at most 1). */
+  resolutionFor(frameWidth) {
+    if (this.options.resolution !== void 0) return this.options.resolution;
+    const shown = this.canvas.clientWidth || frameWidth;
+    const dpr = typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1;
+    return Math.min(1, shown * dpr / frameWidth);
+  }
   draw(frame) {
     if (!this.ctx) return;
-    const shown = this.canvas.clientWidth || frame.width;
-    const dpr = typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1;
-    const resolution = this.options.resolution ?? Math.min(1, shown * dpr / frame.width);
+    const resolution = this.resolutionFor(frame.width);
     const w = Math.max(1, Math.round(frame.width * resolution));
     const h = Math.max(1, Math.round(frame.height * resolution));
     if (this.canvas.width !== w) this.canvas.width = w;
@@ -3738,6 +4114,7 @@ var VideoPreviewEngine = class {
     this.destroyed = true;
     this.detachPixels();
     this.unsubscribeLuts();
+    this.unsubscribeFrames();
     this.filterHost?.remove();
     this.filterHost = null;
     this.filters.clear();
@@ -3757,10 +4134,13 @@ var VideoEditorController = class {
   previewPixels = new VideoPreviewPixels();
   /** Grades' LUTs, loaded on demand for the preview, SVG frames and agents. */
   luts;
+  /** The host's frame cache, if it gave one (the preview fills and reads it). */
+  frameCache;
   project;
   issues;
   selection = [];
   readOnly;
+  previewScale;
   error = null;
   revision = 0;
   applying = false;
@@ -3772,9 +4152,11 @@ var VideoEditorController = class {
     this.history = options.history ?? new HistoryManager();
     this.audioPeaks = options.audioPeaks instanceof VideoAudioPeaksCache ? options.audioPeaks : new VideoAudioPeaksCache(options.audioPeaks);
     this.luts = options.luts instanceof VideoLutCache ? options.luts : new VideoLutCache(options.luts);
+    this.frameCache = options.frameCache ?? null;
     this.project = options.project ? parseVideoProject(options.project) : createVideoProject();
     this.issues = checkVideoProject(this.project);
     this.readOnly = options.readOnly ?? false;
+    this.previewScale = checkPreviewScale(options.previewScale ?? "auto");
     this.onChange = options.onChange;
     this.player = new AnimationPlayer({ clock: options.clock, duration: () => videoProjectDuration(this.project), loop: "none" });
     this.state = this.computeState();
@@ -3824,6 +4206,7 @@ var VideoEditorController = class {
       canRedo: h.canRedo,
       undoLabel: h.undoName,
       redoLabel: h.redoName,
+      previewScale: this.previewScale,
       revision: this.revision
     };
   }
@@ -3913,6 +4296,17 @@ var VideoEditorController = class {
     this.readOnly = readOnly;
     this.notify();
   }
+  /**
+   * Sets how large a picture the preview plays: `full` (the originals), a fraction such as 0.5
+   * (the smallest proxy at least that large, else the original) or `auto` (as large as the canvas
+   * shows). A view setting, not part of the project: no undo step.
+   */
+  setPreviewScale(scale) {
+    const next = checkPreviewScale(scale);
+    if (next === this.previewScale) return;
+    this.previewScale = next;
+    this.notify();
+  }
   /** Selects clips (unknown ids are dropped). `add` toggles them into the current selection. */
   select(clips, options = {}) {
     const known = clips?.filter((id) => findVideoClip(this.project, id)) ?? [];
@@ -3997,6 +4391,11 @@ var VideoEditorController = class {
     return toVideoEdl(this.project, options);
   }
 };
+function checkPreviewScale(scale) {
+  if (scale === "auto" || scale === "full") return scale;
+  if (typeof scale !== "number" || !(scale > 0 && scale <= 1)) throw new Error(`A preview scale is "auto", "full" or a fraction above 0 up to 1 (0.5 is half size), not ${JSON.stringify(scale)}.`);
+  return scale === 1 ? "full" : scale;
+}
 
 // src/video-editor/ui.ts
 var STEPS = [40, 100, 200, 500, 1e3, 2e3, 5e3, 1e4, 15e3, 3e4, 6e4, 12e4, 3e5, 6e5];
@@ -4466,7 +4865,7 @@ function createVideoEditorToolProvider(controller, options = {}) {
     handler: () => {
       const state = controller.getState();
       const reason = readOnlyReason();
-      return { ...describeVideoProject(state.project), playhead: state.time, selection: state.selection, issues: issueSummary(state.issues), editable: !reason, ...reason ? { readOnlyReason: reason } : {} };
+      return { ...describeVideoProject(state.project), playhead: state.time, previewScale: state.previewScale, selection: state.selection, issues: issueSummary(state.issues), editable: !reason, ...reason ? { readOnlyReason: reason } : {} };
     }
   };
   const getFrame = {
@@ -4634,7 +5033,7 @@ function createVideoEditorToolProvider(controller, options = {}) {
     name: "update_video_asset",
     title: "Change media details",
     description: "Changes an asset's src, name, duration, size, sound or poster (e.g. relinking moved media). Clips that now run past its end are refused. Returns the asset.",
-    inputSchema: object({ asset: ASSET_ID, set: object(ASSET_FIELDS, [], "Fields to replace."), remove: { type: "array", items: { type: "string", enum: ["name", "duration", "width", "height", "hasAudio", "poster", "transcript"] }, description: "Fields to clear (transcript removes its words)." } }, ["asset"]),
+    inputSchema: object({ asset: ASSET_ID, set: object(ASSET_FIELDS, [], "Fields to replace."), remove: { type: "array", items: { type: "string", enum: ["name", "duration", "width", "height", "hasAudio", "poster", "transcript", "proxies"] }, description: "Fields to clear (transcript removes its words, proxies its proxies)." } }, ["asset"]),
     annotations: { title: "Change media details", ...WRITE_IDEMPOTENT },
     handler: ({ asset, set, remove }) => apply({ op: "update_asset", asset, set, remove }, "Change media", (r) => ({ asset: videoAssetOut(r.project.assets.find((a) => a.id === asset)) }))
   };
@@ -4832,6 +5231,79 @@ function createVideoEditorToolProvider(controller, options = {}) {
       return apply(videoLutEdits(p, withLut, null), "Remove LUT", (r) => ({ clips: clips.map((id) => ({ id, grade: findVideoClip(r.project, id)?.clip.grade ?? null })) }));
     }
   };
+  const PROXY_SCALE = { type: "number", exclusiveMinimum: 0, exclusiveMaximum: 1, description: "Proxy size as a fraction of the original: 0.5 (half width and height, the default) or 0.25 for very large footage." };
+  const planProxies = {
+    name: "plan_video_proxies",
+    title: "Plan proxy files",
+    description: 'Returns the ffmpeg commands that make smaller proxy copies of video assets for smooth preview playback, without changing anything: one per video asset (or each of "assets") that has no proxy at that scale yet, each with { asset, args, command, proxy }. Proxies are scaled, H.264 with a keyframe every few frames so scrubbing is quick, and keep the sound. After the host runs a command, attach its "proxy" with set_video_proxies. The export always uses the originals.',
+    inputSchema: object({
+      scale: PROXY_SCALE,
+      assets: { type: "array", items: ASSET_ID, minItems: 1, uniqueItems: true, description: "Only these video assets (default: every video asset without a proxy at this scale)." },
+      gop: { type: "integer", minimum: 1, maximum: 300, description: "Frames between keyframes (default 12): fewer makes seeking cheaper and files larger." },
+      crf: { type: "integer", minimum: 0, maximum: 51, description: "x264 quality, lower is better (default 28: proxies are for editing)." }
+    }),
+    annotations: { title: "Plan proxy files", ...READ },
+    handler: ({ scale, assets, gop, crf }) => {
+      const commands = videoProxyPlan(project(), { scale, assets, gop, crf });
+      return { scale: scale ?? 0.5, commands, ...commands.length ? {} : { note: "Every video asset already has a proxy at this scale." } };
+    }
+  };
+  const setProxies = {
+    name: "set_video_proxies",
+    title: "Attach proxies",
+    description: "Sets a video asset's proxies, the smaller copies the preview plays instead of the original (one undo step); an empty list removes them. Each proxy must match the original's length and timing (plan_video_proxies makes such files). The export, EDL and source times always use the original. Returns the asset.",
+    inputSchema: object(
+      {
+        asset: { ...ASSET_ID, description: "A video asset id from get_video_project." },
+        proxies: {
+          type: "array",
+          maxItems: 8,
+          description: "Its proxies, one per scale (empty removes them all).",
+          items: object({ scale: PROXY_SCALE, src: { type: "string", minLength: 1, description: "Where the preview loads the proxy from (URL or path)." }, width: { type: "number", exclusiveMinimum: 0, description: "Its width in pixels." }, height: { type: "number", exclusiveMinimum: 0, description: "Its height in pixels." } }, ["scale", "src"], "One proxy.")
+        }
+      },
+      ["asset", "proxies"]
+    ),
+    annotations: { title: "Attach proxies", ...WRITE_IDEMPOTENT },
+    handler: ({ asset, proxies }) => {
+      const a = project().assets.find((x) => x.id === asset);
+      if (!a) throw new Error(`There is no asset "${asset}"; the assets are ${project().assets.map((x) => `"${x.id}"`).join(", ") || "none"}.`);
+      if (a.kind !== "video") throw new Error(`Asset "${asset}" is ${a.kind === "image" ? "an image" : "audio"}; only video assets have proxies.`);
+      const edit = proxies.length ? { op: "update_asset", asset, set: { proxies } } : { op: "update_asset", asset, remove: ["proxies"] };
+      return apply(edit, proxies.length ? "Attach proxies" : "Remove proxies", (r) => ({ asset: videoAssetOut(r.project.assets.find((x) => x.id === asset)) }));
+    }
+  };
+  const setPreviewScale = {
+    name: "set_video_preview_scale",
+    title: "Set the preview size",
+    description: 'Sets how large a picture the preview plays, without changing the project (no undo step): "full" plays the originals, a fraction (0.5, 0.25) plays the smallest proxy at least that large (or the original where there is none), "auto" (the default) picks by the size the preview is shown at. Use a proxy scale when playback stutters on large footage. Returns the setting and, for each video asset, what the preview plays at a fixed scale.',
+    inputSchema: object(
+      { scale: { anyOf: [{ type: "string", enum: ["auto", "full"] }, { type: "number", exclusiveMinimum: 0, maximum: 1 }], description: '"auto", "full", or a fraction above 0 up to 1 (0.5 is half size).' } },
+      ["scale"]
+    ),
+    annotations: { title: "Set the preview size", ...WRITE_IDEMPOTENT },
+    handler: ({ scale }) => {
+      controller.setPreviewScale(scale);
+      const s = controller.getState().previewScale;
+      const fixed = s === "full" ? 1 : typeof s === "number" ? s : null;
+      const plays = fixed === null ? void 0 : project().assets.filter((a) => a.kind === "video").map((a) => ({ asset: a.id, src: videoAssetProxy(a, fixed)?.src ?? a.src, proxy: !!videoAssetProxy(a, fixed) }));
+      return { previewScale: s, ...plays ? { plays } : { note: "auto picks the smallest proxy at least as large as the preview canvas shows, so it depends on the preview's size." } };
+    }
+  };
+  const previewCache = {
+    name: "get_video_preview_cache",
+    title: "Read the preview's frame cache",
+    description: `Reports the preview's cache of decoded frames, without changing anything: whether the host has one, how many frames and bytes it holds against its budget, hits and misses, frames still decoding, how far ahead it prefetches (ms), and the stretches of the timeline between "from" and "to" whose frames are all cached (these play and scrub without waiting). Use it to tell whether stuttering is the cache filling, and before asking the person to review a passage. With no cache, says so.`,
+    inputSchema: object({ from: MS("Start of the stretch to report cached ranges for (default 0)"), to: MS("End of it (default: the end of the project)") }),
+    annotations: { title: "Read the preview's frame cache", ...READ },
+    handler: ({ from, to }) => {
+      const cache = controller.frameCache;
+      if (!cache) return { enabled: false, reason: "The host has not given this editor a frame cache (VideoEditorController frameCache), so the preview decodes each frame as it plays." };
+      if (from !== void 0 && to !== void 0 && !(to > from)) throw new Error(`"to" (${to} ms) must be after "from" (${from} ms).`);
+      const ranges = cache.cachedRanges(project(), { from, to });
+      return { enabled: true, ...cache.stats(), cachedRanges: ranges };
+    }
+  };
   const TRANSCRIPT_TRACK = { ...TRACK_ID, description: "Track whose words to read (default: the first audio track with a transcribed clip, else the first video track with one)." };
   const RANGE_OUT = (r) => ({ from: round(r.from), to: round(r.to), text: r.text });
   const timelineWords = (track) => {
@@ -5273,8 +5745,8 @@ function createVideoEditorToolProvider(controller, options = {}) {
       return { time: t, timecode: formatVideoTimecode(t, p.fps), width: pixels.width, height: pixels.height, ...summarizeVideoScopes(pixels, { bins, columns }) };
     }
   };
-  const reads = [getProject, getFrame, getTranscript, findText, findFillers, findPauses, findGaps, checkProject, renderFrame, getScopes, exportFfmpeg, exportLoudnessMeasure, exportEdl, audioLevels, findSilences, seek];
-  const writes = [setSettings, addAsset, updateAsset, removeAsset, addTrack, updateTrack, removeTrack, moveTrack, addClip, moveClip, trimClip, splitClip, deleteClips, updateClip, setTransition, setSpeedRamp, addFreeze, removeRamp, setTranscript, removeRanges, applyGradePreset, copyGrade, setLut, removeLut, setKeyframes, removeKeyframes, slipClip, rollEdit, slideClip, liftRange, extractRange, splitAt, closeGaps, addMarker, removeMarker, editVideo, undo, redo];
+  const reads = [getProject, getFrame, getTranscript, findText, findFillers, findPauses, findGaps, checkProject, renderFrame, getScopes, previewCache, planProxies, exportFfmpeg, exportLoudnessMeasure, exportEdl, audioLevels, findSilences, seek, setPreviewScale];
+  const writes = [setSettings, addAsset, updateAsset, removeAsset, setProxies, addTrack, updateTrack, removeTrack, moveTrack, addClip, moveClip, trimClip, splitClip, deleteClips, updateClip, setTransition, setSpeedRamp, addFreeze, removeRamp, setTranscript, removeRanges, applyGradePreset, copyGrade, setLut, removeLut, setKeyframes, removeKeyframes, slipClip, rollEdit, slideClip, liftRange, extractRange, splitAt, closeGaps, addMarker, removeMarker, editVideo, undo, redo];
   return {
     id: options.id ?? "video",
     namespace: options.namespace,
@@ -5315,6 +5787,8 @@ export {
   VIDEO_LUT_MAX_SIZE,
   VIDEO_PEAK_BLOCK,
   VIDEO_PLACEMENT_MODES,
+  VIDEO_PREVIEW_SCALE_OPTIONS,
+  VIDEO_PROXY_SCALES,
   VIDEO_SCOPE_KINDS,
   VIDEO_TIME_EPSILON,
   VIDEO_TRANSFORM_PROPERTIES,
@@ -5324,6 +5798,7 @@ export {
   VIDEO_WIPE_DIRECTIONS,
   VideoAudioPeaksCache,
   VideoEditorController,
+  VideoFrameCache,
   VideoLutCache,
   VideoPreviewEngine,
   VideoPreviewPixels,
@@ -5336,6 +5811,7 @@ export {
   checkVideoProject,
   checkVideoTimeRemap,
   createVideoEditorToolProvider,
+  createVideoElementDecoder,
   createVideoProject,
   decodeVideoAudioPeaks,
   describeVideoProject,
@@ -5359,6 +5835,7 @@ export {
   normalizeVideoWord,
   parseVideoAnimatable,
   parseVideoAsset,
+  parseVideoAssetProxies,
   parseVideoClip,
   parseVideoClipAnimation,
   parseVideoCubeLut,
@@ -5367,6 +5844,7 @@ export {
   parseVideoKeyframes,
   parseVideoLoudnessMeasurement,
   parseVideoMarker,
+  parseVideoPreviewScale,
   parseVideoProject,
   parseVideoTimeRemap,
   parseVideoTrack,
@@ -5376,9 +5854,11 @@ export {
   parseVideoTransition,
   placeVideoRect,
   planVideoClipDrag,
+  planVideoPrefetch,
   probeVideoMedia,
   readVideoScopesPanel,
   removeVideoKey,
+  resolveVideoPreviewScale,
   retimeVideoAnimatable,
   setVideoKey,
   snapToVideoFrame,
@@ -5394,10 +5874,12 @@ export {
   videoAssetHasSound,
   videoAssetKindOf,
   videoAssetMap,
+  videoAssetProxy,
   videoAudioLevels,
   videoAudioPeakRange,
   videoAudioPeakSpans,
   videoAudioPeaksDuration,
+  videoCacheEvictions,
   videoChroma,
   videoClipAfter,
   videoClipAnimated,
@@ -5428,7 +5910,9 @@ export {
   videoExposureStats,
   videoFadeCurveGain,
   videoFrameAt,
+  videoFrameCacheKey,
   videoFrameDuration,
+  videoFrameRequestsAt,
   videoFrameToSvg,
   videoFrames,
   videoFreezeFrameEdit,
@@ -5462,13 +5946,21 @@ export {
   videoLutToCube,
   videoOverlap,
   videoPeakDb,
+  videoPreviewSrc,
   videoProjectDuration,
+  videoProjectHasProxies,
   videoProjectSvg,
+  videoProxyFfmpeg,
+  videoProxyName,
+  videoProxyPlan,
   videoRemoveRangesEdits,
   videoRulerTicks,
   videoScopeImage,
+  videoShellQuote,
   videoSlowMotionRamp,
   videoSnapPoints,
+  videoSourceFrame,
+  videoSourceFrameTime,
   videoSpeedRampEdit,
   videoSpeedRampKeys,
   videoTextStyle,