Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

21.1 KB
Raw Blame
//! Main-thread test pattern for the A/V sync self-test.
//!
//! Renders a fullscreen black window that flashes white at a fixed period
//! while playing a 1 kHz beep through the default audio output at the same
//! scheduled instants. The window must run on the process main thread
//! (required by AppKit); the async side of the self-test requests a pattern
//! run through [`request_pattern`] and the real main thread services it via
//! [`serve_main_thread`].

use std::{
    num::NonZeroU32,
    sync::{
        Arc, Mutex, OnceLock,
        atomic::{AtomicBool, Ordering},
        mpsc,
    },
    time::{Duration, Instant},
};

use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
use winit::{
    application::ApplicationHandler,
    event::{ElementState, WindowEvent},
    event_loop::{ActiveEventLoop, ControlFlow, EventLoop},
    keyboard::{Key, NamedKey},
    platform::run_on_demand::EventLoopExtRunOnDemand,
    window::{Fullscreen, Window, WindowId, WindowLevel},
};

#[derive(Clone, Copy, Debug)]
pub struct PatternSpec {
    /// Time to sit black before the first event, letting capture settle.
    pub settle: Duration,
    /// Number of flash+beep events.
    pub events: u32,
    /// Time between event onsets.
    pub period: Duration,
    /// Duration of each flash / beep.
    pub flash_len: Duration,
}

impl PatternSpec {
    pub fn total_runtime(&self) -> Duration {
        self.settle + self.period * self.events + Duration::from_millis(500)
    }

    /// Event onsets relative to the pattern epoch. Nominally periodic, with a
    /// deterministic per-event jitter of up to ±300 ms: a perfectly periodic
    /// schedule would let an A/V shift of exactly one period pair every flash
    /// with the wrong beep and alias to a zero measured offset.
    pub fn event_offsets_secs(&self) -> Vec<f64> {
        (0..self.events)
            .map(|k| {
                let jitter = (u64::from(k).wrapping_mul(2_654_435_761) % 601) as f64 / 1000.0 - 0.3;
                (f64::from(k) * self.period.as_secs_f64() + jitter).max(0.0)
            })
            .collect()
    }
}

#[derive(Debug)]
pub struct PatternReport {
    /// Instants at which each flash was actually presented (post-present).
    pub flash_presents: Vec<(u32, Instant)>,
    /// Estimated instants at which each beep hit the output (DAC time).
    pub beep_outputs: Vec<(u32, Instant)>,
    /// Mean reported output latency of the audio stream, if available.
    pub audio_latency_ms: Option<f64>,
}

pub struct PatternRequest {
    pub spec: PatternSpec,
    pub reply: mpsc::Sender<Result<PatternReport, String>>,
}

static PATTERN_TX: OnceLock<Mutex<Option<mpsc::Sender<PatternRequest>>>> = OnceLock::new();

/// Called from `main()` before the runtime thread spawns, when the parsed
/// command is a self-test. Returns the receiver the main thread must serve.
pub fn install_main_thread_runner() -> mpsc::Receiver<PatternRequest> {
    let (tx, rx) = mpsc::channel();
    let _ = PATTERN_TX.set(Mutex::new(Some(tx)));
    rx
}

/// Called by the runtime thread once the command finishes, releasing the main
/// thread from its serve loop.
pub fn shutdown_main_thread_runner() {
    if let Some(slot) = PATTERN_TX.get() {
        slot.lock().unwrap().take();
    }
}

/// Runs pattern requests on the main thread until the sender is dropped via
/// [`shutdown_main_thread_runner`].
///
/// The event loop is built once and reused: winit allows exactly one
/// `EventLoop` per process, so a second `--mode both` leg would otherwise fail
/// with `RecreationAttempt`. `run_app_on_demand` exists for exactly this.
pub fn serve_main_thread(rx: mpsc::Receiver<PatternRequest>) {
    let mut event_loop: Option<EventLoop<()>> = None;

    while let Ok(request) = rx.recv() {
        let result = match event_loop_for(&mut event_loop) {
            Ok(event_loop) => run_pattern(event_loop, request.spec),
            Err(e) => Err(e),
        };
        let _ = request.reply.send(result);
    }
}

fn event_loop_for(slot: &mut Option<EventLoop<()>>) -> Result<&mut EventLoop<()>, String> {
    if slot.is_none() {
        #[allow(unused_mut)]
        let mut builder = EventLoop::builder();
        #[cfg(target_os = "macos")]
        {
            use winit::platform::macos::{ActivationPolicy, EventLoopBuilderExtMacOS};
            builder
                .with_activation_policy(ActivationPolicy::Regular)
                .with_activate_ignoring_other_apps(true);
        }
        *slot = Some(
            builder
                .build()
                .map_err(|e| format!("failed to create event loop: {e}"))?,
        );
    }

    Ok(slot.as_mut().expect("event loop was just created"))
}

/// Called from the async side; blocks the calling task until the pattern
/// window has run to completion on the main thread.
pub async fn request_pattern(spec: PatternSpec) -> Result<PatternReport, String> {
    let tx = PATTERN_TX
        .get()
        .and_then(|slot| slot.lock().unwrap().clone())
        .ok_or("self-test pattern runner is not installed on the main thread")?;
    tokio::task::spawn_blocking(move || {
        let (reply_tx, reply_rx) = mpsc::channel();
        tx.send(PatternRequest {
            spec,
            reply: reply_tx,
        })
        .map_err(|_| "main thread pattern runner is gone".to_string())?;
        reply_rx
            .recv()
            .map_err(|_| "main thread pattern runner dropped the request".to_string())?
    })
    .await
    .map_err(|e| format!("pattern task join error: {e}"))?
}

struct BeepState {
    epoch: Instant,
    /// Sorted (start, end) sample windows of each beep, relative to epoch.
    event_windows: Vec<(u64, u64)>,
    sample_rate: u32,
    channels: usize,
    /// Absolute sample index of pattern epoch, fixed on the first callback.
    epoch_sample: Mutex<Option<i64>>,
    samples_written: Mutex<u64>,
    beep_outputs: Mutex<Vec<(u32, Instant)>>,
    latency_sum_ms: Mutex<(f64, u64)>,
}

impl BeepState {
    fn fill(&self, data: &mut [f32], info: &cpal::OutputCallbackInfo) {
        let now = Instant::now();
        let mut written = self.samples_written.lock().unwrap();
        let buffer_start_sample = *written as i64;

        let mut epoch_sample = self.epoch_sample.lock().unwrap();
        let epoch_sample = *epoch_sample.get_or_insert_with(|| {
            let until_epoch = if self.epoch > now {
                (self.epoch - now).as_secs_f64()
            } else {
                -(now - self.epoch).as_secs_f64()
            };
            buffer_start_sample + (until_epoch * self.sample_rate as f64) as i64
        });

        let latency = info
            .timestamp()
            .playback
            .duration_since(&info.timestamp().callback);
        if let Some(latency) = latency {
            let mut acc = self.latency_sum_ms.lock().unwrap();
            acc.0 += latency.as_secs_f64() * 1000.0;
            acc.1 += 1;
        }

        let frames = data.len() / self.channels.max(1);
        for frame_idx in 0..frames {
            let abs_sample = buffer_start_sample + frame_idx as i64;
            let rel = abs_sample - epoch_sample;
            let mut value = 0.0f32;
            if rel >= 0 {
                let rel = rel as u64;
                let idx = self
                    .event_windows
                    .partition_point(|&(start, _)| start <= rel);
                if idx > 0 {
                    let (start, end) = self.event_windows[idx - 1];
                    if rel < end {
                        // 1 kHz tone with a 2 ms fade-in/out to avoid clicks while
                        // keeping the onset sharp for detection.
                        let within = rel - start;
                        let t = within as f32 / self.sample_rate as f32;
                        let fade_len = 0.002 * self.sample_rate as f32;
                        let fade_in = (within as f32 / fade_len).min(1.0);
                        let remaining = (end - rel) as f32;
                        let fade_out = (remaining / fade_len).min(1.0);
                        value = 0.4
                            * fade_in
                            * fade_out
                            * (t * 1000.0 * 2.0 * std::f32::consts::PI).sin();

                        if within == 0 {
                            let dac = now
                                + latency.unwrap_or_default()
                                + Duration::from_secs_f64(
                                    frame_idx as f64 / self.sample_rate as f64,
                                );
                            self.beep_outputs
                                .lock()
                                .unwrap()
                                .push(((idx - 1) as u32, dac));
                        }
                    }
                }
            }
            for ch in 0..self.channels {
                data[frame_idx * self.channels + ch] = value;
            }
        }

        *written += frames as u64;
    }
}

fn build_beep_stream(
    epoch: Instant,
    spec: &PatternSpec,
) -> Result<(cpal::Stream, Arc<BeepState>), String> {
    let host = cpal::default_host();
    let device = host
        .default_output_device()
        .ok_or("no default audio output device; cannot run the sync test")?;
    let config = device
        .default_output_config()
        .map_err(|e| format!("failed to query audio output config: {e}"))?;

    let sample_rate = config.sample_rate().0;
    let channels = config.channels() as usize;
    let beep_samples = (spec.flash_len.as_secs_f64() * sample_rate as f64) as u64;
    let state = Arc::new(BeepState {
        epoch,
        event_windows: spec
            .event_offsets_secs()
            .into_iter()
            .map(|offset| {
                let start = (offset * sample_rate as f64) as u64;
                (start, start + beep_samples)
            })
            .collect(),
        sample_rate,
        channels,
        epoch_sample: Mutex::new(None),
        samples_written: Mutex::new(0),
        beep_outputs: Mutex::new(Vec::new()),
        latency_sum_ms: Mutex::new((0.0, 0)),
    });

    let err_fn = |e| tracing::warn!("selftest audio stream error: {e}");
    let stream_config = config.config();

    let stream = match config.sample_format() {
        cpal::SampleFormat::F32 => {
            let state = state.clone();
            device
                .build_output_stream(
                    &stream_config,
                    move |data: &mut [f32], info: &cpal::OutputCallbackInfo| {
                        state.fill(data, info);
                    },
                    err_fn,
                    None,
                )
                .map_err(|e| format!("failed to build audio output stream: {e}"))?
        }
        cpal::SampleFormat::I16 => {
            let state = state.clone();
            let mut scratch = Vec::new();
            device
                .build_output_stream(
                    &stream_config,
                    move |data: &mut [i16], info: &cpal::OutputCallbackInfo| {
                        scratch.clear();
                        scratch.resize(data.len(), 0.0f32);
                        state.fill(&mut scratch, info);
                        for (dst, src) in data.iter_mut().zip(&scratch) {
                            *dst = (src * f32::from(i16::MAX)) as i16;
                        }
                    },
                    err_fn,
                    None,
                )
                .map_err(|e| format!("failed to build audio output stream: {e}"))?
        }
        other => {
            return Err(format!(
                "unsupported audio output sample format for the sync test: {other:?}"
            ));
        }
    };

    Ok((stream, state))
}

struct PatternApp {
    spec: PatternSpec,
    /// Event onsets in seconds from epoch, from `PatternSpec::event_offsets_secs`.
    event_offsets: Vec<f64>,
    run_start: Instant,
    epoch: Instant,
    window: Option<Arc<Window>>,
    surface: Option<softbuffer::Surface<Arc<Window>, Arc<Window>>>,
    size: (u32, u32),
    last_drawn_white: bool,
    flash_presents: Vec<(u32, Instant)>,
    aborted: Arc<AtomicBool>,
    error: Option<String>,
}

impl PatternApp {
    /// Returns whether the pattern should currently show white, and the event
    /// index if so.
    fn desired_state(&self, now: Instant) -> Option<u32> {
        if now < self.epoch {
            return None;
        }
        let rel = (now - self.epoch).as_secs_f64();
        let flash = self.spec.flash_len.as_secs_f64();
        self.event_offsets
            .iter()
            .position(|&start| rel >= start && rel < start + flash)
            .map(|idx| idx as u32)
    }

    fn next_transition(&self, now: Instant) -> Instant {
        if now < self.epoch {
            return self.epoch;
        }
        let rel = (now - self.epoch).as_secs_f64();
        let flash = self.spec.flash_len.as_secs_f64();
        let next_rel = self
            .event_offsets
            .iter()
            .flat_map(|&start| [start, start + flash])
            .filter(|&boundary| boundary > rel)
            .fold(f64::INFINITY, f64::min);
        if next_rel.is_finite() {
            self.epoch + Duration::from_secs_f64(next_rel)
        } else {
            self.done_at()
        }
    }

    fn done_at(&self) -> Instant {
        self.run_start + self.spec.total_runtime()
    }

    fn draw(&mut self, event_loop: &ActiveEventLoop) {
        let now = Instant::now();
        let desired = self.desired_state(now);
        let white = desired.is_some();

        let Some(surface) = self.surface.as_mut() else {
            return;
        };
        let (w, h) = self.size;
        if w == 0 || h == 0 {
            return;
        }
        if surface
            .resize(NonZeroU32::new(w).unwrap(), NonZeroU32::new(h).unwrap())
            .is_err()
        {
            return;
        }
        let Ok(mut buffer) = surface.buffer_mut() else {
            return;
        };
        // Keep the high byte opaque: some softbuffer backends (macOS layers)
        // treat it as alpha rather than ignoring it.
        let color: u32 = if white { 0xFFFF_FFFF } else { 0xFF00_0000 };
        buffer.fill(color);
        let presented = buffer.present().is_ok();

        if presented && white && !self.last_drawn_white {
            let event = desired.unwrap_or(0);
            if self
                .flash_presents
                .last()
                .is_none_or(|(last, _)| *last != event)
            {
                self.flash_presents.push((event, Instant::now()));
            }
        }
        self.last_drawn_white = white;

        if Instant::now() >= self.done_at() {
            event_loop.exit();
        }
    }
}

impl ApplicationHandler for PatternApp {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        if self.window.is_some() {
            return;
        }
        // The self-test records the primary display, so the pattern has to
        // land there: on a multi-monitor desk `Borderless(None)` picks the
        // window's current monitor, which can be a screen nothing is
        // recording (measured as zero flashes).
        let monitor = event_loop.primary_monitor();
        let attrs = Window::default_attributes()
            .with_title("Cap Sync Test")
            .with_fullscreen(Some(Fullscreen::Borderless(monitor)))
            .with_window_level(WindowLevel::AlwaysOnTop);
        let window = match event_loop.create_window(attrs) {
            Ok(w) => Arc::new(w),
            Err(e) => {
                self.error = Some(format!("failed to create test window: {e}"));
                event_loop.exit();
                return;
            }
        };
        let size = window.inner_size();
        self.size = (size.width, size.height);

        let context = match softbuffer::Context::new(window.clone()) {
            Ok(c) => c,
            Err(e) => {
                self.error = Some(format!("failed to create draw context: {e}"));
                event_loop.exit();
                return;
            }
        };
        match softbuffer::Surface::new(&context, window.clone()) {
            Ok(s) => self.surface = Some(s),
            Err(e) => {
                self.error = Some(format!("failed to create draw surface: {e}"));
                event_loop.exit();
                return;
            }
        }
        window.request_redraw();
        self.window = Some(window);
    }

    fn window_event(&mut self, event_loop: &ActiveEventLoop, _id: WindowId, event: WindowEvent) {
        match event {
            WindowEvent::CloseRequested => {
                self.aborted.store(true, Ordering::Release);
                event_loop.exit();
            }
            WindowEvent::KeyboardInput { event, .. } => {
                if event.state == ElementState::Pressed
                    && event.logical_key == Key::Named(NamedKey::Escape)
                {
                    self.aborted.store(true, Ordering::Release);
                    event_loop.exit();
                }
            }
            WindowEvent::Resized(size) => {
                self.size = (size.width, size.height);
            }
            WindowEvent::RedrawRequested => {
                self.draw(event_loop);
            }
            _ => {}
        }
    }

    fn about_to_wait(&mut self, event_loop: &ActiveEventLoop) {
        let now = Instant::now();
        if now >= self.done_at() {
            event_loop.exit();
            return;
        }
        let next = self.next_transition(now).min(self.done_at());
        if let Some(window) = &self.window {
            // Redraw slightly eagerly so the flip lands at (not after) the
            // scheduled transition.
            window.request_redraw();
        }
        event_loop.set_control_flow(ControlFlow::WaitUntil(next));
    }
}

/// How long the loop may keep turning after the pattern window is gone.
const TEARDOWN_BUDGET: Duration = Duration::from_millis(750);

/// Runs the loop for a brief, bounded moment after the pattern window has been
/// dropped.
///
/// The fullscreen pattern window lives in a real macOS Space (winit's
/// `Fullscreen::Borderless` is `toggleFullScreen:`), and leaving that Space is
/// animated: it needs run-loop turns to finish. Without this the loop stops
/// turning the instant `run_pattern` returns -- the main thread goes straight
/// back to blocking on its request channel -- so the black always-on-top window
/// can still be up over the next leg's recording.
///
/// Deliberately not `pump_app_events`: after `run_app_on_demand` returns, the
/// loop's exit flag is still set and only `run_on_demand` clears it, so a pump
/// would dispatch init events and exit again without ever turning the loop.
/// Running the loop with a handler that cannot create a window is the mechanism
/// that actually works. It creates nothing and exits on a deadline, so it
/// cannot hang and it cannot bring a second window up.
struct TeardownApp {
    deadline: Instant,
}

impl ApplicationHandler for TeardownApp {
    /// Empty by design: nothing in this handler may create a window.
    fn resumed(&mut self, _event_loop: &ActiveEventLoop) {}

    fn window_event(&mut self, _: &ActiveEventLoop, _: WindowId, _: WindowEvent) {}

    fn about_to_wait(&mut self, event_loop: &ActiveEventLoop) {
        if Instant::now() >= self.deadline {
            event_loop.exit();
            return;
        }
        event_loop.set_control_flow(ControlFlow::WaitUntil(self.deadline));
    }
}

fn drain_after_window_close(event_loop: &mut EventLoop<()>) {
    let mut teardown = TeardownApp {
        deadline: Instant::now() + TEARDOWN_BUDGET,
    };
    if let Err(e) = event_loop.run_app_on_demand(&mut teardown) {
        tracing::warn!("selftest pattern teardown: {e}");
    }
}

fn run_pattern(event_loop: &mut EventLoop<()>, spec: PatternSpec) -> Result<PatternReport, String> {
    let run_start = Instant::now();
    let epoch = run_start + spec.settle;

    let (stream, beep_state) = build_beep_stream(epoch, &spec)?;
    stream
        .play()
        .map_err(|e| format!("failed to start audio output: {e}"))?;

    let mut app = PatternApp {
        event_offsets: spec.event_offsets_secs(),
        spec,
        run_start,
        epoch,
        window: None,
        surface: None,
        size: (0, 0),
        last_drawn_white: false,
        flash_presents: Vec::new(),
        aborted: Arc::new(AtomicBool::new(false)),
        error: None,
    };

    let run_result = event_loop
        .run_app_on_demand(&mut app)
        .map_err(|e| format!("event loop error: {e}"));

    drop(stream);

    // Dropping the surface and then the window is what asks AppKit to leave the
    // fullscreen Space; the drain gives it the run-loop turns to finish before
    // the main thread parks on its request channel again.
    app.surface = None;
    app.window = None;
    drain_after_window_close(event_loop);

    run_result?;

    if let Some(error) = app.error {
        return Err(error);
    }
    if app.aborted.load(Ordering::Acquire) {
        return Err("cancelled".to_string());
    }

    let latency = {
        let acc = beep_state.latency_sum_ms.lock().unwrap();
        (acc.1 > 0).then(|| acc.0 / acc.1 as f64)
    };
    let beep_outputs = beep_state.beep_outputs.lock().unwrap().clone();

    Ok(PatternReport {
        flash_presents: app.flash_presents,
        beep_outputs,
        audio_latency_ms: latency,
    })
}