@pixerate/editor 0.86.0 → 0.87.0

package/dist/video-editor/index.js

@@ -2124,6 +2124,379 @@ var VideoAudioPeaksCache = class {
   }
 };
 
+// src/video-editor/scopes.ts
+var VIDEO_SCOPE_KINDS = ["histogram", "waveform", "vectorscope"];
+var videoLuma = (r, g, b) => 0.2126 * r + 0.7152 * g + 0.0722 * b;
+function videoChroma(r, g, b) {
+  const y = videoLuma(r, g, b);
+  return [(b - y) / 1.8556, (r - y) / 1.5748];
+}
+function eachPixel(pixels, maxPixels, visit) {
+  const { width, height, data } = pixels;
+  if (!(width > 0 && height > 0) || data.length < width * height * 4) throw new Error(`The pixels are not ${width} \xD7 ${height} RGBA: there are ${data.length} values, and ${width * height * 4} are needed.`);
+  const step = Math.max(1, Math.sqrt(width * height / Math.max(1, maxPixels ?? 262144)));
+  let count = 0;
+  for (let fy = step / 2; fy < height; fy += step) {
+    const y = Math.floor(fy);
+    for (let fx = step / 2; fx < width; fx += step) {
+      const x = Math.floor(fx);
+      const i = (y * width + x) * 4;
+      visit(data[i], data[i + 1], data[i + 2], x, y);
+      count++;
+    }
+  }
+  return count;
+}
+var binOf = (v, bins) => Math.min(bins - 1, Math.floor((v + 1e-6) / 256 * bins));
+function videoHistogram(pixels, options = {}) {
+  const bins = Math.max(1, Math.min(256, Math.round(options.bins ?? 256)));
+  const out = { bins, r: Array(bins).fill(0), g: Array(bins).fill(0), b: Array(bins).fill(0), luma: Array(bins).fill(0), total: 0 };
+  out.total = eachPixel(pixels, options.maxPixels, (r, g, b) => {
+    out.r[binOf(r, bins)]++;
+    out.g[binOf(g, bins)]++;
+    out.b[binOf(b, bins)]++;
+    out.luma[binOf(videoLuma(r, g, b), bins)]++;
+  });
+  return out;
+}
+function videoLumaWaveform(pixels, options = {}) {
+  const columns = Math.max(1, Math.min(pixels.width, Math.round(options.columns ?? Math.min(pixels.width, 256))));
+  const levels = Math.max(2, Math.min(256, Math.round(options.levels ?? 128)));
+  const data = new Uint32Array(columns * levels);
+  let peak = 0;
+  eachPixel(pixels, options.maxPixels, (r, g, b, x) => {
+    const c = Math.min(columns - 1, Math.floor(x / pixels.width * columns));
+    const i = c * levels + binOf(videoLuma(r, g, b), levels);
+    if (++data[i] > peak) peak = data[i];
+  });
+  return { columns, levels, data, peak };
+}
+var videoVectorscopePoint = (cb, cr, size) => [(cb + 0.5) * (size - 1), (0.5 - cr) * (size - 1)];
+function videoVectorscope(pixels, options = {}) {
+  const size = Math.max(16, Math.min(512, Math.round(options.size ?? 128)));
+  const data = new Uint32Array(size * size);
+  let peak = 0;
+  eachPixel(pixels, options.maxPixels, (r, g, b) => {
+    const [cb, cr] = videoChroma(r / 255, g / 255, b / 255);
+    const [x, y] = videoVectorscopePoint(cb, cr, size);
+    const i = Math.round(y) * size + Math.round(x);
+    if (++data[i] > peak) peak = data[i];
+  });
+  return { size, data, peak };
+}
+var round3 = (v) => Math.round(v * 1e3) / 1e3;
+var hex2 = (v) => Math.round(Math.min(255, Math.max(0, v))).toString(16).padStart(2, "0");
+function videoExposureStats(pixels, options = {}) {
+  const low = (options.shadowLevel ?? 0.02) * 255;
+  const high = (options.highlightLevel ?? 0.98) * 255;
+  const lumaBins = new Uint32Array(256);
+  let sumY = 0;
+  let sumR = 0;
+  let sumG = 0;
+  let sumB = 0;
+  let sumSat = 0;
+  let maxSat = 0;
+  let shadows = 0;
+  let highlights = 0;
+  let cr = 0;
+  let cg = 0;
+  let cbl = 0;
+  const total = eachPixel(pixels, options.maxPixels, (r, g, b) => {
+    const y = videoLuma(r, g, b);
+    lumaBins[Math.min(255, Math.round(y))]++;
+    sumY += y;
+    sumR += r;
+    sumG += g;
+    sumB += b;
+    const [u, v] = videoChroma(r / 255, g / 255, b / 255);
+    const sat = Math.min(1, Math.hypot(u, v) / 0.5);
+    sumSat += sat;
+    if (sat > maxSat) maxSat = sat;
+    if (y <= low) shadows++;
+    if (y >= high) highlights++;
+    if (r >= high) cr++;
+    if (g >= high) cg++;
+    if (b >= high) cbl++;
+  });
+  const percentile = (p) => {
+    const target = p * total;
+    let seen = 0;
+    for (let i = 0; i < 256; i++) {
+      seen += lumaBins[i];
+      if (seen >= target && seen > 0) return i / 255;
+    }
+    return 1;
+  };
+  let min = 0;
+  while (min < 255 && !lumaBins[min]) min++;
+  let max = 255;
+  while (max > 0 && !lumaBins[max]) max--;
+  return {
+    pixels: total,
+    luma: { mean: round3(sumY / total / 255), median: round3(percentile(0.5)), min: round3(min / 255), max: round3(max / 255), p1: round3(percentile(0.01)), p99: round3(percentile(0.99)) },
+    clipped: { shadows: round3(shadows / total), highlights: round3(highlights / total), r: round3(cr / total), g: round3(cg / total), b: round3(cbl / total) },
+    saturation: { mean: round3(sumSat / total), max: round3(maxSat) },
+    average: `#${hex2(sumR / total)}${hex2(sumG / total)}${hex2(sumB / total)}`
+  };
+}
+function videoExposureNotes(stats) {
+  const notes = [];
+  const pct = (v2) => `${Math.round(v2 * 1e3) / 10}%`;
+  if (stats.clipped.shadows >= 0.05) notes.push(`${pct(stats.clipped.shadows)} of the picture is crushed to black; raise exposure or lower contrast.`);
+  if (stats.clipped.highlights >= 0.02) notes.push(`${pct(stats.clipped.highlights)} of the picture is blown to white; lower exposure.`);
+  else {
+    const channels = ["r", "g", "b"].filter((k) => stats.clipped[k] >= 0.05);
+    if (channels.length) notes.push(`The ${channels.map((k) => ({ r: "red", g: "green", b: "blue" })[k]).join(" and ")} channel${channels.length > 1 ? "s clip" : " clips"} in ${pct(Math.max(...channels.map((k) => stats.clipped[k])))} of the picture; lower exposure or saturation.`);
+  }
+  if (stats.luma.mean < 0.2 && stats.clipped.shadows < 0.05) notes.push(`The picture is dark (mean luma ${stats.luma.mean}); raise exposure if it is not meant to be.`);
+  if (stats.luma.mean > 0.75 && stats.clipped.highlights < 0.02) notes.push(`The picture is bright (mean luma ${stats.luma.mean}); lower exposure if it is not meant to be.`);
+  if (stats.luma.p99 - stats.luma.p1 < 0.3 && stats.pixels > 1) notes.push(`The picture is flat (most of it lies between luma ${stats.luma.p1} and ${stats.luma.p99}); raise contrast.`);
+  const [r, g, b] = [1, 3, 5].map((i) => parseInt(stats.average.slice(i, i + 2), 16) / 255);
+  const [u, v] = videoChroma(r, g, b);
+  if (Math.hypot(u, v) > 0.04 && stats.saturation.mean < 0.35) {
+    const warm = v - u;
+    notes.push(`The picture has a ${Math.abs(warm) > Math.abs(v + u) * 0.5 ? warm > 0 ? "warm (orange)" : "cool (blue)" : v > 0 ? "magenta" : "green"} cast (average ${stats.average}); adjust temperature and tint.`);
+  }
+  return notes;
+}
+var videoVectorscopeAngle = (cb, cr) => (Math.atan2(cr, cb) * 180 / Math.PI % 360 + 360) % 360;
+function summarizeVideoScopes(pixels, options = {}) {
+  const stats = videoExposureStats(pixels, options);
+  const bins = Math.max(2, Math.min(64, Math.round(options.bins ?? 16)));
+  const h = videoHistogram(pixels, { ...options, bins });
+  const share = (a) => a.map((v) => round3(v / h.total));
+  const columns = Math.max(1, Math.min(32, Math.round(options.columns ?? 8)));
+  const w = videoLumaWaveform(pixels, { ...options, columns, levels: 256 });
+  const waveform = Array.from({ length: w.columns }, (_, c) => {
+    const counts = w.data.subarray(c * 256, c * 256 + 256);
+    const n2 = counts.reduce((a, b) => a + b, 0);
+    let lo = 0;
+    while (lo < 255 && !counts[lo]) lo++;
+    let hi = 255;
+    while (hi > 0 && !counts[hi]) hi--;
+    let seen = 0;
+    let median = 0;
+    for (let i = 0; i < 256; i++) {
+      seen += counts[i];
+      if (seen >= n2 / 2 && n2) {
+        median = i;
+        break;
+      }
+    }
+    return { start: round3(c / w.columns), end: round3((c + 1) / w.columns), min: round3(lo / 255), median: round3(median / 255), max: round3(hi / 255) };
+  }).filter((_, c) => w.data.subarray(c * 256, c * 256 + 256).some((v) => v > 0));
+  const chroma = [];
+  eachPixel(pixels, Math.min(options.maxPixels ?? 65536, 65536), (r, g, b) => {
+    const [u, v] = videoChroma(r / 255, g / 255, b / 255);
+    chroma.push([u, v, Math.hypot(u, v)]);
+  });
+  chroma.sort((a, b) => b[2] - a[2]);
+  const top = chroma.slice(0, Math.max(1, Math.ceil(chroma.length / 10)));
+  const mu = top.reduce((s, c) => s + c[0], 0) / top.length;
+  const mv = top.reduce((s, c) => s + c[1], 0) / top.length;
+  const strength = Math.min(1, top.reduce((s, c) => s + c[2], 0) / top.length / 0.5);
+  const coherence = Math.hypot(mu, mv) / Math.max(1e-9, top.reduce((s, c) => s + c[2], 0) / top.length);
+  return {
+    stats,
+    notes: videoExposureNotes(stats),
+    histogram: { bins, luma: share(h.luma), r: share(h.r), g: share(h.g), b: share(h.b) },
+    waveform,
+    vectorscope: { hue: strength < 0.02 ? null : Math.round(videoVectorscopeAngle(mu, mv)), strength: round3(strength), spread: round3(1 - coherence) }
+  };
+}
+var VIDEO_VECTORSCOPE_TARGETS = [
+  ["R", [0.75, 0, 0]],
+  ["Mg", [0.75, 0, 0.75]],
+  ["B", [0, 0, 0.75]],
+  ["Cy", [0, 0.75, 0.75]],
+  ["G", [0, 0.75, 0]],
+  ["Yl", [0.75, 0.75, 0]]
+].map(([name, rgb]) => {
+  const [cb, cr] = videoChroma(rgb[0], rgb[1], rgb[2]);
+  return { name, rgb: [...rgb], cb, cr };
+});
+function canvas(width, height) {
+  const data = new Uint8ClampedArray(width * height * 4);
+  for (let i = 0; i < data.length; i += 4) {
+    data[i] = 12;
+    data[i + 1] = 14;
+    data[i + 2] = 18;
+    data[i + 3] = 255;
+  }
+  return { width, height, data };
+}
+function plot(img, x, y, rgb, alpha = 1, add = false) {
+  const xi = Math.round(x);
+  const yi = Math.round(y);
+  if (xi < 0 || yi < 0 || xi >= img.width || yi >= img.height) return;
+  const i = (yi * img.width + xi) * 4;
+  for (let k = 0; k < 3; k++) img.data[i + k] = add ? img.data[i + k] + rgb[k] * alpha : img.data[i + k] * (1 - alpha) + rgb[k] * alpha;
+}
+var GRID = [70, 76, 88];
+var glow = (count, peak) => count ? 0.25 + 0.75 * (Math.log1p(count) / Math.log1p(Math.max(1, peak))) : 0;
+function videoHistogramImage(h, width = 256, height = 128) {
+  const img = canvas(width, height);
+  for (const q of [0.25, 0.5, 0.75]) for (let y = 0; y < height; y++) plot(img, q * (width - 1), y, GRID);
+  const inner = (a) => a.length > 2 ? a.slice(1, -1) : a;
+  const peak = Math.max(1, ...inner(h.r), ...inner(h.g), ...inner(h.b), ...inner(h.luma));
+  const height01 = (v) => Math.min(1, Math.sqrt(v / peak));
+  for (let x = 0; x < width; x++) {
+    const bin = Math.min(h.bins - 1, Math.floor(x / width * h.bins));
+    const channels = [
+      [h.r, [200, 40, 40]],
+      [h.g, [40, 180, 40]],
+      [h.b, [50, 80, 220]]
+    ];
+    for (const [a, rgb] of channels) {
+      const top = height - height01(a[bin]) * height;
+      for (let y = Math.ceil(top); y < height; y++) plot(img, x, y, rgb, 0.8, true);
+    }
+    plot(img, x, height - 1 - height01(h.luma[bin]) * (height - 1), [255, 255, 255]);
+  }
+  return img;
+}
+function videoWaveformImage(w, width = 256, height = 128) {
+  const img = canvas(width, height);
+  for (const q of [0, 0.25, 0.5, 0.75, 1]) for (let x = 0; x < width; x++) plot(img, x, (1 - q) * (height - 1), GRID);
+  for (let x = 0; x < width; x++) {
+    const c = Math.min(w.columns - 1, Math.floor(x / width * w.columns));
+    for (let y = 0; y < height; y++) {
+      const level = Math.min(w.levels - 1, Math.floor((height - 1 - y) / height * w.levels));
+      const a = glow(w.data[c * w.levels + level], w.peak);
+      if (a) plot(img, x, y, [120, 255, 140], a);
+    }
+  }
+  return img;
+}
+function videoVectorscopeImage(v, size = v.size) {
+  const img = canvas(size, size);
+  const c = (size - 1) / 2;
+  for (let a = 0; a < 720; a++) {
+    const t = a / 720 * 2 * Math.PI;
+    plot(img, c + Math.cos(t) * c, c - Math.sin(t) * c, GRID);
+  }
+  const skin = 123 * Math.PI / 180;
+  for (let r = 0; r < c; r++) plot(img, c + Math.cos(skin) * r, c - Math.sin(skin) * r, [140, 110, 90]);
+  for (const t of VIDEO_VECTORSCOPE_TARGETS) {
+    const [x, y] = videoVectorscopePoint(t.cb, t.cr, size);
+    const rgb = t.rgb.map((k) => 80 + k * 200);
+    for (let k = -3; k <= 3; k++) {
+      plot(img, x + k, y - 3, rgb);
+      plot(img, x + k, y + 3, rgb);
+      plot(img, x - 3, y + k, rgb);
+      plot(img, x + 3, y + k, rgb);
+    }
+  }
+  for (let y = 0; y < size; y++)
+    for (let x = 0; x < size; x++) {
+      const sy = Math.min(v.size - 1, Math.floor(y / size * v.size));
+      const sx = Math.min(v.size - 1, Math.floor(x / size * v.size));
+      const a = glow(v.data[sy * v.size + sx], v.peak);
+      if (!a) continue;
+      const cb = sx / (v.size - 1) - 0.5;
+      const cr = 0.5 - sy / (v.size - 1);
+      const r = Math.min(1, Math.max(0, 0.6 + 1.5748 * cr));
+      const g = Math.min(1, Math.max(0, 0.6 - 0.1873 * cb - 0.4681 * cr));
+      const b = Math.min(1, Math.max(0, 0.6 + 1.8556 * cb));
+      plot(img, x, y, [r * 255, g * 255, b * 255], a);
+    }
+  return img;
+}
+function videoScopeImage(kind, pixels, width = 256, height = 128, options = {}) {
+  if (kind === "histogram") return videoHistogramImage(videoHistogram(pixels, { ...options, bins: Math.min(256, width) }), width, height);
+  if (kind === "waveform") return videoWaveformImage(videoLumaWaveform(pixels, { ...options, columns: Math.min(pixels.width, width), levels: Math.min(256, height) }), width, height);
+  const size = Math.min(width, height);
+  return videoVectorscopeImage(videoVectorscope(pixels, { ...options, size }), size);
+}
+var VideoPreviewPixels = class {
+  reader = null;
+  drawnAt = null;
+  listeners = /* @__PURE__ */ new Set();
+  /** Gives the canvas to read (the latest preview wins). Returns a function that takes it away again. */
+  attach(reader) {
+    this.reader = reader;
+    this.drawnAt = null;
+    return () => {
+      if (this.reader !== reader) return;
+      this.reader = null;
+      this.drawnAt = null;
+      this.emit();
+    };
+  }
+  /** Whether a preview is attached. */
+  get attached() {
+    return this.reader !== null;
+  }
+  /** The preview drew the frame at `time`; `complete` is false while a picture was missing or stale. */
+  drawn(time, complete) {
+    this.drawnAt = { time, complete };
+    this.emit();
+  }
+  /** The last frame drawn, with its pixels; `null` without a preview. Throws when the canvas cannot be read. */
+  read() {
+    if (!this.reader) return null;
+    try {
+      return this.reader();
+    } catch (e) {
+      const reason = e instanceof Error ? e.message : String(e);
+      throw new Error(`The preview's pixels cannot be read (${reason}). Media from another origin must be served with CORS headers (Access-Control-Allow-Origin) for its pixels to be measured.`);
+    }
+  }
+  /** Called after each frame the preview draws. */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * The frame at `time` once it is complete: now, if the last frame drawn was it, else the next
+   * complete drawing of it. Fails after `timeout` ms (default 5000).
+   */
+  next(time, timeout = 5e3) {
+    const matches = () => this.drawnAt && this.drawnAt.complete && Math.abs(this.drawnAt.time - time) < 0.5;
+    return new Promise((resolve, reject) => {
+      const done = (fn) => {
+        clearTimeout(timer);
+        off();
+        fn();
+      };
+      const check = () => {
+        if (!this.reader) return done(() => reject(new Error("The preview was closed before it drew the frame.")));
+        if (!matches()) return;
+        try {
+          const snap = this.read();
+          done(() => snap ? resolve(snap) : reject(new Error("The preview has no pixels to read.")));
+        } catch (e) {
+          done(() => reject(e));
+        }
+      };
+      const off = this.subscribe(check);
+      const timer = setTimeout(() => done(() => reject(new Error(`The preview did not finish drawing ${Math.round(time)} ms within ${timeout} ms; its media may still be loading or may have failed to load. Try again, or check the asset sources.`))), timeout);
+      check();
+    });
+  }
+  emit() {
+    for (const l of [...this.listeners]) l();
+  }
+};
+function readVideoScopesPanel(feed, kinds = VIDEO_SCOPE_KINDS, options = {}) {
+  let snap;
+  try {
+    snap = feed.read();
+  } catch (e) {
+    return { ok: false, message: e instanceof Error ? e.message : String(e) };
+  }
+  if (!snap) return { ok: false, message: feed.attached ? "The preview has not drawn a frame yet." : "Show the preview to see its scopes." };
+  const width = options.width ?? 256;
+  const height = options.height ?? 128;
+  const opts = { maxPixels: options.maxPixels ?? 65536 };
+  const images = {};
+  for (const kind of kinds) images[kind] = videoScopeImage(kind, snap.pixels, width, height, opts);
+  const stats = videoExposureStats(snap.pixels, opts);
+  return { ok: true, time: snap.time, complete: snap.complete, images, stats, notes: videoExposureNotes(stats) };
+}
+
 // src/video-editor/transcript.ts
 var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 function cueTime(s) {
@@ -2846,12 +3219,16 @@ function buildFfmpeg(project, options, measure) {
 
 // src/video-editor/preview.ts
 var VideoPreviewEngine = class {
-  constructor(source, canvas, options = {}) {
+  constructor(source, canvas2, options = {}) {
     this.source = source;
     this.options = options;
-    this.canvas = canvas;
-    this.ctx = options.context !== void 0 ? options.context : canvas.getContext?.("2d") ?? null;
+    this.canvas = canvas2;
+    this.ctx = options.context !== void 0 ? options.context : canvas2.getContext?.("2d") ?? null;
     this.unsubscribe = source.subscribe(() => this.update());
+    const pixels = options.pixels !== void 0 ? options.pixels : source.previewPixels;
+    this.detachPixels = pixels ? pixels.attach(() => this.readPixels()) : () => {
+    };
+    this.pixelsTarget = pixels ?? null;
     this.update();
   }
   source;
@@ -2865,6 +3242,16 @@ var VideoPreviewEngine = class {
   destroyed = false;
   filterHost = null;
   filters = /* @__PURE__ */ new Set();
+  detachPixels;
+  pixelsTarget;
+  drawn = null;
+  complete = true;
+  /** The canvas's pixels and the frame they show, or `null` when its context cannot be read. */
+  readPixels() {
+    const ctx = this.ctx;
+    if (!ctx?.getImageData || !this.drawn) return null;
+    return { ...this.drawn, pixels: ctx.getImageData(0, 0, this.canvas.width, this.canvas.height) };
+  }
   createMedia(kind) {
     if (this.options.createMedia) return this.options.createMedia(kind);
     const el = document.createElement(kind);
@@ -2956,7 +3343,9 @@ var VideoPreviewEngine = class {
       return img.complete ? img : null;
     }
     const entry = this.media.get(layer.clip);
-    return entry && entry.media.readyState >= 2 ? entry.media : null;
+    if (!entry || entry.media.readyState < 2) return null;
+    if (entry.media.seeking) this.complete = false;
+    return entry.media;
   };
   draw(frame) {
     if (!this.ctx) return;
@@ -2967,8 +3356,16 @@ var VideoPreviewEngine = class {
     const h = Math.max(1, Math.round(frame.height * resolution));
     if (this.canvas.width !== w) this.canvas.width = w;
     if (this.canvas.height !== h) this.canvas.height = h;
-    drawVideoFrame(this.ctx, frame, this.sourceFor, resolution, { defineSvgFilter: this.defineSvgFilter });
+    this.complete = true;
+    const sourceFor = (layer) => {
+      const source = this.sourceFor(layer);
+      if (!source) this.complete = false;
+      return source;
+    };
+    drawVideoFrame(this.ctx, frame, sourceFor, resolution, { defineSvgFilter: this.defineSvgFilter });
+    this.drawn = { time: frame.time, complete: this.complete };
     this.options.onFrame?.(frame);
+    this.pixelsTarget?.drawn(frame.time, this.complete);
   }
   defineSvgFilter = (id, markup) => {
     if (this.options.defineSvgFilter === null) return;
@@ -2989,6 +3386,7 @@ var VideoPreviewEngine = class {
   /** Stops following the editor and releases every media element. */
   destroy() {
     this.destroyed = true;
+    this.detachPixels();
     this.filterHost?.remove();
     this.filterHost = null;
     this.filters.clear();
@@ -3004,6 +3402,8 @@ var VideoEditorController = class {
   player;
   /** Sound levels per asset, loaded on demand for waveforms and agents. */
   audioPeaks;
+  /** The pixels the preview last drew, for scopes and `get_video_scopes` (a `VideoPreviewEngine` fills it). */
+  previewPixels = new VideoPreviewPixels();
   project;
   issues;
   selection = [];
@@ -4199,7 +4599,46 @@ function createVideoEditorToolProvider(controller, options = {}) {
       return { asset: r.asset.id, from: r.from, to: r.to, silences, total: round(silences.reduce((n2, x) => n2 + x.end - x.start, 0)) };
     }
   };
-  const reads = [getProject, getFrame, getTranscript, findText, findFillers, findPauses, findGaps, checkProject, renderFrame, exportFfmpeg, exportLoudnessMeasure, exportEdl, audioLevels, findSilences, seek];
+  const pixelsAt = async (time) => {
+    if (options.framePixels) {
+      const px = await options.framePixels(time);
+      if (!px) throw new Error(`The host could not render the frame at ${Math.round(time)} ms; use render_video_frame to look at it instead.`);
+      return px;
+    }
+    const feed = controller.previewPixels;
+    if (!feed.attached) throw new Error("No preview is showing this project, so there are no pixels to measure. The host must show a <VideoPreview> for this editor (or pass framePixels to the tool provider); until then use get_video_frame and render_video_frame.");
+    const state = controller.getState();
+    if (Math.abs(time - state.time) < 0.5) return (await feed.next(state.time, options.framePixelsTimeout)).pixels;
+    const { time: before, playing } = state;
+    if (playing) controller.pause();
+    controller.seek(time);
+    try {
+      return (await feed.next(controller.getState().time, options.framePixelsTimeout)).pixels;
+    } finally {
+      controller.seek(before);
+      if (playing) controller.play();
+    }
+  };
+  const getScopes = {
+    name: "get_video_scopes",
+    title: "Measure a frame with scopes",
+    description: "Measures the rendered picture at a moment as colour scopes would, without changing the project: luma (0 = black, 1 = white) mean, median, min, max and 1st / 99th percentiles; the share of pixels crushed to black or blown to white (and per channel); saturation; the average colour (a cast shows as a tint); a coarse luma and RGB histogram; the luma spread of vertical strips left to right (a waveform); the main hue and strength on a vectorscope; and notes on what to fix. Use it before and after grading (update_video_clip grade, apply_video_grade_preset) to check exposure and colour. Needs the pixels the host draws: fails with a reason when no preview is showing.",
+    inputSchema: object({
+      time: MS("Time from the start to measure (default: the playhead). Another time is shown briefly and the playhead put back"),
+      bins: { type: "integer", minimum: 2, maximum: 64, description: "Histogram steps, darkest first (default 16)." },
+      columns: { type: "integer", minimum: 1, maximum: 32, description: "Waveform strips across the picture, left to right (default 8)." }
+    }),
+    annotations: { title: "Measure a frame with scopes", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async ({ time, bins, columns }) => {
+      const p = project();
+      const end = videoProjectDuration(p);
+      const t = time ?? controller.getState().time;
+      if (time !== void 0 && time > end) throw new Error(`Time ${time} ms is past the end of the project (${end} ms).`);
+      const pixels = await pixelsAt(t);
+      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, setKeyframes, removeKeyframes, slipClip, rollEdit, slideClip, liftRange, extractRange, splitAt, closeGaps, addMarker, removeMarker, editVideo, undo, redo];
   return {
     id: options.id ?? "video",
@@ -4461,14 +4900,17 @@ export {
   VIDEO_KEYFRAME_PROPERTIES,
   VIDEO_PEAK_BLOCK,
   VIDEO_PLACEMENT_MODES,
+  VIDEO_SCOPE_KINDS,
   VIDEO_TIME_EPSILON,
   VIDEO_TRANSFORM_PROPERTIES,
   VIDEO_TRANSITION_LABELS,
   VIDEO_TRANSITION_TYPES,
+  VIDEO_VECTORSCOPE_TARGETS,
   VIDEO_WIPE_DIRECTIONS,
   VideoAudioPeaksCache,
   VideoEditorController,
   VideoPreviewEngine,
+  VideoPreviewPixels,
   allVideoClipIds,
   applyVideoEdits,
   applyVideoGrade,
@@ -4514,6 +4956,7 @@ export {
   placeVideoRect,
   planVideoClipDrag,
   probeVideoMedia,
+  readVideoScopesPanel,
   removeVideoKey,
   retimeVideoAnimatable,
   setVideoKey,
@@ -4522,6 +4965,7 @@ export {
   sortVideoKeys,
   sortedVideoClips,
   splitVideoAnimatable,
+  summarizeVideoScopes,
   toVideoEdl,
   toVideoFfmpeg,
   toVideoLoudnessMeasure,
@@ -4533,6 +4977,7 @@ export {
   videoAudioPeakRange,
   videoAudioPeakSpans,
   videoAudioPeaksDuration,
+  videoChroma,
   videoClipAfter,
   videoClipAnimated,
   videoClipAnimationProperties,
@@ -4558,6 +5003,8 @@ export {
   videoDropTracks,
   videoEaseBezier,
   videoEaseProgress,
+  videoExposureNotes,
+  videoExposureStats,
   videoFadeCurveGain,
   videoFrameAt,
   videoFrameDuration,
@@ -4573,6 +5020,8 @@ export {
   videoGradeSteps,
   videoGradeSvgDefs,
   videoGradeSvgFilter,
+  videoHistogram,
+  videoHistogramImage,
   videoHourFrames,
   videoIrisRadius,
   videoIssueKey,
@@ -4582,12 +5031,15 @@ export {
   videoKeyframeToggleEdit,
   videoKeyframeValueEdit,
   videoKeysOf,
+  videoLuma,
+  videoLumaWaveform,
   videoOverlap,
   videoPeakDb,
   videoProjectDuration,
   videoProjectSvg,
   videoRemoveRangesEdits,
   videoRulerTicks,
+  videoScopeImage,
   videoSlowMotionRamp,
   videoSnapPoints,
   videoSpeedRampEdit,
@@ -4606,6 +5058,11 @@ export {
   videoTransitionEase,
   videoTransitionHasDirection,
   videoValueAt,
+  videoVectorscope,
+  videoVectorscopeAngle,
+  videoVectorscopeImage,
+  videoVectorscopePoint,
+  videoWaveformImage,
   videoWaveformPath,
   videoWipeRect,
   videoWordAt,