BlueGit

timfa filemanager

Document video thumbnail cache behaviour

timfa Tim Falken · pushed by timfa

Authored 2026-05-15 · 6 months ago

Hash
5e969c036ec3887a7fcdf2d10d282d92382842a1
Parent
e6861e10
1 file changed +4 −1
.github/technical-reference.md +4 −1
@@ -6,7 +6,7 @@
6 6 - GET /share/:token - Calls buildShareOpenGraphPage to serve share.html with injected OG meta tags for all visitors; social media crawlers see rich preview data, browsers get the full interactive page.
7 7
8 8 ## server/thumbnail-cache.js
9 - syncThumbnailCacheOnce() - Mirrors configured roots and userPath into public/thumbs and generates 99x99-max WebP thumbnails for image files; removes stale thumbnails and updates manifest hashes while preserving prior cache entries for temporarily unavailable roots (e.g. removable mounts).
9 - syncThumbnailCacheOnce() - Mirrors configured roots and userPath into public/thumbs and generates 99x99-max WebP thumbnails for image files and video files (frame around 10% via ffprobe/ffmpeg); removes stale thumbnails and updates manifest hashes while preserving prior cache entries for temporarily unavailable roots (e.g. removable mounts).
10 10 - startThumbnailCacheLoop() - Schedules cache sync runs 5 seconds after boot and 5 seconds after each run completes.
11 11 - stopThumbnailCacheLoop() - Stops scheduled background cache sync runs.
12 12 - getCachedThumbnailInfo(sourceFile) - Returns cached thumbnail path/content-type when present; null when not ready.
@@ -144,6 +144,7 @@
144 144 - openShareModal(item) - Opens the Delen (share) popup, calls POST /api/share/create, shows the 24-hour URL with a copy button and OK to dismiss.
145 145 - loadThumbnails() - Registers visible file icons for lazy thumbnail loading (both file thumbnails and folder icons); retries missing cache thumbnails during incremental refresh.
146 146 - loadOneThumbnail(iconEl) - Loads thumbnails from server cache endpoint for images, text snapshots for text files, and badges for other files; marks image icons as pending when cache returns 404 and uses direct source SVG thumbnails for SVG files under 1MB.
147 - loadOneThumbnail(iconEl) - Loads thumbnails from server cache endpoint for images and videos, text snapshots for text files, and badges for other files; marks image/video icons as pending when cache returns 404 and uses direct source SVG thumbnails for SVG files under 1MB.
147 148 - observeFolderIcon(iconEl) - Registers a folder icon element with IntersectionObserver for lazy loading.
148 149 - loadOneFolderIcon(iconEl) - Fetches /api/files/folder-icon then the thumbnail blob and overlays it inside the folder SVG; no-op if no icon available.
149 150 - applyFolderThumbnail(iconEl, srcUrl) - Injects an SVG <image> element clipped to the folder outline path into the folder's icon SVG.
@@ -161,6 +162,7 @@
161 162 ## tests/thumbnail-cache.test.js
162 163 - thumbnail cache worker / creates cached thumbnail with dimensions smaller than 100px - Verifies cached image generation and manifest write.
163 164 - thumbnail cache worker / removes cached thumbnail when source file is deleted - Verifies stale thumbnail cleanup behavior.
165 - thumbnail cache worker / creates cached thumbnail for video files using ffmpeg frame extraction - Verifies video thumbnail generation uses ffprobe duration and ffmpeg frame capture.
164 166 - afterEach() cleanup - Removes temp roots with `fs.rmSync(...maxRetries...)` to tolerate transient Windows file locks.
165 167 - detectCodeLanguage(name, mime) - Determines preview language for text/script files by MIME and extension.
166 168 - prettyPrintCode(raw, lang) - Best-effort formatter for JSON/markup/script previews before rendering.
@@ -253,6 +255,7 @@
253 255 - video preview releases the backend stream session when closed - Verifies closing a streamed video preview sends an explicit backend release call.
254 256 - rapid file reselection does not duplicate sidebar action buttons after delayed metadata - Verifies stale sidebar loads are ignored so action buttons are not duplicated.
255 257 - video tiles show centred watched overlays after watched metadata is loaded - Verifies overlays remain absent until watched metadata is fetched, then render as solid eye icons for fully and partway statuses.
258 - shows pending icon spinner when video thumbnail cache is not ready - Verifies video tiles use thumbnail-cache loading (instead of badge fallback) and pending-state UI.
256 259
257 260 ## tests/video-stream.test.js
258 261 - createVideoStreamSession resolves once ffmpeg starts writing stream assets - Verifies session creation no longer waits for the final master playlist before preview can begin.
@@ -6,7 +6,7 @@
6- GET /share/:token - Calls buildShareOpenGraphPage to serve share.html with injected OG meta tags for all visitors; social media crawlers see rich preview data, browsers get the full interactive page.
6- GET /share/:token - Calls buildShareOpenGraphPage to serve share.html with injected OG meta tags for all visitors; social media crawlers see rich preview data, browsers get the full interactive page.
7
7
8## server/thumbnail-cache.js
8## server/thumbnail-cache.js
9- syncThumbnailCacheOnce() - Mirrors configured roots and userPath into public/thumbs and generates 99x99-max WebP thumbnails for image files; removes stale thumbnails and updates manifest hashes while preserving prior cache entries for temporarily unavailable roots (e.g. removable mounts).
9- syncThumbnailCacheOnce() - Mirrors configured roots and userPath into public/thumbs and generates 99x99-max WebP thumbnails for image files and video files (frame around 10% via ffprobe/ffmpeg); removes stale thumbnails and updates manifest hashes while preserving prior cache entries for temporarily unavailable roots (e.g. removable mounts).
10- startThumbnailCacheLoop() - Schedules cache sync runs 5 seconds after boot and 5 seconds after each run completes.
10- startThumbnailCacheLoop() - Schedules cache sync runs 5 seconds after boot and 5 seconds after each run completes.
11- stopThumbnailCacheLoop() - Stops scheduled background cache sync runs.
11- stopThumbnailCacheLoop() - Stops scheduled background cache sync runs.
12- getCachedThumbnailInfo(sourceFile) - Returns cached thumbnail path/content-type when present; null when not ready.
12- getCachedThumbnailInfo(sourceFile) - Returns cached thumbnail path/content-type when present; null when not ready.
@@ -144,6 +144,7 @@
144- openShareModal(item) - Opens the Delen (share) popup, calls POST /api/share/create, shows the 24-hour URL with a copy button and OK to dismiss.
144- openShareModal(item) - Opens the Delen (share) popup, calls POST /api/share/create, shows the 24-hour URL with a copy button and OK to dismiss.
145- loadThumbnails() - Registers visible file icons for lazy thumbnail loading (both file thumbnails and folder icons); retries missing cache thumbnails during incremental refresh.
145- loadThumbnails() - Registers visible file icons for lazy thumbnail loading (both file thumbnails and folder icons); retries missing cache thumbnails during incremental refresh.
146- loadOneThumbnail(iconEl) - Loads thumbnails from server cache endpoint for images, text snapshots for text files, and badges for other files; marks image icons as pending when cache returns 404 and uses direct source SVG thumbnails for SVG files under 1MB.
146- loadOneThumbnail(iconEl) - Loads thumbnails from server cache endpoint for images, text snapshots for text files, and badges for other files; marks image icons as pending when cache returns 404 and uses direct source SVG thumbnails for SVG files under 1MB.
147- loadOneThumbnail(iconEl) - Loads thumbnails from server cache endpoint for images and videos, text snapshots for text files, and badges for other files; marks image/video icons as pending when cache returns 404 and uses direct source SVG thumbnails for SVG files under 1MB.
147- observeFolderIcon(iconEl) - Registers a folder icon element with IntersectionObserver for lazy loading.
148- observeFolderIcon(iconEl) - Registers a folder icon element with IntersectionObserver for lazy loading.
148- loadOneFolderIcon(iconEl) - Fetches /api/files/folder-icon then the thumbnail blob and overlays it inside the folder SVG; no-op if no icon available.
149- loadOneFolderIcon(iconEl) - Fetches /api/files/folder-icon then the thumbnail blob and overlays it inside the folder SVG; no-op if no icon available.
149- applyFolderThumbnail(iconEl, srcUrl) - Injects an SVG <image> element clipped to the folder outline path into the folder's icon SVG.
150- applyFolderThumbnail(iconEl, srcUrl) - Injects an SVG <image> element clipped to the folder outline path into the folder's icon SVG.
@@ -161,6 +162,7 @@
161## tests/thumbnail-cache.test.js
162## tests/thumbnail-cache.test.js
162- thumbnail cache worker / creates cached thumbnail with dimensions smaller than 100px - Verifies cached image generation and manifest write.
163- thumbnail cache worker / creates cached thumbnail with dimensions smaller than 100px - Verifies cached image generation and manifest write.
163- thumbnail cache worker / removes cached thumbnail when source file is deleted - Verifies stale thumbnail cleanup behavior.
164- thumbnail cache worker / removes cached thumbnail when source file is deleted - Verifies stale thumbnail cleanup behavior.
165- thumbnail cache worker / creates cached thumbnail for video files using ffmpeg frame extraction - Verifies video thumbnail generation uses ffprobe duration and ffmpeg frame capture.
164- afterEach() cleanup - Removes temp roots with `fs.rmSync(...maxRetries...)` to tolerate transient Windows file locks.
166- afterEach() cleanup - Removes temp roots with `fs.rmSync(...maxRetries...)` to tolerate transient Windows file locks.
165- detectCodeLanguage(name, mime) - Determines preview language for text/script files by MIME and extension.
167- detectCodeLanguage(name, mime) - Determines preview language for text/script files by MIME and extension.
166- prettyPrintCode(raw, lang) - Best-effort formatter for JSON/markup/script previews before rendering.
168- prettyPrintCode(raw, lang) - Best-effort formatter for JSON/markup/script previews before rendering.
@@ -253,6 +255,7 @@
253- video preview releases the backend stream session when closed - Verifies closing a streamed video preview sends an explicit backend release call.
255- video preview releases the backend stream session when closed - Verifies closing a streamed video preview sends an explicit backend release call.
254- rapid file reselection does not duplicate sidebar action buttons after delayed metadata - Verifies stale sidebar loads are ignored so action buttons are not duplicated.
256- rapid file reselection does not duplicate sidebar action buttons after delayed metadata - Verifies stale sidebar loads are ignored so action buttons are not duplicated.
255- video tiles show centred watched overlays after watched metadata is loaded - Verifies overlays remain absent until watched metadata is fetched, then render as solid eye icons for fully and partway statuses.
257- video tiles show centred watched overlays after watched metadata is loaded - Verifies overlays remain absent until watched metadata is fetched, then render as solid eye icons for fully and partway statuses.
258- shows pending icon spinner when video thumbnail cache is not ready - Verifies video tiles use thumbnail-cache loading (instead of badge fallback) and pending-state UI.
256
259
257## tests/video-stream.test.js
260## tests/video-stream.test.js
258- createVideoStreamSession resolves once ffmpeg starts writing stream assets - Verifies session creation no longer waits for the final master playlist before preview can begin.
261- createVideoStreamSession resolves once ffmpeg starts writing stream assets - Verifies session creation no longer waits for the final master playlist before preview can begin.