@pixerate/editor 0.85.0 → 0.86.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;
@@ -2344,6 +2513,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 +2573,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 +2637,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 +2662,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 +2680,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 +2730,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 +2815,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) {
@@ -2682,13 +2915,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(() => {
         });
@@ -3671,6 +3905,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 +4092,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"]
   };
@@ -3889,7 +4200,7 @@ function createVideoEditorToolProvider(controller, options = {}) {
     }
   };
   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 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,
@@ -4163,6 +4474,7 @@ export {
   applyVideoGrade,
   buildVideoAudioPeaks,
   checkVideoProject,
+  checkVideoTimeRemap,
   createVideoEditorToolProvider,
   createVideoProject,
   decodeVideoAudioPeaks,
@@ -4193,6 +4505,7 @@ export {
   parseVideoLoudnessMeasurement,
   parseVideoMarker,
   parseVideoProject,
+  parseVideoTimeRemap,
   parseVideoTrack,
   parseVideoTranscript,
   parseVideoTranscriptWords,
@@ -4233,7 +4546,9 @@ export {
   videoClipShowsWaveform,
   videoClipSoundGain,
   videoClipSourceRange,
+  videoClipSourceTime,
   videoClipSpeed,
+  videoClipSpeedAt,
   videoClipTint,
   videoClipWaveform,
   videoClipWaveformPath,
@@ -4248,6 +4563,7 @@ export {
   videoFrameDuration,
   videoFrameToSvg,
   videoFrames,
+  videoFreezeFrameEdit,
   videoGradeCssFilter,
   videoGradeFfmpegFilters,
   videoGradeGainsFilterId,
@@ -4272,8 +4588,13 @@ export {
   videoProjectSvg,
   videoRemoveRangesEdits,
   videoRulerTicks,
+  videoSlowMotionRamp,
   videoSnapPoints,
+  videoSpeedRampEdit,
+  videoSpeedRampKeys,
   videoTextStyle,
+  videoTimeRemapBreakpoints,
+  videoTimeRemapSpan,
   videoTimecodeFrames,
   videoTimelineTranscript,
   videoTitleFrame,