Skip to content

Write HTML. Render video. Built for agents.

7.0 KB
Raw Blame
/** A ramp is a `rate` lane in `data-automation`; `sourceTimeAt` is the one rate-to-time mapping consumers share. */

import { RATE_TARGET, sampleAutomationLane, type HfAutomationLane } from "./audioAutomation.js";
import { laneFromAttr } from "./runtime/audioAutomationVolume.js";
import { MAX_PLAYBACK_RATE, MIN_PLAYBACK_RATE } from "./playbackRateBounds.js";

/** A constant multiplier, or a lane whose `v` is the multiplier over clip-local time. */
export type RateSpec = number | HfAutomationLane;

const SHIFT_RESAMPLES = 16;

/**
 * The lane as seen from `dt` seconds into the clip: what a renderer sees after it trims the clip's start.
 * A shaped segment (`curve`, `viaX`) cut in the middle is resampled, since its shape belongs to its left point.
 */
export function shiftRateLane(spec: RateSpec, dt: number): RateSpec {
  if (typeof spec === "number" || dt === 0) return spec;
  const next = spec.points.findIndex((p) => p.t > dt);
  const later = next < 0 ? [] : spec.points.slice(next).map((p) => ({ ...p, t: p.t - dt }));
  const left = next > 0 ? spec.points[next - 1] : undefined;
  const shaped = left !== undefined && (left.curve || left.viaX !== undefined);
  const cut = shaped && next > 0 ? spec.points[next]!.t - dt : 0;
  const samples = Array.from({ length: shaped ? SHIFT_RESAMPLES - 1 : 0 }, (_, k) => {
    const t = ((k + 1) * cut) / SHIFT_RESAMPLES;
    return { t, v: rateAt(spec, dt + t) };
  });
  return { ...spec, points: [{ t: 0, v: rateAt(spec, dt) }, ...samples, ...later] };
}

const CELLS_PER_SEGMENT = 48;

interface RateTable {
  /** Ascending clip-local times and the source seconds consumed by each. */
  ts: Float64Array;
  ss: Float64Array;
  firstRate: number;
  lastRate: number;
}

const tables = new WeakMap<HfAutomationLane, RateTable>();

function buildTable(lane: HfAutomationLane): RateTable {
  const pts = lane.points;
  const firstRate = pts[0]!.v;
  const lastRate = pts[pts.length - 1]!.v;
  const ts: number[] = [0];
  const ss: number[] = [0];
  const push = (t: number) => {
    const prevT = ts[ts.length - 1]!;
    if (t <= prevT) return;
    const prevRate = sampleAutomationLane(lane, prevT, "log");
    ts.push(t);
    ss.push(
      ss[ss.length - 1]! + ((prevRate + sampleAutomationLane(lane, t, "log")) / 2) * (t - prevT),
    );
  };
  const first = Math.max(0, pts[0]!.t);
  push(first);
  for (let i = 1; i < pts.length; i += 1) {
    const a = pts[i - 1]!.t;
    const b = pts[i]!.t;
    if (b <= 0) continue;
    for (let k = 1; k <= CELLS_PER_SEGMENT; k += 1)
      push(Math.max(a, 0) + ((b - a) * k) / CELLS_PER_SEGMENT);
  }
  return { ts: Float64Array.from(ts), ss: Float64Array.from(ss), firstRate, lastRate };
}

function tableFor(lane: HfAutomationLane): RateTable {
  let table = tables.get(lane);
  if (!table) {
    table = buildTable(lane);
    tables.set(lane, table);
  }
  return table;
}

function usable(spec: RateSpec): spec is HfAutomationLane {
  return typeof spec !== "number" && spec.points.length > 0;
}

/** Speed multiplier at clip-local time `t`. */
export function rateAt(spec: RateSpec, t: number): number {
  if (typeof spec === "number") return spec;
  return usable(spec) ? sampleAutomationLane(spec, t, "log") : 1;
}

/** Piecewise-linear lookup of `x` in the ascending `xs`, read off `ys`; caller keeps `x` inside `xs`. */
function interpolate(xs: Float64Array, ys: Float64Array, x: number): number {
  let lo = 0;
  let hi = xs.length - 1;
  while (hi - lo > 1) {
    const mid = (lo + hi) >> 1;
    if (xs[mid]! <= x) lo = mid;
    else hi = mid;
  }
  return ys[lo]! + ((ys[hi]! - ys[lo]!) * (x - xs[lo]!)) / (xs[hi]! - xs[lo]!);
}

/** Source seconds consumed by clip-local time `t` (the integral of the rate). */
export function sourceTimeAt(spec: RateSpec, t: number): number {
  if (typeof spec === "number") return t * spec;
  if (!usable(spec)) return t;
  const { ts, ss, firstRate, lastRate } = tableFor(spec);
  const last = ts.length - 1;
  if (t <= 0) return t * firstRate;
  if (t >= ts[last]!) return ss[last]! + (t - ts[last]!) * lastRate;
  return interpolate(ts, ss, t);
}

/** Inverse of `sourceTimeAt`: the clip-local time at which `source` seconds have been consumed. */
export function timeAtSourceTime(spec: RateSpec, source: number): number {
  if (typeof spec === "number") return source / spec;
  if (!usable(spec)) return source;
  const { ts, ss, firstRate, lastRate } = tableFor(spec);
  const last = ts.length - 1;
  if (source <= 0) return source / firstRate;
  if (source >= ss[last]!) return ts[last]! + (source - ss[last]!) / lastRate;
  return interpolate(ss, ts, source);
}

/** The `rate` lane inside a `data-automation` attribute value, or null when absent or unreadable. */
export function parseRateLane(raw: string | null | undefined): HfAutomationLane | null {
  return raw ? laneFromAttr(raw, RATE_TARGET) : null;
}

/** A clip's rate: its `rate` lane when it has one, otherwise the constant. */
export function resolveRateSpec(
  automationAttr: string | null | undefined,
  constant: number,
): RateSpec {
  return parseRateLane(automationAttr) ?? constant;
}

interface RatePreset {
  id: string;
  label: string;
  /** Points as [progress 0..1 through the clip, speed]. */
  points: ReadonlyArray<readonly [number, number]>;
}

/** The CapCut-style presets; `speedPresetLane` stretches one over a clip's duration. */
export const SPEED_PRESETS = [
  {
    id: "montage",
    label: "Montage",
    points: [
      [0, 0.9],
      [0.15, 0.3],
      [0.5, 2.5],
      [0.85, 0.3],
      [1, 0.9],
    ],
  },
  {
    id: "hero",
    label: "Hero",
    points: [
      [0, 1],
      [0.25, 1.6],
      [0.5, 0.25],
      [0.75, 1.6],
      [1, 1],
    ],
  },
  {
    id: "bullet",
    label: "Bullet",
    points: [
      [0, 3],
      [0.4, 3],
      [0.5, 0.15],
      [0.6, 3],
      [1, 3],
    ],
  },
  {
    id: "jump-cut",
    label: "Jump cut",
    points: [
      [0, 0.5],
      [0.24, 0.5],
      [0.26, 3],
      [0.5, 3],
      [0.52, 0.5],
      [0.74, 0.5],
      [0.76, 3],
      [1, 3],
    ],
  },
  {
    id: "flash-in",
    label: "Flash in",
    points: [
      [0, 0.3],
      [0.6, 0.6],
      [1, 5],
    ],
  },
  {
    id: "flash-out",
    label: "Flash out",
    points: [
      [0, 5],
      [0.4, 0.6],
      [1, 0.3],
    ],
  },
  {
    id: "ramp-in",
    label: "Ramp in",
    points: [
      [0, 0.5],
      [1, 1],
    ],
  },
  {
    id: "ramp-out",
    label: "Ramp out",
    points: [
      [0, 1],
      [1, 0.5],
    ],
  },
  {
    id: "slowmo-middle",
    label: "Slow-mo middle",
    points: [
      [0, 1],
      [1 / 3, 0.35],
      [2 / 3, 0.35],
      [1, 1],
    ],
  },
] as const satisfies readonly RatePreset[];

export type SpeedPresetId = (typeof SPEED_PRESETS)[number]["id"];

export function speedPresetLane(id: SpeedPresetId, clipDuration: number): HfAutomationLane {
  const preset = SPEED_PRESETS.find((p) => p.id === id)!;
  return {
    target: RATE_TARGET,
    points: preset.points.map(([x, v]) => ({
      t: x * clipDuration,
      v: Math.min(MAX_PLAYBACK_RATE, Math.max(MIN_PLAYBACK_RATE, v)),
    })),
  };
}