Skip to content

Commit 34a9762

Browse files
vanceingallsclaude
andcommitted
perf(studio): timeline thumbnails come back from disk in the next session
Reopening a project re-read every video's index and re-decoded every strip: the frame cache and the source facts lived in memory, keyed by the session. Now each source's facts (aspect, duration) and every decoded frame are kept in Cache Storage under the file's ETag, the version the server says it is. A new session checks each source once with a conditional one-byte read: a 304 means the stored frames are still that file's, and a strip they cover paints without opening a reader. A new ETag drops what was stored for the old one. Sources are dropped whole, least recently used first, past 256 MiB. A store that is missing or fails (private window, quota) warns once and the strip decodes as before. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 40c28e1 commit 34a9762

6 files changed

Lines changed: 461 additions & 6 deletions

File tree

‎packages/studio/src/player/lib/mediaFetch.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -177,6 +177,9 @@ export function mediaUrlSourceOptions(reader: MediaReader) {
177177
const failuresByStart = new Map<number | null, number>();
178178
const inFlightReads = new AbortController();
179179
let ranges: "unknown" | "readable" | "hidden" = reader === "thumbnail" ? "unknown" : "hidden";
180+
let etag: string | undefined;
181+
const noteEtag = (response: Response) =>
182+
void (etag ??= response.headers.get("ETag") ?? undefined);
180183
const fetchFn = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
181184
const sent = ranges === "readable" ? boundedRange(init) : init;
182185
const asked = Number(rangeStart(sent, true) ?? 0);
@@ -187,6 +190,7 @@ export function mediaUrlSourceOptions(reader: MediaReader) {
187190
);
188191
const response = await typedFetch(reader, input, sent ?? {}, asked, request);
189192
if (ranges !== "hidden") ranges = rangesReadable(sent, response) ? "readable" : "hidden";
193+
noteEtag(response);
190194
return typedResponse(response, asked, request);
191195
};
192196
const getRetryDelay = (_previousAttempts: number, error: unknown): number | null => {
@@ -201,8 +205,9 @@ export function mediaUrlSourceOptions(reader: MediaReader) {
201205
};
202206
const cancelReads = () =>
203207
inFlightReads.abort(new DOMException("Media reads cancelled", "AbortError"));
204-
if (reader === "probe") return { fetchFn, getRetryDelay, cancelReads };
205-
return { fetchFn, getRetryDelay, cancelReads, maxCacheSize: POOLED_READER_CACHE_BYTES };
208+
const etagOf = () => etag;
209+
if (reader === "probe") return { fetchFn, getRetryDelay, cancelReads, etagOf };
210+
return { fetchFn, getRetryDelay, cancelReads, etagOf, maxCacheSize: POOLED_READER_CACHE_BYTES };
206211
}
207212

208213
export function reportMediaFetchFailure(error: unknown): void {
Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
// @vitest-environment happy-dom
2+
3+
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
4+
import {
5+
readStoredFrame,
6+
readStoredInfo,
7+
rememberVersion,
8+
resetStoredThumbnailsForTests,
9+
STORED_THUMBNAIL_BYTES,
10+
storedVersion,
11+
storeFrame,
12+
storeInfo,
13+
} from "./thumbnailDiskCache";
14+
15+
/** Cache Storage as a Map of Maps: what a browser keeps across sessions. */
16+
function fakeCacheStorage() {
17+
const stores = new Map<string, Map<string, Response>>();
18+
const storage = {
19+
open: async (name: string) => {
20+
const store = stores.get(name) ?? new Map<string, Response>();
21+
stores.set(name, store);
22+
return {
23+
match: async (url: string) => store.get(String(url))?.clone(),
24+
put: async (url: string, response: Response) => void store.set(String(url), response),
25+
};
26+
},
27+
has: async (name: string) => stores.has(name),
28+
keys: async () => [...stores.keys()],
29+
delete: async (name: string) => stores.delete(name),
30+
};
31+
return { storage, stores };
32+
}
33+
34+
const v1 = { source: "/media/take.mp4", etag: '"one"' };
35+
const v2 = { source: "/media/take.mp4", etag: '"two"' };
36+
// a picture that reports `bytes` without holding them, so the budget test needs no real 128 MB
37+
function jpeg(bytes = 5): Blob {
38+
const blob = new Blob([new Uint8Array(Math.min(bytes, 5))], { type: "image/jpeg" });
39+
return Object.defineProperty(blob, "size", { value: bytes });
40+
}
41+
42+
let stores: Map<string, Map<string, Response>>;
43+
44+
beforeEach(() => {
45+
resetStoredThumbnailsForTests();
46+
localStorage.clear();
47+
const fake = fakeCacheStorage();
48+
stores = fake.stores;
49+
vi.stubGlobal("caches", fake.storage);
50+
});
51+
52+
afterEach(() => {
53+
vi.unstubAllGlobals();
54+
vi.restoreAllMocks();
55+
});
56+
57+
describe("stored thumbnails", () => {
58+
it("keep a source's facts and each frame with the time it was decoded at", async () => {
59+
await storeInfo(v1, { aspect: 16 / 9, metadataDuration: 30 });
60+
await storeFrame(v1, "cover 320x180 2.5", 2.4, jpeg());
61+
62+
expect(await readStoredInfo(v1)).toEqual({ aspect: 16 / 9, metadataDuration: 30 });
63+
const frame = await readStoredFrame(v1, "cover 320x180 2.5");
64+
expect(frame?.decodedAt).toBe(2.4);
65+
expect(frame?.blob.size).toBe(5);
66+
expect(await readStoredFrame(v1, "cover 320x180 5")).toBeUndefined();
67+
expect(await readStoredFrame(v2, "cover 320x180 2.5")).toBeUndefined();
68+
});
69+
70+
it("are trusted in a new session only when the server answers the stored ETag with a 304", async () => {
71+
const fetch = vi.fn(async () => new Response(null, { status: 304 }));
72+
vi.stubGlobal("fetch", fetch);
73+
expect(await storedVersion(v1.source)).toBeUndefined();
74+
expect(fetch).not.toHaveBeenCalled();
75+
76+
await rememberVersion(v1);
77+
expect(await storedVersion(v1.source)).toEqual(v1);
78+
expect(fetch).toHaveBeenCalledWith(v1.source, {
79+
headers: { Range: "bytes=0-0", "If-None-Match": '"one"' },
80+
});
81+
fetch.mockResolvedValueOnce(new Response("x", { status: 206 }));
82+
expect(await storedVersion(v1.source)).toBeUndefined();
83+
});
84+
85+
it("drop what was stored for a file's earlier version once a new one is read", async () => {
86+
await rememberVersion(v1);
87+
await storeFrame(v1, "cover 320x180 1", 1, jpeg());
88+
await rememberVersion(v2);
89+
90+
expect(await readStoredFrame(v1, "cover 320x180 1")).toBeUndefined();
91+
expect(stores.size).toBe(0);
92+
});
93+
94+
it("drop the least recently used sources once they pass the budget", async () => {
95+
const big = Math.floor(STORED_THUMBNAIL_BYTES / 2) + 1;
96+
const others = ["/a.mp4", "/b.mp4", "/c.mp4"].map((source) => ({ source, etag: '"1"' }));
97+
for (const version of others) {
98+
await storeFrame(version, "cover 1x1 0", 0, jpeg(big));
99+
vi.spyOn(Date, "now").mockReturnValue(Date.now() + 1000);
100+
}
101+
102+
expect(await readStoredFrame(others[0]!, "cover 1x1 0")).toBeUndefined();
103+
expect(await readStoredFrame(others[2]!, "cover 1x1 0")).toBeDefined();
104+
});
105+
106+
it("never fail a thumbnail: a broken store warns once and reads as empty", async () => {
107+
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
108+
vi.stubGlobal("caches", {
109+
open: async () => {
110+
throw new DOMException("quota", "QuotaExceededError");
111+
},
112+
});
113+
114+
expect(await readStoredInfo(v1)).toBeUndefined();
115+
expect(await storeFrame(v1, "cover 1x1 0", 0, jpeg())).toBeUndefined();
116+
expect(warn).toHaveBeenCalledTimes(1);
117+
});
118+
119+
it("are skipped where the browser offers no Cache Storage", async () => {
120+
vi.stubGlobal("caches", undefined);
121+
expect(await readStoredInfo(v1)).toBeUndefined();
122+
expect(await storeInfo(v1, { aspect: 1, metadataDuration: 1 })).toBeUndefined();
123+
});
124+
});
Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
import type { SourceInfo } from "./thumbnailSourcePool";
2+
3+
/** A video as the server serves it now: its URL and the ETag of this version of its file. */
4+
export interface StoredSource {
5+
source: string;
6+
etag: string;
7+
}
8+
9+
interface StoredFrame {
10+
blob: Blob;
11+
decodedAt: number;
12+
}
13+
14+
const CACHE_PREFIX = "hf-thumbnails:";
15+
const INDEX_KEY = "hf-thumbnails-index";
16+
const ENTRY_ORIGIN = "https://hf-thumbnail.invalid/";
17+
export const STORED_THUMBNAIL_BYTES = 256 * 1024 * 1024;
18+
19+
interface Index {
20+
etags: Record<string, string>;
21+
caches: Record<string, { usedAt: number; bytes: number }>;
22+
}
23+
24+
let index: Index | undefined;
25+
let saveTimer: ReturnType<typeof setTimeout> | undefined;
26+
let warned = false;
27+
28+
const available = () => typeof caches !== "undefined" && typeof crypto?.subtle !== "undefined";
29+
30+
/** Disk is a shortcut, never a reason a thumbnail fails: a broken store says so once and is skipped. */
31+
async function quietly<T>(work: () => Promise<T>): Promise<T | undefined> {
32+
if (!available()) return undefined;
33+
try {
34+
return await work();
35+
} catch (error) {
36+
if (!warned) console.warn("[Studio] timeline thumbnails stay in memory:", error);
37+
warned = true;
38+
return undefined;
39+
}
40+
}
41+
42+
async function digest(text: string): Promise<string> {
43+
const bytes = new Uint8Array(
44+
await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)),
45+
);
46+
return Array.from(bytes.subarray(0, 12), (byte) => byte.toString(16).padStart(2, "0")).join("");
47+
}
48+
49+
const cacheNameOf = async ({ source, etag }: StoredSource) =>
50+
`${CACHE_PREFIX}${await digest(source)}:${await digest(etag)}`;
51+
52+
function loadIndex(): Index {
53+
if (index) return index;
54+
try {
55+
const saved = JSON.parse(localStorage.getItem(INDEX_KEY) ?? "null") as Index | null;
56+
if (saved?.etags && saved.caches) index = saved;
57+
} catch {
58+
// expected: no storage (a private window) or a value this version can't read starts an empty index
59+
}
60+
return (index ??= { etags: {}, caches: {} });
61+
}
62+
63+
function saveIndexSoon(): void {
64+
saveTimer ??= setTimeout(() => {
65+
saveTimer = undefined;
66+
try {
67+
localStorage.setItem(INDEX_KEY, JSON.stringify(loadIndex()));
68+
} catch {
69+
// expected: storage refused; the caches still hold the frames, only their order of use is lost
70+
}
71+
}, 1000);
72+
}
73+
74+
function used(name: string, addedBytes = 0): void {
75+
const caches = loadIndex().caches;
76+
caches[name] = { usedAt: Date.now(), bytes: (caches[name]?.bytes ?? 0) + addedBytes };
77+
saveIndexSoon();
78+
}
79+
80+
/** The version stored for `source`, when one conditional one-byte read says the server still has it (304). */
81+
export const storedVersion = (source: string) =>
82+
quietly(async (): Promise<StoredSource | undefined> => {
83+
const etag = loadIndex().etags[await digest(source)];
84+
if (!etag) return undefined;
85+
// oxlint-disable-next-line no-restricted-globals -- one validation read, on the media's own route like mediabunny's
86+
const response = await fetch(source, {
87+
headers: { Range: "bytes=0-0", "If-None-Match": etag },
88+
});
89+
await response.body?.cancel();
90+
return response.status === 304 ? { source, etag } : undefined;
91+
});
92+
93+
/** Records the version the server now has, dropping what was stored for the source's earlier versions. */
94+
export const rememberVersion = (stored: StoredSource) =>
95+
quietly(async () => {
96+
const key = await digest(stored.source);
97+
const saved = loadIndex();
98+
if (saved.etags[key] === stored.etag) return;
99+
saved.etags[key] = stored.etag;
100+
saveIndexSoon();
101+
const keep = await cacheNameOf(stored);
102+
for (const name of await caches.keys()) {
103+
if (!name.startsWith(`${CACHE_PREFIX}${key}:`) || name === keep) continue;
104+
await caches.delete(name);
105+
delete saved.caches[name];
106+
}
107+
});
108+
109+
async function entry(stored: StoredSource, path: string) {
110+
const name = await cacheNameOf(stored);
111+
return { name, cache: await caches.open(name), url: `${ENTRY_ORIGIN}${path}` };
112+
}
113+
114+
/** A read opens nothing: opening a cache creates it, and an empty one for a gone version would never be dropped. */
115+
async function storedEntry(stored: StoredSource, path: string) {
116+
const name = await cacheNameOf(stored);
117+
return (await caches.has(name)) ? entry(stored, path) : undefined;
118+
}
119+
120+
export const readStoredInfo = (stored: StoredSource) =>
121+
quietly(async (): Promise<SourceInfo | undefined> => {
122+
const found = await storedEntry(stored, "info");
123+
if (!found) return undefined;
124+
const { name, cache, url } = found;
125+
const info = (await (await cache.match(url))?.json()) as SourceInfo | undefined;
126+
if (!(info && info.aspect > 0)) return undefined;
127+
used(name);
128+
return info;
129+
});
130+
131+
export const storeInfo = (stored: StoredSource, info: SourceInfo) =>
132+
quietly(async () => {
133+
const { name, cache, url } = await entry(stored, "info");
134+
await cache.put(url, new Response(JSON.stringify(info)));
135+
used(name);
136+
});
137+
138+
/** `frame` names one picture of the source: its fit, size and the time it was asked for. */
139+
export const readStoredFrame = (stored: StoredSource, frame: string) =>
140+
quietly(async (): Promise<StoredFrame | undefined> => {
141+
const found = await storedEntry(stored, `frame?${encodeURIComponent(frame)}`);
142+
if (!found) return undefined;
143+
const { name, cache, url } = found;
144+
const response = await cache.match(url);
145+
const decodedAt = Number(response?.headers.get("x-decoded-at"));
146+
if (!response || !Number.isFinite(decodedAt)) return undefined;
147+
used(name);
148+
return { blob: await response.blob(), decodedAt };
149+
});
150+
151+
export const storeFrame = (stored: StoredSource, frame: string, decodedAt: number, blob: Blob) =>
152+
quietly(async () => {
153+
const { name, cache, url } = await entry(stored, `frame?${encodeURIComponent(frame)}`);
154+
const headers = { "content-type": blob.type, "x-decoded-at": String(decodedAt) };
155+
await cache.put(url, new Response(blob, { headers }));
156+
used(name, blob.size);
157+
await dropLeastUsed(STORED_THUMBNAIL_BYTES);
158+
});
159+
160+
/** Whole sources go, least recently used first, until what is stored fits `budgetBytes`. */
161+
async function dropLeastUsed(budgetBytes: number): Promise<void> {
162+
const saved = loadIndex();
163+
let total = Object.values(saved.caches).reduce((sum, { bytes }) => sum + bytes, 0);
164+
const oldestFirst = Object.entries(saved.caches).sort(([, a], [, b]) => a.usedAt - b.usedAt);
165+
for (const [name, { bytes }] of oldestFirst) {
166+
if (total <= budgetBytes) break;
167+
await caches.delete(name);
168+
delete saved.caches[name];
169+
total -= bytes;
170+
}
171+
saveIndexSoon();
172+
}
173+
174+
/** Tests only: forget the in-memory index and any pending save. */
175+
export function resetStoredThumbnailsForTests(): void {
176+
clearTimeout(saveTimer);
177+
saveTimer = undefined;
178+
index = undefined;
179+
warned = false;
180+
}

‎packages/studio/src/player/lib/thumbnailSourcePool.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ interface OpenedSource {
1212
mediabunny: Mediabunny;
1313
track: InputVideoTrack;
1414
info: SourceInfo;
15+
etag: string | undefined;
1516
}
1617

1718
export interface ThumbnailSource extends OpenedSource {
@@ -88,7 +89,8 @@ async function open(source: string, pooled: () => PooledSource): Promise<OpenedS
8889
}
8990
const metadataDuration = await track.getDurationFromMetadata({ skipLiveWait: true });
9091
live();
91-
return { mediabunny, track, info: { aspect: displayWidth / displayHeight, metadataDuration } };
92+
const info = { aspect: displayWidth / displayHeight, metadataDuration };
93+
return { mediabunny, track, info, etag: options.etagOf() };
9294
}
9395

9496
function pooledSource(source: string, version: string | undefined): PooledSource {

0 commit comments

Comments
 (0)