Open source CapCut alternative.
TypeScript
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { retimeOf } from "@donkeycut/effects-kit";
import { stubModule } from "@/lib/testing/stubModule";
import { DECODE_AHEAD_S, type Timed } from "./frameSource";
import type { MediaAsset } from "./types";
// ── the files a source reads, stood in for ──────────────────────────────────
// Only the reads are replaced; every other export is carried through as it is.
interface FakeInput {
url: string;
disposed: boolean;
dispose(): void;
}
const inputs: FakeInput[] = [];
/** Addresses whose open is held until the test releases or refuses it. */
const gates = new Map<string, { promise: Promise<void>; release(): void; refuse(): void }>();
const gate = (url: string) => {
let release!: () => void;
let refuse!: () => void;
const promise = new Promise<void>((res, rej) => {
release = res;
refuse = () => rej(new Error("no track"));
});
const g = { promise, release, refuse };
gates.set(url, g);
return g;
};
const openMedia = ((src: string | Blob) => {
const input: FakeInput = {
url: String(src),
disposed: false,
dispose() {
this.disposed = true;
},
};
inputs.push(input);
return input;
}) as never;
interface FakeTrack {
url: string;
codec: string;
getDurationFromMetadata(): Promise<number>;
}
const videoTrackOf = (async (input: FakeInput) => {
const g = gates.get(input.url);
if (g) await g.promise;
const track: FakeTrack = { url: input.url, codec: "avc1", getDurationFromMetadata: async () => 10 };
return track;
}) as never;
/** Every walk a fake sink was asked for, with the address it reads and the
* height it decodes at. */
const sinkWalks: { url: string; from: number; height: number }[] = [];
/** Hold every walk on sinks of this height until released, to stand in for a
* decoder that cannot keep up with the pointer. */
let stall: { height: number; promise: Promise<void> } | null = null;
const frame = (track: FakeTrack, timestamp: number) => ({
canvas: { width: 640, height: 360 },
timestamp,
duration: 1 / 30,
});
const frameSink = ((track: FakeTrack, size?: { height?: number }) => ({
async *canvases(from: number) {
sinkWalks.push({ url: track.url, from, height: size?.height ?? 0 });
if (stall && size?.height === stall.height) await stall.promise;
for (let i = 0; ; i++) {
const timestamp = from + i / 30;
if (timestamp > 10) return;
yield frame(track, timestamp);
}
},
async getCanvas(t: number) {
return frame(track, t);
},
async *canvasesAtTimestamps(asks: number[]) {
for (const t of asks) yield frame(track, t);
},
})) as never;
const keyframeTimeAt = (async (_track: unknown, t: number) => Math.max(0, Math.floor(t))) as never;
// The shared open, over the fake files: one input per URL, closed by the
// last holder to let go, the way the real one is.
const shared = new Map<string, { input: FakeInput; refs: number }>();
const openMediaShared = (src: string) => {
let entry = shared.get(src);
if (!entry) {
entry = { input: (openMedia as unknown as (s: string) => FakeInput)(src), refs: 0 };
shared.set(src, entry);
}
const held = entry;
held.refs++;
let released = false;
return {
input: held.input,
release() {
if (released) return;
released = true;
if (--held.refs > 0) return;
if (shared.get(src) === held) shared.delete(src);
held.input.dispose();
},
};
};
await stubModule<typeof import("./mediaRead")>("./mediaRead", import.meta.url, {
openMedia,
openMediaShared: openMediaShared as never,
videoTrackOf,
frameSink,
keyframeTimeAt,
});
/** Proxies a reader reported as unopenable. */
const unopenable: MediaAsset[] = [];
await stubModule<typeof import("./mediaProxy")>("./mediaProxy", import.meta.url, {
proxyUnreadable: (async (a: MediaAsset) => {
unopenable.push(a);
}) as never,
});
const { BACK_WINDOW, ClipFrameSource, FrameRing, FrameSourcePool, mappingKey, walkClaim } =
await import("./frameSource");
/** Let the opens, walks and drains the last call set going run out. */
const settle = async (rounds = 400) => {
for (let i = 0; i < rounds; i++) await Promise.resolve();
};
/** A decoded frame at 30fps, as the sink would hand it over. */
const f = (timestamp: number, duration = 1 / 30): Timed => ({ timestamp, duration });
const asset = (id: string, width = 1280, height = 720): MediaAsset => ({
id,
name: `${id}.mp4`,
fileName: `${id}.mp4`,
type: "video",
url: `https://example.test/${id}.mp4`,
duration: 10,
width,
height,
});
describe("FrameRing", () => {
test("hands back the frame covering the asked-for time", () => {
const ring = new FrameRing<Timed>(8);
for (let i = 0; i < 5; i++) ring.push(f(i / 30));
// Between two frames, the one that started is the one on screen.
expect(ring.at(2.5 / 30)?.timestamp).toBeCloseTo(2 / 30);
expect(ring.at(2 / 30)?.timestamp).toBeCloseTo(2 / 30);
});
test("answers past the end with the newest frame it holds", () => {
// A decoder running behind the playhead should show the last real frame
// rather than nothing — this is the "never withhold" rule.
const ring = new FrameRing<Timed>(8);
ring.push(f(0));
ring.push(f(1 / 30));
expect(ring.at(5)?.timestamp).toBeCloseTo(1 / 30);
});
test("answers before the first frame with the earliest it holds", () => {
// At a clip's head the frame the cut opens on is the right thing to show.
const ring = new FrameRing<Timed>(8);
ring.push(f(2));
ring.push(f(2 + 1 / 30));
expect(ring.at(1)?.timestamp).toBeCloseTo(2);
});
test("empty ring has no answer", () => {
expect(new FrameRing<Timed>(4).at(0)).toBe(null);
});
test("covers() separates a real frame from a held one", () => {
const ring = new FrameRing<Timed>(8);
ring.push(f(1));
expect(ring.covers(1)).toBe(true);
expect(ring.covers(1 + 0.5 / 30)).toBe(true);
// Past this frame's own duration nothing is covered, even though `at`
// still hands the frame over.
expect(ring.covers(1 + 2 / 30)).toBe(false);
expect(ring.at(1 + 2 / 30)?.timestamp).toBeCloseTo(1);
expect(ring.covers(0.5)).toBe(false);
});
test("drops the oldest past capacity, so the canvas pool never wraps under it", () => {
const ring = new FrameRing<Timed>(3);
for (let i = 0; i < 6; i++) ring.push(f(i));
expect(ring.size).toBe(3);
expect(ring.oldest).toBeCloseTo(3);
expect(ring.newest).toBeCloseTo(5);
// The evicted frames are gone, not merely unreachable.
expect(ring.at(0)?.timestamp).toBeCloseTo(3);
});
test("nearer merges two rings' answers under at()'s own policy", () => {
// The backward walk's windows and the main ring each answer separately; the
// frame served is the one a single ring holding both would have picked.
const a = f(1);
const b = f(2);
const late = f(5);
// A frame at or before the ask beats one after it.
expect(FrameRing.nearer(3, a, late)).toBe(a);
expect(FrameRing.nearer(3, late, a)).toBe(a);
// Of two before, the later; of two after, the earlier.
expect(FrameRing.nearer(3, a, b)).toBe(b);
expect(FrameRing.nearer(0.5, a, b)).toBe(a);
// A lone answer stands.
expect(FrameRing.nearer(3, null, b)).toBe(b);
expect(FrameRing.nearer(3, a, null)).toBe(a);
expect(FrameRing.nearer(3, null, null)).toBe(null);
});
test("a window keeps the answer on the asking clip's side of a split", () => {
// Two clips split from one file share a ring. The clip past the split asks
// inside its own span; a garden frame from before the split is nearer but
// shows the other scene.
const ring = new FrameRing<Timed>(16);
ring.push(f(45.4));
ring.push(f(45.5));
ring.push(f(46.0));
// Ask at 45.68 in a clip whose span starts at the 45.57 split: the frames
// before the split are out, and the earliest in-window frame answers.
expect(ring.at(45.68, 45.57, 60)?.timestamp).toBeCloseTo(46.0);
// The clip before the split never shows the far side.
expect(ring.at(45.55, 40, 45.57)?.timestamp).toBeCloseTo(45.5);
expect(ring.at(46.2, 40, 45.57)?.timestamp).toBeCloseTo(45.5);
});
test("a frame spanning the window's edge still answers inside it", () => {
// A split lands mid-frame: the frame covering the second clip's `in`
// starts just before it, and it is that clip's real first picture.
const ring = new FrameRing<Timed>(16);
ring.push(f(45.55));
expect(ring.at(45.58, 45.57, 60)?.timestamp).toBeCloseTo(45.55);
});
test("nothing on the asking side answers null", () => {
const ring = new FrameRing<Timed>(16);
ring.push(f(45.4));
expect(ring.at(46.1, 45.57, 60)).toBe(null);
});
});
describe("mappingKey", () => {
const uniform = (speed: number, inPoint: number, out = 100) =>
retimeOf({ in: inPoint, out, speed });
test("clips showing identical pictures share a decoder", () => {
// A plain split: same file, same speed, and the same source time at
// timeline zero. One decoder reads straight across the cut.
const left = mappingKey("a", uniform(1, 0), 0);
const right = mappingKey("a", uniform(1, 4), 4);
expect(left).toBe(right);
});
test("different trims of one file keep their own decoders", () => {
// Both live at timeline 4, showing different moments — a same-source
// dissolve has to blend two distinct frames.
expect(mappingKey("a", uniform(1, 0), 4)).not.toBe(mappingKey("a", uniform(1, 8), 4));
});
test("a speed change is a different mapping", () => {
expect(mappingKey("a", uniform(1, 0), 0)).not.toBe(mappingKey("a", uniform(2, 0), 0));
});
test("a reversed clip is its own mapping", () => {
const rev = (inPoint: number, start: number) =>
mappingKey("a", retimeOf({ in: inPoint, out: inPoint + 4, speed: 1, reverse: true }), start);
expect(rev(0, 0)).not.toBe(mappingKey("a", uniform(1, 0, 4), 0));
// Two reversed halves of one span read straight across their cut too:
// the right half shows the lower source seconds.
expect(rev(4, 0)).toBe(rev(0, 4));
expect(rev(0, 0)).not.toBe(rev(4, 0));
});
test("a speed curve is its own mapping, keyed on the curve and the start", () => {
const curved = (start: number) =>
mappingKey("a", retimeOf({ in: 0, out: 10, speedCurve: [[0, 1], [10, 4]] }), start);
expect(curved(0)).toBe(curved(0));
expect(curved(0)).not.toBe(curved(2));
expect(curved(0)).not.toBe(mappingKey("a", uniform(1, 0), 0));
});
test("different files never share", () => {
expect(mappingKey("a", uniform(1, 0), 0)).not.toBe(mappingKey("b", uniform(1, 0), 0));
});
test("a second file read at an offset keys on that offset", () => {
// Two clips over one removal matte, each holding the matte from a
// different second. They read different pictures and need their own
// decoders; without the offset they would share one and fight over it.
const matte = (offset: number) => mappingKey("m", uniform(1, 0), 0, offset);
expect(matte(0)).toBe(mappingKey("m", uniform(1, 0), 0));
expect(matte(2)).not.toBe(matte(5));
// A curve keys the same way.
const curve = retimeOf({ in: 0, out: 10, speedCurve: [[0, 1], [10, 4]] });
expect(mappingKey("m", curve, 0, 2)).not.toBe(mappingKey("m", curve, 0, 5));
expect(mappingKey("m", curve, 0, 0)).toBe(mappingKey("m", curve, 0));
});
test("an offset lands on the mapping it shifts to", () => {
// Reading the matte two seconds back from source second 8 is the same
// picture as reading it straight from source second 6.
expect(mappingKey("m", uniform(1, 8), 0, 2)).toBe(mappingKey("m", uniform(1, 6), 0));
});
});
describe("walkClaim", () => {
/** A walk that has landed frames from `from` to `tail`, asked for `t`. */
const landed = (t: number, from: number, tail: number, covered = false, heldBefore = true) =>
walkClaim({
t, ahead: DECODE_AHEAD_S, walkFor: from, from, tail, landed: true, covered, heldBefore, comingS: 5, playing: true,
});
test("playback inside the walk keeps it", () => {
// The ordinary tick: the playhead is a beat behind the walk's tail and the
// frame is in the ring. Anything but `hold` here is a decode per frame.
expect(landed(3, 2, 3.3, true)).toBe("hold");
});
test("a walk running behind keeps its claim until it is history", () => {
// Frames still land; the picture advances a beat late. Restarting would
// pay a fresh keyframe seek to be in the same place.
expect(landed(4, 2, 3)).toBe("hold");
expect(landed(5, 2, 3.5)).toBe("hold");
// Past the allowance the frames it is about to land are already gone by.
expect(landed(6, 2, 3.5)).toBe("hop");
});
test("a walk ahead of the reader is kept, however far ahead it is", () => {
// A walk holding its lookahead is always a little way past the reader, and
// the ring stops covering that moment before the walk has done anything
// wrong. Measured on a laptop's montage, tearing one down there took a
// clean run to a seventh of its frames late — every lapse in coverage
// bought a fresh keyframe seek.
expect(landed(3, 2, 3.3)).toBe("hold");
expect(landed(3, 2, 4.9)).toBe("hold");
expect(landed(1, 0, 8)).toBe("hold");
});
test("a reader re-entering behind everything the walk left restarts it", () => {
// A montage replayed from the top: the walk from the last pass sits at the
// clip's end, the ring holds only its final frames, and the reader asks
// for the clip's head — the moment the walk was first sent for. Held, the
// clip shows its last frame for the whole pass while the sound plays on.
expect(landed(0, 0, 8, false, false)).toBe("restart");
// The same walk holding no more than its lookahead is left to land it.
expect(landed(7.8, 0, 8, false, false)).toBe("hold");
});
test("a walk aimed ahead is kept while the reader catches up to it", () => {
// A hop anchors ahead of the reader by what reaching a frame costs. The
// reader is behind the anchor by construction, and that is not the walk
// going past it — it is the walk about to be right.
const lead = {
t: 4, ahead: DECODE_AHEAD_S, walkFor: 4, from: 4.5, tail: 4.6, landed: true, covered: false, heldBefore: true, playing: true,
};
expect(walkClaim({ ...lead, comingS: 5 })).toBe("hold");
expect(walkClaim({ ...lead, t: 4.4, comingS: 5 })).toBe("hold");
// A reader that jumps back behind where the walk was sent gets the moment
// it asked for, not the lead.
expect(walkClaim({ ...lead, t: 3, comingS: 5 })).toBe("restart");
});
test("a walk still coming is left to land", () => {
// Nothing has landed: the keyframe seek, the bytes it needs, and every
// frame from the keyframe forward are all in flight. Starting another asks
// for the whole thing again, which on a reader short of bytes is the
// difference between a walk that lands and one that never does.
const coming = { walkFor: 2, from: 2, tail: 2, landed: false, covered: false, heldBefore: false, playing: true };
expect(walkClaim({ ...coming, t: 2.5, comingS: 0.5 })).toBe("hold");
expect(walkClaim({ ...coming, t: 9, comingS: 1.5 })).toBe("hold");
// Past the lag it was meant to cure, at a reader that has run beyond it,
// waiting only widens the gap it will land into.
expect(walkClaim({ ...coming, t: 9, comingS: 3 })).toBe("hop");
// Still coming, and the reader has not passed it: there is nothing better
// to do than let it land.
expect(walkClaim({ ...coming, t: 3, comingS: 3 })).toBe("hold");
// A reader behind where it was sent is not waiting for it at all.
expect(walkClaim({ ...coming, t: 1, comingS: 0.1 })).toBe("restart");
});
test("a frame in hand beats every other rule", () => {
expect(walkClaim({
t: 0, walkFor: 5, from: 5, tail: 9, landed: true, covered: true, heldBefore: false, comingS: 9, playing: true,
})).toBe("hold");
// A paused reader is served by the backward walk and by the single-frame
// fetch, so a walk it cannot use is left where it is.
expect(walkClaim({
t: 1, walkFor: 5, from: 5, tail: 6, landed: true, covered: false, heldBefore: false, comingS: 9, playing: false,
})).toBe("hold");
});
});
describe("FrameSourcePool", () => {
// The pool's budgets are the smaller of what it was tuned to want and this
// machine's share, and these tests are about the tuning: they put the pool
// on a machine with room, which is the most a browser will report, and hand
// the machine back after.
beforeEach(() => {
Object.defineProperty(navigator, "deviceMemory", { value: 8, configurable: true });
});
afterEach(() => {
delete (navigator as { deviceMemory?: number }).deviceMemory;
});
test("one source per mapping and size, reused across frames", () => {
const pool = new FrameSourcePool(4);
pool.beginFrame();
const a = pool.get("k", asset("a"), 480);
const b = pool.get("k", asset("a"), 480);
expect(a).toBe(b);
// A different preview size is a different decode.
expect(pool.get("k", asset("a"), 240)).not.toBe(a);
expect(pool.size).toBe(2);
});
test("a source follows its asset's URL, in place", () => {
// A signed URL re-mints, or an import lands in project storage. The
// mapping still names the same pictures at a new address, so the source
// moves there itself — everything it has decoded keeps answering while
// the new address opens behind it.
const pool = new FrameSourcePool(4);
pool.beginFrame();
const before = pool.get("k", asset("a"), 480);
expect(pool.get("k", asset("a"), 480)).toBe(before);
const moved = { ...asset("a"), url: "https://example.test/a.mp4?e=2&s=next" };
const after = pool.get("k", moved, 480);
expect(after).toBe(before);
expect(after.url).toBe(moved.url);
expect(pool.size).toBe(1);
});
test("a source moves onto the proxy the moment it lands", () => {
// A ProRes master plays through the WASM decoder until its proxy is
// written onto the asset; the same mapping then reads the proxy's URL,
// in place, with nothing reloaded.
const pool = new FrameSourcePool(4);
pool.beginFrame();
const master = asset("a");
const before = pool.get("k", master, 480);
expect(before.url).toBe(master.url);
const proxied = {
...master,
proxy: { fileName: "a.proxy.mp4", sizeBytes: 1 },
proxyUrl: "https://example.test/a.proxy.mp4",
};
const after = pool.get("k", proxied, 480);
expect(after).toBe(before);
expect(after.url).toBe(proxied.proxyUrl);
expect(pool.size).toBe(1);
});
test("suspends the least recently asked-for, never this frame's", () => {
const pool = new FrameSourcePool(2);
pool.beginFrame();
const old = pool.get("old", asset("a"), 480);
pool.beginFrame();
const mid = pool.get("mid", asset("b"), 480);
// Let the grace expire on both, then draw a third from a frame of its own.
for (let i = 0; i < 200; i++) pool.beginFrame();
const live = pool.get("live", asset("c"), 480);
expect(pool.size).toBe(3);
pool.evict();
// Past the budget the idle ones stand down, and standing down keeps the
// source — its parsed file and its sink's canvases — so the next visit
// finds the same instance instead of paying for a fresh open.
expect(pool.size).toBe(3);
expect(pool.get("live", asset("c"), 480)).toBe(live);
expect(pool.get("mid", asset("b"), 480)).toBe(mid);
expect(pool.get("old", asset("a"), 480)).toBe(old);
});
test("idle decoders stand down by the pixels they cover", () => {
const uhd = (id: string) => asset(id, 3840, 2160);
const hd = (id: string) => asset(id, 1920, 1080);
const ids = ["a", "b", "c", "d", "e", "f"];
const pool = new FrameSourcePool(12);
const big = ids.map((id) => {
pool.beginFrame();
return pool.get(id, uhd(id), 480);
});
const small = ids.map((id) => {
pool.beginFrame();
return pool.get(`${id}-hd`, hd(id), 480);
});
for (let i = 0; i < 200; i++) pool.beginFrame();
pool.evict();
// Twelve decoders are inside the count. The six 1080p files are read
// most recently and fit the pixel budget together; behind them the 4K
// files fill what is left, and the oldest stand down.
expect(small.map((s) => s.suspended)).toEqual(ids.map(() => false));
expect(big.map((s) => s.suspended)).toEqual([true, true, true, true, false, false]);
});
test("says what it is holding, live sources included", () => {
const pool = new FrameSourcePool(4);
expect(pool.decoderBytes).toBe(0);
expect(pool.canvasBytes).toBe(0);
pool.beginFrame();
pool.get("a", asset("a", 3840, 2160), 2160);
// A live 4K decoder holds sixteen planar frames: about two hundred
// megabytes, none of which the warm shelf's own number would ever show.
expect(Math.round(pool.decoderBytes / 2 ** 20)).toBe(190);
expect(pool.warmPixels).toBe(0);
expect(pool.canvasBytes).toBeGreaterThan(0);
// One 4K source is well inside the budget, so nothing stands down.
for (let i = 0; i < 200; i++) pool.beginFrame();
pool.evict();
expect(pool.decoderBytes).toBeGreaterThan(0);
// Standing down gives the decoder back and keeps the canvases, which is
// the whole point of the warm shelf.
const tight = new FrameSourcePool(0);
tight.beginFrame();
tight.get("a", asset("a", 1920, 1080), 1080);
const canvases = tight.canvasBytes;
for (let i = 0; i < 200; i++) tight.beginFrame();
tight.evict();
expect(tight.decoderBytes).toBe(0);
expect(tight.canvasBytes).toBe(canvases);
});
test("standing down costs a decoder, not a source", () => {
const pool = new FrameSourcePool(1);
pool.beginFrame();
const a = pool.get("a", asset("a"), 360);
pool.beginFrame();
pool.get("b", asset("b"), 360);
for (let i = 0; i < 200; i++) pool.beginFrame();
// Both are idle and the budget is one, so the older gives up its decoder.
pool.evict();
expect(pool.size).toBe(2);
expect(pool.active).toBe(1);
// Suspension is a state: evicting again changes nothing, and reading the
// source is what wakes it.
pool.evict();
expect(pool.active).toBe(1);
a.want(0, false);
expect(pool.active).toBe(2);
});
test("closes what the canvas budget cannot keep", () => {
// Big frames: a handful of sinks is the whole budget, so a montage of them
// is bounded by memory rather than by a count.
const pool = new FrameSourcePool(2);
for (let i = 0; i < 24; i++) {
pool.beginFrame();
pool.get(`s${i}`, asset(`x${i}`, 3840, 2160), 2160);
}
for (let i = 0; i < 200; i++) pool.beginFrame();
pool.evict();
expect(pool.size).toBeLessThan(6);
// Small frames of the same count fit, and all of them stay.
const small = new FrameSourcePool(2);
for (let i = 0; i < 24; i++) {
small.beginFrame();
small.get(`s${i}`, asset(`x${i}`, 640, 360), 360);
}
for (let i = 0; i < 200; i++) small.beginFrame();
small.evict();
expect(small.size).toBe(24);
expect(small.active).toBe(2);
});
test("holds a source through the grace, so a busy cut never thrashes", () => {
// A cut with more clips than the budget would otherwise close and reopen
// decoders every frame, and reopening costs far more than the memory it
// saves. Nothing is closed until it has gone unwanted for a while.
const pool = new FrameSourcePool(1);
pool.beginFrame();
const a = pool.get("a", asset("a"), 480);
pool.beginFrame();
const b = pool.get("b", asset("b"), 480);
pool.evict();
expect(pool.size).toBe(2);
expect(pool.get("a", asset("a"), 480)).toBe(a);
expect(pool.get("b", asset("b"), 480)).toBe(b);
});
test("stays put while under budget", () => {
const pool = new FrameSourcePool(4);
pool.beginFrame();
const a = pool.get("a", asset("a"), 480);
pool.beginFrame();
pool.evict();
expect(pool.get("a", asset("a"), 480)).toBe(a);
});
});
describe("ClipFrameSource retarget", () => {
const reset = () => {
inputs.length = 0;
sinkWalks.length = 0;
gates.clear();
};
test("the picture rides its ring across a change of address", async () => {
// The failure this is here for: a library clip lands in project storage
// mid-play and its asset moves to the stored URL, and closing the source
// there put a cold open — a container read over the link, an empty ring —
// in front of the very next frame. The frames already decoded carry the
// picture while the new address opens behind them.
reset();
const before = asset("ride");
const src = new ClipFrameSource(before, 360);
src.want(0.1, true);
await settle();
expect(src.frameAt(0.1)).not.toBeNull();
const movedUrl = "https://example.test/ride-landed.mp4";
const g = gate(movedUrl);
src.retarget({ ...before, url: movedUrl });
expect(src.url).toBe(movedUrl);
await settle();
// The new address has not opened yet: everything decoded keeps answering,
// and the old stack keeps walking frames in.
expect(src.frameAt(0.1)).not.toBeNull();
src.want(0.3, true);
await settle();
expect(src.frameAt(0.3)).not.toBeNull();
expect(inputs[0].disposed).toBe(false);
g.release();
await settle();
// The stack swapped: the old file let go, the frames kept.
expect(inputs[0].disposed).toBe(true);
expect(src.frameAt(0.3)).not.toBeNull();
src.want(0.6, true);
await settle();
// The walk carrying on reads the new address.
expect(sinkWalks[sinkWalks.length - 1].url).toBe(movedUrl);
expect(src.frameAt(0.6)).not.toBeNull();
src.close();
});
test("a proxy that will not open hands the source back to the master", async () => {
// A copied project once named a proxy file it never received: the source
// retried that address forever and the clip stayed black. The reader
// reports it, the store drops the proxy, and the pool moves the source
// onto the master.
reset();
unopenable.length = 0;
const pool = new FrameSourcePool(4);
pool.beginFrame();
const master = asset("lost");
const proxied = { ...master, proxy: { fileName: "lost.proxy.mp4", sizeBytes: 1 }, proxyUrl: "https://example.test/lost.proxy.mp4" };
gate(proxied.proxyUrl).refuse();
const src = pool.get("k", proxied, 360);
src.want(0.1, true);
await settle();
expect(unopenable.map((a) => a.id)).toEqual(["lost"]);
expect(src.failed).toBe(true);
// What proxyUnreadable does to the store: the asset loses its proxy.
expect(pool.get("k", master, 360)).toBe(src);
expect(src.url).toBe(master.url);
expect(src.failed).toBe(false);
src.want(0.1, true);
await settle();
expect(src.frameAt(0.1)).not.toBeNull();
expect(sinkWalks[sinkWalks.length - 1].url).toBe(master.url);
pool.dispose();
});
test("a new address that will not open leaves the picture standing", async () => {
reset();
const before = asset("stay");
const src = new ClipFrameSource(before, 360);
src.want(0.1, true);
await settle();
expect(src.frameAt(0.1)).not.toBeNull();
const movedUrl = "https://example.test/stay-gone.mp4";
const g = gate(movedUrl);
src.retarget({ ...before, url: movedUrl });
await settle();
g.refuse();
await settle();
// The failed open is spent on the probe alone: the frames stay, the old
// file stays open, and the usual retries go after the new address.
expect(src.frameAt(0.1)).not.toBeNull();
expect(inputs[0].disposed).toBe(false);
expect(inputs[inputs.length - 1].disposed).toBe(true);
src.close();
});
});
describe("ClipFrameSource held frames keep their read", () => {
// A full-range master reads full range; its proxy is limited-range Rec.709.
// A frame decoded from one keeps meaning what it meant when the source moves
// to the other, until frames off the new file replace it.
const color = { matrix: "bt709", fullRange: true, bitDepth: 8, detected: "rec709", codec: "avc1" } as const;
const master = (): MediaAsset => ({ ...asset("held"), color: { ...color } });
const proxied = (): MediaAsset => ({
...master(),
proxy: { fileName: "held.proxy.mp4", sizeBytes: 1 },
proxyUrl: "https://example.test/held.proxy.mp4",
});
const rangeOf = (read: { recipe(): { fullRange?: boolean } } | undefined) => read?.recipe().fullRange;
test("a master frame held after its proxy lands is read as the master", async () => {
inputs.length = 0;
sinkWalks.length = 0;
gates.clear();
const src = new ClipFrameSource(master(), 360);
src.want(0.1, true);
await settle();
expect(rangeOf(src.frameAt(0.1)!.read)).toBe(true);
src.retarget(proxied());
await settle();
// Paused on the same moment: the held master frame answers exactly, so
// nothing re-decodes it, and it keeps the master's read while the source
// itself now reads the proxy.
src.want(0.1, false);
await settle();
expect(src.hasExact(0.1)).toBe(true);
expect(rangeOf(src.colorRead)).toBe(false);
expect(rangeOf(src.frameAt(0.1)!.read)).toBe(true);
expect(rangeOf(src.shownColorRead)).toBe(true);
// Frames the walk lands off the proxy read as the proxy.
src.want(2, true);
await settle();
expect(sinkWalks[sinkWalks.length - 1].url).toBe(proxied().proxyUrl!);
expect(rangeOf(src.frameAt(2)!.read)).toBe(false);
expect(rangeOf(src.shownColorRead)).toBe(false);
src.close();
});
test("a proxy frame held after the fallback to the master is read as the proxy", async () => {
inputs.length = 0;
sinkWalks.length = 0;
gates.clear();
const src = new ClipFrameSource(proxied(), 360);
src.want(0.1, true);
await settle();
expect(rangeOf(src.frameAt(0.1)!.read)).toBe(false);
src.retarget(master());
await settle();
src.want(0.1, false);
await settle();
expect(rangeOf(src.colorRead)).toBe(true);
expect(rangeOf(src.frameAt(0.1)!.read)).toBe(false);
src.want(2, true);
await settle();
expect(sinkWalks[sinkWalks.length - 1].url).toBe(master().url);
expect(rangeOf(src.frameAt(2)!.read)).toBe(true);
src.close();
});
test("a profile override reaches a held frame at once", async () => {
inputs.length = 0;
sinkWalks.length = 0;
gates.clear();
const src = new ClipFrameSource(master(), 360);
src.want(0.1, true);
await settle();
src.follow({ ...master(), colorProfile: "srgb" });
expect(src.frameAt(0.1)!.read!.recipe().profile).toBe("srgb");
src.close();
});
});
describe("ClipFrameSource replay", () => {
test("a playing reader back at a clip's head gets a fresh walk", async () => {
// The cut played once: the walk read the clip from 2s to its end at 5s and
// stopped there, holding its lookahead. The play button then seeks to zero
// and starts the clock in the same turn, so the clip is asked for 2s again
// while playing — behind everything the ring holds. A held walk here is
// the report of a picture that stops while the sound plays on.
inputs.length = 0;
sinkWalks.length = 0;
gates.clear();
const src = new ClipFrameSource(asset("replay"), 360);
src.want(2, true);
await settle();
for (let t = 2; t <= 5; t += 0.1) {
src.want(+t.toFixed(3), true);
await settle(50);
}
expect(src.frameAt(5)?.timestamp).toBeGreaterThanOrEqual(5 - 1e-3);
expect(src.hasExact(2)).toBe(false);
const walksBefore = sinkWalks.length;
src.want(2, true);
await settle();
expect(sinkWalks.length).toBe(walksBefore + 1);
expect(sinkWalks[sinkWalks.length - 1].from).toBeCloseTo(2, 3);
expect(src.hasExact(2)).toBe(true);
expect(src.frameAt(2)?.timestamp).toBeCloseTo(2, 3);
src.close();
});
test("an ordinary tick never restarts the walk", async () => {
// The same play, watched tick by tick: the reader is always a beat behind
// the walk's tail with the frame on screen in hand, and one walk carries
// the whole clip.
inputs.length = 0;
sinkWalks.length = 0;
gates.clear();
const src = new ClipFrameSource(asset("steady"), 360);
src.want(2, true);
await settle();
const walks = sinkWalks.length;
for (let t = 2; t <= 5; t += 1 / 60) {
src.want(+t.toFixed(4), true);
await settle(50);
expect(src.frameAt(t)).not.toBeNull();
}
expect(sinkWalks.length).toBe(walks);
src.close();
});
});
describe("ClipFrameSource backward walk", () => {
const reset = () => {
inputs.length = 0;
sinkWalks.length = 0;
gates.clear();
stall = null;
};
const dt = 1 / 30;
test("a creep backward is answered from windows landed below the pointer", async () => {
// The report: dragging the playhead backward stutters. Frames decode
// forward from a keyframe, so each backward step used to cost a keyframe
// walk of its own, thrown away by the next step. Here the pointer backs
// through two seconds a frame at a time and finds each frame already in
// hand: one keyframe decode per window of frames, the next window landed
// while the pointer crosses the current one.
reset();
const src = new ClipFrameSource(asset("back"), 360);
src.want(6, false);
await settle();
expect(src.hasExact(6)).toBe(true);
const walksBefore = sinkWalks.length;
let waited = 0;
for (let t = 6 - dt; t >= 4; t -= dt) {
const at = +t.toFixed(4);
src.want(at, false);
if (!src.hasExact(at)) waited++;
await settle(60);
expect(src.hasExact(at)).toBe(true);
expect(Math.abs(src.frameAt(at)!.timestamp - at)).toBeLessThan(dt);
}
// Only the first step waits on a fill; every later one lands inside a
// window already there.
expect(waited).toBeLessThanOrEqual(1);
// Sixty frames back is six windows, plus the ones clamped at a keyframe.
const walks = sinkWalks.length - walksBefore;
expect(walks).toBeLessThanOrEqual(60 / BACK_WINDOW + 4);
src.close();
});
test("a drag that outruns the windows still has a picture near the pointer", async () => {
// The fine windows are held back, as a decoder that cannot keep up would
// hold them; the coarse spread over the keyframe span lands regardless
// and stands in near the pointer until the window arrives.
reset();
const src = new ClipFrameSource(asset("fast"), 720);
src.want(7.5, false);
await settle();
let release!: () => void;
stall = { height: 720, promise: new Promise<void>((r) => (release = r)) };
src.want(7.4, false);
await settle(60);
src.want(7.05, false);
await settle(60);
expect(src.hasExact(7.05)).toBe(false);
const near = src.frameAt(7.05);
expect(near).not.toBeNull();
expect(Math.abs(near!.timestamp - 7.05)).toBeLessThan(0.1);
release();
stall = null;
await settle();
// The walk catches up: the window ending at the pointer lands.
expect(src.hasExact(7.05)).toBe(true);
expect(Math.abs(src.frameAt(7.05)!.timestamp - 7.05)).toBeLessThan(dt);
src.close();
});
test("turning forward again rides the forward walk", async () => {
reset();
const src = new ClipFrameSource(asset("turn"), 360);
src.want(5, false);
await settle();
for (let t = 5 - dt; t >= 4.5; t -= dt) {
src.want(+t.toFixed(4), false);
await settle(60);
}
const walksBefore = sinkWalks.length;
for (let t = 4.5 + dt; t <= 5.5; t += dt) {
const at = +t.toFixed(4);
src.want(at, false);
await settle(60);
expect(src.hasExact(at)).toBe(true);
}
// Back through the windows costs nothing; past them, one walk creeps on.
expect(sinkWalks.length - walksBefore).toBeLessThanOrEqual(2);
src.close();
});
test("playing lets the backward frames go", async () => {
reset();
const src = new ClipFrameSource(asset("play"), 360);
src.want(5, false);
await settle();
src.want(5 - dt, false);
await settle();
expect(src.debugState().back).not.toBeNull();
src.want(5 - dt, true);
await settle();
expect(src.debugState().back).toBeNull();
src.close();
});
test("only the sources this frame reads hold backward frames", async () => {
// Backward frames are two sinks' worth of canvases. A montage backed
// through would keep a set per clip crossed; the pool keeps them on what
// this frame reads — the pointer's clip and the neighbour warmed under it
// — and a clip the pointer has left lets its go the moment another walk
// starts.
reset();
const pool = new FrameSourcePool(4);
pool.beginFrame();
const a = pool.get("a", asset("a"), 360);
a.want(5, false);
await settle();
a.want(5 - dt, false);
await settle();
expect(a.debugState().back).not.toBeNull();
pool.beginFrame();
const b = pool.get("b", asset("b"), 360);
b.want(5, false);
await settle();
b.want(5 - dt, false);
await settle();
expect(b.debugState().back).not.toBeNull();
expect(a.debugState().back).toBeNull();
// Both read in one frame — the pointer's clip and the one warmed below
// it — keep theirs together.
pool.beginFrame();
pool.get("a", asset("a"), 360);
pool.get("b", asset("b"), 360);
a.want(5, false);
await settle();
a.want(5 - dt, false);
await settle();
expect(a.debugState().back).not.toBeNull();
expect(b.debugState().back).not.toBeNull();
pool.closeAll();
});
});