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.
@@ -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.
@@ -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;116
const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 15;116
const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 15;117
const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS = 60;117
const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS = 60;118
const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS = 40;118
const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS = 40;119
const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR = 1;119
const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR = 3;120
const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR = 5;120
const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR = 10;121
let videoJsLoaderPromise = null;121
let videoJsLoaderPromise = null;122
let threePreviewModulesPromise = null;122
let 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(),@@ -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
598
async function renderImageSubtitleFrame (options)598
function 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);618
async 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
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
recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);695
recordDuration(subtitleDebugStats.frameRequestDurationMs, requestStartedAt);665
return cacheValue;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
function deleteSupFileForKey (identityKey)753
function deleteSupFileForKey (identityKey)669
{754
{670
const cacheKey = eventCacheFileKey(identityKey);755
const cacheKey = eventCacheFileKey(identityKey);@@ -893,7 +978,9 @@ function getImageSubtitleDebugSnapshot ()893
978
894
module.exports = {979
module.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,@@ -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('.12
const { requireAuth } = require('../auth');12
const { requireAuth } = require('../auth');13
const { getCachedThumbnailInfo, getFilesWithThumbnailsInDir, getFolderIconSourceFile, setFolderIconAssignment } = require('../thumbnail-cache');13
const { getCachedThumbnailInfo, getFilesWithThumbnailsInDir, getFolderIconSourceFile, setFolderIconAssignment } = require('../thumbnail-cache');14
const { logError } = require('../logger');14
const { logError } = require('../logger');15
const { renderImageSubtitleFrame } = require('../image-subtitles');15
const { renderImageSubtitleFrame, renderImageSubtitleFramesInRange } = require('../image-subtitles');16
const { appendSubtitleDebugEntries, SUBTITLE_DEBUG_LOG_DIR } = require('../subtitle-debug-log');16
const { appendSubtitleDebugEntries, SUBTITLE_DEBUG_LOG_DIR } = require('../subtitle-debug-log');17
const { buildZip } = require('./share');17
const { buildZip } = require('./share');18
const { createVideoStreamSession, sendVideoStreamAsset, releaseVideoStreamSession } = require('../video-stream');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-range1806
// Authenticated. Returns rendered PNG subtitle bitmaps overlapping a time range.1807
// Query params: filePath, streamIndex, startTimeSeconds, endTimeSeconds1808
// ---------------------------------------------------------------------------1809
router.get('/video-stream-subtitle-range', requireAuth, async (req, res) =>1810
{1811
const requestReceivedAtMs = Date.now();1812
try1813
{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-log1885
// POST /api/files/video-stream-subtitle-log1806
// Authenticated. Persists client-side subtitle timing diagnostics to local cache.1886
// Authenticated. Persists client-side subtitle timing diagnostics to local cache.@@ -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;21
let releasedVideoStreamSessionId = null;21
let releasedVideoStreamSessionId = null;22
let mockSubtitleFrameResult = null;22
let mockSubtitleFrameResult = null;23
let mockSubtitleFrameError = null;23
let mockSubtitleFrameError = null;24
let mockSubtitleRangeResult = null;25
let mockSubtitleRangeError = null;24
const mockSubtitleDebugLogDir = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');26
const mockSubtitleDebugLogDir = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');25
27
26
jest.mock('../server/db', () =>28
jest.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
134
jest.mock('../server/subtitle-debug-log', () => ({141
jest.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');@@ -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 @@3
const fs = require('fs');3
const fs = require('fs');4
const os = require('os');4
const os = require('os');5
const path = require('path');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
describe('image subtitle option parsing', () =>8
describe('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 slowest84
// When a subtitle event ends at 30s, it should be dropped once the slowest