Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: optimize video galleries by removing per-card media pipelines (#10228)

oobaboogaf070971da12a
diff --git a/studio/backend/core/inference/video_gallery.py b/studio/backend/core/inference/video_gallery.py
index a5b81839ea4..f5c39afce75 100644
--- a/studio/backend/core/inference/video_gallery.py
+++ b/studio/backend/core/inference/video_gallery.py
@@ -29,6 +29,7 @@ logger = get_logger(__name__)
_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
_JOB_OUTCOME_KEY = "_worker_outcome"
_job_lock = threading.Lock()
+_THUMBNAIL_WIDTH = 192
def gallery_dir() -> Path:
@@ -196,8 +197,9 @@ def _thumbnail_webp(path: Path) -> bytes:
import io
try:
import av
- except Exception as exc: # noqa: BLE001 -- no PyAV -> no thumbnail
- raise RuntimeError("Thumbnail generation needs the 'av' package (PyAV).") from exc
+ from PIL import Image
+ except Exception as exc: # noqa: BLE001 -- a missing decoder dependency makes thumbnails unavailable
+ raise RuntimeError("Thumbnail generation needs the 'av' and 'Pillow' packages.") from exc
try:
with av.open(str(path)) as src:
if not src.streams.video:
@@ -205,8 +207,15 @@ def _thumbnail_webp(path: Path) -> bytes:
frame = next(src.decode(src.streams.video[0]), None)
if frame is None:
raise RuntimeError("Thumbnail generation failed: the clip has no decodable frames.")
+ image = frame.to_image()
+ if image.width > _THUMBNAIL_WIDTH:
+ scale = _THUMBNAIL_WIDTH / image.width
+ image = image.resize(
+ (max(1, round(image.width * scale)), max(1, round(image.height * scale))),
+ Image.LANCZOS,
+ )
buf = io.BytesIO()
- frame.to_image().save(buf, format = "WEBP", quality = 85, method = 4)
+ image.save(buf, format = "WEBP", quality = 85, method = 4)
return buf.getvalue()
except RuntimeError:
raise
diff --git a/studio/backend/tests/test_video_gallery.py b/studio/backend/tests/test_video_gallery.py
index cea584f90b0..7a5f0a00d9b 100644
--- a/studio/backend/tests/test_video_gallery.py
+++ b/studio/backend/tests/test_video_gallery.py
@@ -314,7 +314,7 @@ def test_save_leaves_no_orphan_mp4_when_sidecar_publish_fails(monkeypatch):
def _real_mp4_bytes(
frames: int = 8,
- size: int = 32,
+ size: int | tuple[int, int] = 32,
rate: int = 8,
) -> bytes:
# A real tiny MP4 for the transcode tests: flat-color frames in mpeg4 (bundled in every PyAV build, unlike libx264).
@@ -325,12 +325,13 @@ def _real_mp4_bytes(
buf = io.BytesIO()
with av.open(buf, "w", format = "mp4") as out:
stream = out.add_stream("mpeg4", rate = rate)
- stream.width = size
- stream.height = size
+ width, height = size if isinstance(size, tuple) else (size, size)
+ stream.width = width
+ stream.height = height
stream.pix_fmt = "yuv420p"
for i in range(frames):
frame = av.VideoFrame.from_ndarray(
- np.full((size, size, 3), (i * 30) % 256, dtype = np.uint8), format = "rgb24"
+ np.full((height, width, 3), (i * 30) % 256, dtype = np.uint8), format = "rgb24"
)
for packet in stream.encode(frame):
out.mux(packet)
@@ -488,6 +489,20 @@ def test_thumbnail_produces_a_webp_from_the_video():
assert image.size == (64, 64)
+def test_thumbnail_scales_large_frames_to_gallery_width():
+ import io
+
+ Image = pytest.importorskip("PIL.Image")
+ record = gallery.save(_real_mp4_bytes(frames = 1, size = (320, 180)), _meta())
+
+ with Image.open(io.BytesIO(gallery.thumbnail(record["id"]))) as image:
+ assert image.size == (192, 108)
+
+ portrait = gallery.save(_real_mp4_bytes(frames = 1, size = (320, 568)), _meta())
+ with Image.open(io.BytesIO(gallery.thumbnail(portrait["id"]))) as image:
+ assert image.size == (192, 341)
+
+
def test_thumbnail_rejects_unowned_and_invalid_videos():
assert gallery.thumbnail("does-not-exist") is None
record = gallery.save(_mp4(), _meta())
diff --git a/studio/frontend/src/features/settings/components/archived-media-dialog.tsx b/studio/frontend/src/features/settings/components/archived-media-dialog.tsx
index f3704b82965..d0a01e677a6 100644
--- a/studio/frontend/src/features/settings/components/archived-media-dialog.tsx
+++ b/studio/frontend/src/features/settings/components/archived-media-dialog.tsx
@@ -24,10 +24,11 @@ import {
} from "@/features/images/api";
import {
deleteGalleryVideo,
- fetchGalleryVideoSignedUrl,
+ fetchGalleryVideoThumbnail,
getVideoGallery,
setGalleryVideoFlags,
} from "@/features/video/api";
+import { videoThumbnailQueue } from "@/features/video/thumbnail-request-queue";
import { BlobUrlCache } from "@/lib/blob-url-cache";
import { notifyGalleryChanged } from "@/lib/gallery-flags";
import { toast } from "@/lib/toast";
@@ -111,9 +112,8 @@ export function ArchivedMediaView({ kind }: { kind: ArchivedMediaKind }) {
const [hasMore, setHasMore] = useState(false);
const [loading, setLoading] = useState(true);
const [thumbs, setThumbs] = useState<Record<string, string>>({});
- // Archived PNGs are full-size generated images, so "Show more" a few times would pin hundreds of
- // MB if every blob were held to unmount. Budget them like the main gallery does. Images only: a
- // clip uses a signed link, which is not an object URL and must not be revoked.
+ // Archived images and video posters are object URLs, so "Show more" a few times would otherwise
+ // pin their bytes until unmount. Budget them like the main galleries do.
const blobs = useRef(new BlobUrlCache(ARCHIVED_THUMB_BUDGET_BYTES));
// Only rows on screen fetch a thumbnail, and only rows off screen are evicted. Together those
// two rules keep memory bounded without ever blanking a row the user is looking at.
@@ -279,8 +279,10 @@ export function ArchivedMediaView({ kind }: { kind: ArchivedMediaKind }) {
if ((failures.current.get(row.id) ?? 0) > THUMB_RETRY_LIMIT) continue;
requested.current.add(row.id);
try {
- if (isImages) {
- const { url, bytes } = await fetchGalleryObjectUrl(row.url);
+ if (isImages || kind === "videos") {
+ const { url, bytes } = isImages
+ ? await fetchGalleryObjectUrl(row.url)
+ : await videoThumbnailQueue.run(() => fetchGalleryVideoThumbnail(row.id));
// Dropped from the list, or the dialog closed: there is no row left to show it on,
// and caching it after the unmount sweep would leak the blob.
if (!alive.current || !rowsRef.current.some((r) => r.id === row.id)) {
@@ -308,15 +310,6 @@ export function ArchivedMediaView({ kind }: { kind: ArchivedMediaKind }) {
if (cancelled) return;
continue;
}
- // A clip is a short-lived signed link, not a blob: nothing to budget or revoke.
- const src = await fetchGalleryVideoSignedUrl(row.id);
- if (!alive.current || !rowsRef.current.some((r) => r.id === row.id)) {
- requested.current.delete(row.id);
- return;
- }
- failures.current.delete(row.id);
- setThumbs((prev) => ({ ...prev, [row.id]: src }));
- if (cancelled) return;
} catch {
// A missing thumbnail still leaves a usable, actionable row, so a failure is not fatal.
// Schedule the retry rather than only clearing the flag, which nothing would act on.
@@ -334,7 +327,7 @@ export function ArchivedMediaView({ kind }: { kind: ArchivedMediaKind }) {
return () => {
cancelled = true;
};
- }, [rows, isImages, isAudio, visible, retryTick]);
+ }, [rows, isImages, isAudio, kind, visible, retryTick]);
// Drop a row, then top the page back up if that emptied it while more remain, so the list never
// dead-ends with rows still unreachable behind a hidden "Show more".
@@ -475,18 +468,7 @@ export function ArchivedMediaView({ kind }: { kind: ArchivedMediaKind }) {
className="size-4 text-muted-foreground"
/>
) : thumbs[row.id] ? (
- isImages ? (
- <img src={thumbs[row.id]} alt="" className="size-full object-cover" />
- ) : (
- // Muted metadata-only poster, same treatment as the filmstrip cards.
- <video
- src={thumbs[row.id]}
- muted={true}
- playsInline={true}
- preload="metadata"
- className="size-full object-cover"
- />
- )
+ <img src={thumbs[row.id]} alt="" className="size-full object-cover" />
) : null}
</span>
<span className="min-w-0 flex-1 truncate" title={row.prompt}>
diff --git a/studio/frontend/src/features/video/api.ts b/studio/frontend/src/features/video/api.ts
index 5c5eb7f87d4..d0a6f326f24 100644
--- a/studio/frontend/src/features/video/api.ts
+++ b/studio/frontend/src/features/video/api.ts
@@ -372,6 +372,21 @@ export async function fetchGalleryVideoSignedUrl(id: string): Promise<string> {
return apiUrl(body.url);
}
+/** A still WebP poster for a gallery clip. The endpoint is bearer-gated, so keep
+ * the bytes in a revocable object URL instead of assigning its path to an img. */
+export async function fetchGalleryVideoThumbnail(
+ id: string,
+): Promise<{ url: string; bytes: number }> {
+ const res = await authFetch(
+ `/v1/videos/${encodeURIComponent(id)}/content?variant=thumbnail`,
+ );
+ if (!res.ok) throw new Error(await readFastApiError(res));
+ const blob = await res.blob();
+ // An empty 200 would cache a card that can never render, and the cache hit ends every retry.
+ if (blob.size === 0) throw new Error("The thumbnail response was empty.");
+ return { url: URL.createObjectURL(blob), bytes: blob.size };
+}
+
/** Server-side transcode for the Download menu (WebM / GIF). The backend 501s with a readable
* message when the codec is unavailable. */
export async function fetchGalleryVideoExport(
diff --git a/studio/frontend/src/features/video/thumbnail-request-queue.ts b/studio/frontend/src/features/video/thumbnail-request-queue.ts
new file mode 100644
index 00000000000..6ca5cf9ac19
--- /dev/null
+++ b/studio/frontend/src/features/video/thumbnail-request-queue.ts
@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+/** Backend poster generation opens and decodes a video, so visible cards must not fan out into an
+ * unbounded burst. This queue is shared by the active and archived galleries. */
+export const VIDEO_THUMBNAIL_CONCURRENCY = 3;
+
+interface WaitingTask {
+ start: () => void;
+}
+
+export class ThumbnailRequestQueue {
+ private readonly limit: number;
+ private readonly waiting: WaitingTask[] = [];
+ private activeCount = 0;
+
+ constructor(limit = VIDEO_THUMBNAIL_CONCURRENCY) {
+ this.limit = Math.max(1, Math.floor(limit));
+ }
+
+ run<T>(task: () => Promise<T>): Promise<T> {
+ const result = new Promise<T>((resolve, reject) => {
+ this.waiting.push({
+ start: () => {
+ Promise.resolve()
+ .then(task)
+ .then(resolve, reject)
+ .finally(() => {
+ this.activeCount -= 1;
+ this.pump();
+ });
+ },
+ });
+ });
+ this.pump();
+ return result;
+ }
+
+ get active(): number {
+ return this.activeCount;
+ }
+
+ get pending(): number {
+ return this.waiting.length;
+ }
+
+ private pump(): void {
+ while (this.activeCount < this.limit) {
+ const next = this.waiting.shift();
+ if (!next) {
+ return;
+ }
+ this.activeCount += 1;
+ next.start();
+ }
+ }
+}
+
+export const videoThumbnailQueue = new ThumbnailRequestQueue();
+
+// Same policy the archived view applies to its rows: a backend that blinked must not leave a
+// perfectly decodable clip on the undecodable marker for the rest of the session, and a clip that
+// really cannot be decoded must stop asking.
+export const VIDEO_THUMBNAIL_RETRY_LIMIT = 2;
+export const VIDEO_THUMBNAIL_RETRY_DELAY_MS = 750;
+
+/** Run ``attempt`` until it resolves, retrying a rejection with a linear backoff. Rethrows the last
+ * error once the retries are spent, which is the only outcome the caller may treat as permanent. */
+export async function withThumbnailRetries<T>(
+ attempt: () => Promise<T>,
+ limit = VIDEO_THUMBNAIL_RETRY_LIMIT,
+ delayMs = VIDEO_THUMBNAIL_RETRY_DELAY_MS,
+): Promise<T> {
+ for (let tries = 0; ; tries += 1) {
+ try {
+ return await attempt();
+ } catch (error) {
+ if (tries >= limit) {
+ throw error;
+ }
+ await new Promise((resolve) =>
+ setTimeout(resolve, delayMs * (tries + 1)),
+ );
+ }
+ }
+}
diff --git a/studio/frontend/src/features/video/video-page.tsx b/studio/frontend/src/features/video/video-page.tsx
index 73a00409b35..cb333edbb92 100644
--- a/studio/frontend/src/features/video/video-page.tsx
+++ b/studio/frontend/src/features/video/video-page.tsx
@@ -136,6 +136,7 @@ import {
} from "@/lib/native-files";
import { toast } from "@/lib/toast";
import { subscribeModelEjected } from "@/lib/model-lifecycle-events";
+import { BlobUrlCache } from "@/lib/blob-url-cache";
import { MATCH_SOURCE_RESOLUTION, matchedCanvas } from "./keyframe-canvas";
import { hasReferenceCapacity } from "./reference-budget";
@@ -166,6 +167,7 @@ import {
setGalleryVideoFlags,
fetchGalleryVideoExport,
fetchGalleryVideoSignedUrl,
+ fetchGalleryVideoThumbnail,
generateVideo,
getVideoGallery,
getVideoGenerateProgress,
@@ -175,6 +177,7 @@ import {
loadVideoModel,
unloadVideoModel,
} from "./api";
+import { videoThumbnailQueue, withThumbnailRetries } from "./thumbnail-request-queue";
// Curated models come from the shared catalog, one group per model with a format second level
// (which also surfaces LTX-2.3 in Recommended). Host-dependent: a Mac gets only GGUF rows.
@@ -217,8 +220,8 @@ const FALLBACK_FRAME_OFFSET = 1;
const FALLBACK_FPS = 24;
const FALLBACK_DURATION_TARGETS = [1, 2, 3, 5];
-// Module cache of the backend-persisted gallery, so a tab switch re-renders instantly. The
-// srcById entries are short-lived signed links, not object URLs: nothing is pinned.
+// Module cache of the backend-persisted gallery, so a tab switch re-renders instantly. Playback
+// uses short-lived signed links; still posters use byte-budgeted object URLs.
const galleryCache: {
videos: GalleryVideo[];
hasMore: boolean;
@@ -228,6 +231,9 @@ const galleryCache: {
// is per-process while this cache survives navigation, so an entry has to be re-mintable or
// playback would 401 until a reload.
srcById: Map<string, { url: string; mintedAt: number }>;
+ thumbnailById: BlobUrlCache;
+ thumbnailInflight: Map<string, Promise<boolean>>;
+ thumbnailFailed: Set<string>;
// Ids re-minted once after a media error already, so a clip broken for any other reason cannot
// spin in a mint/error loop.
refreshed: Set<string>;
@@ -246,6 +252,9 @@ const galleryCache: {
selectedId: null,
quant: null,
srcById: new Map(),
+ thumbnailById: new BlobUrlCache(32 * 1024 * 1024),
+ thumbnailInflight: new Map(),
+ thumbnailFailed: new Set(),
refreshed: new Set(),
inflight: new Set(),
deleted: new Set(),
@@ -989,7 +998,7 @@ function VideoGenerator({
onScroll: onSettingsScroll,
className: settingsFadeClass,
} = useScrollFades();
- // Records come from the backend (durable); srcById maps each id to its object URL.
+ // Records come from the backend (durable); playback links and poster object URLs are cached separately.
const [videos, setVideos] = useState<GalleryVideo[]>(() => galleryCache.videos);
const [hasMore, setHasMore] = useState(() => galleryCache.hasMore);
const [selectedId, setSelectedId] = useState<string | null>(() => galleryCache.selectedId);
@@ -1016,6 +1025,13 @@ function VideoGenerator({
const [srcById, setSrcById] = useState<Record<string, string>>(() =>
Object.fromEntries([...galleryCache.srcById].map(([id, e]) => [id, e.url])),
);
+ const [thumbnailById, setThumbnailById] = useState<Record<string, string>>(() =>
+ galleryCache.thumbnailById.toRecord(),
+ );
+ const [thumbnailFailedIds, setThumbnailFailedIds] = useState<ReadonlySet<string>>(
+ () => new Set(galleryCache.thumbnailFailed),
+ );
+ const visibleThumbnailIds = useRef(new Set<string>());
// Guards a "load more" so a fast scroll cannot fire several at once.
const loadingMore = useRef(false);
// False once the page truly unmounts. The page stays mounted across tab switches, so a switch does NOT flip this.
@@ -1494,6 +1510,90 @@ function VideoGenerator({
}
}, []);
+ // The selected clip's card is usually off-strip, so its poster is the coldest and evicts first.
+ const protectedThumbnailIds = useCallback((extra?: string) => {
+ const keep = new Set(visibleThumbnailIds.current);
+ if (galleryCache.selectedId) keep.add(galleryCache.selectedId);
+ if (extra) keep.add(extra);
+ return keep;
+ }, []);
+
+ // On visibility too: a fully cached strip fetches nothing, so a fetch-only prune never ran.
+ const pruneThumbnails = useCallback(() => {
+ const evicted = galleryCache.thumbnailById.prune(protectedThumbnailIds());
+ if (evicted.length === 0 || !isMounted.current) return;
+ setThumbnailById((prev) => {
+ const next = { ...prev };
+ for (const id of evicted) delete next[id];
+ return next;
+ });
+ }, [protectedThumbnailIds]);
+
+ const ensureThumbnail = useCallback((video: GalleryVideo): Promise<boolean> => {
+ const cached = galleryCache.thumbnailById.get(video.id);
+ if (cached) {
+ galleryCache.thumbnailById.touch(video.id);
+ return Promise.resolve(true);
+ }
+ if (galleryCache.thumbnailFailed.has(video.id)) return Promise.resolve(false);
+ const existing = galleryCache.thumbnailInflight.get(video.id);
+ if (existing) return existing;
+ const epochAtStart = galleryCache.epoch;
+ // Deletion and clear can happen while this request is queued or backing off. Skip the decoder
+ // entirely once its result no longer has a gallery record to attach to.
+ const stale = () => galleryCache.deleted.has(video.id) || galleryCache.epoch !== epochAtStart;
+ const request = (async () => {
+ try {
+ // Retried, because the marker below is permanent for the session: without this a single
+ // connection blip would leave a decodable clip on the undecodable icon until a reload.
+ const fetched = await withThumbnailRetries(() =>
+ videoThumbnailQueue.run(() =>
+ stale() ? Promise.resolve(null) : fetchGalleryVideoThumbnail(video.id),
+ ),
+ );
+ if (!fetched) return false;
+ if (stale()) {
+ URL.revokeObjectURL(fetched.url);
+ return false;
+ }
+ galleryCache.thumbnailById.set(video.id, fetched.url, fetched.bytes);
+ // Unprotected, a poster bigger than the budget evicts every neighbour, then itself.
+ const evicted = galleryCache.thumbnailById.prune(protectedThumbnailIds(video.id));
+ if (isMounted.current) {
+ setThumbnailById((prev) => {
+ const next = { ...prev, [video.id]: fetched.url };
+ for (const id of evicted) delete next[id];
+ return next;
+ });
+ }
+ return true;
+ } catch {
+ galleryCache.thumbnailFailed.add(video.id);
+ if (isMounted.current) {
+ setThumbnailFailedIds(new Set(galleryCache.thumbnailFailed));
+ }
+ return false;
+ } finally {
+ galleryCache.thumbnailInflight.delete(video.id);
+ }
+ })();
+ galleryCache.thumbnailInflight.set(video.id, request);
+ return request;
+ }, [protectedThumbnailIds]);
+
+ // Terminal: ensureThumbnail's cache hit ends later attempts, and refetching rejected bytes spins.
+ const handlePosterError = useCallback((id: string) => {
+ galleryCache.thumbnailById.delete(id);
+ galleryCache.thumbnailFailed.add(id);
+ if (!isMounted.current) return;
+ setThumbnailById((prev) => {
+ const next = { ...prev };
+ delete next[id];
+ return next;
+ });
+ setThumbnailFailedIds(new Set(galleryCache.thumbnailFailed));
+ }, []);
+
// A media error on a playing clip means its link died early (the server restarted, changing
// its signing secret). Re-mint once per clip per session.
const remintSrc = useCallback(
@@ -1506,22 +1606,37 @@ function VideoGenerator({
[ensureSrc],
);
- // A card's poster frame appears once its src lands and each src costs a request, so minting a
- // full page up front would queue PAGE_SIZE requests ahead of the clip being waited on.
- // Mint as a card nears the viewport, per page.
+ // Load a still poster as a card nears the viewport. A video element per card makes WebKit create
+ // a decoder, source, video queue and audio queue for every clip, even with preload="metadata".
const stripRef = useRef<HTMLDivElement | null>(null);
useEffect(() => {
const root = stripRef.current;
if (!root || typeof IntersectionObserver === "undefined") return;
+ // disconnect() delivers no final entry, so a resynced-away id protects its blob forever.
+ const listed = new Set(videos.map((v) => v.id));
+ let stranded = false;
+ for (const id of visibleThumbnailIds.current) {
+ if (listed.has(id)) continue;
+ visibleThumbnailIds.current.delete(id);
+ stranded = true;
+ }
+ if (stranded) pruneThumbnails();
const io = new IntersectionObserver(
(entries) => {
+ let left = false;
for (const entry of entries) {
- if (!entry.isIntersecting) continue;
const id = (entry.target as HTMLElement).dataset.clipId;
if (!id) continue;
+ if (!entry.isIntersecting) {
+ if (visibleThumbnailIds.current.delete(id)) left = true;
+ continue;
+ }
+ visibleThumbnailIds.current.add(id);
+ galleryCache.thumbnailById.touch(id);
const clip = videos.find((v) => v.id === id);
- if (clip) void ensureSrc(clip);
+ if (clip) void ensureThumbnail(clip);
}
+ if (left) pruneThumbnails();
},
// rootMargin is added to the ROOT box only, so the root has to be the strip itself: a card
// past its right edge is clipped. The strip scrolls horizontally, so sideways is what counts.
@@ -1529,15 +1644,14 @@ function VideoGenerator({
);
for (const card of root.querySelectorAll("[data-clip-id]")) io.observe(card);
return () => io.disconnect();
- }, [videos, ensureSrc]);
+ }, [videos, ensureThumbnail, pruneThumbnails]);
// The preview player is what the user watches, so the selected clip is fetched whether or not its card is on screen.
useEffect(() => {
if (!selected) return;
- void (async () => {
- await ensureSrc(selected);
- })();
- }, [selected, ensureSrc]);
+ void ensureThumbnail(selected);
+ void ensureSrc(selected);
+ }, [selected, ensureSrc, ensureThumbnail]);
// Bumped by every LOCAL change to the strip. A resync started before one holds a snapshot the
// server listing cannot reconcile with what the user just did, so it drops it.
@@ -1562,18 +1676,23 @@ function VideoGenerator({
);
if (!page) return;
pageEpoch.current += 1;
+ // Otherwise permanent: one backend restart during an open bricks the whole window.
+ if (galleryCache.thumbnailFailed.size > 0) {
+ galleryCache.thumbnailFailed.clear();
+ setThumbnailFailedIds(new Set());
+ }
galleryCache.videos = page.videos;
galleryCache.hasMore = page.has_more;
setVideos(page.videos);
setHasMore(page.has_more);
- // No visibility signal without IntersectionObserver (jsdom / old webview), so keep the eager fetch there.
+ // No visibility signal without IntersectionObserver (jsdom / old webview), so keep the eager poster fetch there.
if (typeof IntersectionObserver === "undefined") {
- page.videos.forEach((video) => void ensureSrc(video));
+ page.videos.forEach((video) => void ensureThumbnail(video));
}
} catch {
// Best-effort: a failed gallery load should not block the page.
}
- }, [ensureSrc]);
+ }, [ensureThumbnail]);
const loadMore = useCallback(async () => {
if (loadingMore.current || !galleryCache.hasMore) return;
@@ -1599,14 +1718,14 @@ function VideoGenerator({
galleryCache.hasMore = page.has_more;
setHasMore(page.has_more);
if (typeof IntersectionObserver === "undefined") {
- page.videos.forEach((video) => void ensureSrc(video));
+ page.videos.forEach((video) => void ensureThumbnail(video));
}
} catch {
// transient; the user can scroll again to retry
} finally {
loadingMore.current = false;
}
- }, [ensureSrc]);
+ }, [ensureThumbnail]);
// WebM/GIF go through a server-side transcode that can take seconds (and 501s when the codec
// is missing), so wrap the helper with toasts.
@@ -1634,8 +1753,11 @@ function VideoGenerator({
// Drop a clip from the strip. `discardLink` is for a real delete: the bytes are gone, so the
// cached link must go and any mint in flight must discard. An archived clip keeps both.
const dropFromStrip = useCallback((id: string, discardLink: boolean) => {
+ visibleThumbnailIds.current.delete(id);
if (discardLink) {
galleryCache.srcById.delete(id);
+ galleryCache.thumbnailById.delete(id);
+ galleryCache.thumbnailFailed.delete(id);
galleryCache.refreshed.delete(id);
galleryCache.deleted.add(id);
setSrcById((prev) => {
@@ -1643,6 +1765,12 @@ function VideoGenerator({
delete next[id];
return next;
});
+ setThumbnailById((prev) => {
+ const next = { ...prev };
+ delete next[id];
+ return next;
+ });
+ setThumbnailFailedIds(new Set(galleryCache.thumbnailFailed));
}
stripEpoch.current += 1;
// Read the list from the cache rather than nesting a setSelectedId inside a setVideos
@@ -1708,12 +1836,12 @@ function VideoGenerator({
setVideos(collected);
setHasMore(more);
if (typeof IntersectionObserver === "undefined") {
- collected.forEach((video) => void ensureSrc(video));
+ collected.forEach((video) => void ensureThumbnail(video));
}
return;
}
},
- [ensureSrc],
+ [ensureThumbnail],
);
// This page stays mounted across route changes, so an archive restore would not reach the
@@ -1834,6 +1962,11 @@ function VideoGenerator({
try {
await clearVideoGallery();
galleryCache.srcById.clear();
+ galleryCache.thumbnailById.clear();
+ galleryCache.thumbnailFailed.clear();
+ // Else a regenerated id joins a promise the epoch below fenced, stranding it on a spinner.
+ galleryCache.thumbnailInflight.clear();
+ visibleThumbnailIds.current.clear();
galleryCache.refreshed.clear();
// Every mint in flight now belongs to a cleared gallery, so their links are discarded on
// arrival. The epoch covers unlisted ids too.
@@ -1843,6 +1976,8 @@ function VideoGenerator({
galleryCache.hasMore = false;
galleryCache.selectedId = null;
setSrcById({});
+ setThumbnailById({});
+ setThumbnailFailedIds(new Set());
setVideos([]);
setHasMore(false);
setSelectedId(null);
@@ -1950,7 +2085,10 @@ function VideoGenerator({
galleryCache.videos.find(
(video) => video.id === galleryCache.selectedId,
) ?? galleryCache.videos[0];
- if (initialSelection) await ensureSrc(initialSelection);
+ if (initialSelection) {
+ void ensureThumbnail(initialSelection);
+ await ensureSrc(initialSelection);
+ }
})(),
]);
if (cancelled || initialReadySent.current) return;
@@ -1960,7 +2098,7 @@ function VideoGenerator({
return () => {
cancelled = true;
};
- }, [active, ensureSrc, loadGallery, onInitialReady, refreshStatus]);
+ }, [active, ensureSrc, ensureThumbnail, loadGallery, onInitialReady, refreshStatus]);
// Ejected from the loaded models indicator, which does not run handleUnload: without this the
// controls keep offering to generate on a freed runtime. So: handleUnload minus the unload.
@@ -2112,6 +2250,7 @@ function VideoGenerator({
sortGalleryItems([clip, ...prev.filter((v) => v.id !== clip.id)]),
);
setSelectedId(clip.id);
+ void ensureThumbnail(clip);
void ensureSrc(clip);
}
} else if (p.phase === "failed") {
@@ -2143,7 +2282,7 @@ function VideoGenerator({
};
document.addEventListener("visibilitychange", genVisibilityListener.current);
genPollTimer.current = setInterval(() => void pollGenerateOnce(), 300);
- }, [ensureSrc, stopGenPoll]);
+ }, [ensureSrc, ensureThumbnail, stopGenPoll]);
useEffect(() => {
void (async () => {
@@ -2180,6 +2319,7 @@ function VideoGenerator({
setVideos((prev) =>
prev.some((v) => v.id === clip.id) ? prev : sortGalleryItems([clip, ...prev]),
);
+ void ensureThumbnail(clip);
void ensureSrc(clip);
}
} else if (g.phase === "failed") {
@@ -2197,7 +2337,7 @@ function VideoGenerator({
stopGenPoll();
dismissLoadToast();
};
- }, [refreshStatus, dismissLoadToast, pollLoadProgress, startGenPoll, stopGenPoll, ensureSrc, cancelLoadFromToast]);
+ }, [refreshStatus, dismissLoadToast, pollLoadProgress, startGenPoll, stopGenPoll, ensureSrc, ensureThumbnail, cancelLoadFromToast]);
// Keep the snapshot helper stable: route effects depend on loadOrStage.
const loadControlsRef = useRef({
@@ -4060,16 +4200,20 @@ function VideoGenerator({
onClick={() => setSelectedId(video.id)}
className="relative flex size-full flex-col justify-end overflow-hidden rounded-[10px] bg-muted/40 outline-none ring-1 ring-transparent transition-shadow hover:ring-border focus-visible:ring-2 focus-visible:ring-ring"
>
- {srcById[video.id] ? (
- // Muted, preload="metadata" so the first frame renders as a poster without playing every card.
- <video
- src={srcById[video.id]}
- muted
- playsInline
- preload="metadata"
- onError={() => remintSrc(video)}
+ {thumbnailById[video.id] ? (
+ <img
+ src={thumbnailById[video.id]}
+ alt=""
+ onError={() => handlePosterError(video.id)}
className="absolute inset-0 size-full object-cover"
/>
+ ) : thumbnailFailedIds.has(video.id) ? (
+ <span className="absolute inset-0 flex items-center justify-center">
+ <HugeiconsIcon
+ icon={FlimSlateIcon}
+ className="size-4 text-muted-foreground"
+ />
+ </span>
) : (
<span className="absolute inset-0 flex items-center justify-center">
<Spinner className="size-4 text-muted-foreground" />
diff --git a/studio/frontend/tests/video-gallery-thumbnail-load.test.ts b/studio/frontend/tests/video-gallery-thumbnail-load.test.ts
new file mode 100644
index 00000000000..14afb15912e
--- /dev/null
+++ b/studio/frontend/tests/video-gallery-thumbnail-load.test.ts
@@ -0,0 +1,259 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+import {
+ ThumbnailRequestQueue,
+ withThumbnailRetries,
+} from "../src/features/video/thumbnail-request-queue.ts";
+
+const BROKEN_POSTER = /broken poster/;
+
+function source(path: string): string {
+ return readFileSync(
+ fileURLToPath(new URL(path, import.meta.url)),
+ "utf8",
+ ).replace(/\r\n/g, "\n");
+}
+
+function between(text: string, start: string, end: string): string {
+ const from = text.indexOf(start);
+ const to = text.indexOf(end, from + start.length);
+ if (from === -1 || to <= from) {
+ throw new Error(`markers not found: ${start} / ${end}`);
+ }
+ return text.slice(from, to);
+}
+
+test("video gallery tiles use still posters instead of media pipelines", () => {
+ const page = source("../src/features/video/video-page.tsx");
+ const strip = between(
+ page,
+ "{/* In-progress generation: a placeholder tile",
+ "{/* Tail spinner while older pages stream in on scroll.",
+ );
+
+ assert.ok(strip.includes("thumbnailById[video.id]"));
+ assert.ok(strip.includes("<img"));
+ assert.ok(strip.includes("src={thumbnailById[video.id]}"));
+ assert.ok(!strip.includes("<video"));
+ assert.ok(!strip.includes("srcById[video.id]"));
+});
+
+test("selected playback does not depend on poster decoding", () => {
+ const page = source("../src/features/video/video-page.tsx");
+ const selected = between(
+ page,
+ "// The preview player is what the user watches",
+ "// Bumped by every LOCAL change",
+ );
+
+ assert.ok(selected.includes("void ensureThumbnail(selected);"));
+ assert.ok(selected.includes("void ensureSrc(selected);"));
+ assert.ok(page.includes("thumbnailById: new BlobUrlCache(32 * 1024 * 1024)"));
+ assert.ok(page.includes("galleryCache.thumbnailById.clear();"));
+});
+
+function deferred() {
+ let resolve!: () => void;
+ const promise = new Promise<void>((done) => {
+ resolve = done;
+ });
+ return { promise, resolve };
+}
+
+test("video poster requests stay within their decoder concurrency cap", async () => {
+ const queue = new ThumbnailRequestQueue(3);
+ const gates = Array.from({ length: 8 }, deferred);
+ const started: number[] = [];
+ let active = 0;
+ let peak = 0;
+
+ const all = gates.map((gate, index) =>
+ queue.run(async () => {
+ started.push(index);
+ active += 1;
+ peak = Math.max(peak, active);
+ await gate.promise;
+ active -= 1;
+ }),
+ );
+
+ await Promise.resolve();
+ await Promise.resolve();
+ assert.deepEqual(started, [0, 1, 2]);
+ assert.equal(queue.active, 3);
+ assert.equal(queue.pending, 5);
+ for (const gate of gates) {
+ gate.resolve();
+ }
+ await Promise.all(all);
+ assert.equal(peak, 3);
+ assert.equal(queue.active, 0);
+ assert.equal(queue.pending, 0);
+});
+
+test("a failed poster request releases its queue slot", async () => {
+ const queue = new ThumbnailRequestQueue(1);
+ const seen: string[] = [];
+ const failed = queue.run(() => {
+ seen.push("failed");
+ return Promise.reject(new Error("broken poster"));
+ });
+ const recovered = queue.run(() => {
+ seen.push("recovered");
+ return Promise.resolve(7);
+ });
+
+ await assert.rejects(failed, BROKEN_POSTER);
+ assert.equal(await recovered, 7);
+ assert.deepEqual(seen, ["failed", "recovered"]);
+});
+
+test("a poster request that blinked is retried before the clip is called undecodable", async () => {
+ let calls = 0;
+ const poster = await withThumbnailRetries(
+ () =>
+ calls++ < 2
+ ? Promise.reject(new Error("broken poster"))
+ : Promise.resolve("poster"),
+ 2,
+ 0,
+ );
+
+ assert.equal(poster, "poster");
+ assert.equal(calls, 3);
+});
+
+test("a poster request that keeps failing gives up so the tile stops asking", async () => {
+ let calls = 0;
+ const attempt = withThumbnailRetries(
+ () => {
+ calls += 1;
+ return Promise.reject(new Error("broken poster"));
+ },
+ 2,
+ 0,
+ );
+
+ await assert.rejects(attempt, BROKEN_POSTER);
+ assert.equal(calls, 3);
+});
+
+test("only an exhausted poster request marks a clip undecodable", () => {
+ const page = source("../src/features/video/video-page.tsx");
+ const ensure = between(
+ page,
+ "const ensureThumbnail = useCallback(",
+ "// A media error on a playing clip",
+ );
+
+ assert.ok(ensure.includes("withThumbnailRetries(() =>"));
+ assert.match(
+ ensure,
+ /withThumbnailRetries\(\(\) =>[\s\S]*?\} catch \{\s*\n\s*galleryCache\.thumbnailFailed\.add\(video\.id\);/,
+ );
+});
+
+test("video posters are fetched through the authenticated thumbnail route", () => {
+ const api = source("../src/features/video/api.ts");
+ const page = source("../src/features/video/video-page.tsx");
+ const helper = between(
+ api,
+ "export async function fetchGalleryVideoThumbnail(",
+ "/** Server-side transcode",
+ );
+
+ assert.ok(helper.includes("authFetch("));
+ assert.ok(helper.includes("/content?variant=thumbnail`"));
+ assert.ok(helper.includes("URL.createObjectURL(blob)"));
+ assert.ok(page.includes("videoThumbnailQueue.run(() =>"));
+ assert.ok(page.includes("galleryCache.epoch !== epochAtStart"));
+});
+
+test("archived video rows reuse still posters", () => {
+ const archived = source(
+ "../src/features/settings/components/archived-media-dialog.tsx",
+ );
+ assert.ok(archived.includes("fetchGalleryVideoThumbnail(row.id)"));
+ assert.ok(archived.includes("videoThumbnailQueue.run(() =>"));
+ assert.ok(!archived.includes("fetchGalleryVideoSignedUrl"));
+ const row = between(archived, "{rows.map((row) => (", "{hasMore ? (");
+ assert.ok(row.includes("<img"));
+ assert.ok(row.includes("src={thumbs[row.id]}"));
+ assert.ok(!row.includes("<video"));
+});
+
+test("a poster the renderer cannot decode falls back to the slate", () => {
+ const page = source("../src/features/video/video-page.tsx");
+ // A 200 carrying bytes no decoder accepts still populates the cache, and the cache hit at the top
+ // of ensureThumbnail short-circuits every later attempt, so an unhandled decode failure is a
+ // broken tile for the rest of the session. onError has to drop the blob AND mark the clip.
+ const strip = between(
+ page,
+ "{/* In-progress generation: a placeholder tile",
+ "{/* Tail spinner while older pages stream in on scroll.",
+ );
+ assert.ok(strip.includes("onError={() => handlePosterError(video.id)}"));
+ const handler = between(page, "const handlePosterError", "}, []);");
+ assert.ok(handler.includes("galleryCache.thumbnailById.delete(id)"));
+ assert.ok(handler.includes("galleryCache.thumbnailFailed.add(id)"));
+});
+
+test("an empty thumbnail response is a failed attempt, not a blank poster", () => {
+ const helper = between(
+ source("../src/features/video/api.ts"),
+ "export async function fetchGalleryVideoThumbnail",
+ "/** Server-side transcode",
+ );
+ // Minting an object URL for a zero-byte body caches a tile that can never render and never
+ // pressures the LRU, because its accounted size is 0.
+ assert.ok(helper.includes("blob.size === 0"));
+ assert.ok(helper.indexOf("blob.size === 0") < helper.indexOf("URL.createObjectURL(blob)"));
+});
+
+test("the poster budget still binds after cards leave the strip", () => {
+ const page = source("../src/features/video/video-page.tsx");
+ // prune() only ever ran on the success path, so a strip whose visible cards are all cached
+ // issues no further fetches and an over-budget cache is never brought back down.
+ const observer = between(page, "const stripRef = useRef", "// The preview player is what");
+ assert.ok(observer.includes("if (left) pruneThumbnails();"));
+ // A card dropped by a wholesale list replacement unmounts without an observer entry, and
+ // disconnect() delivers none, so its id would protect its blob from eviction forever.
+ assert.ok(observer.includes("const listed = new Set(videos.map((v) => v.id));"));
+ assert.ok(observer.includes("visibleThumbnailIds.current.delete(id)"));
+ assert.ok(observer.includes("if (stranded) pruneThumbnails();"));
+});
+
+test("eviction spares the selected clip and the poster it just fetched", () => {
+ const page = source("../src/features/video/video-page.tsx");
+ const keep = between(page, "const protectedThumbnailIds", "}, []);");
+ // The selected clip's card can be scrolled far off the strip while it plays, which makes its
+ // poster the coldest entry and therefore the first evicted.
+ assert.ok(keep.includes("if (galleryCache.selectedId) keep.add(galleryCache.selectedId);"));
+ assert.ok(keep.includes("if (extra) keep.add(extra);"));
+ // A poster larger than the whole budget would otherwise evict every neighbour on its way to
+ // evicting itself, leaving the card on a spinner and re-downloading the strip on each retrigger.
+ assert.ok(page.includes("prune(protectedThumbnailIds(video.id))"));
+ assert.ok(!page.includes("prune(visibleThumbnailIds.current)"));
+});
+
+test("clearing the gallery drops poster requests still in flight", () => {
+ const page = source("../src/features/video/video-page.tsx");
+ const clear = between(page, "const handleClearAll", "setClearingGallery(false)");
+ // A regenerated id joining a promise fenced by the old epoch resolves false without caching and
+ // without a marker, which strands the card on a spinner with nothing left to retrigger it.
+ assert.ok(clear.includes("galleryCache.thumbnailInflight.clear();"));
+});
+
+test("an explicit gallery load gives the slate another chance", () => {
+ const page = source("../src/features/video/video-page.tsx");
+ const load = between(page, "const loadGallery = useCallback", "setHasMore(page.has_more);");
+ // The marker is permanent for the session, so one backend restart during a single gallery open
+ // would brick every card in the window until the clips were deleted or the gallery cleared.
+ assert.ok(load.includes("galleryCache.thumbnailFailed.clear();"));
+});
diff --git a/tests/studio/test_model_picker_contracts.py b/tests/studio/test_model_picker_contracts.py
index 8b3283b9d24..d30a77b012d 100644
--- a/tests/studio/test_model_picker_contracts.py
+++ b/tests/studio/test_model_picker_contracts.py
@@ -1962,18 +1962,20 @@ def test_staged_download_callbacks_only_answer_their_own_variant():
def test_video_gallery_fetches_clips_as_their_cards_come_into_view():
- """Each gallery record's src is a blob holding the whole MP4 until the page closes, so
- fetching a full page of them up front pinned hundreds of MB (gigabytes across "load more"
- pages) for cards the user may never scroll to. Fetch on visibility instead, and always
- fetch the selected clip, since that is the one the preview player plays."""
+ """A card was a <video> pointed at a signed MP4 link, so a whole page of them made WebKit build
+ a demux and decode pipeline per clip, for cards the user may never scroll to. Cards now draw a
+ still poster fetched as they near the viewport, and only the selected clip mints a playback
+ link, since that is the one the preview player plays."""
src = _read("features/video/video-page.tsx")
assert "new IntersectionObserver(" in src
assert "ref={stripRef}" in src and "data-clip-id={video.id}" in src
assert 'root.querySelectorAll("[data-clip-id]")' in src
# rootMargin applies to the root box only, so the strip (the clipping scroller) must BE the root or the prefetch margin never reaches a clipped card.
assert '{ root, rootMargin: "0px 600px" }' in src
- # The only surviving whole-page fetches are the no-IntersectionObserver fallbacks.
- eager = list(re.finditer(r"page\.videos\.forEach\(\(video\) => void ensureSrc\(video\)\)", src))
+ # A whole page of playback links is what the pipelines were built from, so no path may mint one.
+ assert not re.search(r"forEach\(\(video\) => void ensureSrc\(video\)\)", src)
+ # The only surviving whole-page fetches are the no-IntersectionObserver poster fallbacks.
+ eager = list(re.finditer(r"forEach\(\(video\) => void ensureThumbnail\(video\)\)", src))
assert eager, "the jsdom/old-webview fallback fetch is missing"
for match in eager:
assert (
@@ -1981,7 +1983,8 @@ def test_video_gallery_fetches_clips_as_their_cards_come_into_view():
in src[max(0, match.start() - 260) : match.start()]
)
assert re.search(
- r"if \(!selected\) return;\s*\n\s*void \(async \(\) => \{\s*\n\s*await ensureSrc\(selected\);",
+ r"if \(!selected\) return;\s*\n\s*void ensureThumbnail\(selected\);"
+ r"\s*\n\s*void ensureSrc\(selected\);",
src,
)