feat(recording-viewer): video subtitles + Open Folder button

Predixx · Predixx · commit 68ff6d0d7211 · 2026-04-13T09:15:16.000+02:00
Adds VTT/SRT subtitle support to the video player:
- Server endpoints GET/HEAD/PUT /api/recordings/:id/subtitles in vite.config.ts,
  with line-by-line SRT-&gt;VTT conversion, validation on both read and write paths,
  5 MB upload cap enforced during streaming, atomic write, and concurrency guard.
- Session list response now includes hasSubtitles per session.
- VideoPlayer renders &lt;track kind="subtitles"&gt; when subtitlesUrl is provided and
  exposes a showSubtitles() handle method to force-activate the track after
  re-uploads (where the `default` attribute alone is not enough).
- New SubtitleUpload component mirrors VideoUpload (.srt/.vtt accepted).
- Session table gets a Subtitles column.

Also adds an "Open Folder" button to the session-detail header so the session
folder is reachable without going back to the session list.
diff --git a/recording-viewer/src/App.css b/recording-viewer/src/App.css
@@ -76,7 +76,7 @@
 
 .session-table-header {
     display: grid;
-    grid-template-columns: 2fr 1fr 1.5fr 1fr 0.7fr 0.6fr 0.6fr 90px;
+    grid-template-columns: 2fr 1fr 1.5fr 1fr 0.7fr 0.6fr 0.6fr 0.6fr 90px;
     gap: 12px;
     padding: 8px 12px;
     font-size: 11px;
@@ -89,7 +89,7 @@
 
 .session-table-row {
     display: grid;
-    grid-template-columns: 2fr 1fr 1.5fr 1fr 0.7fr 0.6fr 0.6fr 90px;
+    grid-template-columns: 2fr 1fr 1.5fr 1fr 0.7fr 0.6fr 0.6fr 0.6fr 90px;
     align-items: center;
     gap: 12px;
     padding: 10px 12px;
@@ -213,6 +213,11 @@
     letter-spacing: -0.5px;
 }
 
+.header-actions {
+    display: flex;
+    gap: 8px;
+}
+
 .reset-btn {
     font-family: var(--sans);
     font-size: 13px;
diff --git a/recording-viewer/src/App.tsx b/recording-viewer/src/App.tsx
@@ -10,6 +10,7 @@ import { TrackingTimeline } from './components/TrackingTimeline';
 import { VideoPlayer } from './components/VideoPlayer';
 import type { VideoPlayerHandle } from './components/VideoPlayer';
 import { VideoUpload } from './components/VideoUpload';
+import { SubtitleUpload } from './components/SubtitleUpload';
 import { OffsetConfig } from './components/OffsetConfig';
 import { FreeAnnotationForm } from './components/FreeAnnotationForm';
 import { ALL_EVENT_TYPES } from './constants';
@@ -24,6 +25,7 @@ function App() {
 
     // Video state
     const [videoSyncConfig, setVideoSyncConfig] = useState<VideoSyncConfig | null>(null);
+    const [hasSubtitles, setHasSubtitles] = useState(false);
     const [isVideoPlaying, setIsVideoPlaying] = useState(false);
     const [videoCacheBust, setVideoCacheBust] = useState(0);
     const videoTimeRef = useRef<number>(0);
@@ -64,12 +66,13 @@ function App() {
         setViewMode('timeline');
         setScrollToTimestamp(null);
         try {
-            const [eventsRes, metaRes, replayRes, annotRes, videoSyncRes] = await Promise.all([
+            const [eventsRes, metaRes, replayRes, annotRes, videoSyncRes, subsRes] = await Promise.all([
                 fetch(`/api/recordings/${sessionId}/events`),
                 fetch(`/api/recordings/${sessionId}/metadata`),
                 fetch(`/api/recordings/${sessionId}/replay-eq`),
                 fetch(`/api/recordings/${sessionId}/annotations`),
                 fetch(`/api/recordings/${sessionId}/video-sync`),
+                fetch(`/api/recordings/${sessionId}/subtitles`, { method: 'HEAD' }),
             ]);
 
             const events: RecordedEvent[] = await eventsRes.json();
@@ -94,6 +97,7 @@ function App() {
             activeSessionId.current = sessionId;
             setAnnotations(loadedAnnotations);
             setVideoSyncConfig(syncConfig);
+            setHasSubtitles(subsRes.ok);
             setVideoCacheBust(Date.now());
             setIsVideoPlaying(false);
             videoTimeRef.current = 0;
@@ -110,6 +114,7 @@ function App() {
         activeSessionId.current = null;
         setAnnotations([]);
         setVideoSyncConfig(null);
+        setHasSubtitles(false);
         setIsVideoPlaying(false);
         videoTimeRef.current = 0;
         setViewMode('timeline');
@@ -122,6 +127,7 @@ function App() {
         activeSessionId.current = null;
         setAnnotations([]);
         setVideoSyncConfig(null);
+        setHasSubtitles(false);
         setIsVideoPlaying(false);
         videoTimeRef.current = 0;
         setViewMode('timeline');
@@ -143,6 +149,19 @@ function App() {
         setVideoCacheBust(Date.now());
     }, []);
 
+    const handleSubtitleUploadComplete = useCallback(() => {
+        setHasSubtitles(true);
+        setVideoCacheBust(Date.now());
+        // `<track>` is remounted via React key change; force-activate after new load.
+        requestAnimationFrame(() => videoPlayerRef.current?.showSubtitles());
+    }, []);
+
+    const handleOpenSessionFolder = useCallback(() => {
+        if (!activeSessionId.current) return;
+        fetch(`/api/recordings/${encodeURIComponent(activeSessionId.current)}/open`, { method: 'POST' })
+            .catch(() => {/* best-effort */});
+    }, []);
+
     const handleOffsetChange = useCallback(async (newOffset: number) => {
         if (!activeSessionId.current || !videoSyncConfig) return;
         const updated = { ...videoSyncConfig, videoTimeAtSessionStartSeconds: newOffset };
@@ -256,14 +275,25 @@ function App() {
         ? `/api/recordings/${encodeURIComponent(activeSessionId.current)}/video?v=${videoCacheBust}`
         : null;
 
+    const subtitlesUrl = activeSessionId.current && hasSubtitles
+        ? `/api/recordings/${encodeURIComponent(activeSessionId.current)}/subtitles?v=${videoCacheBust}`
+        : null;
+
     return (
         <div className="app">
             <header className="app-header">
                 <h1>Artemis Extension Session Analyzer</h1>
                 {session && (
-                    <button className="reset-btn" onClick={handleBack}>
-                        &larr; Back
-                    </button>
+                    <div className="header-actions">
+                        {activeSessionId.current && (
+                            <button className="reset-btn" onClick={handleOpenSessionFolder} title="Open session folder in Finder">
+                                Open Folder
+                            </button>
+                        )}
+                        <button className="reset-btn" onClick={handleBack}>
+                            &larr; Back
+                        </button>
+                    </div>
                 )}
             </header>
 
@@ -292,6 +322,7 @@ function App() {
                                 sessionEndTime={sessionEndTime}
                                 videoTimeAtSessionStartSeconds={videoSyncConfig.videoTimeAtSessionStartSeconds}
                                 videoUrl={videoUrl}
+                                subtitlesUrl={subtitlesUrl}
                                 videoTimeRef={videoTimeRef}
                                 onPlayStateChange={handleVideoPlayStateChange}
                             />
@@ -305,6 +336,11 @@ function App() {
                                     hasVideo={true}
                                     onUploadComplete={handleVideoUploadComplete}
                                 />
+                                <SubtitleUpload
+                                    sessionId={activeSessionId.current}
+                                    hasSubtitles={hasSubtitles}
+                                    onUploadComplete={handleSubtitleUploadComplete}
+                                />
                             </div>
                         </div>
                     )}
diff --git a/recording-viewer/src/components/SessionList.tsx b/recording-viewer/src/components/SessionList.tsx
@@ -7,6 +7,7 @@ interface SessionEntry {
     metadata: SessionMetadata | null;
     hasReplay: boolean;
     hasVideo: boolean;
+    hasSubtitles: boolean;
 }
 
 interface SessionListResponse {
@@ -143,6 +144,7 @@ export function SessionList({ onSelectSession }: Props) {
                     <span>Events</span>
                     <span>Replay</span>
                     <span>Video</span>
+                    <span>Subtitles</span>
                     <span></span>
                 </div>
                 {data.sessions.map(entry => (
@@ -183,6 +185,9 @@ export function SessionList({ onSelectSession }: Props) {
                         <span className={`replay-indicator ${entry.hasVideo ? 'has-replay' : ''}`}>
                             {entry.hasVideo ? 'Yes' : '—'}
                         </span>
+                        <span className={`replay-indicator ${entry.hasSubtitles ? 'has-replay' : ''}`}>
+                            {entry.hasSubtitles ? 'Yes' : '—'}
+                        </span>
                         <span className="session-actions">
                             <button
                                 className="action-btn rename-btn"
diff --git a/recording-viewer/src/components/SubtitleUpload.tsx b/recording-viewer/src/components/SubtitleUpload.tsx
@@ -0,0 +1,79 @@
+import { useRef, useState, useCallback } from 'react';
+
+interface Props {
+    sessionId: string;
+    hasSubtitles: boolean;
+    onUploadComplete: () => void;
+}
+
+type UploadState = 'idle' | 'uploading' | 'done' | 'error';
+
+function contentTypeFor(file: File): string {
+    if (file.type === 'text/vtt' || file.name.toLowerCase().endsWith('.vtt')) return 'text/vtt';
+    if (file.type === 'application/x-subrip' || file.name.toLowerCase().endsWith('.srt')) return 'application/x-subrip';
+    return 'text/plain';
+}
+
+export function SubtitleUpload({ sessionId, hasSubtitles, onUploadComplete }: Props) {
+    const inputRef = useRef<HTMLInputElement>(null);
+    const [state, setState] = useState<UploadState>('idle');
+    const [errorMsg, setErrorMsg] = useState('');
+
+    const handleFile = useCallback(async (file: File) => {
+        const name = file.name.toLowerCase();
+        if (!name.endsWith('.srt') && !name.endsWith('.vtt')) {
+            setState('error');
+            setErrorMsg('Only .srt and .vtt files are supported');
+            return;
+        }
+
+        setState('uploading');
+        setErrorMsg('');
+
+        try {
+            const res = await fetch(`/api/recordings/${encodeURIComponent(sessionId)}/subtitles`, {
+                method: 'PUT',
+                headers: { 'Content-Type': contentTypeFor(file) },
+                body: file,
+            });
+
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: 'Upload failed' }));
+                throw new Error(err.error || 'Upload failed');
+            }
+
+            setState('done');
+            onUploadComplete();
+            setTimeout(() => setState('idle'), 2000);
+        } catch (err) {
+            setState('error');
+            setErrorMsg(err instanceof Error ? err.message : 'Upload failed');
+        }
+    }, [sessionId, onUploadComplete]);
+
+    return (
+        <div className="video-upload">
+            <input
+                ref={inputRef}
+                type="file"
+                accept=".srt,.vtt,text/vtt,application/x-subrip"
+                style={{ display: 'none' }}
+                onChange={e => {
+                    const file = e.target.files?.[0];
+                    if (file) handleFile(file);
+                    e.target.value = '';
+                }}
+            />
+            <button
+                className="video-upload-btn"
+                onClick={() => inputRef.current?.click()}
+                disabled={state === 'uploading'}
+            >
+                {state === 'uploading' ? 'Uploading...' :
+                 state === 'done' ? 'Uploaded!' :
+                 hasSubtitles ? 'Replace subtitles' : 'Upload subtitles'}
+            </button>
+            {state === 'error' && <span className="video-upload-error">{errorMsg}</span>}
+        </div>
+    );
+}
diff --git a/recording-viewer/src/components/VideoPlayer.tsx b/recording-viewer/src/components/VideoPlayer.tsx
@@ -4,13 +4,15 @@ export interface VideoPlayerHandle {
     seekToSessionTimestamp(ts: number): void;
     getCurrentSessionTimestamp(): number;
     isPaused(): boolean;
+    showSubtitles(): void;
 }
 
 interface Props {
     sessionStartTime: number;
     sessionEndTime: number;
     videoTimeAtSessionStartSeconds: number;
     videoUrl: string;
+    subtitlesUrl?: string | null;
     videoTimeRef: React.RefObject<number>;
     onPlayStateChange: (isPlaying: boolean) => void;
 }
@@ -23,7 +25,7 @@ function formatVideoTime(seconds: number): string {
 }
 
 export const VideoPlayer = forwardRef<VideoPlayerHandle, Props>(function VideoPlayer(
-    { sessionStartTime, sessionEndTime, videoTimeAtSessionStartSeconds, videoUrl, videoTimeRef, onPlayStateChange },
+    { sessionStartTime, sessionEndTime, videoTimeAtSessionStartSeconds, videoUrl, subtitlesUrl, videoTimeRef, onPlayStateChange },
     ref,
 ) {
     const videoRef = useRef<HTMLVideoElement>(null);
@@ -61,6 +63,18 @@ export const VideoPlayer = forwardRef<VideoPlayerHandle, Props>(function VideoPl
         isPaused() {
             return videoRef.current?.paused ?? true;
         },
+        showSubtitles() {
+            const video = videoRef.current;
+            if (!video) return;
+            // Force-activate the subtitles track. `default` attribute is only a hint
+            // at first paint; switching it on after a new upload needs explicit mode = 'showing'.
+            for (let i = 0; i < video.textTracks.length; i++) {
+                const t = video.textTracks[i];
+                if (t.kind === 'subtitles' || t.kind === 'captions') {
+                    t.mode = 'showing';
+                }
+            }
+        },
     }), [sessionToVideoTime, videoTimeToSession]);
 
     // Frame callback: update videoTimeRef with current session timestamp
@@ -194,7 +208,18 @@ export const VideoPlayer = forwardRef<VideoPlayerHandle, Props>(function VideoPl
                 onPlay={handlePlayPause}
                 onPause={handlePlayPause}
                 preload="metadata"
-            />
+            >
+                {subtitlesUrl && (
+                    <track
+                        key={subtitlesUrl}
+                        kind="subtitles"
+                        src={subtitlesUrl}
+                        srcLang="und"
+                        label="Transcript"
+                        default
+                    />
+                )}
+            </video>
             <div className="video-controls">
                 <button className="video-play-btn" onClick={togglePlay} title={playing ? 'Pause' : 'Play'}>
                     {playing ? '\u23F8' : '\u25B6'}
diff --git a/recording-viewer/vite.config.ts b/recording-viewer/vite.config.ts
