Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

51.7 KB
Raw Blame
//! Load-time repair for recordings whose video tracks were stamped at the
//! wrong rate.
//!
//! A source that delivered frames faster than the pipeline's nominal rate
//! produced a track whose duration is a multiple of the real recording span —
//! the video plays in slow motion, desyncs from audio, and stretches the
//! editor timeline. Two variants shipped:
//!
//! - cameras free-running past their nominal rate (e.g. an AVFoundation
//!   device at 60fps recorded as 30fps) → stretched camera.mp4;
//! - Windows screen capture on high-refresh monitors (WGC delivering at up
//!   to the monitor rate with no MinUpdateInterval support) → stretched
//!   display.mp4, with a content-dependent non-integer ratio
//!   (delivered fps / nominal fps, e.g. ~2.24x for a 165Hz monitor).
//!
//! The recorder-side defects are fixed, but affected recordings on disk stay
//! broken; this module detects the signatures on editor open and losslessly
//! rewrites the tracks' timestamps.

use std::collections::HashMap;
use std::path::{Path, PathBuf};

use cap_enc_ffmpeg::remux::{
    get_media_duration, get_video_capture_fps, get_video_fps, probe_video_pts_ladder,
    rescale_video_timestamps,
};
use cap_project::{ProjectConfiguration, RecordingMeta, RecordingMetaInner, StudioRecordingMeta};
use tracing::{info, warn};

/// Runs every track repair for a studio recording, display first so the
/// camera heal can trust the display track as a reference. Returns `true`
/// if anything was healed.
pub fn heal_stretched_tracks(project_path: &Path) -> anyhow::Result<bool> {
    // Concurrent editor opens of the same project would race the
    // backup/install renames and could bury the original under an
    // already-healed file; only one heal per project may be in flight.
    // The app is single-instance and only the editor-open path heals, so
    // an in-process guard suffices.
    let Some(_guard) = HealInFlightGuard::try_claim(project_path) else {
        return Ok(false);
    };

    let fps_healed = heal_average_display_fps(project_path)?;
    let display_healed = heal_stretched_display(project_path)?;
    let camera_healed = heal_stretched_camera(project_path)?;
    Ok(fps_healed || display_healed || camera_healed)
}

/// Finalizing a fragmented Studio recording stored the display track's
/// average frame rate as its fps. Decoders place frames on that rate, so a
/// mostly static screen, averaging well under its capture rate, played and
/// exported with frames missing. A track whose fps is still its average
/// rate gets the rate its frames were captured at; the media is untouched,
/// and a healed fps no longer matches the average, so this runs once.
pub fn heal_average_display_fps(project_path: &Path) -> anyhow::Result<bool> {
    let mut meta = RecordingMeta::load_for_project(project_path)
        .map_err(|e| anyhow::anyhow!("failed to load recording meta: {e}"))?;
    let RecordingMetaInner::Studio(studio_meta) = &mut meta.inner else {
        return Ok(false);
    };
    let StudioRecordingMeta::MultipleSegments { inner } = studio_meta.as_mut() else {
        return Ok(false);
    };

    let mut healed_any = false;
    for (segment_index, segment) in inner.segments.iter_mut().enumerate() {
        let display_path = segment.display.path.to_path(project_path);
        let stored = segment.display.fps;
        if get_video_fps(&display_path) != Some(stored) {
            continue;
        }
        let Some(capture) = get_video_capture_fps(&display_path) else {
            continue;
        };
        if capture <= stored {
            continue;
        }
        info!(
            segment_index,
            stored, capture, "Display fps was the track's average rate, restoring its capture rate"
        );
        segment.display.fps = capture;
        healed_any = true;
    }

    if healed_any {
        meta.save_for_project()
            .map_err(|e| anyhow::anyhow!("failed to save healed recording meta: {e:?}"))?;
    }
    Ok(healed_any)
}

struct HealInFlightGuard(PathBuf);

impl HealInFlightGuard {
    fn in_flight() -> &'static std::sync::Mutex<std::collections::HashSet<PathBuf>> {
        static IN_FLIGHT: std::sync::OnceLock<
            std::sync::Mutex<std::collections::HashSet<PathBuf>>,
        > = std::sync::OnceLock::new();
        IN_FLIGHT.get_or_init(Default::default)
    }

    fn try_claim(project_path: &Path) -> Option<Self> {
        let path = project_path.to_path_buf();
        let mut set = Self::in_flight().lock().ok()?;
        set.insert(path.clone()).then(|| Self(path))
    }
}

impl Drop for HealInFlightGuard {
    fn drop(&mut self) {
        if let Ok(mut set) = Self::in_flight().lock() {
            set.remove(&self.0);
        }
    }
}

/// Minimum reference span for a heal to be considered; very short recordings
/// have too much probe noise to trust a ratio.
const MIN_REFERENCE_SECS: f64 = 2.0;
/// Camera must exceed the reference span by at least this factor…
const MIN_STRETCH_RATIO: f64 = 1.5;
/// …and by at least this many seconds, so long recordings with slightly
/// off-by-probe durations never trigger.
const MIN_STRETCH_SECS: f64 = 1.0;
/// When only the display track is available as a reference (no audio), the
/// ratio must sit in the rate-doubling family (60/30, 50/25, 60/24) to rule
/// out a display track that legitimately stopped early.
const DISPLAY_ONLY_RATIO_RANGE: (f64, f64) = (1.6, 2.6);
/// References must agree with each other within this fraction of the larger
/// one before the camera is judged against them.
const REFERENCE_AGREEMENT_RATIO: f64 = 0.15;
/// The healed file must land within this fraction of the expected span or the
/// original is kept untouched.
const HEAL_VERIFY_TOLERANCE_RATIO: f64 = 0.05;

const BACKUP_FILE_NAME: &str = "camera.original.mp4";

/// Detects and repairs stretched camera tracks in a studio recording.
/// Returns `true` if any segment was healed. Never modifies media unless the
/// stretch signature is unambiguous, and keeps the original file alongside
/// the healed one.
pub fn heal_stretched_camera(project_path: &Path) -> anyhow::Result<bool> {
    let mut meta = RecordingMeta::load_for_project(project_path)
        .map_err(|e| anyhow::anyhow!("failed to load recording meta: {e}"))?;

    let RecordingMetaInner::Studio(studio_meta) = &mut meta.inner else {
        return Ok(false);
    };

    let StudioRecordingMeta::MultipleSegments { inner } = studio_meta.as_mut() else {
        return Ok(false);
    };

    let project_path = project_path.to_path_buf();
    let mut healed_any = false;

    for (segment_index, segment) in inner.segments.iter_mut().enumerate() {
        let Some(camera) = segment.camera.as_mut() else {
            continue;
        };

        let camera_path = camera.path.to_path(&project_path);
        let display_path = segment.display.path.to_path(&project_path);

        let backup_path = backup_path_for(&camera_path);
        if backup_path.exists() {
            // Healed before — never rescale the same track twice.
            continue;
        }

        let Some(camera_duration) = get_media_duration(&camera_path) else {
            continue;
        };

        // Each reference predicts the camera's span from its own duration
        // plus the difference in track start times (a track that started
        // later ran for less wall time).
        let camera_start = camera.start_time.unwrap_or(0.0);
        let mut references: Vec<(&'static str, f64)> = Vec::new();

        if let Some(display_duration) = get_media_duration(&display_path) {
            let display_start = segment.display.start_time.unwrap_or(0.0);
            references.push((
                "display",
                display_duration.as_secs_f64() + (display_start - camera_start),
            ));
        }

        for (name, audio) in [
            ("mic", segment.mic.as_ref()),
            ("system-audio", segment.system_audio.as_ref()),
        ] {
            let Some(audio) = audio else { continue };
            let audio_path = audio.path.to_path(&project_path);
            if let Some(audio_duration) = get_media_duration(&audio_path) {
                let audio_start = audio.start_time.unwrap_or(0.0);
                references.push((
                    name,
                    audio_duration.as_secs_f64() + (audio_start - camera_start),
                ));
            }
        }

        let Some(decision) = evaluate_stretch(camera_duration.as_secs_f64(), &references) else {
            continue;
        };

        info!(
            segment_index,
            camera_secs = camera_duration.as_secs_f64(),
            expected_secs = decision.expected_span_secs,
            ratio = decision.ratio,
            references = ?references,
            "Detected stretched camera track, rewriting timestamps"
        );

        let healed_path = camera_path.with_extension("healed.mp4");
        let _ = std::fs::remove_file(&healed_path);

        if let Err(e) = rescale_video_timestamps(&camera_path, &healed_path, decision.scale) {
            warn!(
                segment_index,
                "Camera heal remux failed, keeping original: {e}"
            );
            let _ = std::fs::remove_file(&healed_path);
            continue;
        }

        let healed_ok = get_media_duration(&healed_path).is_some_and(|healed| {
            let error = (healed.as_secs_f64() - decision.expected_span_secs).abs();
            error <= decision.expected_span_secs * HEAL_VERIFY_TOLERANCE_RATIO
        });

        if !healed_ok {
            warn!(
                segment_index,
                "Healed camera track failed duration verification, keeping original"
            );
            let _ = std::fs::remove_file(&healed_path);
            continue;
        }

        if let Err(e) = std::fs::rename(&camera_path, &backup_path) {
            warn!(
                segment_index,
                "Failed to back up original camera track: {e}"
            );
            let _ = std::fs::remove_file(&healed_path);
            continue;
        }

        if let Err(e) = std::fs::rename(&healed_path, &camera_path) {
            warn!(segment_index, "Failed to install healed camera track: {e}");
            // Put the original back so the recording stays playable.
            let _ = std::fs::rename(&backup_path, &camera_path);
            let _ = std::fs::remove_file(&healed_path);
            continue;
        }

        if let Some(fps) = get_video_fps(&camera_path).filter(|fps| *fps > 0) {
            camera.fps = fps;
        }

        info!(
            segment_index,
            healed_secs = get_media_duration(&camera_path).map(|d| d.as_secs_f64()),
            fps = camera.fps,
            "Camera track healed (original kept as {BACKUP_FILE_NAME})"
        );
        healed_any = true;
    }

    if healed_any {
        meta.save_for_project()
            .map_err(|e| anyhow::anyhow!("failed to save healed recording meta: {e:?}"))?;
    }

    Ok(healed_any)
}

fn backup_path_for(camera_path: &Path) -> PathBuf {
    camera_path.with_file_name(BACKUP_FILE_NAME)
}

const DISPLAY_BACKUP_FILE_NAME: &str = "display.original.mp4";
/// The display ratio is content-dependent (delivered fps / nominal), so no
/// ratio-family gate applies; instead the floor is low enough to catch a
/// 75Hz monitor (1.25x) while staying above audio-tail noise.
const DISPLAY_MIN_STRETCH_RATIO: f64 = 1.15;
/// Absolute stretch floor, so long recordings with slightly off-by-probe
/// durations never trigger.
const DISPLAY_MIN_STRETCH_SECS: f64 = 2.0;
/// No real refresh/nominal mismatch exceeds this; anything above means a
/// different defect we should not touch.
const DISPLAY_MAX_STRETCH_RATIO: f64 = 6.0;
/// Video cannot run longer than the wall clock; requiring it to exceed the
/// log-derived wall span (which over-counts by a few seconds of pre/post
/// roll) by this factor is the physical proof of a stretch. It also rejects
/// the nastiest false positive: a healthy recording whose audio track died
/// early, which an audio-only ratio would mis-read as a stretched video.
const WALL_GATE_RATIO: f64 = 1.1;
/// An audio reference predicting a content span below this fraction of the
/// wall span is treated as a track that died early, not as a sync target.
const AUDIO_REF_PLAUSIBLE_WALL_FRACTION: f64 = 0.4;

/// Detects and repairs stretched display tracks in a studio recording.
/// Returns `true` if any segment was healed. The display is the timeline's
/// backbone, so this is deliberately more conservative than the camera heal:
/// it requires the synthetic CFR-ladder signature that the defective
/// pipeline always produced, plus either wall-clock proof from the recording
/// log or two independently-agreeing audio references.
pub fn heal_stretched_display(project_path: &Path) -> anyhow::Result<bool> {
    let meta = RecordingMeta::load_for_project(project_path)
        .map_err(|e| anyhow::anyhow!("failed to load recording meta: {e}"))?;

    let RecordingMetaInner::Studio(studio_meta) = &meta.inner else {
        return Ok(false);
    };

    let StudioRecordingMeta::MultipleSegments { inner } = studio_meta.as_ref() else {
        return Ok(false);
    };

    let wall_span_secs = recording_log_wall_span_secs(project_path);
    let project_path = project_path.to_path_buf();
    let mut healed_scales: HashMap<u32, f64> = HashMap::new();

    for (segment_index, segment) in inner.segments.iter().enumerate() {
        let display_path = segment.display.path.to_path(&project_path);

        let backup_path = display_path.with_file_name(DISPLAY_BACKUP_FILE_NAME);
        if backup_path.exists() {
            // Healed before — never rescale the same track twice.
            continue;
        }

        let Some(display_duration) = get_media_duration(&display_path) else {
            continue;
        };
        let display_secs = display_duration.as_secs_f64();
        let display_start = segment.display.start_time.unwrap_or(0.0);

        let mut audio_refs: Vec<(&'static str, f64)> = Vec::new();
        let mut audio_track_count = 0usize;
        for (name, audio) in [
            ("mic", segment.mic.as_ref()),
            ("system-audio", segment.system_audio.as_ref()),
        ] {
            let Some(audio) = audio else { continue };
            audio_track_count += 1;
            let audio_path = audio.path.to_path(&project_path);
            if let Some(audio_duration) = get_media_duration(&audio_path) {
                let audio_start = audio.start_time.unwrap_or(0.0);
                audio_refs.push((
                    name,
                    audio_duration.as_secs_f64() + (audio_start - display_start),
                ));
            }
        }

        // The ladder probe reads packets, so run the cheap gates through
        // `evaluate_display_stretch` first with a claimed ladder, then
        // confirm against the file before touching anything.
        let inputs = DisplayStretchInputs {
            display_secs,
            display_start,
            audio_refs: audio_refs.clone(),
            audio_track_count,
            wall_span_secs,
            ladder_is_synthetic: true,
        };
        let Some(decision) = evaluate_display_stretch(&inputs) else {
            continue;
        };

        let ladder_confirmed = probe_video_pts_ladder(&display_path, segment.display.fps)
            .is_some_and(|probe| probe.is_ladder());
        if !ladder_confirmed {
            info!(
                segment_index,
                display_secs,
                "Display track is long relative to references but not ladder-stamped; leaving it alone"
            );
            continue;
        }

        info!(
            segment_index,
            display_secs,
            expected_secs = decision.expected_span_secs,
            ratio = decision.ratio,
            wall_span_secs,
            references = ?audio_refs,
            "Detected stretched display track, rewriting timestamps"
        );

        let healed_path = display_path.with_extension("healed.mp4");
        let _ = std::fs::remove_file(&healed_path);

        if let Err(e) = rescale_video_timestamps(&display_path, &healed_path, decision.scale) {
            warn!(
                segment_index,
                "Display heal remux failed, keeping original: {e}"
            );
            let _ = std::fs::remove_file(&healed_path);
            continue;
        }

        let healed_ok = get_media_duration(&healed_path).is_some_and(|healed| {
            let error = (healed.as_secs_f64() - decision.expected_span_secs).abs();
            error <= decision.expected_span_secs * HEAL_VERIFY_TOLERANCE_RATIO
        });

        if !healed_ok {
            warn!(
                segment_index,
                "Healed display track failed duration verification, keeping original"
            );
            let _ = std::fs::remove_file(&healed_path);
            continue;
        }

        if let Err(e) = std::fs::rename(&display_path, &backup_path) {
            warn!(
                segment_index,
                "Failed to back up original display track: {e}"
            );
            let _ = std::fs::remove_file(&healed_path);
            continue;
        }

        if let Err(e) = std::fs::rename(&healed_path, &display_path) {
            warn!(segment_index, "Failed to install healed display track: {e}");
            // Put the original back so the recording stays playable.
            let _ = std::fs::rename(&backup_path, &display_path);
            let _ = std::fs::remove_file(&healed_path);
            continue;
        }

        info!(
            segment_index,
            healed_secs = get_media_duration(&display_path).map(|d| d.as_secs_f64()),
            "Display track healed (original kept as {DISPLAY_BACKUP_FILE_NAME})"
        );
        healed_scales.insert(segment_index as u32, decision.scale);
    }

    if !healed_scales.is_empty() {
        rescale_project_config(&project_path, &healed_scales);
    }

    Ok(!healed_scales.is_empty())
}

/// Wall-clock span of the recording session, from the first and last
/// timestamped lines of `recording-logs.log`. Over-counts the capture span
/// by a few seconds (setup before the pipeline plays, finalization after
/// stop), which is the safe direction for a "video exceeds wall time" gate.
///
/// Log timestamps are system wall-clock, not monotonic: if the clock
/// stepped backward mid-recording (NTP correction), the net span
/// under-counts and could authorize — and mis-target — a heal of a healthy
/// no-audio recording. A backward step is visible as a backwards jump
/// between adjacent log lines, so any such jump discredits the whole log.
/// Small inversions are normal (threads capture timestamps before the
/// appender serializes them) and are tolerated.
fn recording_log_wall_span_secs(project_path: &Path) -> Option<f64> {
    // Logs are tens of KB; cap the read defensively rather than streaming.
    const MAX_LOG_READ_BYTES: u64 = 8 * 1024 * 1024;
    /// Well above async-logging interleave, well below any real clock step.
    const MAX_BACKWARD_INTERLEAVE_MS: i64 = 2_000;

    let log_path = project_path.join("recording-logs.log");
    let len = std::fs::metadata(&log_path).ok()?.len();
    if len == 0 || len > MAX_LOG_READ_BYTES {
        return None;
    }
    let contents = std::fs::read_to_string(&log_path).ok()?;

    let mut first: Option<chrono::DateTime<chrono::FixedOffset>> = None;
    let mut prev: Option<chrono::DateTime<chrono::FixedOffset>> = None;
    for line in contents.lines() {
        let Some(ts_str) = line.split_whitespace().next() else {
            continue;
        };
        let Ok(ts) = chrono::DateTime::parse_from_rfc3339(ts_str) else {
            continue;
        };
        if let Some(prev) = prev
            && prev.signed_duration_since(ts).num_milliseconds() > MAX_BACKWARD_INTERLEAVE_MS
        {
            return None;
        }
        if first.is_none() {
            first = Some(ts);
        }
        prev = Some(ts);
    }

    let span = prev?.signed_duration_since(first?);
    let secs = span.num_milliseconds() as f64 / 1000.0;
    (secs > 0.0).then_some(secs)
}

#[derive(Debug, Clone)]
struct DisplayStretchInputs {
    display_secs: f64,
    display_start: f64,
    /// Expected display spans predicted by each audio track.
    audio_refs: Vec<(&'static str, f64)>,
    /// How many audio tracks the recording has, probed successfully or not.
    audio_track_count: usize,
    wall_span_secs: Option<f64>,
    /// Whether the track's packet timestamps form the synthetic
    /// one-nominal-tick-per-frame ladder the defective pipeline produced.
    ladder_is_synthetic: bool,
}

/// Decides whether a display track is stretched. Returns `None` unless the
/// signature is unambiguous.
fn evaluate_display_stretch(inputs: &DisplayStretchInputs) -> Option<StretchDecision> {
    if !inputs.ladder_is_synthetic {
        return None;
    }

    // Physical gate: a video track cannot outrun the wall clock. When the
    // log span is available it must prove the stretch, whatever the audio
    // says.
    if let Some(wall) = inputs.wall_span_secs
        && inputs.display_secs < wall * WALL_GATE_RATIO
    {
        return None;
    }

    // Audio references that died early (pre-keepalive system audio) predict
    // a span far below the wall clock; they are not sync targets.
    let plausible_refs: Vec<(&'static str, f64)> = inputs
        .audio_refs
        .iter()
        .filter(|(_, span)| match inputs.wall_span_secs {
            Some(wall) => *span >= wall * AUDIO_REF_PLAUSIBLE_WALL_FRACTION,
            None => true,
        })
        .copied()
        .collect();

    let expected_span_secs = if !plausible_refs.is_empty() {
        let spans: Vec<f64> = plausible_refs.iter().map(|(_, span)| *span).collect();
        let max_span = spans.iter().cloned().fold(f64::MIN, f64::max);
        let min_span = spans.iter().cloned().fold(f64::MAX, f64::min);

        // All remaining references must tell the same story.
        if max_span - min_span > (max_span * REFERENCE_AGREEMENT_RATIO).max(MIN_STRETCH_SECS) {
            return None;
        }

        // Without wall-clock proof, one audio track alone cannot rule out
        // "the audio died early"; require two independent tracks agreeing.
        if inputs.wall_span_secs.is_none() && plausible_refs.len() < 2 {
            return None;
        }

        max_span
    } else if inputs.audio_track_count > 0 {
        // The recording had audio but no track produced a plausible
        // reference — too ambiguous to touch.
        return None;
    } else {
        // No audio at all: the wall span is the only reference. Without a
        // log there is nothing to measure against.
        inputs.wall_span_secs? - inputs.display_start
    };

    if expected_span_secs < MIN_REFERENCE_SECS {
        return None;
    }

    let ratio = inputs.display_secs / expected_span_secs;
    if !(DISPLAY_MIN_STRETCH_RATIO..=DISPLAY_MAX_STRETCH_RATIO).contains(&ratio)
        || inputs.display_secs - expected_span_secs < DISPLAY_MIN_STRETCH_SECS
    {
        return None;
    }

    Some(StretchDecision {
        expected_span_secs,
        ratio,
        scale: expected_span_secs / inputs.display_secs,
    })
}

/// Rewrites an existing project config so edits made against a stretched
/// recording keep pointing at the same content after the heal. For the pure
/// ladder stretch the source-time mapping is exactly linear, so scaling
/// segment bounds is exact, not approximate. Overlay tracks live on the
/// output timeline, which only scales by the same factor when every timeline
/// segment does; keyboard and caption segments are regenerable from their
/// source-of-truth files, so they are left untouched.
fn rescale_project_config(project_path: &Path, scales: &HashMap<u32, f64>) {
    let Ok(mut config) = ProjectConfiguration::load(project_path) else {
        // No config yet: the editor will build a default timeline from the
        // healed media.
        return;
    };
    let Some(timeline) = config.timeline.as_mut() else {
        return;
    };

    let mut changed = false;
    let mut all_clips_healed = true;

    for segment in &mut timeline.segments {
        if let Some(scale) = scales.get(&segment.recording_clip) {
            // `timescale` (the user-facing Speed control) is deliberately
            // untouched: scaling start/end alone keeps content selection and
            // overlay alignment exact and makes a "2x" label mean 2x of real
            // time again. A speed edit made against the stretched media was
            // compensating for the defect; preserving its on-screen rate
            // would carry the defect forward.
            segment.start *= scale;
            segment.end *= scale;
            changed = true;
        } else {
            all_clips_healed = false;
        }
    }

    let uniform_scale = if scales.len() == 1 && all_clips_healed {
        scales.values().next().copied()
    } else {
        None
    };

    if let Some(scale) = uniform_scale {
        for s in &mut timeline.zoom_segments {
            s.start *= scale;
            s.end *= scale;
        }
        for s in &mut timeline.scene_segments {
            s.start *= scale;
            s.end *= scale;
        }
        for s in &mut timeline.mask_segments {
            s.start *= scale;
            s.end *= scale;
        }
        for s in &mut timeline.text_segments {
            s.start *= scale;
            s.end *= scale;
        }
        for s in &mut timeline.audio_segments {
            s.start *= scale;
            s.end *= scale;
        }
        for s in &mut timeline.camera3d_segments {
            s.start *= scale;
            s.end *= scale;
            s.transition_in *= scale;
            s.transition_out *= scale;
            for track in s.tracks.all_tracks_mut() {
                for k in track.iter_mut() {
                    k.time *= scale;
                }
            }
        }
        changed = true;
    }

    if changed && let Err(e) = config.write(project_path) {
        warn!("Failed to write rescaled project config after display heal: {e}");
    }
}

#[derive(Debug, PartialEq)]
struct StretchDecision {
    expected_span_secs: f64,
    ratio: f64,
    scale: f64,
}

/// Decides whether `camera_secs` is a stretched track given the expected
/// spans predicted by the other tracks. Returns `None` unless the signature
/// is unambiguous.
fn evaluate_stretch(camera_secs: f64, references: &[(&str, f64)]) -> Option<StretchDecision> {
    let spans: Vec<f64> = references.iter().map(|(_, span)| *span).collect();
    if spans.is_empty() {
        return None;
    }

    let max_span = spans.iter().cloned().fold(f64::MIN, f64::max);
    let min_span = spans.iter().cloned().fold(f64::MAX, f64::min);

    if max_span < MIN_REFERENCE_SECS {
        return None;
    }

    // All references must tell the same story; a mic that ran much longer
    // than the display means the display died early, not that the camera is
    // stretched.
    if max_span - min_span > (max_span * REFERENCE_AGREEMENT_RATIO).max(MIN_STRETCH_SECS) {
        return None;
    }

    let expected_span_secs = max_span;
    let ratio = camera_secs / expected_span_secs;

    if ratio < MIN_STRETCH_RATIO || camera_secs - expected_span_secs < MIN_STRETCH_SECS {
        return None;
    }

    let has_audio_reference = references.iter().any(|(name, _)| *name != "display");
    if !has_audio_reference
        && !(DISPLAY_ONLY_RATIO_RANGE.0..=DISPLAY_ONLY_RATIO_RANGE.1).contains(&ratio)
    {
        return None;
    }

    Some(StretchDecision {
        expected_span_secs,
        ratio,
        scale: expected_span_secs / camera_secs,
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    use cap_project::{Cursors, MultipleSegment, MultipleSegments, VideoMeta};
    use std::time::Duration;

    /// A Studio project whose display track holds `timestamps`, with `fps`
    /// stored for it.
    fn display_project(
        timestamps: &[Duration],
        fps: impl FnOnce(&Path) -> u32,
    ) -> tempfile::TempDir {
        use cap_enc_ffmpeg::{h264::H264Encoder, mp4::MP4File};

        ffmpeg::init().unwrap();
        let directory = tempfile::tempdir().unwrap();
        let project = directory.path();
        let display = project.join("content/segments/segment-0/display.mp4");
        std::fs::create_dir_all(display.parent().unwrap()).unwrap();
        let info = cap_media_info::VideoInfo {
            pixel_format: cap_media_info::Pixel::NV12,
            width: 320,
            height: 240,
            time_base: ffmpeg::Rational(1, 1_000_000),
            frame_rate: ffmpeg::Rational(60, 1),
        };
        let mut file = MP4File::init(
            "display",
            display.clone(),
            false,
            |o| H264Encoder::builder(info).build(o),
            |_| None,
        )
        .unwrap();
        for (index, timestamp) in timestamps.iter().enumerate() {
            let mut frame = ffmpeg::frame::Video::new(ffmpeg::format::Pixel::NV12, 320, 240);
            frame.data_mut(0).fill(32 + index as u8);
            frame.data_mut(1).fill(128);
            file.queue_video_frame(frame, *timestamp).unwrap();
        }
        file.finish().unwrap();
        RecordingMeta {
            platform: None,
            project_path: project.to_path_buf(),
            pretty_name: "fps heal fixture".into(),
            sharing: None,
            upload: None,
            inner: RecordingMetaInner::Studio(Box::new(StudioRecordingMeta::MultipleSegments {
                inner: MultipleSegments {
                    segments: vec![MultipleSegment {
                        display: VideoMeta {
                            path: "content/segments/segment-0/display.mp4".into(),
                            fps: fps(&display),
                            start_time: None,
                            device_id: None,
                        },
                        camera: None,
                        mic: None,
                        system_audio: None,
                        cursor: None,
                        keyboard: None,
                        display_notch: None,
                    }],
                    cursors: Cursors::default(),
                    status: None,
                },
            })),
        }
        .save_for_project()
        .unwrap();
        directory
    }

    fn stored_display_fps(project: &Path) -> u32 {
        let meta = RecordingMeta::load_for_project(project).unwrap();
        let RecordingMetaInner::Studio(studio) = meta.inner else {
            panic!("not a studio recording");
        };
        studio.max_fps()
    }

    /// 60 fps frames in bursts of six between half-second holds.
    fn static_screen_capture() -> Vec<Duration> {
        (0..20u64)
            .flat_map(|burst| (0..6).map(move |i| burst * 36 + i))
            .map(|slot| Duration::from_nanos(slot * 1_000_000_000 / 60))
            .collect()
    }

    #[test]
    fn an_average_display_fps_is_healed_to_the_capture_rate() {
        let project = display_project(&static_screen_capture(), |display| {
            get_video_fps(display).unwrap()
        });
        let average = stored_display_fps(project.path());
        assert!(average < 12, "fixture averages {average} fps");

        assert!(heal_average_display_fps(project.path()).unwrap());
        assert_eq!(stored_display_fps(project.path()), 60);
        assert!(!heal_average_display_fps(project.path()).unwrap());
        assert_eq!(stored_display_fps(project.path()), 60);
    }

    #[test]
    fn a_recorded_display_fps_is_left_alone() {
        let project = display_project(&static_screen_capture(), |_| 60);
        assert!(!heal_average_display_fps(project.path()).unwrap());
        assert_eq!(stored_display_fps(project.path()), 60);
    }

    #[test]
    fn a_steady_capture_at_its_average_is_left_alone() {
        let timestamps: Vec<Duration> = (0..90u64)
            .map(|i| Duration::from_nanos(i * 1_000_000_000 / 30))
            .collect();
        let project = display_project(&timestamps, |display| get_video_fps(display).unwrap());
        assert_eq!(stored_display_fps(project.path()), 30);
        assert!(!heal_average_display_fps(project.path()).unwrap());
        assert_eq!(stored_display_fps(project.path()), 30);
    }

    const USER_REPORT_CAMERA_SECS: f64 = 13.666;

    fn user_report_references() -> Vec<(&'static str, f64)> {
        // From the original report: display 6.75s starting at 0.302s, mic
        // 6.91s starting at 0.102s, camera starting at 0.149s.
        vec![
            ("display", 6.75 + (0.302 - 0.149)),
            ("mic", 6.91 + (0.102 - 0.149)),
        ]
    }

    #[test]
    fn detects_the_reported_double_length_camera() {
        let decision = evaluate_stretch(USER_REPORT_CAMERA_SECS, &user_report_references())
            .expect("the reported recording must be detected");
        assert!(
            (decision.ratio - 2.0).abs() < 0.05,
            "ratio {}",
            decision.ratio
        );
        assert!(
            (decision.scale - 0.5).abs() < 0.02,
            "scale {}",
            decision.scale
        );
    }

    #[test]
    fn healthy_recording_is_left_alone() {
        assert_eq!(
            evaluate_stretch(6.9, &[("display", 6.75), ("mic", 6.91)]),
            None
        );
    }

    #[test]
    fn camera_slightly_longer_than_references_is_left_alone() {
        // Cameras legitimately run a little past the other tracks.
        assert_eq!(
            evaluate_stretch(7.4, &[("display", 6.75), ("mic", 6.91)]),
            None
        );
    }

    #[test]
    fn display_dying_early_does_not_trigger_heal() {
        // Display stopped at half-time but the mic kept going: references
        // disagree, so the long camera is trusted.
        assert_eq!(
            evaluate_stretch(60.0, &[("display", 30.0), ("mic", 59.5)]),
            None
        );
    }

    #[test]
    fn display_only_requires_doubling_ratio() {
        // Without audio, a 2x camera is healed…
        assert!(evaluate_stretch(13.6, &[("display", 6.8)]).is_some());
        // …but a 3x mismatch (not a rate-doubling signature) is not.
        assert_eq!(evaluate_stretch(20.4, &[("display", 6.8)]), None);
        // …nor is a display that died at two-thirds.
        assert_eq!(evaluate_stretch(90.0, &[("display", 60.0)]), None);
    }

    #[test]
    fn short_recordings_are_not_healed() {
        assert_eq!(
            evaluate_stretch(3.0, &[("display", 1.5), ("mic", 1.5)]),
            None
        );
    }

    #[test]
    fn below_ratio_threshold_is_left_alone() {
        assert_eq!(
            evaluate_stretch(3.1, &[("display", 2.1), ("mic", 2.1)]),
            None
        );
    }

    /// Manual harness for healing a real .cap bundle:
    /// `CAP_HEAL_PROJECT_PATH=/path/to/recording.cap cargo test -p cap-recording \
    ///   --lib track_heal::tests::heal_project_from_env -- --ignored --nocapture`
    #[test]
    #[ignore]
    fn heal_project_from_env() {
        let path =
            std::env::var("CAP_HEAL_PROJECT_PATH").expect("CAP_HEAL_PROJECT_PATH must be set");
        let healed = heal_stretched_tracks(Path::new(&path)).unwrap();
        println!("healed: {healed}");
    }

    // -- Display heal --
    //
    // Numbers below are from the 2026-07-06 user report: a 90.3s window
    // recording on a 165Hz monitor produced a 202.22s display.mp4 (12,133
    // frames stamped at exactly 1/60s) against 90.82s of real-time system
    // audio and a 92.8s log wall span.

    fn report_inputs() -> DisplayStretchInputs {
        DisplayStretchInputs {
            display_secs: 202.22,
            display_start: 0.4728,
            audio_refs: vec![("system-audio", 90.8225 - 0.4728)],
            audio_track_count: 1,
            wall_span_secs: Some(92.8),
            ladder_is_synthetic: true,
        }
    }

    #[test]
    fn detects_the_reported_high_refresh_display_stretch() {
        let decision = evaluate_display_stretch(&report_inputs())
            .expect("the reported recording must be detected");
        assert!(
            (decision.ratio - 2.24).abs() < 0.02,
            "ratio {}",
            decision.ratio
        );
        // The scale targets the audio span, which is what playback syncs to.
        assert!(
            (decision.scale - 0.4468).abs() < 0.002,
            "scale {}",
            decision.scale
        );
    }

    #[test]
    fn non_ladder_track_is_never_healed() {
        // Long relative to audio but with real, jittered timestamps: the
        // audio died early, the video is fine.
        let inputs = DisplayStretchInputs {
            ladder_is_synthetic: false,
            ..report_inputs()
        };
        assert_eq!(evaluate_display_stretch(&inputs), None);
    }

    #[test]
    fn wall_clock_gate_blocks_healthy_video_with_dead_audio() {
        // Pre-fix 60Hz recording (ladder-stamped but correctly paced) whose
        // system audio died at 30s: the audio ratio alone screams "stretch"
        // but the video does not exceed the wall clock.
        let inputs = DisplayStretchInputs {
            display_secs: 90.3,
            display_start: 0.4,
            audio_refs: vec![("system-audio", 30.0)],
            audio_track_count: 1,
            wall_span_secs: Some(92.8),
            ladder_is_synthetic: true,
        };
        assert_eq!(evaluate_display_stretch(&inputs), None);
    }

    #[test]
    fn implausible_audio_reference_is_not_a_sync_target() {
        // Genuinely stretched video, but the only audio track died at a
        // quarter of the wall span; squeezing the video to it would over-
        // correct, so nothing is healed.
        let inputs = DisplayStretchInputs {
            display_secs: 202.22,
            display_start: 0.4728,
            audio_refs: vec![("system-audio", 22.0)],
            audio_track_count: 1,
            wall_span_secs: Some(92.8),
            ladder_is_synthetic: true,
        };
        assert_eq!(evaluate_display_stretch(&inputs), None);
    }

    #[test]
    fn without_wall_clock_a_single_audio_reference_is_not_enough() {
        let inputs = DisplayStretchInputs {
            wall_span_secs: None,
            ..report_inputs()
        };
        assert_eq!(evaluate_display_stretch(&inputs), None);
    }

    #[test]
    fn without_wall_clock_two_agreeing_audio_references_heal() {
        let inputs = DisplayStretchInputs {
            display_secs: 202.22,
            display_start: 0.4728,
            audio_refs: vec![("mic", 90.1), ("system-audio", 90.35)],
            audio_track_count: 2,
            wall_span_secs: None,
            ladder_is_synthetic: true,
        };
        let decision = evaluate_display_stretch(&inputs).expect("two refs must be enough");
        assert!((decision.expected_span_secs - 90.35).abs() < 0.01);
    }

    #[test]
    fn without_wall_clock_disagreeing_references_do_not_heal() {
        let inputs = DisplayStretchInputs {
            display_secs: 202.22,
            display_start: 0.4728,
            audio_refs: vec![("mic", 45.0), ("system-audio", 90.35)],
            audio_track_count: 2,
            wall_span_secs: None,
            ladder_is_synthetic: true,
        };
        assert_eq!(evaluate_display_stretch(&inputs), None);
    }

    #[test]
    fn no_audio_heals_against_the_wall_span() {
        let inputs = DisplayStretchInputs {
            display_secs: 202.22,
            display_start: 0.4728,
            audio_refs: vec![],
            audio_track_count: 0,
            wall_span_secs: Some(92.8),
            ladder_is_synthetic: true,
        };
        let decision = evaluate_display_stretch(&inputs).expect("wall span must be enough");
        assert!((decision.expected_span_secs - (92.8 - 0.4728)).abs() < 0.01);
    }

    #[test]
    fn no_audio_and_no_log_does_not_heal() {
        let inputs = DisplayStretchInputs {
            display_secs: 202.22,
            display_start: 0.4728,
            audio_refs: vec![],
            audio_track_count: 0,
            wall_span_secs: None,
            ladder_is_synthetic: true,
        };
        assert_eq!(evaluate_display_stretch(&inputs), None);
    }

    #[test]
    fn healthy_sixty_hertz_prefix_recording_is_left_alone() {
        // Pre-fix on a 60Hz monitor: ladder-stamped but correctly paced,
        // so the ratio sits at ~1.
        let inputs = DisplayStretchInputs {
            display_secs: 90.3,
            display_start: 0.4728,
            audio_refs: vec![("system-audio", 90.35)],
            audio_track_count: 1,
            wall_span_secs: Some(92.8),
            ladder_is_synthetic: true,
        };
        assert_eq!(evaluate_display_stretch(&inputs), None);
    }

    #[test]
    fn paused_stretched_recording_heals_to_the_audio_span() {
        // 90s wall with a long pause: 45s of content stretched 2.24x. The
        // wall gate still passes (100.8 > 99) and audio remains the target.
        let inputs = DisplayStretchInputs {
            display_secs: 100.8,
            display_start: 0.4,
            audio_refs: vec![("mic", 45.0), ("system-audio", 45.2)],
            audio_track_count: 2,
            wall_span_secs: Some(90.0),
            ladder_is_synthetic: true,
        };
        let decision = evaluate_display_stretch(&inputs).expect("paused stretch must heal");
        assert!((decision.expected_span_secs - 45.2).abs() < 0.01);
    }

    #[test]
    fn absurd_ratio_is_not_touched() {
        let inputs = DisplayStretchInputs {
            display_secs: 800.0,
            display_start: 0.0,
            audio_refs: vec![("mic", 90.0), ("system-audio", 90.0)],
            audio_track_count: 2,
            wall_span_secs: Some(92.8),
            ladder_is_synthetic: true,
        };
        assert_eq!(evaluate_display_stretch(&inputs), None);
    }

    #[test]
    fn wall_span_parses_first_and_last_log_timestamps() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(
            dir.path().join("recording-logs.log"),
            "2026-07-06T18:19:14.754110Z  INFO recording: start\n\
             not a timestamped line\n\
             2026-07-06T18:19:58.715980Z  INFO snapshot\n\
             2026-07-06T18:20:47.563260Z  INFO cap_desktop_lib::recording: done\n",
        )
        .unwrap();
        let span = recording_log_wall_span_secs(dir.path()).unwrap();
        assert!((span - 92.809).abs() < 0.01, "span {span}");
    }

    #[test]
    fn wall_span_is_none_for_missing_or_unparseable_logs() {
        let dir = tempfile::tempdir().unwrap();
        assert_eq!(recording_log_wall_span_secs(dir.path()), None);
        std::fs::write(
            dir.path().join("recording-logs.log"),
            "no timestamps here\n",
        )
        .unwrap();
        assert_eq!(recording_log_wall_span_secs(dir.path()), None);
    }

    #[test]
    fn wall_span_rejects_logs_with_backward_clock_steps() {
        // A backward system-clock step mid-recording under-counts the span,
        // which could both authorize and mis-target a no-audio heal; such a
        // log must be discredited entirely.
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(
            dir.path().join("recording-logs.log"),
            "2026-07-06T18:19:14.754110Z  INFO start\n\
             2026-07-06T18:19:58.715980Z  INFO snapshot\n\
             2026-07-06T18:19:20.000000Z  INFO after ntp step\n\
             2026-07-06T18:20:47.563260Z  INFO done\n",
        )
        .unwrap();
        assert_eq!(recording_log_wall_span_secs(dir.path()), None);
    }

    #[test]
    fn wall_span_tolerates_async_log_interleaving() {
        // Millisecond-scale inversions are normal: threads capture their
        // timestamps before the appender serializes the lines.
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(
            dir.path().join("recording-logs.log"),
            "2026-07-06T18:19:14.754110Z  INFO start\n\
             2026-07-06T18:19:58.715980Z  INFO a\n\
             2026-07-06T18:19:58.703215Z  INFO b (interleaved)\n\
             2026-07-06T18:20:47.563260Z  INFO done\n",
        )
        .unwrap();
        let span = recording_log_wall_span_secs(dir.path()).unwrap();
        assert!((span - 92.809).abs() < 0.01, "span {span}");
    }

    #[test]
    fn concurrent_heals_of_the_same_project_are_exclusive() {
        let dir = tempfile::tempdir().unwrap();
        let first = HealInFlightGuard::try_claim(dir.path());
        assert!(first.is_some());
        assert!(
            HealInFlightGuard::try_claim(dir.path()).is_none(),
            "second claim must be refused while the first is held"
        );
        drop(first);
        assert!(
            HealInFlightGuard::try_claim(dir.path()).is_some(),
            "claim must be reusable after release"
        );
    }

    #[test]
    fn config_rescale_scales_timeline_and_overlays_exactly() {
        use cap_project::{
            ProjectConfiguration, TimelineConfiguration, TimelineSegment, ZoomMode, ZoomSegment,
        };

        let dir = tempfile::tempdir().unwrap();
        let timeline = TimelineConfiguration {
            segments: vec![TimelineSegment {
                recording_clip: 0,
                timescale: 1.0,
                start: 0.0,
                end: 202.220711,
                name: None,
                speed_audio_mode: None,
                hide_cursor: None,
                volume: None,
            }],
            transitions: Vec::new(),
            zoom_segments: vec![ZoomSegment {
                start: 100.0,
                end: 150.0,
                amount: 2.0,
                mode: ZoomMode::Auto,
                glide_direction: Default::default(),
                glide_speed: 0.5,
                instant_animation: false,
                edge_snap_ratio: 0.25,
            }],
            scene_segments: vec![],
            style_segments: Vec::new(),
            image_segments: Vec::new(),
            mask_segments: vec![],
            text_segments: vec![],
            caption_segments: vec![],
            keyboard_segments: vec![],
            audio_segments: vec![],
            camera3d_segments: Vec::new(),
        };
        let config = ProjectConfiguration {
            timeline: Some(timeline),
            ..Default::default()
        };
        config.write(dir.path()).unwrap();

        let scale = 0.4468;
        let mut scales = HashMap::new();
        scales.insert(0u32, scale);
        rescale_project_config(dir.path(), &scales);

        let reloaded = ProjectConfiguration::load(dir.path()).unwrap();
        let timeline = reloaded.timeline.unwrap();
        assert!((timeline.segments[0].end - 202.220711 * scale).abs() < 1e-6);
        assert!((timeline.zoom_segments[0].start - 100.0 * scale).abs() < 1e-6);
        assert!((timeline.zoom_segments[0].end - 150.0 * scale).abs() < 1e-6);
    }

    #[test]
    fn config_rescale_scales_camera3d_segments_exactly() {
        use cap_project::{
            Camera3DKeyframe, Camera3DSegment, Camera3DTracks, ProjectConfiguration,
            TimelineConfiguration, TimelineSegment,
        };

        let dir = tempfile::tempdir().unwrap();
        let timeline = TimelineConfiguration {
            segments: vec![TimelineSegment {
                recording_clip: 0,
                timescale: 1.0,
                start: 0.0,
                end: 202.220711,
                name: None,
                speed_audio_mode: None,
                hide_cursor: None,
                volume: None,
            }],
            transitions: Vec::new(),
            zoom_segments: vec![],
            scene_segments: vec![],
            style_segments: Vec::new(),
            image_segments: Vec::new(),
            mask_segments: vec![],
            text_segments: vec![],
            caption_segments: vec![],
            keyboard_segments: vec![],
            audio_segments: vec![],
            camera3d_segments: vec![Camera3DSegment {
                start: 100.0,
                end: 150.0,
                enabled: true,
                properties: Default::default(),
                blur: Default::default(),
                tracks: Camera3DTracks {
                    tilt_x: vec![
                        Camera3DKeyframe {
                            time: 0.0,
                            value: 0.0,
                            out_easing: None,
                            in_easing: None,
                        },
                        Camera3DKeyframe {
                            time: 10.0,
                            value: 15.0,
                            out_easing: None,
                            in_easing: None,
                        },
                    ],
                    ..Default::default()
                },
                transition_in: 0.5,
                transition_out: 0.8,
            }],
        };
        let config = ProjectConfiguration {
            timeline: Some(timeline),
            ..Default::default()
        };
        config.write(dir.path()).unwrap();

        let scale = 0.4468;
        let mut scales = HashMap::new();
        scales.insert(0u32, scale);
        rescale_project_config(dir.path(), &scales);

        let reloaded = ProjectConfiguration::load(dir.path()).unwrap();
        let timeline = reloaded.timeline.unwrap();
        let segment = &timeline.camera3d_segments[0];
        assert!((segment.start - 100.0 * scale).abs() < 1e-6);
        assert!((segment.end - 150.0 * scale).abs() < 1e-6);
        assert!((segment.transition_in - 0.5 * scale).abs() < 1e-6);
        assert!((segment.transition_out - 0.8 * scale).abs() < 1e-6);
        assert!((segment.tracks.tilt_x[0].time - 0.0 * scale).abs() < 1e-6);
        assert!((segment.tracks.tilt_x[1].time - 10.0 * scale).abs() < 1e-6);
    }

    #[test]
    fn config_rescale_leaves_overlays_alone_with_unhealed_clips() {
        use cap_project::{
            ProjectConfiguration, TimelineConfiguration, TimelineSegment, ZoomMode, ZoomSegment,
        };

        let dir = tempfile::tempdir().unwrap();
        let timeline = TimelineConfiguration {
            segments: vec![
                TimelineSegment {
                    recording_clip: 0,
                    timescale: 1.0,
                    start: 0.0,
                    end: 100.0,
                    name: None,
                    speed_audio_mode: None,
                    hide_cursor: None,
                    volume: None,
                },
                TimelineSegment {
                    recording_clip: 1,
                    timescale: 1.0,
                    start: 0.0,
                    end: 50.0,
                    name: None,
                    speed_audio_mode: None,
                    hide_cursor: None,
                    volume: None,
                },
            ],
            transitions: Vec::new(),
            zoom_segments: vec![ZoomSegment {
                start: 10.0,
                end: 20.0,
                amount: 2.0,
                mode: ZoomMode::Auto,
                glide_direction: Default::default(),
                glide_speed: 0.5,
                instant_animation: false,
                edge_snap_ratio: 0.25,
            }],
            scene_segments: vec![],
            style_segments: Vec::new(),
            image_segments: Vec::new(),
            mask_segments: vec![],
            text_segments: vec![],
            caption_segments: vec![],
            keyboard_segments: vec![],
            audio_segments: vec![],
            camera3d_segments: Vec::new(),
        };
        let config = ProjectConfiguration {
            timeline: Some(timeline),
            ..Default::default()
        };
        config.write(dir.path()).unwrap();

        let mut scales = HashMap::new();
        scales.insert(0u32, 0.5);
        rescale_project_config(dir.path(), &scales);

        let reloaded = ProjectConfiguration::load(dir.path()).unwrap();
        let timeline = reloaded.timeline.unwrap();
        // Healed clip's timeline segment scales…
        assert!((timeline.segments[0].end - 50.0).abs() < 1e-6);
        // …the unhealed clip's does not…
        assert!((timeline.segments[1].end - 50.0).abs() < 1e-6);
        // …and output-time overlays are left untouched because the output
        // timeline no longer scales uniformly.
        assert!((timeline.zoom_segments[0].start - 10.0).abs() < 1e-6);
    }
}