Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

63.5 KB
Raw Blame
//! The video half of Stage 2: PipeWire frames in, MP4 on disk out.
//!
//! CONSTANT FRAME RATE, DRIVEN BY A CLOCK, NOT BY ARRIVALS.
//!
//! A compositor delivers frames on damage. Nothing moves on screen, no frames
//! arrive — mutter will happily go seconds without one while the user reads a
//! page. Writing one output frame per delivered frame would therefore produce a
//! file whose playback speed depends on how busy the screen was, which is not a
//! recording of anything.
//!
//! So the output rate comes from a monotonic clock instead. [`Capture::advance`]
//! asks what frame index the wall clock is on and stamps the staged picture with
//! THAT index as its PTS, holding the last picture across a gap. That is why
//! [`crate::encoder`] splits conversion from encoding: a held frame costs an
//! upload and an encode (1.4 ms here) but not the colour conversion (3.6 ms),
//! which is the expensive part.
//!
//! WALL-CLOCK PTS, NOT A FRAME COUNTER. The PTS is the clock's frame index, not
//! a running count of frames written — and the two stop agreeing the moment a
//! tick is missed. If the loop is starved under load, an encode runs long, or the
//! screen sits static between wakeups, the next write JUMPS its PTS to the real
//! index and the container stores the skipped slots as that frame's duration. So
//! the file's length always equals real elapsed time: a dropped frame becomes one
//! longer-held frame, never a deleted slice of the timeline. Encoding a running
//! counter instead silently time-compressed recordings under load and desynced
//! the screen from audio, webcam and the cursor overlay (issue #511). Playback is
//! variable-rate, which the editor and compositor already seek/play by decoded
//! PTS (the same path the webcam, itself VFR, has always taken).
//!
//! The clock is ours, not the compositor's. `SPA_META_Header.pts` is more precise
//! per frame, but pause/resume and the audio epoch all live on this process's
//! monotonic clock, and quantising to 1/fps makes the difference immaterial.

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

use crate::encoder::{
    AudioEncoder, Backend, EncodeStats, Muxer, TrackId, VideoEncoder, VideoParams,
    AUDIO_CHANNELS, AUDIO_SAMPLE_RATE,
};
use crate::ffmpeg as ff;
use crate::shim::{self, AudioRing};

/// An audio capture to mux alongside the video.
pub struct AudioSource {
    /// "system" or "microphone" — the label a warning names.
    pub label: &'static str,
    pub ring: Arc<AudioRing>,
    /// Linear multiplier applied before encoding. 1.0 for the system mix; the
    /// microphone carries the UI's boost.
    pub gain: f32,
    pub bitrate: i64,
}

/// One capture feeding the mix.
struct AudioInput {
    label: &'static str,
    ring: Arc<AudioRing>,
    gain: f32,
    /// Samples drained but not yet mixed, because the other inputs had fewer.
    pending: Vec<f32>,
}

/// The single AAC track, and everything mixed into it.
///
/// ONE TRACK, NOT ONE PER SOURCE. The first shape of this code followed macOS
/// and wrote system audio and the microphone as two separate AAC tracks, on the
/// grounds that the export mixes every track it finds
/// (`crates/compositor/src/audio.rs`). What that missed is that THE PREVIEW DOES
/// NOT: it plays an HTML5 `<video>` element, which plays only the default audio
/// track and cannot be told to switch, because Chromium does not implement the
/// `audioTracks` API. With system audio first and nothing playing, the preview
/// was silent while the microphone sat in a track nothing would ever select.
///
/// The Windows helper has always written one mixed track
/// (`mf_encoder.cpp` has a single `audioStreamIndex_`, fed by `AudioMixer`), and
/// macOS has since done the same (`AudioTrackMixer` feeding the helper's single
/// `AVAssetWriterInput(mediaType: .audio)`). All three now agree.
struct AudioMix {
    inputs: Vec<AudioInput>,
    encoder: AudioEncoder,
    track: TrackId,
    /// Reused across drains so the steady state allocates nothing.
    scratch: Vec<f32>,
}

/// How far one input may lag behind another before it is treated as silent
/// rather than allowed to stall the track.
///
/// Mixing consumes `min(available)` across inputs so that neither runs ahead of
/// the other. Taken literally that means one dead input — a microphone
/// unplugged mid-recording — freezes the whole track, because its `min` stays
/// zero forever. A quarter of a second of slack is far more than the jitter
/// between two streams of the same 48 kHz graph, and far less than anyone can
/// hear as a gap.
const AUDIO_STARVE_SAMPLES: usize = AUDIO_SAMPLE_RATE as usize / 4 * AUDIO_CHANNELS;

impl AudioMix {
    /// Drains every input, mixes what they have in common, and encodes it.
    ///
    /// `flush` is set once at stop: it mixes whatever remains even when the
    /// inputs are unevenly filled, because there will be no more samples to even
    /// them out.
    fn pump(&mut self, muxer: &mut Muxer, flush: bool) -> Result<(), String> {
        for input in &mut self.inputs {
            input.ring.drain_into(&mut input.pending);
        }

        let shortest = self.inputs.iter().map(|i| i.pending.len()).min().unwrap_or(0);
        let longest = self.inputs.iter().map(|i| i.pending.len()).max().unwrap_or(0);
        // Normally consume only what every input can supply, so none runs ahead.
        // When one has fallen far behind — or at flush, when nothing more is
        // coming — take the longest and let the short ones contribute silence,
        // rather than letting a dead input freeze the track. See
        // AUDIO_STARVE_SAMPLES.
        let take = if flush || longest.saturating_sub(shortest) > AUDIO_STARVE_SAMPLES {
            longest
        } else {
            shortest
        };
        if take == 0 {
            return Ok(());
        }

        self.scratch.clear();
        self.scratch.resize(take, 0.0);
        for input in &mut self.inputs {
            let n = input.pending.len().min(take);
            for (out, sample) in self.scratch.iter_mut().zip(input.pending.drain(..n)) {
                // Summed, then clamped ONCE at the end rather than per input:
                // clamping each contribution would quietly attenuate the mix
                // whenever one source alone is already near full scale.
                *out += sample * input.gain;
            }
        }
        for sample in &mut self.scratch {
            // A boosted microphone over loud system audio must clip flat. An
            // out-of-range float survives until AAC quantises it and then wraps
            // to the opposite polarity, which sounds like a burst of noise.
            *sample = sample.clamp(-1.0, 1.0);
        }

        let id = self.track;
        let scratch = std::mem::take(&mut self.scratch);
        let result = self.encoder.push(&scratch, |packet| muxer.write(id, packet));
        self.scratch = scratch;
        result
    }

    /// Samples the rings had to discard, per input. Audible, unlike a dropped
    /// video frame.
    fn dropped(&self) -> Vec<(&'static str, u64)> {
        self.inputs
            .iter()
            .map(|input| (input.label, input.ring.dropped_samples()))
            .filter(|(_, dropped)| *dropped > 0)
            .collect()
    }
}

pub struct Selection {
    pub backend: Backend,
    /// One line per backend the ladder tried and refused, in order.
    pub rejected: Vec<String>,
}

/// Bits per pixel per frame for H.264 screen content.
///
/// Screen recordings are mostly static and compress far better than camera
/// footage, so this sits well below the ~0.2 a live-action encode would want.
/// At 1920×1080/60 it comes to about 12 Mbit/s.
const BITS_PER_PIXEL: f64 = 0.1;

/// Picks a video bitrate from the size the compositor actually negotiated.
///
/// THE CALLER CANNOT DO THIS. On Wayland the app does not know the capture
/// resolution until the portal has negotiated it — the user picks the source in
/// the compositor's own dialog, and it may be a window rather than a display.
/// The renderer therefore sends no bitrate at all. It used to send
/// `computeBitrate(TARGET_WIDTH, TARGET_HEIGHT)`, whose constants are 4K, so a
/// 1080p capture asked for 76.5 Mbit/s and produced 44 MB for 18 seconds.
fn default_bitrate(width: i32, height: i32, fps: i32) -> i64 {
    let pixels_per_second = f64::from(width.max(1)) * f64::from(height.max(1)) * f64::from(fps.max(1));
    // Floor so that a tiny window capture still gets enough bits to look sharp,
    // ceiling so that a 4K/120 stream cannot ask for something no disk wants.
    ((pixels_per_second * BITS_PER_PIXEL) as i64).clamp(2_000_000, 60_000_000)
}

pub struct Summary {
    pub path: PathBuf,
    /// The video timeline's length: the last PTS + 1 frame, in ms. With
    /// wall-clock PTS this tracks real elapsed time even when frames were
    /// dropped, so it — not the encoded frame count — is what the file lasts.
    pub duration_ms: u64,
    /// Frames actually encoded. Under variable-rate output this can be FEWER than
    /// `duration_ms * fps`: a stall is one held frame spanning many slots.
    pub frames: u64,
    /// Real wall-clock time the recording ran, excluding paused spans. Compared
    /// against `duration_ms` to flag a regression to time-compression (#511).
    pub wall_clock_ms: u64,
    pub stats: EncodeStats,
}

pub struct Capture {
    encoder: VideoEncoder,
    /// The dmabuf → VAAPI importer, present only on the zero-copy path (issue
    /// #507). When set, [`Self::stage`] imports the frame's descriptor into an
    /// NV12 surface instead of running swscale, and the encoder was opened
    /// against this importer's pool.
    importer: Option<crate::dmabuf_import::DmabufImporter>,
    video_track: TrackId,
    audio: Option<AudioMix>,
    /// `None` only between [`Self::finish`] taking it and the struct dropping.
    muxer: Option<Muxer>,
    path: PathBuf,
    fps: i32,
    /// Monotonic instant of output frame 0. Set when the FIRST frame is staged,
    /// not at construction: the gap between opening the encoder and the
    /// compositor's first frame is portal and negotiation latency, and starting
    /// the timeline before it would put that latency at the head of every
    /// recording.
    epoch: Option<Instant>,
    /// Time spent paused, subtracted from the elapsed clock so a resumed
    /// recording continues where it left off instead of leaving a gap.
    paused_total: Duration,
    paused_at: Option<Instant>,
    /// The next output frame index to write.
    next_index: i64,
    frames_written: u64,
    /// The size the encoder was opened at, latched for the whole file.
    ///
    /// An MP4 track cannot change resolution mid-file, but a window's crop rect
    /// can change on ANY buffer — mutter never renegotiates the format for a
    /// window stream, so a resize travels down the crop and nothing else. The
    /// committed size is therefore the contract, and a later crop is read
    /// through it rather than replacing it.
    committed_width: i32,
    committed_height: i32,
    /// The rectangle of the SOURCE STREAM the encoder last read, in stream
    /// pixels: the live crop origin (clamped by [`Self::read_origin`]) at the
    /// committed size.
    ///
    /// Exists for the cursor, not for the video. The portal reports pointer
    /// positions in stream pixels, and for a window stream the stream is the
    /// whole monitor — mutter pins it there and carves the window out through
    /// SPA_META_VideoCrop. Normalising the pointer against the stream would
    /// then place it in a rectangle the file does not show. This is the one the
    /// file DOES show.
    content: shim::CropRect,
}

/// The outcome of staging one captured frame.
#[derive(Debug, PartialEq, Eq)]
pub enum StageOutcome {
    /// A new frame was staged; `advance` will encode it.
    Staged,
    /// The recording is paused, so the incoming frame was deliberately ignored and
    /// the held picture kept frozen at the pause instant (pause is app-side, but the
    /// compositor keeps streaming). A distinct outcome on purpose: it is NOT
    /// `Staged` — nothing new was staged, so a caller counting encoded frames must
    /// not tally it — and NOT `Dropped` — nothing failed, so it must not count
    /// toward the import-failure budget that ends a recording.
    Frozen,
    /// A recoverable per-frame failure — one dmabuf the GPU could not map, or a
    /// transient EAGAIN. The frame is skipped and `advance` holds the previously
    /// staged one forward, so a single bad frame costs one frame, not the whole
    /// recording. Carries the reason for a log warning.
    Dropped(String),
}

impl Capture {
    pub fn start(
        path: &Path,
        width: i32,
        height: i32,
        fps: i32,
        // `None` derives one from the negotiated size, which is almost always
        // what the caller wants — see `default_bitrate`.
        bitrate: Option<i64>,
        forced: Option<Backend>,
        audio_sources: Vec<AudioSource>,
        // Present when the first frame is a tiled dmabuf: the encoder is then
        // opened to consume the importer's NV12 pool directly (issue #507).
        dmabuf: Option<&shim::DmabufDesc>,
    ) -> Result<(Self, Selection), String> {
        let bitrate = bitrate.unwrap_or_else(|| default_bitrate(width, height, fps));
        let mut rejected = Vec::new();
        // Shared with the negotiation offer (`prefer_dmabuf` in main) so the two
        // never disagree: offering dmabuf that this then refuses to import is what
        // makes a forced-software recording fail on its first frame.
        let use_dmabuf = crate::encoder::forced_allows_dmabuf(forced);
        let (encoder, importer) = match dmabuf.filter(|_| use_dmabuf) {
            Some(desc) => {
                // The importer maps the full stream (`desc`) and its VPP crops to
                // the committed record size (`width`/`height`): equal to the source
                // for a monitor, or the window's crop rectangle for a window. The
                // encoder is FORCED to VAAPI — the only backend that can consume the
                // mapped surface; a non-VAAPI machine never negotiates dmabuf.
                //
                // This branch never goes through `VideoEncoder::open`, so it skips the
                // ladder's `vaMapBuffer2` guard, as `dmabuf_import::available` does.
                // That is safe only while nothing here uploads a CPU frame: the import
                // maps and never transfers, and `open_importing` re-applies the guard
                // to the one upload left, in `VideoEncoder::stage`. On a libva without
                // the symbol this branch is also the ONLY route to hardware H.264, so
                // anything that disables it there downgrades to software (issue #534).
                let importer = crate::dmabuf_import::DmabufImporter::new(
                    desc.width,
                    desc.height,
                    width,
                    height,
                    desc.drm_fourcc,
                )?;
                // SAFETY: the importer's device and NV12 frames context are live
                // for as long as the returned encoder, which the Capture owns
                // alongside it below.
                let encoder = unsafe {
                    VideoEncoder::open_importing(
                        VideoParams { width, height, fps, bitrate },
                        importer.device(),
                        importer.output_frames_ctx(),
                    )?
                };
                (encoder, Some(importer))
            }
            None => {
                let encoder = VideoEncoder::open(
                    VideoParams { width, height, fps, bitrate },
                    forced,
                    |backend, error| rejected.push(format!("{}: {error}", backend.as_str())),
                )?;
                (encoder, None)
            }
        };
        let selection = Selection { backend: encoder.backend(), rejected };

        // Every track must exist before the header: MP4 fixes its track list
        // there, so an audio stream opened later could not be added at all.
        let mut muxer = Muxer::create(path)?;
        let video_track = muxer.add_stream(encoder.codec_context())?;
        // ONE encoder and ONE track for however many captures there are.
        let audio = if audio_sources.is_empty() {
            None
        } else {
            let bitrate = audio_sources.iter().map(|s| s.bitrate).max().unwrap_or(128_000);
            let encoder = AudioEncoder::open(bitrate)?;
            let track = muxer.add_stream(encoder.codec_context())?;
            Some(AudioMix {
                inputs: audio_sources
                    .into_iter()
                    .map(|source| AudioInput {
                        label: source.label,
                        ring: source.ring,
                        gain: source.gain,
                        pending: Vec::new(),
                    })
                    .collect(),
                encoder,
                track,
                scratch: Vec::new(),
            })
        };
        muxer.write_header()?;

        Ok((
            Self {
                encoder,
                importer,
                video_track,
                audio,
                muxer: Some(muxer),
                path: path.to_path_buf(),
                fps,
                epoch: None,
                paused_total: Duration::ZERO,
                paused_at: None,
                next_index: 0,
                frames_written: 0,
                committed_width: width,
                committed_height: height,
                content: shim::CropRect { x: 0, y: 0, width, height },
            },
            selection,
        ))
    }

    /// Whether this frame's crop still matches what the encoder was opened at.
    ///
    /// A divergence means the recorded window was resized. The recording keeps
    /// its original dimensions — see [`Self::committed_width`] — so the caller
    /// reports it once rather than silently reframing.
    pub fn crop_diverged(&self, frame: &shim::Frame) -> bool {
        // Compared at ENCODED parity, not raw. The committed size was rounded
        // down to even for H.264 chroma, so a window sitting stably at 321x241
        // commits 320x240 and would otherwise be reported as resized on every
        // single frame — a warning about a window that never moved.
        (frame.crop.width & !1) != self.committed_width
            || (frame.crop.height & !1) != self.committed_height
    }

    /// Where to start reading this frame, in source pixels.
    ///
    /// Follows the LIVE crop origin, so moving the recorded window tracks it,
    /// but clamps so a committed-size read always stays inside the buffer. That
    /// clamp is the only thing standing between a shrunken window and an
    /// out-of-bounds read inside swscale.
    fn read_origin(&self, frame: &shim::Frame) -> (i32, i32) {
        let max_x = (frame.width - self.committed_width).max(0);
        let max_y = (frame.height - self.committed_height).max(0);
        (
            frame.crop.x.clamp(0, max_x),
            frame.crop.y.clamp(0, max_y),
        )
    }

    /// Converts a captured frame into the encoder's staging buffer. Nothing is
    /// written until [`Self::advance`] runs. A recoverable per-frame failure (a
    /// dmabuf the GPU cannot map) returns `Ok(Dropped)` rather than `Err`, so it
    /// costs one frame, not the recording; a genuine encoder error still errors.
    pub fn stage(&mut self, frame: &shim::Frame) -> Result<StageOutcome, String> {
        // A paused recording must not ingest new pixels. The compositor keeps
        // streaming while the app is paused — pause is app-side — so frames still
        // arrive here; staging one would move the held picture to POST-pause
        // content, which the tail write in `finish` would then encode into the
        // file if a stop follows a pause with no resume. The user expects pause
        // to hold that privacy boundary, so the staged picture is frozen at the
        // pause instant instead.
        //
        // Its own `Frozen`, not `Dropped` and not `Staged`. Not `Dropped`: that is
        // the GPU-import failure signal, which warns per frame and ends the
        // recording past MAX_CONSECUTIVE_IMPORT_FAILURES, so a pause longer than
        // that many frames would abort the file — nothing failed here. Not `Staged`
        // either: nothing was staged, so anything downstream that counts encoded
        // frames or reasons about import health must be able to tell a freeze from
        // a real frame rather than have it hidden behind `Staged`.
        //
        // Ahead of the dmabuf path so the freeze covers the zero-copy route as
        // well, and so `mark_started` stays untouched: a pause that arrives
        // before the first frame must leave the capture unstarted.
        if self.paused_at.is_some() {
            return Ok(StageOutcome::Frozen);
        }
        // The rectangle this frame is read from, recorded BEFORE the paths diverge.
        // Both of them read from the same origin, so computing it once is what
        // makes `content_rect` the single answer to "what does the file show" —
        // the whole point of measuring the cursor against it. Assigning it inside
        // the CPU branch alone left `content` at its opening value on the
        // zero-copy path, so a window recorded through dmabuf reported the pointer
        // without the crop origin taken off: the scale was right and the position
        // was not, which is half of issue #513 surviving on the default GPU route.
        let (x, y) = self.read_origin(frame);
        self.content = shim::CropRect {
            x,
            y,
            width: self.committed_width,
            height: self.committed_height,
        };

        // Zero-copy dmabuf path: import the tiled GPU buffer into an NV12 VAAPI
        // surface (the VPP crops a window to its committed rectangle) and hand it
        // to the encoder as-is — no swscale. See issue #507.
        if frame.dmabuf.is_some() {
            // Same origin the content rect above carries. For a monitor it is (0, 0).
            let (crop_x, crop_y) = (x, y);
            let desc = frame.dmabuf.as_ref().expect("checked is_some above");
            let importer = self
                .importer
                .as_mut()
                .ok_or_else(|| "dmabuf frame arrived but no importer was built".to_owned())?;
            // Borrow the descriptor's planes directly — they are already
            // `shim::DmabufPlane`, the exact type `import` takes — instead of
            // reallocating a plane vector on every frame.
            let nv12 = match importer.import(
                &crate::dmabuf_import::DmabufFrame {
                    width: desc.width,
                    height: desc.height,
                    drm_fourcc: desc.drm_fourcc,
                    modifier: desc.modifier,
                    planes: &desc.planes,
                },
                crop_x,
                crop_y,
            ) {
                Ok(nv12) => nv12,
                // A single un-mappable buffer must not end the recording. Skip it;
                // `advance` holds the previous frame, and the shm path is still in
                // the offer for a full downgrade later (a planned follow-up).
                Err(reason) => return Ok(StageOutcome::Dropped(reason)),
            };
            // SAFETY: `nv12` is a VAAPI NV12 frame from the pool the encoder was
            // opened against; the encoder takes ownership.
            unsafe { self.encoder.stage_hw(nv12) };
            self.mark_started();
            return Ok(StageOutcome::Staged);
        }

        let format = pixel_format(frame.video_format)?;

        // Address the crop by moving the START of the slice, and hand swscale the
        // frame's OWN stride unchanged. The stride is the distance between rows
        // in the source buffer, which cropping does not alter — WebRTC's memfd
        // path subtracts the x offset from it, which is wrong for any non-zero x
        // and is latent there only because no shipping compositor sets one.
        let offset = (y as usize)
            .checked_mul(frame.stride)
            .and_then(|rows| rows.checked_add((x as usize) * BYTES_PER_SOURCE_PIXEL))
            .ok_or_else(|| "crop offset overflows".to_owned())?;
        let pixels = frame
            .pixels
            .get(offset..)
            .ok_or_else(|| format!("crop offset {offset} is past the end of the frame"))?;

        self.encoder.stage(pixels, frame.stride, format)?;
        self.mark_started();
        Ok(StageOutcome::Staged)
    }

    /// Starts the timeline on the first staged frame and drops the audio backlog.
    ///
    /// Audio has been accumulating since the process started, while the portal
    /// picker was up and the format was being negotiated. None of it belongs to
    /// the recording: video frame 0 is now, so audio sample 0 is now too. Keeping
    /// the backlog would shift the whole track earlier by however long the user
    /// took to click.
    fn mark_started(&mut self) {
        if self.epoch.is_some() {
            return;
        }
        self.epoch = Some(Instant::now());
        if let Some(mix) = &mut self.audio {
            for input in &mut mix.inputs {
                input.ring.clear();
                input.pending.clear();
            }
        }
    }

    /// Whether a picture has been staged, which is also whether the timeline has
    /// started.
    pub fn started(&self) -> bool {
        self.epoch.is_some()
    }

    /// The source rectangle the file is showing. See [`Self::content`].
    pub fn content_rect(&self) -> shim::CropRect {
        self.content
    }

    /// Stamps the staged picture at the wall clock's current frame index and
    /// encodes it. Returns 1 if a frame was written this call, 0 otherwise.
    ///
    /// ONE ENCODE PER CALL, STAMPED FROM THE CLOCK. The PTS is `current_index()`
    /// — the frame index real time is on — not a running counter. When the loop
    /// is serviced every tick the indices come out consecutive and the file
    /// looks constant-rate; when ticks were missed (loop starved, slow encode,
    /// static screen) `next_index` JUMPS past the skipped slots and the container
    /// records them as this frame's duration. That jump is what keeps the file's
    /// length equal to real elapsed time under drops, with no unbounded catch-up
    /// burst to block `stop` (issue #511). Several arrivals inside one 1/fps slot
    /// collapse to one write, which is the correct quantisation.
    pub fn advance(&mut self) -> Result<u32, String> {
        if self.paused_at.is_some() || !self.encoder.has_staged_frame() {
            return Ok(0);
        }
        let target = self.current_index();
        let Some(muxer) = self.muxer.as_mut() else {
            return Ok(0);
        };
        let mut written = 0;
        if target >= self.next_index {
            let track = self.video_track;
            self.encoder
                .encode_staged(target, |packet| muxer.write(track, packet))?;
            self.next_index = target + 1;
            self.frames_written += 1;
            written = 1;
        }

        // Audio is NOT quantised the way video is. A held video frame can be
        // recreated at any time; a missed audio sample cannot, and the ring
        // drops the oldest once it fills. Draining every wakeup keeps it far
        // from that cap — at 48 kHz a 16 ms tick carries about 768 samples.
        if let Some(mix) = self.audio.as_mut() {
            mix.pump(muxer, false)?;
        }
        Ok(written)
    }

    pub fn pause(&mut self) {
        if self.paused_at.is_none() {
            self.paused_at = Some(Instant::now());
            // The rings stop taking samples for the duration. What they already
            // hold is audio from before the pause: it is part of the take and
            // stays, and the first drain after resume places it. See
            // AudioRing::pause for what discarding it used to cost.
            //
            // THE CLOCK IS STOPPED FIRST, AND THAT ORDER IS THE RIGHT WAY ROUND.
            // It leaves a window of a microsecond or so in which a capture
            // thread can still be admitted — but a PipeWire buffer is delivered
            // AFTER the audio in it was captured, so a buffer arriving in that
            // window carries sound from before the pause instant, which the
            // video timeline does cover. Keeping it is correct. Closing the
            // gates first would reject that same buffer instead, and a
            // rejection owes no silence, so it would drop a quantum of audio
            // the video still accounts for — the same error, in the direction
            // that actually loses something.
            if let Some(mix) = &mut self.audio {
                for input in &mut mix.inputs {
                    input.ring.pause();
                }
            }
        }
    }

    pub fn resume(&mut self) {
        if let Some(since) = self.paused_at.take() {
            self.paused_total += since.elapsed();
            // Nothing was captured while paused, so there is nothing here to
            // throw away — the rings only have to start taking samples again.
            // `pending` is left alone for the same reason the rings are: it
            // holds samples drained before the pause, which are take audio.
            if let Some(mix) = &mut self.audio {
                for input in &mut mix.inputs {
                    input.ring.resume();
                }
            }
        }
    }

    /// Samples the rings had to discard because the encoder fell behind, per
    /// track. Audible if non-zero, unlike a dropped video frame.
    pub fn dropped_audio(&self) -> Vec<(&'static str, u64)> {
        self.audio.as_ref().map(AudioMix::dropped).unwrap_or_default()
    }

    pub fn is_paused(&self) -> bool {
        self.paused_at.is_some()
    }

    /// Flushes the encoder, writes the trailer, and closes the file.
    pub fn finish(mut self) -> Result<Summary, String> {
        let mut muxer = self
            .muxer
            .take()
            .ok_or_else(|| "capture was already finished".to_owned())?;

        // Close the tail. Stamp one final held frame at the current wall-clock
        // index so the file's last PTS reflects real elapsed time even when the
        // loop's final heartbeat landed a few ticks before stop — otherwise a
        // recording that ended during a quiet spell would be short by that gap.
        // Runs even when stopped while PAUSED: `current_index()` freezes at the
        // pause boundary, so the active time up to the pause still reaches the
        // timeline (a stop can follow a pause with no resume in between). The
        // staged picture is the last PRE-pause frame — `stage` is gated on pause —
        // so this cannot leak post-pause content into the file.
        if self.encoder.has_staged_frame() {
            let target = self.current_index();
            if target >= self.next_index {
                let track = self.video_track;
                self.encoder
                    .encode_staged(target, |packet| muxer.write(track, packet))?;
                self.next_index = target + 1;
                self.frames_written += 1;
            }
        }

        // Snapshot the active wall-clock time HERE, before the flush below.
        // Draining audio, the encoder and the mp4 trailer can take tens of ms on
        // a long recording, and `elapsed_active` keeps ticking through it; reading
        // it afterwards would make a slow flush look like a timeline divergence
        // (issue #512). The video timeline (`next_index`) is already frozen at the
        // tail write above, so this is the moment the two are meant to agree.
        let wall_clock_ms = self
            .elapsed_active()
            .map(|elapsed| elapsed.as_millis() as u64)
            .unwrap_or(0);

        // Audio first: whatever is still in the rings is real recorded sound,
        // and draining it before the video flush keeps both ending at roughly
        // the same timestamp. `flush` lets the mix take unevenly-filled inputs,
        // since no more samples are coming to even them out.
        if let Some(mix) = self.audio.as_mut() {
            mix.pump(&mut muxer, true)?;
            let id = mix.track;
            mix.encoder.finish(|packet| muxer.write(id, packet))?;
        }

        let video_track = self.video_track;
        self.encoder
            .finish(|packet| muxer.write(video_track, packet))?;
        muxer.finish()?;

        Ok(Summary {
            path: self.path.clone(),
            // From the timeline, not the frame count: the last PTS is
            // `next_index - 1`, so the presentation spans `next_index` frames.
            // With wall-clock PTS this equals real elapsed time even when frames
            // were dropped — which the old `frames_written / fps` did not, and is
            // the bug being fixed (#511).
            duration_ms: (self.next_index as u64 * 1000) / self.fps.max(1) as u64,
            frames: self.frames_written,
            wall_clock_ms,
            stats: self.encoder.stats(),
        })
    }

    /// Output frame index the wall clock is currently on, excluding paused time.
    /// `-1` before the first frame is staged, so `advance` writes nothing.
    fn current_index(&self) -> i64 {
        match self.elapsed_active() {
            Some(elapsed) => (elapsed.as_nanos() as i64 * self.fps as i64) / 1_000_000_000,
            None => -1,
        }
    }

    /// Wall-clock time since the first staged frame, with paused spans removed.
    /// `None` until the timeline has started. The single source of both the PTS
    /// clock (`current_index`) and the divergence telemetry (`wall_clock_ms`), so
    /// the two cannot drift apart by construction.
    fn elapsed_active(&self) -> Option<Duration> {
        let epoch = self.epoch?;
        let mut elapsed = epoch.elapsed().saturating_sub(self.paused_total);
        if let Some(since) = self.paused_at {
            elapsed = elapsed.saturating_sub(since.elapsed());
        }
        Some(elapsed)
    }
}

/// SPA video format id → ffmpeg pixel format.
///
/// The ids come from the compiled shim rather than from hardcoded numbers (see
/// [`shim::constants`]), so this cannot silently mis-map the day upstream
/// inserts an enum value. Only the four formats
/// `osc_build_enum_format` advertises can appear here; anything else means the
/// two lists drifted apart, which is worth an error rather than a guess at the
/// channel order.
/// Bytes per pixel in every format [`pixel_format`] accepts.
///
/// All four that `osc_build_enum_format` advertises are 32-bit, so this is a
/// constant rather than a lookup. It lives HERE, next to the table it describes,
/// because the two must change together: adding a 24-bit format below without
/// revisiting this would silently mis-address every cropped row.
pub const BYTES_PER_SOURCE_PIXEL: usize = 4;

fn pixel_format(spa_format: u32) -> Result<ff::AVPixelFormat, String> {
    let constants = shim::constants();
    // `*0` rather than `*A`: the padding byte carries no alpha, and telling
    // swscale it does would make it blend against uninitialised data.
    let table = [
        (constants.video_format_bgrx, ff::AV_PIX_FMT_BGR0),
        (constants.video_format_rgbx, ff::AV_PIX_FMT_RGB0),
        (constants.video_format_bgra, ff::AV_PIX_FMT_BGRA),
        (constants.video_format_rgba, ff::AV_PIX_FMT_RGBA),
    ];
    table
        .iter()
        .find(|(id, _)| *id == spa_format)
        .map(|(_, format)| *format)
        .ok_or_else(|| {
            format!(
                "the compositor negotiated SPA video format {spa_format}, which this helper \
                 does not know how to convert. It should only ever pick one of the four \
                 formats osc_build_enum_format advertises."
            )
        })
}

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

    fn frame(width: i32, height: i32, format: u32) -> shim::Frame {
        let stride = width as usize * 4;
        shim::Frame {
            pixels: vec![0x30; stride * height as usize],
            stride,
            width,
            height,
            video_format: format,
            pts_ns: -1,
            crop: shim::CropRect { x: 0, y: 0, width, height },
            has_crop: false,
            dmabuf: None,
        }
    }

    /// A window's frame: a monitor-sized buffer whose content is the rectangle
    /// at (x, y). This is what mutter actually delivers for a window stream.
    fn cropped_frame(
        width: i32,
        height: i32,
        crop: shim::CropRect,
        format: u32,
    ) -> shim::Frame {
        let mut frame = frame(width, height, format);
        frame.crop = crop;
        frame.has_crop = true;
        frame
    }

    #[test]
    fn advertised_formats_all_map_to_a_pixel_format() {
        // The two lists — what osc_build_enum_format offers and what
        // pixel_format accepts — must not drift. A compositor picking a format
        // we advertised but cannot convert kills the recording at the first
        // frame, on that user's machine only.
        let c = shim::constants();
        for id in [
            c.video_format_bgrx,
            c.video_format_rgbx,
            c.video_format_bgra,
            c.video_format_rgba,
        ] {
            assert!(pixel_format(id).is_ok(), "SPA format {id} is offered but not convertible");
        }
    }

    #[test]
    fn an_unadvertised_format_is_reported_not_guessed() {
        let error = pixel_format(u32::MAX).expect_err("must reject");
        assert!(error.contains("does not know how to convert"), "{error}");
    }

    #[test]
    fn the_timeline_does_not_start_until_the_first_frame_is_staged() {
        let output = std::env::temp_dir().join("openscreen-capture-epoch.mp4");
        let (mut capture, _) =
            Capture::start(&output, 320, 240, 30, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
                .expect("start");
        assert!(!capture.started());
        // Nothing staged: advance must not write a frame of uninitialised memory.
        assert_eq!(capture.advance().expect("advance"), 0);

        capture
            .stage(&frame(320, 240, shim::constants().video_format_bgrx))
            .expect("stage");
        assert!(capture.started());
        let _ = std::fs::remove_file(&output);
    }

    #[test]
    fn a_static_screen_still_produces_frames_and_tracks_wall_clock() {
        // The whole reason the clock drives the output: one staged frame, no
        // further arrivals, and the file's DURATION must still track real time.
        // Under variable-rate output a long static gap is one held frame, so the
        // event loop's heartbeat is simulated — a tick every ~30 ms.
        let output = std::env::temp_dir().join("openscreen-capture-static.mp4");
        let (mut capture, _) =
            Capture::start(&output, 320, 240, 30, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
                .expect("start");
        capture
            .stage(&frame(320, 240, shim::constants().video_format_bgrx))
            .expect("stage");

        for _ in 0..5 {
            std::thread::sleep(Duration::from_millis(30));
            capture.advance().expect("advance");
        }

        let summary = capture.finish().expect("finish");
        assert!(summary.frames >= 1, "a static screen must still produce frames, got {}", summary.frames);
        assert!(
            summary.duration_ms >= 130,
            "the timeline must track the ~150 ms elapsed, got {} ms",
            summary.duration_ms
        );
        let _ = std::fs::remove_file(&output);
    }

    /// The window-capture bug, at the layer where it produced wrong pixels.
    ///
    /// mutter hands a window stream MONITOR-sized buffers and reports the
    /// window's rectangle as SPA_META_VideoCrop. Encoding the buffer without
    /// applying that rectangle is what padded window recordings out to screen
    /// size with black.
    #[test]
    fn a_window_is_staged_from_its_crop_inside_a_larger_frame() {
        let output = std::env::temp_dir().join("openscreen-capture-crop.mp4");
        let (mut capture, _) =
            Capture::start(&output, 320, 240, 30, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
                .expect("start");

        // A 1920x1080 stream carrying a 320x240 window at (100, 50).
        let staged = capture.stage(&cropped_frame(
            1920,
            1080,
            shim::CropRect { x: 100, y: 50, width: 320, height: 240 },
            shim::constants().video_format_bgrx,
        ));

        assert!(staged.is_ok(), "a crop inside the frame must stage: {staged:?}");

        // Frames are clock-driven, so let the timeline advance far enough for the
        // staged picture to actually reach the encoder at the cropped geometry.
        std::thread::sleep(Duration::from_millis(120));
        let written = capture.advance().expect("advance");
        assert!(written >= 1, "the cropped picture should have been encoded, wrote {written}");

        let summary = capture.finish().expect("finish");
        assert!(summary.frames >= 1, "the cropped picture must reach the file, got {}", summary.frames);
        let _ = std::fs::remove_file(&output);
    }

    /// The rectangle the cursor is measured against has to be the one the FILE
    /// shows, which for a window is the crop and not the stream. Getting this
    /// wrong put the pointer in monitor coordinates over window-sized footage —
    /// a fixed offset and a wrong scale, in every window recording.
    #[test]
    fn the_content_rect_is_the_window_the_file_shows() {
        let output = std::env::temp_dir().join("openscreen-capture-content.mp4");
        let (mut capture, _) =
            Capture::start(&output, 320, 240, 30, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
                .expect("start");

        // Before a frame is staged there is nothing cropped yet, so the whole
        // committed size sits at the origin.
        assert_eq!(
            capture.content_rect(),
            shim::CropRect { x: 0, y: 0, width: 320, height: 240 }
        );

        capture
            .stage(&cropped_frame(
                1920,
                1080,
                shim::CropRect { x: 100, y: 50, width: 320, height: 240 },
                shim::constants().video_format_bgrx,
            ))
            .expect("stage");
        assert_eq!(
            capture.content_rect(),
            shim::CropRect { x: 100, y: 50, width: 320, height: 240 }
        );

        // The window moved. The file follows its origin at the committed size,
        // and so must the cursor.
        capture
            .stage(&cropped_frame(
                1920,
                1080,
                shim::CropRect { x: 700, y: 400, width: 320, height: 240 },
                shim::constants().video_format_bgrx,
            ))
            .expect("stage");
        assert_eq!(
            capture.content_rect(),
            shim::CropRect { x: 700, y: 400, width: 320, height: 240 }
        );

        // An origin that would read past the buffer is clamped for the pixels,
        // so the cursor has to be clamped with it or the two disagree about
        // which rectangle was recorded.
        capture
            .stage(&cropped_frame(
                1920,
                1080,
                shim::CropRect { x: 1800, y: 1000, width: 320, height: 240 },
                shim::constants().video_format_bgrx,
            ))
            .expect("stage");
        assert_eq!(
            capture.content_rect(),
            shim::CropRect { x: 1600, y: 840, width: 320, height: 240 }
        );

        let _ = capture.finish();
        let _ = std::fs::remove_file(&output);
    }

    /// A crop flush against the right edge leaves the last row short of a full
    /// stride. The old `stride * height` bounds check rejected exactly those —
    /// i.e. every window not touching the left edge.
    #[test]
    fn a_crop_against_the_right_edge_is_not_rejected_as_truncated() {
        let output = std::env::temp_dir().join("openscreen-capture-edge.mp4");
        let (mut capture, _) =
            Capture::start(&output, 320, 240, 30, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
                .expect("start");

        let staged = capture.stage(&cropped_frame(
            1920,
            1080,
            shim::CropRect { x: 1600, y: 840, width: 320, height: 240 },
            shim::constants().video_format_bgrx,
        ));

        assert!(staged.is_ok(), "a crop at the far corner must stage: {staged:?}");
        let _ = capture.finish();
        let _ = std::fs::remove_file(&output);
    }

    /// The safety property. A window that SHRANK after the encoder was opened
    /// still reports its own smaller rect, and reading a committed-sized picture
    /// from its origin must stay inside the buffer rather than running off the
    /// end into whatever follows it in the mapping.
    #[test]
    fn a_shrunken_window_is_read_from_inside_the_frame() {
        let output = std::env::temp_dir().join("openscreen-capture-shrunk.mp4");
        let (mut capture, _) =
            Capture::start(&output, 320, 240, 30, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
                .expect("start");

        // Origin so close to the edge that a 320x240 read from it would overrun.
        let frame = cropped_frame(
            400,
            300,
            shim::CropRect { x: 380, y: 290, width: 20, height: 10 },
            shim::constants().video_format_bgrx,
        );
        assert!(capture.crop_diverged(&frame), "20x10 must not look like the committed 320x240");

        let staged = capture.stage(&frame);
        assert!(staged.is_ok(), "the read must be clamped back inside the frame: {staged:?}");
        let _ = capture.finish();
        let _ = std::fs::remove_file(&output);
    }

    /// A window whose size is odd is rounded down once, at encoder open. Judging
    /// later frames against the raw rect would then report a resize on every
    /// frame of a window that never moved.
    #[test]
    fn a_stable_odd_sized_window_is_not_reported_as_resized() {
        let output = std::env::temp_dir().join("openscreen-capture-odd.mp4");
        // 321x241 rounds to the 320x240 the encoder is opened at.
        let (mut capture, _) =
            Capture::start(&output, 320, 240, 30, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
                .expect("start");

        let frame = cropped_frame(
            1920,
            1080,
            shim::CropRect { x: 0, y: 0, width: 321, height: 241 },
            shim::constants().video_format_bgrx,
        );

        assert!(!capture.crop_diverged(&frame), "an unchanged odd crop is not a resize");
        let _ = capture.finish();
        let _ = std::fs::remove_file(&output);
    }

    #[test]
    fn an_uncropped_frame_reports_no_divergence() {
        let output = std::env::temp_dir().join("openscreen-capture-nocrop.mp4");
        let (mut capture, _) =
            Capture::start(&output, 320, 240, 30, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
                .expect("start");

        assert!(!capture.crop_diverged(&frame(320, 240, shim::constants().video_format_bgrx)));
        let _ = capture.finish();
        let _ = std::fs::remove_file(&output);
    }

    #[test]
    fn paused_time_does_not_advance_the_timeline() {
        let output = std::env::temp_dir().join("openscreen-capture-pause.mp4");
        let (mut capture, _) =
            Capture::start(&output, 320, 240, 30, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
                .expect("start");
        capture
            .stage(&frame(320, 240, shim::constants().video_format_bgrx))
            .expect("stage");

        capture.pause();
        assert!(capture.is_paused());
        std::thread::sleep(Duration::from_millis(150));
        // A paused capture writes nothing, however long it is paused for.
        assert_eq!(capture.advance().expect("advance"), 0);
        capture.resume();
        // And the paused interval is not owed back as a burst of held frames.
        assert_eq!(capture.advance().expect("advance"), 1, "only frame 0 is due");

        let _ = std::fs::remove_file(&output);
    }

    #[test]
    fn audio_captured_before_the_first_frame_is_discarded_without_being_called_a_drop() {
        // Regression: the audio stream opens before the portal picker is
        // raised, so it records for as long as the user takes to click — easily
        // past the ring's cap. Those samples are deliberately thrown away when
        // the video epoch is set. Counting them as overflow made every single
        // recording report "the encoder could not keep up", which was measured
        // on a real 29-second capture: 78336 samples, all of them pre-roll.
        let ring = Arc::new(AudioRing::new(1, 8, AUDIO_CHANNELS));
        let capacity = 1 * 8 * AUDIO_CHANNELS;
        ring.push_for_test(&vec![0.5; capacity * 3]);
        assert!(ring.dropped_samples() > 0, "the ring must have overflowed for this test to mean anything");

        let output = std::env::temp_dir().join("openscreen-capture-audio-preroll.mp4");
        let (mut capture, _) = Capture::start(
            &output,
            320,
            240,
            30,
            Some(1_000_000),
            Some(Backend::Software),
            vec![AudioSource { label: "system", ring: ring.clone(), gain: 1.0, bitrate: 128_000 }],
            None,
        )
        .expect("start");

        capture
            .stage(&frame(320, 240, shim::constants().video_format_bgrx))
            .expect("stage");

        assert_eq!(
            ring.dropped_samples(),
            0,
            "pre-roll overflow must not be reported as the encoder falling behind"
        );
        assert!(capture.dropped_audio().is_empty());
        let _ = std::fs::remove_file(&output);
    }

    #[test]
    fn a_real_drop_before_a_pause_still_reaches_the_warning_after_it() {
        // Regression: resume() threw away what arrived during the pause by
        // clearing the ring, and the clear reset `dropped` — so an overflow that
        // happened for real earlier in the take was forgotten, and the
        // `audio-dropped` warning (main.rs) never fired for it. Pausing is the
        // only thing between the user and the only report that a recording lost
        // audio.
        let ring = Arc::new(AudioRing::new(1, 8, AUDIO_CHANNELS));
        let capacity = 1 * 8 * AUDIO_CHANNELS;

        let output = std::env::temp_dir().join("openscreen-capture-audio-pause-drop.mp4");
        let (mut capture, _) = Capture::start(
            &output,
            320,
            240,
            30,
            Some(1_000_000),
            Some(Backend::Software),
            vec![AudioSource { label: "system", ring: ring.clone(), gain: 1.0, bitrate: 128_000 }],
            None,
        )
        .expect("start");
        capture
            .stage(&frame(320, 240, shim::constants().video_format_bgrx))
            .expect("stage");

        // Mid-take: the encoder falls far enough behind that the ring overflows.
        ring.push_for_test(&vec![0.5; capacity * 3]);
        let dropped = ring.dropped_samples();
        assert!(dropped > 0, "the ring must have overflowed for this test to mean anything");

        capture.pause();
        // A long pause. Nothing that arrives during it belongs to the recording,
        // and none of it is the encoder falling behind either.
        ring.push_for_test(&vec![0.5; capacity * 10]);
        capture.resume();

        assert_eq!(
            capture.dropped_audio(),
            vec![("system", dropped)],
            "the pause must not spend the tally of a drop that happened before it"
        );
        let _ = std::fs::remove_file(&output);
    }

    #[test]
    fn microphone_gain_clamps_instead_of_wrapping() {
        // A boosted microphone that clips must clip flat. An out-of-range float
        // survives until AAC quantises it, and then wraps to the opposite
        // polarity — which sounds like a burst of noise, not like clipping.
        let ring = Arc::new(AudioRing::new(1, AUDIO_SAMPLE_RATE as usize, AUDIO_CHANNELS));
        ring.push_for_test(&[0.9, -0.9, 0.4, -0.4]);

        let output = std::env::temp_dir().join("openscreen-capture-gain.mp4");
        let (mut capture, _) = Capture::start(
            &output,
            320,
            240,
            30,
            Some(1_000_000),
            Some(Backend::Software),
            vec![AudioSource { label: "microphone", ring, gain: 4.0, bitrate: 128_000 }],
            None,
        )
        .expect("start");
        capture
            .stage(&frame(320, 240, shim::constants().video_format_bgrx))
            .expect("stage");

        // stage() cleared the pre-roll, so feed the samples the run will see.
        let mix = capture.audio.as_ref().expect("a mix exists");
        mix.inputs[0].ring.push_for_test(&[0.9, -0.9, 0.4, -0.4]);
        capture.advance().expect("advance");
        for sample in &capture.audio.as_ref().unwrap().scratch {
            assert!(
                (-1.0..=1.0).contains(sample),
                "gain produced {sample}, which is outside the representable range"
            );
        }
        let _ = std::fs::remove_file(&output);
    }

    #[test]
    fn two_captures_become_one_muxed_track() {
        // THE regression this guards. Two separate AAC tracks meant the preview
        // — an HTML5 <video>, which plays only the default track and cannot
        // switch — heard whichever came first. With system audio silent, that
        // was silence, while the microphone sat in a track nothing selects.
        let system = Arc::new(AudioRing::new(1, AUDIO_SAMPLE_RATE as usize, AUDIO_CHANNELS));
        let mic = Arc::new(AudioRing::new(1, AUDIO_SAMPLE_RATE as usize, AUDIO_CHANNELS));
        let output = std::env::temp_dir().join("openscreen-capture-one-track.mp4");
        let (mut capture, _) = Capture::start(
            &output,
            320,
            240,
            30,
            Some(1_000_000),
            Some(Backend::Software),
            vec![
                AudioSource { label: "system", ring: system.clone(), gain: 1.0, bitrate: 128_000 },
                AudioSource { label: "microphone", ring: mic.clone(), gain: 1.0, bitrate: 128_000 },
            ],
            None,
        )
        .expect("start");

        let mix = capture.audio.as_ref().expect("a mix exists");
        assert_eq!(mix.inputs.len(), 2, "both captures feed the mix");
        let track = mix.track;

        capture
            .stage(&frame(320, 240, shim::constants().video_format_bgrx))
            .expect("stage");
        // stage() cleared the pre-roll, so feed after it.
        system.push_for_test(&vec![0.25; 4096]);
        mic.push_for_test(&vec![0.5; 4096]);
        capture.advance().expect("advance");

        let mix = capture.audio.as_ref().unwrap();
        assert_eq!(mix.track, track, "there is exactly one audio track, and it never changes");
        // The mixed scratch must carry BOTH contributions summed, not one of them.
        assert!(
            mix.scratch.iter().any(|s| (*s - 0.75).abs() < 1e-4),
            "system 0.25 + mic 0.5 should sum to 0.75; got {:?}",
            &mix.scratch[..mix.scratch.len().min(4)]
        );

        let summary = capture.finish().expect("finish");
        assert!(summary.frames > 0);
        let _ = std::fs::remove_file(&output);
    }

    #[test]
    fn a_silent_input_cannot_freeze_the_track() {
        // A microphone unplugged mid-recording stops filling its ring. Mixing
        // strictly on min(available) would then wait for it forever and the
        // whole audio track would stop — including the system audio that is
        // still arriving. AUDIO_STARVE_SAMPLES is what breaks that deadlock.
        let system = Arc::new(AudioRing::new(2, AUDIO_SAMPLE_RATE as usize, AUDIO_CHANNELS));
        let dead = Arc::new(AudioRing::new(2, AUDIO_SAMPLE_RATE as usize, AUDIO_CHANNELS));
        let output = std::env::temp_dir().join("openscreen-capture-starve.mp4");
        let (mut capture, _) = Capture::start(
            &output,
            320,
            240,
            30,
            Some(1_000_000),
            Some(Backend::Software),
            vec![
                AudioSource { label: "system", ring: system.clone(), gain: 1.0, bitrate: 128_000 },
                AudioSource { label: "microphone", ring: dead, gain: 1.0, bitrate: 128_000 },
            ],
            None,
        )
        .expect("start");
        capture
            .stage(&frame(320, 240, shim::constants().video_format_bgrx))
            .expect("stage");

        // Well past the quarter-second slack, with the other input silent.
        system.push_for_test(&vec![0.4; AUDIO_STARVE_SAMPLES + 8192]);
        capture.advance().expect("advance");

        let mix = capture.audio.as_ref().unwrap();
        assert!(
            mix.inputs[0].pending.len() < AUDIO_STARVE_SAMPLES,
            "the live input should have been consumed, not held hostage: {} left",
            mix.inputs[0].pending.len()
        );
        let _ = std::fs::remove_file(&output);
    }

    #[test]
    fn a_long_stall_is_one_jump_not_a_burst_or_a_deleted_span() {
        // A stall (the loop starved under load) must not be paid back as an
        // unbounded catch-up burst that blocks `stop`, nor — the #511 bug — as a
        // deleted slice of the timeline. Wall-clock PTS represents it as a single
        // held frame whose PTS jumps to real time: one encode, honest duration.
        let output = std::env::temp_dir().join("openscreen-capture-catchup.mp4");
        let (mut capture, _) =
            Capture::start(&output, 320, 240, 60, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
                .expect("start");
        capture
            .stage(&frame(320, 240, shim::constants().video_format_bgrx))
            .expect("stage");

        // 500 ms at 60 fps is 30 slots due; a single advance writes ONE frame
        // stamped at the real index, not 30 duplicates.
        std::thread::sleep(Duration::from_millis(500));
        let written = capture.advance().expect("advance");
        assert_eq!(written, 1, "a stall is one time-stamped frame, not a burst");

        let summary = capture.finish().expect("finish");
        assert!(
            summary.duration_ms >= 480,
            "duration must track the ~500 ms elapsed, got {} ms",
            summary.duration_ms
        );
        assert!(
            summary.frames <= 3,
            "the stall must not be backfilled with duplicates, encoded {} frames",
            summary.frames
        );
        let _ = std::fs::remove_file(&output);
    }

    #[test]
    fn frames_arriving_while_paused_are_not_staged() {
        // A paused recording must not ingest new pixels. The compositor keeps
        // streaming while the app is paused, so frames still arrive; staging one
        // would move the held picture to post-pause content, which the tail write
        // in finish() could then encode when a stop follows a pause (#512). Pause
        // must hold that privacy boundary — the staged picture freezes.
        let output = std::env::temp_dir().join("openscreen-capture-pause-stage.mp4");
        let (mut capture, _) =
            Capture::start(&output, 320, 240, 30, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
                .expect("start");

        // Pause BEFORE any frame is staged, then a frame arrives during the pause.
        capture.pause();
        let staged = capture.stage(&frame(320, 240, shim::constants().video_format_bgrx));
        assert_eq!(
            staged.expect("staging while paused is a no-op, not an error"),
            StageOutcome::Frozen,
            "a frame arriving while paused is Frozen — not Staged (nothing staged) nor Dropped (nothing failed)",
        );
        assert!(!capture.started(), "a frame received while paused must not start the timeline");

        let summary = capture.finish().expect("finish");
        assert_eq!(summary.frames, 0, "nothing captured while paused may reach the file");
        let _ = std::fs::remove_file(&output);
    }

    #[test]
    fn finishing_while_paused_still_records_the_active_time_before_the_pause() {
        // Stop can arrive while paused — the user pauses, then decides to stop
        // without resuming. The active time between the last heartbeat and the
        // pause must still reach the timeline; dropping it would compress the
        // file and desync the screen from audio (#511), the same class of bug.
        // current_index() freezes at the pause boundary, so the tail write is
        // both safe and required while paused.
        let output = std::env::temp_dir().join("openscreen-capture-pause-finish.mp4");
        let (mut capture, _) =
            Capture::start(&output, 320, 240, 60, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
                .expect("start");
        capture
            .stage(&frame(320, 240, shim::constants().video_format_bgrx))
            .expect("stage");

        // ~200 ms of active time passes WITHOUT a heartbeat servicing it (loop
        // starved), then the user pauses and stops.
        std::thread::sleep(Duration::from_millis(200));
        capture.pause();
        let summary = capture.finish().expect("finish");

        assert!(
            summary.duration_ms >= 180,
            "the ~200 ms active before the pause must reach the timeline, got {} ms",
            summary.duration_ms
        );
        let skew = (summary.duration_ms as i64 - summary.wall_clock_ms as i64).abs();
        assert!(
            skew <= 60,
            "duration {} ms and wall-clock {} ms diverged by {} ms",
            summary.duration_ms, summary.wall_clock_ms, skew
        );
        let _ = std::fs::remove_file(&output);
    }

    #[test]
    fn sparse_wakeups_do_not_compress_the_timeline() {
        // THE regression guard for #511. advance() is serviced only a couple of
        // times, far less often than the frame rate, as if the event loop were
        // starved under load. The old frame-index PTS produced a file shorter
        // than real time (55.2 s for 61 s in the field report); wall-clock PTS
        // keeps duration ~= elapsed, and the wall-clock telemetry agrees with it.
        let output = std::env::temp_dir().join("openscreen-capture-sparse.mp4");
        let (mut capture, _) =
            Capture::start(&output, 320, 240, 60, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
                .expect("start");
        capture
            .stage(&frame(320, 240, shim::constants().video_format_bgrx))
            .expect("stage");

        std::thread::sleep(Duration::from_millis(200));
        capture.advance().expect("advance");
        std::thread::sleep(Duration::from_millis(200));
        capture.advance().expect("advance");

        let summary = capture.finish().expect("finish");
        // ~400 ms of real time, honoured despite only a couple of encoded frames.
        assert!(
            summary.duration_ms >= 360,
            "the timeline compressed: {} ms for ~400 ms of capture",
            summary.duration_ms
        );
        // Duration and measured wall-clock must agree within a small epsilon —
        // the invariant the `timeline-divergence` warning (main.rs) watches.
        let skew = (summary.duration_ms as i64 - summary.wall_clock_ms as i64).abs();
        assert!(
            skew <= 60,
            "duration {} ms and wall-clock {} ms diverged by {} ms",
            summary.duration_ms, summary.wall_clock_ms, skew
        );
        // Variable-rate, not a duplicate burst: far fewer than 400 ms × 60 fps.
        assert!(summary.frames < 10, "expected a handful of held frames, got {}", summary.frames);
        let _ = std::fs::remove_file(&output);
    }
}