improve: make scrub supersession thresholds runtime configurable

Co-authored-by: Richie McIlroy <richiemcilroy@users.noreply.github.com>

Author: cursoragent

crates/editor/PLAYBACK-BENCHMARKS.md

@@ -88,6 +88,12 @@ cargo run -p cap-editor --example playback-benchmark -- --video /path/to/video.m
 ```bash
 # Simulate rapid scrub bursts and track latest-request latency
 cargo run -p cap-editor --example scrub-benchmark -- --video /path/to/video.mp4 --fps 60 --bursts 20 --burst-size 12 --sweep-seconds 2.0
+
+# Runtime tuning for FFmpeg scrub supersession heuristic
+CAP_FFMPEG_SCRUB_SUPERSEDE_MIN_PIXELS=3686400 \
+CAP_FFMPEG_SCRUB_SUPERSEDE_MIN_REQUESTS=8 \
+CAP_FFMPEG_SCRUB_SUPERSEDE_MIN_SPAN_FRAMES=45 \
+cargo run -p cap-editor --example scrub-benchmark -- --video /path/to/video.mp4
 ```
 
 #### Playback Startup Latency Report (log analysis)
@@ -526,6 +532,56 @@ cargo run -p cap-recording --example playback-test-runner -- full
 - Effective FPS: **60.19**
 - Decode: avg **4.99ms**, p95 **7.17ms**, p99 **9.64ms**, max **13.37ms**
 
+### Benchmark Run: 2026-02-14 00:00:00 UTC (Scrub supersession runtime controls)
+
+**Environment:** Linux runner with synthetic 1080p60 and 4k60 MP4 assets  
+**Commands:** `scrub-benchmark`, `decode-benchmark`, `playback-benchmark`  
+**Change under test:** FFmpeg scrub supersession thresholds moved to env-configurable runtime controls
+
+#### Scrub Burst Benchmark — 1080p60 (`/tmp/cap-bench-1080p60.mp4`)
+- Requests: **240 success / 0 failures**
+- All-request latency: avg **211.38ms**, p95 **417.65ms**, p99 **435.23ms**, max **454.51ms**
+- Last-request-in-burst latency: avg **303.76ms**, p95 **435.23ms**, p99 **454.51ms**, max **454.51ms**
+
+#### Scrub Burst Benchmark — 4k60 (`/tmp/cap-bench-4k60.mp4`)
+- Requests: **240 success / 0 failures**
+- All-request latency: avg **812.11ms**, p95 **1767.50ms**, p99 **1822.52ms**, max **1822.52ms**
+- Last-request-in-burst latency: avg **820.99ms**, p95 **1767.50ms**, p99 **1822.52ms**, max **1822.52ms**
+
+#### Decode Benchmark — 1080p60 (`/tmp/cap-bench-1080p60.mp4`)
+- Decoder init: **6.64ms**
+- Sequential decode: **335.5 fps**, avg **2.98ms**
+- Seek latency (avg / p95 / max):
+  - 0.5s: **48.41 / 96.68 / 96.68ms**
+  - 1.0s: **71.81 / 151.73 / 151.73ms**
+  - 2.0s: **152.21 / 372.41 / 372.41ms**
+  - 5.0s: **233.93 / 388.51 / 388.51ms**
+- Random access: avg **115.07ms**, p95 **354.67ms**, p99 **399.31ms**
+
+#### Decode Benchmark — 4k60 (`/tmp/cap-bench-4k60.mp4`)
+- Decoder init: **32.18ms**
+- Sequential decode: **98.7 fps**, avg **10.13ms**
+- Seek latency (avg / p95 / max):
+  - 0.5s: **201.24 / 387.51 / 387.51ms**
+  - 1.0s: **347.03 / 774.83 / 774.83ms**
+  - 2.0s: **623.25 / 1499.39 / 1499.39ms**
+  - 5.0s: **961.84 / 1629.35 / 1629.35ms**
+- Random access: avg **524.19ms**, p95 **1485.61ms**, p99 **1619.96ms**
+
+#### Playback Throughput Benchmark — 1080p60 (`/tmp/cap-bench-1080p60.mp4`)
+- Target: **60 fps**, budget **16.67ms**
+- Decoded: **240/240**, failures **0**
+- Missed deadlines: **0**
+- Effective FPS: **60.22**
+- Decode: avg **1.33ms**, p95 **2.49ms**, p99 **2.80ms**, max **3.90ms**
+
+#### Playback Throughput Benchmark — 4k60 (`/tmp/cap-bench-4k60.mp4`)
+- Target: **60 fps**, budget **16.67ms**
+- Decoded: **240/240**, failures **0**
+- Missed deadlines: **2**
+- Effective FPS: **60.17**
+- Decode: avg **6.43ms**, p95 **8.82ms**, p99 **14.14ms**, max **17.52ms**
+
 <!-- PLAYBACK_BENCHMARK_RESULTS_END -->
 
 ---

crates/editor/PLAYBACK-FINDINGS.md

@@ -743,6 +743,40 @@ The CPU RGBA→NV12 conversion was taking 15-25ms per frame for 3024x1964 resolu
 
 ---
 
+### Session 2026-02-14 (Supersession runtime configurability)
+
+**Goal**: Enable faster cross-platform tuning of scrub supersession without code edits
+
+**What was done**:
+1. Added environment-driven controls for FFmpeg scrub supersession behavior:
+   - `CAP_FFMPEG_SCRUB_SUPERSEDE_DISABLED`
+   - `CAP_FFMPEG_SCRUB_SUPERSEDE_MIN_PIXELS`
+   - `CAP_FFMPEG_SCRUB_SUPERSEDE_MIN_REQUESTS`
+   - `CAP_FFMPEG_SCRUB_SUPERSEDE_MIN_SPAN_FRAMES`
+2. Kept default behavior equivalent to current tuned path.
+3. Re-ran scrub, decode, and playback benchmarks with defaults to verify no functional regressions.
+
+**Changes Made**:
+- `crates/rendering/src/decoder/ffmpeg.rs`
+  - added `ScrubSupersessionConfig` with `OnceLock` initialization
+  - replaced hard-coded supersession thresholds with config values
+- `crates/editor/PLAYBACK-BENCHMARKS.md`
+  - added command examples for runtime supersession tuning
+  - added validation benchmark run for the configurable defaults
+
+**Results**:
+- ✅ Scrub supersession behavior preserved with defaults:
+  - 4k last-request avg **~821ms**, p95 **~1768ms**
+  - 1080p last-request avg **~304ms**, p95 **~435ms**
+- ✅ Playback throughput remains at 60fps-class:
+  - 1080p: **60.22 fps**
+  - 4k: **60.17 fps**
+- ✅ Decode benchmark metrics remain in expected variance envelope after config refactor.
+
+**Stopping point**: supersession tuning is now runtime-configurable, enabling platform-specific calibration runs (especially macOS/Windows) without recompiling.
+
+---
+
 ## References
 
 - `PLAYBACK-BENCHMARKS.md` - Raw performance test data (auto-updated by test runner)

crates/rendering/src/decoder/ffmpeg.rs

@@ -6,8 +6,10 @@ use ffmpeg::{format, frame};
 use std::{
     cell::RefCell,
     collections::BTreeMap,
+    env,
     path::PathBuf,
     rc::Rc,
+    sync::OnceLock,
     sync::{Arc, mpsc},
 };
 use tokio::sync::oneshot;
@@ -71,6 +73,53 @@ struct PendingRequest {
     order: u64,
 }
 
+#[derive(Clone, Copy)]
+struct ScrubSupersessionConfig {
+    min_requests: usize,
+    min_span_frames: u32,
+    min_pixels: u64,
+    disabled: bool,
+}
+
+static SCRUB_SUPERSESSION_CONFIG: OnceLock<ScrubSupersessionConfig> = OnceLock::new();
+
+fn parse_usize_env(key: &str) -> Option<usize> {
+    env::var(key).ok()?.parse::<usize>().ok()
+}
+
+fn parse_u32_env(key: &str) -> Option<u32> {
+    env::var(key).ok()?.parse::<u32>().ok()
+}
+
+fn parse_u64_env(key: &str) -> Option<u64> {
+    env::var(key).ok()?.parse::<u64>().ok()
+}
+
+fn scrub_supersession_config() -> ScrubSupersessionConfig {
+    *SCRUB_SUPERSESSION_CONFIG.get_or_init(|| {
+        let min_requests = parse_usize_env("CAP_FFMPEG_SCRUB_SUPERSEDE_MIN_REQUESTS")
+            .filter(|value| *value > 0)
+            .unwrap_or(8);
+        let min_span_frames = parse_u32_env("CAP_FFMPEG_SCRUB_SUPERSEDE_MIN_SPAN_FRAMES")
+            .filter(|value| *value > 0)
+            .unwrap_or((FRAME_CACHE_SIZE as u32 / 2).max(1));
+        let min_pixels = parse_u64_env("CAP_FFMPEG_SCRUB_SUPERSEDE_MIN_PIXELS")
+            .filter(|value| *value > 0)
+            .unwrap_or(3_686_400);
+        let disabled = env::var("CAP_FFMPEG_SCRUB_SUPERSEDE_DISABLED")
+            .ok()
+            .map(|value| value == "1" || value.eq_ignore_ascii_case("true"))
+            .unwrap_or(false);
+
+        ScrubSupersessionConfig {
+            min_requests,
+            min_span_frames,
+            min_pixels,
+            disabled,
+        }
+    })
+}
+
 fn send_to_replies(
     name: &str,
     frame_number: u32,
@@ -85,9 +134,9 @@ fn send_to_replies(
 }
 
 fn maybe_supersede_scrub_burst(pending_requests: &mut Vec<PendingRequest>, enabled: bool) {
-    const SCRUB_SUPERSEDE_MIN_REQUESTS: usize = 8;
+    let config = scrub_supersession_config();
 
-    if !enabled || pending_requests.len() < SCRUB_SUPERSEDE_MIN_REQUESTS {
+    if !enabled || pending_requests.len() < config.min_requests {
         return;
     }
 
@@ -102,7 +151,7 @@ fn maybe_supersede_scrub_burst(pending_requests: &mut Vec<PendingRequest>, enabl
         .max()
         .unwrap_or(0);
 
-    if max_frame.saturating_sub(min_frame) <= (FRAME_CACHE_SIZE as u32 / 2) {
+    if max_frame.saturating_sub(min_frame) <= config.min_span_frames {
         return;
     }
 
@@ -354,8 +403,10 @@ impl FfmpegDecoder {
                     decoder_type: sw_decoder_type,
                 };
                 let _ = ready_tx.send(Ok(sw_init_result));
-                let enable_scrub_supersession =
-                    (video_width as u64) * (video_height as u64) >= 3_686_400;
+                let supersession_config = scrub_supersession_config();
+                let enable_scrub_supersession = !supersession_config.disabled
+                    && (video_width as u64) * (video_height as u64)
+                        >= supersession_config.min_pixels;
 
                 while let Ok(r) = rx.recv() {
                     const MAX_FRAME_TOLERANCE: u32 = 2;
@@ -697,8 +748,9 @@ impl FfmpegDecoder {
                 decoder_type,
             };
             let _ = ready_tx.send(Ok(init_result));
-            let enable_scrub_supersession =
-                (video_width as u64) * (video_height as u64) >= 3_686_400;
+            let supersession_config = scrub_supersession_config();
+            let enable_scrub_supersession = !supersession_config.disabled
+                && (video_width as u64) * (video_height as u64) >= supersession_config.min_pixels;
 
             while let Ok(r) = rx.recv() {
                 const MAX_FRAME_TOLERANCE: u32 = 2;