improve: tune frame wait and add startup threshold checks

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

Author: cursoragent

crates/editor/PLAYBACK-BENCHMARKS.md

@@ -10,6 +10,7 @@ This document tracks performance benchmarks for Cap's playback and decoding syst
 |--------|--------|-----------|
 | Decoder Init | <200ms | - |
 | Decode Latency (p95) | <50ms | - |
+| Startup to First Frame | <250ms | configurable |
 | Effective FPS | ≥30 fps | ±2 fps |
 | Decode Jitter | <10ms | - |
 | Scrub Seek Latency (p95) | <40ms | - |
@@ -42,6 +43,7 @@ This document tracks performance benchmarks for Cap's playback and decoding syst
 ```bash
 # Run full playback validation on recordings from real-device-test-runner
 cargo run -p cap-recording --example playback-test-runner -- full
+cargo run -p cap-recording --example playback-test-runner -- full --startup-threshold-ms 250
 
 # Run specific test categories
 cargo run -p cap-recording --example playback-test-runner -- decoder
@@ -118,9 +120,9 @@ cargo run -p cap-recording --example playback-test-runner -- scrub --fps 60 --be
 Automated helper for machine runs:
 
 ```bash
-node scripts/run-playback-benchmark-matrix.js --platform macos-13 --gpu apple-silicon --output-dir /tmp/playback-matrix --fps 60 --input-dir /tmp/cap-real-device-tests
-node scripts/run-playback-benchmark-matrix.js --platform windows-11 --gpu nvidia-discrete --output-dir /tmp/playback-matrix-windows-nvidia --fps 60 --require-formats mp4,fragmented --input-dir /tmp/cap-real-device-tests
-node scripts/run-playback-benchmark-matrix.js --platform windows-11 --gpu integrated --output-dir /tmp/playback-matrix-windows-integrated --fps 60 --scenarios scrub --input-dir /tmp/cap-real-device-tests
+node scripts/run-playback-benchmark-matrix.js --platform macos-13 --gpu apple-silicon --output-dir /tmp/playback-matrix --fps 60 --startup-threshold-ms 250 --input-dir /tmp/cap-real-device-tests
+node scripts/run-playback-benchmark-matrix.js --platform windows-11 --gpu nvidia-discrete --output-dir /tmp/playback-matrix-windows-nvidia --fps 60 --startup-threshold-ms 250 --require-formats mp4,fragmented --input-dir /tmp/cap-real-device-tests
+node scripts/run-playback-benchmark-matrix.js --platform windows-11 --gpu integrated --output-dir /tmp/playback-matrix-windows-integrated --fps 60 --startup-threshold-ms 250 --scenarios scrub --input-dir /tmp/cap-real-device-tests
 ```
 
 | Platform | GPU Class | MP4 Full | Fragmented Full | MP4 Scrub | Fragmented Scrub | Notes |

crates/editor/PLAYBACK-FINDINGS.md

@@ -171,10 +171,15 @@ cargo run -p cap-recording --example playback-test-runner -- full
    - Only the latest pending seek frame is sent while an async seek is in-flight.
    - Duplicate same-frame seeks are dropped in both frontend dispatch and playback seek signaling.
 
+8. **Playback frame wait timeout now scales with target FPS (2026-02-13)**
+   - Replaced fixed 200ms frame fetch waits with FPS-derived bounded timeout.
+   - Reduces long stall windows on 60fps playback and improves real-time catch-up behavior.
+
 8. **Playback benchmark runner now supports JSON evidence export (2026-02-13)**
    - `playback-test-runner` supports `--json-output` for structured report emission.
    - JSON output includes command metadata, system info, summary, and per-recording test detail.
    - Command metadata now includes input scope and output flags for reproducibility.
+   - Startup-to-first-frame threshold is configurable with `--startup-threshold-ms` and tracked as pass/fail signal.
 
 9. **Added JSON aggregate utility for cross-platform benchmark collation (2026-02-13)**
    - `scripts/aggregate-playback-benchmarks.js` builds a markdown table from multiple JSON outputs.
@@ -185,6 +190,7 @@ cargo run -p cap-recording --example playback-test-runner -- full
    - Automatically generates aggregate markdown for each machine run directory.
    - Performs per-machine post-run validation for required scenarios and optional format requirements.
    - Supports scenario subset reruns via `--scenarios` for faster targeted validation.
+   - Supports startup threshold tuning via `--startup-threshold-ms`.
 
 11. **Added matrix completeness validator (2026-02-13)**
    - `scripts/validate-playback-matrix.js` validates required platform/gpu/scenario cells.

crates/editor/PLAYBACK-MATRIX-RUNBOOK.md

@@ -43,6 +43,7 @@ node scripts/run-playback-benchmark-matrix.js \
   --gpu "<gpu-label>" \
   --output-dir "$OUT_DIR" \
   --fps 60 \
+  --startup-threshold-ms 250 \
   --require-formats mp4,fragmented \
   --scenarios full,scrub \
   --input-dir "$INPUT_DIR"
@@ -51,7 +52,7 @@ node scripts/run-playback-benchmark-matrix.js \
 Equivalent shortcut:
 
 ```bash
-pnpm bench:playback:matrix -- --platform "<platform-label>" --gpu "<gpu-label>" --output-dir "$OUT_DIR" --fps 60 --require-formats mp4,fragmented --scenarios full,scrub --input-dir "$INPUT_DIR"
+pnpm bench:playback:matrix -- --platform "<platform-label>" --gpu "<gpu-label>" --output-dir "$OUT_DIR" --fps 60 --startup-threshold-ms 250 --require-formats mp4,fragmented --scenarios full,scrub --input-dir "$INPUT_DIR"
 ```
 
 Rerun only scrub scenario for a machine:

crates/editor/src/playback.rs

@@ -384,6 +384,10 @@ impl Playback {
             .spawn();
 
             let frame_duration = Duration::from_secs_f64(1.0 / fps_f64);
+            let frame_fetch_timeout = frame_duration
+                .mul_f64(4.0)
+                .max(Duration::from_millis(20))
+                .min(Duration::from_millis(80));
             let mut frame_number = self.start_frame_number;
             let mut prefetch_buffer: VecDeque<PrefetchedFrame> =
                 VecDeque::with_capacity(PREFETCH_BUFFER_SIZE);
@@ -553,7 +557,7 @@ impl Playback {
 
                         if is_in_flight {
                             let wait_start = Instant::now();
-                            let max_wait = Duration::from_millis(200);
+                            let max_wait = frame_fetch_timeout;
                             let mut found_frame = None;
 
                             while wait_start.elapsed() < max_wait {
@@ -603,11 +607,8 @@ impl Playback {
                         } else if prefetch_buffer.is_empty() && total_frames_rendered < 15 {
                             let _ = frame_request_tx.send(frame_number);
 
-                            let wait_result = tokio::time::timeout(
-                                Duration::from_millis(200),
-                                prefetch_rx.recv(),
-                            )
-                            .await;
+                            let wait_result =
+                                tokio::time::timeout(frame_fetch_timeout, prefetch_rx.recv()).await;
 
                             if let Ok(Some(prefetched)) = wait_result {
                                 if prefetched.frame_number == frame_number {
@@ -651,7 +652,7 @@ impl Playback {
                                 guard.insert(frame_number);
                             }
 
-                            let max_wait = Duration::from_millis(200);
+                            let max_wait = frame_fetch_timeout;
                             let data = tokio::select! {
                                 _ = stop_rx.changed() => {
                                     if let Ok(mut guard) = main_in_flight.write() {

crates/recording/examples/playback-test-runner.rs

@@ -39,6 +39,9 @@ struct Cli {
     #[arg(long, global = true, default_value = "30")]
     fps: u32,
 
+    #[arg(long, global = true, default_value_t = STARTUP_TO_FIRST_FRAME_WARNING_MS)]
+    startup_threshold_ms: f64,
+
     #[arg(long, global = true)]
     verbose: bool,
 
@@ -66,6 +69,7 @@ enum Commands {
 const FPS_TOLERANCE: f64 = 2.0;
 const DECODE_LATENCY_WARNING_MS: f64 = 50.0;
 const SCRUB_SEEK_WARNING_MS: f64 = 40.0;
+const STARTUP_TO_FIRST_FRAME_WARNING_MS: f64 = 250.0;
 const AUDIO_VIDEO_SYNC_TOLERANCE_MS: f64 = 100.0;
 const CAMERA_SYNC_TOLERANCE_MS: f64 = 100.0;
 
@@ -101,6 +105,8 @@ struct PlaybackTestResult {
     fps_ok: bool,
     jitter_ms: f64,
     decode_latency_ok: bool,
+    startup_latency_ok: bool,
+    startup_threshold_ms: f64,
     errors: Vec<String>,
 }
 
@@ -243,6 +249,12 @@ impl RecordingTestReport {
             if !result.decode_latency_ok {
                 println!("      WARN: Decode latency exceeds {DECODE_LATENCY_WARNING_MS}ms!");
             }
+            if !result.startup_latency_ok {
+                println!(
+                    "      WARN: Startup-to-first-frame exceeds {:.1}ms!",
+                    result.startup_threshold_ms
+                );
+            }
             for err in &result.errors {
                 println!("      ERROR: {err}");
             }
@@ -390,12 +402,14 @@ async fn test_playback(
     meta: &StudioRecordingMeta,
     segment_index: usize,
     fps: u32,
+    startup_threshold_ms: f64,
     verbose: bool,
 ) -> PlaybackTestResult {
     let playback_start = Instant::now();
     let mut result = PlaybackTestResult {
         segment_index,
         expected_fps: fps as f64,
+        startup_threshold_ms,
         ..Default::default()
     };
 
@@ -496,9 +510,11 @@ async fn test_playback(
     result.fps_ok = (result.effective_fps - result.expected_fps).abs() <= FPS_TOLERANCE
         || result.effective_fps >= result.expected_fps;
     result.decode_latency_ok = result.p95_decode_time_ms <= DECODE_LATENCY_WARNING_MS;
+    result.startup_latency_ok = result.startup_to_first_frame_ms <= startup_threshold_ms;
 
     result.passed = result.fps_ok
         && result.decode_latency_ok
+        && result.startup_latency_ok
         && result.failed_frames == 0
         && result.decoded_frames > 0;
 
@@ -880,6 +896,7 @@ fn discover_recordings(input_dir: &Path) -> Vec<PathBuf> {
 async fn run_tests_on_recording(
     recording_path: &Path,
     fps: u32,
+    startup_threshold_ms: f64,
     run_decoder: bool,
     run_playback: bool,
     run_scrub: bool,
@@ -969,8 +986,15 @@ async fn run_tests_on_recording(
             if verbose {
                 println!("  Testing playback for segment {segment_idx}...");
             }
-            let playback_result =
-                test_playback(&meta, studio_meta.as_ref(), segment_idx, fps, verbose).await;
+            let playback_result = test_playback(
+                &meta,
+                studio_meta.as_ref(),
+                segment_idx,
+                fps,
+                startup_threshold_ms,
+                verbose,
+            )
+            .await;
             report.playback_results.push(playback_result);
         }
 
@@ -1082,6 +1106,13 @@ fn get_failure_tags(report: &RecordingTestReport) -> Vec<String> {
     if report.playback_results.iter().any(|r| !r.decode_latency_ok) {
         tags.push("LATENCY".to_string());
     }
+    if report
+        .playback_results
+        .iter()
+        .any(|r| !r.startup_latency_ok)
+    {
+        tags.push("STARTUP".to_string());
+    }
     if report.scrub_results.iter().any(|r| !r.seek_latency_ok) {
         tags.push("SCRUB_LATENCY".to_string());
     }
@@ -1191,7 +1222,7 @@ fn report_to_markdown(report: &RecordingTestReport) -> String {
         ));
         md.push_str(&format!(
             "| ↳ Startup | {} | first_decode={:.1}ms startup_to_first={:.1}ms |\n",
-            if result.startup_to_first_frame_ms > 0.0 {
+            if result.startup_latency_ok {
                 "✅"
             } else {
                 "❌"
@@ -1505,9 +1536,10 @@ fn shell_quote(value: &str) -> String {
 
 fn build_command_string(cli: &Cli) -> String {
     let mut command = format!(
-        "cargo run -p cap-recording --example playback-test-runner -- {} --fps {}",
+        "cargo run -p cap-recording --example playback-test-runner -- {} --fps {} --startup-threshold-ms {:.1}",
         command_name(cli.command.as_ref()),
-        cli.fps
+        cli.fps,
+        cli.startup_threshold_ms
     );
 
     if let Some(path) = &cli.recording_path {
@@ -1598,9 +1630,10 @@ async fn main() -> anyhow::Result<()> {
     println!("\nCap Playback Test Runner");
     println!("{}", "=".repeat(40));
     println!(
-        "Testing {} recording(s) at {} FPS",
+        "Testing {} recording(s) at {} FPS (startup threshold: {:.1}ms)",
         recordings.len(),
-        cli.fps
+        cli.fps,
+        cli.startup_threshold_ms
     );
     println!();
 
@@ -1612,6 +1645,7 @@ async fn main() -> anyhow::Result<()> {
         match run_tests_on_recording(
             recording_path,
             cli.fps,
+            cli.startup_threshold_ms,
             run_decoder,
             run_playback,
             run_scrub,

scripts/run-playback-benchmark-matrix.js

@@ -10,6 +10,7 @@ function parseArgs(argv) {
 		gpu: null,
 		outputDir: null,
 		fps: 60,
+		startupThresholdMs: 250,
 		recordingPath: null,
 		inputDir: null,
 		validate: true,
@@ -46,6 +47,14 @@ function parseArgs(argv) {
 			options.fps = value;
 			continue;
 		}
+		if (arg === "--startup-threshold-ms") {
+			const value = Number.parseFloat(argv[++i] ?? "");
+			if (!Number.isFinite(value) || value <= 0) {
+				throw new Error("Invalid --startup-threshold-ms value");
+			}
+			options.startupThresholdMs = value;
+			continue;
+		}
 		if (arg === "--recording-path") {
 			options.recordingPath = argv[++i] ?? null;
 			continue;
@@ -85,7 +94,7 @@ function parseArgs(argv) {
 }
 
 function usage() {
-	console.log(`Usage: node scripts/run-playback-benchmark-matrix.js --platform <name> --gpu <name> --output-dir <dir> [--fps 60] [--recording-path <path>] [--input-dir <path>] [--require-formats mp4,fragmented] [--scenarios full,scrub]
+	console.log(`Usage: node scripts/run-playback-benchmark-matrix.js --platform <name> --gpu <name> --output-dir <dir> [--fps 60] [--startup-threshold-ms 250] [--recording-path <path>] [--input-dir <path>] [--require-formats mp4,fragmented] [--scenarios full,scrub]
 
 Runs playback benchmark matrix scenarios and writes JSON outputs.
 
@@ -96,6 +105,7 @@ Required:
 
 Optional:
   --fps           FPS for benchmark runs (default: 60)
+  --startup-threshold-ms Startup-to-first-frame threshold in ms (default: 250)
   --recording-path  Specific recording path
   --input-dir       Recording discovery directory
   --require-formats Required formats for local validation (comma-separated)
@@ -134,6 +144,8 @@ function scenarioArgs(options, scenario) {
 		scenario,
 		"--fps",
 		String(options.fps),
+		"--startup-threshold-ms",
+		String(options.startupThresholdMs),
 		"--json-output",
 		jsonOutput,
 		"--notes",