@hyperframes/core 0.8.50 → 0.8.52

package/dist/speedRamp.d.ts

@@ -0,0 +1,48 @@
+/** A ramp is a `rate` lane in `data-automation`; `sourceTimeAt` is the one rate-to-time mapping consumers share. */
+import { type HfAutomationLane } from "./audioAutomation.js";
+/** A constant multiplier, or a lane whose `v` is the multiplier over clip-local time. */
+export type RateSpec = number | HfAutomationLane;
+/**
+ * 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 declare function shiftRateLane(spec: RateSpec, dt: number): RateSpec;
+/** Speed multiplier at clip-local time `t`. */
+export declare function rateAt(spec: RateSpec, t: number): number;
+/** Source seconds consumed by clip-local time `t` (the integral of the rate). */
+export declare function sourceTimeAt(spec: RateSpec, t: number): number;
+/** Inverse of `sourceTimeAt`: the clip-local time at which `source` seconds have been consumed. */
+export declare function timeAtSourceTime(spec: RateSpec, source: number): number;
+/** The `rate` lane inside a `data-automation` attribute value, or null when absent or unreadable. */
+export declare function parseRateLane(raw: string | null | undefined): HfAutomationLane | null;
+/** A clip's rate: its `rate` lane when it has one, otherwise the constant. */
+export declare function resolveRateSpec(automationAttr: string | null | undefined, constant: number): RateSpec;
+/** The CapCut-style presets; `speedPresetLane` stretches one over a clip's duration. */
+export declare const SPEED_PRESETS: readonly [{
+    readonly id: "montage";
+    readonly label: "Montage";
+    readonly points: readonly [readonly [0, 0.9], readonly [0.15, 0.3], readonly [0.5, 2.5], readonly [0.85, 0.3], readonly [1, 0.9]];
+}, {
+    readonly id: "hero";
+    readonly label: "Hero";
+    readonly points: readonly [readonly [0, 1], readonly [0.25, 1.6], readonly [0.5, 0.25], readonly [0.75, 1.6], readonly [1, 1]];
+}, {
+    readonly id: "bullet";
+    readonly label: "Bullet";
+    readonly points: readonly [readonly [0, 3], readonly [0.4, 3], readonly [0.5, 0.15], readonly [0.6, 3], readonly [1, 3]];
+}, {
+    readonly id: "jump-cut";
+    readonly label: "Jump cut";
+    readonly points: readonly [readonly [0, 0.5], readonly [0.24, 0.5], readonly [0.26, 3], readonly [0.5, 3], readonly [0.52, 0.5], readonly [0.74, 0.5], readonly [0.76, 3], readonly [1, 3]];
+}, {
+    readonly id: "flash-in";
+    readonly label: "Flash in";
+    readonly points: readonly [readonly [0, 0.3], readonly [0.6, 0.6], readonly [1, 5]];
+}, {
+    readonly id: "flash-out";
+    readonly label: "Flash out";
+    readonly points: readonly [readonly [0, 5], readonly [0.4, 0.6], readonly [1, 0.3]];
+}];
+export type SpeedPresetId = (typeof SPEED_PRESETS)[number]["id"];
+export declare function speedPresetLane(id: SpeedPresetId, clipDuration: number): HfAutomationLane;
+//# sourceMappingURL=speedRamp.d.ts.map

package/dist/speedRamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speedRamp.d.ts","sourceRoot":"","sources":["../src/speedRamp.ts"],"names":[],"mappings":"AAAA,oHAAoH;AAEpH,OAAO,EAAqC,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAIhG,yFAAyF;AACzF,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,gBAAgB,CAAC;AAIjD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ,CAYlE;AAsDD,+CAA+C;AAC/C,wBAAgB,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGxD;AAcD,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ9D;AAED,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQvE;AAED,qGAAqG;AACrG,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,gBAAgB,GAAG,IAAI,CAErF;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACzC,QAAQ,EAAE,MAAM,GACf,QAAQ,CAEV;AASD,wFAAwF;AACxF,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;EAkEgB,CAAC;AAE3C,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AAEjE,wBAAgB,eAAe,CAAC,EAAE,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,GAAG,gBAAgB,CASzF"}

package/dist/speedRamp.js

@@ -0,0 +1,196 @@
+/** A ramp is a `rate` lane in `data-automation`; `sourceTimeAt` is the one rate-to-time mapping consumers share. */
+import { RATE_TARGET, sampleAutomationLane } from "./audioAutomation.js";
+import { laneFromAttr } from "./runtime/audioAutomationVolume.js";
+import { MAX_PLAYBACK_RATE, MIN_PLAYBACK_RATE } from "./playbackRateBounds.js";
+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, dt) {
+    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;
+const tables = new WeakMap();
+function buildTable(lane) {
+    const pts = lane.points;
+    const firstRate = pts[0].v;
+    const lastRate = pts[pts.length - 1].v;
+    const ts = [0];
+    const ss = [0];
+    const push = (t) => {
+        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) {
+    let table = tables.get(lane);
+    if (!table) {
+        table = buildTable(lane);
+        tables.set(lane, table);
+    }
+    return table;
+}
+function usable(spec) {
+    return typeof spec !== "number" && spec.points.length > 0;
+}
+/** Speed multiplier at clip-local time `t`. */
+export function rateAt(spec, t) {
+    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, ys, x) {
+    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, t) {
+    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, source) {
+    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) {
+    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, constant) {
+    return parseRateLane(automationAttr) ?? constant;
+}
+/** 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],
+        ],
+    },
+];
+export function speedPresetLane(id, clipDuration) {
+    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)),
+        })),
+    };
+}
+//# sourceMappingURL=speedRamp.js.map

package/dist/speedRamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"speedRamp.js","sourceRoot":"","sources":["../src/speedRamp.ts"],"names":[],"mappings":"AAAA,oHAAoH;AAEpH,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAyB,MAAM,sBAAsB,CAAC;AAChG,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAK/E,MAAM,eAAe,GAAG,EAAE,CAAC;AAE3B;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAc,EAAE,EAAU;IACtD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,EAAE,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtD,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;IAC1F,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1D,MAAM,MAAM,GAAG,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAC7E,MAAM,GAAG,GAAG,MAAM,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAChF,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,eAAe,CAAC;QAC5C,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;IACxC,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC;AACpF,CAAC;AAED,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAU7B,MAAM,MAAM,GAAG,IAAI,OAAO,EAA+B,CAAC;AAE1D,SAAS,UAAU,CAAC,IAAsB;IACxC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;IACxB,MAAM,SAAS,GAAG,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC;IAC5B,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,CAAC,CAAC;IACxC,MAAM,EAAE,GAAa,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,EAAE,GAAa,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,EAAE;QACzB,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;QACjC,IAAI,CAAC,IAAI,KAAK;YAAE,OAAO;QACvB,MAAM,QAAQ,GAAG,oBAAoB,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC1D,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACX,EAAE,CAAC,IAAI,CACL,EAAE,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,CAAE,GAAG,CAAC,CAAC,QAAQ,GAAG,oBAAoB,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAC3F,CAAC;IACJ,CAAC,CAAC;IACF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC;IACrC,IAAI,CAAC,KAAK,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,iBAAiB,EAAE,CAAC,IAAI,CAAC;YAC5C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AACvF,CAAC;AAED,SAAS,QAAQ,CAAC,IAAsB;IACtC,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QACzB,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,MAAM,CAAC,IAAc;IAC5B,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;AAC5D,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,MAAM,CAAC,IAAc,EAAE,CAAS;IAC9C,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,yGAAyG;AACzG,SAAS,WAAW,CAAC,EAAgB,EAAE,EAAgB,EAAE,CAAS;IAChE,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IACvB,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;QACnB,MAAM,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,EAAE,CAAC,GAAG,CAAE,IAAI,CAAC;YAAE,EAAE,GAAG,GAAG,CAAC;;YACvB,EAAE,GAAG,GAAG,CAAC;IAChB,CAAC;IACD,OAAO,EAAE,CAAC,EAAE,CAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAE,GAAG,EAAE,CAAC,EAAE,CAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,CAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAE,GAAG,EAAE,CAAC,EAAE,CAAE,CAAC,CAAC;AAC/E,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,YAAY,CAAC,IAAc,EAAE,CAAS;IACpD,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC5B,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,IAAI,GAAG,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACjC,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,CAAE;QAAE,OAAO,EAAE,CAAC,IAAI,CAAE,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAE,CAAC,GAAG,QAAQ,CAAC;IAClE,OAAO,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,gBAAgB,CAAC,IAAc,EAAE,MAAc;IAC7D,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,MAAM,GAAG,IAAI,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC;IACjC,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,IAAI,GAAG,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3B,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,MAAM,GAAG,SAAS,CAAC;IAC3C,IAAI,MAAM,IAAI,EAAE,CAAC,IAAI,CAAE;QAAE,OAAO,EAAE,CAAC,IAAI,CAAE,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,IAAI,CAAE,CAAC,GAAG,QAAQ,CAAC;IAC5E,OAAO,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;AACrC,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,aAAa,CAAC,GAA8B;IAC1D,OAAO,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACrD,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,eAAe,CAC7B,cAAyC,EACzC,QAAgB;IAEhB,OAAO,aAAa,CAAC,cAAc,CAAC,IAAI,QAAQ,CAAC;AACnD,CAAC;AASD,wFAAwF;AACxF,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B;QACE,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,SAAS;QAChB,MAAM,EAAE;YACN,CAAC,CAAC,EAAE,GAAG,CAAC;YACR,CAAC,IAAI,EAAE,GAAG,CAAC;YACX,CAAC,GAAG,EAAE,GAAG,CAAC;YACV,CAAC,IAAI,EAAE,GAAG,CAAC;YACX,CAAC,CAAC,EAAE,GAAG,CAAC;SACT;KACF;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,MAAM;QACb,MAAM,EAAE;YACN,CAAC,CAAC,EAAE,CAAC,CAAC;YACN,CAAC,IAAI,EAAE,GAAG,CAAC;YACX,CAAC,GAAG,EAAE,IAAI,CAAC;YACX,CAAC,IAAI,EAAE,GAAG,CAAC;YACX,CAAC,CAAC,EAAE,CAAC,CAAC;SACP;KACF;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,QAAQ;QACf,MAAM,EAAE;YACN,CAAC,CAAC,EAAE,CAAC,CAAC;YACN,CAAC,GAAG,EAAE,CAAC,CAAC;YACR,CAAC,GAAG,EAAE,IAAI,CAAC;YACX,CAAC,GAAG,EAAE,CAAC,CAAC;YACR,CAAC,CAAC,EAAE,CAAC,CAAC;SACP;KACF;IACD;QACE,EAAE,EAAE,UAAU;QACd,KAAK,EAAE,UAAU;QACjB,MAAM,EAAE;YACN,CAAC,CAAC,EAAE,GAAG,CAAC;YACR,CAAC,IAAI,EAAE,GAAG,CAAC;YACX,CAAC,IAAI,EAAE,CAAC,CAAC;YACT,CAAC,GAAG,EAAE,CAAC,CAAC;YACR,CAAC,IAAI,EAAE,GAAG,CAAC;YACX,CAAC,IAAI,EAAE,GAAG,CAAC;YACX,CAAC,IAAI,EAAE,CAAC,CAAC;YACT,CAAC,CAAC,EAAE,CAAC,CAAC;SACP;KACF;IACD;QACE,EAAE,EAAE,UAAU;QACd,KAAK,EAAE,UAAU;QACjB,MAAM,EAAE;YACN,CAAC,CAAC,EAAE,GAAG,CAAC;YACR,CAAC,GAAG,EAAE,GAAG,CAAC;YACV,CAAC,CAAC,EAAE,CAAC,CAAC;SACP;KACF;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,WAAW;QAClB,MAAM,EAAE;YACN,CAAC,CAAC,EAAE,CAAC,CAAC;YACN,CAAC,GAAG,EAAE,GAAG,CAAC;YACV,CAAC,CAAC,EAAE,GAAG,CAAC;SACT;KACF;CACuC,CAAC;AAI3C,MAAM,UAAU,eAAe,CAAC,EAAiB,EAAE,YAAoB;IACrE,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAE,CAAC;IACvD,OAAO;QACL,MAAM,EAAE,WAAW;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACrC,CAAC,EAAE,CAAC,GAAG,YAAY;YACnB,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC;SAC/D,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}

package/dist/storyboard/types.d.ts

@@ -4,7 +4,7 @@
  * A storyboard is the plan for a video before any animation work happens: an
  * ordered set of frames (key moments) plus their narrative/script. It is
  * authored as a single canonical markdown file (`STORYBOARD.md`) and parsed
- * into this normalized shape for the Studio's storyboard view and for agents.
+ * into this normalized shape for agents.
  *
  * See PRD: "Storyboarding in HyperFrames". The markdown stays canonical; this
  * is the derived structure the parser produces.
@@ -19,7 +19,7 @@ export declare const STORYBOARD_FILENAME = "STORYBOARD.md";
 export declare const SCRIPT_FILENAME = "SCRIPT.md";
 /**
  * Lifecycle of a single frame. The agent advances each frame
- * `outline → built → animated`; the Studio renders progress from this.
+ * `outline → built → animated`; scripts and the agent read progress from this.
  */
 export type FrameStatus = "outline" | "built" | "animated";
 /** The set of recognized {@link FrameStatus} values. */

package/dist/storyboard/types.js

@@ -4,7 +4,7 @@
  * A storyboard is the plan for a video before any animation work happens: an
  * ordered set of frames (key moments) plus their narrative/script. It is
  * authored as a single canonical markdown file (`STORYBOARD.md`) and parsed
- * into this normalized shape for the Studio's storyboard view and for agents.
+ * into this normalized shape for agents.
  *
  * See PRD: "Storyboarding in HyperFrames". The markdown stays canonical; this
  * is the derived structure the parser produces.

package/docs/core.md

@@ -183,7 +183,7 @@ A clip is any discrete block on the timeline. We represent clips as HTML element
 
 - `id` — Unique identifier (e.g., "el-1")
 - `data-start` — Start time in seconds, or a clip `id` reference. See [Relative Timing](#relative-timing).
-- `data-duration` — Duration in seconds. Required for `<img>` clips. Optional for `<video>` and `<audio>` (defaults to the source media's full duration). Not used on compositions.
+- `data-duration` — Duration in seconds. Optional for `<img>` (defaults to 3 seconds), `<video>` and `<audio>` (default to the source media's length, less any playback offset, over the playback rate; an authored value trims). Not used on compositions.
 - `data-track-index` — Timeline track number. Tracks serve two purposes: they determine visual layering (higher tracks render in front) and they group clips into rows on the timeline. Clips on the same track **cannot overlap in time**.
 
 ### Media Clips (video, audio)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/core",
-  "version": "0.8.50",
+  "version": "0.8.52",
   "description": "",
   "repository": {
     "type": "git",
@@ -134,6 +134,10 @@
       "import": "./dist/audioAutomation.js",
       "types": "./dist/audioAutomation.d.ts"
     },
+    "./clip-facts": {
+      "import": "./dist/clipFacts.js",
+      "types": "./dist/clipFacts.d.ts"
+    },
     "./audio-gain": {
       "import": "./dist/audioGain.js",
       "types": "./dist/audioGain.d.ts"
@@ -175,6 +179,10 @@
       "import": "./dist/runtime/protocol.js",
       "types": "./dist/runtime/protocol.d.ts"
     },
+    "./runtime/clip-window": {
+      "import": "./dist/runtime/clipWindow.js",
+      "types": "./dist/runtime/clipWindow.d.ts"
+    },
     "./runtime/stacking-context": {
       "import": "./dist/runtime/stackingContext.js",
       "types": "./dist/runtime/stackingContext.d.ts"
@@ -286,9 +294,9 @@
     "bpm-detective": "^2.0.5",
     "linkedom": "^0.18.12",
     "postcss": "^8.5.8",
-    "@hyperframes/lint": "0.8.50",
-    "@hyperframes/studio-server": "0.8.50",
-    "@hyperframes/parsers": "0.8.50"
+    "@hyperframes/lint": "0.8.52",
+    "@hyperframes/parsers": "0.8.52",
+    "@hyperframes/studio-server": "0.8.52"
   },
   "devDependencies": {
     "@types/jsdom": "^28.0.0",