BlueGit

timfa filemanager

Add subtitle range prefetching

The image subtitle walker now uses dedicated range-prefetch endpoints that return all subtitle frames overlapping a requested time window, allowing the client to cache multiple caption images from one backend call.\n\nAuthenticated and shared video playback now use adaptive range windows tuned for the new model: smaller near playback and larger when already far ahead. Route, client, and parser tests were extended to cover the new range APIs and prefetch path.

timfa Tim Falken · pushed by timfa

Authored 2026-05-27 · 5 months ago

Hash
e3527da641c362ce42b460e7ca60effef2ff8b71
Parent
5b6217e0
12 files changed +578 −52
.github/technical-reference.md +7 −3
@@ -31,7 +31,9 @@
31 31
32 32 ## server/image-subtitles.js
33 33 - parseRenderOptions(options) - Normalises subtitle-frame request options and validates filePath/streamIndex/time/canvas dimensions; stream index `0` is valid and must not be treated as missing; canvas is scaled down within a 1280x720 ceiling, then multiplied by `IMAGE_SUBTITLE_RENDER_SCALE` (default `0.75`) while preserving requested aspect ratio.
34 - parseRenderRangeOptions(options) - Normalises subtitle-range request options and validates filePath/streamIndex/start/end/canvas dimensions for multi-frame walker requests.
34 35 - renderImageSubtitleFrame(options) - Extracts bitmap subtitle streams to cached `.sup`, parses PGS display sets, and returns {frame: PNG buffer, left, top, width, height, canvasWidth, canvasHeight} with metadata for proper client-side upscaling; the server preserves positioning info instead of throwing it away, allowing the client to calculate percentage-based sizing for downscaled frames; cold event-cache builds now continue in the background while requests return quickly with no frame (`null`) until parsing finishes, avoiding long-hanging subtitle frame requests after cache purge; request/build/render timing counters are tracked for debug diagnostics.
36 - renderImageSubtitleFramesInRange(options) - Returns all rendered subtitle frames overlapping a requested [start,end) window, reusing the same event/frame caches as single-frame rendering so the client walker can cache multiple subtitle images per request.
35 37 - clearCachesForFile(filePath) - Removes all event and frame cache entries for a given file path using path-prefixed cache keys, also deletes the corresponding `.sup` file from disk for each evicted event entry; called when video stream sessions end to prevent memory and disk accumulation.
36 38 - pruneOldImageSubtitleCaches(filePath, slowestViewerTimeSeconds) - Drops subtitle frame and event caches once the slowest viewer has passed event end time plus a 5-second grace window (e.g., event ending at 30s is dropped after slowest viewer reaches 35s); runs unconditionally on prune cycles instead of waiting for event-cache byte cap pressure so old subtitle image bytes are released promptly.
37 39 - purgeSubtitleCacheDir() - Removes the entire subtitle `.sup` file cache directory from disk; called once at server startup to clean up any files left over from a previous run.
@@ -145,6 +147,7 @@
145 147 - POST /api/files/copy - Copies a file to a destination folder with conflict strategies (`error`, `overwrite`, `rename`) and user-folder size-limit checks.
146 148 - POST /api/files/video-stream - Creates a short-lived HLS session for a video and returns playlistUrl, durationSeconds, videoWidth, videoHeight, subtitleTracks, imageSubtitleTracks, and subtitleSummary ({total, converted, imageBased, skipped}).
147 149 - GET /api/files/video-stream-subtitle-frame - Authenticated. Renders a PNG subtitle frame for bitmap subtitle tracks via cached PGS decode/composite flow; returns {frame, left, top, width, height, canvasWidth, canvasHeight}; sends response headers X-Subtitle-Frame-{Left,Top,Width,Height,Canvas-Width,Canvas-Height,Start-Time,End-Time} plus X-Subtitle-{Request-Received-At-Ms,Response-Sent-At-Ms} so the client can log subtitle timing against server send time; on failures or no active subtitle it returns 204 so the client can stop retrying.
150 - GET /api/files/video-stream-subtitle-range - Authenticated. Returns JSON {status, startTimeSeconds, endTimeSeconds, frames[]} for all bitmap subtitle events overlapping a requested time window; each frame entry includes placement/canvas metadata plus base64 PNG data so the client walker can cache multiple subtitle images per request.
148 151 - POST /api/files/video-stream-subtitle-log - Authenticated. Accepts batched client-side subtitle timing events for an authorised file and appends them to the local subtitle debug-log cache with file path, username, and stream session context.
149 152 - DELETE /api/files/video-stream/:sessionId - Explicitly releases an active short-lived video stream session and stops backend processing.
150 153 - POST /api/files/watched-statuses - Returns fast per-user watched statuses for up to 500 file paths without triggering expensive metadata/hash work; response is { statuses: { [filePath]: 'fully'|'partway' } }.
@@ -160,6 +163,7 @@
160 163 - GET /api/share/download/:token - Public. Downloads the file or a zip of the directory for a valid token; 410 expired.
161 164 - GET /api/share/video-stream/:token - Public. Creates a short-lived HLS session for a shared video and returns playlistUrl, durationSeconds, subtitleTracks, imageSubtitleTracks, and subtitleSummary ({total, converted, imageBased, skipped}).
162 165 - GET /api/share/video-stream-subtitle-frame/:token - Public. Renders a PNG subtitle frame for shared-video bitmap subtitle tracks using the same cached PGS decode path as the authenticated player; returns the same subtitle timing headers as the authenticated route and 204 with X-Subtitle-Frame-Status when no frame is active or rendering fails.
166 - GET /api/share/video-stream-subtitle-range/:token - Public. Returns the same JSON subtitle-window payload as the authenticated range route for shared-video prefetching.
163 167 - POST /api/share/video-stream-subtitle-log/:token - Public. Accepts batched client-side subtitle timing events for a valid shared-video token and appends them to the local subtitle debug-log cache with share-token and stream-session context.
164 168 - DELETE /api/share/video-stream/session/:sessionId - Public. Explicitly releases a shared HLS lease so the share page can clean up the backend stream session on close/unload instead of waiting for idle expiry.
165 169 - buildShareOpenGraphPage(token, req) - Reads share.html, injects OG meta tags (<og:title>, <og:description>, <og:image> for image files, twitter:card) based on DB lookup of token, and returns the full HTML string. Handles expired and not-found tokens. Exported and used by the /share/:token route in server/index.js.
@@ -199,14 +203,14 @@
199 203 - Standalone public share page served at /share/:token; no auth required.
200 204 - Timer bar - Live HH:MM:SS countdown showing remaining validity; turns red and disables download when expired.
201 205 - tryPreview(name, isDir) - Renders inline preview (img/video/audio/text pre); no-op for unsupported types or directories.
202 - Share video preview - Uses the shared browser video-player helper used by app previews: VOD UI enforcement, long forward buffer, forced caption overrides (text background opacity transparent + text edge style uniform), subtitle/audio track restore/save by matching track names, image-subtitle overlay support (adaptive subtitle prefetch stride: smaller near playback, larger when cache lead is high), background stream-ahead prefetch (session playlist/variant/segment fetches continue towards video end while playback reads cache), seek-bar cache frontier marker (`:`) for walker progress, service-worker-backed HLS segment cache enablement during playback (with per-session cache cleanup on close), and explicit backend session release on unload.
206 - Share video preview - Uses the shared browser video-player helper used by app previews: VOD UI enforcement, long forward buffer, forced caption overrides (text background opacity transparent + text edge style uniform), subtitle/audio track restore/save by matching track names, image-subtitle overlay support (adaptive range-prefetch windows: 3 seconds near playback, up to 10 seconds when cache lead is high), background stream-ahead prefetch (session playlist/variant/segment fetches continue towards video end while playback reads cache), seek-bar cache frontier marker (`:`) for walker progress, service-worker-backed HLS segment cache enablement during playback (with per-session cache cleanup on close), and explicit backend session release on unload.
203 207 - Fetches /api/share/info/:token on load; shows error state for 404/410 responses.
204 208 - Download link points to /api/share/download/:token; labelled "Download als .zip" for directories.
205 209
206 210 ## public/shared-video-player.js
207 211 - applyDefaultTextTrackPrefs() - Writes the default Video.js caption override settings (transparent background, uniform edge style) so all streamed players start from the same text-track baseline.
208 212 - bindTrackPrefs(player, prefs, savePrefs) - Restores subtitle/audio track selections by track name and persists later track changes; shared by the authenticated player and the share page so both resolve track matches the same way.
209 - bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Adds the shared IM button/menu/overlay for bitmap subtitle tracks, restores saved image-subtitle selections, fetches rendered frames through a caller-supplied request builder, keeps a separate rolling lookahead-prefetch worker alive across timeupdates (including gaps where no subtitle is currently visible), supports cache-only foreground playback with `currentFetchEnabled: false` (foreground uses cached frames while walker owns server fetches), supports startup warmup with `initialPrefetchSeconds` (default 60s) so early timeline subtitle frames are requested immediately on player load before playback advances, supports fixed prefetch stride (`prefetchStepSeconds`) and adaptive stride mode (`prefetchAdaptiveStepEnabled` with `prefetchStepSecondsMin`/`prefetchStepSecondsMax`) plus optional adaptive pacing (`prefetchAdaptivePacingEnabled`) to balance cache fill speed against backend request pressure, extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), merges buffered-end signals from both Video.js/player APIs and underlying media buffered ranges so under-reported player values do not cap subtitle prefetch early, keeps the prefetch frontier pinned to at least current playback time so it chases buffered-ahead range instead of replaying stale lag after video/session changes, coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), applies per-request timeouts (`currentRequestTimeoutMs`, `prefetchRequestTimeoutMs`) so hung subtitle frame requests cannot stall updates indefinitely, paces prefetch polling (`prefetchRequestIntervalMs`) to reduce request bursts, logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, caches received subtitle PNG frames client-side for the lifetime of the player session (including prefetched frames) so rewind playback can render from local cache even after server-side purge, ensures force-seek aborts still clear in-flight current-request state so subtitle refreshes continue instead of deadlocking, updates seek-bar bracket markers only after responses resolve (no in-flight jump-back flicker), keeps both marker positions forward-only (never regressing to earlier times), allows the two bracket glyphs to overlap naturally when positions match, advances markers even when responses are 204/no-frame, and disables the track after the first hard failure.
213 - bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Adds the shared IM button/menu/overlay for bitmap subtitle tracks, restores saved image-subtitle selections, fetches rendered frames through a caller-supplied request builder, can optionally use a separate range-prefetch request builder (`buildPrefetchRequest`) so the walker caches multiple subtitle images from one window request, keeps a separate rolling lookahead-prefetch worker alive across timeupdates (including gaps where no subtitle is currently visible), supports cache-only foreground playback with `currentFetchEnabled: false` (foreground uses cached frames while walker owns server fetches), supports startup warmup with `initialPrefetchSeconds` (default 60s) so early timeline subtitle frames are requested immediately on player load before playback advances, supports fixed prefetch stride (`prefetchStepSeconds`) and adaptive stride mode (`prefetchAdaptiveStepEnabled` with `prefetchStepSecondsMin`/`prefetchStepSecondsMax`) plus optional adaptive pacing (`prefetchAdaptivePacingEnabled`) to balance cache fill speed against backend request pressure, extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), merges buffered-end signals from both Video.js/player APIs and underlying media buffered ranges so under-reported player values do not cap subtitle prefetch early, keeps the prefetch frontier pinned to at least current playback time so it chases buffered-ahead range instead of replaying stale lag after video/session changes, coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), applies per-request timeouts (`currentRequestTimeoutMs`, `prefetchRequestTimeoutMs`) so hung subtitle frame requests cannot stall updates indefinitely, paces prefetch polling (`prefetchRequestIntervalMs`) to reduce request bursts, logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, caches received subtitle PNG frames client-side for the lifetime of the player session (including prefetched frames) so rewind playback can render from local cache even after server-side purge, ensures force-seek aborts still clear in-flight current-request state so subtitle refreshes continue instead of deadlocking, updates seek-bar bracket markers only after responses resolve (no in-flight jump-back flicker), keeps both marker positions forward-only (never regressing to earlier times), allows the two bracket glyphs to overlap naturally when positions match, advances markers even when responses are 204/no-frame, and disables the track after the first hard failure.
210 214 - bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Cache-frame time matching now uses a small epsilon window around start/end timestamps to avoid boundary misses; cache-only mode can also perform a throttled direct current-frame fallback fetch on cache miss (`cacheMissFallbackEnabled`, `cacheMissFallbackIntervalMs`) so subtitles recover without waiting for another seek/timeupdate cycle, fallback fetches preserve prefetch progress so repeated cache misses do not keep resetting subtitle lookahead, and duration metadata hints now extend lookahead prefetch to the known video end even before playback advances.
211 215 - bindStreamAheadPrefetch(opts) - Starts a background HLS walker that repeatedly fetches the session playlist, discovers variant playlists and media segments, and prefetches those assets into the browser cache so playback can read already-fetched segments while the backend prunes old files; tracks cached-through timeline progress (primary from playlist segment durations, with filename-based segment-index fallback for `.ts/.m4s` naming and a section-ratio fallback from fetched segments/total discovered segments when absolute timing metadata is missing) and returns a controller with stop()/done()/getStatus()/subscribe().
212 216 - bindStreamAheadSeekMarker(player, streamAheadPrefetch, opts) - Renders a non-interactive `:` marker on the playback seek bar showing how far the stream-ahead walker has cached through the timeline; subscribes to walker progress updates, updates tooltip text with formatted cached-through time, and removes itself on detach.
@@ -295,7 +299,7 @@
295 299 - buildAuthHeaders() - Builds the authenticated fetch headers used by preview-side API calls that need the bearer token plus fingerprint header.
296 300 - renderStreamedVideoPreview(item) - For authenticated video previews, creates a backend stream session and starts the background stream-ahead prefetch worker so playlist/segment requests can continue independently of playback reads until cleanup.
297 301 - bindImageSubtitleOverlay(player, videojs, prefs, session, item) - Adds the fullscreen-safe image-subtitle button, menu, and bottom overlay used to fetch and display subtitle frames for image-based tracks; keeps subtitle bitmaps horizontally centred at the bottom, highlights the currently selected IM menu option, persists per-user image subtitle stream index + track name, restores by saved track name first (then stream index), batches subtitle timing diagnostics to `/api/files/video-stream-subtitle-log`, and reads X-Subtitle-Frame-* headers from server responses to properly upscale downscaled frames while maintaining proportions.
298 - renderStreamedVideoPreview(item, targetEl) - Creates the Video.js player with HLS source/track config, enables service-worker-backed HLS segment caching for the active stream session (and clears that cache on close), enforces non-live playback UI for file streams, uses container-fill sizing to keep previews within bounds, restores per-user video prefs (volume + subtitle/audio track names when present), wires the image-subtitle overlay controller, forces caption overrides on each open (text background opacity transparent + text edge style uniform), reports watch progress, warns when subtitle streams exist but none are web-compatible, releases the backend stream session on close/unload, uses a preview initialisation token guard so stale async player/walker setup from a previously closed preview is discarded immediately, and configures adaptive image-subtitle walker stepping in app playback (1s near playback, up to 5s when far ahead).
302 - renderStreamedVideoPreview(item, targetEl) - Creates the Video.js player with HLS source/track config, enables service-worker-backed HLS segment caching for the active stream session (and clears that cache on close), enforces non-live playback UI for file streams, uses container-fill sizing to keep previews within bounds, restores per-user video prefs (volume + subtitle/audio track names when present), wires the image-subtitle overlay controller, forces caption overrides on each open (text background opacity transparent + text edge style uniform), reports watch progress, warns when subtitle streams exist but none are web-compatible, releases the backend stream session on close/unload, uses a preview initialisation token guard so stale async player/walker setup from a previously closed preview is discarded immediately, and configures adaptive image-subtitle range prefetching in app playback (3s near playback, up to 10s when far ahead).
299 303 - modelPreviewType(name) - Classifies direct client-side 3D preview support for `.stl` and `.obj`.
300 304 - loadThreePreviewModules() - Lazy-loads Three.js plus OrbitControls/STLLoader/OBJLoader via import map aliases.
301 305 - modelThumbnailDataUrl(item, blob) - Builds a blue SVG thumbnail for STL/OBJ files by parsing their geometry client-side; falls back to a badge when parsing fails.
@@ -31,7 +31,9 @@
31
31
32## server/image-subtitles.js
32## server/image-subtitles.js
33- parseRenderOptions(options) - Normalises subtitle-frame request options and validates filePath/streamIndex/time/canvas dimensions; stream index `0` is valid and must not be treated as missing; canvas is scaled down within a 1280x720 ceiling, then multiplied by `IMAGE_SUBTITLE_RENDER_SCALE` (default `0.75`) while preserving requested aspect ratio.
33- parseRenderOptions(options) - Normalises subtitle-frame request options and validates filePath/streamIndex/time/canvas dimensions; stream index `0` is valid and must not be treated as missing; canvas is scaled down within a 1280x720 ceiling, then multiplied by `IMAGE_SUBTITLE_RENDER_SCALE` (default `0.75`) while preserving requested aspect ratio.
34- parseRenderRangeOptions(options) - Normalises subtitle-range request options and validates filePath/streamIndex/start/end/canvas dimensions for multi-frame walker requests.
34- renderImageSubtitleFrame(options) - Extracts bitmap subtitle streams to cached `.sup`, parses PGS display sets, and returns {frame: PNG buffer, left, top, width, height, canvasWidth, canvasHeight} with metadata for proper client-side upscaling; the server preserves positioning info instead of throwing it away, allowing the client to calculate percentage-based sizing for downscaled frames; cold event-cache builds now continue in the background while requests return quickly with no frame (`null`) until parsing finishes, avoiding long-hanging subtitle frame requests after cache purge; request/build/render timing counters are tracked for debug diagnostics.
35- renderImageSubtitleFrame(options) - Extracts bitmap subtitle streams to cached `.sup`, parses PGS display sets, and returns {frame: PNG buffer, left, top, width, height, canvasWidth, canvasHeight} with metadata for proper client-side upscaling; the server preserves positioning info instead of throwing it away, allowing the client to calculate percentage-based sizing for downscaled frames; cold event-cache builds now continue in the background while requests return quickly with no frame (`null`) until parsing finishes, avoiding long-hanging subtitle frame requests after cache purge; request/build/render timing counters are tracked for debug diagnostics.
36- renderImageSubtitleFramesInRange(options) - Returns all rendered subtitle frames overlapping a requested [start,end) window, reusing the same event/frame caches as single-frame rendering so the client walker can cache multiple subtitle images per request.
35- clearCachesForFile(filePath) - Removes all event and frame cache entries for a given file path using path-prefixed cache keys, also deletes the corresponding `.sup` file from disk for each evicted event entry; called when video stream sessions end to prevent memory and disk accumulation.
37- clearCachesForFile(filePath) - Removes all event and frame cache entries for a given file path using path-prefixed cache keys, also deletes the corresponding `.sup` file from disk for each evicted event entry; called when video stream sessions end to prevent memory and disk accumulation.
36- pruneOldImageSubtitleCaches(filePath, slowestViewerTimeSeconds) - Drops subtitle frame and event caches once the slowest viewer has passed event end time plus a 5-second grace window (e.g., event ending at 30s is dropped after slowest viewer reaches 35s); runs unconditionally on prune cycles instead of waiting for event-cache byte cap pressure so old subtitle image bytes are released promptly.
38- pruneOldImageSubtitleCaches(filePath, slowestViewerTimeSeconds) - Drops subtitle frame and event caches once the slowest viewer has passed event end time plus a 5-second grace window (e.g., event ending at 30s is dropped after slowest viewer reaches 35s); runs unconditionally on prune cycles instead of waiting for event-cache byte cap pressure so old subtitle image bytes are released promptly.
37- purgeSubtitleCacheDir() - Removes the entire subtitle `.sup` file cache directory from disk; called once at server startup to clean up any files left over from a previous run.
39- purgeSubtitleCacheDir() - Removes the entire subtitle `.sup` file cache directory from disk; called once at server startup to clean up any files left over from a previous run.
@@ -145,6 +147,7 @@
145- POST /api/files/copy - Copies a file to a destination folder with conflict strategies (`error`, `overwrite`, `rename`) and user-folder size-limit checks.
147- POST /api/files/copy - Copies a file to a destination folder with conflict strategies (`error`, `overwrite`, `rename`) and user-folder size-limit checks.
146- POST /api/files/video-stream - Creates a short-lived HLS session for a video and returns playlistUrl, durationSeconds, videoWidth, videoHeight, subtitleTracks, imageSubtitleTracks, and subtitleSummary ({total, converted, imageBased, skipped}).
148- POST /api/files/video-stream - Creates a short-lived HLS session for a video and returns playlistUrl, durationSeconds, videoWidth, videoHeight, subtitleTracks, imageSubtitleTracks, and subtitleSummary ({total, converted, imageBased, skipped}).
147- GET /api/files/video-stream-subtitle-frame - Authenticated. Renders a PNG subtitle frame for bitmap subtitle tracks via cached PGS decode/composite flow; returns {frame, left, top, width, height, canvasWidth, canvasHeight}; sends response headers X-Subtitle-Frame-{Left,Top,Width,Height,Canvas-Width,Canvas-Height,Start-Time,End-Time} plus X-Subtitle-{Request-Received-At-Ms,Response-Sent-At-Ms} so the client can log subtitle timing against server send time; on failures or no active subtitle it returns 204 so the client can stop retrying.
149- GET /api/files/video-stream-subtitle-frame - Authenticated. Renders a PNG subtitle frame for bitmap subtitle tracks via cached PGS decode/composite flow; returns {frame, left, top, width, height, canvasWidth, canvasHeight}; sends response headers X-Subtitle-Frame-{Left,Top,Width,Height,Canvas-Width,Canvas-Height,Start-Time,End-Time} plus X-Subtitle-{Request-Received-At-Ms,Response-Sent-At-Ms} so the client can log subtitle timing against server send time; on failures or no active subtitle it returns 204 so the client can stop retrying.
150- GET /api/files/video-stream-subtitle-range - Authenticated. Returns JSON {status, startTimeSeconds, endTimeSeconds, frames[]} for all bitmap subtitle events overlapping a requested time window; each frame entry includes placement/canvas metadata plus base64 PNG data so the client walker can cache multiple subtitle images per request.
148- POST /api/files/video-stream-subtitle-log - Authenticated. Accepts batched client-side subtitle timing events for an authorised file and appends them to the local subtitle debug-log cache with file path, username, and stream session context.
151- POST /api/files/video-stream-subtitle-log - Authenticated. Accepts batched client-side subtitle timing events for an authorised file and appends them to the local subtitle debug-log cache with file path, username, and stream session context.
149- DELETE /api/files/video-stream/:sessionId - Explicitly releases an active short-lived video stream session and stops backend processing.
152- DELETE /api/files/video-stream/:sessionId - Explicitly releases an active short-lived video stream session and stops backend processing.
150- POST /api/files/watched-statuses - Returns fast per-user watched statuses for up to 500 file paths without triggering expensive metadata/hash work; response is { statuses: { [filePath]: 'fully'|'partway' } }.
153- POST /api/files/watched-statuses - Returns fast per-user watched statuses for up to 500 file paths without triggering expensive metadata/hash work; response is { statuses: { [filePath]: 'fully'|'partway' } }.
@@ -160,6 +163,7 @@
160- GET /api/share/download/:token - Public. Downloads the file or a zip of the directory for a valid token; 410 expired.
163- GET /api/share/download/:token - Public. Downloads the file or a zip of the directory for a valid token; 410 expired.
161- GET /api/share/video-stream/:token - Public. Creates a short-lived HLS session for a shared video and returns playlistUrl, durationSeconds, subtitleTracks, imageSubtitleTracks, and subtitleSummary ({total, converted, imageBased, skipped}).
164- GET /api/share/video-stream/:token - Public. Creates a short-lived HLS session for a shared video and returns playlistUrl, durationSeconds, subtitleTracks, imageSubtitleTracks, and subtitleSummary ({total, converted, imageBased, skipped}).
162- GET /api/share/video-stream-subtitle-frame/:token - Public. Renders a PNG subtitle frame for shared-video bitmap subtitle tracks using the same cached PGS decode path as the authenticated player; returns the same subtitle timing headers as the authenticated route and 204 with X-Subtitle-Frame-Status when no frame is active or rendering fails.
165- GET /api/share/video-stream-subtitle-frame/:token - Public. Renders a PNG subtitle frame for shared-video bitmap subtitle tracks using the same cached PGS decode path as the authenticated player; returns the same subtitle timing headers as the authenticated route and 204 with X-Subtitle-Frame-Status when no frame is active or rendering fails.
166- GET /api/share/video-stream-subtitle-range/:token - Public. Returns the same JSON subtitle-window payload as the authenticated range route for shared-video prefetching.
163- POST /api/share/video-stream-subtitle-log/:token - Public. Accepts batched client-side subtitle timing events for a valid shared-video token and appends them to the local subtitle debug-log cache with share-token and stream-session context.
167- POST /api/share/video-stream-subtitle-log/:token - Public. Accepts batched client-side subtitle timing events for a valid shared-video token and appends them to the local subtitle debug-log cache with share-token and stream-session context.
164- DELETE /api/share/video-stream/session/:sessionId - Public. Explicitly releases a shared HLS lease so the share page can clean up the backend stream session on close/unload instead of waiting for idle expiry.
168- DELETE /api/share/video-stream/session/:sessionId - Public. Explicitly releases a shared HLS lease so the share page can clean up the backend stream session on close/unload instead of waiting for idle expiry.
165- buildShareOpenGraphPage(token, req) - Reads share.html, injects OG meta tags (<og:title>, <og:description>, <og:image> for image files, twitter:card) based on DB lookup of token, and returns the full HTML string. Handles expired and not-found tokens. Exported and used by the /share/:token route in server/index.js.
169- buildShareOpenGraphPage(token, req) - Reads share.html, injects OG meta tags (<og:title>, <og:description>, <og:image> for image files, twitter:card) based on DB lookup of token, and returns the full HTML string. Handles expired and not-found tokens. Exported and used by the /share/:token route in server/index.js.
@@ -199,14 +203,14 @@
199- Standalone public share page served at /share/:token; no auth required.
203- Standalone public share page served at /share/:token; no auth required.
200- Timer bar - Live HH:MM:SS countdown showing remaining validity; turns red and disables download when expired.
204- Timer bar - Live HH:MM:SS countdown showing remaining validity; turns red and disables download when expired.
201- tryPreview(name, isDir) - Renders inline preview (img/video/audio/text pre); no-op for unsupported types or directories.
205- tryPreview(name, isDir) - Renders inline preview (img/video/audio/text pre); no-op for unsupported types or directories.
202- Share video preview - Uses the shared browser video-player helper used by app previews: VOD UI enforcement, long forward buffer, forced caption overrides (text background opacity transparent + text edge style uniform), subtitle/audio track restore/save by matching track names, image-subtitle overlay support (adaptive subtitle prefetch stride: smaller near playback, larger when cache lead is high), background stream-ahead prefetch (session playlist/variant/segment fetches continue towards video end while playback reads cache), seek-bar cache frontier marker (`:`) for walker progress, service-worker-backed HLS segment cache enablement during playback (with per-session cache cleanup on close), and explicit backend session release on unload.
206- Share video preview - Uses the shared browser video-player helper used by app previews: VOD UI enforcement, long forward buffer, forced caption overrides (text background opacity transparent + text edge style uniform), subtitle/audio track restore/save by matching track names, image-subtitle overlay support (adaptive range-prefetch windows: 3 seconds near playback, up to 10 seconds when cache lead is high), background stream-ahead prefetch (session playlist/variant/segment fetches continue towards video end while playback reads cache), seek-bar cache frontier marker (`:`) for walker progress, service-worker-backed HLS segment cache enablement during playback (with per-session cache cleanup on close), and explicit backend session release on unload.
203- Fetches /api/share/info/:token on load; shows error state for 404/410 responses.
207- Fetches /api/share/info/:token on load; shows error state for 404/410 responses.
204- Download link points to /api/share/download/:token; labelled "Download als .zip" for directories.
208- Download link points to /api/share/download/:token; labelled "Download als .zip" for directories.
205
209
206## public/shared-video-player.js
210## public/shared-video-player.js
207- applyDefaultTextTrackPrefs() - Writes the default Video.js caption override settings (transparent background, uniform edge style) so all streamed players start from the same text-track baseline.
211- applyDefaultTextTrackPrefs() - Writes the default Video.js caption override settings (transparent background, uniform edge style) so all streamed players start from the same text-track baseline.
208- bindTrackPrefs(player, prefs, savePrefs) - Restores subtitle/audio track selections by track name and persists later track changes; shared by the authenticated player and the share page so both resolve track matches the same way.
212- bindTrackPrefs(player, prefs, savePrefs) - Restores subtitle/audio track selections by track name and persists later track changes; shared by the authenticated player and the share page so both resolve track matches the same way.
209- bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Adds the shared IM button/menu/overlay for bitmap subtitle tracks, restores saved image-subtitle selections, fetches rendered frames through a caller-supplied request builder, keeps a separate rolling lookahead-prefetch worker alive across timeupdates (including gaps where no subtitle is currently visible), supports cache-only foreground playback with `currentFetchEnabled: false` (foreground uses cached frames while walker owns server fetches), supports startup warmup with `initialPrefetchSeconds` (default 60s) so early timeline subtitle frames are requested immediately on player load before playback advances, supports fixed prefetch stride (`prefetchStepSeconds`) and adaptive stride mode (`prefetchAdaptiveStepEnabled` with `prefetchStepSecondsMin`/`prefetchStepSecondsMax`) plus optional adaptive pacing (`prefetchAdaptivePacingEnabled`) to balance cache fill speed against backend request pressure, extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), merges buffered-end signals from both Video.js/player APIs and underlying media buffered ranges so under-reported player values do not cap subtitle prefetch early, keeps the prefetch frontier pinned to at least current playback time so it chases buffered-ahead range instead of replaying stale lag after video/session changes, coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), applies per-request timeouts (`currentRequestTimeoutMs`, `prefetchRequestTimeoutMs`) so hung subtitle frame requests cannot stall updates indefinitely, paces prefetch polling (`prefetchRequestIntervalMs`) to reduce request bursts, logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, caches received subtitle PNG frames client-side for the lifetime of the player session (including prefetched frames) so rewind playback can render from local cache even after server-side purge, ensures force-seek aborts still clear in-flight current-request state so subtitle refreshes continue instead of deadlocking, updates seek-bar bracket markers only after responses resolve (no in-flight jump-back flicker), keeps both marker positions forward-only (never regressing to earlier times), allows the two bracket glyphs to overlap naturally when positions match, advances markers even when responses are 204/no-frame, and disables the track after the first hard failure.
213- bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Adds the shared IM button/menu/overlay for bitmap subtitle tracks, restores saved image-subtitle selections, fetches rendered frames through a caller-supplied request builder, can optionally use a separate range-prefetch request builder (`buildPrefetchRequest`) so the walker caches multiple subtitle images from one window request, keeps a separate rolling lookahead-prefetch worker alive across timeupdates (including gaps where no subtitle is currently visible), supports cache-only foreground playback with `currentFetchEnabled: false` (foreground uses cached frames while walker owns server fetches), supports startup warmup with `initialPrefetchSeconds` (default 60s) so early timeline subtitle frames are requested immediately on player load before playback advances, supports fixed prefetch stride (`prefetchStepSeconds`) and adaptive stride mode (`prefetchAdaptiveStepEnabled` with `prefetchStepSecondsMin`/`prefetchStepSecondsMax`) plus optional adaptive pacing (`prefetchAdaptivePacingEnabled`) to balance cache fill speed against backend request pressure, extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), merges buffered-end signals from both Video.js/player APIs and underlying media buffered ranges so under-reported player values do not cap subtitle prefetch early, keeps the prefetch frontier pinned to at least current playback time so it chases buffered-ahead range instead of replaying stale lag after video/session changes, coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), applies per-request timeouts (`currentRequestTimeoutMs`, `prefetchRequestTimeoutMs`) so hung subtitle frame requests cannot stall updates indefinitely, paces prefetch polling (`prefetchRequestIntervalMs`) to reduce request bursts, logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, caches received subtitle PNG frames client-side for the lifetime of the player session (including prefetched frames) so rewind playback can render from local cache even after server-side purge, ensures force-seek aborts still clear in-flight current-request state so subtitle refreshes continue instead of deadlocking, updates seek-bar bracket markers only after responses resolve (no in-flight jump-back flicker), keeps both marker positions forward-only (never regressing to earlier times), allows the two bracket glyphs to overlap naturally when positions match, advances markers even when responses are 204/no-frame, and disables the track after the first hard failure.
210- bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Cache-frame time matching now uses a small epsilon window around start/end timestamps to avoid boundary misses; cache-only mode can also perform a throttled direct current-frame fallback fetch on cache miss (`cacheMissFallbackEnabled`, `cacheMissFallbackIntervalMs`) so subtitles recover without waiting for another seek/timeupdate cycle, fallback fetches preserve prefetch progress so repeated cache misses do not keep resetting subtitle lookahead, and duration metadata hints now extend lookahead prefetch to the known video end even before playback advances.
214- bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Cache-frame time matching now uses a small epsilon window around start/end timestamps to avoid boundary misses; cache-only mode can also perform a throttled direct current-frame fallback fetch on cache miss (`cacheMissFallbackEnabled`, `cacheMissFallbackIntervalMs`) so subtitles recover without waiting for another seek/timeupdate cycle, fallback fetches preserve prefetch progress so repeated cache misses do not keep resetting subtitle lookahead, and duration metadata hints now extend lookahead prefetch to the known video end even before playback advances.
211- bindStreamAheadPrefetch(opts) - Starts a background HLS walker that repeatedly fetches the session playlist, discovers variant playlists and media segments, and prefetches those assets into the browser cache so playback can read already-fetched segments while the backend prunes old files; tracks cached-through timeline progress (primary from playlist segment durations, with filename-based segment-index fallback for `.ts/.m4s` naming and a section-ratio fallback from fetched segments/total discovered segments when absolute timing metadata is missing) and returns a controller with stop()/done()/getStatus()/subscribe().
215- bindStreamAheadPrefetch(opts) - Starts a background HLS walker that repeatedly fetches the session playlist, discovers variant playlists and media segments, and prefetches those assets into the browser cache so playback can read already-fetched segments while the backend prunes old files; tracks cached-through timeline progress (primary from playlist segment durations, with filename-based segment-index fallback for `.ts/.m4s` naming and a section-ratio fallback from fetched segments/total discovered segments when absolute timing metadata is missing) and returns a controller with stop()/done()/getStatus()/subscribe().
212- bindStreamAheadSeekMarker(player, streamAheadPrefetch, opts) - Renders a non-interactive `:` marker on the playback seek bar showing how far the stream-ahead walker has cached through the timeline; subscribes to walker progress updates, updates tooltip text with formatted cached-through time, and removes itself on detach.
216- bindStreamAheadSeekMarker(player, streamAheadPrefetch, opts) - Renders a non-interactive `:` marker on the playback seek bar showing how far the stream-ahead walker has cached through the timeline; subscribes to walker progress updates, updates tooltip text with formatted cached-through time, and removes itself on detach.
@@ -295,7 +299,7 @@
295- buildAuthHeaders() - Builds the authenticated fetch headers used by preview-side API calls that need the bearer token plus fingerprint header.
299- buildAuthHeaders() - Builds the authenticated fetch headers used by preview-side API calls that need the bearer token plus fingerprint header.
296- renderStreamedVideoPreview(item) - For authenticated video previews, creates a backend stream session and starts the background stream-ahead prefetch worker so playlist/segment requests can continue independently of playback reads until cleanup.
300- renderStreamedVideoPreview(item) - For authenticated video previews, creates a backend stream session and starts the background stream-ahead prefetch worker so playlist/segment requests can continue independently of playback reads until cleanup.
297- bindImageSubtitleOverlay(player, videojs, prefs, session, item) - Adds the fullscreen-safe image-subtitle button, menu, and bottom overlay used to fetch and display subtitle frames for image-based tracks; keeps subtitle bitmaps horizontally centred at the bottom, highlights the currently selected IM menu option, persists per-user image subtitle stream index + track name, restores by saved track name first (then stream index), batches subtitle timing diagnostics to `/api/files/video-stream-subtitle-log`, and reads X-Subtitle-Frame-* headers from server responses to properly upscale downscaled frames while maintaining proportions.
301- bindImageSubtitleOverlay(player, videojs, prefs, session, item) - Adds the fullscreen-safe image-subtitle button, menu, and bottom overlay used to fetch and display subtitle frames for image-based tracks; keeps subtitle bitmaps horizontally centred at the bottom, highlights the currently selected IM menu option, persists per-user image subtitle stream index + track name, restores by saved track name first (then stream index), batches subtitle timing diagnostics to `/api/files/video-stream-subtitle-log`, and reads X-Subtitle-Frame-* headers from server responses to properly upscale downscaled frames while maintaining proportions.
298- renderStreamedVideoPreview(item, targetEl) - Creates the Video.js player with HLS source/track config, enables service-worker-backed HLS segment caching for the active stream session (and clears that cache on close), enforces non-live playback UI for file streams, uses container-fill sizing to keep previews within bounds, restores per-user video prefs (volume + subtitle/audio track names when present), wires the image-subtitle overlay controller, forces caption overrides on each open (text background opacity transparent + text edge style uniform), reports watch progress, warns when subtitle streams exist but none are web-compatible, releases the backend stream session on close/unload, uses a preview initialisation token guard so stale async player/walker setup from a previously closed preview is discarded immediately, and configures adaptive image-subtitle walker stepping in app playback (1s near playback, up to 5s when far ahead).
302- renderStreamedVideoPreview(item, targetEl) - Creates the Video.js player with HLS source/track config, enables service-worker-backed HLS segment caching for the active stream session (and clears that cache on close), enforces non-live playback UI for file streams, uses container-fill sizing to keep previews within bounds, restores per-user video prefs (volume + subtitle/audio track names when present), wires the image-subtitle overlay controller, forces caption overrides on each open (text background opacity transparent + text edge style uniform), reports watch progress, warns when subtitle streams exist but none are web-compatible, releases the backend stream session on close/unload, uses a preview initialisation token guard so stale async player/walker setup from a previously closed preview is discarded immediately, and configures adaptive image-subtitle range prefetching in app playback (3s near playback, up to 10s when far ahead).
299- modelPreviewType(name) - Classifies direct client-side 3D preview support for `.stl` and `.obj`.
303- modelPreviewType(name) - Classifies direct client-side 3D preview support for `.stl` and `.obj`.
300- loadThreePreviewModules() - Lazy-loads Three.js plus OrbitControls/STLLoader/OBJLoader via import map aliases.
304- loadThreePreviewModules() - Lazy-loads Three.js plus OrbitControls/STLLoader/OBJLoader via import map aliases.
301- modelThumbnailDataUrl(item, blob) - Builds a blue SVG thumbnail for STL/OBJ files by parsing their geometry client-side; falls back to a badge when parsing fails.
305- modelThumbnailDataUrl(item, blob) - Builds a blue SVG thumbnail for STL/OBJ files by parsing their geometry client-side; falls back to a badge when parsing fails.
public/app.js +7 −2
@@ -116,8 +116,8 @@ const VIDEO_FORWARD_BUFFER_OVERRIDE_ENABLED = false;
116 116 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 15;
117 117 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS = 60;
118 118 const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS = 40;
119 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR = 1;
120 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR = 5;
119 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR = 3;
120 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR = 10;
121 121 let videoJsLoaderPromise = null;
122 122 let threePreviewModulesPromise = null;
123 123
@@ -442,6 +442,11 @@ function bindImageSubtitleOverlay (player, videojs, prefs, session, item)
442 442 prefetchStepSecondsMin: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR,
443 443 prefetchStepSecondsMax: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR,
444 444 sendSubtitleLogBatch,
445 buildPrefetchRequest: ({ currentTime, endTime, streamIndex, session: activeSession }) => ({
446 url: `/api/files/video-stream-subtitle-range?filePath=${encodeURIComponent(item.path)}&streamIndex=${streamIndex}&startTimeSeconds=${encodeURIComponent(String(currentTime))}&endTimeSeconds=${encodeURIComponent(String(endTime))}&videoWidth=${encodeURIComponent(String(activeSession.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(activeSession.videoHeight || ''))}`,
447 headers: buildAuthHeaders(),
448 credentials: 'same-origin',
449 }),
445 450 buildFrameRequest: ({ currentTime, streamIndex, session: activeSession }) => ({
446 451 url: `/api/files/video-stream-subtitle-frame?filePath=${encodeURIComponent(item.path)}&streamIndex=${streamIndex}&timeSeconds=${encodeURIComponent(String(currentTime))}&videoWidth=${encodeURIComponent(String(activeSession.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(activeSession.videoHeight || ''))}`,
447 452 headers: buildAuthHeaders(),
@@ -116,8 +116,8 @@ const VIDEO_FORWARD_BUFFER_OVERRIDE_ENABLED = false;
116const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 15;
116const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 15;
117const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS = 60;
117const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS = 60;
118const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS = 40;
118const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS = 40;
119const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR = 1;
119const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR = 3;
120const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR = 5;
120const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR = 10;
121let videoJsLoaderPromise = null;
121let videoJsLoaderPromise = null;
122let threePreviewModulesPromise = null;
122let threePreviewModulesPromise = null;
123
123
@@ -442,6 +442,11 @@ function bindImageSubtitleOverlay (player, videojs, prefs, session, item)
442 prefetchStepSecondsMin: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR,
442 prefetchStepSecondsMin: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR,
443 prefetchStepSecondsMax: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR,
443 prefetchStepSecondsMax: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR,
444 sendSubtitleLogBatch,
444 sendSubtitleLogBatch,
445 buildPrefetchRequest: ({ currentTime, endTime, streamIndex, session: activeSession }) => ({
446 url: `/api/files/video-stream-subtitle-range?filePath=${encodeURIComponent(item.path)}&streamIndex=${streamIndex}&startTimeSeconds=${encodeURIComponent(String(currentTime))}&endTimeSeconds=${encodeURIComponent(String(endTime))}&videoWidth=${encodeURIComponent(String(activeSession.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(activeSession.videoHeight || ''))}`,
447 headers: buildAuthHeaders(),
448 credentials: 'same-origin',
449 }),
445 buildFrameRequest: ({ currentTime, streamIndex, session: activeSession }) => ({
450 buildFrameRequest: ({ currentTime, streamIndex, session: activeSession }) => ({
446 url: `/api/files/video-stream-subtitle-frame?filePath=${encodeURIComponent(item.path)}&streamIndex=${streamIndex}&timeSeconds=${encodeURIComponent(String(currentTime))}&videoWidth=${encodeURIComponent(String(activeSession.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(activeSession.videoHeight || ''))}`,
451 url: `/api/files/video-stream-subtitle-frame?filePath=${encodeURIComponent(item.path)}&streamIndex=${streamIndex}&timeSeconds=${encodeURIComponent(String(currentTime))}&videoWidth=${encodeURIComponent(String(activeSession.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(activeSession.videoHeight || ''))}`,
447 headers: buildAuthHeaders(),
452 headers: buildAuthHeaders(),
public/share.html +6 −2
@@ -252,8 +252,8 @@
252 252 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 15;
253 253 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS = 60;
254 254 const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS = 40;
255 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR = 1;
256 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR = 5;
255 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR = 3;
256 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR = 10;
257 257 const SHARE_VIDEO_PREFS_KEY = 'filemanager.share-video-prefs.v1';
258 258 let expiresAt = null;
259 259 let timerInterval = null;
@@ -517,6 +517,10 @@
517 517 prefetchAdaptivePacingEnabled: true,
518 518 prefetchStepSecondsMin: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR,
519 519 prefetchStepSecondsMax: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR,
520 buildPrefetchRequest: ({ currentTime, endTime, streamIndex, session }) => ({
521 url: `/api/share/video-stream-subtitle-range/${encodeURIComponent(token)}?streamIndex=${streamIndex}&startTimeSeconds=${encodeURIComponent(String(currentTime))}&endTimeSeconds=${encodeURIComponent(String(endTime))}&videoWidth=${encodeURIComponent(String(session.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(session.videoHeight || ''))}`,
522 credentials: 'same-origin',
523 }),
520 524 sendSubtitleLogBatch: (entries) =>
521 525 {
522 526 if (!Array.isArray(entries) || !entries.length) return Promise.resolve();
@@ -252,8 +252,8 @@
252 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 15;
252 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 15;
253 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS = 60;
253 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS = 60;
254 const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS = 40;
254 const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS = 40;
255 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR = 1;
255 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR = 3;
256 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR = 5;
256 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR = 10;
257 const SHARE_VIDEO_PREFS_KEY = 'filemanager.share-video-prefs.v1';
257 const SHARE_VIDEO_PREFS_KEY = 'filemanager.share-video-prefs.v1';
258 let expiresAt = null;
258 let expiresAt = null;
259 let timerInterval = null;
259 let timerInterval = null;
@@ -517,6 +517,10 @@
517 prefetchAdaptivePacingEnabled: true,
517 prefetchAdaptivePacingEnabled: true,
518 prefetchStepSecondsMin: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR,
518 prefetchStepSecondsMin: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR,
519 prefetchStepSecondsMax: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR,
519 prefetchStepSecondsMax: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR,
520 buildPrefetchRequest: ({ currentTime, endTime, streamIndex, session }) => ({
521 url: `/api/share/video-stream-subtitle-range/${encodeURIComponent(token)}?streamIndex=${streamIndex}&startTimeSeconds=${encodeURIComponent(String(currentTime))}&endTimeSeconds=${encodeURIComponent(String(endTime))}&videoWidth=${encodeURIComponent(String(session.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(session.videoHeight || ''))}`,
522 credentials: 'same-origin',
523 }),
520 sendSubtitleLogBatch: (entries) =>
524 sendSubtitleLogBatch: (entries) =>
521 {
525 {
522 if (!Array.isArray(entries) || !entries.length) return Promise.resolve();
526 if (!Array.isArray(entries) || !entries.length) return Promise.resolve();
public/shared-video-player.js +78 −18
@@ -15,7 +15,7 @@
15 15 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS_MAX = 120;
16 16 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_DEFAULT = 0.5;
17 17 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN = 0.25;
18 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX = 5;
18 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX = 30;
19 19 const IMAGE_SUBTITLE_TIME_MATCH_EPSILON_SECONDS = 0.05;
20 20 const IMAGE_SUBTITLE_CACHE_MISS_FALLBACK_INTERVAL_MS_DEFAULT = 2000;
21 21 const IMAGE_SUBTITLE_CURRENT_REQUEST_TIMEOUT_MS_DEFAULT = 4000;
@@ -76,6 +76,26 @@
76 76 return roundLogNumber(later - earlier, 3);
77 77 }
78 78
79 function base64ToBlob (base64, contentType = 'image/png')
80 {
81 const raw = String(base64 || '').trim();
82 if (!raw) return null;
83
84 try
85 {
86 const decoded = window.atob(raw);
87 const bytes = new Uint8Array(decoded.length);
88 for (let index = 0; index < decoded.length; index++)
89 {
90 bytes[index] = decoded.charCodeAt(index);
91 }
92 return new Blob([bytes], { type: String(contentType || '').trim() || 'image/png' });
93 } catch
94 {
95 return null;
96 }
97 }
98
79 99 function waitForImagePresentation (windowRef, imageEl)
80 100 {
81 101 return new Promise((resolve) =>
@@ -285,6 +305,7 @@
285 305
286 306 const savePrefs = typeof opts.savePrefs === 'function' ? opts.savePrefs : (() => { });
287 307 const buildFrameRequest = typeof opts.buildFrameRequest === 'function' ? opts.buildFrameRequest : null;
308 const buildPrefetchRequest = typeof opts.buildPrefetchRequest === 'function' ? opts.buildPrefetchRequest : buildFrameRequest;
288 309 const notifyError = typeof opts.onError === 'function' ? opts.onError : (() => { });
289 310 const sendSubtitleLogBatch = typeof opts.sendSubtitleLogBatch === 'function' ? opts.sendSubtitleLogBatch : null;
290 311 const requestedLookaheadSeconds = Number(opts.lookaheadSeconds);
@@ -1008,9 +1029,10 @@
1008 1029 : prefetchedThroughTimeSeconds + stepSeconds;
1009 1030 if (!Number.isFinite(nextTime) || nextTime > prefetchTargetTimeSeconds + 1e-6) return;
1010 1031
1011 const request = buildFrameRequest({
1032 const request = buildPrefetchRequest({
1012 1033 streamIndex: selectedStreamIndex,
1013 1034 currentTime: nextTime,
1035 endTime: Math.min(prefetchTargetTimeSeconds, nextTime + stepSeconds),
1014 1036 session,
1015 1037 });
1016 1038 if (!request || !request.url) return;
@@ -1023,6 +1045,7 @@
1023 1045 requestUrl: String(request.url || ''),
1024 1046 requestedAtMs: prefetchRequestStartedAtMs,
1025 1047 requestedVideoTimeSeconds: roundLogNumber(nextTime),
1048 requestedRangeEndTimeSeconds: roundLogNumber(Math.min(prefetchTargetTimeSeconds, nextTime + stepSeconds)),
1026 1049 });
1027 1050
1028 1051 let prefetchTimedOut = false;
@@ -1085,17 +1108,55 @@
1085 1108 }
1086 1109
1087 1110 if (!res.ok) return;
1088 const payload = await res.arrayBuffer();
1089 1111 const receivedAtMs = Date.now();
1090 const metadata = parseFrameMetadata(res, nextTime, stepSeconds);
1091 const blob = new Blob([payload], {
1092 type: String(res.headers.get('Content-Type') || '').trim() || 'image/png',
1093 });
1094 const cachedFrameEntry = cacheSubtitleFrame({
1095 streamIndex: selectedStreamIndex,
1096 blob,
1097 metadata,
1098 });
1112 let cachedFrameEntry = null;
1113 let receivedBlobBytes = 0;
1114
1115 if (/application\/json/i.test(String(res.headers.get('Content-Type') || '')))
1116 {
1117 const body = await res.json().catch(() => null);
1118 if (String(body && body.status || '').toLowerCase() === 'error') return;
1119 const responseFrames = Array.isArray(body && body.frames) ? body.frames : [];
1120 for (const frame of responseFrames)
1121 {
1122 if (!frame) continue;
1123 const blob = base64ToBlob(frame.frameBase64, frame.contentType || 'image/png');
1124 if (!blob || !blob.size) continue;
1125 receivedBlobBytes += Number(blob.size) || 0;
1126 const cached = cacheSubtitleFrame({
1127 streamIndex: selectedStreamIndex,
1128 blob,
1129 metadata: {
1130 startTimeSeconds: Number(frame.startTimeSeconds),
1131 endTimeSeconds: Number(frame.endTimeSeconds),
1132 frameWidth: Number(frame.width),
1133 frameHeight: Number(frame.height),
1134 canvasWidth: Number(frame.canvasWidth),
1135 canvasHeight: Number(frame.canvasHeight),
1136 },
1137 });
1138 if (cached) cachedFrameEntry = cached;
1139 }
1140 responseMeta.shouldShowAtVideoTimeSeconds = Number.isFinite(Number(body && body.startTimeSeconds))
1141 ? Number(body.startTimeSeconds)
1142 : responseMeta.shouldShowAtVideoTimeSeconds;
1143 responseMeta.subtitleEndTimeSeconds = Number.isFinite(Number(body && body.endTimeSeconds))
1144 ? Number(body.endTimeSeconds)
1145 : responseMeta.subtitleEndTimeSeconds;
1146 } else
1147 {
1148 const payload = await res.arrayBuffer();
1149 receivedBlobBytes = Number(payload && payload.byteLength || 0);
1150 const metadata = parseFrameMetadata(res, nextTime, stepSeconds);
1151 const blob = new Blob([payload], {
1152 type: String(res.headers.get('Content-Type') || '').trim() || 'image/png',
1153 });
1154 cachedFrameEntry = cacheSubtitleFrame({
1155 streamIndex: selectedStreamIndex,
1156 blob,
1157 metadata,
1158 });
1159 }
1099 1160
1100 1161 // When foreground fetches are disabled, current-time rendering is
1101 1162 // cache-only and may otherwise wait for a later timeupdate tick.
@@ -1105,11 +1166,10 @@
1105 1166 const nowTime = Number(player.currentTime());
1106 1167 if (Number.isFinite(nowTime) && nowTime >= 0)
1107 1168 {
1108 const startsAt = cachedFrameEntry.startTimeSeconds - IMAGE_SUBTITLE_TIME_MATCH_EPSILON_SECONDS;
1109 const endsAt = cachedFrameEntry.endTimeSeconds + IMAGE_SUBTITLE_TIME_MATCH_EPSILON_SECONDS;
1110 if (nowTime >= startsAt && nowTime < endsAt)
1169 const cachedForCurrentTime = findCachedFrameForTime(selectedStreamIndex, nowTime);
1170 if (cachedForCurrentTime)
1111 1171 {
1112 renderSubtitleFrame(cachedFrameEntry);
1172 renderSubtitleFrame(cachedForCurrentTime);
1113 1173 }
1114 1174 }
1115 1175 }
@@ -1119,9 +1179,9 @@
1119 1179 receivedAtMs,
1120 1180 sentToReceivedMs: diffMilliseconds(receivedAtMs, responseMeta.serverResponseSentAtMs),
1121 1181 requestedToReceivedMs: diffMilliseconds(receivedAtMs, prefetchRequestStartedAtMs),
1122 blobBytes: Number(payload && payload.byteLength || 0),
1182 blobBytes: receivedBlobBytes,
1123 1183 });
1124 prefetchedThroughTimeSeconds = nextTime;
1184 prefetchedThroughTimeSeconds = Math.min(prefetchTargetTimeSeconds, nextTime + stepSeconds);
1125 1185 const waitMs = getPrefetchDelayMs(Number(player.currentTime()));
1126 1186 if (waitMs > 0)
1127 1187 {
@@ -15,7 +15,7 @@
15 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS_MAX = 120;
15 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS_MAX = 120;
16 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_DEFAULT = 0.5;
16 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_DEFAULT = 0.5;
17 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN = 0.25;
17 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN = 0.25;
18 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX = 5;
18 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX = 30;
19 const IMAGE_SUBTITLE_TIME_MATCH_EPSILON_SECONDS = 0.05;
19 const IMAGE_SUBTITLE_TIME_MATCH_EPSILON_SECONDS = 0.05;
20 const IMAGE_SUBTITLE_CACHE_MISS_FALLBACK_INTERVAL_MS_DEFAULT = 2000;
20 const IMAGE_SUBTITLE_CACHE_MISS_FALLBACK_INTERVAL_MS_DEFAULT = 2000;
21 const IMAGE_SUBTITLE_CURRENT_REQUEST_TIMEOUT_MS_DEFAULT = 4000;
21 const IMAGE_SUBTITLE_CURRENT_REQUEST_TIMEOUT_MS_DEFAULT = 4000;
@@ -76,6 +76,26 @@
76 return roundLogNumber(later - earlier, 3);
76 return roundLogNumber(later - earlier, 3);
77 }
77 }
78
78
79 function base64ToBlob (base64, contentType = 'image/png')
80 {
81 const raw = String(base64 || '').trim();
82 if (!raw) return null;
83
84 try
85 {
86 const decoded = window.atob(raw);
87 const bytes = new Uint8Array(decoded.length);
88 for (let index = 0; index < decoded.length; index++)
89 {
90 bytes[index] = decoded.charCodeAt(index);
91 }
92 return new Blob([bytes], { type: String(contentType || '').trim() || 'image/png' });
93 } catch
94 {
95 return null;
96 }
97 }
98
79 function waitForImagePresentation (windowRef, imageEl)
99 function waitForImagePresentation (windowRef, imageEl)
80 {
100 {
81 return new Promise((resolve) =>
101 return new Promise((resolve) =>
@@ -285,6 +305,7 @@
285
305
286 const savePrefs = typeof opts.savePrefs === 'function' ? opts.savePrefs : (() => { });
306 const savePrefs = typeof opts.savePrefs === 'function' ? opts.savePrefs : (() => { });
287 const buildFrameRequest = typeof opts.buildFrameRequest === 'function' ? opts.buildFrameRequest : null;
307 const buildFrameRequest = typeof opts.buildFrameRequest === 'function' ? opts.buildFrameRequest : null;
308 const buildPrefetchRequest = typeof opts.buildPrefetchRequest === 'function' ? opts.buildPrefetchRequest : buildFrameRequest;
288 const notifyError = typeof opts.onError === 'function' ? opts.onError : (() => { });
309 const notifyError = typeof opts.onError === 'function' ? opts.onError : (() => { });
289 const sendSubtitleLogBatch = typeof opts.sendSubtitleLogBatch === 'function' ? opts.sendSubtitleLogBatch : null;
310 const sendSubtitleLogBatch = typeof opts.sendSubtitleLogBatch === 'function' ? opts.sendSubtitleLogBatch : null;
290 const requestedLookaheadSeconds = Number(opts.lookaheadSeconds);
311 const requestedLookaheadSeconds = Number(opts.lookaheadSeconds);
@@ -1008,9 +1029,10 @@
1008 : prefetchedThroughTimeSeconds + stepSeconds;
1029 : prefetchedThroughTimeSeconds + stepSeconds;
1009 if (!Number.isFinite(nextTime) || nextTime > prefetchTargetTimeSeconds + 1e-6) return;
1030 if (!Number.isFinite(nextTime) || nextTime > prefetchTargetTimeSeconds + 1e-6) return;
1010
1031
1011 const request = buildFrameRequest({
1032 const request = buildPrefetchRequest({
1012 streamIndex: selectedStreamIndex,
1033 streamIndex: selectedStreamIndex,
1013 currentTime: nextTime,
1034 currentTime: nextTime,
1035 endTime: Math.min(prefetchTargetTimeSeconds, nextTime + stepSeconds),
1014 session,
1036 session,
1015 });
1037 });
1016 if (!request || !request.url) return;
1038 if (!request || !request.url) return;
@@ -1023,6 +1045,7 @@
1023 requestUrl: String(request.url || ''),
1045 requestUrl: String(request.url || ''),
1024 requestedAtMs: prefetchRequestStartedAtMs,
1046 requestedAtMs: prefetchRequestStartedAtMs,
1025 requestedVideoTimeSeconds: roundLogNumber(nextTime),
1047 requestedVideoTimeSeconds: roundLogNumber(nextTime),
1048 requestedRangeEndTimeSeconds: roundLogNumber(Math.min(prefetchTargetTimeSeconds, nextTime + stepSeconds)),
1026 });
1049 });
1027
1050
1028 let prefetchTimedOut = false;
1051 let prefetchTimedOut = false;
@@ -1085,17 +1108,55 @@
1085 }
1108 }
1086
1109
1087 if (!res.ok) return;
1110 if (!res.ok) return;
1088 const payload = await res.arrayBuffer();
1089 const receivedAtMs = Date.now();
1111 const receivedAtMs = Date.now();
1090 const metadata = parseFrameMetadata(res, nextTime, stepSeconds);
1112 let cachedFrameEntry = null;
1091 const blob = new Blob([payload], {
1113 let receivedBlobBytes = 0;
1092 type: String(res.headers.get('Content-Type') || '').trim() || 'image/png',
1114
1093 });
1115 if (/application\/json/i.test(String(res.headers.get('Content-Type') || '')))
1094 const cachedFrameEntry = cacheSubtitleFrame({
1116 {
1095 streamIndex: selectedStreamIndex,
1117 const body = await res.json().catch(() => null);
1096 blob,
1118 if (String(body && body.status || '').toLowerCase() === 'error') return;
1097 metadata,
1119 const responseFrames = Array.isArray(body && body.frames) ? body.frames : [];
1098 });
1120 for (const frame of responseFrames)
1121 {
1122 if (!frame) continue;
1123 const blob = base64ToBlob(frame.frameBase64, frame.contentType || 'image/png');
1124 if (!blob || !blob.size) continue;
1125 receivedBlobBytes += Number(blob.size) || 0;
1126 const cached = cacheSubtitleFrame({
1127 streamIndex: selectedStreamIndex,
1128 blob,
1129 metadata: {
1130 startTimeSeconds: Number(frame.startTimeSeconds),
1131 endTimeSeconds: Number(frame.endTimeSeconds),
1132 frameWidth: Number(frame.width),
1133 frameHeight: Number(frame.height),
1134 canvasWidth: Number(frame.canvasWidth),
1135 canvasHeight: Number(frame.canvasHeight),
1136 },
1137 });
1138 if (cached) cachedFrameEntry = cached;
1139 }
1140 responseMeta.shouldShowAtVideoTimeSeconds = Number.isFinite(Number(body && body.startTimeSeconds))
1141 ? Number(body.startTimeSeconds)
1142 : responseMeta.shouldShowAtVideoTimeSeconds;
1143 responseMeta.subtitleEndTimeSeconds = Number.isFinite(Number(body && body.endTimeSeconds))
1144 ? Number(body.endTimeSeconds)
1145 : responseMeta.subtitleEndTimeSeconds;
1146 } else
1147 {
1148 const payload = await res.arrayBuffer();
1149 receivedBlobBytes = Number(payload && payload.byteLength || 0);
1150 const metadata = parseFrameMetadata(res, nextTime, stepSeconds);
1151 const blob = new Blob([payload], {
1152 type: String(res.headers.get('Content-Type') || '').trim() || 'image/png',
1153 });
1154 cachedFrameEntry = cacheSubtitleFrame({
1155 streamIndex: selectedStreamIndex,
1156 blob,
1157 metadata,
1158 });
1159 }
1099
1160
1100 // When foreground fetches are disabled, current-time rendering is
1161 // When foreground fetches are disabled, current-time rendering is
1101 // cache-only and may otherwise wait for a later timeupdate tick.
1162 // cache-only and may otherwise wait for a later timeupdate tick.
@@ -1105,11 +1166,10 @@
1105 const nowTime = Number(player.currentTime());
1166 const nowTime = Number(player.currentTime());
1106 if (Number.isFinite(nowTime) && nowTime >= 0)
1167 if (Number.isFinite(nowTime) && nowTime >= 0)
1107 {
1168 {
1108 const startsAt = cachedFrameEntry.startTimeSeconds - IMAGE_SUBTITLE_TIME_MATCH_EPSILON_SECONDS;
1169 const cachedForCurrentTime = findCachedFrameForTime(selectedStreamIndex, nowTime);
1109 const endsAt = cachedFrameEntry.endTimeSeconds + IMAGE_SUBTITLE_TIME_MATCH_EPSILON_SECONDS;
1170 if (cachedForCurrentTime)
1110 if (nowTime >= startsAt && nowTime < endsAt)
1111 {
1171 {
1112 renderSubtitleFrame(cachedFrameEntry);
1172 renderSubtitleFrame(cachedForCurrentTime);
1113 }
1173 }
1114 }
1174 }
1115 }
1175 }
@@ -1119,9 +1179,9 @@
1119 receivedAtMs,
1179 receivedAtMs,
1120 sentToReceivedMs: diffMilliseconds(receivedAtMs, responseMeta.serverResponseSentAtMs),
1180 sentToReceivedMs: diffMilliseconds(receivedAtMs, responseMeta.serverResponseSentAtMs),
1121 requestedToReceivedMs: diffMilliseconds(receivedAtMs, prefetchRequestStartedAtMs),
1181 requestedToReceivedMs: diffMilliseconds(receivedAtMs, prefetchRequestStartedAtMs),
1122 blobBytes: Number(payload && payload.byteLength || 0),
1182 blobBytes: receivedBlobBytes,
1123 });
1183 });
1124 prefetchedThroughTimeSeconds = nextTime;
1184 prefetchedThroughTimeSeconds = Math.min(prefetchTargetTimeSeconds, nextTime + stepSeconds);
1125 const waitMs = getPrefetchDelayMs(Number(player.currentTime()));
1185 const waitMs = getPrefetchDelayMs(Number(player.currentTime()));
1126 if (waitMs > 0)
1186 if (waitMs > 0)
1127 {
1187 {
server/image-subtitles.js +111 −24
@@ -595,38 +595,35 @@ function parseRenderOptions (options)
595 595 };
596 596 }
597 597
598 async function renderImageSubtitleFrame (options)
598 function parseRenderRangeOptions (options)
599 599 {
600 const requestStartedAt = Date.now();
601 const parsed = parseRenderOptions(options);
602 const { filePath, streamIndex, timeSeconds, canvasWidth, canvasHeight } = parsed;
603
604 if (!parsed.isValid)
605 {
606 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
607 return null;
608 }
600 const parsed = parseRenderOptions({
601 ...options,
602 timeSeconds: options && options.startTimeSeconds,
603 });
604 const startTimeSeconds = parsed.timeSeconds;
605 const endTimeSeconds = Number.parseFloat(String((options && options.endTimeSeconds) ?? ''), 10);
609 606
610 const entry = await getEventCacheEntry(filePath, streamIndex, { waitForBuild: false });
611 if (!entry || !Array.isArray(entry.events) || entry.events.length === 0)
612 {
613 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
614 return null;
615 }
607 return {
608 filePath: parsed.filePath,
609 streamIndex: parsed.streamIndex,
610 startTimeSeconds,
611 endTimeSeconds,
612 canvasWidth: parsed.canvasWidth,
613 canvasHeight: parsed.canvasHeight,
614 isValid: !!(parsed.isValid && Number.isFinite(endTimeSeconds) && endTimeSeconds > startTimeSeconds),
615 };
616 }
616 617
617 const eventIndex = findActiveEventIndex(entry.events, timeSeconds);
618 if (eventIndex < 0)
619 {
620 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
621 return null;
622 }
618 async function getRenderedFrameForEvent (entry, eventIndex, canvasWidth, canvasHeight)
619 {
620 if (!entry || !Array.isArray(entry.events) || eventIndex < 0 || eventIndex >= entry.events.length) return null;
623 621
624 622 const frameKey = `${entry.cacheKey}|${eventIndex}|${canvasWidth}x${canvasHeight}`;
625 623 const cachedFrame = getCachedValue(frameCache, frameKey);
626 624 if (cachedFrame)
627 625 {
628 626 subtitleDebugStats.frameCacheHits += 1;
629 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
630 627 return cachedFrame;
631 628 }
632 629
@@ -637,7 +634,6 @@ async function renderImageSubtitleFrame (options)
637 634 if (!frameData)
638 635 {
639 636 recordDuration(subtitleDebugStats.frameRenderDurationMs, renderStartedAt);
640 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
641 637 return null;
642 638 }
643 639 recordDuration(subtitleDebugStats.frameRenderDurationMs, renderStartedAt);
@@ -661,10 +657,99 @@ async function renderImageSubtitleFrame (options)
661 657 FRAME_CACHE_TTL_MS,
662 658 estimateFrameCacheBytes,
663 659 );
660 return cacheValue;
661 }
662
663 async function renderImageSubtitleFrame (options)
664 {
665 const requestStartedAt = Date.now();
666 const parsed = parseRenderOptions(options);
667 const { filePath, streamIndex, timeSeconds, canvasWidth, canvasHeight } = parsed;
668
669 if (!parsed.isValid)
670 {
671 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
672 return null;
673 }
674
675 const entry = await getEventCacheEntry(filePath, streamIndex, { waitForBuild: false });
676 if (!entry || !Array.isArray(entry.events) || entry.events.length === 0)
677 {
678 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
679 return null;
680 }
681
682 const eventIndex = findActiveEventIndex(entry.events, timeSeconds);
683 if (eventIndex < 0)
684 {
685 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
686 return null;
687 }
688
689 const cacheValue = await getRenderedFrameForEvent(entry, eventIndex, canvasWidth, canvasHeight);
690 if (!cacheValue)
691 {
692 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
693 return null;
694 }
664 695 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
665 696 return cacheValue;
666 697 }
667 698
699 async function renderImageSubtitleFramesInRange (options)
700 {
701 const requestStartedAt = Date.now();
702 const parsed = parseRenderRangeOptions(options);
703 const { filePath, streamIndex, startTimeSeconds, endTimeSeconds, canvasWidth, canvasHeight } = parsed;
704
705 if (!parsed.isValid)
706 {
707 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
708 return {
709 frames: [],
710 startTimeSeconds,
711 endTimeSeconds,
712 };
713 }
714
715 const entry = await getEventCacheEntry(filePath, streamIndex, { waitForBuild: false });
716 if (!entry || !Array.isArray(entry.events) || entry.events.length === 0)
717 {
718 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
719 return {
720 frames: [],
721 startTimeSeconds,
722 endTimeSeconds,
723 };
724 }
725
726 let eventIndex = findActiveEventIndex(entry.events, startTimeSeconds);
727 if (eventIndex < 0)
728 {
729 eventIndex = entry.events.findIndex((event) => event && Number(event.endTimeSeconds) > startTimeSeconds);
730 }
731
732 const frames = [];
733 for (let index = Math.max(0, eventIndex); index < entry.events.length; index++)
734 {
735 const event = entry.events[index];
736 if (!event) continue;
737 if (Number(event.startTimeSeconds) >= endTimeSeconds) break;
738 if (Number(event.endTimeSeconds) <= startTimeSeconds) continue;
739
740 const frame = await getRenderedFrameForEvent(entry, index, canvasWidth, canvasHeight);
741 if (!frame || !frame.frame) continue;
742 frames.push(frame);
743 }
744
745 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
746 return {
747 frames,
748 startTimeSeconds,
749 endTimeSeconds,
750 };
751 }
752
668 753 function deleteSupFileForKey (identityKey)
669 754 {
670 755 const cacheKey = eventCacheFileKey(identityKey);
@@ -893,7 +978,9 @@ function getImageSubtitleDebugSnapshot ()
893 978
894 979 module.exports = {
895 980 parseRenderOptions,
981 parseRenderRangeOptions,
896 982 renderImageSubtitleFrame,
983 renderImageSubtitleFramesInRange,
897 984 clearCachesForFile,
898 985 pruneOldImageSubtitleCaches,
899 986 purgeSubtitleCacheDir,
@@ -595,38 +595,35 @@ function parseRenderOptions (options)
595 };
595 };
596}
596}
597
597
598async function renderImageSubtitleFrame (options)
598function parseRenderRangeOptions (options)
599{
599{
600 const requestStartedAt = Date.now();
600 const parsed = parseRenderOptions({
601 const parsed = parseRenderOptions(options);
601 ...options,
602 const { filePath, streamIndex, timeSeconds, canvasWidth, canvasHeight } = parsed;
602 timeSeconds: options && options.startTimeSeconds,
603
603 });
604 if (!parsed.isValid)
604 const startTimeSeconds = parsed.timeSeconds;
605 {
605 const endTimeSeconds = Number.parseFloat(String((options && options.endTimeSeconds) ?? ''), 10);
606 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
607 return null;
608 }
609
606
610 const entry = await getEventCacheEntry(filePath, streamIndex, { waitForBuild: false });
607 return {
611 if (!entry || !Array.isArray(entry.events) || entry.events.length === 0)
608 filePath: parsed.filePath,
612 {
609 streamIndex: parsed.streamIndex,
613 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
610 startTimeSeconds,
614 return null;
611 endTimeSeconds,
615 }
612 canvasWidth: parsed.canvasWidth,
613 canvasHeight: parsed.canvasHeight,
614 isValid: !!(parsed.isValid && Number.isFinite(endTimeSeconds) && endTimeSeconds > startTimeSeconds),
615 };
616}
616
617
617 const eventIndex = findActiveEventIndex(entry.events, timeSeconds);
618async function getRenderedFrameForEvent (entry, eventIndex, canvasWidth, canvasHeight)
618 if (eventIndex < 0)
619{
619 {
620 if (!entry || !Array.isArray(entry.events) || eventIndex < 0 || eventIndex >= entry.events.length) return null;
620 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
621 return null;
622 }
623
621
624 const frameKey = `${entry.cacheKey}|${eventIndex}|${canvasWidth}x${canvasHeight}`;
622 const frameKey = `${entry.cacheKey}|${eventIndex}|${canvasWidth}x${canvasHeight}`;
625 const cachedFrame = getCachedValue(frameCache, frameKey);
623 const cachedFrame = getCachedValue(frameCache, frameKey);
626 if (cachedFrame)
624 if (cachedFrame)
627 {
625 {
628 subtitleDebugStats.frameCacheHits += 1;
626 subtitleDebugStats.frameCacheHits += 1;
629 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
630 return cachedFrame;
627 return cachedFrame;
631 }
628 }
632
629
@@ -637,7 +634,6 @@ async function renderImageSubtitleFrame (options)
637 if (!frameData)
634 if (!frameData)
638 {
635 {
639 recordDuration(subtitleDebugStats.frameRenderDurationMs, renderStartedAt);
636 recordDuration(subtitleDebugStats.frameRenderDurationMs, renderStartedAt);
640 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
641 return null;
637 return null;
642 }
638 }
643 recordDuration(subtitleDebugStats.frameRenderDurationMs, renderStartedAt);
639 recordDuration(subtitleDebugStats.frameRenderDurationMs, renderStartedAt);
@@ -661,10 +657,99 @@ async function renderImageSubtitleFrame (options)
661 FRAME_CACHE_TTL_MS,
657 FRAME_CACHE_TTL_MS,
662 estimateFrameCacheBytes,
658 estimateFrameCacheBytes,
663 );
659 );
660 return cacheValue;
661}
662
663async function renderImageSubtitleFrame (options)
664{
665 const requestStartedAt = Date.now();
666 const parsed = parseRenderOptions(options);
667 const { filePath, streamIndex, timeSeconds, canvasWidth, canvasHeight } = parsed;
668
669 if (!parsed.isValid)
670 {
671 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
672 return null;
673 }
674
675 const entry = await getEventCacheEntry(filePath, streamIndex, { waitForBuild: false });
676 if (!entry || !Array.isArray(entry.events) || entry.events.length === 0)
677 {
678 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
679 return null;
680 }
681
682 const eventIndex = findActiveEventIndex(entry.events, timeSeconds);
683 if (eventIndex < 0)
684 {
685 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
686 return null;
687 }
688
689 const cacheValue = await getRenderedFrameForEvent(entry, eventIndex, canvasWidth, canvasHeight);
690 if (!cacheValue)
691 {
692 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
693 return null;
694 }
664 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
695 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
665 return cacheValue;
696 return cacheValue;
666}
697}
667
698
699async function renderImageSubtitleFramesInRange (options)
700{
701 const requestStartedAt = Date.now();
702 const parsed = parseRenderRangeOptions(options);
703 const { filePath, streamIndex, startTimeSeconds, endTimeSeconds, canvasWidth, canvasHeight } = parsed;
704
705 if (!parsed.isValid)
706 {
707 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
708 return {
709 frames: [],
710 startTimeSeconds,
711 endTimeSeconds,
712 };
713 }
714
715 const entry = await getEventCacheEntry(filePath, streamIndex, { waitForBuild: false });
716 if (!entry || !Array.isArray(entry.events) || entry.events.length === 0)
717 {
718 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
719 return {
720 frames: [],
721 startTimeSeconds,
722 endTimeSeconds,
723 };
724 }
725
726 let eventIndex = findActiveEventIndex(entry.events, startTimeSeconds);
727 if (eventIndex < 0)
728 {
729 eventIndex = entry.events.findIndex((event) => event && Number(event.endTimeSeconds) > startTimeSeconds);
730 }
731
732 const frames = [];
733 for (let index = Math.max(0, eventIndex); index < entry.events.length; index++)
734 {
735 const event = entry.events[index];
736 if (!event) continue;
737 if (Number(event.startTimeSeconds) >= endTimeSeconds) break;
738 if (Number(event.endTimeSeconds) <= startTimeSeconds) continue;
739
740 const frame = await getRenderedFrameForEvent(entry, index, canvasWidth, canvasHeight);
741 if (!frame || !frame.frame) continue;
742 frames.push(frame);
743 }
744
745 recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);
746 return {
747 frames,
748 startTimeSeconds,
749 endTimeSeconds,
750 };
751}
752
668function deleteSupFileForKey (identityKey)
753function deleteSupFileForKey (identityKey)
669{
754{
670 const cacheKey = eventCacheFileKey(identityKey);
755 const cacheKey = eventCacheFileKey(identityKey);
@@ -893,7 +978,9 @@ function getImageSubtitleDebugSnapshot ()
893
978
894module.exports = {
979module.exports = {
895 parseRenderOptions,
980 parseRenderOptions,
981 parseRenderRangeOptions,
896 renderImageSubtitleFrame,
982 renderImageSubtitleFrame,
983 renderImageSubtitleFramesInRange,
897 clearCachesForFile,
984 clearCachesForFile,
898 pruneOldImageSubtitleCaches,
985 pruneOldImageSubtitleCaches,
899 purgeSubtitleCacheDir,
986 purgeSubtitleCacheDir,
server/routes/files.js +81 −1
@@ -12,7 +12,7 @@ const { loadConfig, saveConfig, getEffectivePaths, getAllowedRoot } = require('.
12 12 const { requireAuth } = require('../auth');
13 13 const { getCachedThumbnailInfo, getFilesWithThumbnailsInDir, getFolderIconSourceFile, setFolderIconAssignment } = require('../thumbnail-cache');
14 14 const { logError } = require('../logger');
15 const { renderImageSubtitleFrame } = require('../image-subtitles');
15 const { renderImageSubtitleFrame, renderImageSubtitleFramesInRange } = require('../image-subtitles');
16 16 const { appendSubtitleDebugEntries, SUBTITLE_DEBUG_LOG_DIR } = require('../subtitle-debug-log');
17 17 const { buildZip } = require('./share');
18 18 const { createVideoStreamSession, sendVideoStreamAsset, releaseVideoStreamSession } = require('../video-stream');
@@ -1801,6 +1801,86 @@ router.get('/video-stream-subtitle-frame', requireAuth, async (req, res, next) =
1801 1801 }
1802 1802 });
1803 1803
1804 // ---------------------------------------------------------------------------
1805 // GET /api/files/video-stream-subtitle-range
1806 // Authenticated. Returns rendered PNG subtitle bitmaps overlapping a time range.
1807 // Query params: filePath, streamIndex, startTimeSeconds, endTimeSeconds
1808 // ---------------------------------------------------------------------------
1809 router.get('/video-stream-subtitle-range', requireAuth, async (req, res) =>
1810 {
1811 const requestReceivedAtMs = Date.now();
1812 try
1813 {
1814 const filePath = String(req.query.filePath || '').trim();
1815 const streamIndex = Number.parseInt(String(req.query.streamIndex || ''), 10);
1816 const startTimeSeconds = Number.parseFloat(String(req.query.startTimeSeconds || ''), 10);
1817 const endTimeSeconds = Number.parseFloat(String(req.query.endTimeSeconds || ''), 10);
1818 const videoWidth = Number.parseInt(String(req.query.videoWidth || ''), 10);
1819 const videoHeight = Number.parseInt(String(req.query.videoHeight || ''), 10);
1820
1821 if (!filePath || !Number.isInteger(streamIndex) || streamIndex < 0 || !Number.isFinite(startTimeSeconds) || startTimeSeconds < 0 || !Number.isFinite(endTimeSeconds) || endTimeSeconds <= startTimeSeconds)
1822 {
1823 return res.status(400).json({ error: 'filePath, streamIndex, startTimeSeconds, and endTimeSeconds are required.' });
1824 }
1825
1826 const { config, roots } = loadConfigAndRoots();
1827 const info = resolveRootForUser(filePath, roots, req.user, config);
1828 if (!info || !canReadInfo(req.user, info))
1829 {
1830 return res.status(403).json({ error: 'Access denied.' });
1831 }
1832
1833 if (!fs.existsSync(filePath) || fs.statSync(filePath).isDirectory())
1834 {
1835 return res.status(404).json({ error: 'File not found.' });
1836 }
1837
1838 const canvasWidth = Number.isInteger(videoWidth) && videoWidth > 0 ? videoWidth : 1280;
1839 const canvasHeight = Number.isInteger(videoHeight) && videoHeight > 0 ? videoHeight : 720;
1840 const result = await renderImageSubtitleFramesInRange({
1841 filePath,
1842 streamIndex,
1843 startTimeSeconds,
1844 endTimeSeconds,
1845 canvasWidth,
1846 canvasHeight,
1847 });
1848
1849 res.set('X-Subtitle-Request-Received-At-Ms', String(requestReceivedAtMs));
1850 res.set('X-Subtitle-Response-Sent-At-Ms', String(Date.now()));
1851 res.json({
1852 status: 'ok',
1853 startTimeSeconds,
1854 endTimeSeconds,
1855 frames: Array.isArray(result && result.frames)
1856 ? result.frames.map((frame) => ({
1857 left: frame.left || 0,
1858 top: frame.top || 0,
1859 width: frame.width || 0,
1860 height: frame.height || 0,
1861 canvasWidth: frame.canvasWidth || canvasWidth,
1862 canvasHeight: frame.canvasHeight || canvasHeight,
1863 startTimeSeconds: frame.startTimeSeconds || 0,
1864 endTimeSeconds: frame.endTimeSeconds || 0,
1865 contentType: 'image/png',
1866 frameBase64: Buffer.from(frame.frame || Buffer.alloc(0)).toString('base64'),
1867 }))
1868 : [],
1869 });
1870 } catch (err)
1871 {
1872 logError('Subtitle range extraction failed', err, {
1873 filePath: String(req.query.filePath || ''),
1874 streamIndex: Number.parseInt(String(req.query.streamIndex || ''), 10),
1875 startTimeSeconds: Number.parseFloat(String(req.query.startTimeSeconds || ''), 10),
1876 endTimeSeconds: Number.parseFloat(String(req.query.endTimeSeconds || ''), 10),
1877 });
1878 res.set('X-Subtitle-Request-Received-At-Ms', String(requestReceivedAtMs));
1879 res.set('X-Subtitle-Response-Sent-At-Ms', String(Date.now()));
1880 return res.status(200).json({ status: 'error', frames: [] });
1881 }
1882 });
1883
1804 1884 // ---------------------------------------------------------------------------
1805 1885 // POST /api/files/video-stream-subtitle-log
1806 1886 // Authenticated. Persists client-side subtitle timing diagnostics to local cache.
@@ -12,7 +12,7 @@ const { loadConfig, saveConfig, getEffectivePaths, getAllowedRoot } = require('.
12const { requireAuth } = require('../auth');
12const { requireAuth } = require('../auth');
13const { getCachedThumbnailInfo, getFilesWithThumbnailsInDir, getFolderIconSourceFile, setFolderIconAssignment } = require('../thumbnail-cache');
13const { getCachedThumbnailInfo, getFilesWithThumbnailsInDir, getFolderIconSourceFile, setFolderIconAssignment } = require('../thumbnail-cache');
14const { logError } = require('../logger');
14const { logError } = require('../logger');
15const { renderImageSubtitleFrame } = require('../image-subtitles');
15const { renderImageSubtitleFrame, renderImageSubtitleFramesInRange } = require('../image-subtitles');
16const { appendSubtitleDebugEntries, SUBTITLE_DEBUG_LOG_DIR } = require('../subtitle-debug-log');
16const { appendSubtitleDebugEntries, SUBTITLE_DEBUG_LOG_DIR } = require('../subtitle-debug-log');
17const { buildZip } = require('./share');
17const { buildZip } = require('./share');
18const { createVideoStreamSession, sendVideoStreamAsset, releaseVideoStreamSession } = require('../video-stream');
18const { createVideoStreamSession, sendVideoStreamAsset, releaseVideoStreamSession } = require('../video-stream');
@@ -1801,6 +1801,86 @@ router.get('/video-stream-subtitle-frame', requireAuth, async (req, res, next) =
1801 }
1801 }
1802});
1802});
1803
1803
1804// ---------------------------------------------------------------------------
1805// GET /api/files/video-stream-subtitle-range
1806// Authenticated. Returns rendered PNG subtitle bitmaps overlapping a time range.
1807// Query params: filePath, streamIndex, startTimeSeconds, endTimeSeconds
1808// ---------------------------------------------------------------------------
1809router.get('/video-stream-subtitle-range', requireAuth, async (req, res) =>
1810{
1811 const requestReceivedAtMs = Date.now();
1812 try
1813 {
1814 const filePath = String(req.query.filePath || '').trim();
1815 const streamIndex = Number.parseInt(String(req.query.streamIndex || ''), 10);
1816 const startTimeSeconds = Number.parseFloat(String(req.query.startTimeSeconds || ''), 10);
1817 const endTimeSeconds = Number.parseFloat(String(req.query.endTimeSeconds || ''), 10);
1818 const videoWidth = Number.parseInt(String(req.query.videoWidth || ''), 10);
1819 const videoHeight = Number.parseInt(String(req.query.videoHeight || ''), 10);
1820
1821 if (!filePath || !Number.isInteger(streamIndex) || streamIndex < 0 || !Number.isFinite(startTimeSeconds) || startTimeSeconds < 0 || !Number.isFinite(endTimeSeconds) || endTimeSeconds <= startTimeSeconds)
1822 {
1823 return res.status(400).json({ error: 'filePath, streamIndex, startTimeSeconds, and endTimeSeconds are required.' });
1824 }
1825
1826 const { config, roots } = loadConfigAndRoots();
1827 const info = resolveRootForUser(filePath, roots, req.user, config);
1828 if (!info || !canReadInfo(req.user, info))
1829 {
1830 return res.status(403).json({ error: 'Access denied.' });
1831 }
1832
1833 if (!fs.existsSync(filePath) || fs.statSync(filePath).isDirectory())
1834 {
1835 return res.status(404).json({ error: 'File not found.' });
1836 }
1837
1838 const canvasWidth = Number.isInteger(videoWidth) && videoWidth > 0 ? videoWidth : 1280;
1839 const canvasHeight = Number.isInteger(videoHeight) && videoHeight > 0 ? videoHeight : 720;
1840 const result = await renderImageSubtitleFramesInRange({
1841 filePath,
1842 streamIndex,
1843 startTimeSeconds,
1844 endTimeSeconds,
1845 canvasWidth,
1846 canvasHeight,
1847 });
1848
1849 res.set('X-Subtitle-Request-Received-At-Ms', String(requestReceivedAtMs));
1850 res.set('X-Subtitle-Response-Sent-At-Ms', String(Date.now()));
1851 res.json({
1852 status: 'ok',
1853 startTimeSeconds,
1854 endTimeSeconds,
1855 frames: Array.isArray(result && result.frames)
1856 ? result.frames.map((frame) => ({
1857 left: frame.left || 0,
1858 top: frame.top || 0,
1859 width: frame.width || 0,
1860 height: frame.height || 0,
1861 canvasWidth: frame.canvasWidth || canvasWidth,
1862 canvasHeight: frame.canvasHeight || canvasHeight,
1863 startTimeSeconds: frame.startTimeSeconds || 0,
1864 endTimeSeconds: frame.endTimeSeconds || 0,
1865 contentType: 'image/png',
1866 frameBase64: Buffer.from(frame.frame || Buffer.alloc(0)).toString('base64'),
1867 }))
1868 : [],
1869 });
1870 } catch (err)
1871 {
1872 logError('Subtitle range extraction failed', err, {
1873 filePath: String(req.query.filePath || ''),
1874 streamIndex: Number.parseInt(String(req.query.streamIndex || ''), 10),
1875 startTimeSeconds: Number.parseFloat(String(req.query.startTimeSeconds || ''), 10),
1876 endTimeSeconds: Number.parseFloat(String(req.query.endTimeSeconds || ''), 10),
1877 });
1878 res.set('X-Subtitle-Request-Received-At-Ms', String(requestReceivedAtMs));
1879 res.set('X-Subtitle-Response-Sent-At-Ms', String(Date.now()));
1880 return res.status(200).json({ status: 'error', frames: [] });
1881 }
1882});
1883
1804// ---------------------------------------------------------------------------
1884// ---------------------------------------------------------------------------
1805// POST /api/files/video-stream-subtitle-log
1885// POST /api/files/video-stream-subtitle-log
1806// Authenticated. Persists client-side subtitle timing diagnostics to local cache.
1886// Authenticated. Persists client-side subtitle timing diagnostics to local cache.
server/routes/share.js +80 −1
@@ -11,7 +11,7 @@ const { getDb } = require('../db');
11 11 const { requireAuth } = require('../auth');
12 12 const { loadConfig, getEffectivePaths, getAllowedRoot } = require('../config');
13 13 const { createVideoStreamSession, sendVideoStreamAsset, releaseVideoStreamSession } = require('../video-stream');
14 const { renderImageSubtitleFrame } = require('../image-subtitles');
14 const { renderImageSubtitleFrame, renderImageSubtitleFramesInRange } = require('../image-subtitles');
15 15 const { appendSubtitleDebugEntries } = require('../subtitle-debug-log');
16 16 const { logError } = require('../logger');
17 17
@@ -536,6 +536,85 @@ router.get('/video-stream-subtitle-frame/:token', async (req, res) =>
536 536 }
537 537 });
538 538
539 // ---------------------------------------------------------------------------
540 // GET /api/share/video-stream-subtitle-range/:token
541 // Public. Returns rendered PNG subtitle bitmaps for a shared-video time range.
542 // Query params: streamIndex, startTimeSeconds, endTimeSeconds, videoWidth, videoHeight
543 // ---------------------------------------------------------------------------
544 router.get('/video-stream-subtitle-range/:token', async (req, res) =>
545 {
546 const requestReceivedAtMs = Date.now();
547 try
548 {
549 const token = String(req.params.token || '').trim();
550 const streamIndex = Number.parseInt(String(req.query.streamIndex || ''), 10);
551 const startTimeSeconds = Number.parseFloat(String(req.query.startTimeSeconds || ''), 10);
552 const endTimeSeconds = Number.parseFloat(String(req.query.endTimeSeconds || ''), 10);
553 const videoWidth = Number.parseInt(String(req.query.videoWidth || ''), 10);
554 const videoHeight = Number.parseInt(String(req.query.videoHeight || ''), 10);
555
556 if (!token || !Number.isInteger(streamIndex) || streamIndex < 0 || !Number.isFinite(startTimeSeconds) || startTimeSeconds < 0 || !Number.isFinite(endTimeSeconds) || endTimeSeconds <= startTimeSeconds)
557 {
558 return res.status(400).json({ error: 'token, streamIndex, startTimeSeconds, and endTimeSeconds are required.' });
559 }
560
561 const db = getDb();
562 const row = db.prepare('SELECT * FROM share_tokens WHERE token = ?').get([token]);
563 if (!row) return res.status(404).json({ error: 'Share link not found.' });
564 if (Date.now() > row.expires_at) return res.status(410).json({ error: 'Share link has expired.' });
565 if (row.is_dir) return res.status(400).json({ error: 'Cannot preview a directory.' });
566
567 if (!fs.existsSync(row.file_path) || fs.statSync(row.file_path).isDirectory())
568 {
569 return res.status(404).json({ error: 'File not found.' });
570 }
571
572 const canvasWidth = Number.isInteger(videoWidth) && videoWidth > 0 ? videoWidth : 1280;
573 const canvasHeight = Number.isInteger(videoHeight) && videoHeight > 0 ? videoHeight : 720;
574 const result = await renderImageSubtitleFramesInRange({
575 filePath: row.file_path,
576 streamIndex,
577 startTimeSeconds,
578 endTimeSeconds,
579 canvasWidth,
580 canvasHeight,
581 });
582
583 res.set('X-Subtitle-Request-Received-At-Ms', String(requestReceivedAtMs));
584 res.set('X-Subtitle-Response-Sent-At-Ms', String(Date.now()));
585 res.json({
586 status: 'ok',
587 startTimeSeconds,
588 endTimeSeconds,
589 frames: Array.isArray(result && result.frames)
590 ? result.frames.map((frame) => ({
591 left: frame.left || 0,
592 top: frame.top || 0,
593 width: frame.width || 0,
594 height: frame.height || 0,
595 canvasWidth: frame.canvasWidth || canvasWidth,
596 canvasHeight: frame.canvasHeight || canvasHeight,
597 startTimeSeconds: frame.startTimeSeconds || 0,
598 endTimeSeconds: frame.endTimeSeconds || 0,
599 contentType: 'image/png',
600 frameBase64: Buffer.from(frame.frame || Buffer.alloc(0)).toString('base64'),
601 }))
602 : [],
603 });
604 } catch (err)
605 {
606 logError('Shared subtitle range extraction failed', err, {
607 token: String(req.params.token || ''),
608 streamIndex: Number.parseInt(String(req.query.streamIndex || ''), 10),
609 startTimeSeconds: Number.parseFloat(String(req.query.startTimeSeconds || ''), 10),
610 endTimeSeconds: Number.parseFloat(String(req.query.endTimeSeconds || ''), 10),
611 });
612 res.set('X-Subtitle-Request-Received-At-Ms', String(requestReceivedAtMs));
613 res.set('X-Subtitle-Response-Sent-At-Ms', String(Date.now()));
614 return res.status(200).json({ status: 'error', frames: [] });
615 }
616 });
617
539 618 // ---------------------------------------------------------------------------
540 619 // POST /api/share/video-stream-subtitle-log/:token
541 620 // Public. Persists client-side subtitle timing diagnostics for a share playback.
@@ -11,7 +11,7 @@ const { getDb } = require('../db');
11const { requireAuth } = require('../auth');
11const { requireAuth } = require('../auth');
12const { loadConfig, getEffectivePaths, getAllowedRoot } = require('../config');
12const { loadConfig, getEffectivePaths, getAllowedRoot } = require('../config');
13const { createVideoStreamSession, sendVideoStreamAsset, releaseVideoStreamSession } = require('../video-stream');
13const { createVideoStreamSession, sendVideoStreamAsset, releaseVideoStreamSession } = require('../video-stream');
14const { renderImageSubtitleFrame } = require('../image-subtitles');
14const { renderImageSubtitleFrame, renderImageSubtitleFramesInRange } = require('../image-subtitles');
15const { appendSubtitleDebugEntries } = require('../subtitle-debug-log');
15const { appendSubtitleDebugEntries } = require('../subtitle-debug-log');
16const { logError } = require('../logger');
16const { logError } = require('../logger');
17
17
@@ -536,6 +536,85 @@ router.get('/video-stream-subtitle-frame/:token', async (req, res) =>
536 }
536 }
537});
537});
538
538
539// ---------------------------------------------------------------------------
540// GET /api/share/video-stream-subtitle-range/:token
541// Public. Returns rendered PNG subtitle bitmaps for a shared-video time range.
542// Query params: streamIndex, startTimeSeconds, endTimeSeconds, videoWidth, videoHeight
543// ---------------------------------------------------------------------------
544router.get('/video-stream-subtitle-range/:token', async (req, res) =>
545{
546 const requestReceivedAtMs = Date.now();
547 try
548 {
549 const token = String(req.params.token || '').trim();
550 const streamIndex = Number.parseInt(String(req.query.streamIndex || ''), 10);
551 const startTimeSeconds = Number.parseFloat(String(req.query.startTimeSeconds || ''), 10);
552 const endTimeSeconds = Number.parseFloat(String(req.query.endTimeSeconds || ''), 10);
553 const videoWidth = Number.parseInt(String(req.query.videoWidth || ''), 10);
554 const videoHeight = Number.parseInt(String(req.query.videoHeight || ''), 10);
555
556 if (!token || !Number.isInteger(streamIndex) || streamIndex < 0 || !Number.isFinite(startTimeSeconds) || startTimeSeconds < 0 || !Number.isFinite(endTimeSeconds) || endTimeSeconds <= startTimeSeconds)
557 {
558 return res.status(400).json({ error: 'token, streamIndex, startTimeSeconds, and endTimeSeconds are required.' });
559 }
560
561 const db = getDb();
562 const row = db.prepare('SELECT * FROM share_tokens WHERE token = ?').get([token]);
563 if (!row) return res.status(404).json({ error: 'Share link not found.' });
564 if (Date.now() > row.expires_at) return res.status(410).json({ error: 'Share link has expired.' });
565 if (row.is_dir) return res.status(400).json({ error: 'Cannot preview a directory.' });
566
567 if (!fs.existsSync(row.file_path) || fs.statSync(row.file_path).isDirectory())
568 {
569 return res.status(404).json({ error: 'File not found.' });
570 }
571
572 const canvasWidth = Number.isInteger(videoWidth) && videoWidth > 0 ? videoWidth : 1280;
573 const canvasHeight = Number.isInteger(videoHeight) && videoHeight > 0 ? videoHeight : 720;
574 const result = await renderImageSubtitleFramesInRange({
575 filePath: row.file_path,
576 streamIndex,
577 startTimeSeconds,
578 endTimeSeconds,
579 canvasWidth,
580 canvasHeight,
581 });
582
583 res.set('X-Subtitle-Request-Received-At-Ms', String(requestReceivedAtMs));
584 res.set('X-Subtitle-Response-Sent-At-Ms', String(Date.now()));
585 res.json({
586 status: 'ok',
587 startTimeSeconds,
588 endTimeSeconds,
589 frames: Array.isArray(result && result.frames)
590 ? result.frames.map((frame) => ({
591 left: frame.left || 0,
592 top: frame.top || 0,
593 width: frame.width || 0,
594 height: frame.height || 0,
595 canvasWidth: frame.canvasWidth || canvasWidth,
596 canvasHeight: frame.canvasHeight || canvasHeight,
597 startTimeSeconds: frame.startTimeSeconds || 0,
598 endTimeSeconds: frame.endTimeSeconds || 0,
599 contentType: 'image/png',
600 frameBase64: Buffer.from(frame.frame || Buffer.alloc(0)).toString('base64'),
601 }))
602 : [],
603 });
604 } catch (err)
605 {
606 logError('Shared subtitle range extraction failed', err, {
607 token: String(req.params.token || ''),
608 streamIndex: Number.parseInt(String(req.query.streamIndex || ''), 10),
609 startTimeSeconds: Number.parseFloat(String(req.query.startTimeSeconds || ''), 10),
610 endTimeSeconds: Number.parseFloat(String(req.query.endTimeSeconds || ''), 10),
611 });
612 res.set('X-Subtitle-Request-Received-At-Ms', String(requestReceivedAtMs));
613 res.set('X-Subtitle-Response-Sent-At-Ms', String(Date.now()));
614 return res.status(200).json({ status: 'error', frames: [] });
615 }
616});
617
539// ---------------------------------------------------------------------------
618// ---------------------------------------------------------------------------
540// POST /api/share/video-stream-subtitle-log/:token
619// POST /api/share/video-stream-subtitle-log/:token
541// Public. Persists client-side subtitle timing diagnostics for a share playback.
620// Public. Persists client-side subtitle timing diagnostics for a share playback.
tests/files.routes.test.js +60 −0
@@ -21,6 +21,8 @@ let mockVideoStreamAsset = null;
21 21 let releasedVideoStreamSessionId = null;
22 22 let mockSubtitleFrameResult = null;
23 23 let mockSubtitleFrameError = null;
24 let mockSubtitleRangeResult = null;
25 let mockSubtitleRangeError = null;
24 26 const mockSubtitleDebugLogDir = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
25 27
26 28 jest.mock('../server/db', () =>
@@ -129,6 +131,11 @@ jest.mock('../server/image-subtitles', () => ({
129 131 if (mockSubtitleFrameError) throw mockSubtitleFrameError;
130 132 return mockSubtitleFrameResult;
131 133 }),
134 renderImageSubtitleFramesInRange: jest.fn(async () =>
135 {
136 if (mockSubtitleRangeError) throw mockSubtitleRangeError;
137 return mockSubtitleRangeResult;
138 }),
132 139 }));
133 140
134 141 jest.mock('../server/subtitle-debug-log', () => ({
@@ -194,6 +201,8 @@ beforeEach(() =>
194 201 releasedVideoStreamSessionId = null;
195 202 mockSubtitleFrameResult = null;
196 203 mockSubtitleFrameError = null;
204 mockSubtitleRangeResult = null;
205 mockSubtitleRangeError = null;
197 206 const db = getDb();
198 207 db.prepare('DELETE FROM file_meta').run([]);
199 208 db.prepare('DELETE FROM users').run([]);
@@ -1311,6 +1320,57 @@ describe('video streaming routes', () =>
1311 1320 expect(body.length).toBe(0);
1312 1321 });
1313 1322
1323 test('GET /api/files/video-stream-subtitle-range returns rendered subtitle frames in JSON', async () =>
1324 {
1325 const filePath = path.join(rootDir, 'clip.mkv');
1326 fs.writeFileSync(filePath, 'video');
1327 mockSubtitleRangeResult = {
1328 frames: [
1329 {
1330 frame: Buffer.from('png-a'),
1331 left: 10,
1332 top: 20,
1333 width: 300,
1334 height: 90,
1335 canvasWidth: 640,
1336 canvasHeight: 360,
1337 startTimeSeconds: 2,
1338 endTimeSeconds: 4,
1339 },
1340 {
1341 frame: Buffer.from('png-b'),
1342 left: 12,
1343 top: 24,
1344 width: 320,
1345 height: 96,
1346 canvasWidth: 640,
1347 canvasHeight: 360,
1348 startTimeSeconds: 5,
1349 endTimeSeconds: 7,
1350 },
1351 ],
1352 };
1353
1354 const result = await req('GET', `/api/files/video-stream-subtitle-range?filePath=${encodeURIComponent(filePath)}&streamIndex=0&startTimeSeconds=2&endTimeSeconds=8&videoWidth=1920&videoHeight=1080`);
1355
1356 expect(result.status).toBe(200);
1357 expect(result.body.status).toBe('ok');
1358 expect(result.body.frames).toHaveLength(2);
1359 expect(result.body.frames[0]).toEqual(expect.objectContaining({
1360 left: 10,
1361 top: 20,
1362 width: 300,
1363 height: 90,
1364 canvasWidth: 640,
1365 canvasHeight: 360,
1366 startTimeSeconds: 2,
1367 endTimeSeconds: 4,
1368 contentType: 'image/png',
1369 frameBase64: Buffer.from('png-a').toString('base64'),
1370 }));
1371 expect(result.body.frames[1].frameBase64).toBe(Buffer.from('png-b').toString('base64'));
1372 });
1373
1314 1374 test('POST /api/files/watch-progress stores per-user watched status by thresholds', async () =>
1315 1375 {
1316 1376 const filePath = path.join(rootDir, 'clip.mkv');
@@ -21,6 +21,8 @@ let mockVideoStreamAsset = null;
21let releasedVideoStreamSessionId = null;
21let releasedVideoStreamSessionId = null;
22let mockSubtitleFrameResult = null;
22let mockSubtitleFrameResult = null;
23let mockSubtitleFrameError = null;
23let mockSubtitleFrameError = null;
24let mockSubtitleRangeResult = null;
25let mockSubtitleRangeError = null;
24const mockSubtitleDebugLogDir = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
26const mockSubtitleDebugLogDir = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
25
27
26jest.mock('../server/db', () =>
28jest.mock('../server/db', () =>
@@ -129,6 +131,11 @@ jest.mock('../server/image-subtitles', () => ({
129 if (mockSubtitleFrameError) throw mockSubtitleFrameError;
131 if (mockSubtitleFrameError) throw mockSubtitleFrameError;
130 return mockSubtitleFrameResult;
132 return mockSubtitleFrameResult;
131 }),
133 }),
134 renderImageSubtitleFramesInRange: jest.fn(async () =>
135 {
136 if (mockSubtitleRangeError) throw mockSubtitleRangeError;
137 return mockSubtitleRangeResult;
138 }),
132}));
139}));
133
140
134jest.mock('../server/subtitle-debug-log', () => ({
141jest.mock('../server/subtitle-debug-log', () => ({
@@ -194,6 +201,8 @@ beforeEach(() =>
194 releasedVideoStreamSessionId = null;
201 releasedVideoStreamSessionId = null;
195 mockSubtitleFrameResult = null;
202 mockSubtitleFrameResult = null;
196 mockSubtitleFrameError = null;
203 mockSubtitleFrameError = null;
204 mockSubtitleRangeResult = null;
205 mockSubtitleRangeError = null;
197 const db = getDb();
206 const db = getDb();
198 db.prepare('DELETE FROM file_meta').run([]);
207 db.prepare('DELETE FROM file_meta').run([]);
199 db.prepare('DELETE FROM users').run([]);
208 db.prepare('DELETE FROM users').run([]);
@@ -1311,6 +1320,57 @@ describe('video streaming routes', () =>
1311 expect(body.length).toBe(0);
1320 expect(body.length).toBe(0);
1312 });
1321 });
1313
1322
1323 test('GET /api/files/video-stream-subtitle-range returns rendered subtitle frames in JSON', async () =>
1324 {
1325 const filePath = path.join(rootDir, 'clip.mkv');
1326 fs.writeFileSync(filePath, 'video');
1327 mockSubtitleRangeResult = {
1328 frames: [
1329 {
1330 frame: Buffer.from('png-a'),
1331 left: 10,
1332 top: 20,
1333 width: 300,
1334 height: 90,
1335 canvasWidth: 640,
1336 canvasHeight: 360,
1337 startTimeSeconds: 2,
1338 endTimeSeconds: 4,
1339 },
1340 {
1341 frame: Buffer.from('png-b'),
1342 left: 12,
1343 top: 24,
1344 width: 320,
1345 height: 96,
1346 canvasWidth: 640,
1347 canvasHeight: 360,
1348 startTimeSeconds: 5,
1349 endTimeSeconds: 7,
1350 },
1351 ],
1352 };
1353
1354 const result = await req('GET', `/api/files/video-stream-subtitle-range?filePath=${encodeURIComponent(filePath)}&streamIndex=0&startTimeSeconds=2&endTimeSeconds=8&videoWidth=1920&videoHeight=1080`);
1355
1356 expect(result.status).toBe(200);
1357 expect(result.body.status).toBe('ok');
1358 expect(result.body.frames).toHaveLength(2);
1359 expect(result.body.frames[0]).toEqual(expect.objectContaining({
1360 left: 10,
1361 top: 20,
1362 width: 300,
1363 height: 90,
1364 canvasWidth: 640,
1365 canvasHeight: 360,
1366 startTimeSeconds: 2,
1367 endTimeSeconds: 4,
1368 contentType: 'image/png',
1369 frameBase64: Buffer.from('png-a').toString('base64'),
1370 }));
1371 expect(result.body.frames[1].frameBase64).toBe(Buffer.from('png-b').toString('base64'));
1372 });
1373
1314 test('POST /api/files/watch-progress stores per-user watched status by thresholds', async () =>
1374 test('POST /api/files/watch-progress stores per-user watched status by thresholds', async () =>
1315 {
1375 {
1316 const filePath = path.join(rootDir, 'clip.mkv');
1376 const filePath = path.join(rootDir, 'clip.mkv');
tests/image-subtitles.test.js +17 −1
@@ -3,7 +3,7 @@
3 3 const fs = require('fs');
4 4 const os = require('os');
5 5 const path = require('path');
6 const { parseRenderOptions, getImageSubtitleDebugSnapshot, purgeSubtitleCacheDir } = require('../server/image-subtitles');
6 const { parseRenderOptions, parseRenderRangeOptions, getImageSubtitleDebugSnapshot, purgeSubtitleCacheDir } = require('../server/image-subtitles');
7 7
8 8 describe('image subtitle option parsing', () =>
9 9 {
@@ -63,6 +63,22 @@ describe('image subtitle option parsing', () =>
63 63 expect(parsed.canvasHeight).toBe(400);
64 64 });
65 65
66 test('accepts valid subtitle range windows', () =>
67 {
68 const parsed = parseRenderRangeOptions({
69 filePath: '/tmp/example.mkv',
70 streamIndex: 0,
71 startTimeSeconds: 5,
72 endTimeSeconds: 10,
73 canvasWidth: 1920,
74 canvasHeight: 1080,
75 });
76
77 expect(parsed.startTimeSeconds).toBe(5);
78 expect(parsed.endTimeSeconds).toBe(10);
79 expect(parsed.isValid).toBe(true);
80 });
81
66 82 test('prune calculates drop threshold as end plus 5-second grace', () =>
67 83 {
68 84 // When a subtitle event ends at 30s, it should be dropped once the slowest
@@ -3,7 +3,7 @@
3const fs = require('fs');
3const fs = require('fs');
4const os = require('os');
4const os = require('os');
5const path = require('path');
5const path = require('path');
6const { parseRenderOptions, getImageSubtitleDebugSnapshot, purgeSubtitleCacheDir } = require('../server/image-subtitles');
6const { parseRenderOptions, parseRenderRangeOptions, getImageSubtitleDebugSnapshot, purgeSubtitleCacheDir } = require('../server/image-subtitles');
7
7
8describe('image subtitle option parsing', () =>
8describe('image subtitle option parsing', () =>
9{
9{
@@ -63,6 +63,22 @@ describe('image subtitle option parsing', () =>
63 expect(parsed.canvasHeight).toBe(400);
63 expect(parsed.canvasHeight).toBe(400);
64 });
64 });
65
65
66 test('accepts valid subtitle range windows', () =>
67 {
68 const parsed = parseRenderRangeOptions({
69 filePath: '/tmp/example.mkv',
70 streamIndex: 0,
71 startTimeSeconds: 5,
72 endTimeSeconds: 10,
73 canvasWidth: 1920,
74 canvasHeight: 1080,
75 });
76
77 expect(parsed.startTimeSeconds).toBe(5);
78 expect(parsed.endTimeSeconds).toBe(10);
79 expect(parsed.isValid).toBe(true);
80 });
81
66 test('prune calculates drop threshold as end plus 5-second grace', () =>
82 test('prune calculates drop threshold as end plus 5-second grace', () =>
67 {
83 {
68 // When a subtitle event ends at 30s, it should be dropped once the slowest
84 // When a subtitle event ends at 30s, it should be dropped once the slowest
tests/share.page.load.test.js +5 −0
@@ -84,6 +84,11 @@ describe('share page video preview', () =>
84 84 res.set('X-Subtitle-Frame-Status', 'none').status(204).end();
85 85 });
86 86
87 app.get('/api/share/video-stream-subtitle-range/:token', (req, res) =>
88 {
89 res.json({ status: 'ok', frames: [] });
90 });
91
87 92 app.delete('/api/share/video-stream/session/:sessionId', (req, res) =>
88 93 {
89 94 res.json({ ok: true });
@@ -84,6 +84,11 @@ describe('share page video preview', () =>
84 res.set('X-Subtitle-Frame-Status', 'none').status(204).end();
84 res.set('X-Subtitle-Frame-Status', 'none').status(204).end();
85 });
85 });
86
86
87 app.get('/api/share/video-stream-subtitle-range/:token', (req, res) =>
88 {
89 res.json({ status: 'ok', frames: [] });
90 });
91
87 app.delete('/api/share/video-stream/session/:sessionId', (req, res) =>
92 app.delete('/api/share/video-stream/session/:sessionId', (req, res) =>
88 {
93 {
89 res.json({ ok: true });
94 res.json({ ok: true });
tests/share.routes.test.js +52 −0
@@ -15,6 +15,8 @@ let mockVideoStreamAsset = null;
15 15 let releasedVideoStreamSessionId = null;
16 16 let mockSubtitleFrameResult = null;
17 17 let mockSubtitleFrameError = null;
18 let mockSubtitleRangeResult = null;
19 let mockSubtitleRangeError = null;
18 20
19 21 jest.mock('../server/db', () =>
20 22 {
@@ -88,6 +90,11 @@ jest.mock('../server/image-subtitles', () => ({
88 90 if (mockSubtitleFrameError) throw mockSubtitleFrameError;
89 91 return mockSubtitleFrameResult;
90 92 }),
93 renderImageSubtitleFramesInRange: jest.fn(async () =>
94 {
95 if (mockSubtitleRangeError) throw mockSubtitleRangeError;
96 return mockSubtitleRangeResult;
97 }),
91 98 }));
92 99
93 100 jest.mock('../server/logger', () => ({
@@ -155,6 +162,8 @@ beforeEach(() =>
155 162 releasedVideoStreamSessionId = null;
156 163 mockSubtitleFrameResult = null;
157 164 mockSubtitleFrameError = null;
165 mockSubtitleRangeResult = null;
166 mockSubtitleRangeError = null;
158 167 // Reset DB between tests
159 168 const db = getDb();
160 169 db.exec('DELETE FROM share_tokens');
@@ -425,6 +434,49 @@ describe('GET /api/share/video-stream/:token', () =>
425 434 expect(Buffer.from(await res.arrayBuffer()).equals(Buffer.from('png-data'))).toBe(true);
426 435 });
427 436
437 test('renders image subtitle frames for a shared video range request', async () =>
438 {
439 const filePath = path.join(rootDir, 'movie-subs.mkv');
440 fs.writeFileSync(filePath, 'video');
441 insertToken({ token: 'stream-subs-range', filePath });
442 mockSubtitleRangeResult = {
443 frames: [
444 {
445 frame: Buffer.from('png-a'),
446 left: 10,
447 top: 20,
448 width: 300,
449 height: 90,
450 canvasWidth: 640,
451 canvasHeight: 360,
452 startTimeSeconds: 2,
453 endTimeSeconds: 4,
454 },
455 ],
456 };
457
458 const res = await get('/api/share/video-stream-subtitle-range/stream-subs-range?streamIndex=0&startTimeSeconds=2&endTimeSeconds=8&videoWidth=1920&videoHeight=1080');
459
460 expect(res.status).toBe(200);
461 expect(await res.json()).toEqual(expect.objectContaining({
462 status: 'ok',
463 startTimeSeconds: 2,
464 endTimeSeconds: 8,
465 frames: [expect.objectContaining({
466 left: 10,
467 top: 20,
468 width: 300,
469 height: 90,
470 canvasWidth: 640,
471 canvasHeight: 360,
472 startTimeSeconds: 2,
473 endTimeSeconds: 4,
474 contentType: 'image/png',
475 frameBase64: Buffer.from('png-a').toString('base64'),
476 })],
477 }));
478 });
479
428 480 test('persists subtitle debug batches for shared video playback', async () =>
429 481 {
430 482 const filePath = path.join(rootDir, 'movie-subs.mkv');
@@ -15,6 +15,8 @@ let mockVideoStreamAsset = null;
15let releasedVideoStreamSessionId = null;
15let releasedVideoStreamSessionId = null;
16let mockSubtitleFrameResult = null;
16let mockSubtitleFrameResult = null;
17let mockSubtitleFrameError = null;
17let mockSubtitleFrameError = null;
18let mockSubtitleRangeResult = null;
19let mockSubtitleRangeError = null;
18
20
19jest.mock('../server/db', () =>
21jest.mock('../server/db', () =>
20{
22{
@@ -88,6 +90,11 @@ jest.mock('../server/image-subtitles', () => ({
88 if (mockSubtitleFrameError) throw mockSubtitleFrameError;
90 if (mockSubtitleFrameError) throw mockSubtitleFrameError;
89 return mockSubtitleFrameResult;
91 return mockSubtitleFrameResult;
90 }),
92 }),
93 renderImageSubtitleFramesInRange: jest.fn(async () =>
94 {
95 if (mockSubtitleRangeError) throw mockSubtitleRangeError;
96 return mockSubtitleRangeResult;
97 }),
91}));
98}));
92
99
93jest.mock('../server/logger', () => ({
100jest.mock('../server/logger', () => ({
@@ -155,6 +162,8 @@ beforeEach(() =>
155 releasedVideoStreamSessionId = null;
162 releasedVideoStreamSessionId = null;
156 mockSubtitleFrameResult = null;
163 mockSubtitleFrameResult = null;
157 mockSubtitleFrameError = null;
164 mockSubtitleFrameError = null;
165 mockSubtitleRangeResult = null;
166 mockSubtitleRangeError = null;
158 // Reset DB between tests
167 // Reset DB between tests
159 const db = getDb();
168 const db = getDb();
160 db.exec('DELETE FROM share_tokens');
169 db.exec('DELETE FROM share_tokens');
@@ -425,6 +434,49 @@ describe('GET /api/share/video-stream/:token', () =>
425 expect(Buffer.from(await res.arrayBuffer()).equals(Buffer.from('png-data'))).toBe(true);
434 expect(Buffer.from(await res.arrayBuffer()).equals(Buffer.from('png-data'))).toBe(true);
426 });
435 });
427
436
437 test('renders image subtitle frames for a shared video range request', async () =>
438 {
439 const filePath = path.join(rootDir, 'movie-subs.mkv');
440 fs.writeFileSync(filePath, 'video');
441 insertToken({ token: 'stream-subs-range', filePath });
442 mockSubtitleRangeResult = {
443 frames: [
444 {
445 frame: Buffer.from('png-a'),
446 left: 10,
447 top: 20,
448 width: 300,
449 height: 90,
450 canvasWidth: 640,
451 canvasHeight: 360,
452 startTimeSeconds: 2,
453 endTimeSeconds: 4,
454 },
455 ],
456 };
457
458 const res = await get('/api/share/video-stream-subtitle-range/stream-subs-range?streamIndex=0&startTimeSeconds=2&endTimeSeconds=8&videoWidth=1920&videoHeight=1080');
459
460 expect(res.status).toBe(200);
461 expect(await res.json()).toEqual(expect.objectContaining({
462 status: 'ok',
463 startTimeSeconds: 2,
464 endTimeSeconds: 8,
465 frames: [expect.objectContaining({
466 left: 10,
467 top: 20,
468 width: 300,
469 height: 90,
470 canvasWidth: 640,
471 canvasHeight: 360,
472 startTimeSeconds: 2,
473 endTimeSeconds: 4,
474 contentType: 'image/png',
475 frameBase64: Buffer.from('png-a').toString('base64'),
476 })],
477 }));
478 });
479
428 test('persists subtitle debug batches for shared video playback', async () =>
480 test('persists subtitle debug batches for shared video playback', async () =>
429 {
481 {
430 const filePath = path.join(rootDir, 'movie-subs.mkv');
482 const filePath = path.join(rootDir, 'movie-subs.mkv');
tests/shared-video-player.test.js +74 −0
@@ -387,6 +387,80 @@ describe('shared image subtitle prefetching', () =>
387 387 window.close();
388 388 });
389 389
390 test('prefetch can cache subtitle frames from a range request and render immediately', async () =>
391 {
392 const window = createWindow();
393 const helper = loadSharedVideoPlayer(window);
394 const { player, videojs } = buildPlayerHarness(window);
395 const requestedUrls = [];
396
397 player.duration(12);
398 player.setCurrentTime(2);
399
400 window.fetch = jest.fn(async (url) =>
401 {
402 const parsed = new URL(url, 'http://localhost/');
403 requestedUrls.push(parsed.pathname + parsed.search);
404
405 if (parsed.pathname === '/subtitle-range')
406 {
407 return new Response(JSON.stringify({
408 status: 'ok',
409 startTimeSeconds: Number(parsed.searchParams.get('startTimeSeconds')),
410 endTimeSeconds: Number(parsed.searchParams.get('endTimeSeconds')),
411 frames: [
412 {
413 left: 0,
414 top: 0,
415 width: 320,
416 height: 180,
417 canvasWidth: 640,
418 canvasHeight: 360,
419 startTimeSeconds: 2,
420 endTimeSeconds: 4,
421 contentType: 'image/png',
422 frameBase64: Buffer.from('png-data').toString('base64'),
423 },
424 ],
425 }), {
426 status: 200,
427 headers: { 'Content-Type': 'application/json' },
428 });
429 }
430
431 return new Response(null, {
432 status: 204,
433 headers: { 'X-Subtitle-Frame-Status': 'none' },
434 });
435 });
436
437 helper.bindImageSubtitleOverlay(player, videojs, {}, {
438 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
439 }, {
440 currentFetchEnabled: false,
441 cacheMissFallbackEnabled: false,
442 lookaheadSeconds: 0,
443 initialPrefetchSeconds: 0,
444 buildPrefetchRequest: ({ currentTime, endTime, streamIndex }) => ({
445 url: `/subtitle-range?streamIndex=${streamIndex}&startTimeSeconds=${currentTime}&endTimeSeconds=${endTime}`,
446 }),
447 buildFrameRequest: ({ currentTime, streamIndex }) => ({
448 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
449 }),
450 });
451
452 await flushAsyncWork(window, 10);
453
454 expect(requestedUrls.some((url) => url.startsWith('/subtitle-range'))).toBe(true);
455 expect(requestedUrls.some((url) => url.startsWith('/subtitle-frame'))).toBe(false);
456
457 const overlay = player.el().querySelector('.video-subtitle-overlay');
458 expect(overlay).toBeTruthy();
459 expect(overlay.style.display).toBe('block');
460
461 window.close();
462 });
463
390 464 test('prefetch uses furthest buffered end when player.bufferedEnd under-reports', async () =>
391 465 {
392 466 const window = createWindow();
@@ -387,6 +387,80 @@ describe('shared image subtitle prefetching', () =>
387 window.close();
387 window.close();
388 });
388 });
389
389
390 test('prefetch can cache subtitle frames from a range request and render immediately', async () =>
391 {
392 const window = createWindow();
393 const helper = loadSharedVideoPlayer(window);
394 const { player, videojs } = buildPlayerHarness(window);
395 const requestedUrls = [];
396
397 player.duration(12);
398 player.setCurrentTime(2);
399
400 window.fetch = jest.fn(async (url) =>
401 {
402 const parsed = new URL(url, 'http://localhost/');
403 requestedUrls.push(parsed.pathname + parsed.search);
404
405 if (parsed.pathname === '/subtitle-range')
406 {
407 return new Response(JSON.stringify({
408 status: 'ok',
409 startTimeSeconds: Number(parsed.searchParams.get('startTimeSeconds')),
410 endTimeSeconds: Number(parsed.searchParams.get('endTimeSeconds')),
411 frames: [
412 {
413 left: 0,
414 top: 0,
415 width: 320,
416 height: 180,
417 canvasWidth: 640,
418 canvasHeight: 360,
419 startTimeSeconds: 2,
420 endTimeSeconds: 4,
421 contentType: 'image/png',
422 frameBase64: Buffer.from('png-data').toString('base64'),
423 },
424 ],
425 }), {
426 status: 200,
427 headers: { 'Content-Type': 'application/json' },
428 });
429 }
430
431 return new Response(null, {
432 status: 204,
433 headers: { 'X-Subtitle-Frame-Status': 'none' },
434 });
435 });
436
437 helper.bindImageSubtitleOverlay(player, videojs, {}, {
438 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
439 }, {
440 currentFetchEnabled: false,
441 cacheMissFallbackEnabled: false,
442 lookaheadSeconds: 0,
443 initialPrefetchSeconds: 0,
444 buildPrefetchRequest: ({ currentTime, endTime, streamIndex }) => ({
445 url: `/subtitle-range?streamIndex=${streamIndex}&startTimeSeconds=${currentTime}&endTimeSeconds=${endTime}`,
446 }),
447 buildFrameRequest: ({ currentTime, streamIndex }) => ({
448 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
449 }),
450 });
451
452 await flushAsyncWork(window, 10);
453
454 expect(requestedUrls.some((url) => url.startsWith('/subtitle-range'))).toBe(true);
455 expect(requestedUrls.some((url) => url.startsWith('/subtitle-frame'))).toBe(false);
456
457 const overlay = player.el().querySelector('.video-subtitle-overlay');
458 expect(overlay).toBeTruthy();
459 expect(overlay.style.display).toBe('block');
460
461 window.close();
462 });
463
390 test('prefetch uses furthest buffered end when player.bufferedEnd under-reports', async () =>
464 test('prefetch uses furthest buffered end when player.bufferedEnd under-reports', async () =>
391 {
465 {
392 const window = createWindow();
466 const window = createWindow();