@pixerate/editor 0.252.0 → 0.254.0

package/dist/effects/index.js

@@ -3,7 +3,7 @@ import {
 } from "../chunk-N4ZXW3WB.js";
 import {
   createEffectAuthoringSession
-} from "../chunk-ABL7IWFZ.js";
+} from "../chunk-GBEF2D4P.js";
 import {
   EFFECT_LAYER_USES,
   EFFECT_SEQUENCE_NAME,
@@ -28,7 +28,7 @@ import {
   templateSlotTakes,
   templateValueProblem,
   templateValuesSchema
-} from "../chunk-226QDRO3.js";
+} from "../chunk-DHQPRKXF.js";
 import {
   EffectRendererPool
 } from "../chunk-EHLOCVWB.js";
@@ -50,15 +50,22 @@ import {
   EffectUnsupportedError,
   EffectsSlot,
   NoEffectsProviderError,
+  TIMING_BLENDS,
+  TIMING_DEFAULT_FPS,
+  TIMING_MAX_FPS,
+  TIMING_MAX_FRAMES,
   UnknownEffectError,
   UnknownTemplateError,
   applyEffectMask,
+  blendTimingFrames,
   cameraBoxOfView,
   cameraMoveField,
   cameraMoveIdList,
   cameraMoveParts,
   cameraMovesFor,
   cameraViewOfBox,
+  checkTimingFootage,
+  checkTimingRequest,
   countEffectTags,
   createEffectPixels,
   createEffectToolProvider,
@@ -72,14 +79,16 @@ import {
   layerImageInput,
   linearToSrgb,
   normaliseEffectTag,
+  normaliseTimingSample,
   pathControlsOf,
   resolveCameraMoveSpec,
   resolveEffectValues,
   sampleCameraViews,
   sampleEffectCameraMove,
   searchEffectSummaries,
-  srgbToLinear
-} from "../chunk-JA57JIT5.js";
+  srgbToLinear,
+  timingSampleProblems
+} from "../chunk-MV7CYFMJ.js";
 import "../chunk-V2ZCJRDM.js";
 import "../chunk-NS62CQ2B.js";
 import {
@@ -124,6 +133,10 @@ function checkSummary(e, issues) {
     if (e.uses?.includes("camera")) at('only camera effects may have the use "camera"');
     if (e.camera !== void 0) at("only camera effects may have camera");
   }
+  if (e.kind === "timing") {
+    if (e.uses?.length !== 1 || e.uses[0] !== "timing") at('a timing effect must have exactly the use "timing"');
+    if (e.duration !== void 0) at("a timing effect has no duration: its length depends on its footage (timingLength)");
+  } else if (e.uses?.includes("timing")) at('only timing effects may have the use "timing"');
 }
 function checkDescription(id, d, issues) {
   const at = (message) => issues.push({ effectId: id, message });
@@ -167,7 +180,7 @@ async function checkRender(provider, d, size, issues) {
   try {
     renderer = await provider.createRenderer(d.id, { width: size, height: size });
   } catch (e) {
-    if (!((d.kind === "vector" || d.kind === "camera") && codeOf(e) === "unsupported")) at(`createRenderer failed: ${codeOf(e)}`);
+    if (!((d.kind === "vector" || d.kind === "camera" || d.kind === "timing") && codeOf(e) === "unsupported")) at(`createRenderer failed: ${codeOf(e)}`);
     else if (!(e instanceof Error && e.message.trim())) at("createRenderer refused without saying why");
     return;
   }
@@ -229,6 +242,51 @@ async function checkCamera(provider, d, issues) {
     }
   }
 }
+var FOOTAGE = [{ footage: 3e3 }, { footage: 1e3, fps: 24 }];
+var isPromise = (v) => !!v && typeof v.then === "function";
+async function checkTiming(provider, d, issues) {
+  const at = (message) => issues.push({ effectId: d.id, message });
+  if (d.inputs.length) at("a timing effect takes no inputs: the host decodes its footage");
+  for (const probe of FOOTAGE) {
+    const fpsText = probe.fps ? ` at ${probe.fps} fps` : "";
+    let length;
+    try {
+      length = provider.timingLength(d.id, probe.footage);
+      if (isPromise(length)) return at("timingLength must be synchronous; it returned a Promise");
+      if (!(typeof length === "number" && Number.isFinite(length) && length > 0)) {
+        at(`timingLength for ${probe.footage} ms of footage is ${String(length)}; it must be a number of ms > 0`);
+        continue;
+      }
+      if (provider.timingLength(d.id, probe.footage) !== length) at(`timingLength is not pure: two calls for ${probe.footage} ms gave different lengths`);
+    } catch (e) {
+      at(`timingLength for ${probe.footage} ms of footage failed: ${codeOf(e)}`);
+      continue;
+    }
+    for (const share of [0, 0.25, 0.5, 0.75, 1]) {
+      const request2 = { time: share * length, ...probe };
+      try {
+        const sample = provider.timingSample(d.id, request2);
+        if (isPromise(sample)) return at("timingSample must be synchronous; it returned a Promise");
+        const problems = timingSampleProblems(sample, request2);
+        for (const p of problems) at(`timingSample at ${+request2.time.toFixed(3)} ms of ${probe.footage} ms footage${fpsText}: ${p}`);
+        if (!problems.length && JSON.stringify(provider.timingSample(d.id, request2)) !== JSON.stringify(sample)) at(`timingSample is not pure: two calls at ${+request2.time.toFixed(3)} ms gave different samples`);
+      } catch (e) {
+        at(`timingSample at ${+request2.time.toFixed(3)} ms of ${probe.footage} ms footage${fpsText} failed: ${codeOf(e)}`);
+      }
+    }
+  }
+  const request = { time: 0, footage: 1e3 };
+  const badLength = await rejectsWith("invalid_values", () => provider.timingLength(d.id, 1e3, { __not_a_control__: 1 }));
+  if (badLength) at(`timingLength with an unknown control ${badLength}`);
+  const badSample = await rejectsWith("invalid_values", () => provider.timingSample(d.id, request, { __not_a_control__: 1 }));
+  if (badSample) at(`timingSample with an unknown control ${badSample}`);
+  const noFootage = await rejectsWith("unsupported", () => provider.timingLength(d.id, 0));
+  if (noFootage) at(`timingLength of 0 ms of footage ${noFootage}`);
+  const badFps = await rejectsWith("unsupported", () => provider.timingSample(d.id, { ...request, fps: 0 }));
+  if (badFps) at(`timingSample at 0 fps ${badFps}`);
+  const badTime = await rejectsWith("unsupported", () => provider.timingSample(d.id, { ...request, time: Number.NaN }));
+  if (badTime) at(`timingSample at time NaN ${badTime}`);
+}
 var wrongValue = (slot) => slot.type === "number" ? "not a number" : slot.type === "text" ? 42 : slot.type === "color" ? "blue" : 42;
 function checkSlot(templateId, slot, issues) {
   const at = (message) => issues.push({ templateId, message: `slot ${JSON.stringify(slot?.name)}: ${message}` });
@@ -324,6 +382,8 @@ async function checkEffectProvider(provider, options = {}) {
   if (caps?.supportsCamera !== void 0 && typeof caps.supportsCamera !== "boolean") top("capabilities.supportsCamera is not a boolean");
   if (caps?.supportsCamera && typeof provider.cameraView !== "function") top("supportsCamera is set but cameraView is missing");
   if (provider.sampleCameraMove && typeof provider.cameraView !== "function") top("sampleCameraMove is present but cameraView is missing");
+  if (caps?.supportsTiming !== void 0 && typeof caps.supportsTiming !== "boolean") top("capabilities.supportsTiming is not a boolean");
+  for (const m of ["timingLength", "timingSample"]) if (caps?.supportsTiming && typeof provider[m] !== "function") top(`supportsTiming is set but ${m} is missing`);
   if (caps?.supportsTemplates !== void 0 && typeof caps.supportsTemplates !== "boolean") top("capabilities.supportsTemplates is not a boolean");
   const templateMethods = ["listTemplates", "describeTemplate", "instantiateTemplate"];
   if (caps?.supportsTemplates) {
@@ -338,6 +398,7 @@ async function checkEffectProvider(provider, options = {}) {
     checkSummary(e, issues);
   }
   if (!caps?.supportsCamera && list.some((e) => e.kind === "camera")) top("the catalog lists camera effects but capabilities.supportsCamera is not set");
+  if (!caps?.supportsTiming && list.some((e) => e.kind === "timing")) top("the catalog lists timing effects but capabilities.supportsTiming is not set");
   const all = await provider.search("");
   if (all.length !== list.length) top(`search("") returned ${all.length} effects, list() ${list.length}`);
   const firstUse = list[0]?.uses[0];
@@ -357,6 +418,21 @@ async function checkEffectProvider(provider, options = {}) {
     const wrongKind = notCamera && await rejectsWith("unsupported", () => provider.cameraView(notCamera.id, probe));
     if (wrongKind) issues.push({ effectId: notCamera.id, message: `cameraView of a ${notCamera.kind} effect ${wrongKind}` });
   }
+  const timing = caps?.supportsTiming && provider.timingLength && provider.timingSample;
+  if (timing) {
+    const request = { time: 0, footage: 1e3 };
+    const unknownLength = await rejectsWith("unknown_effect", () => provider.timingLength("__no_such_effect__", 1e3));
+    if (unknownLength) top(`timingLength of an unknown id ${unknownLength}`);
+    const unknownSample = await rejectsWith("unknown_effect", () => provider.timingSample("__no_such_effect__", request));
+    if (unknownSample) top(`timingSample of an unknown id ${unknownSample}`);
+    const notTiming = list.find((e) => e.kind !== "timing");
+    if (notTiming) {
+      const wrongLength = await rejectsWith("unsupported", () => provider.timingLength(notTiming.id, 1e3));
+      if (wrongLength) issues.push({ effectId: notTiming.id, message: `timingLength of a ${notTiming.kind} effect ${wrongLength}` });
+      const wrongSample = await rejectsWith("unsupported", () => provider.timingSample(notTiming.id, request));
+      if (wrongSample) issues.push({ effectId: notTiming.id, message: `timingSample of a ${notTiming.kind} effect ${wrongSample}` });
+    }
+  }
   const size = options.size ?? 8;
   for (const id of options.ids ?? [...ids]) {
     let d;
@@ -369,6 +445,7 @@ async function checkEffectProvider(provider, options = {}) {
     checkDescription(id, d, issues);
     if (options.render !== false && d.kind !== "motion") await checkRender(provider, d, size, issues);
     if (d.kind === "camera" && d.camera && caps.supportsCamera && provider.cameraView) await checkCamera(provider, d, issues);
+    if (d.kind === "timing" && timing) await checkTiming(provider, d, issues);
     if ((d.kind === "vector" || d.kind === "motion") && caps.supportsVector && provider.applyVectorEffect) {
       try {
         const m = await provider.applyVectorEffect(id, '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><rect id="r" width="10" height="10"/></svg>');
@@ -383,7 +460,7 @@ async function checkEffectProvider(provider, options = {}) {
   }
   if (caps?.supportsAuthoring && options.authoring !== false && typeof provider.openAuthoring === "function") {
     const targetEffect = (await Promise.all((options.ids ?? [...ids]).map((id) => provider.describe(id)))).find(
-      (d) => d.kind !== "motion" && d.kind !== "vector" && d.kind !== "camera"
+      (d) => d.kind !== "motion" && d.kind !== "vector" && d.kind !== "camera" && d.kind !== "timing"
     );
     if (targetEffect) {
       try {
@@ -862,6 +939,79 @@ var CAMERA_DESCRIPTIONS = [
     inputs: []
   }
 ];
+var TIMING_DESCRIPTIONS = [
+  {
+    id: "fake.speed",
+    name: "Speed change",
+    kind: "timing",
+    category: "timing",
+    uses: ["timing"],
+    description: "Footage played slower or faster throughout; slowed frames blend the two either side, sped-up ones average the frames they pass over.",
+    tags: ["retime", "slow motion", "time-lapse"],
+    transparent: false,
+    loop: false,
+    controls: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        speed: { type: "number", minimum: 0.1, maximum: 8, description: "Playback speed as a multiple of real time, 0.1\u20138 (0.5 is half speed). Default 0.5." },
+        smooth: { type: "boolean", description: "Blend frames: in-betweens when slowed, motion blur when sped up. Default true." }
+      }
+    },
+    defaults: { speed: 0.5, smooth: true },
+    presets: [
+      { name: "Slow motion", values: { speed: 0.25 } },
+      { name: "Double speed", values: { speed: 2 } }
+    ],
+    inputs: []
+  },
+  {
+    id: "fake.freeze",
+    name: "Freeze frame",
+    kind: "timing",
+    category: "timing",
+    uses: ["timing"],
+    description: "Footage that stops on one frame, holds it, then plays on from where it stopped.",
+    tags: ["retime", "freeze", "hold"],
+    transparent: false,
+    loop: false,
+    controls: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        at: { type: "number", minimum: 0, maximum: 1, description: "Where it freezes, as a share of the footage, 0\u20131. Default 0.5." },
+        hold: { type: "number", minimum: 0, maximum: 1e4, description: "How long it holds (ms). Default 1000." }
+      }
+    },
+    defaults: { at: 0.5, hold: 1e3 },
+    presets: [{ name: "Opening still", values: { at: 0, hold: 2e3 } }],
+    inputs: []
+  },
+  {
+    id: "fake.echo",
+    name: "Frame echo",
+    kind: "timing",
+    category: "timing",
+    uses: ["timing"],
+    description: "Each frame with fading copies of the frames just before it, so moving things leave a trail.",
+    tags: ["retime", "echo", "trail"],
+    transparent: false,
+    loop: false,
+    controls: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        echoes: { type: "integer", minimum: 1, maximum: 8, description: "Copies of earlier frames, 1\u20138. Default 3." },
+        spacing: { type: "number", minimum: 10, maximum: 500, description: "Footage time between copies (ms). Default 100." },
+        decay: { type: "number", minimum: 0.1, maximum: 0.95, description: "Each copy's weight as a share of the one after it, 0.1\u20130.95. Default 0.5." },
+        lighten: { type: "boolean", description: "Keep the brightest of the copies (light trails) instead of averaging them. Default false." }
+      }
+    },
+    defaults: { echoes: 3, spacing: 100, decay: 0.5, lighten: false },
+    presets: [{ name: "Light trails", values: { echoes: 6, spacing: 50, decay: 0.8, lighten: true } }],
+    inputs: []
+  }
+];
 var summaryOf = ({ controls: _c, defaults: _d, presets: _p, inputs: _i, ...summary }) => summary;
 var hexToRgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
 var smooth = (t) => t * t * (3 - 2 * t);
@@ -998,6 +1148,53 @@ function cameraViewOf(d, ctx, v) {
       throw new EffectUnsupportedError(`"${d.id}" is a ${d.kind} effect, not a camera move.`, d.id);
   }
 }
+function timingLengthOf(d, footage, v) {
+  switch (d.id) {
+    case "fake.speed":
+      return footage / v.speed;
+    case "fake.freeze":
+      return footage + v.hold;
+    case "fake.echo":
+      return footage;
+    default:
+      throw new EffectUnsupportedError(`"${d.id}" is a ${d.kind} effect, not a timing effect.`, d.id);
+  }
+}
+function timingFramesOf(d, request, v) {
+  const { time, fps } = request;
+  const frameMs = 1e3 / fps;
+  switch (d.id) {
+    case "fake.speed": {
+      const speed = v.speed;
+      const s = time * speed;
+      if (!v.smooth) return { frames: [{ time: s, weight: 1 }] };
+      if (speed <= 1) {
+        const i = s / frameMs;
+        const f = Math.floor(i + 1e-6);
+        const frac = Math.max(0, i - f);
+        return { frames: [{ time: f * frameMs, weight: 1 - frac }, { time: (f + 1) * frameMs, weight: frac }] };
+      }
+      const n = Math.ceil(speed);
+      return { frames: Array.from({ length: n }, (_, k) => ({ time: s + k * speed * frameMs / n, weight: 1 })) };
+    }
+    case "fake.freeze": {
+      const at = Math.floor(v.at * request.footage / frameMs + 1e-6) * frameMs;
+      const hold = v.hold;
+      return { frames: [{ time: time < at ? time : time < at + hold ? at : time - hold, weight: 1 }] };
+    }
+    case "fake.echo": {
+      const frames = [];
+      for (let k = 0; k <= v.echoes; k++) {
+        const t = time - k * v.spacing;
+        if (t < 0) break;
+        frames.push({ time: t, weight: Math.pow(v.decay, k) });
+      }
+      return { frames, lighten: v.lighten };
+    }
+    default:
+      throw new EffectUnsupportedError(`"${d.id}" is a ${d.kind} effect, not a timing effect.`, d.id);
+  }
+}
 function toFloat(p) {
   const f = new Float32Array(p.data.length);
   for (let i = 0; i < f.length; i += 4) {
@@ -1029,11 +1226,12 @@ function createFakeEffectProvider(options = {}) {
     supportsVector: true,
     supportsAuthoring,
     ...options.camera ? { supportsCamera: true } : {},
+    ...options.timing ? { supportsTiming: true } : {},
     ...options.templates ? { supportsTemplates: true } : {},
     maxSize: 8192,
     ...options.capabilities
   };
-  const all = options.camera ? [...DESCRIPTIONS, ...CAMERA_DESCRIPTIONS] : DESCRIPTIONS;
+  const all = [...DESCRIPTIONS, ...options.camera ? CAMERA_DESCRIPTIONS : [], ...options.timing ? TIMING_DESCRIPTIONS : []];
   const byId = new Map(all.map((d) => [d.id, d]));
   const get = (id) => {
     const d = byId.get(id);
@@ -1047,6 +1245,25 @@ function createFakeEffectProvider(options = {}) {
     if (!(ctx.u >= 0 && ctx.u <= 1)) throw new EffectUnsupportedError(`u must be 0\u20131 through the move, got ${ctx.u}.`, id);
     return cameraViewOf(d, ctx, resolveEffectValues(d, values));
   };
+  const timingEffect = (id) => {
+    const d = get(id);
+    if (d.kind !== "timing") {
+      const ids = TIMING_DESCRIPTIONS.map((t) => `"${t.id}"`).join(", ");
+      throw new EffectUnsupportedError(`"${id}" is a ${d.kind} effect, not a timing effect; the timing effects are ${ids}.`, id);
+    }
+    return d;
+  };
+  const timingLength = (id, footageMs, values) => {
+    const d = timingEffect(id);
+    checkTimingFootage(footageMs, id);
+    return timingLengthOf(d, footageMs, resolveEffectValues(d, values));
+  };
+  const timingSample = (id, request, values) => {
+    const d = timingEffect(id);
+    const fps = checkTimingRequest(request, id);
+    const raw = timingFramesOf(d, { time: request.time, footage: request.footage, fps }, resolveEffectValues(d, values));
+    return normaliseTimingSample(raw.frames, { ...request, fps }, raw.lighten ? "lighten" : "average");
+  };
   const provider = {
     id: "fake",
     name: "Fake effects",
@@ -1058,6 +1275,7 @@ function createFakeEffectProvider(options = {}) {
     createRenderer(id, ro) {
       const d = get(id);
       if (d.kind === "camera") throw new EffectUnsupportedError(`"${id}" is a camera move: it moves a scene's camera and draws no pixels. Use cameraView.`, id);
+      if (d.kind === "timing") throw new EffectUnsupportedError(`"${id}" is a timing effect: it retimes video footage and draws no pixels of its own. Use timingSample and blend the footage frames it names.`, id);
       if (d.kind !== "shader") throw new EffectUnsupportedError(`"${id}" is a ${d.kind} effect; use applyVectorEffect.`, id);
       const { width, height } = ro;
       const depth = ro.depth ?? 8;
@@ -1135,6 +1353,7 @@ function createFakeEffectProvider(options = {}) {
         return sampleCameraViews((u) => camera(id, { from, to, u, ms, stage }, values), { ms, fps, cut: d.camera?.cut });
       }
     } : {},
+    ...options.timing ? { timingLength, timingSample } : {},
     ...options.templates ? fakeTemplateMethods() : {},
     ...supportsAuthoring ? {
       openAuthoring: (from) => createEffectAuthoringSession(from, { provider })
@@ -1152,7 +1371,8 @@ var EFFECT_USE_LABELS = {
   title: "Title",
   motion: "Motion",
   interactive: "Interactive",
-  camera: "Camera"
+  camera: "Camera",
+  timing: "Timing"
 };
 var HEX2 = /^#[0-9a-f]{6}([0-9a-f]{2})?$/i;
 var typeOf = (s) => Array.isArray(s.type) ? s.type.find((t) => t !== "null") : s.type;
@@ -1682,9 +1902,14 @@ export {
   EffectUnsupportedError,
   EffectsSlot,
   NoEffectsProviderError,
+  TIMING_BLENDS,
+  TIMING_DEFAULT_FPS,
+  TIMING_MAX_FPS,
+  TIMING_MAX_FRAMES,
   UnknownEffectError,
   UnknownTemplateError,
   applyEffectMask,
+  blendTimingFrames,
   cameraBoxOfView,
   cameraMoveField,
   cameraMoveIdList,
@@ -1694,6 +1919,8 @@ export {
   checkEffectProvider,
   checkEffectSequence,
   checkTemplateValues,
+  checkTimingFootage,
+  checkTimingRequest,
   countEffectTags,
   createEffectAuthoringSession,
   createEffectAuthoringToolProvider,
@@ -1730,6 +1957,7 @@ export {
   layerImageInput,
   linearToSrgb,
   normaliseEffectTag,
+  normaliseTimingSample,
   pathControlsOf,
   renderEffectThumbnail,
   resolveCameraMoveSpec,
@@ -1744,5 +1972,6 @@ export {
   templateSlotSummary,
   templateSlotTakes,
   templateValueProblem,
-  templateValuesSchema
+  templateValuesSchema,
+  timingSampleProblems
 };

package/dist/effects/types.d.cts

@@ -11,9 +11,10 @@ import type { FlairSvgAnimation } from '../animation-editor/flair.cjs';
 import type { EffectAuthoringSession, EffectAuthoringSource } from './authoring.cjs';
 /**
  * How an effect is drawn: a pixel shader, an animated vector picture, motion applied to someone
- * else's vector art, or a camera move, which moves a scene's camera and draws no pixels.
+ * else's vector art, a camera move, which moves a scene's camera and draws no pixels, or a
+ * timing effect, which retimes video footage and draws no pixels of its own.
  */
-export type EffectKind = 'shader' | 'vector' | 'motion' | 'camera';
+export type EffectKind = 'shader' | 'vector' | 'motion' | 'camera' | 'timing';
 /**
  * What an effect is for. An effect may have several uses.
  *
@@ -26,8 +27,10 @@ export type EffectKind = 'shader' | 'vector' | 'motion' | 'camera';
  * - `interactive`: reacts to pointer, scroll or audio input at run time.
  * - `camera`: moves a scene's camera (`cameraView`). Only `camera` effects have it, and they have
  *   no other use, so editors that draw pixels never offer them.
+ * - `timing`: retimes video footage (`timingSample`): slow motion, a reverse, a freeze, a long
+ *   exposure. Only `timing` effects have it, and they have no other use.
  */
-export type EffectUse = 'filter' | 'transition' | 'generator' | 'overlay' | 'title' | 'motion' | 'interactive' | 'camera';
+export type EffectUse = 'filter' | 'transition' | 'generator' | 'overlay' | 'title' | 'motion' | 'interactive' | 'camera' | 'timing';
 export declare const EFFECT_KINDS: readonly EffectKind[];
 export declare const EFFECT_USES: readonly EffectUse[];
 /**
@@ -66,7 +69,10 @@ export interface EffectSummary {
     transparent: boolean;
     /** True when the effect loops; its `duration` is then one cycle. */
     loop: boolean;
-    /** Length of one play (ms). Absent for effects that do not change over time. */
+    /**
+     * Length of one play (ms). Absent for effects that do not change over time, and for `timing`
+     * effects, whose length depends on their footage (`timingLength`).
+     */
     duration?: number;
     /**
      * The control (a number from 0 to 1) setting how opaque the effect's own background is: at 0
@@ -300,6 +306,59 @@ export interface CameraMoveSample {
     /** Ms of the cut, when the move has one. */
     cut?: number;
 }
+/** The frame rate footage is taken to have when a timing request does not say. */
+export declare const TIMING_DEFAULT_FPS = 30;
+/** Most footage frames one retimed frame blends (`TimingSample.frames`). */
+export declare const TIMING_MAX_FRAMES = 128;
+/** Highest footage frame rate a timing request may give. */
+export declare const TIMING_MAX_FPS = 240;
+/**
+ * How a retimed frame's footage frames combine (straight-alpha RGBA in, straight alpha out;
+ * `blendTimingFrames` is the reference):
+ *
+ * - `average`: the weighted mean in premultiplied alpha, so transparent edges do not darken.
+ *   Colour is Σ(c·a·w) / Σ(a·w) and alpha Σ(a·w) / Σw, with `a` the frame's alpha (0–1).
+ * - `lighten`: each channel's brightest. Every frame is first scaled by `weight / maxWeight`
+ *   (`k`): colour by `a·k`, alpha by `k`. The result keeps the largest scaled colour and the
+ *   largest scaled alpha, and its colour is not divided back up by its alpha, so a faded trail
+ *   stays dimmer.
+ *
+ * A single frame is shown as it is either way.
+ */
+export type TimingBlend = 'average' | 'lighten';
+export declare const TIMING_BLENDS: readonly TimingBlend[];
+/** Where a retimed frame is: what `timingSample` takes. */
+export interface TimingSampleRequest {
+    /** Ms into the retimed clip (any finite number; frames are held within the footage). */
+    time: number;
+    /** Length of the footage (ms); > 0. */
+    footage: number;
+    /** Footage frames per second, > 0 and at most `TIMING_MAX_FPS`. Default `TIMING_DEFAULT_FPS`. */
+    fps?: number;
+}
+/** One footage frame of a retimed frame. */
+export interface TimingFrame {
+    /** Footage time (ms): the start of a frame, `index * 1000 / fps`. */
+    time: number;
+    /** Share of the blend, > 0; a sample's weights add up to 1. */
+    weight: number;
+}
+/**
+ * The footage frames one retimed frame is made of, and how to blend them. The host decodes the
+ * frames from its own footage and blends them (`blendTimingFrames` does it for `EffectPixels`).
+ *
+ * - Each `time` is a footage frame's start, `index * 1000 / fps` with a whole `index` from 0 to
+ *   the footage's last frame (`ceil(footage * fps / 1000) - 1`): a time before the footage is held
+ *   on its first frame and one after it on its last.
+ * - Times are distinct (frames that land on the same footage frame are merged, their weights
+ *   added), sorted earliest first, and at most `TIMING_MAX_FRAMES` (spaced evenly when an effect
+ *   wants more).
+ * - Weights are > 0 and add up to 1.
+ */
+export interface TimingSample {
+    frames: readonly TimingFrame[];
+    blend: TimingBlend;
+}
 /** A box in a sequence's stage units (pixels of `EffectSequence.stage`). */
 export interface EffectRect {
     x: number;
@@ -516,6 +575,8 @@ export interface EffectProviderCapabilities {
     supportsAuthoring?: boolean;
     /** Lists `camera` effects and implements `cameraView` (and maybe `sampleCameraMove`). */
     supportsCamera?: boolean;
+    /** Lists `timing` effects and implements `timingLength` and `timingSample`. */
+    supportsTiming?: boolean;
     /** Implements `listTemplates`, `describeTemplate` and `instantiateTemplate`. */
     supportsTemplates?: boolean;
 }
@@ -539,7 +600,8 @@ export interface EffectProvider {
     describe(id: string): MaybePromise<EffectDescription>;
     /**
      * A pixel renderer. A `vector` effect may refuse with `EffectUnsupportedError` where it cannot
-     * lay out SVG (a Worker); a `camera` effect draws no pixels and may refuse with one saying so.
+     * lay out SVG (a Worker); `camera` and `timing` effects draw no pixels of their own and may
+     * refuse with one saying so.
      */
     createRenderer(id: string, options: EffectRendererOptions): MaybePromise<EffectRenderer>;
     /**
@@ -573,6 +635,23 @@ export interface EffectProvider {
      * `sampleEffectCameraMove` falls back to `cameraView` per frame. Errors as for `cameraView`.
      */
     sampleCameraMove?(id: string, request: CameraMoveSampleRequest): MaybePromise<CameraMoveSample>;
+    /**
+     * Ms a timing effect's retimed clip lasts for footage `footageMs` long (a speed change stretches
+     * or squeezes it, a freeze adds its hold, a boomerang goes there and back); > 0. Present when
+     * `capabilities.supportsTiming`. Synchronous and pure. Unknown ids throw `UnknownEffectError`,
+     * invalid values `EffectControlError`, and an effect that is not a timing effect (or a footage
+     * length that is not a number of ms > 0) `EffectUnsupportedError`, each with a sentence naming
+     * what is valid.
+     */
+    timingLength?(id: string, footageMs: number, values?: EffectValues): number;
+    /**
+     * The footage frames retimed frame `request.time` shows and how to blend them (see
+     * `TimingSample` for exactly what it holds). Present when `capabilities.supportsTiming`.
+     * Synchronous and pure: a frame can be drawn on its own, in any order, and the same id,
+     * request and values always give the same sample. Errors as for `timingLength`; a time that is
+     * not finite or an `fps` outside 0–`TIMING_MAX_FPS` also throw `EffectUnsupportedError`.
+     */
+    timingSample?(id: string, request: TimingSampleRequest, values?: EffectValues): TimingSample;
     /** Sequence templates, best match first. Present when `capabilities.supportsTemplates`. */
     listTemplates?(options?: EffectTemplateSearchOptions): MaybePromise<readonly EffectTemplateSummary[]>;
     /** A template with its slots. Unknown ids throw `UnknownTemplateError`. */