Files
hyperframes/packages/core/src/runtime/media.test.ts
T
Vance IngallsandClaude Opus 5.5 07a126d80f fix(core): preview audio fades play as ramps on the audio clock, so cuts no longer click (#6397)
* fix(core): preview audio fades play as ramps on the audio clock, so cuts no longer click

data-fade-in / data-fade-out were folded into one volume per 50 ms sync tick and applied as
a step (el.volume, or gain.value in the Web Audio transport), so a 20 ms fade never played
and each clip started and stopped at near full level: a click at every cut. The export
applies the fades (ffmpeg afade) and does not click.

The transport now books each clip's fades on a gain of its own when it schedules the
clip, for both decoded buffers and captured media elements: a linear ramp from where the
clip starts sounding up to its fade-in, and down to silence at its end. The sync tick hands
the transport the level without the fade (onElementVolume's new fifth argument, sent only
where a fade applies), so a booked fade is not applied twice. The plain el.volume fallback
keeps its stepped fade.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(core): one doc block on setElementVolume

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(core): keep the comment share where it was

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(core): booked fades hold through pre-roll, follow rate changes, skip unbounded ends

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: raise the producer unpacked budget to the measured size plus 1%

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 06:25:24 +00:00

2208 lines
84 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// fallow-ignore-file code-duplication
import { describe, it, expect, vi, afterEach } from "vitest";
import {
evictMediaSyncState,
hasMediaSyncStateForTest,
readElementPlaybackRate,
readElementPlaybackStart,
refreshRuntimeMediaCache,
resolveRuntimeMediaClipDuration,
syncRuntimeMedia as syncRuntimeMediaWithDuration,
} from "./media";
import type { RuntimeMediaClip } from "./media";
import { resolveNaturalMediaTimelineDuration } from "./playbackRate";
import { resetSeekDispatchState, waitForSeekCompletion } from "./adapters/seek-dispatch";
import { sourceTimeAt } from "../speedRamp";
import type { HfAutomationLane } from "../audioAutomation";
// Most cases predate the terminal rule and run with no composition end to hold at.
const syncRuntimeMedia = (
params: Omit<Parameters<typeof syncRuntimeMediaWithDuration>[0], "getCompositionDuration"> &
Partial<Pick<Parameters<typeof syncRuntimeMediaWithDuration>[0], "getCompositionDuration">>,
) => syncRuntimeMediaWithDuration({ getCompositionDuration: () => 0, ...params });
function createVideo(attrs: Record<string, string>): HTMLVideoElement {
const el = document.createElement("video");
for (const [key, value] of Object.entries(attrs)) {
el.setAttribute(key, value);
}
// jsdom doesn't compute media duration, so we stub it
Object.defineProperty(el, "duration", { value: NaN, writable: true, configurable: true });
document.body.appendChild(el);
return el;
}
function createAudio(attrs: Record<string, string>): HTMLAudioElement {
const el = document.createElement("audio");
for (const [key, value] of Object.entries(attrs)) {
el.setAttribute(key, value);
}
Object.defineProperty(el, "duration", { value: NaN, writable: true, configurable: true });
document.body.appendChild(el);
return el;
}
describe("readElementPlaybackRate", () => {
it("reads defaultPlaybackRate from element", () => {
const el = document.createElement("video");
Object.defineProperty(el, "defaultPlaybackRate", { value: 0.5, writable: true });
expect(readElementPlaybackRate(el)).toBe(0.5);
});
it("defaults to 1 when not set", () => {
const el = document.createElement("video");
expect(readElementPlaybackRate(el)).toBe(1);
});
it("clamps to [0.1, 10]", () => {
const el = document.createElement("video");
Object.defineProperty(el, "defaultPlaybackRate", { value: 0.01, writable: true });
expect(readElementPlaybackRate(el)).toBe(0.1);
Object.defineProperty(el, "defaultPlaybackRate", { value: 20, writable: true });
expect(readElementPlaybackRate(el)).toBe(10);
});
it("defaults to 1 for NaN/negative/zero", () => {
const el = document.createElement("video");
Object.defineProperty(el, "defaultPlaybackRate", { value: NaN, writable: true });
expect(readElementPlaybackRate(el)).toBe(1);
Object.defineProperty(el, "defaultPlaybackRate", { value: -1, writable: true });
expect(readElementPlaybackRate(el)).toBe(1);
Object.defineProperty(el, "defaultPlaybackRate", { value: 0, writable: true });
expect(readElementPlaybackRate(el)).toBe(1);
});
});
describe("readElementPlaybackStart fallback", () => {
it.each([
["", "1.5", 1.5],
[" ", "1.5", 1.5],
["later", "1.5", 1.5],
["-1", "1.5", 1.5],
[null, "-1", 0],
["0", "1.5", 0],
["2.25", "1.5", 2.25],
])("uses non-negative finite playback-start -> media-start -> 0", (playback, media, expected) => {
const el = document.createElement("audio");
if (playback !== null) el.setAttribute("data-playback-start", playback);
el.setAttribute("data-media-start", media);
expect(readElementPlaybackStart(el)).toBe(expected);
});
});
describe("refreshRuntimeMediaCache", () => {
afterEach(() => {
document.body.innerHTML = "";
});
it("finds video elements with data-start", () => {
createVideo({ "data-start": "0", "data-duration": "5" });
const result = refreshRuntimeMediaCache();
expect(result.timedMediaEls).toHaveLength(1);
expect(result.mediaClips).toHaveLength(1);
expect(result.videoClips).toHaveLength(1);
});
it("finds audio elements with data-start", () => {
createAudio({ "data-start": "2", "data-duration": "3" });
const result = refreshRuntimeMediaCache();
expect(result.timedMediaEls).toHaveLength(1);
expect(result.mediaClips).toHaveLength(1);
expect(result.videoClips).toHaveLength(0);
});
it("ignores media without data-start", () => {
document.body.appendChild(document.createElement("video"));
const result = refreshRuntimeMediaCache();
expect(result.timedMediaEls).toHaveLength(0);
});
it("calculates clip end from start + duration", () => {
createVideo({ "data-start": "2", "data-duration": "3" });
const result = refreshRuntimeMediaCache();
const clip = result.mediaClips[0];
expect(clip.start).toBe(2);
expect(clip.duration).toBe(3);
expect(clip.end).toBe(5);
});
it("uses media-start offset", () => {
createVideo({ "data-start": "0", "data-duration": "5", "data-media-start": "10" });
const result = refreshRuntimeMediaCache();
expect(result.mediaClips[0].mediaStart).toBe(10);
});
it("parses volume attribute", () => {
createVideo({ "data-start": "0", "data-duration": "5", "data-volume": "0.5" });
const result = refreshRuntimeMediaCache();
expect(result.mediaClips[0].volume).toBe(0.5);
});
it("handles missing volume gracefully", () => {
createVideo({ "data-start": "0", "data-duration": "5" });
const result = refreshRuntimeMediaCache();
expect(result.mediaClips[0].volume).toBeNull();
});
it("maxMediaEnd tracks highest clip end", () => {
createVideo({ "data-start": "0", "data-duration": "5" });
createVideo({ "data-start": "3", "data-duration": "10" });
const result = refreshRuntimeMediaCache();
expect(result.maxMediaEnd).toBe(13);
});
it("uses custom resolveStartSeconds", () => {
createVideo({ "data-start": "0", "data-duration": "5" });
const result = refreshRuntimeMediaCache({ resolveStartSeconds: () => 10 });
expect(result.mediaClips[0].start).toBe(10);
});
it("falls back to element.duration when data-duration missing", () => {
const el = createVideo({ "data-start": "0" });
Object.defineProperty(el, "duration", { value: 8, writable: true });
const result = refreshRuntimeMediaCache();
expect(result.mediaClips[0].duration).toBe(8);
});
it("reads defaultPlaybackRate from element", () => {
const el = createVideo({ "data-start": "0", "data-duration": "10" });
Object.defineProperty(el, "defaultPlaybackRate", { value: 0.5, writable: true });
const result = refreshRuntimeMediaCache();
expect(result.mediaClips[0].playbackRate).toBe(0.5);
});
it("defaults playback rate to 1", () => {
createVideo({ "data-start": "0", "data-duration": "5" });
const result = refreshRuntimeMediaCache();
expect(result.mediaClips[0].playbackRate).toBe(1);
});
it("clamps playback rate to [0.1, 10]", () => {
const el1 = createVideo({ "data-start": "0", "data-duration": "5" });
Object.defineProperty(el1, "defaultPlaybackRate", { value: 0.01, writable: true });
const r1 = refreshRuntimeMediaCache();
expect(r1.mediaClips[0].playbackRate).toBe(0.1);
document.body.innerHTML = "";
const el2 = createVideo({ "data-start": "0", "data-duration": "5" });
Object.defineProperty(el2, "defaultPlaybackRate", { value: 20, writable: true });
const r2 = refreshRuntimeMediaCache();
expect(r2.mediaClips[0].playbackRate).toBe(10);
});
it("adjusts fallback duration by playback rate", () => {
const el = createVideo({ "data-start": "0" });
Object.defineProperty(el, "defaultPlaybackRate", { value: 0.5, writable: true });
Object.defineProperty(el, "duration", { value: 10, writable: true });
const result = refreshRuntimeMediaCache();
// 10s source at 0.5x = 20s on timeline
expect(result.mediaClips[0].duration).toBe(20);
});
it("resolveDurationSeconds must account for playbackRate (regression: clip clipped early)", () => {
const el = createVideo({ "data-start": "0", "data-duration": "10" });
Object.defineProperty(el, "defaultPlaybackRate", { value: 0.5, writable: true });
Object.defineProperty(el, "duration", { value: 5, writable: true });
const result = refreshRuntimeMediaCache({
resolveDurationSeconds: (element) => {
const mediaStart =
Number.parseFloat(element.dataset.playbackStart ?? element.dataset.mediaStart ?? "0") ||
0;
const playbackRate = readElementPlaybackRate(element);
return Number.isFinite(element.duration) && element.duration > mediaStart
? Math.max(0, (element.duration - mediaStart) / playbackRate)
: null;
},
});
// 5s source at 0.5x = 10s effective; should NOT be capped to 5s
expect(result.mediaClips[0].duration).toBe(10);
expect(result.mediaClips[0].end).toBe(10);
});
it.each([10, 11])(
"preserves an authoritative zero duration at or past EOF (start=%s)",
(mediaStart) => {
const el = createVideo({ "data-start": "3", "data-media-start": String(mediaStart) });
Object.defineProperty(el, "duration", { value: 10, writable: true });
const result = refreshRuntimeMediaCache({
resolveDurationSeconds: (element) =>
resolveNaturalMediaTimelineDuration(element, element.duration),
});
expect(result.mediaClips[0].duration).toBe(0);
expect(result.mediaClips[0].end).toBe(3);
expect(result.maxMediaEnd).toBe(3);
},
);
it("distinguishes an authoritative zero duration from an unknown duration", () => {
createVideo({ "data-start": "3" });
const knownZero = refreshRuntimeMediaCache({ resolveDurationSeconds: () => 0 });
const unknown = refreshRuntimeMediaCache({ resolveDurationSeconds: () => null });
expect(knownZero.mediaClips[0]).toMatchObject({ duration: 0, end: 3 });
expect(unknown.mediaClips[0]).toMatchObject({ duration: Infinity, end: Infinity });
});
it("reads native loop attribute", () => {
createVideo({ "data-start": "0", "data-duration": "15", loop: "" });
const result = refreshRuntimeMediaCache();
expect(result.mediaClips[0].loop).toBe(true);
});
it("defaults loop to false", () => {
createVideo({ "data-start": "0", "data-duration": "5" });
const result = refreshRuntimeMediaCache();
expect(result.mediaClips[0].loop).toBe(false);
});
});
describe("resolveRuntimeMediaClipDuration", () => {
it("preserves an explicit video slot beyond the source", () => {
expect(
resolveRuntimeMediaClipDuration({
isVideo: true,
sourceDuration: 1,
hostRemaining: 8,
explicitDuration: 5,
}),
).toBe(5);
});
it("honors an explicit slot for a looping video instead of truncating it to one loop", () => {
// Loop wrapping happens later in syncRuntimeMedia. Duration resolution must
// preserve the authored window that the loop fills.
expect(
resolveRuntimeMediaClipDuration({
isVideo: true,
sourceDuration: 1,
hostRemaining: null,
explicitDuration: 10,
}),
).toBe(10);
});
it("keeps audio bounded by its playable source", () => {
expect(
resolveRuntimeMediaClipDuration({
isVideo: false,
sourceDuration: 1,
hostRemaining: 8,
explicitDuration: 5,
}),
).toBe(1);
});
it("uses natural duration for a video without an explicit slot", () => {
expect(
resolveRuntimeMediaClipDuration({
isVideo: true,
sourceDuration: 1,
hostRemaining: 8,
explicitDuration: null,
}),
).toBe(1);
});
it("uses natural source duration when a video has no slot or host window", () => {
expect(
resolveRuntimeMediaClipDuration({
isVideo: true,
sourceDuration: 1,
hostRemaining: null,
explicitDuration: null,
}),
).toBe(1);
});
it("preserves a known zero natural span instead of falling back to the host window", () => {
expect(
resolveRuntimeMediaClipDuration({
isVideo: true,
sourceDuration: 0,
hostRemaining: 8,
explicitDuration: null,
}),
).toBe(0);
});
});
describe("syncRuntimeMedia", () => {
function fakePlayedRanges(el: HTMLMediaElement, ranges: Array<[number, number]>): void {
Object.defineProperty(el, "played", {
configurable: true,
get: () => ({
length: ranges.length,
start: (i: number) => ranges[i][0],
end: (i: number) => ranges[i][1],
}),
});
}
function createMockClip(
overrides?: Partial<RuntimeMediaClip>,
mediaType: "audio" | "video" = "video",
): RuntimeMediaClip {
const el = document.createElement(mediaType);
document.body.appendChild(el);
Object.defineProperty(el, "paused", { value: true, writable: true, configurable: true });
el.play = vi.fn(() => Promise.resolve());
el.pause = vi.fn();
Object.defineProperty(el, "currentTime", { value: 0, writable: true, configurable: true });
Object.defineProperty(el, "playbackRate", { value: 1, writable: true, configurable: true });
// Default: audio has been playing — so drift-seek forward is allowed.
// Tests that exercise the "cold first play" guard call fakePlayedRanges(el, []).
fakePlayedRanges(el, [[0, 1]]);
// Mirror bindMediaMetadataListeners: pre-set el.volume to data-volume so the
// first-tick path in syncRuntimeMedia sees the correct baseline (not the browser
// default of 1) and GSAP-change detection works correctly from the first tick.
const dataVolume = overrides?.volume;
if (dataVolume != null && Number.isFinite(dataVolume)) {
el.volume = Math.max(0, Math.min(1, dataVolume));
}
return {
el,
start: 0,
mediaStart: 0,
duration: 10,
end: 10,
volume: null,
playbackRate: 1,
loop: false,
sourceDuration: null,
...overrides,
};
}
afterEach(() => {
document.body.innerHTML = "";
});
it("seeks a clip whose start is a float sum to its first frame, never before it", () => {
const clip = createMockClip({ start: 19.8 + 0.1, end: 25 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
clip.el.currentTime = 3;
syncRuntimeMedia({ clips: [clip], timeSeconds: 19.9, playing: false, playbackRate: 1 });
expect(clip.el.currentTime).toBe(0);
});
describe("speed ramp", () => {
it("seeks to the integrated source time and plays at the instantaneous rate", () => {
const rate = {
target: "rate",
points: [
{ t: 0, v: 1 },
{ t: 2, v: 3 },
],
};
const clip = createMockClip({ start: 1, end: 5, rate });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 3, playing: false, playbackRate: 1 });
expect(clip.el.currentTime).toBeCloseTo(3.641, 2);
syncRuntimeMedia({ clips: [clip], timeSeconds: 3, playing: true, playbackRate: 1 });
expect(clip.el.playbackRate).toBeCloseTo(3, 5);
});
});
describe("volume automation lane", () => {
const DUCK = JSON.stringify({
version: 1,
lanes: [
{
target: "volume",
points: [
{ t: 0, v: 0.8 },
{ t: 2, v: 0.8 },
{ t: 3, v: 0.1 },
{ t: 8, v: 0.1 },
],
},
],
});
/**
* The runtime rewrites the transport's gain every tick. Before the lane fed
* this path it was scheduled onto the AudioParam instead and erased within a
* frame, so the envelope was inaudible in preview while being correct in the
* render.
*/
function volumesAt(times: number[], automation?: string, volume = 0.55) {
const clip = createMockClip({ start: 0, end: 10, volume });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
if (automation) clip.el.setAttribute("data-automation", automation);
const seen: number[] = [];
for (const t of times) {
syncRuntimeMedia({
clips: [clip],
timeSeconds: t,
playing: true,
playbackRate: 1,
onElementVolume: (_el, v) => seen.push(v),
});
}
return seen;
}
it("drives the transport gain from the lane times data-volume", () => {
const [held, ducked] = volumesAt([1, 5], DUCK);
expect(held).toBeCloseTo(0.8 * 0.55, 5);
expect(ducked).toBeCloseTo(0.1 * 0.55, 5);
});
it("keeps automation author-only while user volume remains a separate layer", () => {
const clip = createMockClip({ start: 0, end: 10, volume: 0.55 });
clip.el.setAttribute("data-automation", DUCK);
const onElementVolume = vi.fn();
syncRuntimeMedia({
clips: [clip],
timeSeconds: 1,
playing: true,
playbackRate: 1,
userVolume: 0.5,
onElementVolume,
});
expect(onElementVolume).toHaveBeenLastCalledWith(
clip.el,
expect.closeTo(0.22, 5),
expect.closeTo(0.44, 5),
1,
);
});
it("leaves a routed clip's lane to the transport, sending data-volume as clip gain", () => {
const clip = createMockClip({ start: 0, end: 10, volume: 0.55 });
clip.el.setAttribute("data-automation", DUCK);
const onElementVolume = vi.fn();
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
onElementVolume,
isWebAudioRouted: () => true,
});
expect(onElementVolume).toHaveBeenLastCalledWith(clip.el, 1, 1, 0.55);
});
it("ramps between points across ticks", () => {
const [a, b, c] = volumesAt([2, 2.5, 3], DUCK);
expect(a).toBeCloseTo(0.8 * 0.55, 5);
expect(b).toBeGreaterThan(0.1 * 0.55);
expect(b).toBeLessThan(0.8 * 0.55);
expect(c).toBeCloseTo(0.1 * 0.55, 5);
});
it("falls back to data-volume when there is no lane", () => {
const [only] = volumesAt([5], undefined, 0.55);
expect(only).toBeCloseTo(0.55, 5);
});
it("applies data-fade-in / data-fade-out on top of data-volume, anchored to the clip edges", () => {
const at = (t: number) => {
const clip = createMockClip({ start: 2, end: 12, duration: 10, volume: 0.8 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
clip.el.setAttribute("data-fade-in", "2");
clip.el.setAttribute("data-fade-out", "1");
clip.fades = { fadeIn: 2, fadeOut: 1 };
let authored = -1;
syncRuntimeMedia({
clips: [clip],
timeSeconds: t,
playing: true,
playbackRate: 1,
onElementVolume: (_el, _effective, authorVolume) => {
authored = authorVolume;
},
});
return authored;
};
expect(at(2.5)).toBeCloseTo(0.2, 5); // a quarter into the 2 s fade-in
expect(at(3)).toBeCloseTo(0.4, 5); // halfway through the fade-in
expect(at(6)).toBeCloseTo(0.8, 5); // body of the clip: data-volume alone
expect(at(11.5)).toBeCloseTo(0.4, 5); // halfway through the 1 s fade-out
expect(at(11.9)).toBeCloseTo(0.08, 5); // almost at the clip's end
});
it("also hands a transport the level without the fade, so one that books fades on its own clock does not fade twice", () => {
const clip = createMockClip({ start: 2, end: 12, duration: 10, volume: 0.8 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
clip.fades = { fadeIn: 2, fadeOut: 1 };
const onElementVolume = vi.fn();
syncRuntimeMedia({
clips: [clip],
timeSeconds: 3,
playing: true,
playbackRate: 1,
onElementVolume,
});
const [, , authorVolume, , unfadedVolume] = onElementVolume.mock.lastCall ?? [];
expect(authorVolume).toBeCloseTo(0.4, 5); // halfway through the fade-in, as the tick steps it
expect(unfadedVolume).toBeCloseTo(0.8, 5);
});
it("never writes NaN or a negative volume for 0, negative, NaN, or longer-than-clip fades", () => {
const cases: Array<{ fadeIn: number; fadeOut: number }> = [
{ fadeIn: 0, fadeOut: 0 },
{ fadeIn: -2, fadeOut: -1 },
{ fadeIn: Number.NaN, fadeOut: Number.NaN },
{ fadeIn: 40, fadeOut: 40 },
];
for (const fades of cases) {
const clip = createMockClip({ start: 0, end: 10, duration: 10, volume: 0.5, fades });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
for (const t of [0, 5, 10, 12]) {
syncRuntimeMedia({
clips: [clip],
timeSeconds: t,
playing: true,
playbackRate: 1,
});
expect(Number.isFinite(clip.el.volume)).toBe(true);
expect(clip.el.volume).toBeGreaterThanOrEqual(0);
expect(clip.el.volume).toBeLessThanOrEqual(1);
}
}
});
it("sends boosted author gain to Web Audio while keeping the native element legal", () => {
const clip = createMockClip({ start: 0, end: 10, volume: 3.98 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
let transportGain = -1;
syncRuntimeMedia({
clips: [clip],
timeSeconds: 1,
playing: true,
playbackRate: 1,
// Third arg is the authored gain, which is the one the transport wants;
// the second is the element's, which the spec pins to [0,1].
onElementVolume: (_el, _effectiveVolume, authorVolume) => {
transportGain = authorVolume;
},
});
expect(transportGain).toBeCloseTo(3.98, 5);
expect(clip.el.volume).toBe(1);
});
/**
* The render bakes the lane at CLIP-LOCAL time: prepareAudioTrack already
* cut the wav with `-ss mediaStart`, so its t=0 is the clip's start, and
* normaliseEnvelope subtracts trackStart. Preview used to sample at MEDIA
* time — mediaStart included, scaled by playbackRate, wrapped on a loop — so
* the same envelope played somewhere else than it rendered.
*/
it("samples the lane at clip-local time, the way the render bakes it", () => {
const trimmed = (t: number) => {
const clip = createMockClip({ start: 0, end: 10, volume: 0.55, mediaStart: 30 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
clip.el.setAttribute("data-automation", DUCK);
let seen = -1;
syncRuntimeMedia({
clips: [clip],
timeSeconds: t,
playing: true,
playbackRate: 1,
onElementVolume: (_el, v) => {
seen = v;
},
});
return seen;
};
// `data-media-start="30"` on a clip whose lane holds 0.8 until t=2 then
// ducks to 0.1 by t=3. At media time the playhead is already 30 s past the
// last point, so preview held 0.1 from the first frame and never ducked.
expect(trimmed(1)).toBeCloseTo(0.8 * 0.55, 5);
expect(trimmed(5)).toBeCloseTo(0.1 * 0.55, 5);
});
it("supersedes keyframes probed from the timeline", () => {
// Both present: the lane is the explicit one, and `lint` warns about it.
const clip = createMockClip({ start: 0, end: 10, volume: 0.55 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
clip.el.setAttribute("data-automation", DUCK);
clip.volumeKeyframes = [
{ time: 0, volume: 1 },
{ time: 10, volume: 1 },
];
let seen = -1;
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
onElementVolume: (_el, v) => {
seen = v;
},
});
expect(seen).toBeCloseTo(0.1 * 0.55, 5);
});
});
it("hands the transport an above-unity author gain, uncapped", () => {
// The preview terminus. `el.volume` is spec-bound to [0,1] and always will
// be, so the boost can only reach the ear through the Web Audio gain node —
// which means the author gain handed to the transport must NOT be capped on
// the way out, even though the native write beside it is.
const clip = createMockClip({ start: 0, end: 10, volume: 1.949845 });
const onElementVolume = vi.fn();
syncRuntimeMedia({
clips: [clip],
timeSeconds: 1,
playing: false,
playbackRate: 1,
onElementVolume,
});
const [, , authorVolume] = onElementVolume.mock.calls.at(-1) as [unknown, number, number];
expect(authorVolume).toBeCloseTo(1.949845, 6);
expect(clip.el.volume).toBe(1);
});
it("plays active clip when playing and buffered", () => {
const clip = createMockClip({ start: 0, end: 10 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
expect(clip.el.play).toHaveBeenCalled();
});
it("uses a half-open interval around a clip's end boundary", () => {
const clip = createMockClip({ start: 0, end: 2.5 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 2.5 - 1e-9,
playing: true,
playbackRate: 1,
});
expect(clip.el.play).toHaveBeenCalledTimes(1);
syncRuntimeMedia({ clips: [clip], timeSeconds: 2.5, playing: true, playbackRate: 1 });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 2.5 + 1e-9,
playing: true,
playbackRate: 1,
});
expect(clip.el.play).toHaveBeenCalledTimes(1);
});
it("plays synchronously even when media is unbuffered (preserves user gesture)", () => {
// Calling play() synchronously inside the user-gesture call chain lets the
// browser queue playback until data buffers, while consuming the transient
// user activation. Deferring to an async canplay handler would let the
// activation expire and the autoplay policy silently reject — producing
// the "silent first play, audio only after second click" bug.
const clip = createMockClip({ start: 0, end: 10 });
Object.defineProperty(clip.el, "readyState", { value: 0, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
expect(clip.el.play).toHaveBeenCalled();
});
describe("data-hidden silences preview volume", () => {
const hiddenClip = () => {
const clip = createMockClip({ start: 0, end: 10, volume: 0.8 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
const hiddenAncestor = document.createElement("div");
hiddenAncestor.setAttribute("data-hidden", "");
document.body.appendChild(hiddenAncestor);
hiddenAncestor.appendChild(clip.el);
return clip;
};
const volumeSeen = (clip: ReturnType<typeof hiddenClip>) => {
let seen = -1;
syncRuntimeMedia({
clips: [clip],
timeSeconds: 1,
playing: true,
playbackRate: 1,
onElementVolume: (_el, v) => {
seen = v;
},
});
return seen;
};
it("zeroes effective volume for a clip under a data-hidden ancestor", () => {
expect(volumeSeen(hiddenClip())).toBe(0);
});
// A visible clip is the control: the zero above has to come from the
// ancestor, not from the fixture reading 0 for some other reason.
it("leaves a visible clip at its authored volume", () => {
const clip = createMockClip({ start: 0, end: 10, volume: 0.8 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
document.body.appendChild(clip.el);
expect(volumeSeen(clip)).toBe(0.8);
});
it("does not touch el.muted when silencing a hidden clip (RULES trap: transport owns el.muted)", () => {
const clip = hiddenClip();
clip.el.muted = false;
syncRuntimeMedia({
clips: [clip],
timeSeconds: 1,
playing: true,
playbackRate: 1,
});
expect(clip.el.muted).toBe(false);
});
});
describe("video seek completion", () => {
afterEach(() => resetSeekDispatchState());
function seekColdVideo(): RuntimeMediaClip {
const clip = createMockClip({ start: 7.1, end: 18.24 });
Object.defineProperty(clip.el, "seeking", { value: true, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 12, playing: false, playbackRate: 1 });
return clip;
}
async function barrierSettled(barrier: Promise<void>): Promise<boolean> {
let settled = false;
void barrier.then(() => (settled = true));
await new Promise((resolve) => setTimeout(resolve, 0));
return settled;
}
it("holds the seek-completion barrier until a seeking video lands its frame", async () => {
const clip = seekColdVideo();
expect(clip.el.currentTime).toBeCloseTo(4.9);
const barrier = waitForSeekCompletion();
expect(await barrierSettled(barrier)).toBe(false);
clip.el.dispatchEvent(new Event("seeked"));
expect(await barrierSettled(barrier)).toBe(true);
});
it("does not hold a geometry read for a seeking video's frame", async () => {
seekColdVideo();
expect(await barrierSettled(waitForSeekCompletion({ videoFrames: false }))).toBe(true);
expect(await barrierSettled(waitForSeekCompletion())).toBe(false);
});
function seekLoadingVideo(): RuntimeMediaClip {
const clip = createMockClip({ start: 7.1, end: 18.24 });
Object.defineProperty(clip.el, "readyState", { value: 0, configurable: true });
Object.defineProperty(clip.el, "networkState", { value: 2, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 12, playing: false, playbackRate: 1 });
return clip;
}
it("holds the barrier until a video still loading its first data has it", async () => {
const clip = seekLoadingVideo();
expect(clip.el.seeking).toBe(false);
const barrier = waitForSeekCompletion();
expect(await barrierSettled(barrier)).toBe(false);
Object.defineProperty(clip.el, "seeking", { value: true, configurable: true });
clip.el.dispatchEvent(new Event("loadeddata"));
expect(await barrierSettled(barrier)).toBe(false);
clip.el.dispatchEvent(new Event("seeked"));
expect(await barrierSettled(barrier)).toBe(true);
});
it("holds a loading video that is already parked on the frame's time", async () => {
const clip = createMockClip({ start: 7.1, end: 18.24 });
Object.defineProperty(clip.el, "readyState", { value: 0, configurable: true });
Object.defineProperty(clip.el, "networkState", { value: 2, configurable: true });
clip.el.currentTime = 4.9;
syncRuntimeMedia({ clips: [clip], timeSeconds: 12, playing: false, playbackRate: 1 });
expect(await barrierSettled(waitForSeekCompletion())).toBe(false);
});
it("does not hold a video that is not fetching", async () => {
const clip = createMockClip({ start: 7.1, end: 18.24 });
Object.defineProperty(clip.el, "readyState", { value: 0, configurable: true });
Object.defineProperty(clip.el, "networkState", { value: 1, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 12, playing: false, playbackRate: 1 });
expect(await barrierSettled(waitForSeekCompletion())).toBe(true);
});
it("releases a loading video when its <source> child fails", async () => {
const clip = seekLoadingVideo();
const source = document.createElement("source");
clip.el.appendChild(source);
const barrier = waitForSeekCompletion();
source.dispatchEvent(new Event("error"));
expect(await barrierSettled(barrier)).toBe(true);
});
it("gives a later seek its own full wait", async () => {
vi.useFakeTimers();
try {
const clip = seekLoadingVideo();
await vi.advanceTimersByTimeAsync(4000);
syncRuntimeMedia({ clips: [clip], timeSeconds: 13, playing: false, playbackRate: 1 });
let settled = false;
void waitForSeekCompletion().then(() => (settled = true));
await vi.advanceTimersByTimeAsync(4999);
expect(settled).toBe(false);
await vi.advanceTimersByTimeAsync(1);
expect(settled).toBe(true);
} finally {
vi.useRealTimers();
}
});
it("does not hold a loading video while playing without a seek", async () => {
const clip = createMockClip({ start: 7.1, end: 18.24 });
Object.defineProperty(clip.el, "readyState", { value: 0, configurable: true });
Object.defineProperty(clip.el, "networkState", { value: 2, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 12, playing: true, playbackRate: 1 });
resetSeekDispatchState();
syncRuntimeMedia({ clips: [clip], timeSeconds: 12, playing: true, playbackRate: 1 });
expect(await barrierSettled(waitForSeekCompletion())).toBe(true);
});
it("releases a video that never loads after the cap", async () => {
vi.useFakeTimers();
try {
seekLoadingVideo();
let settled = false;
void waitForSeekCompletion().then(() => (settled = true));
await vi.advanceTimersByTimeAsync(4999);
expect(settled).toBe(false);
await vi.advanceTimersByTimeAsync(1);
expect(settled).toBe(true);
} finally {
vi.useRealTimers();
}
});
it("keeps holding a loading video through a suspend between range requests", async () => {
const clip = seekLoadingVideo();
const barrier = waitForSeekCompletion();
clip.el.dispatchEvent(new Event("suspend"));
expect(await barrierSettled(barrier)).toBe(false);
Object.defineProperty(clip.el, "seeking", { value: true, configurable: true });
clip.el.dispatchEvent(new Event("loadedmetadata"));
clip.el.dispatchEvent(new Event("seeking"));
expect(await barrierSettled(barrier)).toBe(false);
Object.defineProperty(clip.el, "seeking", { value: false, configurable: true });
clip.el.dispatchEvent(new Event("seeked"));
expect(await barrierSettled(barrier)).toBe(true);
});
it("does not hold a render for a video still loading", async () => {
const renderWindow = window as { __HF_EXPORT_RENDER_SEEK_CONFIG?: unknown };
renderWindow.__HF_EXPORT_RENDER_SEEK_CONFIG = { mode: "seek" };
try {
seekLoadingVideo();
expect(await barrierSettled(waitForSeekCompletion())).toBe(true);
} finally {
delete renderWindow.__HF_EXPORT_RENDER_SEEK_CONFIG;
}
});
it.each(["error", "emptied", "abort"])(
"releases the barrier when the seek ends in %s",
async (type) => {
const clip = seekColdVideo();
const barrier = waitForSeekCompletion();
clip.el.dispatchEvent(new Event(type));
expect(await barrierSettled(barrier)).toBe(true);
},
);
});
describe("play() storm guard (unplayable elements)", () => {
it("does not play() an element with a media error", () => {
const clip = createMockClip({ start: 0, end: 10 });
Object.defineProperty(clip.el, "error", { value: { code: 4 }, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
expect(clip.el.play).not.toHaveBeenCalled();
});
it("starts an audio clip due within the next tick, from its first sample", () => {
const clip = createMockClip({ start: 5, end: 6, mediaStart: 2 }, "audio");
syncRuntimeMedia({
clips: [clip],
timeSeconds: 4.99,
playing: true,
playbackRate: 1,
cueAheadSeconds: 0.017,
});
expect(clip.el.play).toHaveBeenCalledTimes(1);
expect(clip.el.currentTime).toBe(2);
});
it("does not start an audio clip further away than the next tick", () => {
const clip = createMockClip({ start: 5, end: 6 }, "audio");
syncRuntimeMedia({
clips: [clip],
timeSeconds: 4.95,
playing: true,
playbackRate: 1,
cueAheadSeconds: 0.017,
});
expect(clip.el.play).not.toHaveBeenCalled();
});
it("does not start a sped-up clip so early that its window opens it past strict sync", () => {
const clip = createMockClip({ start: 5, end: 6, rate: 3 }, "audio");
syncRuntimeMedia({
clips: [clip],
timeSeconds: 4.98,
playing: true,
playbackRate: 1,
cueAheadSeconds: 0.034,
});
expect(clip.el.play).not.toHaveBeenCalled();
});
it("judges a head-cut clip's cue-ahead by its rate at the cut, not at its own start", () => {
// The clip's own t=0 is 2 and an in-point cuts it to start at 5, where the ramp has reached 3x.
const rate: HfAutomationLane = {
target: "rate",
points: [
{ t: 0, v: 1 },
{ t: 3, v: 3 },
],
};
const clip = createMockClip({ start: 5, origin: 2, end: 6, rate }, "audio");
syncRuntimeMedia({
clips: [clip],
timeSeconds: 4.98,
playing: true,
playbackRate: 1,
cueAheadSeconds: 0.034,
});
expect(clip.el.play).not.toHaveBeenCalled();
});
it("keeps a clip it started early playing when the next tick is shorter", () => {
const clip = createMockClip({ start: 5, end: 6 }, "audio");
syncRuntimeMedia({
clips: [clip],
timeSeconds: 4.97,
playing: true,
playbackRate: 1,
cueAheadSeconds: 0.034,
});
Object.defineProperty(clip.el, "paused", {
value: false,
writable: true,
configurable: true,
});
syncRuntimeMedia({
clips: [clip],
timeSeconds: 4.98,
playing: true,
playbackRate: 1,
cueAheadSeconds: 0.01,
});
expect(clip.el.pause).not.toHaveBeenCalled();
});
it("does not start a clip again once the playhead is past it", () => {
const clip = createMockClip({ start: 5, end: 6 }, "audio");
syncRuntimeMedia({
clips: [clip],
timeSeconds: 6.01,
playing: true,
playbackRate: 1,
cueAheadSeconds: 0.017,
});
expect(clip.el.play).not.toHaveBeenCalled();
});
it("starts nothing early while paused, and never a video", () => {
const audio = createMockClip({ start: 5, end: 6 }, "audio");
syncRuntimeMedia({
clips: [audio],
timeSeconds: 4.99,
playing: false,
playbackRate: 1,
cueAheadSeconds: 0.017,
});
const video = createMockClip({ start: 5, end: 6 }, "video");
syncRuntimeMedia({
clips: [video],
timeSeconds: 4.99,
playing: true,
playbackRate: 1,
cueAheadSeconds: 0.017,
});
expect(audio.el.play).not.toHaveBeenCalled();
expect(video.el.play).not.toHaveBeenCalled();
});
it("does not play() an element whose networkState is NO_SOURCE", () => {
const clip = createMockClip({ start: 0, end: 10 });
Object.defineProperty(clip.el, "networkState", { value: 3, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
expect(clip.el.play).not.toHaveBeenCalled();
});
it("does not re-play() across ticks while the element stays errored", () => {
const clip = createMockClip({ start: 0, end: 10 });
Object.defineProperty(clip.el, "error", { value: { code: 4 }, configurable: true });
for (const t of [5, 5.1, 5.2, 5.3]) {
syncRuntimeMedia({ clips: [clip], timeSeconds: t, playing: true, playbackRate: 1 });
}
expect(clip.el.play).not.toHaveBeenCalled();
});
it("plays again once the element recovers (error clears)", () => {
const clip = createMockClip({ start: 0, end: 10 });
Object.defineProperty(clip.el, "error", { value: { code: 4 }, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
expect(clip.el.play).not.toHaveBeenCalled();
Object.defineProperty(clip.el, "error", { value: null, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5.1, playing: true, playbackRate: 1 });
expect(clip.el.play).toHaveBeenCalled();
});
});
it("forces preload=auto on every active element, not just during play", () => {
// Streaming formats (MP3) may arrive with preload="metadata", which only
// buffers the first few seconds. Setting preload="auto" on every active
// tick catches elements whose preload was overridden after init.ts set it
// — and ensures it happens even when paused (e.g. during a seek).
const clip = createMockClip({ start: 0, end: 10 });
Object.defineProperty(clip.el, "preload", { value: "metadata", writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
expect(clip.el.preload).toBe("auto");
});
it("leaves a video the render replaces with extracted frames at preload none", () => {
const clip = createMockClip({ start: 0, end: 10 });
clip.el.id = "cut";
Object.defineProperty(clip.el, "preload", { value: "none", writable: true });
(
window as Window & { __HF_RENDER_FRAME_VIDEO_IDS?: readonly string[] }
).__HF_RENDER_FRAME_VIDEO_IDS = ["cut"];
try {
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
expect(clip.el.preload).toBe("none");
} finally {
delete (window as Window & { __HF_RENDER_FRAME_VIDEO_IDS?: readonly string[] })
.__HF_RENDER_FRAME_VIDEO_IDS;
}
});
it("does not re-fire play() while a previous play() is in flight", () => {
// Without a play-request dedup, the 50ms runtime poll would fire 20–40
// spurious play() calls per element during the 1–2s initial buffer, each
// with a catch() that would swallow any real AbortError / NotAllowedError
// the developer needs to see.
const clip = createMockClip({ start: 0, end: 10 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5.02, playing: true, playbackRate: 1 });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5.04, playing: true, playbackRate: 1 });
expect(clip.el.play).toHaveBeenCalledTimes(1);
});
it("re-issues play() after a hard seek clears the in-flight guard", () => {
// A scrub during playback triggers a hard seek (offset jump > 0.5s).
// The fix clears the playRequested guard so the very next sync tick can
// re-issue play() instead of waiting 50-150ms for the guard to clear
// naturally — closing the audible desync gap on timeline scrub.
const clip = createMockClip({ start: 0, end: 20, mediaStart: 0 });
Object.defineProperty(clip.el, "currentTime", { value: 2, writable: true });
// Steady-state playback at t=2
syncRuntimeMedia({ clips: [clip], timeSeconds: 2, playing: true, playbackRate: 1 });
expect(clip.el.play).toHaveBeenCalledTimes(1);
// Scrub to t=15 — hard seek fires, guard should be cleared
syncRuntimeMedia({ clips: [clip], timeSeconds: 15, playing: true, playbackRate: 1 });
// Next tick: play() should fire again (guard was cleared by the seek)
syncRuntimeMedia({ clips: [clip], timeSeconds: 15.02, playing: true, playbackRate: 1 });
expect(clip.el.play).toHaveBeenCalledTimes(2);
});
it("calls load() once when a seek fails past the buffered range (MP3 partial buffer)", () => {
// Streaming MP3 with preload="metadata" only buffers the first ~15s.
// When the user seeks to 20s, el.currentTime = 20 silently fails —
// currentTime stays at 0. The fix detects this and calls load() once
// to trigger a full network fetch.
const clip = createMockClip({ start: 0, end: 30, mediaStart: 0 });
// Simulate: currentTime is writable but the setter is intercepted
// to stay at 0 (simulating failed seek past buffer).
let internalTime = 0;
Object.defineProperty(clip.el, "currentTime", {
get: () => internalTime,
set: () => {
// Seek silently fails — stays at 0 (MP3 past buffer)
},
configurable: true,
});
clip.el.load = vi.fn();
// First tick at t=20 — hard seek fires, fails, should call load()
syncRuntimeMedia({ clips: [clip], timeSeconds: 20, playing: true, playbackRate: 1 });
expect(clip.el.load).toHaveBeenCalledTimes(1);
// Second tick — load() should NOT be called again (one-shot guard)
syncRuntimeMedia({ clips: [clip], timeSeconds: 20.05, playing: true, playbackRate: 1 });
expect(clip.el.load).toHaveBeenCalledTimes(1);
});
it("does not call load() when the seek succeeds", () => {
const clip = createMockClip({ start: 0, end: 30, mediaStart: 0 });
Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
clip.el.load = vi.fn();
// Seek to 20 — succeeds (currentTime updates)
syncRuntimeMedia({ clips: [clip], timeSeconds: 20, playing: true, playbackRate: 1 });
expect(clip.el.currentTime).toBe(20);
expect(clip.el.load).not.toHaveBeenCalled();
});
it("clears the load-retry guard when clip deactivates and reactivates", () => {
const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
let internalTime = 0;
Object.defineProperty(clip.el, "currentTime", {
get: () => internalTime,
set: () => {},
configurable: true,
});
clip.el.load = vi.fn();
// First activation — seek fails, load() called
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
expect(clip.el.load).toHaveBeenCalledTimes(1);
// Deactivate
syncRuntimeMedia({ clips: [clip], timeSeconds: 11, playing: true, playbackRate: 1 });
// Reactivate — guard was cleared, so load() can fire again
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
expect(clip.el.load).toHaveBeenCalledTimes(2);
});
it("pauses active clip when not playing", () => {
const clip = createMockClip({ start: 0, end: 10 });
Object.defineProperty(clip.el, "paused", { value: false, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
expect(clip.el.pause).toHaveBeenCalled();
});
it("pauses inactive clip", () => {
const clip = createMockClip({ start: 5, end: 10 });
Object.defineProperty(clip.el, "paused", { value: false, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 2, playing: true, playbackRate: 1 });
expect(clip.el.pause).toHaveBeenCalled();
});
it("does not restart a non-loop clip that has naturally ended before the clip's end time", () => {
// Reproduces: bg-music WAV is 60s but data-duration="68.6" (composition duration).
// At t=62 the file has ended; without this guard the runtime calls el.play() every
// rAF tick, resetting currentTime to 0 and causing audible stutter for 8.6s.
const clip = createMockClip({ start: 0, end: 68.6, loop: false });
Object.defineProperty(clip.el, "paused", { value: true, writable: true });
Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 62, playing: true, playbackRate: 1 });
expect(clip.el.play).not.toHaveBeenCalled();
});
it("seeks a non-looping video to its final frame when entering an authored hold tail", () => {
const clip = createMockClip({ start: 0, end: 5, duration: 5, sourceDuration: 0.25 });
syncRuntimeMedia({ clips: [clip], timeSeconds: 4, playing: true, playbackRate: 1 });
expect(clip.el.currentTime).toBe(0.25);
expect(clip.el.play).not.toHaveBeenCalled();
});
it("holds a video that runs to the composition end on its last frame at the terminal time", () => {
const clip = createMockClip({ start: 2.5, end: 5, duration: 2.5, sourceDuration: 10 });
const seek = {
clips: [clip],
playing: false,
playbackRate: 1,
getCompositionDuration: () => 5,
};
syncRuntimeMedia({ ...seek, timeSeconds: 5 });
expect(clip.el.currentTime).toBe(2.5);
expect(clip.el.play).not.toHaveBeenCalled();
});
it("holds a video ending on a float sum at the composition end on its last frame", () => {
const clip = createMockClip({
start: 19.8,
end: 19.8 + 6.4,
duration: 6.4,
sourceDuration: 10,
});
syncRuntimeMedia({
clips: [clip],
timeSeconds: 26.2,
playing: false,
playbackRate: 1,
getCompositionDuration: () => 26.2,
});
expect(clip.el.currentTime).toBeCloseTo(6.4, 9);
});
it("holds a speed-ramped video that runs to the composition end at the source time of its own end", () => {
const lane: HfAutomationLane = {
target: "rate",
points: [
{ t: 0, v: 1 },
{ t: 5, v: 2 },
],
};
const clip = createMockClip({ start: 0, end: 5, duration: 5, sourceDuration: 100, rate: lane });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 6,
playing: false,
playbackRate: 1,
getCompositionDuration: () => 5,
});
expect(clip.el.currentTime).toBeCloseTo(sourceTimeAt(lane, 5), 5);
expect(clip.el.currentTime).toBeLessThan(sourceTimeAt(lane, 6));
expect(clip.el.play).not.toHaveBeenCalled();
});
it("clamps a terminal video hold to a shorter source tail", () => {
const clip = createMockClip({ start: 0, end: 5, duration: 5, sourceDuration: 0.25 });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
getCompositionDuration: () => 5,
});
expect(clip.el.currentTime).toBe(0.25);
expect(clip.el.play).not.toHaveBeenCalled();
});
it("does not hold a video that ended before the composition did", () => {
const clip = createMockClip({ start: 0, end: 2.5, duration: 2.5, sourceDuration: 10 });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: false,
playbackRate: 1,
getCompositionDuration: () => 5,
});
expect(clip.el.currentTime).toBe(0);
});
it("seeks an ended video backward into its playable source", () => {
const clip = createMockClip({ start: 0, end: 5, duration: 5, sourceDuration: 1 });
Object.defineProperty(clip.el, "currentTime", { value: 1, writable: true, configurable: true });
Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 0.9, playing: true, playbackRate: 1 });
expect(clip.el.currentTime).toBe(0.9);
expect(clip.el.play).toHaveBeenCalledTimes(1);
});
it("seeks an ended audio clip backward into its playable source", () => {
const clip = createMockClip(
{ start: 3.12, end: 3.67, duration: 0.55, sourceDuration: 0.55 },
"audio",
);
Object.defineProperty(clip.el, "currentTime", {
value: 0.55,
writable: true,
configurable: true,
});
Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 3.12, playing: true, playbackRate: 1 });
expect(clip.el.currentTime).toBe(0);
expect(clip.el.play).toHaveBeenCalledTimes(1);
});
it("does not restart ended audio past its source duration", () => {
const clip = createMockClip(
{ start: 3.12, end: 4.12, duration: 1, sourceDuration: 0.55 },
"audio",
);
Object.defineProperty(clip.el, "currentTime", {
value: 0.55,
writable: true,
configurable: true,
});
Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 3.8, playing: true, playbackRate: 1 });
expect(clip.el.currentTime).toBe(0.55);
expect(clip.el.play).not.toHaveBeenCalled();
});
it("does not replay an audio tail when native EOF leads the runtime clock", () => {
const clip = createMockClip(
{ start: 3.12, end: 3.67, duration: 0.55, sourceDuration: 0.55 },
"audio",
);
Object.defineProperty(clip.el, "paused", { value: false, writable: true });
Object.defineProperty(clip.el, "currentTime", { value: 0.53, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 3.65, playing: true, playbackRate: 1 });
clip.el.currentTime = 0.55;
Object.defineProperty(clip.el, "paused", { value: true, writable: true });
Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 3.66,
playing: true,
playbackRate: 1,
forceSync: true,
});
syncRuntimeMedia({
clips: [clip],
timeSeconds: 3.665,
playing: true,
playbackRate: 1,
forceSync: true,
});
expect(clip.el.currentTime).toBe(0.55);
expect(clip.el.play).not.toHaveBeenCalled();
});
it("rewinds ended audio after a backward seek within the active clip", () => {
const clip = createMockClip(
{ start: 3.12, end: 3.67, duration: 0.55, sourceDuration: 0.55 },
"audio",
);
Object.defineProperty(clip.el, "currentTime", { value: 0.5, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 3.62, playing: true, playbackRate: 1 });
vi.mocked(clip.el.play).mockClear();
clip.el.currentTime = 0.55;
Object.defineProperty(clip.el, "paused", { value: true, writable: true });
Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 3.12,
playing: true,
playbackRate: 1,
forceSync: true,
});
expect(clip.el.currentTime).toBe(0);
expect(clip.el.play).toHaveBeenCalledTimes(1);
});
it("does restart a loop clip that has naturally ended while still within its active window", () => {
const clip = createMockClip({ start: 0, end: 68.6, loop: true, sourceDuration: 60 });
Object.defineProperty(clip.el, "paused", { value: true, writable: true });
Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 62, playing: true, playbackRate: 1 });
expect(clip.el.play).toHaveBeenCalled();
});
it("resumes a previously-ended non-loop clip after a backward seek resets el.ended", () => {
// el.ended resets to false when the browser processes a seek (per WHATWG spec).
// This test pins the contract: silent at t=62 (ended), playable again at t=30 (seeked back).
const clip = createMockClip({ start: 0, end: 68.6, loop: false });
Object.defineProperty(clip.el, "paused", { value: true, writable: true });
Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 62, playing: true, playbackRate: 1 });
expect(clip.el.play).not.toHaveBeenCalled();
// Simulate backward seek: browser resets ended to false before committing new currentTime
Object.defineProperty(clip.el, "ended", { value: false, writable: true, configurable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 30, playing: true, playbackRate: 1 });
expect(clip.el.play).toHaveBeenCalledTimes(1);
});
it("sets volume when clip has volume", () => {
const clip = createMockClip({ start: 0, end: 10, volume: 0.7 });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
expect(clip.el.volume).toBe(0.7);
});
it("applies userVolume as a multiplier on clip volume", () => {
const clip = createMockClip({ start: 0, end: 10, volume: 0.8 });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: false,
playbackRate: 1,
userVolume: 0.5,
});
expect(clip.el.volume).toBeCloseTo(0.4);
});
it("applies userVolume to clips without explicit volume (default 1)", () => {
const clip = createMockClip({ start: 0, end: 10 });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: false,
playbackRate: 1,
userVolume: 0.3,
});
expect(clip.el.volume).toBeCloseTo(0.3);
});
it("preserves authored volume changes made between sync ticks", () => {
const clip = createMockClip({ start: 0, end: 10, volume: 0 });
syncRuntimeMedia({ clips: [clip], timeSeconds: 0, playing: false, playbackRate: 1 });
expect(clip.el.volume).toBe(0);
clip.el.volume = 0.5;
syncRuntimeMedia({ clips: [clip], timeSeconds: 0.5, playing: false, playbackRate: 1 });
expect(clip.el.volume).toBe(0.5);
});
it("writes volume and muted only when they change, not on every tick", () => {
const clip = createMockClip({ start: 0, end: 10, volume: 0.7 });
const writes = { volume: 0, muted: 0 };
for (const prop of ["volume", "muted"] as const) {
const native = Object.getOwnPropertyDescriptor(HTMLMediaElement.prototype, prop)!;
Object.defineProperty(clip.el, prop, {
configurable: true,
get() {
return native.get!.call(this);
},
set(value) {
writes[prop]++;
native.set!.call(this, value);
},
});
}
for (const timeSeconds of [1, 1.04, 1.08, 1.12]) {
syncRuntimeMedia({
clips: [clip],
timeSeconds,
playing: false,
playbackRate: 1,
outputMuted: true,
});
}
expect(clip.el.volume).toBe(0.7);
expect(clip.el.muted).toBe(true);
expect(writes).toEqual({ volume: 0, muted: 1 });
clip.el.muted = false;
syncRuntimeMedia({
clips: [clip],
timeSeconds: 1.16,
playing: false,
playbackRate: 1,
outputMuted: true,
});
expect(clip.el.muted).toBe(true);
});
it("reports effective and author-only volume to external audio transports", () => {
const clip = createMockClip({ start: 0, end: 10, volume: 0 });
const onElementVolume = vi.fn();
syncRuntimeMedia({
clips: [clip],
timeSeconds: 0,
playing: false,
playbackRate: 1,
onElementVolume,
});
clip.el.volume = 0.75;
syncRuntimeMedia({
clips: [clip],
timeSeconds: 1,
playing: false,
playbackRate: 1,
userVolume: 0.5,
onElementVolume,
});
expect(clip.el.volume).toBeCloseTo(0.375);
expect(onElementVolume).toHaveBeenLastCalledWith(clip.el, 0.375, 0.75, 1);
});
it("preserves author volume through user zero then restore", () => {
const clip = createMockClip({ start: 0, end: 10, volume: 0.8 });
const onElementVolume = vi.fn();
syncRuntimeMedia({
clips: [clip],
timeSeconds: 1,
playing: false,
playbackRate: 1,
userVolume: 0,
onElementVolume,
});
syncRuntimeMedia({
clips: [clip],
timeSeconds: 2,
playing: false,
playbackRate: 1,
userVolume: 0.5,
onElementVolume,
});
expect(onElementVolume.mock.calls.at(-2)).toEqual([clip.el, 0, 0.8, 1]);
expect(onElementVolume.mock.calls.at(-1)).toEqual([clip.el, 0.4, 0.8, 1]);
});
it("does not mistake routed upstream unity for an authored volume change", () => {
const clip = createMockClip({ start: 0, end: 10, volume: 0.8 });
clip.el.volume = 1;
const onElementVolume = vi.fn();
syncRuntimeMedia({
clips: [clip],
timeSeconds: 1,
playing: true,
playbackRate: 1,
userVolume: 0.5,
isWebAudioRouted: (el) => el === clip.el,
onElementVolume,
});
expect(onElementVolume).toHaveBeenLastCalledWith(clip.el, 0.5, 1, 0.8);
});
describe("per-element mute (Web Audio ownership)", () => {
it("mutes a clip whose element the transport owns", () => {
const clip = createMockClip({ start: 0, end: 10 });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
isWebAudioOwned: (el) => el === clip.el,
});
expect(clip.el.muted).toBe(true);
});
it("leaves an un-owned clip audible while another track is on Web Audio", () => {
// Regression: the un-owned track used to be muted by the global gate the
// moment any source was active → silent while the owned track played.
const owned = createMockClip({ start: 0, end: 10 });
const unowned = createMockClip({ start: 0, end: 10 });
syncRuntimeMedia({
clips: [owned, unowned],
timeSeconds: 5,
playing: true,
playbackRate: 1,
isWebAudioOwned: (el) => el === owned.el,
});
expect(owned.el.muted).toBe(true);
expect(unowned.el.muted).toBe(false);
});
it("force-mutes every element when outputMuted (parent proxy owns all audio)", () => {
const clip = createMockClip({ start: 0, end: 10 });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
outputMuted: true,
isWebAudioOwned: () => false,
});
expect(clip.el.muted).toBe(true);
});
it("force-mutes every element when userMuted", () => {
const clip = createMockClip({ start: 0, end: 10 });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
userMuted: true,
isWebAudioOwned: () => false,
});
expect(clip.el.muted).toBe(true);
});
it("mutes only once the transport takes the element over", () => {
const clip = createMockClip({ start: 0, end: 10 });
let owned = false;
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
isWebAudioOwned: () => owned,
});
expect(clip.el.muted).toBe(false); // decoding — audible via HTMLMedia fallback
owned = true;
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5.1,
playing: true,
playbackRate: 1,
isWebAudioOwned: () => owned,
});
expect(clip.el.muted).toBe(true);
});
});
it("hard-syncs on the first active tick (sub-composition activation, mediaStart offsets)", () => {
const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
expect(clip.el.currentTime).toBe(5);
});
it("does not seek on sub-0.5s drift in steady-state — avoids pause/play hiccups", () => {
const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
Object.defineProperty(clip.el, "currentTime", { value: 5.4, writable: true });
// Establish a baseline offset of 0 with a steady-state tick first.
syncRuntimeMedia({ clips: [clip], timeSeconds: 5.4, playing: true, playbackRate: 1 });
// Now a small transient drift: timeline backs up 0.4s (typical of
// pause/play ordering). Below the 0.5s threshold — don't seek.
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
expect(clip.el.currentTime).toBe(5.4);
});
it("does not force audio forward while it's still buffering (gradual drift growth)", () => {
// Cold-play: audio stuck buffering at 0, timeline advances ~16ms per tick.
// The offset grows gradually; no single tick jumps by 0.5s, so the
// drift-correction seek must NOT fire. Without this guard the runtime
// would force-seek audio forward and the user would miss the opening
// words of the narration.
const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
// First tick: timeline at 0, audio at 0, no drift — first-tick hard-sync is a no-op.
syncRuntimeMedia({ clips: [clip], timeSeconds: 0, playing: true, playbackRate: 1 });
// Subsequent ticks: timeline advances, audio stays buffering at 0.
for (let t = 0.016; t < 0.7; t += 0.016) {
syncRuntimeMedia({ clips: [clip], timeSeconds: t, playing: true, playbackRate: 1 });
}
expect(clip.el.currentTime).toBe(0);
});
it("re-syncs on a scrub — offset jumps in one tick", () => {
const clip = createMockClip({ start: 0, end: 20, mediaStart: 0 });
Object.defineProperty(clip.el, "currentTime", { value: 2, writable: true });
// Steady-state.
syncRuntimeMedia({ clips: [clip], timeSeconds: 2, playing: true, playbackRate: 1 });
syncRuntimeMedia({ clips: [clip], timeSeconds: 2.02, playing: true, playbackRate: 1 });
// User scrubs forward to 15 — offset jumps from ~0 to ~13 in one tick.
syncRuntimeMedia({ clips: [clip], timeSeconds: 15, playing: true, playbackRate: 1 });
expect(clip.el.currentTime).toBe(15);
});
it("catastrophic-drift safety valve eventually resyncs a stuck element", () => {
const clip = createMockClip({ start: 0, end: 100, mediaStart: 0 });
Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
// Establish baseline at t=0.
syncRuntimeMedia({ clips: [clip], timeSeconds: 0, playing: true, playbackRate: 1 });
// Gradually advance timeline by 0.3s per tick without audio moving.
// Each tick's offset delta is 0.3 (< 0.5s jump threshold), so only the
// >3s catastrophic-drift safety valve can trigger the resync.
for (let t = 0.3; t <= 4; t += 0.3) {
syncRuntimeMedia({ clips: [clip], timeSeconds: t, playing: true, playbackRate: 1 });
}
expect(clip.el.currentTime).toBeGreaterThan(3);
});
it("clears offset baseline when clip deactivates — re-entry hard-syncs", () => {
const clip = createMockClip({ start: 0, end: 5, mediaStart: 0 });
Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
// Active pass: establish baseline at t=2.
syncRuntimeMedia({ clips: [clip], timeSeconds: 2, playing: true, playbackRate: 1 });
// Deactivate: timeline moves past the clip window.
syncRuntimeMedia({ clips: [clip], timeSeconds: 6, playing: true, playbackRate: 1 });
// Re-activate at t=3 — first-tick hard-sync should fire despite having
// a previous baseline, because the clip was inactive in between.
Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 3, playing: true, playbackRate: 1 });
expect(clip.el.currentTime).toBe(3);
});
it("rewinds stale short audio on its first tick after re-entry", () => {
const clip = createMockClip(
{ start: 3.12, end: 3.67, duration: 0.55, sourceDuration: 0.55 },
"audio",
);
Object.defineProperty(clip.el, "currentTime", { value: 0.49, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 3.12, playing: true, playbackRate: 1 });
expect(clip.el.currentTime).toBe(0);
});
it("does not force cold audio forward on its first active tick", () => {
const clip = createMockClip(
{ start: 3.12, end: 3.67, duration: 0.55, sourceDuration: 0.55 },
"audio",
);
Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 3.61, playing: true, playbackRate: 1 });
expect(clip.el.currentTime).toBe(0);
});
it("sets per-element playbackRate × global rate", () => {
const clip = createMockClip({ start: 0, end: 10, playbackRate: 0.5 });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 2 });
expect(clip.el.playbackRate).toBe(1); // 0.5 × 2 = 1
});
it("computes relTime with per-element playback rate", () => {
const clip = createMockClip({ start: 0, end: 20, playbackRate: 0.5, mediaStart: 0 });
Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 10, playing: false, playbackRate: 1 });
// At timeline t=10, with 0.5x rate: relTime = 10 * 0.5 + 0 = 5s into the media
expect(clip.el.currentTime).toBe(5);
});
it("wraps relTime when loop is true and media has ended", () => {
// 3s source at 1x, looped over 10s clip
const clip = createMockClip({
start: 0,
end: 10,
mediaStart: 0,
loop: true,
sourceDuration: 3,
});
Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
// At t=7, relTime = 7, wraps to 7 % 3 = 1
syncRuntimeMedia({ clips: [clip], timeSeconds: 7, playing: false, playbackRate: 1 });
expect(clip.el.currentTime).toBe(1);
});
it("wraps loop with mediaStart offset", () => {
// Source is 10s, mediaStart=5, so loop length is 5s (5-10)
const clip = createMockClip({
start: 0,
end: 15,
mediaStart: 5,
loop: true,
sourceDuration: 10,
});
Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
// At t=7: relTime = 7*1 + 5 = 12, wraps: 5 + ((12-5) % 5) = 5 + (7%5) = 5+2 = 7
syncRuntimeMedia({ clips: [clip], timeSeconds: 7, playing: false, playbackRate: 1 });
expect(clip.el.currentTime).toBe(7);
});
it("holds the final frame instead of looping a non-looping video", () => {
const clip = createMockClip({
start: 0,
end: 10,
mediaStart: 0,
loop: false,
sourceDuration: 3,
});
Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
// At t=7 the source is exhausted, so the final frame remains visible.
syncRuntimeMedia({ clips: [clip], timeSeconds: 7, playing: false, playbackRate: 1 });
expect(clip.el.currentTime).toBe(3);
});
it("asserts muted=true every tick while outputMuted is set", () => {
// Parent ownership has taken over audible playback via parent-frame
// proxies. The iframe runtime must silence every active media element
// per tick so new sub-composition media inherits the mute as soon as
// it appears in the DOM — otherwise a late <audio> insertion would
// briefly play audibly and double-voice the viewer.
const clip = createMockClip({ start: 0, end: 10, volume: 1 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
Object.defineProperty(clip.el, "muted", { value: false, writable: true });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
outputMuted: true,
});
expect(clip.el.muted).toBe(true);
// A second tick re-asserts — captures the sticky behavior, since
// the bridge handler only runs on flip transitions.
Object.defineProperty(clip.el, "muted", { value: false, writable: true });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5.02,
playing: true,
playbackRate: 1,
outputMuted: true,
});
expect(clip.el.muted).toBe(true);
});
it("does not touch muted when outputMuted is absent", () => {
// The un-mute decision belongs to author intent (`<audio muted>`) and
// user preference (`onSetMuted`) — syncRuntimeMedia must not race them.
const clip = createMockClip({ start: 0, end: 10 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
Object.defineProperty(clip.el, "muted", { value: true, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
expect(clip.el.muted).toBe(true);
});
it("fires onAutoplayBlocked when play() rejects with NotAllowedError", async () => {
const clip = createMockClip({ start: 0, end: 10 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
const rejection = Object.assign(new Error("blocked"), { name: "NotAllowedError" });
clip.el.play = vi.fn(() => Promise.reject(rejection));
const onAutoplayBlocked = vi.fn();
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
onAutoplayBlocked,
});
// The rejection is delivered on a microtask — flush it.
await Promise.resolve();
await Promise.resolve();
expect(onAutoplayBlocked).toHaveBeenCalledTimes(1);
});
it("does not fire onAutoplayBlocked for non-autoplay rejections", async () => {
const clip = createMockClip({ start: 0, end: 10 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
const rejection = Object.assign(new Error("aborted"), { name: "AbortError" });
clip.el.play = vi.fn(() => Promise.reject(rejection));
const onAutoplayBlocked = vi.fn();
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
onAutoplayBlocked,
});
await Promise.resolve();
await Promise.resolve();
expect(onAutoplayBlocked).not.toHaveBeenCalled();
});
it("asserts muted=true every tick while userMuted is set", () => {
// Mirror of the `outputMuted` test — user preference must be sticky
// too. A sub-composition that activates after the user mutes should
// inherit the silence, not briefly play at author volume before the
// next bridge message lands.
const clip = createMockClip({ start: 0, end: 10, volume: 1 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
Object.defineProperty(clip.el, "muted", { value: false, writable: true });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
userMuted: true,
});
expect(clip.el.muted).toBe(true);
});
it("fires onAutoplayBlocked for every rejected play (caller owns the latch)", async () => {
// media.ts is intentionally memoryless — each NotAllowedError rejection
// invokes the callback. The init.ts caller wraps with
// `mediaAutoplayBlockedPosted` so the outbound message is posted at most
// once per session. This test pins down the contract (fires always) so
// a future refactor can't quietly add deduplication here and break the
// caller's latching logic.
const clip = createMockClip({ start: 0, end: 10 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
const rejection = Object.assign(new Error("blocked"), { name: "NotAllowedError" });
clip.el.play = vi.fn(() => Promise.reject(rejection));
const onAutoplayBlocked = vi.fn();
// Simulate two ticks — between them `playRequested` clears so play() runs
// again and rejects again.
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
onAutoplayBlocked,
});
await Promise.resolve();
await Promise.resolve();
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5.05,
playing: true,
playbackRate: 1,
onAutoplayBlocked,
});
await Promise.resolve();
await Promise.resolve();
// No latch inside media.ts — two rejections, two callback invocations.
// The caller's latch is what prevents a second outbound message.
expect(onAutoplayBlocked).toHaveBeenCalledTimes(2);
});
it("caller-side latch pattern posts once across many rejections", async () => {
// Mirrors what init.ts does: the onAutoplayBlocked wrapper checks and
// sets a boolean flag so the outbound post fires exactly once even if
// the raw callback fires many times. Regression guard for the latch
// wiring in the init.ts handler.
const clip = createMockClip({ start: 0, end: 10 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
const rejection = Object.assign(new Error("blocked"), { name: "NotAllowedError" });
clip.el.play = vi.fn(() => Promise.reject(rejection));
let posted = 0;
const state = { latched: false };
const wrapped = () => {
if (state.latched) return;
state.latched = true;
posted += 1;
};
for (let i = 0; i < 5; i++) {
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5 + i * 0.05,
playing: true,
playbackRate: 1,
onAutoplayBlocked: wrapped,
});
await Promise.resolve();
await Promise.resolve();
}
expect(posted).toBe(1);
});
it("corrects stable sub-0.5s drift after consecutive over-threshold ticks", () => {
const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
Object.defineProperty(clip.el, "currentTime", { value: 5.4, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5.4, playing: true, playbackRate: 1 });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
expect(clip.el.currentTime).toBe(5.4);
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
expect(clip.el.currentTime).toBe(5.4);
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
expect(clip.el.currentTime).toBe(5);
});
it("does not force audio forward while it's still buffering (gradual drift growth)", () => {
const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 0, playing: true, playbackRate: 1 });
for (let t = 0.016; t < 0.7; t += 0.016) {
syncRuntimeMedia({ clips: [clip], timeSeconds: t, playing: true, playbackRate: 1 });
}
expect(clip.el.currentTime).toBe(0);
});
it("forceSync corrects any drift above 20ms immediately", () => {
const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
Object.defineProperty(clip.el, "currentTime", { value: 5.1, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 5.1, playing: true, playbackRate: 1 });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
forceSync: true,
});
expect(clip.el.currentTime).toBe(5);
});
describe("playing video drift", () => {
function playingVideoAt(currentTime: number, playbackRate = 1) {
const clip = createMockClip({ start: 0, end: 20, duration: 20 });
Object.defineProperty(clip.el, "paused", { value: false, writable: true });
Object.defineProperty(clip.el, "currentTime", { value: currentTime, writable: true });
clip.el.playbackRate = playbackRate;
return clip;
}
const tick = (clip: RuntimeMediaClip, timeSeconds: number, playbackRate = 1) =>
syncRuntimeMedia({
clips: [clip],
timeSeconds,
playing: true,
playbackRate,
getCompositionDuration: () => 20,
});
it("runs a video lagging past the sync tolerance 3% fast instead of seeking it", () => {
const clip = playingVideoAt(4.908);
tick(clip, 5);
tick(clip, 5);
expect(clip.el.playbackRate).toBeCloseTo(1.03, 9);
expect(clip.el.currentTime).toBe(4.908);
});
it("runs a video that is ahead 3% slow", () => {
const clip = playingVideoAt(5.06);
tick(clip, 5);
tick(clip, 5);
expect(clip.el.playbackRate).toBeCloseTo(0.97, 9);
});
it("keeps steering until the video is nearly back, then returns to the authored rate", () => {
const clip = playingVideoAt(4.9);
tick(clip, 5);
tick(clip, 5);
clip.el.currentTime = 4.98;
tick(clip, 5);
expect(clip.el.playbackRate).toBeCloseTo(1.03, 9);
clip.el.currentTime = 4.995;
tick(clip, 5);
expect(clip.el.playbackRate).toBe(1);
});
it("keeps steering through a speed ramp, whose base rate moves every tick", () => {
const clip = playingVideoAt(4.9);
tick(clip, 5, 1);
tick(clip, 5, 1);
clip.el.currentTime = 4.98;
tick(clip, 5, 1.2);
expect(clip.el.playbackRate).toBeCloseTo(1.2 * 1.03, 9);
});
it("plays a hard-synced video at its authored rate on the tick it is seeked", () => {
const clip = playingVideoAt(4.9);
tick(clip, 5);
tick(clip, 5);
expect(clip.el.playbackRate).toBeCloseTo(1.03, 9);
tick(clip, 9); // a jump past the hard-sync threshold
expect(clip.el.currentTime).toBe(9);
expect(clip.el.playbackRate).toBe(1);
});
it("does not start steering inside the sync tolerance", () => {
const clip = playingVideoAt(4.97, 2);
tick(clip, 5, 2);
tick(clip, 5, 2);
expect(clip.el.playbackRate).toBe(2);
});
it("returns a steered video to its authored rate when the transport pauses", () => {
const clip = playingVideoAt(4.9);
tick(clip, 5);
tick(clip, 5);
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: false,
playbackRate: 1,
getCompositionDuration: () => 20,
});
clip.el.currentTime = 4.98; // inside the tolerance: must not resume steering
tick(clip, 5);
expect(clip.el.playbackRate).toBe(1);
});
it("forgets the steering when the element's sync state is evicted", () => {
const clip = playingVideoAt(4.9);
tick(clip, 5);
tick(clip, 5);
evictMediaSyncState(clip.el);
expect(hasMediaSyncStateForTest(clip.el)).toBe(false);
});
it("does not rewrite a steered rate that reads back at lower precision", () => {
const clip = playingVideoAt(4.9);
let stored = 1;
let writes = 0;
Object.defineProperty(clip.el, "playbackRate", {
configurable: true,
get: () => stored,
set: (v: number) => {
writes += 1;
stored = Math.fround(v);
},
});
for (let i = 0; i < 5; i++) tick(clip, 5);
expect(writes).toBe(1);
});
it("steers a video that is far behind harder, in steps", () => {
const clip = playingVideoAt(4.85);
tick(clip, 5);
tick(clip, 5);
expect(clip.el.playbackRate).toBeCloseTo(1.1, 9);
clip.el.currentTime = 4.6;
tick(clip, 5);
expect(clip.el.playbackRate).toBeCloseTo(1.25, 9);
clip.el.currentTime = 4.93;
tick(clip, 5);
expect(clip.el.playbackRate).toBeCloseTo(1.03, 9);
});
it("steers a video that is far ahead slower, by the same steps", () => {
const clip = playingVideoAt(5.2);
tick(clip, 5);
tick(clip, 5);
expect(clip.el.playbackRate).toBeCloseTo(0.9, 9);
});
it("scales the steer with the transport rate", () => {
const clip = playingVideoAt(4.908, 2);
tick(clip, 5, 2);
tick(clip, 5, 2);
expect(clip.el.playbackRate).toBeCloseTo(2.06, 9);
});
});
it.each([
[60, 0.25],
[10, 0.5],
])(
"keeps a video slower than the browser can play on the playhead at %i fps, preview speed %f",
(fps, speed) => {
// A 0.1x clip at 0.25x or 0.5x preview speed is below Chromium's 1/16 rate floor.
const clip = createMockClip({ start: 0, end: 30, duration: 30, playbackRate: 0.1 });
const el = clip.el;
let rate = speed;
let paused = true;
Object.defineProperty(el, "playbackRate", {
configurable: true,
get: () => rate,
set: (v: number) => {
if (v < 0.0625) throw new DOMException("unsupported rate", "NotSupportedError");
rate = v;
},
});
Object.defineProperty(el, "paused", { configurable: true, get: () => paused });
el.play = vi.fn(() => ((paused = false), Promise.resolve()));
el.pause = vi.fn(() => void (paused = true));
const dt = 1 / fps;
let timeline = 0;
for (let i = 0; i < fps * 4; i++) {
timeline += speed * dt;
if (!paused) el.currentTime += rate * dt;
syncRuntimeMedia({
clips: [clip],
timeSeconds: timeline,
playing: true,
playbackRate: speed,
});
}
expect(Math.abs(el.currentTime - 0.1 * timeline)).toBeLessThan(0.05);
},
);
// A seek while playing pauses and syncs in one pass, before the video element has paused.
it("a seek that pauses mid-playback lands a lagging playing video on the new time", () => {
const clip = createMockClip({ start: 3.85, end: 5.6, duration: 1.75 });
Object.defineProperty(clip.el, "paused", { value: false, writable: true });
Object.defineProperty(clip.el, "currentTime", { value: 0.031, writable: true });
syncRuntimeMedia({ clips: [clip], timeSeconds: 4.109, playing: true, playbackRate: 1 });
expect(clip.el.currentTime).toBe(0.031);
syncRuntimeMedia({
clips: [clip],
timeSeconds: 4.4,
playing: false,
playbackRate: 1,
forceSync: true,
});
expect(clip.el.currentTime).toBeCloseTo(0.55, 5);
expect(clip.el.pause).toHaveBeenCalled();
});
it("mutes when either outputMuted OR userMuted is true (OR invariant)", () => {
// Explicit validation of the combined-flag contract: setting one to
// false while the other is true must keep the element muted.
const clip = createMockClip({ start: 0, end: 10, volume: 1 });
Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
Object.defineProperty(clip.el, "muted", { value: false, writable: true });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
outputMuted: false,
userMuted: true,
});
expect(clip.el.muted).toBe(true);
Object.defineProperty(clip.el, "muted", { value: false, writable: true });
syncRuntimeMedia({
clips: [clip],
timeSeconds: 5,
playing: true,
playbackRate: 1,
outputMuted: true,
userMuted: false,
});
expect(clip.el.muted).toBe(true);
});
});