@pixerate/editor 0.85.0 → 0.87.0

package/dist/video-editor/index.js

@@ -340,6 +340,105 @@ function videoGradeFfmpegFilters(grade) {
   });
 }
 
+// src/video-editor/remap.ts
+function videoClipSourceTime(clip, clipTime) {
+  const base = clip.in ?? 0;
+  return clip.timeRemap ? base + videoValueAt(clip.timeRemap, clipTime, 0) : base + clipTime * (clip.speed ?? 1);
+}
+function videoClipSpeedAt(clip, clipTime) {
+  if (clip.type !== "media") return 1;
+  if (!clip.timeRemap) return clip.speed ?? 1;
+  const t = Math.min(Math.max(clipTime, 0), Math.max(0, clip.duration - 1));
+  return Math.max(0, videoClipSourceTime(clip, t + 1) - videoClipSourceTime(clip, t));
+}
+function videoSpeedRampKeys(segments) {
+  if (!segments.length) throw new Error("Give at least one stretch { duration, speed }.");
+  const keys = [];
+  let t = 0;
+  let v = 0;
+  segments.forEach((s, i) => {
+    if (!(s.duration > 0)) throw new Error(`Stretch ${i + 1} needs a duration above 0 ms.`);
+    for (const [name, x] of [["speed", s.speed], ["toSpeed", s.toSpeed]])
+      if (x !== void 0 && !(x >= 0 && x <= 20)) throw new Error(`Stretch ${i + 1}'s ${name} must be from 0 (a freeze) to 20; got ${x}.`);
+    const a = s.speed;
+    const b = s.toSpeed ?? s.speed;
+    const avg = (a + b) / 2;
+    let ease = "linear";
+    if (a !== b && avg > 0) {
+      ease = [1 / 3, 2 * a / (3 * (a + b)), 2 / 3, 1 - 2 * b / (3 * (a + b))].map((n2) => Math.round(n2 * 1e6) / 1e6);
+    }
+    keys.push({ t, v, ...ease === "linear" ? {} : { ease } });
+    t += s.duration;
+    v += avg * s.duration;
+  });
+  keys.push({ t, v });
+  return { keys: mergeLinear(keys), duration: t, source: v };
+}
+function mergeLinear(keys) {
+  const out = [keys[0]];
+  for (let i = 1; i < keys.length; i++) {
+    const prev = out[out.length - 1];
+    const k = keys[i];
+    const before = out.length > 1 ? out[out.length - 2] : null;
+    if (before && !before.ease && !prev.ease) {
+      const s1 = (prev.v - before.v) / (prev.t - before.t);
+      const s2 = (k.v - prev.v) / (k.t - prev.t);
+      if (Math.abs(s1 - s2) < 1e-9) {
+        out[out.length - 1] = k;
+        continue;
+      }
+    }
+    out.push(k);
+  }
+  return out;
+}
+function checkVideoTimeRemap(remap, path = "timeRemap") {
+  const { keys } = remap;
+  if (!keys.length) throw new Error(`${path} needs at least one key.`);
+  keys.forEach((k, i) => {
+    if (k.v < 0) throw new Error(`${path}.keys[${i}].v must be at least 0 (ms after the in point).`);
+    const next = keys[i + 1];
+    if (!next) return;
+    if (next.v < k.v - 1e-6) throw new Error(`${path}.keys[${i + 1}] goes back in the source (${next.v} ms after ${k.v} ms); a ramp only plays forwards, so make each value at least the one before.`);
+    if (!videoEaseBezier(k.ease)) return;
+    let prev = k.v;
+    for (let n2 = 1; n2 <= 32; n2++) {
+      const v = videoValueAt(remap, k.t + (next.t - k.t) * n2 / 32);
+      if (v < prev - 1e-3) throw new Error(`${path}.keys[${i}].ease overshoots, which would play backwards; use a curve that only moves forwards (or linear).`);
+      prev = v;
+    }
+  });
+}
+function videoTimeRemapSpan(remap) {
+  return { from: remap.keys[0].v, to: remap.keys[remap.keys.length - 1].v };
+}
+function videoTimeRemapBreakpoints(remap, step) {
+  const { points, holds } = videoKeyframeBreakpoints(remap, step);
+  const out = [];
+  points.forEach(([t, v], i) => {
+    out.push({ t, v });
+    if (holds.has(i) && points[i + 1]) out.push({ t: points[i + 1][0], v });
+  });
+  return out;
+}
+function videoSpeedRampEdit(clip, segments, ripple = true) {
+  const ramp = videoSpeedRampKeys(segments);
+  const offset = videoClipSourceTime(clip, 0) - (clip.in ?? 0);
+  return { op: "set_time_remap", clip: clip.id, keys: ramp.keys.map((k) => ({ ...k, v: k.v + offset })), duration: ramp.duration, ripple };
+}
+function videoFreezeFrameEdit(clip, at, duration, ripple = true) {
+  if (at < 0 || at > clip.duration) throw new Error(`${Math.round(at)} ms is outside clip "${clip.id}" (0\u2013${clip.duration} ms of clip time).`);
+  const remap = clip.timeRemap ?? { keys: [{ t: 0, v: 0 }, { t: clip.duration, v: clip.duration * (clip.speed ?? 1) }] };
+  const [left, right] = splitVideoAnimatable(remap, at);
+  const keys = [...left.keys.slice(0, -1), { ...left.keys[left.keys.length - 1], ease: "linear" }, ...right.keys.map((k) => ({ ...k, t: k.t + at + duration }))];
+  return { op: "set_time_remap", clip: clip.id, keys, duration: clip.duration + duration, ripple };
+}
+var videoSlowMotionRamp = (duration) => [
+  { duration: Math.max(1, duration / 2), speed: 1 },
+  { duration: 500, speed: 1, toSpeed: 0.3 },
+  { duration: 1500, speed: 0.3 }
+];
+
 // src/video-editor/parse.ts
 var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var fail = (path, what) => {
@@ -408,6 +507,18 @@ function parseVideoTransform(v, path) {
     rotation: parseVideoAnimatable(v.rotation, `${path}.rotation`, { optional: true })
   });
 }
+function parseVideoTimeRemap(v, speed, path) {
+  if (v === void 0) return void 0;
+  const remap = parseVideoAnimatable(v, path, { optional: true, min: 0 });
+  if (typeof remap === "number" || remap === void 0) return fail(path, "must be keyframes { keys: [{ t, v, ease }] } (v: ms of source after the in point)");
+  if (speed !== void 0 && speed !== 1) fail(path, 'cannot be used with a speed; a ramp sets the speed itself (remove "speed")');
+  try {
+    checkVideoTimeRemap(remap, path);
+  } catch (e) {
+    throw new Error(e.message.replace(/\.?$/, "."));
+  }
+  return remap;
+}
 function parseVideoClipAnimation(v, path) {
   if (v === void 0) return void 0;
   if (!isObject(v)) return fail(path, "must be an object { effect, duration }");
@@ -494,6 +605,7 @@ function parseVideoClip(v, path = "clip") {
       speed: num(v.speed, `${path}.speed`, { optional: true, min: 0.05, max: 20 }),
       volume: parseVideoAnimatable(v.volume, `${path}.volume`, { optional: true, min: 0, max: 4 }),
       muted: bool(v.muted, `${path}.muted`),
+      timeRemap: parseVideoTimeRemap(v.timeRemap, v.speed, `${path}.timeRemap`),
       fadeInCurve: oneOf(v.fadeInCurve, VIDEO_FADE_CURVES, `${path}.fadeInCurve`),
       fadeOutCurve: oneOf(v.fadeOutCurve, VIDEO_FADE_CURVES, `${path}.fadeOutCurve`)
     });
@@ -589,6 +701,7 @@ var videoClipSpeed = (clip) => clip.type === "media" ? clip.speed ?? 1 : 1;
 function videoClipSourceRange(clip) {
   if (clip.type !== "media") return null;
   const start = clip.in ?? 0;
+  if (clip.timeRemap?.keys.length) return { in: start + clip.timeRemap.keys[0].v, out: start + clip.timeRemap.keys[clip.timeRemap.keys.length - 1].v };
   return { in: start, out: start + clip.duration * videoClipSpeed(clip) };
 }
 var videoFrameDuration = (fps) => 1e3 / fps;
@@ -928,6 +1041,7 @@ var VIDEO_EDIT_OPS = [
   "extract_range",
   "split_at",
   "set_keyframes",
+  "set_time_remap",
   "close_gaps",
   "add_marker",
   "update_marker",
@@ -955,11 +1069,14 @@ function mergeSpans(spans) {
   }
   return out;
 }
+var isRamped = (clip) => clip.type === "media" && !!clip.timeRemap;
 function clipAnimatables(clip) {
   const c = clip;
   const out = [
     { get: () => c.opacity, set: (v) => c.opacity = v },
-    { get: () => c.volume, set: (v) => c.volume = v }
+    { get: () => c.volume, set: (v) => c.volume = v },
+    // A speed ramp is keys in clip time too, so trims and splits keep it on the same frames of source.
+    { get: () => c.timeRemap, set: (v) => c.timeRemap = v }
   ];
   for (const p of VIDEO_TRANSFORM_PROPERTIES) out.push({ get: () => c.transform?.[p], set: (v) => c.transform && (c.transform[p] = v) });
   return out;
@@ -970,7 +1087,7 @@ function retimeClipKeys(clip, fn) {
     if (isVideoKeyframes(v)) a.set(fn(v));
   }
 }
-var OPTIONAL_CLIP_FIELDS = ["name", "opacity", "transform", "fit", "blend", "grade", "animateIn", "animateOut", "fadeIn", "fadeOut", "fadeInCurve", "fadeOutCurve", "transition", "in", "speed", "volume", "muted", "color", "fontSize", "fontFamily", "fontWeight", "background"];
+var OPTIONAL_CLIP_FIELDS = ["name", "opacity", "transform", "fit", "blend", "grade", "animateIn", "animateOut", "fadeIn", "fadeOut", "fadeInCurve", "fadeOutCurve", "transition", "in", "speed", "timeRemap", "volume", "muted", "color", "fontSize", "fontFamily", "fontWeight", "background"];
 var TIME_FIELDS = { slip_clip: ["delta"], roll_edit: ["delta"], slide_clip: ["delta"], lift_range: ["from", "to"], extract_range: ["from", "to"], split_at: ["at"] };
 var Editor = class {
   constructor(p) {
@@ -1057,7 +1174,7 @@ var Editor = class {
   }
   /** Moves a clip's head `delta` later in time (start, in point and keys); the caller sets start and duration. */
   trimHead(clip, delta) {
-    this.moveIn(clip, delta);
+    if (!isRamped(clip)) this.moveIn(clip, delta);
     retimeClipKeys(clip, (v) => retimeVideoAnimatable(v, -delta));
   }
   /** Cuts `clip` at `at` (inside it): the left part keeps the id, the right part is returned. */
@@ -1074,7 +1191,7 @@ var Editor = class {
       if (isVideoKeyframes(l)) leftValues[i].set(l);
       if (isVideoKeyframes(rr)) r.set(rr);
     });
-    this.moveIn(right, at - clip.start);
+    if (!isRamped(right)) this.moveIn(right, at - clip.start);
     clip.duration = at - clip.start;
     delete clip.fadeOut;
     delete clip.animateOut;
@@ -1286,7 +1403,7 @@ var Editor = class {
         if (e.edge === "start") {
           const delta = e.to - clip.start;
           if (clip.duration - delta < minimum - VIDEO_TIME_EPSILON) refuse(`Trimming the start to ${formatVideoSeconds(e.to)} would leave "${clip.id}" shorter than a frame; it ends at ${formatVideoSeconds(end)}.`);
-          if (clip.type === "media") {
+          if (clip.type === "media" && !isRamped(clip)) {
             const sourceIn = (clip.in ?? 0) + delta * speed;
             if (sourceIn < -VIDEO_TIME_EPSILON) refuse(`"${clip.id}" starts ${Math.round((clip.in ?? 0) / speed)} ms into its source, so its start can move at most that far earlier (to ${formatVideoSeconds(clip.start - (clip.in ?? 0) / speed)}).`);
             clip.in = Math.max(0, sourceIn);
@@ -1314,7 +1431,7 @@ var Editor = class {
         } else {
           const duration = e.to - clip.start;
           if (duration < minimum - VIDEO_TIME_EPSILON) refuse(`Trimming the end to ${formatVideoSeconds(e.to)} would leave "${clip.id}" shorter than a frame; it starts at ${formatVideoSeconds(clip.start)}.`);
-          if (clip.type === "media") {
+          if (clip.type === "media" && !isRamped(clip)) {
             const asset = assets.get(clip.asset);
             const out = (clip.in ?? 0) + duration * speed;
             if (asset?.duration !== void 0 && out > asset.duration + VIDEO_TIME_EPSILON)
@@ -1370,6 +1487,8 @@ var Editor = class {
         for (const k of ["id", "type"]) if (k in set) refuse(`A clip's ${k} cannot be changed; delete it and add a new one.`);
         for (const k of e.remove ?? []) if (!OPTIONAL_CLIP_FIELDS.includes(k)) refuse(`"${k}" cannot be removed; removable fields are ${OPTIONAL_CLIP_FIELDS.join(", ")}.`);
         if ("speed" in set && (typeof set.speed !== "number" || !(set.speed > 0))) refuse('"speed" must be a number greater than 0 (1 = normal speed).');
+        if ("speed" in set && isRamped(at.clip)) refuse(`Clip "${at.clip.id}" has a speed ramp, which sets its speed; change the ramp, or remove it first.`);
+        if ("timeRemap" in set) refuse("Set a speed ramp with set_time_remap, which checks it against the media and moves later clips if asked.");
         let stretch = 1;
         if (at.clip.type === "media" && !("duration" in set)) {
           const was = videoClipSpeed(at.clip);
@@ -1389,6 +1508,56 @@ var Editor = class {
         at.track.clips.sort((a, b) => a.start - b.start);
         return this.outcomes.push({ op: e.op, clip: clip.id, track: at.track.id });
       }
+      case "set_time_remap": {
+        const { track, clip } = this.clip(e.clip);
+        this.unlocked(track);
+        if (clip.type !== "media") refuse(`Clip "${clip.id}" is a ${clip.type === "text" ? "title" : "colour"}, so it has no source to ramp; only video and audio clips change speed.`);
+        const asset = this.asset(clip.asset);
+        if (asset.kind === "image") refuse(`Clip "${clip.id}" is a still ("${asset.id}"), so it has no motion to ramp.`);
+        const media = clip;
+        const end = videoClipEnd(media);
+        const duration = e.duration ?? media.duration;
+        if (!(duration >= 1e3 / this.p.fps - VIDEO_TIME_EPSILON)) refuse(`"duration" must be at least a frame (${Math.ceil(1e3 / this.p.fps)} ms).`);
+        if (e.keys === null) {
+          if (!media.timeRemap) refuse(`Clip "${clip.id}" has no speed ramp to remove.`);
+          const from = (media.in ?? 0) + media.timeRemap.keys[0].v;
+          if (asset.duration !== void 0 && from + duration > asset.duration + VIDEO_TIME_EPSILON)
+            refuse(`At normal speed from ${Math.round(from)} ms, "${clip.id}" would run past the end of "${asset.id}" (${asset.duration} ms); give a duration of at most ${Math.floor(asset.duration - from)} ms.`);
+          delete media.timeRemap;
+          media.in = from;
+          if (media.in < 1e-9) delete media.in;
+        } else {
+          if (!Array.isArray(e.keys) || !e.keys.length) refuse('"keys" must be a list of at least one { t, v, ease } (or null to remove the ramp).');
+          const remap = parseVideoTimeRemap({ keys: e.keys }, void 0, "keys");
+          remap.keys = sortVideoKeys(remap.keys);
+          checkVideoTimeRemap(remap, "keys");
+          const span = videoTimeRemapSpan(remap);
+          if (asset.duration !== void 0 && (media.in ?? 0) + span.to > asset.duration + VIDEO_TIME_EPSILON)
+            refuse(`The ramp plays ${Math.round(span.to)} ms of source from the in point (${media.in ?? 0} ms), past the end of "${asset.id}" (${asset.duration} ms); it can use at most ${Math.floor(asset.duration - (media.in ?? 0))} ms.`);
+          media.timeRemap = remap;
+          delete media.speed;
+        }
+        const newEnd = media.start + duration;
+        const outcome = { op: e.op, clip: clip.id, track: track.id };
+        if (Math.abs(newEnd - end) > VIDEO_TIME_EPSILON) {
+          if (e.ripple) {
+            const tracks = this.rippleTracks([track]);
+            if (newEnd < end) {
+              media.duration = duration;
+              this.close(tracks, newEnd, end);
+            } else {
+              const created = this.open(tracks, end, newEnd - end, /* @__PURE__ */ new Set([clip.id]));
+              media.duration = duration;
+              if (created.length) outcome.created = created;
+            }
+            outcome.rippled = tracks.map((t) => t.id);
+          } else {
+            if (newEnd > end) this.fits(track, end, newEnd - end, /* @__PURE__ */ new Set([clip.id]), `Lengthening "${clip.id}"`);
+            media.duration = duration;
+          }
+        }
+        return this.outcomes.push(outcome);
+      }
       case "set_transition": {
         const { track, clip } = this.clip(e.clip);
         this.unlocked(track);
@@ -1671,7 +1840,7 @@ function activeOnTrack(track, time) {
   }
   return out;
 }
-var sourceTimeAt = (clip, time) => clip.type === "media" ? (clip.in ?? 0) + (time - clip.start) * videoClipSpeed(clip) : 0;
+var sourceTimeAt = (clip, time) => clip.type === "media" ? videoClipSourceTime(clip, time - clip.start) : 0;
 function videoFrameAt(project, time) {
   const assets = videoAssetMap(project);
   const layers = [];
@@ -1691,7 +1860,7 @@ function videoFrameAt(project, time) {
       const audible = videoAssetHasSound(asset);
       if (audible && clip.type === "media" && !clip.muted && !track.muted) {
         const gain = videoValueAt(clip.volume, clipTime, 1) * (track.volume ?? 1) * fadeGain(clip, inside, true) * mix;
-        audio.push({ clip: clip.id, track: track.id, asset: asset.id, src: asset.src, sourceTime, gain, speed: videoClipSpeed(clip) });
+        audio.push({ clip: clip.id, track: track.id, asset: asset.id, src: asset.src, sourceTime, gain, speed: videoClipSpeedAt(clip, clipTime) });
       }
       if (track.kind !== "video" || track.hidden) continue;
       if (clip.type === "media" && (!asset || asset.kind === "audio")) continue;
@@ -1955,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) {
@@ -2344,6 +2886,7 @@ function parseVideoLoudnessMeasurement(output) {
   return m;
 }
 var sec = (ms) => String(Math.round(ms) / 1e3);
+var fmtMs = (v) => String(Math.round(v * 100) / 100);
 var FFMPEG_BLEND = {
   multiply: "multiply",
   screen: "screen",
@@ -2403,6 +2946,58 @@ function buildFfmpeg(project, options, measure) {
   let cur = "base";
   let usesDrawtext = false;
   const animated = /* @__PURE__ */ new Set();
+  const ramped = /* @__PURE__ */ new Set();
+  const rampedPicture = (remap, lead, end) => {
+    const pts = videoTimeRemapBreakpoints(remap, 2e3 / fps);
+    const first = pts[0];
+    const last = pts[pts.length - 1];
+    const s = `(T*1000+${fmtMs(first.v)})`;
+    let e = fmtMs(last.t - first.t);
+    for (let i = pts.length - 2; i >= 0; i--) {
+      const a = pts[i];
+      const b = pts[i + 1];
+      if (b.v - a.v < 1e-6) continue;
+      e = `if(lt(${s},${fmtMs(b.v)}),${fmtMs(a.t - first.t)}+(${s}-${fmtMs(a.v)})*${fmtMs((b.t - a.t) / (b.v - a.v))},${e})`;
+    }
+    const before = lead + first.t;
+    const after = Math.max(0, end - last.t);
+    return ["setpts=PTS-STARTPTS", `setpts='(${e})/1000/TB'`, `fps=${fps}`, ...before > 0.5 || after > 0.5 ? [`tpad=start_mode=clone:start_duration=${sec(before)}:stop_mode=clone:stop_duration=${sec(after + 1e3 / fps)}`] : [`tpad=stop_mode=clone:stop_duration=${sec(1e3 / fps)}`], `trim=duration=${sec(lead + end)}`];
+  };
+  const rampedSound = (remap, input2, output, lead, end) => {
+    const pts = videoTimeRemapBreakpoints(remap, Math.max(80, 2e3 / fps));
+    const first = pts[0];
+    const last = pts[pts.length - 1];
+    const n2 = audio.length;
+    const fmtA = "aformat=sample_fmts=fltp:sample_rates=48000:channel_layouts=stereo";
+    const silence = (ms) => `anullsrc=r=48000:cl=stereo,atrim=duration=${sec(ms)},${fmtA}`;
+    const pieces = [];
+    const out = [];
+    const parts = [];
+    if (lead + first.t > 0.5) parts.push(silence(lead + first.t));
+    const played = [];
+    for (let i = 0; i + 1 < pts.length; i++) {
+      const dt = pts[i + 1].t - pts[i].t;
+      if (dt < 0.5) continue;
+      const speed = (pts[i + 1].v - pts[i].v) / dt;
+      if (speed < 0.1) parts.push(silence(dt));
+      else {
+        played.push({ from: pts[i].v - first.v, to: pts[i + 1].v - first.v, speed });
+        parts.push(`#${played.length - 1}`);
+      }
+    }
+    if (end - last.t > 0.5) parts.push(silence(end - last.t));
+    if (played.length) out.push(`[${input2}]asplit=${played.length}${played.map((_, k2) => `[r${n2}s${k2}]`).join("")}`);
+    parts.forEach((p, k2) => {
+      const label = `[r${n2}p${k2}]`;
+      if (p.startsWith("#")) {
+        const piece = played[Number(p.slice(1))];
+        out.push(`[r${n2}s${p.slice(1)}]atrim=start=${sec(piece.from)}:end=${sec(piece.to)},asetpts=PTS-STARTPTS,${atempo(piece.speed).join(",") || "anull"},${fmtA}${label}`);
+      } else out.push(`${p}${label}`);
+      pieces.push(label);
+    });
+    out.push(`${pieces.join("")}concat=n=${pieces.length}:v=0:a=1${output}`);
+    return out;
+  };
   const blended = /* @__PURE__ */ new Set();
   let k = 0;
   const step = 2e3 / fps;
@@ -2415,7 +3010,10 @@ function buildFfmpeg(project, options, measure) {
     const src = options.resolve ? options.resolve(asset) : asset.src;
     const span = clip.duration + lead + tail;
     if (asset.kind === "image") inputs.push(["-loop", "1", "-framerate", String(fps), "-t", sec(span), "-i", src]);
-    else inputs.push(["-ss", sec((clip.in ?? 0) - lead * speed), "-t", sec(span * speed), "-i", src]);
+    else if (clip.timeRemap) {
+      const { from, to } = videoTimeRemapSpan(clip.timeRemap);
+      inputs.push(["-ss", sec((clip.in ?? 0) + from), "-t", sec(to - from + 1e3 / fps), "-i", src]);
+    } else inputs.push(["-ss", sec((clip.in ?? 0) - lead * speed), "-t", sec(span * speed), "-i", src]);
     return inputs.length - 1;
   };
   for (const track of [...project.tracks].reverse()) {
@@ -2437,7 +3035,13 @@ function buildFfmpeg(project, options, measure) {
         const ai = index ?? input(clip, asset, lead, tail);
         const trackGain = track.volume ?? 1;
         const volume = isVideoKeyframes(clip.volume) ? `volume='${trackGain}*(${expr(clip.volume, `(t*1000${lead ? `-${Math.round(lead)}` : ""})`, 1, "volume")})':eval=frame` : `volume=${(clip.volume ?? 1) * trackGain}`;
-        const chain2 = ["asetpts=PTS-STARTPTS", ...atempo(videoClipSpeed(clip)), volume];
+        let source2 = `[${ai}:a]`;
+        if (clip.timeRemap) {
+          source2 = `[r${audio.length}]`;
+          graph.push(...rampedSound(clip.timeRemap, `${ai}:a`, source2, lead, clip.duration + tail));
+          ramped.add("sound");
+        }
+        const chain2 = [...clip.timeRemap ? [] : ["asetpts=PTS-STARTPTS", ...atempo(videoClipSpeed(clip))], volume];
         const before2 = clip.transition ? videoClipBefore(track, clip) : null;
         const next2 = sortedVideoClips(track).find((c) => c !== clip && Math.abs(c.start - end) < 0.5 && c.transition);
         const inCurve = clip.transition ? afadeCurve(videoTransitionAudioCurve(clip.transition)) : "";
@@ -2449,7 +3053,7 @@ function buildFfmpeg(project, options, measure) {
         if (clip.fadeIn) chain2.push(`afade=t=in:st=${sec(lead)}:d=${sec(clip.fadeIn)}${afadeCurve(clip.fadeInCurve)}`);
         if (clip.fadeOut) chain2.push(`afade=t=out:st=${sec(lead + clip.duration - clip.fadeOut)}:d=${sec(clip.fadeOut)}${afadeCurve(clip.fadeOutCurve)}`);
         chain2.push(`adelay=${Math.round(t0)}:all=1`);
-        graph.push(`[${ai}:a]${chain2.join(",")}[a${audio.length}]`);
+        graph.push(`${source2}${chain2.join(",")}[a${audio.length}]`);
         audio.push(`[a${audio.length}]`);
       }
       if (measure || track.kind !== "video" || track.hidden) continue;
@@ -2499,7 +3103,8 @@ function buildFfmpeg(project, options, measure) {
       if (clip.type === "color") source = `color=c=${color(clip.color)}:s=${even(rect.width)}x${even(rect.height)}:r=${fps}:d=${sec(span)}`;
       else {
         source = `[${index}:v]`;
-        chain.push(`setpts=${videoClipSpeed(clip) !== 1 ? `(PTS-STARTPTS)/${videoClipSpeed(clip)}` : "PTS-STARTPTS"}`, `fps=${fps}`, `scale=${even(rect.width)}:${even(rect.height)}`);
+        if (clip.type === "media" && clip.timeRemap) chain.push(...rampedPicture(clip.timeRemap, lead, clip.duration + tail), `scale=${even(rect.width)}:${even(rect.height)}`);
+        else chain.push(`setpts=${videoClipSpeed(clip) !== 1 ? `(PTS-STARTPTS)/${videoClipSpeed(clip)}` : "PTS-STARTPTS"}`, `fps=${fps}`, `scale=${even(rect.width)}:${even(rect.height)}`);
       }
       const grade = videoGradeFfmpegFilters(clip.grade);
       if (grade.length) chain.push("format=rgba", ...grade);
@@ -2583,6 +3188,7 @@ function buildFfmpeg(project, options, measure) {
   if (animated.size)
     notes.push(`Keyframed ${[...animated].sort().join(", ")} ${animated.size > 1 ? "are" : "is"} rendered as straight lines between keys, with eased segments sampled every two frames${animated.has("scale") ? "; animated scale needs ffmpeg 5 or later (scale with eval=frame)" : ""}.`);
   if (blended.has("soft-light")) notes.push("ffmpeg's soft-light blend uses a slightly different formula from the browser's, so the render can differ a little from the preview.");
+  if (ramped.has("sound")) notes.push("Sound through a speed ramp plays each stretch at its own speed, so a gliding change is heard in small steps (about every 80 ms), and freezes are silent.");
   if (usesDrawtext) notes.push("Titles use drawtext, which needs an ffmpeg built with libfreetype (Homebrew's is not: check `ffmpeg -filters | grep drawtext`); pass titleImage to render them as images instead.");
   const filterComplex = graph.join(";");
   if (measure) {
@@ -2613,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;
@@ -2632,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);
@@ -2682,13 +3302,14 @@ var VideoPreviewEngine = class {
       const { media } = this.entry(clip, src, kind);
       active.add(clip);
       const target = sourceTime / 1e3;
-      if (Math.abs(media.playbackRate - speed) > 1e-6) media.playbackRate = speed;
+      const frozen = speed < 0.0625;
+      if (!frozen && Math.abs(media.playbackRate - speed) > 1e-6) media.playbackRate = speed;
       if (gain === null) media.muted = true;
       else {
         media.muted = gain <= 0;
         media.volume = Math.min(1, Math.max(0, gain));
       }
-      if (playing) {
+      if (playing && !frozen) {
         if (media.paused || Math.abs(media.currentTime - target) > tolerance) media.currentTime = target;
         if (media.paused) void Promise.resolve(media.play()).catch(() => {
         });
@@ -2722,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;
@@ -2733,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;
@@ -2755,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();
@@ -2770,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 = [];
@@ -3671,6 +4305,83 @@ function createVideoEditorToolProvider(controller, options = {}) {
       return apply(videoRemoveRangesEdits(merged, tracks), merged.length > 1 ? `Cut ${merged.length} stretches` : "Cut stretch", (r) => ({ removed: merged.length, time: round(before - videoProjectDuration(r.project)), duration: videoProjectDuration(r.project) }));
     }
   };
+  const rampTarget = (id) => {
+    const at = findVideoClip(project(), id);
+    if (!at) throw new Error(`There is no clip "${id}"; get_video_project lists the clips.`);
+    const { clip } = at;
+    if (clip.type !== "media") throw new Error(`Clip "${id}" is a ${clip.type === "text" ? "title" : "colour"}, so it has no source to change the speed of; use a video or audio clip.`);
+    if (project().assets.find((a) => a.id === clip.asset)?.kind === "image") throw new Error(`Clip "${id}" is a still, so it has no motion to change the speed of.`);
+    return clip;
+  };
+  const rampOut = (r, id) => {
+    const outcome2 = r.outcomes[r.outcomes.length - 1];
+    return { clip: clipOut(r.project, id), ...outcome2.rippled ? { rippled: outcome2.rippled } : {}, duration: videoProjectDuration(r.project) };
+  };
+  const RIPPLE_RAMP = { type: "boolean", description: "Move later material on every sync-locked track by the change in length (default true); false refuses if the clip would overlap the next one." };
+  const setSpeedRamp = {
+    name: "set_video_speed_ramp",
+    title: "Ramp the speed",
+    description: `Plays a video or audio clip through stretches of speed, from its first frame: e.g. [{ duration: 1500, speed: 1 }, { duration: 500, speed: 1, toSpeed: 0.25 }, { duration: 2000, speed: 0.25 }] for a slow-motion ramp. "toSpeed" glides evenly to a new speed over the stretch; speed 0 is a freeze frame. The clip's length becomes the stretches' total (one undo step). Replaces any ramp or speed it had. Returns the clip (with its timeRemap keys and source range).`,
+    inputSchema: object(
+      {
+        clip: CLIP_ID,
+        segments: {
+          type: "array",
+          minItems: 1,
+          maxItems: 100,
+          description: "The stretches in order, from the clip's start.",
+          items: object(
+            {
+              duration: { type: "number", exclusiveMinimum: 0, description: "Length of the stretch on the timeline, in ms." },
+              speed: { type: "number", minimum: 0, maximum: 20, description: "Speed at its start: 1 normal, 0.5 half speed (slow motion), 2 double, 0 a freeze frame." },
+              toSpeed: { type: "number", minimum: 0, maximum: 20, description: "Glide evenly to this speed by the stretch's end (default: stay at speed). A ramp between two speeds." }
+            },
+            ["duration", "speed"],
+            "One stretch."
+          )
+        },
+        ripple: RIPPLE_RAMP
+      },
+      ["clip", "segments"]
+    ),
+    annotations: { title: "Ramp the speed", ...WRITE_IDEMPOTENT },
+    handler: ({ clip, segments, ripple }) => {
+      const edit = videoSpeedRampEdit(rampTarget(clip), segments, ripple ?? true);
+      return apply(edit, "Speed ramp", (r) => ({ ...rampOut(r, clip), source: Math.round(videoSpeedRampKeys(segments).source) }));
+    }
+  };
+  const addFreeze = {
+    name: "add_video_freeze_frame",
+    title: "Add a freeze frame",
+    description: "Holds the frame a video clip shows at a timeline time for a while, then plays on (one undo step): the clip gets longer by the hold, and with ripple (default) everything after it on sync-locked tracks moves along. Works on clips with or without a speed ramp. Returns the clip.",
+    inputSchema: object(
+      {
+        clip: CLIP_ID,
+        at: MS("Timeline time of the frame to hold (inside the clip)"),
+        duration: { type: "number", exclusiveMinimum: 0, description: "How long to hold it, in ms." },
+        ripple: RIPPLE_RAMP
+      },
+      ["clip", "at", "duration"]
+    ),
+    annotations: { title: "Add a freeze frame", ...WRITE },
+    handler: ({ clip, at, duration, ripple }) => {
+      const c = rampTarget(clip);
+      const t = at - c.start;
+      if (t < 0 || t > c.duration) throw new Error(`${formatVideoSeconds(at)} is outside clip "${clip}" (${formatVideoSeconds(c.start)}\u2013${formatVideoSeconds(videoClipEnd(c))}); pick a time inside it.`);
+      return apply(videoFreezeFrameEdit(c, t, duration, ripple ?? true), "Freeze frame", (r) => rampOut(r, clip));
+    }
+  };
+  const removeRamp = {
+    name: "remove_video_speed_ramp",
+    title: "Remove a speed ramp",
+    description: 'Puts a ramped clip back to normal speed from the moment its ramp started (one undo step), keeping its length unless "duration" is given. Returns the clip.',
+    inputSchema: object({ clip: CLIP_ID, duration: { type: "number", exclusiveMinimum: 0, description: "New length in ms (default: unchanged)." }, ripple: RIPPLE_RAMP }, ["clip"]),
+    annotations: { title: "Remove a speed ramp", ...WRITE },
+    handler: ({ clip, duration, ripple }) => {
+      rampTarget(clip);
+      return apply({ op: "set_time_remap", clip, keys: null, ...duration !== void 0 ? { duration } : {}, ripple: ripple ?? true }, "Remove speed ramp", (r) => rampOut(r, clip));
+    }
+  };
   const setTransition = {
     name: "set_video_transition",
     title: "Set a transition",
@@ -3781,7 +4492,7 @@ function createVideoEditorToolProvider(controller, options = {}) {
   };
   const EDIT_OP = {
     type: "object",
-    description: `One edit: { "op": one of ${VIDEO_EDIT_OPS.filter((o) => o !== "replace_project").join(", ")}, \u2026its fields }. Fields match the single tools: add_clip { track, clip, mode, ripple }, move_clip { clip, start, track, mode }, trim_clip { clip, edge, to, ripple }, split_clip { clip, at, id }, delete_clips { clips, ripple }, update_clip { clip, set, remove }, set_transition { clip, transition }, set_keyframes { clip, property, keys (null removes) }, slip_clip { clip, delta }, roll_edit { left, right, delta }, slide_clip { clip, delta }, lift_range { from, to, tracks }, extract_range { from, to, tracks }, split_at { at, tracks }, close_gaps { track, from }, add_asset { asset }, update_asset { asset, set, remove }, remove_asset { asset }, add_track { track: { kind, id, \u2026 }, at }, update_track { track, set, remove }, remove_track { track }, move_track { track, to }, add_marker { marker: { time, label } }, update_marker { marker, set }, remove_marker { marker }, set_settings { name, width, height, fps, background }.`,
+    description: `One edit: { "op": one of ${VIDEO_EDIT_OPS.filter((o) => o !== "replace_project").join(", ")}, \u2026its fields }. Fields match the single tools: add_clip { track, clip, mode, ripple }, move_clip { clip, start, track, mode }, trim_clip { clip, edge, to, ripple }, split_clip { clip, at, id }, delete_clips { clips, ripple }, update_clip { clip, set, remove }, set_transition { clip, transition }, set_keyframes { clip, property, keys (null removes) }, set_time_remap { clip, keys (clip ms \u2192 source ms after the in point; null removes), duration, ripple }, slip_clip { clip, delta }, roll_edit { left, right, delta }, slide_clip { clip, delta }, lift_range { from, to, tracks }, extract_range { from, to, tracks }, split_at { at, tracks }, close_gaps { track, from }, add_asset { asset }, update_asset { asset, set, remove }, remove_asset { asset }, add_track { track: { kind, id, \u2026 }, at }, update_track { track, set, remove }, remove_track { track }, move_track { track, to }, add_marker { marker: { time, label } }, update_marker { marker, set }, remove_marker { marker }, set_settings { name, width, height, fps, background }.`,
     properties: { op: { type: "string", enum: VIDEO_EDIT_OPS.filter((o) => o !== "replace_project"), description: "Which edit." } },
     required: ["op"]
   };
@@ -3888,8 +4599,47 @@ 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 writes = [setSettings, addAsset, updateAsset, removeAsset, addTrack, updateTrack, removeTrack, moveTrack, addClip, moveClip, trimClip, splitClip, deleteClips, updateClip, setTransition, setTranscript, removeRanges, applyGradePreset, copyGrade, setKeyframes, removeKeyframes, slipClip, rollEdit, slideClip, liftRange, extractRange, splitAt, closeGaps, addMarker, removeMarker, editVideo, undo, redo];
+  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",
     namespace: options.namespace,
@@ -4150,19 +4900,23 @@ 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,
   buildVideoAudioPeaks,
   checkVideoProject,
+  checkVideoTimeRemap,
   createVideoEditorToolProvider,
   createVideoProject,
   decodeVideoAudioPeaks,
@@ -4193,6 +4947,7 @@ export {
   parseVideoLoudnessMeasurement,
   parseVideoMarker,
   parseVideoProject,
+  parseVideoTimeRemap,
   parseVideoTrack,
   parseVideoTranscript,
   parseVideoTranscriptWords,
@@ -4201,6 +4956,7 @@ export {
   placeVideoRect,
   planVideoClipDrag,
   probeVideoMedia,
+  readVideoScopesPanel,
   removeVideoKey,
   retimeVideoAnimatable,
   setVideoKey,
@@ -4209,6 +4965,7 @@ export {
   sortVideoKeys,
   sortedVideoClips,
   splitVideoAnimatable,
+  summarizeVideoScopes,
   toVideoEdl,
   toVideoFfmpeg,
   toVideoLoudnessMeasure,
@@ -4220,6 +4977,7 @@ export {
   videoAudioPeakRange,
   videoAudioPeakSpans,
   videoAudioPeaksDuration,
+  videoChroma,
   videoClipAfter,
   videoClipAnimated,
   videoClipAnimationProperties,
@@ -4233,7 +4991,9 @@ export {
   videoClipShowsWaveform,
   videoClipSoundGain,
   videoClipSourceRange,
+  videoClipSourceTime,
   videoClipSpeed,
+  videoClipSpeedAt,
   videoClipTint,
   videoClipWaveform,
   videoClipWaveformPath,
@@ -4243,11 +5003,14 @@ export {
   videoDropTracks,
   videoEaseBezier,
   videoEaseProgress,
+  videoExposureNotes,
+  videoExposureStats,
   videoFadeCurveGain,
   videoFrameAt,
   videoFrameDuration,
   videoFrameToSvg,
   videoFrames,
+  videoFreezeFrameEdit,
   videoGradeCssFilter,
   videoGradeFfmpegFilters,
   videoGradeGainsFilterId,
@@ -4257,6 +5020,8 @@ export {
   videoGradeSteps,
   videoGradeSvgDefs,
   videoGradeSvgFilter,
+  videoHistogram,
+  videoHistogramImage,
   videoHourFrames,
   videoIrisRadius,
   videoIssueKey,
@@ -4266,14 +5031,22 @@ export {
   videoKeyframeToggleEdit,
   videoKeyframeValueEdit,
   videoKeysOf,
+  videoLuma,
+  videoLumaWaveform,
   videoOverlap,
   videoPeakDb,
   videoProjectDuration,
   videoProjectSvg,
   videoRemoveRangesEdits,
   videoRulerTicks,
+  videoScopeImage,
+  videoSlowMotionRamp,
   videoSnapPoints,
+  videoSpeedRampEdit,
+  videoSpeedRampKeys,
   videoTextStyle,
+  videoTimeRemapBreakpoints,
+  videoTimeRemapSpan,
   videoTimecodeFrames,
   videoTimelineTranscript,
   videoTitleFrame,
@@ -4285,6 +5058,11 @@ export {
   videoTransitionEase,
   videoTransitionHasDirection,
   videoValueAt,
+  videoVectorscope,
+  videoVectorscopeAngle,
+  videoVectorscopeImage,
+  videoVectorscopePoint,
+  videoWaveformImage,
   videoWaveformPath,
   videoWipeRect,
   videoWordAt,