Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

78.0 KB
Raw Blame
//! Synthetic device matrix for A/V sync.
//!
//! Drives the real recording pipeline (sources -> mux loop -> encoders ->
//! containers) with synthetic video and audio across sample rates, channel
//! counts, frame rates and delivery pathologies (jitter, drops, gaps), then
//! verifies the muxed output preserves real time. No capture hardware is
//! required, so this runs identically on macOS, Windows and Linux CI.
//!
//! Frames are emitted in real time because the pipeline pins video
//! timestamps to the wall clock; each case therefore costs its content
//! duration. Keep cases short.
//!
//! Set `CAP_SYNC_MATRIX_REPORT` to write a JSON report of every case.

use std::{
    path::{Path, PathBuf},
    time::Duration,
};

use cap_media_info::{AudioInfo, Sample, Type, VideoInfo};
use cap_recording::{
    AudioFrame, ChannelAudioSource, ChannelAudioSourceConfig, ChannelVideoSource,
    ChannelVideoSourceConfig, OutputPipeline,
    ffmpeg::{
        FFmpegVideoFrame, Mp4Muxer, OggMuxer, OggMuxerConfig, SegmentedVideoMuxer,
        SegmentedVideoMuxerConfig,
    },
};
use cap_timestamp::{Timestamp, Timestamps};
use serde::{Deserialize, Serialize};

const CONTENT_SECS: f64 = 4.0;
const MAX_PRODUCTION_CAPTURE_FPS: u32 = 240;
/// Absolute tolerance for a muxed pts vs the sent capture timestamp,
/// measured from each side's own origin (first sent frame vs first muxed
/// pts). Covers warmup anchoring, emission jitter and encoder rounding,
/// plus scheduler noise on shared CI runners.
const ABS_TOLERANCE_SECS: f64 = 0.25;
/// The drift tracker deliberately re-pins pts toward the wall clock by up to
/// this much; heavy over-delivery cases get it as designed headroom on top of
/// the base tolerance. Keep in step with the tracker's re-pin cap.
const DRIFT_REPIN_CAP_SECS: f64 = 0.1;
/// Tolerance for the relative structure (pts deltas vs sent deltas), which is
/// what actually determines sync drift. The bug class this guards against
/// produces errors of a second or more.
const REL_TOLERANCE_SECS: f64 = 0.15;
/// Tolerance for decoded audio duration vs generated duration.
const AUDIO_DURATION_TOLERANCE_SECS: f64 = 0.15;

#[derive(Debug, Clone, Copy)]
enum VideoScenario {
    Steady,
    Jitter,
    Drops,
    Gap,
}

impl VideoScenario {
    fn name(self) -> &'static str {
        match self {
            Self::Steady => "steady",
            Self::Jitter => "jitter",
            Self::Drops => "drops",
            Self::Gap => "gap",
        }
    }

    /// Deterministic capture timestamps (seconds) for the scenario.
    fn timestamps(self, fps: u32) -> Vec<f64> {
        let period = 1.0 / f64::from(fps);
        let total = (CONTENT_SECS * f64::from(fps)) as u64;
        let mut out = Vec::new();
        for k in 0..total {
            let base = k as f64 * period;
            match self {
                Self::Steady => out.push(base),
                Self::Jitter => {
                    // Deterministic pseudo-jitter, +-40% of the period, kept
                    // monotonic (and non-negative) by construction.
                    let phase = (k as f64 * 0.7368).fract() - 0.5;
                    out.push((base + phase * period * 0.8).max(0.0));
                }
                Self::Drops => {
                    // Drop every 4th and 7th frame: the capture stream simply
                    // never delivers them.
                    if k % 4 != 3 && k % 7 != 6 {
                        out.push(base);
                    }
                }
                Self::Gap => {
                    // 1.5s of frames, a 2s static-screen gap, then the rest.
                    let t = base;
                    if t < 1.5 {
                        out.push(t);
                    } else {
                        out.push(t + 2.0);
                    }
                }
            }
        }
        out.sort_by(|a, b| a.partial_cmp(b).unwrap());
        out.dedup_by(|a, b| (*a - *b).abs() < period * 0.25);
        out
    }
}

#[derive(Serialize)]
struct CaseResult {
    name: String,
    pass: bool,
    detail: String,
}

#[derive(Debug, Clone, Copy, PartialEq)]
enum Content {
    /// Flat color; encodes trivially.
    Flat,
    /// Per-frame pseudo-random noise: worst-case encoder load, exercising
    /// backpressure the way dense real screen content does.
    Noise,
    /// A moving bar over a gradient: typical screen-content motion.
    Motion,
}

fn make_video_frame(
    width: u32,
    height: u32,
    frame_index: u64,
    content: Content,
    rng: &mut Rng,
) -> ffmpeg::frame::Video {
    let mut frame = ffmpeg::frame::Video::new(ffmpeg::format::Pixel::BGRA, width, height);
    let stride = frame.stride(0);
    let data = frame.data_mut(0);
    match content {
        Content::Flat => {
            let shade = ((frame_index * 7) % 200) as u8;
            data.fill(shade);
        }
        Content::Noise => {
            // Refresh a pseudo-random buffer per frame so no two frames are
            // alike and inter prediction gets no free lunch.
            for chunk in data.chunks_mut(8) {
                let v = rng.next().to_le_bytes();
                let n = chunk.len();
                chunk.copy_from_slice(&v[..n]);
            }
        }
        Content::Motion => {
            let bar = ((frame_index * 6) % u64::from(width)) as usize;
            for y in 0..height as usize {
                let row = &mut data[y * stride..y * stride + width as usize * 4];
                for (x, px) in row.chunks_mut(4).enumerate() {
                    let base = ((x * 255) / width as usize) as u8;
                    let v = if x.abs_diff(bar) < 12 { 255 } else { base };
                    px[0] = v;
                    px[1] = v ^ 0x55;
                    px[2] = base;
                    px[3] = 255;
                }
            }
        }
    }
    frame
}

/// splitmix64: tiny, dependency-free, deterministic PRNG. Every randomized
/// case is fully reproducible from the printed seed.
struct Rng(u64);

impl Rng {
    fn next(&mut self) -> u64 {
        self.0 = self.0.wrapping_add(0x9E37_79B9_7F4A_7C15);
        let mut z = self.0;
        z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
        z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
        z ^ (z >> 31)
    }

    fn range(&mut self, lo: u64, hi: u64) -> u64 {
        lo + self.next() % (hi - lo + 1)
    }

    fn f64(&mut self) -> f64 {
        (self.next() >> 11) as f64 / (1u64 << 53) as f64
    }

    fn pick<T: Copy>(&mut self, items: &[T]) -> T {
        items[(self.next() % items.len() as u64) as usize]
    }
}

#[derive(Clone)]
struct VideoCase {
    /// The rate the pipeline is CONFIGURED for (VideoInfo). Real devices may
    /// deliver at a completely different rate.
    fps: u32,
    /// The rate frames are actually generated at (labeling only; the truth
    /// lives in `sent`).
    delivered_fps: u32,
    sent: Vec<f64>,
    fragmented: bool,
    width: u32,
    height: u32,
    content: Content,
    rng_seed: u64,
}

impl VideoCase {
    fn curated(fps: u32, scenario: VideoScenario, fragmented: bool) -> Self {
        Self {
            fps,
            delivered_fps: fps,
            sent: scenario.timestamps(fps),
            fragmented,
            width: 160,
            height: 120,
            content: Content::Flat,
            rng_seed: 1,
        }
    }

    /// A device that free-runs at `delivered_fps` while the pipeline believes
    /// `nominal_fps` — the configured rate is a belief, not a constraint. A
    /// camera advertising 30fps but delivering 60 produced recordings twice
    /// as long as the audio, playing at 0.5x.
    fn mismatch(
        nominal_fps: u32,
        delivered_fps: u32,
        scenario: VideoScenario,
        fragmented: bool,
    ) -> Self {
        Self {
            fps: nominal_fps,
            delivered_fps,
            sent: scenario.timestamps(delivered_fps),
            fragmented,
            width: 160,
            height: 120,
            content: Content::Flat,
            rng_seed: 1,
        }
    }
}

fn minimum_overload_coverage(delivered_fps: u32) -> f64 {
    0.9 * f64::from(MAX_PRODUCTION_CAPTURE_FPS)
        / f64::from(delivered_fps.max(MAX_PRODUCTION_CAPTURE_FPS))
}

async fn run_video_case(case: VideoCase) -> Result<String, String> {
    let temp = tempfile::tempdir().map_err(|e| format!("tempdir: {e}"))?;
    let out_path = if case.fragmented {
        temp.path().join("display")
    } else {
        temp.path().join("display.mp4")
    };
    let fragmented = case.fragmented;

    let info = VideoInfo::from_raw(
        cap_media_info::RawVideoFormat::Bgra,
        case.width,
        case.height,
        case.fps,
    );
    let (tx, rx) = flume::bounded::<FFmpegVideoFrame>(32);
    let timestamps = Timestamps::now();

    let sent = case.sent.clone();
    // Set once the pipeline consumer exists. The emitter starts before the
    // pipeline build so the builder can own the channel receiver; frames
    // scheduled during the build window back up in the bounded channel and
    // their lateness is structural, not a runner stall. Only lateness on
    // frames due after this instant means the runner actually stalled.
    let built_at: std::sync::Arc<std::sync::OnceLock<std::time::Instant>> =
        std::sync::Arc::new(std::sync::OnceLock::new());
    let emit = {
        let sent = sent.clone();
        let base = timestamps.instant();
        let (width, height, content) = (case.width, case.height, case.content);
        let mut rng = Rng(case.rng_seed);
        let built_at = built_at.clone();
        // Over-delivery cases (>240fps, rates production never produces)
        // exist to verify drop handling, not consumer throughput: a weak
        // runner saturated by the firehose proves nothing, so send blocking
        // still counts as falling behind there and earns a loud skip.
        let overload_case = case.delivered_fps > MAX_PRODUCTION_CAPTURE_FPS;
        tokio::spawn(async move {
            let mut max_late = 0.0f64;
            let mut last_send_end: Option<std::time::Instant> = None;
            for (i, &ts) in sent.iter().enumerate() {
                let due = base + Duration::from_secs_f64(ts);
                tokio::time::sleep_until(due.into()).await;
                if built_at.get().is_some_and(|built| due >= *built) {
                    // At production-representative rates, lateness counts
                    // only time since the channel was last free: a send_async
                    // blocked on pipeline backpressure delays the next frame
                    // too, and that is the pipeline's fault, not a runner
                    // stall — a consumer-side regression must fail the case,
                    // not convert it into a skip.
                    let anchor = if overload_case {
                        due
                    } else {
                        last_send_end.map_or(due, |s| s.max(due))
                    };
                    max_late = max_late.max(anchor.elapsed().as_secs_f64());
                }
                let frame = FFmpegVideoFrame {
                    inner: make_video_frame(width, height, i as u64, content, &mut rng),
                    timestamp: Timestamp::Instant(due),
                };
                if tx.send_async(frame).await.is_err() {
                    break;
                }
                last_send_end = Some(std::time::Instant::now());
            }
            // Sender drops here, ending the stream.
            max_late
        })
    };

    let builder = OutputPipeline::builder(out_path.clone())
        .with_video::<ChannelVideoSource<FFmpegVideoFrame>>(ChannelVideoSourceConfig::new(info, rx))
        .with_timestamps(timestamps);

    let pipeline = if fragmented {
        builder
            .build::<SegmentedVideoMuxer>(SegmentedVideoMuxerConfig {
                segment_duration: Duration::from_secs(2),
                ..Default::default()
            })
            .await
    } else {
        builder.build::<Mp4Muxer>(()).await
    }
    .map_err(|e| format!("pipeline build: {e}"))?;
    let _ = built_at.set(std::time::Instant::now());

    let max_emit_late = emit.await.map_err(|e| format!("emit join: {e}"))?;
    // The verification below assumes frames were emitted in real time; when a
    // saturated runner (or a software encoder drowning in worst-case content)
    // stalls emission for seconds, pts-vs-wall comparisons are meaningless.
    // Skip loudly instead of failing on an environment artifact.
    let emit_lag =
        timestamps.instant().elapsed().as_secs_f64() - sent.last().copied().unwrap_or(0.0);
    let finished = {
        // Allow the tail of the stream to flush through the encoder.
        tokio::time::sleep(Duration::from_millis(500)).await;
        pipeline.stop().await.map_err(|e| format!("stop: {e}"))?
    };
    if emit_lag > 1.5 {
        return Ok(format!(
            "skipped: runner fell {emit_lag:.1}s behind real-time emission"
        ));
    }
    // A stall that later catches up is invisible to the end-of-emission lag
    // above, but it still contaminates the checks: frames stamped with their
    // scheduled capture time arrive late, and the pipeline's wall-clock
    // coupling (drift re-pinning) legitimately moves the muxed pts by about
    // the stall size — a 0.3s scheduler stall mid-case reads as a 0.3s "pts
    // error" on an otherwise healthy pipeline. Real timestamp bugs reproduce
    // on healthy runners; a stalled runner proves nothing either way.
    if max_emit_late > 0.1 {
        return Ok(format!(
            "skipped: runner stalled {max_emit_late:.2}s mid-emission; \
             pts-vs-wall checks are environment-contaminated"
        ));
    }

    // Read back the muxed pts.
    let playable = if fragmented {
        concat_fmp4(&out_path, temp.path())?
    } else {
        out_path.clone()
    };
    let pts = read_video_pts(&playable)?;

    // At low frame rates the fixed tolerance is only a frame or two of
    // budget, so scheduler jitter on shared runners trips it; express the
    // floor in frames as well. The bug class this guards produces errors of
    // a second or more either way. When the source over-delivers several
    // times faster than the configured rate, the drift tracker deliberately
    // re-pins pts toward the wall clock (a designed 0.1s cap) while the
    // runner schedules hundreds of timed emissions per second, so the
    // headroom on top of that designed deviation has to be wider.
    let over_delivery = f64::from(case.delivered_fps) / f64::from(case.fps.max(1));
    let base_rel_tolerance = if over_delivery > 4.0 {
        REL_TOLERANCE_SECS + DRIFT_REPIN_CAP_SECS
    } else {
        REL_TOLERANCE_SECS
    };
    let rel_tolerance = base_rel_tolerance.max(2.5 / f64::from(case.fps));

    if pts.len() != sent.len() {
        // Beyond any real capture device's rate, losslessness is not a
        // pipeline guarantee: the muxer's stall budget drops frames rather
        // than block capture (production behavior), and a shared runner
        // cannot real-time-encode several hundred fps of worst-case content.
        // Timestamp correctness is still enforced below on every frame that
        // was muxed; extra frames or heavy loss always fail.
        let overload_case = case.delivered_fps > MAX_PRODUCTION_CAPTURE_FPS;
        let coverage = pts.len() as f64 / sent.len() as f64;
        let minimum_coverage = minimum_overload_coverage(case.delivered_fps);
        if !overload_case || coverage < minimum_coverage || pts.len() > sent.len() {
            return Err(format!(
                "frame count mismatch: sent {} frames, container has {} \
                 (missing sent indices: {})",
                sent.len(),
                pts.len(),
                unmatched_sent_indices(&sent, &pts, 1.0 / f64::from(case.delivered_fps.max(1)))
            ));
        }

        let sent_origin = sent[0];
        let pts_origin = pts[0];
        let mut max_rel: f64 = 0.0;
        let mut j = 0usize;
        for (i, &p) in pts.iter().enumerate() {
            let rel_p = p - pts_origin;
            while j + 1 < sent.len()
                && ((sent[j + 1] - sent_origin) - rel_p).abs()
                    <= ((sent[j] - sent_origin) - rel_p).abs()
            {
                j += 1;
            }
            let rel = (rel_p - (sent[j] - sent_origin)).abs();
            max_rel = max_rel.max(rel);
            if rel > rel_tolerance {
                return Err(format!(
                    "muxed frame {i}: no sent timestamp within {rel_tolerance:.3}s \
                     (pts {p:.3}s, nearest sent {:.3}s, err {rel:.3}s)",
                    sent[j]
                ));
            }
        }
        // Burst collapse piles muxed frames onto instants the sent timeline
        // never had; nearest-matching alone scores that as zero error. Every
        // generator dedups its timeline at exactly this threshold
        // (period * 0.25), so consecutive sent pairs are never tight and
        // sent_tight is identically zero today — the operative bound is the
        // 5% absolute slack for boundary effects. The sent term stays as a
        // scaling guard in case a future generator legitimately emits
        // tighter cadences than its dedup spacing.
        //
        // Applied only at production-representative rates: on a synthetic
        // >240fps firehose a CI runner drains the bounded channel in bursts
        // and the drift tracker truthfully re-pins those frames tightly
        // (three consecutive CI failures, all >850fps delivered; fast
        // machines never cluster). At those rates this check measures
        // runner drain speed, not muxer correctness — span, gap, and
        // coverage checks keep guarding the overload path.
        if !overload_case {
            let tight = 0.25 / f64::from(case.delivered_fps.max(1));
            let tight_rate = |xs: &[f64]| {
                if xs.len() < 2 {
                    return 0.0;
                }
                let tight_pairs = xs.windows(2).filter(|w| w[1] - w[0] < tight).count();
                tight_pairs as f64 / (xs.len() - 1) as f64
            };
            let muxed_tight = tight_rate(&pts);
            let sent_tight = tight_rate(&sent);
            if muxed_tight > sent_tight * 1.5 + 0.05 {
                return Err(format!(
                    "muxed pts cluster far beyond the sent timeline (tight-pair rate \
                     {:.1}% vs sent {:.1}% at <{tight:.6}s) — burst collapse under overload",
                    muxed_tight * 100.0,
                    sent_tight * 100.0
                ));
            }
        }

        // Drops shorten coverage but must not shrink the recorded span
        // beyond the dropped tail/head, and must never stretch it.
        if let Some((first, last)) = finished.video_timestamp_span {
            let span = last.saturating_sub(first).as_secs_f64();
            let expected = sent.last().unwrap() - sent[0];
            if span > expected + 0.25 || span < expected - 0.5 {
                return Err(format!(
                    "video_timestamp_span {span:.3}s does not match sent span \
                     {expected:.3}s under overload"
                ));
            }
        } else {
            return Err("video_timestamp_span missing".to_string());
        }

        // Gap preservation still holds under drops: dropping frames can only
        // widen a container gap, so a collapsed gap is a real timestamp bug.
        let max_sent_gap = sent.windows(2).map(|w| w[1] - w[0]).fold(0.0, f64::max);
        if max_sent_gap > 1.0 {
            let max_pts_gap = pts.windows(2).map(|w| w[1] - w[0]).fold(0.0, f64::max);
            if max_pts_gap < max_sent_gap * 0.9 {
                return Err(format!(
                    "{max_sent_gap:.2}s capture gap collapsed to {max_pts_gap:.3}s \
                     in the container under overload"
                ));
            }
        }

        return Ok(format!(
            "{} of {} frames muxed under {}fps overload (drops allowed), max rel err {max_rel:.3}s",
            pts.len(),
            sent.len(),
            case.delivered_fps
        ));
    }

    let mut max_abs: f64 = 0.0;
    let mut max_rel: f64 = 0.0;
    // The muxed timeline's origin is the first DELIVERED frame: the pipeline
    // zeroes each track at its first frame and the recorder persists the
    // track's start_time for cross-track alignment. A random case whose
    // leading frames were dropped therefore legitimately muxes pts starting
    // near 0, not at sent[0]; compare against the origin-normalized sent
    // timeline. The fixed absolute bound stays valid at any frame rate the
    // generator produces (fps >= 10 keeps rel_tolerance <= ABS_TOLERANCE):
    // a constant whole-track offset does not scale with frame period.
    let sent_origin = sent[0];
    for (i, (&p, &s)) in pts.iter().zip(&sent).enumerate() {
        max_abs = max_abs.max((p - (s - sent_origin)).abs());
        let rel = ((p - pts[0]) - (s - sent_origin)).abs();
        max_rel = max_rel.max(rel);
        if rel > rel_tolerance {
            return Err(format!(
                "frame {i}: relative pts error {rel:.3}s (pts {p:.3}s vs sent {s:.3}s)"
            ));
        }
    }
    if max_abs > ABS_TOLERANCE_SECS {
        return Err(format!(
            "absolute pts error {max_abs:.3}s exceeds tolerance"
        ));
    }

    // The span the recorder would persist must match the sent span.
    if let Some((first, last)) = finished.video_timestamp_span {
        let span = last.saturating_sub(first).as_secs_f64();
        let expected = sent.last().unwrap() - sent[0];
        if (span - expected).abs() > 0.25 {
            return Err(format!(
                "video_timestamp_span {span:.3}s does not match sent span {expected:.3}s"
            ));
        }
    } else {
        return Err("video_timestamp_span missing".to_string());
    }

    // Gap preservation is the regression that desynced 0.5.4: every gap in
    // the sent timeline must survive into the container.
    let max_sent_gap = sent.windows(2).map(|w| w[1] - w[0]).fold(0.0, f64::max);
    if max_sent_gap > 1.0 {
        let max_pts_gap = pts.windows(2).map(|w| w[1] - w[0]).fold(0.0, f64::max);
        if max_pts_gap < max_sent_gap * 0.9 {
            return Err(format!(
                "{max_sent_gap:.2}s capture gap collapsed to {max_pts_gap:.3}s in the container"
            ));
        }
    }

    Ok(format!(
        "{} frames, max abs err {:.0} ms, max rel err {:.0} ms",
        pts.len(),
        max_abs * 1000.0,
        max_rel * 1000.0
    ))
}

/// A mid-recording pause (instant mode): emission continues in real time but
/// the pipeline drops frames while paused. The pause must be EXCISED from the
/// output timeline — video pts must stay continuous across it (matching how
/// audio drops paused samples and how the wall clock subtracts pauses), and
/// the container must contain only the unpaused content. A regression here
/// previously poisoned the drift anchor with pause-inflated time whenever the
/// pause began before the ~2s warmup anchor existed.
async fn run_video_pause_case() -> Result<String, String> {
    const PRE_PAUSE_SECS: f64 = 1.0;
    const PAUSE_SECS: f64 = 2.5;
    const POST_PAUSE_SECS: f64 = 2.0;
    const FPS: u32 = 30;

    let temp = tempfile::tempdir().map_err(|e| format!("tempdir: {e}"))?;
    let out_path = temp.path().join("display.mp4");

    let info = VideoInfo::from_raw(cap_media_info::RawVideoFormat::Bgra, 160, 120, FPS);
    let (tx, rx) = flume::bounded::<FFmpegVideoFrame>(32);
    let timestamps = Timestamps::now();

    let total_secs = PRE_PAUSE_SECS + PAUSE_SECS + POST_PAUSE_SECS;
    let emit = {
        let base = timestamps.instant();
        let mut rng = Rng(7);
        tokio::spawn(async move {
            let period = 1.0 / f64::from(FPS);
            let count = (total_secs * f64::from(FPS)) as u64;
            for k in 0..count {
                let ts = k as f64 * period;
                tokio::time::sleep_until((base + Duration::from_secs_f64(ts)).into()).await;
                let frame = FFmpegVideoFrame {
                    inner: make_video_frame(160, 120, k, Content::Flat, &mut rng),
                    timestamp: Timestamp::Instant(base + Duration::from_secs_f64(ts)),
                };
                if tx.send_async(frame).await.is_err() {
                    break;
                }
            }
        })
    };

    let pipeline = OutputPipeline::builder(out_path.clone())
        .with_video::<ChannelVideoSource<FFmpegVideoFrame>>(ChannelVideoSourceConfig::new(info, rx))
        .with_timestamps(timestamps)
        .build::<Mp4Muxer>(())
        .await
        .map_err(|e| format!("pipeline build: {e}"))?;

    tokio::time::sleep(Duration::from_secs_f64(PRE_PAUSE_SECS)).await;
    let pause_started = std::time::Instant::now();
    pipeline.pause();
    tokio::time::sleep(Duration::from_secs_f64(PAUSE_SECS)).await;
    pipeline.resume();
    let actual_pause = pause_started.elapsed().as_secs_f64();

    emit.await.map_err(|e| format!("emit join: {e}"))?;
    let emit_lag = timestamps.instant().elapsed().as_secs_f64() - total_secs;
    tokio::time::sleep(Duration::from_millis(500)).await;
    pipeline.stop().await.map_err(|e| format!("stop: {e}"))?;
    // The assertions below compare the muxed span against the intended
    // pause/content windows; a runner too stalled to hit those windows
    // invalidates the comparison, not the pipeline.
    if emit_lag > 1.5 || (actual_pause - PAUSE_SECS).abs() > 0.5 {
        return Ok(format!(
            "skipped: runner too slow (emission lag {emit_lag:.1}s, pause window {actual_pause:.2}s)"
        ));
    }

    let pts = read_video_pts(&out_path)?;
    if pts.len() < 8 {
        return Err(format!("only {} frames muxed", pts.len()));
    }

    // The pause is excised: the muxed span must cover roughly the unpaused
    // content, not the wall-clock run.
    let span = pts.last().unwrap() - pts[0];
    let expected = PRE_PAUSE_SECS + POST_PAUSE_SECS;
    if (span - expected).abs() > 0.6 {
        return Err(format!(
            "muxed span {span:.2}s should be about the unpaused content {expected:.2}s \
             (pause leaked into the timeline)"
        ));
    }

    // And no single pts step may contain the pause.
    let max_gap = pts.windows(2).map(|w| w[1] - w[0]).fold(0.0, f64::max);
    if max_gap > PAUSE_SECS * 0.8 {
        return Err(format!(
            "pause survived as a {max_gap:.2}s pts gap in the container"
        ));
    }

    // Post-resume continuity is the discriminating check: without the pause
    // excision the anomaly tracker accepts the pause as a confirmed jump and
    // the drift tracker's wall cap re-pins the post-resume segment ~one
    // tolerance late (measured +0.13s vs +0.03s with the fix). The median
    // over the whole segment is immune to per-frame scheduler jitter.
    let period = 1.0 / f64::from(FPS);
    let split = pts
        .windows(2)
        .position(|w| w[1] - w[0] == max_gap)
        .unwrap_or(0);
    let pre_last = pts[split];
    let mut post_offsets: Vec<f64> = pts[split + 1..]
        .iter()
        .enumerate()
        .map(|(k, &p)| p - (pre_last + (k as f64 + 1.0) * period))
        .collect();
    post_offsets.sort_by(|a, b| a.partial_cmp(b).unwrap());
    let continuity = post_offsets
        .get(post_offsets.len() / 2)
        .copied()
        .unwrap_or(0.0);
    if continuity.abs() > 0.08 {
        return Err(format!(
            "post-resume frames resume {continuity:+.3}s off the pre-pause timeline \
             (pause bled into the drift anchor)"
        ));
    }

    Ok(format!(
        "{} frames, span {span:.2}s (expected ~{expected:.2}s), max pts gap {max_gap:.2}s, \
         post-resume continuity {continuity:+.3}s",
        pts.len()
    ))
}

#[derive(Clone, Copy)]
struct AudioCase {
    rate: u32,
    channels: u16,
    /// Device buffer size in milliseconds; real hardware spans ~3-90ms.
    chunk_ms: f64,
    /// Source clock drift factor: samples arrive slightly faster or slower
    /// than their nominal rate, as real device crystals do.
    drift: f64,
}

impl AudioCase {
    fn curated(rate: u32, channels: u16) -> Self {
        Self {
            rate,
            channels,
            chunk_ms: 20.0,
            drift: 1.0,
        }
    }
}

async fn run_audio_case(case: AudioCase) -> Result<String, String> {
    let AudioCase {
        rate,
        channels,
        chunk_ms,
        drift,
    } = case;
    let temp = tempfile::tempdir().map_err(|e| format!("tempdir: {e}"))?;
    let out_path = temp.path().join("audio.ogg");

    let info = AudioInfo::new(Sample::F32(Type::Packed), rate, channels)
        .map_err(|e| format!("audio info: {e:?}"))?;
    let (tx, rx) = futures::channel::mpsc::channel::<AudioFrame>(32);
    let timestamps = Timestamps::now();

    let chunk_frames = ((f64::from(rate) * chunk_ms / 1000.0) as usize).max(16);
    let chunk_secs = chunk_frames as f64 / f64::from(rate);
    let total_chunks = (CONTENT_SECS / chunk_secs).ceil() as usize;

    let emit = {
        let base = timestamps.instant();
        let mut tx = tx;
        tokio::spawn(async move {
            use futures::SinkExt;
            for k in 0..total_chunks {
                let real_t = k as f64 * chunk_secs;
                let ts = real_t * drift;
                tokio::time::sleep_until((base + Duration::from_secs_f64(real_t)).into()).await;
                let mut frame = ffmpeg::frame::Audio::new(
                    ffmpeg::format::Sample::F32(ffmpeg::format::sample::Type::Packed),
                    chunk_frames,
                    info.channel_layout(),
                );
                frame.set_rate(rate);
                let data = frame.data_mut(0);
                for (i, sample) in bytemuck_cast_f32(data).iter_mut().enumerate() {
                    let n = (k * chunk_frames + i / channels as usize) as f32;
                    *sample = (n * 440.0 * 2.0 * std::f32::consts::PI / rate as f32).sin() * 0.4;
                }
                let frame = AudioFrame::new(
                    frame,
                    Timestamp::Instant(base + Duration::from_secs_f64(ts)),
                );
                if tx.send(frame).await.is_err() {
                    break;
                }
            }
        })
    };

    let pipeline = OutputPipeline::builder(out_path.clone())
        .with_audio_source::<ChannelAudioSource>(ChannelAudioSourceConfig::new(info, rx))
        .with_timestamps(timestamps)
        .build::<OggMuxer>(OggMuxerConfig::default())
        .await
        .map_err(|e| format!("pipeline build: {e}"))?;

    emit.await.map_err(|e| format!("emit join: {e}"))?;
    let emit_lag = timestamps.instant().elapsed().as_secs_f64() - CONTENT_SECS;
    tokio::time::sleep(Duration::from_millis(300)).await;
    pipeline.stop().await.map_err(|e| format!("stop: {e}"))?;
    if emit_lag > 1.5 {
        return Ok(format!(
            "skipped: runner fell {emit_lag:.1}s behind real-time emission"
        ));
    }

    let (duration, decoded_channels, energy) = read_audio_stats(&out_path)?;
    if (duration - CONTENT_SECS).abs() > AUDIO_DURATION_TOLERANCE_SECS {
        return Err(format!(
            "decoded duration {duration:.3}s vs expected {CONTENT_SECS:.3}s \
             (rate handling error: content plays at the wrong speed)"
        ));
    }
    if energy < 0.01 {
        return Err(format!(
            "decoded audio is nearly silent (rms {energy:.4}); samples were lost or zeroed"
        ));
    }

    Ok(format!(
        "duration {duration:.3}s, {decoded_channels} ch decoded, rms {energy:.3}"
    ))
}

fn bytemuck_cast_f32(data: &mut [u8]) -> &mut [f32] {
    let len = data.len() / 4;
    unsafe { std::slice::from_raw_parts_mut(data.as_mut_ptr().cast::<f32>(), len) }
}

/// Tolerance for where audible content sits inside a decoded track. Bounded
/// by the emission chunk size, the muxer gap threshold (70ms), codec frame
/// granularity and CI scheduler noise.
const CONTENT_POSITION_TOLERANCE_SECS: f64 = 0.25;

/// System-audio (WASAPI-loopback-style) delivery: packets only exist while
/// something plays. The recorder sees a late first packet, dead zones with no
/// delivery at all, and possibly nothing after the last sound. The muxed
/// track must still span the whole recording with every burst at its true
/// wall-clock position and `first_timestamp` at the recording epoch.
struct SystemAudioCase {
    /// (start_secs, end_secs) of each burst of real packet delivery.
    bursts: Vec<(f64, f64)>,
    /// Wall-clock stop point of the recording.
    total_secs: f64,
}

/// Emits loopback-style bursts on `tx` in real time, using 80ms chunks (the
/// buffer size our Windows loopback capturer targets).
///
/// Returns the sender when done: real capture sources hold their channel
/// open until the recording stops (the mic feed and the system-audio watcher
/// both keep sender clones), so the test must too — dropping it early would
/// end the mux loop through channel-closure instead of stop-cancellation.
fn spawn_burst_emitter(
    mut tx: futures::channel::mpsc::Sender<AudioFrame>,
    info: AudioInfo,
    timestamps: Timestamps,
    bursts: Vec<(f64, f64)>,
) -> tokio::task::JoinHandle<futures::channel::mpsc::Sender<AudioFrame>> {
    const CHUNK_SECS: f64 = 0.08;
    let rate = info.sample_rate;
    let channels = info.channels;
    let base = timestamps.instant();

    tokio::spawn(async move {
        use futures::SinkExt;
        for (start, end) in bursts {
            let chunk_frames = (f64::from(rate) * CHUNK_SECS) as usize;
            let chunks = ((end - start) / CHUNK_SECS).round() as usize;
            for k in 0..chunks {
                let t = start + k as f64 * CHUNK_SECS;
                tokio::time::sleep_until((base + Duration::from_secs_f64(t)).into()).await;
                let mut frame = ffmpeg::frame::Audio::new(
                    ffmpeg::format::Sample::F32(ffmpeg::format::sample::Type::Packed),
                    chunk_frames,
                    info.channel_layout(),
                );
                frame.set_rate(rate);
                for (i, sample) in bytemuck_cast_f32(frame.data_mut(0)).iter_mut().enumerate() {
                    let n = (i / channels) as f32 + (t * f64::from(rate)) as f32;
                    *sample = (n * 440.0 * 2.0 * std::f32::consts::PI / rate as f32).sin() * 0.4;
                }
                let frame =
                    AudioFrame::new(frame, Timestamp::Instant(base + Duration::from_secs_f64(t)));
                if tx.send(frame).await.is_err() {
                    return tx;
                }
            }
        }
        tx
    })
}

/// Decodes the first channel and returns (windowed rms envelope, window secs).
fn read_audio_envelope(path: &Path, win_secs: f64) -> Result<(Vec<f64>, f64), String> {
    let mut ictx = ffmpeg::format::input(&path).map_err(|e| format!("open {e}"))?;
    let stream = ictx
        .streams()
        .best(ffmpeg::media::Type::Audio)
        .ok_or("no audio stream")?;
    let index = stream.index();
    let ctx = ffmpeg::codec::context::Context::from_parameters(stream.parameters())
        .map_err(|e| format!("params: {e}"))?;
    let mut decoder = ctx.decoder().audio().map_err(|e| format!("decoder: {e}"))?;

    let mut samples: Vec<f64> = Vec::new();
    let mut rate = 0u32;
    let mut frame = ffmpeg::frame::Audio::empty();
    let drain = |decoder: &mut ffmpeg::decoder::Audio,
                 samples: &mut Vec<f64>,
                 rate: &mut u32,
                 frame: &mut ffmpeg::frame::Audio| {
        while decoder.receive_frame(frame).is_ok() {
            *rate = frame.rate();
            if let ffmpeg::format::Sample::F32(ffmpeg::format::sample::Type::Planar) =
                frame.format()
            {
                samples.extend(
                    frame.plane::<f32>(0)[..frame.samples()]
                        .iter()
                        .map(|&v| f64::from(v)),
                );
            }
        }
    };
    for (s, packet) in ictx.packets() {
        if s.index() != index {
            continue;
        }
        if decoder.send_packet(&packet).is_ok() {
            drain(&mut decoder, &mut samples, &mut rate, &mut frame);
        }
    }
    let _ = decoder.send_eof();
    drain(&mut decoder, &mut samples, &mut rate, &mut frame);

    if rate == 0 || samples.is_empty() {
        return Err("no audio decoded".to_string());
    }
    let win = ((f64::from(rate) * win_secs) as usize).max(1);
    let env: Vec<f64> = samples
        .chunks(win)
        .map(|c| (c.iter().map(|v| v * v).sum::<f64>() / c.len() as f64).sqrt())
        .collect();
    Ok((env, win as f64 / f64::from(rate)))
}

/// Regions of the envelope above `thresh`, merged across single-window dips,
/// dropping blips shorter than 0.15s.
fn active_spans(env: &[f64], win_secs: f64, thresh: f64) -> Vec<(f64, f64)> {
    let mut spans: Vec<(f64, f64)> = Vec::new();
    let mut current: Option<(usize, usize)> = None;
    for (i, &v) in env.iter().enumerate() {
        if v > thresh {
            current = match current {
                Some((s, _)) => Some((s, i)),
                None => Some((i, i)),
            };
        } else if let Some((s, e)) = current
            && i > e + 1
        {
            spans.push((s as f64 * win_secs, (e + 1) as f64 * win_secs));
            current = None;
        }
    }
    if let Some((s, e)) = current {
        spans.push((s as f64 * win_secs, (e + 1) as f64 * win_secs));
    }
    spans.retain(|(s, e)| e - s >= 0.15);
    spans
}

fn check_spans(
    decoded: &[(f64, f64)],
    expected: &[(f64, f64)],
    track_offset_secs: f64,
) -> Result<(), String> {
    if decoded.len() != expected.len() {
        return Err(format!(
            "expected {} audible bursts at {:?}, decoded {} at {:?} \
             (track offset {track_offset_secs:.3}s)",
            expected.len(),
            expected,
            decoded.len(),
            decoded,
        ));
    }
    for ((ds, de), (es, ee)) in decoded.iter().zip(expected) {
        // Positions are compared on the recording (epoch) timeline: the
        // decoded in-track position plus the track's start offset.
        let (ds, de) = (ds + track_offset_secs, de + track_offset_secs);
        if (ds - es).abs() > CONTENT_POSITION_TOLERANCE_SECS
            || (de - ee).abs() > CONTENT_POSITION_TOLERANCE_SECS
        {
            return Err(format!(
                "burst decoded at {ds:.3}..{de:.3}s on the recording timeline, \
                 emitted at {es:.3}..{ee:.3}s"
            ));
        }
    }
    Ok(())
}

async fn run_system_audio_case(case: SystemAudioCase) -> Result<String, String> {
    use cap_recording::AudioAnchor;

    let SystemAudioCase { bursts, total_secs } = case;
    let temp = tempfile::tempdir().map_err(|e| format!("tempdir: {e}"))?;
    let out_path = temp.path().join("system_audio.ogg");

    let info = AudioInfo::new(Sample::F32(Type::Packed), 48_000, 2)
        .map_err(|e| format!("audio info: {e:?}"))?;
    let (tx, rx) = futures::channel::mpsc::channel::<AudioFrame>(32);
    let timestamps = Timestamps::now();

    let emit = spawn_burst_emitter(tx, info, timestamps, bursts.clone());

    let pipeline = OutputPipeline::builder(out_path.clone())
        .with_audio_source::<ChannelAudioSource>(ChannelAudioSourceConfig::new(info, rx))
        .with_timestamps(timestamps)
        .with_audio_anchor(AudioAnchor::PipelineEpoch)
        .build::<OggMuxer>(OggMuxerConfig::default())
        .await
        .map_err(|e| format!("pipeline build: {e}"))?;

    let held_tx = emit.await.map_err(|e| format!("emit join: {e}"))?;
    tokio::time::sleep_until((timestamps.instant() + Duration::from_secs_f64(total_secs)).into())
        .await;
    let stop_lag = timestamps.instant().elapsed().as_secs_f64() - total_secs;
    let finished = pipeline.stop().await.map_err(|e| format!("stop: {e}"))?;
    drop(held_tx);
    if stop_lag > 1.5 {
        return Ok(format!(
            "skipped: runner fell {stop_lag:.1}s behind real-time emission"
        ));
    }

    // An intermittent track is anchored at the recording epoch, never at its
    // first packet: a late first sound must not be able to become the
    // cross-track start_time anchor.
    let start_offset = finished
        .first_timestamp
        .signed_duration_since_secs(timestamps);
    if start_offset.abs() > 0.05 {
        return Err(format!(
            "track start {start_offset:.3}s from the epoch; \
             an intermittent source must anchor at the recording start"
        ));
    }

    // Head silence, dead-zone silence and tail silence must all be
    // materialized: the track spans the whole recording.
    let (duration, _, _) = read_audio_stats(&out_path)?;
    if (duration - total_secs).abs() > AUDIO_DURATION_TOLERANCE_SECS + stop_lag {
        return Err(format!(
            "decoded duration {duration:.3}s vs recording span {total_secs:.3}s; \
             silence between/around bursts was not materialized"
        ));
    }

    // Every burst must sit at its true wall-clock position.
    let (env, win) = read_audio_envelope(&out_path, 0.05)?;
    let spans = active_spans(&env, win, 0.08);
    check_spans(&spans, &bursts, start_offset)?;

    Ok(format!(
        "duration {duration:.3}s, start {start_offset:+.3}s, {} bursts in place",
        spans.len()
    ))
}

/// The reported regression shape: a continuous mic and an intermittent
/// system-audio source recorded simultaneously (separate pipelines sharing
/// the recording epoch, exactly like studio mode). Every piece of content in
/// BOTH tracks must resolve to its true wall-clock position through each
/// track's own start_time — the presence of system audio must not move the
/// mic, and vice versa.
async fn run_mic_with_system_audio_case() -> Result<String, String> {
    use cap_recording::AudioAnchor;

    const MIC_START_SECS: f64 = 0.15;
    const TOTAL_SECS: f64 = 4.5;
    let system_bursts: Vec<(f64, f64)> = vec![(1.2, 2.0), (3.4, 4.1)];

    let temp = tempfile::tempdir().map_err(|e| format!("tempdir: {e}"))?;
    let mic_path = temp.path().join("audio-input.ogg");
    let sys_path = temp.path().join("system_audio.ogg");

    let info = AudioInfo::new(Sample::F32(Type::Packed), 48_000, 2)
        .map_err(|e| format!("audio info: {e:?}"))?;
    let timestamps = Timestamps::now();

    let (mic_tx, mic_rx) = futures::channel::mpsc::channel::<AudioFrame>(32);
    let (sys_tx, sys_rx) = futures::channel::mpsc::channel::<AudioFrame>(32);

    // The mic delivers continuously from device-ready at 0.15s to stop.
    let mic_emit =
        spawn_burst_emitter(mic_tx, info, timestamps, vec![(MIC_START_SECS, TOTAL_SECS)]);
    let sys_emit = spawn_burst_emitter(sys_tx, info, timestamps, system_bursts.clone());

    let mic_pipeline = OutputPipeline::builder(mic_path.clone())
        .with_audio_source::<ChannelAudioSource>(ChannelAudioSourceConfig::new(info, mic_rx))
        .with_timestamps(timestamps)
        .build::<OggMuxer>(OggMuxerConfig::default())
        .await
        .map_err(|e| format!("mic pipeline build: {e}"))?;
    let sys_pipeline = OutputPipeline::builder(sys_path.clone())
        .with_audio_source::<ChannelAudioSource>(ChannelAudioSourceConfig::new(info, sys_rx))
        .with_timestamps(timestamps)
        .with_audio_anchor(AudioAnchor::PipelineEpoch)
        .build::<OggMuxer>(OggMuxerConfig::default())
        .await
        .map_err(|e| format!("system pipeline build: {e}"))?;

    let (mic_join, sys_join) = tokio::join!(mic_emit, sys_emit);
    let mic_held_tx = mic_join.map_err(|e| format!("mic emit join: {e}"))?;
    let sys_held_tx = sys_join.map_err(|e| format!("sys emit join: {e}"))?;
    tokio::time::sleep_until((timestamps.instant() + Duration::from_secs_f64(TOTAL_SECS)).into())
        .await;
    let stop_lag = timestamps.instant().elapsed().as_secs_f64() - TOTAL_SECS;
    let (mic_finished, sys_finished) = tokio::join!(mic_pipeline.stop(), sys_pipeline.stop());
    let mic_finished = mic_finished.map_err(|e| format!("mic stop: {e}"))?;
    let sys_finished = sys_finished.map_err(|e| format!("sys stop: {e}"))?;
    drop((mic_held_tx, sys_held_tx));
    if stop_lag > 1.5 {
        return Ok(format!(
            "skipped: runner fell {stop_lag:.1}s behind real-time emission"
        ));
    }

    // Mic keeps first-frame anchoring: its start_time is device-ready.
    let mic_start = mic_finished
        .first_timestamp
        .signed_duration_since_secs(timestamps);
    if (mic_start - MIC_START_SECS).abs() > 0.05 {
        return Err(format!(
            "mic start_time {mic_start:.3}s, expected {MIC_START_SECS:.3}s: \
             recording system audio simultaneously must not move the mic anchor"
        ));
    }

    let sys_start = sys_finished
        .first_timestamp
        .signed_duration_since_secs(timestamps);
    if sys_start.abs() > 0.05 {
        return Err(format!(
            "system audio start_time {sys_start:.3}s, expected the epoch"
        ));
    }

    // Content must land at its true wall-clock position through each track's
    // own start offset — this is exactly the invariant the editor's
    // start_time-based alignment depends on.
    let (mic_env, mic_win) = read_audio_envelope(&mic_path, 0.05)?;
    let mic_spans = active_spans(&mic_env, mic_win, 0.08);
    check_spans(&mic_spans, &[(MIC_START_SECS, TOTAL_SECS)], mic_start)?;

    let (sys_env, sys_win) = read_audio_envelope(&sys_path, 0.05)?;
    let sys_spans = active_spans(&sys_env, sys_win, 0.08);
    check_spans(&sys_spans, &system_bursts, sys_start)?;

    // Both tracks span to the stop point (tail silence materialized).
    let (mic_duration, _, _) = read_audio_stats(&mic_path)?;
    let mic_expected = TOTAL_SECS - MIC_START_SECS;
    if (mic_duration - mic_expected).abs() > AUDIO_DURATION_TOLERANCE_SECS + stop_lag {
        return Err(format!(
            "mic duration {mic_duration:.3}s vs expected {mic_expected:.3}s"
        ));
    }
    let (sys_duration, _, _) = read_audio_stats(&sys_path)?;
    if (sys_duration - TOTAL_SECS).abs() > AUDIO_DURATION_TOLERANCE_SECS + stop_lag {
        return Err(format!(
            "system audio duration {sys_duration:.3}s vs recording span {TOTAL_SECS:.3}s"
        ));
    }

    Ok(format!(
        "mic start {mic_start:.3}s dur {mic_duration:.3}s; \
         system start {sys_start:+.3}s dur {sys_duration:.3}s; all content in place"
    ))
}

/// Concatenates a fragmented-mp4 segment directory (init.mp4 + *.m4s) into a
/// single playable file.
fn concat_fmp4(dir: &Path, scratch: &Path) -> Result<PathBuf, String> {
    let init = dir.join("init.mp4");
    let mut bytes = std::fs::read(&init).map_err(|e| format!("read init.mp4: {e}"))?;
    let mut segments: Vec<PathBuf> = std::fs::read_dir(dir)
        .map_err(|e| format!("read segment dir: {e}"))?
        .filter_map(|e| e.ok().map(|e| e.path()))
        .filter(|p| p.extension().is_some_and(|ext| ext == "m4s"))
        .collect();
    segments.sort();
    if segments.is_empty() {
        return Err("no media segments produced".to_string());
    }
    for segment in &segments {
        bytes.extend(std::fs::read(segment).map_err(|e| format!("read segment: {e}"))?);
    }
    let out = scratch.join("concat.mp4");
    std::fs::write(&out, bytes).map_err(|e| format!("write concat: {e}"))?;
    Ok(out)
}

fn read_video_pts(path: &Path) -> Result<Vec<f64>, String> {
    let mut ictx = ffmpeg::format::input(&path).map_err(|e| format!("open {e}"))?;
    let stream = ictx
        .streams()
        .best(ffmpeg::media::Type::Video)
        .ok_or("no video stream")?;
    let index = stream.index();
    let tb = stream.time_base();
    let tb = f64::from(tb.numerator()) / f64::from(tb.denominator());
    let mut pts: Vec<f64> = ictx
        .packets()
        .filter_map(|(s, p)| (s.index() == index).then_some(p.pts()).flatten())
        .map(|p| p as f64 * tb)
        .collect();
    pts.sort_by(|a, b| a.partial_cmp(b).unwrap());
    Ok(pts)
}

fn read_audio_stats(path: &Path) -> Result<(f64, u16, f64), String> {
    let mut ictx = ffmpeg::format::input(&path).map_err(|e| format!("open {e}"))?;
    let stream = ictx
        .streams()
        .best(ffmpeg::media::Type::Audio)
        .ok_or("no audio stream")?;
    let index = stream.index();
    let ctx = ffmpeg::codec::context::Context::from_parameters(stream.parameters())
        .map_err(|e| format!("params: {e}"))?;
    let mut decoder = ctx.decoder().audio().map_err(|e| format!("decoder: {e}"))?;

    let mut samples = 0u64;
    let mut rate = 0u32;
    let mut channels = 0u16;
    let mut sum_sq = 0.0f64;
    let mut counted = 0u64;
    let mut frame = ffmpeg::frame::Audio::empty();
    for (s, packet) in ictx.packets() {
        if s.index() != index {
            continue;
        }
        if decoder.send_packet(&packet).is_ok() {
            while decoder.receive_frame(&mut frame).is_ok() {
                samples += frame.samples() as u64;
                rate = frame.rate();
                channels = frame.channels();
                if let ffmpeg::format::Sample::F32(ffmpeg::format::sample::Type::Planar) =
                    frame.format()
                {
                    for &v in &frame.plane::<f32>(0)[..frame.samples()] {
                        sum_sq += f64::from(v) * f64::from(v);
                        counted += 1;
                    }
                }
            }
        }
    }
    let _ = decoder.send_eof();
    while decoder.receive_frame(&mut frame).is_ok() {
        samples += frame.samples() as u64;
    }

    if rate == 0 {
        return Err("no audio decoded".to_string());
    }
    let rms = if counted > 0 {
        (sum_sq / counted as f64).sqrt()
    } else {
        0.0
    };
    Ok((samples as f64 / f64::from(rate), channels, rms))
}

/// On a frame-count mismatch, name WHICH sent frames never reached the
/// container: a leading run ("0-4") means a startup stall/race, a spread
/// ("7, 23, 41") means mid-stream drops. Greedy monotone matcher — pts and
/// sent are both origin-normalized and sorted, a pts within 0.6 periods of
/// the sent slot consumes it.
fn unmatched_sent_indices(sent: &[f64], pts: &[f64], period: f64) -> String {
    let Some(&sent0) = sent.first() else {
        return "none".to_string();
    };
    let pts0 = pts.first().copied().unwrap_or(0.0);
    let window = period * 0.6;
    let mut missing: Vec<usize> = Vec::new();
    let mut i = 0usize;
    for (k, &s) in sent.iter().enumerate() {
        let rel_s = s - sent0;
        while i < pts.len() && (pts[i] - pts0) < rel_s - window {
            i += 1;
        }
        if i < pts.len() && ((pts[i] - pts0) - rel_s).abs() <= window {
            i += 1;
        } else {
            missing.push(k);
        }
    }
    if missing.is_empty() {
        return "none (pts shifted rather than missing)".to_string();
    }
    let mut runs: Vec<String> = Vec::new();
    let mut start = missing[0];
    let mut prev = missing[0];
    for &m in &missing[1..] {
        if m == prev + 1 {
            prev = m;
            continue;
        }
        runs.push(if start == prev {
            format!("{start}")
        } else {
            format!("{start}-{prev}")
        });
        start = m;
        prev = m;
    }
    runs.push(if start == prev {
        format!("{start}")
    } else {
        format!("{start}-{prev}")
    });
    runs.join(", ")
}

// Replaying a user's machine
// --------------------------
// `CAP_SYNC_MATRIX_FROM_REPORT=<path to a DiagnosticReport JSON>` replaces the
// curated matrix with cases built from that report's `matrixHints`, so a
// support report can be re-run locally against the shapes the reporter
// actually has:
//
//   CAP_SYNC_MATRIX_FROM_REPORT=~/Downloads/report.json \
//   CAP_SYNC_MATRIX_REPORT=/tmp/replay.json \
//     cargo test -p cap-recording --test sync_matrix -- --nocapture
//
// Every display hint is crossed with every audio-input hint, capped at
// MAX_REPORT_CASES pairs. The report is read through the local structs below
// rather than `cap_recording::diagnostics::DiagnosticReport` on purpose: a
// Windows report must be replayable on macOS, and the per-OS `SystemDiagnostics`
// in the envelope would not deserialize there.
//
// Case resolution is scaled down from the reported display size: the matrix
// generates frames in real time, so a 4K case would spend its budget on
// memcpy rather than on the timestamp behaviour under test. The real size
// stays in the case name.
const MAX_REPORT_CASES: usize = 12;
/// Longest edge of a replayed video case, in pixels.
const REPORT_CASE_MAX_EDGE: u32 = 640;

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct ReportEnvelope {
    #[serde(default, alias = "matrix_hints")]
    matrix_hints: Option<ReportMatrixHints>,
    #[serde(default, alias = "sync_test")]
    sync_test: Option<ReportSyncTest>,
}

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct ReportMatrixHints {
    #[serde(default)]
    video: Vec<ReportVideoHint>,
    #[serde(default, alias = "audio_inputs")]
    audio_inputs: Vec<ReportAudioHint>,
}

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct ReportVideoHint {
    #[serde(default)]
    width: u32,
    #[serde(default)]
    height: u32,
    #[serde(default, alias = "refresh_rate")]
    refresh_rate: u32,
    #[serde(default, alias = "configured_max_fps")]
    configured_max_fps: Option<u32>,
    #[serde(default)]
    fragmented: bool,
}

#[derive(Clone, Copy, Deserialize)]
#[serde(rename_all = "camelCase")]
struct ReportAudioHint {
    #[serde(default)]
    rate: u32,
    #[serde(default)]
    channels: u16,
    #[serde(default, alias = "buffer_range")]
    buffer_range: Option<(u32, u32)>,
}

/// The embedded `cap selftest av-sync` report, which serializes snake_case.
#[derive(Deserialize)]
struct ReportSyncTest {
    #[serde(default)]
    recording: Option<ReportMeasurement>,
}

#[derive(Deserialize)]
struct ReportMeasurement {
    #[serde(default, alias = "driftMsPerMin")]
    drift_ms_per_min: Option<f64>,
}

/// Scales a real display size into something the matrix can generate in real
/// time, preserving aspect ratio and keeping both dimensions even.
fn report_case_size(width: u32, height: u32) -> (u32, u32) {
    if width == 0 || height == 0 {
        return (160, 120);
    }
    let longest = width.max(height);
    let (w, h) = if longest <= REPORT_CASE_MAX_EDGE {
        (width, height)
    } else {
        let scale = f64::from(REPORT_CASE_MAX_EDGE) / f64::from(longest);
        (
            (f64::from(width) * scale).round() as u32,
            (f64::from(height) * scale).round() as u32,
        )
    };
    (w.max(16) & !1, h.max(16) & !1)
}

/// The chunk size to replay for one reported input.
///
/// A device's buffer-size range only says something about its real chunking
/// when it is narrow. CoreAudio/cpal reports `15..=4096` frames for essentially
/// every device, and taking the midpoint of that turns every microphone into
/// the same fabricated ~46ms chunk -- which is exactly what the replay is
/// supposed to avoid. So a wide range falls back to the curated matrix's 20ms
/// rather than inventing a number from it.
fn report_chunk_ms(rate: u32, buffer_range: Option<(u32, u32)>) -> f64 {
    const DEFAULT_CHUNK_MS: f64 = 20.0;
    const MAX_INFORMATIVE_RATIO: u32 = 8;

    buffer_range
        .filter(|(min, max)| {
            *min > 0 && *max >= *min && *max <= min.saturating_mul(MAX_INFORMATIVE_RATIO)
        })
        .map(|(min, max)| (f64::from(min) + f64::from(max)) / 2.0 / f64::from(rate) * 1000.0)
        .filter(|ms| ms.is_finite() && *ms >= 1.0 && *ms <= 200.0)
        .unwrap_or(DEFAULT_CHUNK_MS)
}

/// A wide buffer range says nothing about the device, so it must not become a
/// fabricated chunk size; a narrow one is the device's real shape.
#[test]
fn report_chunk_ms_only_trusts_a_narrow_buffer_range() {
    // What CoreAudio reports for nearly every device.
    assert_eq!(report_chunk_ms(48_000, Some((15, 4096))), 20.0);
    assert_eq!(report_chunk_ms(48_000, None), 20.0);
    // A device pinned to one buffer size, and a narrow range around it.
    assert!((report_chunk_ms(48_000, Some((512, 512))) - 10.666).abs() < 0.01);
    assert!((report_chunk_ms(48_000, Some((480, 960))) - 15.0).abs() < 0.01);
    // Narrow but out of the plausible range, and degenerate values.
    assert_eq!(report_chunk_ms(48_000, Some((1, 2))), 20.0);
    assert_eq!(report_chunk_ms(48_000, Some((0, 4096))), 20.0);
    assert_eq!(report_chunk_ms(48_000, Some((4096, 15))), 20.0);
    assert_eq!(report_chunk_ms(0, Some((480, 960))), 20.0);
}

#[test]
fn overload_coverage_preserves_supported_capture_throughput() {
    assert!((minimum_overload_coverage(240) - 0.9).abs() < f64::EPSILON);
    assert!((minimum_overload_coverage(480) - 0.45).abs() < f64::EPSILON);
    assert!((minimum_overload_coverage(1_000) - 0.216).abs() < f64::EPSILON);
    assert!(1620.0 / 3298.0 >= minimum_overload_coverage(938));
    assert!(700.0 / 3298.0 < minimum_overload_coverage(938));
}

fn cases_from_report(path: &Path) -> Result<Vec<(String, VideoCase, AudioCase)>, String> {
    let raw = std::fs::read_to_string(path).map_err(|e| format!("read {}: {e}", path.display()))?;
    let envelope: ReportEnvelope =
        serde_json::from_str(&raw).map_err(|e| format!("parse {}: {e}", path.display()))?;

    let hints = envelope
        .matrix_hints
        .ok_or_else(|| "report has no matrixHints".to_string())?;
    if hints.video.is_empty() {
        return Err("report matrixHints has no video entries".to_string());
    }

    // A measured recording drift becomes the audio source's crystal drift:
    // the audio clock running fast/slow against the wall clock is what the
    // measurement observed.
    let drift = envelope
        .sync_test
        .and_then(|test| test.recording)
        .and_then(|m| m.drift_ms_per_min)
        .filter(|d| d.is_finite())
        .map(|d| 1.0 + d / 60_000.0)
        .unwrap_or(1.0);

    let audio_hints: Vec<ReportAudioHint> = if hints.audio_inputs.is_empty() {
        vec![ReportAudioHint {
            rate: 48_000,
            channels: 2,
            buffer_range: None,
        }]
    } else {
        hints.audio_inputs.clone()
    };

    let mut cases = Vec::new();
    for video in &hints.video {
        for audio in &audio_hints {
            if cases.len() >= MAX_REPORT_CASES {
                return Ok(cases);
            }

            let refresh = if video.refresh_rate == 0 {
                60
            } else {
                video.refresh_rate.clamp(1, 240)
            };
            let fps = video
                .configured_max_fps
                .unwrap_or(60)
                .min(refresh)
                .clamp(1, 240);
            let (width, height) = report_case_size(video.width, video.height);

            let rate = if audio.rate == 0 { 48_000 } else { audio.rate };
            let channels = audio.channels.max(1);
            let chunk_ms = report_chunk_ms(rate, audio.buffer_range);

            let name = format!(
                "report/{}/video-{}x{}-nominal{fps}-delivered{refresh}-{}/audio-{rate}hz-{channels}ch-{chunk_ms:.0}ms-drift{:+.3}%",
                cases.len(),
                video.width,
                video.height,
                if video.fragmented {
                    "fragmented"
                } else {
                    "mp4"
                },
                (drift - 1.0) * 100.0,
            );

            cases.push((
                name,
                VideoCase {
                    fps,
                    delivered_fps: refresh,
                    sent: VideoScenario::Steady.timestamps(refresh),
                    fragmented: video.fragmented,
                    width,
                    height,
                    content: Content::Flat,
                    rng_seed: 1,
                },
                AudioCase {
                    rate,
                    channels,
                    chunk_ms,
                    drift,
                },
            ));
        }
    }

    Ok(cases)
}

async fn run_report_replay(path: &str, results: &mut Vec<CaseResult>) {
    let cases = match cases_from_report(Path::new(path)) {
        Ok(cases) => cases,
        Err(e) => {
            record(
                results,
                "report/load".to_string(),
                Err(format!("could not build cases from {path}: {e}")),
            );
            return;
        }
    };

    eprintln!("replaying {} cases from {path}", cases.len());

    for (name, video, audio) in cases {
        // Both legs run concurrently, as a real recording does.
        let (video_outcome, audio_outcome) =
            tokio::join!(run_video_case_with_cold_retry(video), run_audio_case(audio));
        let outcome = match (video_outcome, audio_outcome) {
            (Ok(v), Ok(a)) => Ok(format!("video: {v}; audio: {a}")),
            (Err(e), _) => Err(format!("video leg: {e}")),
            (_, Err(e)) => Err(format!("audio leg: {e}")),
        };
        record(results, name, outcome);
    }
}

fn record(results: &mut Vec<CaseResult>, name: String, outcome: Result<String, String>) {
    eprintln!(
        "{name}: {}",
        match &outcome {
            Ok(d) => format!("ok ({d})"),
            Err(e) => format!("FAIL ({e})"),
        }
    );
    results.push(CaseResult {
        name,
        pass: outcome.is_ok(),
        detail: outcome.unwrap_or_else(|e| e),
    });
}

/// A fully random capture shape: arbitrary fps, resolution, encoder-load
/// content, timestamp jitter, random drops, and 0-2 gaps at random positions
/// (including inside the first two seconds, where the drift anchor does not
/// exist yet).
fn random_video_case(rng: &mut Rng) -> VideoCase {
    let fps = rng.range(10, 120) as u32;
    // Half the time the device free-runs at a rate unrelated to the
    // configured one — anywhere up to a 1000fps camera.
    let delivered_fps = if rng.f64() < 0.5 {
        rng.range(10, 1000) as u32
    } else {
        fps
    };
    let (width, height) = rng.pick(&[(160u32, 120u32), (320, 240), (640, 360)]);
    let content = rng.pick(&[Content::Flat, Content::Noise, Content::Motion]);
    let fragmented = rng.f64() < 0.75;

    let period = 1.0 / f64::from(delivered_fps);
    let jitter = rng.f64() * 0.45;
    let drop_prob = rng.f64() * 0.25;
    let gap_count = rng.range(0, 2);
    let mut gaps: Vec<(f64, f64)> = (0..gap_count)
        .map(|_| {
            let at = 0.4 + rng.f64() * (CONTENT_SECS - 1.0);
            let len = 1.2 + rng.f64() * 2.0;
            (at, len)
        })
        .collect();
    gaps.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap());

    let total = (CONTENT_SECS * f64::from(delivered_fps)) as u64;
    let mut sent = Vec::new();
    for k in 0..total {
        if rng.f64() < drop_prob {
            continue;
        }
        let base = k as f64 * period;
        let mut ts = (base + (rng.f64() - 0.5) * period * jitter).max(0.0);
        for &(at, len) in &gaps {
            if ts >= at {
                ts += len;
            }
        }
        sent.push(ts);
    }
    sent.sort_by(|a, b| a.partial_cmp(b).unwrap());
    sent.dedup_by(|a, b| (*a - *b).abs() < period * 0.25);
    // Guarantee at least a handful of frames survive the drop lottery.
    if sent.len() < 8 {
        sent = (0..total).map(|k| k as f64 * period).collect();
    }

    VideoCase {
        fps,
        delivered_fps,
        sent,
        fragmented,
        width,
        height,
        content,
        rng_seed: rng.next(),
    }
}

/// A random audio device shape: any rate from the set real devices negotiate,
/// 1-8 channels, real-world buffer sizes, and a small crystal drift.
fn random_audio_case(rng: &mut Rng) -> AudioCase {
    let rate = rng.pick(&[
        8_000u32, 11_025, 12_000, 16_000, 22_050, 24_000, 32_000, 44_100, 48_000, 88_200, 96_000,
        176_400, 192_000,
    ]);
    let channels = rng.range(1, 8) as u16;
    let chunk_ms = 3.0 + rng.f64() * 85.0;
    let drift = 1.0 + (rng.f64() - 0.5) * 0.002; // +-0.1%

    AudioCase {
        rate,
        channels,
        chunk_ms,
        drift,
    }
}

/// Runs a throwaway pipeline so the platform h264 encoder's one-time session
/// initialization happens before any timed case. On macOS, h264_videotoolbox
/// blocks ~1.5s on its very first frame in a process; the first matrix case
/// would pay that stall, overflow the muxer's bounded channel, and drop its
/// startup frames (observed as the 15fps/fragmented case losing 3-22 of 60
/// frames depending on load).
///
/// The warm-up must run PAST the first segment cut, not just the first
/// accepted frame: VideoToolbox defers parts of session bring-up until real
/// packets flow, and the DASH muxer's first segment write has its own
/// first-use cost. A 3-frame warm-up stopped before either happened and the
/// first real case still stalled 1-3s on fast machines running newer macOS.
async fn warm_up_video_encoder() {
    let Ok(temp) = tempfile::tempdir() else {
        return;
    };
    let info = VideoInfo::from_raw(cap_media_info::RawVideoFormat::Bgra, 160, 120, 30);
    let (tx, rx) = flume::bounded::<FFmpegVideoFrame>(8);
    let timestamps = Timestamps::now();
    let base = timestamps.instant();
    let mut rng = Rng(1);
    let Ok(pipeline) = OutputPipeline::builder(temp.path().join("warmup"))
        .with_video::<ChannelVideoSource<FFmpegVideoFrame>>(ChannelVideoSourceConfig::new(info, rx))
        .with_timestamps(timestamps)
        .build::<SegmentedVideoMuxer>(SegmentedVideoMuxerConfig {
            segment_duration: Duration::from_secs(2),
            ..Default::default()
        })
        .await
    else {
        return;
    };
    // 2.2s of timestamps crosses the 2s segment boundary; frames are pushed
    // as fast as the encoder accepts them (no real-time pacing needed).
    for i in 0..66u64 {
        let frame = FFmpegVideoFrame {
            inner: make_video_frame(160, 120, i, Content::Flat, &mut rng),
            timestamp: Timestamp::Instant(base + Duration::from_millis(i * 33)),
        };
        if tx.send_async(frame).await.is_err() {
            break;
        }
    }
    drop(tx);
    // Blocks until the cold encoder session is live and drained.
    let _ = pipeline.stop().await;
}

/// One retry for a failed video case. A cold system pays one-time costs
/// (VideoToolbox service bring-up, first DASH segment write) INSIDE the
/// pipeline where no emitter-side guard can see them; the muxer's stall
/// budget then drops frames mid-case exactly as production would, and the
/// case fails on count with a contiguous missing run. That never repeats on
/// a warm system, while a real timestamp/drop regression reproduces
/// immediately — so a retried pass is labeled loudly instead of hidden.
async fn run_video_case_with_cold_retry(case: VideoCase) -> Result<String, String> {
    match run_video_case(case.clone()).await {
        Ok(detail) => Ok(detail),
        // Only the cold-start signatures earn a retry: a contiguous
        // missing-frame run fails the count check, and a stop timeout is the
        // same stall surfacing at teardown. Correctness failures (pts error,
        // tight-pair clustering, duration drift) get no second chance — a
        // retry there would let a 50%-reproducible regression pass most runs.
        Err(first_error)
            if first_error.contains("frame count mismatch")
                || first_error.contains("Pipeline stop timed out") =>
        {
            eprintln!("case failed cold ({first_error}); retrying once on a warm pipeline");
            run_video_case(case)
                .await
                .map(|detail| {
                    format!("passed on retry after cold-start failure ({first_error}); {detail}")
                })
                .map_err(|second_error| {
                    format!("failed twice: {second_error} (first: {first_error})")
                })
        }
        Err(first_error) => Err(first_error),
    }
}

#[tokio::test(flavor = "multi_thread")]
async fn segmented_video_muxer_forwards_completed_video_segments() {
    let temp = tempfile::tempdir().expect("temporary recording directory");
    let info = VideoInfo::from_raw(cap_media_info::RawVideoFormat::Bgra, 160, 120, 30);
    let (frame_tx, frame_rx) = flume::bounded::<FFmpegVideoFrame>(8);
    let (segment_tx, segment_rx) = std::sync::mpsc::channel();
    let timestamps = Timestamps::now();
    let base = timestamps.instant();
    let mut rng = Rng(7);

    let pipeline = OutputPipeline::builder(temp.path().join("progressive-video"))
        .with_video::<ChannelVideoSource<FFmpegVideoFrame>>(ChannelVideoSourceConfig::new(
            info, frame_rx,
        ))
        .with_timestamps(timestamps)
        .build::<SegmentedVideoMuxer>(SegmentedVideoMuxerConfig {
            segment_duration: Duration::from_millis(250),
            segment_tx: Some(segment_tx),
            ..Default::default()
        })
        .await
        .expect("segmented video pipeline");

    for index in 0..90u64 {
        frame_tx
            .send_async(FFmpegVideoFrame {
                inner: make_video_frame(160, 120, index, Content::Motion, &mut rng),
                timestamp: Timestamp::Instant(base + Duration::from_millis(index * 33)),
            })
            .await
            .expect("synthetic video frame");
    }
    drop(frame_tx);

    pipeline.stop().await.expect("finalized video pipeline");

    let events = segment_rx.try_iter().collect::<Vec<_>>();
    assert!(
        events.iter().any(|event| event.is_init),
        "segmented video pipeline did not forward its initialization segment"
    );
    assert!(
        events.iter().any(|event| !event.is_init),
        "segmented video pipeline did not forward a completed media segment"
    );
    assert!(events.iter().all(|event| {
        event.media_type == cap_enc_ffmpeg::segmented_stream::SegmentMediaType::Video
            && event.file_size > 0
            && event.path.is_file()
    }));
}

#[tokio::test(flavor = "multi_thread")]
async fn synthetic_device_matrix_preserves_sync() {
    // Silent without RUST_LOG; with it, pipeline drop/stall warnings become
    // visible so a failing case can be diagnosed instead of re-guessed.
    tracing_subscriber::fmt()
        .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
        .with_test_writer()
        .try_init()
        .ok();

    let mut results: Vec<CaseResult> = Vec::new();

    warm_up_video_encoder().await;

    // Randomized cases are reproducible: rerun with CAP_SYNC_MATRIX_SEED=<seed>.
    let seed: u64 = std::env::var("CAP_SYNC_MATRIX_SEED")
        .ok()
        .and_then(|s| s.parse().ok())
        .unwrap_or_else(|| {
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_nanos() as u64)
                .unwrap_or(0x5EED)
        });
    let random_cases: usize = std::env::var("CAP_SYNC_MATRIX_RANDOM_CASES")
        .ok()
        .and_then(|s| s.parse().ok())
        .unwrap_or(6);
    eprintln!("randomized cases: {random_cases}, CAP_SYNC_MATRIX_SEED={seed}");

    // Replay mode runs only the reporter's shapes; the curated matrix is a
    // different question than "does this user's machine hold sync".
    if let Ok(report_path) = std::env::var("CAP_SYNC_MATRIX_FROM_REPORT") {
        run_report_replay(&report_path, &mut results).await;
        finish(results, seed);
        return;
    }

    let video_cases: Vec<(u32, VideoScenario, bool)> = vec![
        (15, VideoScenario::Steady, true),
        (30, VideoScenario::Steady, true),
        (60, VideoScenario::Steady, true),
        (120, VideoScenario::Steady, true),
        (30, VideoScenario::Jitter, true),
        (60, VideoScenario::Jitter, true),
        (30, VideoScenario::Drops, true),
        (60, VideoScenario::Drops, true),
        (30, VideoScenario::Gap, true),
        (60, VideoScenario::Gap, true),
        (30, VideoScenario::Steady, false),
        (30, VideoScenario::Gap, false),
    ];

    for (fps, scenario, fragmented) in video_cases {
        let name = format!(
            "video/{}fps/{}/{}",
            fps,
            scenario.name(),
            if fragmented { "fragmented" } else { "mp4" }
        );
        let outcome =
            run_video_case_with_cold_retry(VideoCase::curated(fps, scenario, fragmented)).await;
        record(&mut results, name, outcome);
    }

    record(
        &mut results,
        "video/30fps/pause-resume/mp4".to_string(),
        run_video_pause_case().await,
    );

    // Nominal-vs-delivered rate mismatches: devices free-run at whatever
    // rate they like regardless of the configured format (a camera
    // advertising 30fps delivered 60fps and recordings came out 2x too long
    // at 0.5x speed). Sync must hold for ANY delivered rate — including a
    // 1000fps camera.
    let mismatch_cases: Vec<(u32, u32, VideoScenario, bool)> = vec![
        (30, 60, VideoScenario::Steady, true), // the original report
        (30, 60, VideoScenario::Jitter, true),
        (24, 90, VideoScenario::Steady, true), // caught the ladder-escape sawtooth
        (30, 240, VideoScenario::Steady, true),
        (30, 1000, VideoScenario::Steady, false),
        (60, 24, VideoScenario::Steady, true), // slow source into a fast belief
        // Windows screen capture on a 165Hz monitor without
        // MinUpdateInterval support: WGC free-runs at the content update
        // rate. 134 is the delivered rate from the reported recording
        // (2.24x slow-motion display track); 165 is the refresh ceiling.
        (60, 134, VideoScenario::Jitter, true),
        (60, 165, VideoScenario::Steady, true),
    ];

    for (nominal, delivered, scenario, fragmented) in mismatch_cases {
        let name = format!(
            "video/nominal{}-delivered{}/{}/{}",
            nominal,
            delivered,
            scenario.name(),
            if fragmented { "fragmented" } else { "mp4" }
        );
        let outcome = run_video_case_with_cold_retry(VideoCase::mismatch(
            nominal, delivered, scenario, fragmented,
        ))
        .await;
        record(&mut results, name, outcome);
    }

    let audio_cases: Vec<(u32, u16)> = vec![
        (8_000, 2),
        (16_000, 2),
        (22_050, 2),
        (44_100, 2),
        (48_000, 2),
        (96_000, 2),
        (48_000, 1),
        (44_100, 1),
        (48_000, 6),
    ];

    for (rate, channels) in audio_cases {
        let name = format!("audio/{rate}hz/{channels}ch");
        let outcome = run_audio_case(AudioCase::curated(rate, channels)).await;
        record(&mut results, name, outcome);
    }

    // System-audio delivery shapes: WASAPI-loopback-style intermittent
    // sources that only produce packets while sound plays. These guard the
    // epoch anchoring + silence materialization that keep an intermittent
    // track from desyncing (or re-anchoring) the whole recording.
    let system_audio_cases: Vec<(&str, SystemAudioCase)> = vec![
        (
            "system-audio/late-first-sound",
            SystemAudioCase {
                bursts: vec![(1.4, 2.6)],
                total_secs: 4.0,
            },
        ),
        (
            "system-audio/dead-zone",
            SystemAudioCase {
                bursts: vec![(0.2, 1.2), (3.0, 3.8)],
                total_secs: 4.5,
            },
        ),
        (
            "system-audio/silent-throughout",
            SystemAudioCase {
                bursts: vec![],
                total_secs: 3.0,
            },
        ),
        (
            "system-audio/bursty-notifications",
            SystemAudioCase {
                bursts: vec![(0.4, 0.8), (1.6, 2.0), (2.8, 3.2)],
                total_secs: 4.0,
            },
        ),
    ];

    for (name, case) in system_audio_cases {
        let outcome = run_system_audio_case(case).await;
        record(&mut results, name.to_string(), outcome);
    }

    record(
        &mut results,
        "system-audio/with-mic".to_string(),
        run_mic_with_system_audio_case().await,
    );

    // Non-predetermined coverage: random device shapes and delivery
    // pathologies, combined audio+video like a real studio recording.
    let mut rng = Rng(seed);
    for i in 0..random_cases {
        let video = random_video_case(&mut rng);
        let audio = random_audio_case(&mut rng);
        let name = format!(
            "random/{i}/video-nominal{}-delivered{}-{}x{}-{:?}-{}ts/audio-{}hz-{}ch-{:.0}ms-drift{:+.2}%",
            video.fps,
            video.delivered_fps,
            video.width,
            video.height,
            video.content,
            video.sent.len(),
            audio.rate,
            audio.channels,
            audio.chunk_ms,
            (audio.drift - 1.0) * 100.0,
        );
        // Run both legs concurrently, as a real recording does.
        let (video_outcome, audio_outcome) =
            tokio::join!(run_video_case_with_cold_retry(video), run_audio_case(audio));
        let outcome = match (video_outcome, audio_outcome) {
            (Ok(v), Ok(a)) => Ok(format!("video: {v}; audio: {a}")),
            (Err(e), _) => Err(format!("video leg: {e}")),
            (_, Err(e)) => Err(format!("audio leg: {e}")),
        };
        record(&mut results, name, outcome);
    }

    finish(results, seed);
}

/// Writes the optional JSON report and applies the pass/degradation gates.
fn finish(results: Vec<CaseResult>, seed: u64) {
    if let Ok(report_path) = std::env::var("CAP_SYNC_MATRIX_REPORT") {
        #[derive(Serialize)]
        struct Report<'a> {
            seed: u64,
            cases: &'a [CaseResult],
        }
        let json = serde_json::to_string_pretty(&Report {
            seed,
            cases: &results,
        })
        .expect("serialize report");
        std::fs::write(&report_path, json).expect("write report");
        eprintln!("report written to {report_path}");
    }

    let failures: Vec<&CaseResult> = results.iter().filter(|r| !r.pass).collect();
    assert!(
        failures.is_empty(),
        "{} of {} matrix cases failed:\n{}",
        failures.len(),
        results.len(),
        failures
            .iter()
            .map(|r| format!("  {} — {}", r.name, r.detail))
            .collect::<Vec<_>>()
            .join("\n")
    );

    // Environment skips are a pressure valve, not a pass: if half the matrix
    // skipped, the run proves nothing and must be loud about it. Retried
    // passes spent one of their two shots on a cold failure, so they count
    // toward the same degradation budget — a runner that needs the retry
    // everywhere proves as little as one that skips everywhere.
    let degraded = results
        .iter()
        .filter(|r| r.detail.contains("skipped:") || r.detail.contains("passed on retry"))
        .count();
    assert!(
        degraded * 2 <= results.len(),
        "{degraded} of {} matrix cases skipped or passed only on retry — runner too \
         degraded for this run to verify anything",
        results.len()
    );
}