fix(playback): load original recordings before requesting conversion

Serve original recording bytes without codec probing or transcoding by default. Recording, timeline, and investigation players attempt native playback and request a bounded compatibility conversion only after a browser decode or unsupported-format error. Keep network and aborted loads out of the conversion path and cancel stale fallback polling.

Verify actual timeline decoding, seeking, playback, and fallback cancellation with a playable MP4 fixture and range responses. Validation: 8 playback-handler C cases, 15 playback JavaScript cases, 18 browser regression cases, and an HTTP check that HEVC playback serves original bytes/ranges without FFmpeg.

Author: matteius

docs/API.md

@@ -836,21 +836,24 @@ Deletes a recording.
 GET /api/recordings/play/{id}
 ```
 
-Streams a recording for playback with byte-range support. HEVC recordings use
-a cached H.264 copy prepared by a single background transcode worker.
+Streams the original recording immediately with byte-range support. Normal
+playback does not probe or convert the video, including HEVC recordings.
 
-Before loading the media URL, poll `GET /api/recordings/play/{id}?prepare=1`:
+If a browser rejects the original with a decode or unsupported-format error,
+it can request a compatible H.264 copy by polling
+`GET /api/recordings/play/{id}?prepare=1`:
 
-- `200` with `{"status":"ready"}`: load the media URL without `prepare=1`.
+- `200` with `{"status":"ready"}`: load `/api/recordings/play/{id}?transcode=1`.
 - `202` with `{"status":"preparing"}`: wait for the `Retry-After` interval and poll again.
 - `500`: preparation failed; the JSON `error` explains the failure. The original
   recording remains available from the download endpoint.
 
-Preparation uses the same replay authorization as playback. A media request
-made while conversion is pending returns `503` with `Retry-After`; it does not
-hold an HTTP worker open for the conversion. H.264 recordings and completed
-cache entries are ready immediately. Clients should stop polling when playback
-is closed or another recording is selected.
+Preparation uses the same replay authorization as playback and retains a single
+background conversion worker. A `transcode=1` request made while conversion is
+pending returns `503` with `Retry-After`; original playback remains available.
+H.264 recordings and completed cache entries are ready immediately. Clients
+should stop polling when playback is closed or another recording is selected,
+and should not request conversion for a network error or aborted media load.
 
 #### Download Recording
 

include/web/api_handlers_recordings_playback.h

@@ -6,10 +6,10 @@
 /**
  * @brief Backend-agnostic handler for GET /api/recordings/play/:id
  *
- * Serves a recording file for playback with range request support for seeking.
- * With ?prepare=1, returns JSON: 200 when ready or 202 with Retry-After while
- * a bounded background transcode is pending. Media requests made before the
- * cache is ready return 503 with Retry-After instead of blocking an HTTP worker.
+ * Serves the original recording with range support, without probing or encoding.
+ * For browsers that reject it, ?prepare=1 requests a compatibility copy and
+ * returns JSON: 200 when ready or 202 with Retry-After while pending. Load the
+ * prepared media using ?transcode=1 (503 with Retry-After if not yet ready).
  *
  * @param req HTTP request
  * @param res HTTP response

src/web/api_handlers_recordings_playback.c

@@ -81,39 +81,45 @@ void handle_recordings_playback(const http_request_t *req, http_response_t *res)
 
     log_info("Serving file for playback: %s (%ld bytes)", recording.file_path, st.st_size);
 
-    // The modal polls ?prepare=1 before attaching the media URL. Never wait
-    // for an encode in a libuv worker: enough duplicate/range requests would
-    // starve both other APIs and the filesystem reads used to serve videos.
+    // Direct playback always serves the original. Only clients that cannot
+    // decode it request the compatibility copy; HEVC alone does not imply
+    // that a browser needs a transcode.
     char prepare[8];
     bool prepare_only = http_request_get_query_param(req, "prepare", prepare,
                                                      sizeof(prepare)) > 0 &&
                         strcmp(prepare, "1") == 0;
+    char transcode[8];
+    bool compatibility_requested = prepare_only ||
+        (http_request_get_query_param(req, "transcode", transcode, sizeof(transcode)) > 0 &&
+         strcmp(transcode, "1") == 0);
 
     const char *serve_path = recording.file_path;
     char transcode_cache_path[MAX_PATH_LENGTH];
-    bool have_cache_path = build_recording_transcode_cache_path(
-        g_config.storage_path, id, transcode_cache_path,
-        sizeof(transcode_cache_path)) == 0;
-    struct stat cache_st;
-    if (have_cache_path && stat(transcode_cache_path, &cache_st) == 0 &&
-        S_ISREG(cache_st.st_mode) && cache_st.st_size > 0) {
-        serve_path = transcode_cache_path;
-    } else if (recording_needs_hevc_transcode(recording.file_path)) {
-        recording_transcode_status_t status = have_cache_path
-            ? request_recording_transcode_cache(recording.file_path, transcode_cache_path)
-            : RECORDING_TRANSCODE_FAILED;
-        if (status == RECORDING_TRANSCODE_PENDING) {
-            http_response_add_header(res, "Retry-After", "2");
-            http_response_set_json(res, prepare_only ? 202 : 503,
-                                   "{\"status\":\"preparing\"}");
-            return;
+    if (compatibility_requested) {
+        bool have_cache_path = build_recording_transcode_cache_path(
+            g_config.storage_path, id, transcode_cache_path,
+            sizeof(transcode_cache_path)) == 0;
+        struct stat cache_st;
+        if (have_cache_path && stat(transcode_cache_path, &cache_st) == 0 &&
+            S_ISREG(cache_st.st_mode) && cache_st.st_size > 0) {
+            serve_path = transcode_cache_path;
+        } else if (recording_needs_hevc_transcode(recording.file_path)) {
+            recording_transcode_status_t status = have_cache_path
+                ? request_recording_transcode_cache(recording.file_path, transcode_cache_path)
+                : RECORDING_TRANSCODE_FAILED;
+            if (status == RECORDING_TRANSCODE_PENDING) {
+                http_response_add_header(res, "Retry-After", "2");
+                http_response_set_json(res, prepare_only ? 202 : 503,
+                                       "{\"status\":\"preparing\"}");
+                return;
+            }
+            if (status == RECORDING_TRANSCODE_FAILED) {
+                http_response_set_json_error(res, 500,
+                    "Unable to prepare recording for playback. Download the original or try again later.");
+                return;
+            }
+            serve_path = transcode_cache_path;
         }
-        if (status == RECORDING_TRANSCODE_FAILED) {
-            http_response_set_json_error(res, 500,
-                "Unable to prepare recording for playback. Download the original or try again later.");
-            return;
-        }
-        serve_path = transcode_cache_path;
     }
 
     if (prepare_only) {

tests/integration/fixtures/recording-media.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Route } from '@playwright/test';
+
+// Ten minutes of blue, 64x64 H.264 at 1 fps. Long enough for timeline seeks,
+// small enough to serve inline, and decodable without cameras or local FFmpeg.
+// Generated with: ffmpeg -f lavfi -i color=c=blue:size=64x64:rate=1:duration=600
+//   -c:v libx264 -threads 1 -pix_fmt yuv420p -movflags +faststart recording.mp4
+export const PLAYABLE_RECORDING_MP4 = readFileSync(join(__dirname, 'recording.mp4'));
+
+// Match the production file server's range contract so Chromium exposes a
+// seekable duration; an empty media response cannot test timeline seeking.
+export function serveRecordingMedia(route: Route) {
+  const range = route.request().headers().range?.match(/^bytes=(\d+)-(\d*)$/);
+  const headers: Record<string, string> = { 'Accept-Ranges': 'bytes' };
+  let body = PLAYABLE_RECORDING_MP4;
+  if (range) {
+    const start = Number(range[1]);
+    const end = Math.min(range[2] ? Number(range[2]) : body.length - 1, body.length - 1);
+    headers['Content-Range'] = `bytes ${start}-${end}/${body.length}`;
+    body = body.subarray(start, end + 1);
+  }
+  return route.fulfill({ status: range ? 206 : 200, contentType: 'video/mp4', headers, body });
+}

tests/integration/fixtures/recording.mp4

@@ -8,6 +8,7 @@
 import { test, expect } from '@playwright/test';
 import { RecordingsPage } from '../pages/RecordingsPage';
 import { USERS, login, sleep } from '../fixtures/test-fixtures';
+import { serveRecordingMedia } from '../fixtures/recording-media';
 
 type MockRecording = {
   id: number;
@@ -316,18 +317,15 @@ test.describe('Recordings Page @ui @recordings', () => {
         }],
         pagination: { total: 1, pages: 1, limit: 20 }
       } }));
-      let prepared = false;
       let preparationRequests = 0;
       await page.route('**/api/recordings/play/601*', route => {
         if (new URL(route.request().url()).searchParams.has('prepare')) {
           preparationRequests++;
           return route.fulfill({
-            status: prepared ? 200 : 202,
-            headers: { 'Retry-After': '1' },
-            json: { status: prepared ? 'ready' : 'preparing' },
+            json: { status: 'ready' },
           });
         }
-        return route.fulfill({ status: 204, body: '' });
+        return serveRecordingMedia(route);
       });
       await page.route('**/api/recordings/601', route => route.fulfill({ json: {
         id: 601,
@@ -356,13 +354,12 @@ test.describe('Recordings Page @ui @recordings', () => {
       await page.locator('button[title="Play"]').first().click();
 
       const modal = page.locator('#video-preview-modal');
-      await expect(modal.getByRole('status')).toHaveText('Preparing recording for playback…');
-      await expect(modal.locator('video')).not.toHaveAttribute('src');
+      await expect.poll(() => modal.locator('video').evaluate((video: HTMLVideoElement) => video.videoWidth)).toBe(64);
+      expect(preparationRequests).toBe(0);
       await modal.locator('button.close').click();
       const requestsAtClose = preparationRequests;
       await page.waitForTimeout(1200);
       expect(preparationRequests).toBe(requestsAtClose);
-      prepared = true;
       await page.locator('button[title="Play"]').first().click();
       await expect(modal.locator('video')).toHaveAttribute('src', '/api/recordings/play/601');
 

tests/integration/specs/recordings.ui.spec.ts

@@ -1,6 +1,7 @@
 import { test, expect, Page } from '@playwright/test';
 import { login, USERS } from '../fixtures/test-fixtures';
 import { TimelinePage } from '../pages/TimelinePage';
+import { serveRecordingMedia } from '../fixtures/recording-media';
 
 type Segment = { id: number; stream: string; start_timestamp: number; end_timestamp: number };
 
@@ -268,7 +269,34 @@ test.describe('Timeline boundary flows @ui @timeline', () => {
     await expect(timelinePage.nextRecordingButton).toBeDisabled();
   });
 
-  test('waits for playback preparation and cancels polling when switching recordings', async ({ page }) => {
+  test('plays and seeks the original recording without preparing a copy', async ({ page }) => {
+    const stream = 'front_door';
+    const date = '2026-03-08';
+    const segments: Segment[] = [
+      { id: 320, stream, start_timestamp: localTimestamp(date, '11:00:00'), end_timestamp: localTimestamp(date, '11:10:00') }
+    ];
+    await mockTimelineApis(page, stream, segments);
+    const playbackRequests: string[] = [];
+    await page.route('**/api/recordings/play/*', route => {
+      playbackRequests.push(route.request().url());
+      return serveRecordingMedia(route);
+    });
+    await page.goto(`/timeline.html?stream=${stream}&date=${date}&time=11:02:00`, { waitUntil: 'domcontentloaded' });
+    const timelinePage = new TimelinePage(page);
+    await expect.poll(() => timelinePage.videoPlayer.evaluate((video: HTMLVideoElement) => video.videoWidth)).toBe(64);
+    await expect.poll(() => timelinePage.videoPlayer.evaluate((video: HTMLVideoElement) => Math.round(video.currentTime))).toBe(120);
+    await timelinePage.videoPlayer.evaluate(async (video: HTMLVideoElement) => {
+      video.muted = true;
+      await video.play();
+    });
+    await expect.poll(() => timelinePage.videoPlayer.evaluate((video: HTMLVideoElement) => video.currentTime)).toBeGreaterThan(120);
+    expect(playbackRequests.length).toBeGreaterThan(0);
+    expect(playbackRequests.every(url => !new URL(url).searchParams.has('prepare') &&
+      !new URL(url).searchParams.has('transcode'))).toBe(true);
+    await expect(timelinePage.videoContainer.getByRole('status')).toHaveCount(0);
+  });
+
+  test('prepares only rejected recordings and cancels fallback when switching recordings', async ({ page }) => {
     const stream = 'front_door';
     const date = '2026-03-08';
     const segments: Segment[] = [
@@ -278,7 +306,7 @@ test.describe('Timeline boundary flows @ui @timeline', () => {
     ];
     await mockTimelineApis(page, stream, segments);
     const preparations: number[] = [];
-    const mediaRequests: number[] = [];
+    const mediaRequests: Array<{ id: number; transcode: boolean }> = [];
     let firstReady = false;
     await page.route('**/api/recordings/play/*', route => {
       const url = new URL(route.request().url());
@@ -292,22 +320,28 @@ test.describe('Timeline boundary flows @ui @timeline', () => {
           json: { status: ready ? 'ready' : 'preparing' }
         });
       }
-      mediaRequests.push(id);
-      return route.fulfill({ status: 204, body: '' });
+      const transcode = url.searchParams.get('transcode') === '1';
+      mediaRequests.push({ id, transcode });
+      if (transcode || id === 323) return serveRecordingMedia(route);
+      return route.fulfill({
+        contentType: 'video/mp4',
+        body: Buffer.from('unsupported video')
+      });
     });
     await page.goto(`/timeline.html?stream=${stream}&date=${date}&time=11:00:00`, { waitUntil: 'domcontentloaded' });
 
     const timelinePage = new TimelinePage(page);
     const status = timelinePage.videoContainer.getByRole('status');
-    await expect(status).toHaveText('Preparing recording for playback…');
+    await expect(status).toHaveText('Preparing a compatible version for this browser…');
     await expect(timelinePage.videoPlayer).not.toHaveAttribute('src');
-    expect(mediaRequests).toEqual([]);
+    expect(mediaRequests).toEqual([{ id: 321, transcode: false }]);
     firstReady = true;
     await expect(timelinePage.videoPlayer).toHaveAttribute('src', /\/api\/recordings\/play\/321(?:\?|$)/);
+    await expect.poll(() => timelinePage.videoPlayer.evaluate((video: HTMLVideoElement) => video.videoWidth)).toBe(64);
     expect(preparations.filter(id => id === 321).length).toBeGreaterThanOrEqual(2);
 
     await timelinePage.nextRecordingButton.click();
-    await expect(status).toHaveText('Preparing recording for playback…');
+    await expect(status).toHaveText('Preparing a compatible version for this browser…');
     await expect(timelinePage.videoPlayer).not.toHaveAttribute('src');
     await timelinePage.nextRecordingButton.click();
     await expect(timelinePage.videoPlayer).toHaveAttribute('src', /\/api\/recordings\/play\/323(?:\?|$)/);
@@ -316,7 +350,11 @@ test.describe('Timeline boundary flows @ui @timeline', () => {
     // Wait beyond Retry-After to catch polling or media loads from the old clip.
     await page.waitForTimeout(1200);
     expect(preparations.filter(id => id === 322)).toHaveLength(abandonedRequests);
-    expect(mediaRequests).toEqual([321, 323]);
+    expect(mediaRequests).toEqual([
+      { id: 321, transcode: false }, { id: 321, transcode: true },
+      { id: 322, transcode: false }, { id: 323, transcode: false }
+    ]);
+    expect(preparations).not.toContain(323);
     await expect(timelinePage.videoPlayer).toHaveAttribute('src', /\/api\/recordings\/play\/323(?:\?|$)/);
   });
 

tests/integration/specs/timeline-boundary.ui.spec.ts

@@ -96,13 +96,23 @@ void test_hevc_preparation_returns_retryable_json_without_serving_media(void) {
 }
 
 void test_uncached_media_request_returns_prompt_retry_instead_of_waiting(void) {
-    request.query_string[0] = '\0';
+    strcpy(request.query_string, "transcode=1");
     handle_recordings_playback(&request, &response);
     TEST_ASSERT_EQUAL_INT(503, response.status_code);
     TEST_ASSERT_EQUAL_STRING("2", response_header("Retry-After"));
     TEST_ASSERT_EQUAL_INT(0, serve_calls);
 }
 
+void test_hevc_media_plays_original_without_probe_or_preparation(void) {
+    request.query_string[0] = '\0';
+    handle_recordings_playback(&request, &response);
+    TEST_ASSERT_EQUAL_INT(200, response.status_code);
+    TEST_ASSERT_EQUAL_INT(1, serve_calls);
+    TEST_ASSERT_EQUAL_STRING(recording.file_path, served_path);
+    TEST_ASSERT_EQUAL_INT(0, probe_calls);
+    TEST_ASSERT_EQUAL_INT(0, prepare_calls);
+}
+
 void test_h264_preparation_is_ready_without_a_transcode(void) {
     hevc = false;
     handle_recordings_playback(&request, &response);
@@ -146,7 +156,7 @@ void test_cached_hevc_media_skips_probe_and_conversion(void) {
     TEST_ASSERT_NOT_NULL(file);
     fputs("cached video", file);
     fclose(file);
-    request.query_string[0] = '\0';
+    strcpy(request.query_string, "transcode=1");
     handle_recordings_playback(&request, &response);
     unlink(cache);
     rmdir(cache_dir);
@@ -167,6 +177,7 @@ int main(void) {
     UNITY_BEGIN();
     RUN_TEST(test_hevc_preparation_returns_retryable_json_without_serving_media);
     RUN_TEST(test_uncached_media_request_returns_prompt_retry_instead_of_waiting);
+    RUN_TEST(test_hevc_media_plays_original_without_probe_or_preparation);
     RUN_TEST(test_h264_preparation_is_ready_without_a_transcode);
     RUN_TEST(test_h264_media_uses_original_with_range_support);
     RUN_TEST(test_failed_transcode_reports_error_instead_of_unplayable_original);

tests/unit/test_api_handlers_recordings_playback.c

@@ -13,7 +13,7 @@ import dayjs from 'dayjs';
 import utc from 'dayjs/plugin/utc';
 import customParseFormat from 'dayjs/plugin/customParseFormat';
 import { ConfirmDialog } from './common/ModalDialog.jsx';
-import { prepareRecordingPlayback } from '../../utils/recording-playback.js';
+import { loadRecordingPlayback } from '../../utils/recording-playback.js';
 
 export { ConfirmDialog } from './common/ModalDialog.jsx';
 
@@ -602,27 +602,12 @@ export function VideoModal({ isOpen, onClose, videoUrl, title, downloadUrl }) {
   useEffect(() => {
     if (!isOpen || !videoUrl || !videoRef.current) return;
     const video = videoRef.current;
-    const controller = new AbortController();
-    setPlaybackMessage('Loading recording…');
-    prepareRecordingPlayback(videoUrl, {
-      signal: controller.signal,
-      onWaiting: () => setPlaybackMessage('Preparing recording for playback…'),
-    }).then(url => {
-      if (controller.signal.aborted) return;
-      setPlaybackMessage('');
-      video.src = url;
-      video.load();
-    }).catch(error => {
-      if (controller.signal.aborted) return;
-      console.error('Recording preparation failed:', error);
-      setPlaybackMessage(error.message);
+    setPlaybackMessage('');
+    return loadRecordingPlayback(video, videoUrl, {
+      onPreparing: () => setPlaybackMessage('Preparing a compatible version for this browser…'),
+      onReady: () => setPlaybackMessage(''),
+      onError: error => setPlaybackMessage(error.message),
     });
-    return () => {
-      controller.abort();
-      video.pause();
-      video.removeAttribute('src');
-      video.load();
-    };
   }, [isOpen, videoUrl]);
 
   // Update detection overlay when enabled/disabled
@@ -814,11 +799,6 @@ export function VideoModal({ isOpen, onClose, videoUrl, title, downloadUrl }) {
                 controls
                 controlsList="nofullscreen"
                 key={videoUrl} /* Add key to force re-render when URL changes */
-                onError={(e) => {
-                  if (!e.currentTarget.hasAttribute('src')) return;
-                  console.error('Video error:', e);
-                  showStatusMessage('Error loading video. Please try again.', 'error');
-                }}
                 onLoadStart={() => console.log('Video load started')}
                 onLoadedData={() => console.log('Video data loaded')}
               />