Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

64.4 KB
Raw Blame
//! Persistent audio output for editor playback.
//!
//! One cpal output stream per editor session, playing silence while paused.
//! Pressing play installs a source into the live callback instead of opening
//! a new device stream per press — the device (Bluetooth included) is already
//! awake, so audio starts within one callback period of the playback clock
//! rather than after a device wake that could take seconds. The stream is
//! rebuilt only when the default output device changes or the stream errors.
//!
//! On the built-in output, which restarts instantly, a stream left without a
//! source for [`IDLE_PAUSE_AFTER`] is paused rather than rendering silence
//! indefinitely, and the next play or prewarm restarts it in place. External,
//! wireless and display outputs keep running.

use std::{
    sync::{
        Arc, Mutex, OnceLock,
        atomic::{AtomicBool, AtomicU64, Ordering},
        mpsc as std_mpsc,
    },
    time::{Duration, Instant},
};

use cap_audio::{AudioData, FromSampleBytes};
#[cfg(not(target_os = "windows"))]
use cap_audio::{LatencyCorrectionConfig, LatencyCorrector, default_output_latency_hint};
use cap_media_info::AudioInfo;
use cap_project::ProjectConfiguration;
use cpal::{
    SampleFormat,
    traits::{DeviceTrait, HostTrait, StreamTrait},
};
use tokio::sync::watch;
use tracing::{error, info};

use crate::audio::{AudioSegment, MusicTracks, PlaybackAudioCache, PrerenderedAudioBuffer};
use crate::preparing_audio::{
    PreparingAudioBuffer, PreparingAudioOutputHandle, PreparingAudioOutputSnapshot,
    PreparingAudioSources,
};

/// How long to wait for the live callback to acknowledge a newly installed
/// source before reporting "no audio". A running stream acknowledges within
/// one callback period; this bound only matters when the device dies at the
/// exact moment of install.
const SOURCE_ACK_TIMEOUT: Duration = Duration::from_secs(5);
/// Deadline for a whole play request (stream build + pre-render window + ack).
/// Freshly opened devices on slow transports (e.g. Bluetooth) can take
/// several seconds for their first callback.
const PLAY_REQUEST_TIMEOUT: Duration = Duration::from_secs(15);
/// Bound on waiting for the initial pre-render window (normally a few ms).
const PRERENDER_READY_TIMEOUT: Duration = Duration::from_secs(2);
/// How long a stream may render silence before it is paused. Long enough to
/// cover the pauses of an active editing session, so play-pause-play stays on
/// the already running stream.
const IDLE_PAUSE_AFTER: Duration = Duration::from_secs(15);

pub struct PlaySpec {
    pub segments: Vec<AudioSegment>,
    pub music: MusicTracks,
    pub project: ProjectConfiguration,
    pub duration_secs: f64,
    pub start_playhead_secs: f64,
    pub playhead_rx: watch::Receiver<f64>,
}

enum ControlMsg {
    Refresh {
        spec: Box<PlaySpec>,
        generation: u64,
        revision: u64,
        retire_tx: std_mpsc::Sender<ControlMsg>,
    },
    Retire(Box<dyn Send>),
    Realign(Box<dyn FnOnce() + Send>),
    EnsureStream,
    HoldAwake,
    ReleaseAwake,
    Play {
        spec: Box<PlaySpec>,
        generation: u64,
        result_tx: std_mpsc::Sender<bool>,
    },
    PreparePlayback {
        spec: Box<PlaySpec>,
        generation: u64,
        request: Arc<PreparingAudioRequest>,
    },
    PrepareProgressivePlayback {
        sources: PreparingAudioSources,
        start_seconds: f64,
        generation: u64,
        installation: PreparingAudioInstallation,
    },
    StopPlayback {
        generation: u64,
    },
    Shutdown,
}

#[derive(Clone, Copy, PartialEq, Eq)]
enum PreparingAudioStatus {
    Pending,
    AwaitingCallback,
    Started,
    Unavailable,
    Cancelled,
}

struct PreparingAudioRequest {
    cancelled: AtomicBool,
    started: AtomicBool,
    deadline: Instant,
    ack_deadline: OnceLock<Instant>,
    status: watch::Sender<PreparingAudioStatus>,
    output: Mutex<Option<PreparingAudioOutputHandle>>,
    installed: watch::Sender<bool>,
}

impl PreparingAudioRequest {
    fn new(timeout: Duration) -> Self {
        Self {
            cancelled: AtomicBool::new(false),
            started: AtomicBool::new(false),
            deadline: Instant::now() + timeout,
            ack_deadline: OnceLock::new(),
            status: watch::channel(PreparingAudioStatus::Pending).0,
            output: Mutex::new(None),
            installed: watch::channel(true).0,
        }
    }

    fn is_cancelled(&self) -> bool {
        self.cancelled.load(Ordering::Acquire)
            || (!self.started.load(Ordering::Acquire) && Instant::now() >= self.deadline())
    }

    fn deadline(&self) -> Instant {
        self.ack_deadline.get().copied().unwrap_or(self.deadline)
    }

    fn awaiting_callback(&self) {
        let _ = self
            .ack_deadline
            .set(self.deadline.min(Instant::now() + SOURCE_ACK_TIMEOUT));
        self.status.send_if_modified(|status| {
            if *status != PreparingAudioStatus::Pending {
                return false;
            }
            *status = PreparingAudioStatus::AwaitingCallback;
            true
        });
    }

    fn cancel(&self) {
        self.cancelled.store(true, Ordering::Release);
        if let Some(output) = self
            .output
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .as_ref()
        {
            output.cancel();
        }
        self.status.send_replace(PreparingAudioStatus::Cancelled);
    }

    fn complete(&self, started: bool) {
        self.status.send_if_modified(|status| {
            if !matches!(
                status,
                PreparingAudioStatus::Pending | PreparingAudioStatus::AwaitingCallback
            ) {
                return false;
            }
            *status = if self.is_cancelled() {
                PreparingAudioStatus::Cancelled
            } else if started {
                self.started.store(true, Ordering::Release);
                PreparingAudioStatus::Started
            } else {
                self.cancelled.store(true, Ordering::Release);
                PreparingAudioStatus::Unavailable
            };
            true
        });
    }
}

struct PreparingAudioInstallation {
    request: Arc<PreparingAudioRequest>,
    runtime: tokio::runtime::Handle,
    playable_until: f64,
}

impl Drop for PreparingAudioInstallation {
    fn drop(&mut self) {
        self.request.installed.send_replace(true);
    }
}

pub(crate) struct PreparingAudioPlayTicket {
    generation: u64,
    request: Arc<PreparingAudioRequest>,
    control_tx: std_mpsc::Sender<ControlMsg>,
}

impl PreparingAudioPlayTicket {
    pub(crate) fn generation(&self) -> u64 {
        self.generation
    }

    pub(crate) fn output_handle(&self) -> Option<PreparingAudioOutputHandle> {
        self.request
            .output
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .clone()
    }

    pub(crate) fn set_playable_until(&self, seconds: f64) -> Result<(), String> {
        if let Some(output) = self
            .request
            .output
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .as_ref()
        {
            output.set_playable_until(seconds)?;
        }
        Ok(())
    }

    pub(crate) fn output_status(&self, now: Instant) -> Option<PreparingAudioOutputSnapshot> {
        self.request
            .output
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .as_ref()
            .map(|output| output.status(now))
    }

    pub(crate) async fn stop_and_wait(&self) -> Result<(), String> {
        self.cancel();
        let mut installed = self.request.installed.subscribe();
        tokio::time::timeout(PLAY_REQUEST_TIMEOUT, async {
            while !*installed.borrow_and_update() {
                installed
                    .changed()
                    .await
                    .map_err(|_| "Preparing audio installation owner ended".to_string())?;
            }
            Ok::<_, String>(())
        })
        .await
        .map_err(|_| "Preparing audio installation cleanup timed out".to_string())??;
        let output = self
            .request
            .output
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .clone();
        if let Some(output) = output {
            tokio::time::timeout(PLAY_REQUEST_TIMEOUT, output.stop_and_wait())
                .await
                .map_err(|_| "Preparing audio source cleanup timed out".to_string())??;
        }
        Ok(())
    }

    pub(crate) async fn wait_started(&self) -> bool {
        let mut status = self.request.status.subscribe();
        loop {
            let current = *status.borrow_and_update();
            match current {
                PreparingAudioStatus::Started if !self.request.is_cancelled() => return true,
                PreparingAudioStatus::Pending | PreparingAudioStatus::AwaitingCallback => {}
                _ => {
                    self.cancel();
                    return false;
                }
            }
            if !matches!(
                tokio::time::timeout_at(self.request.deadline().into(), status.changed()).await,
                Ok(Ok(()))
            ) {
                self.cancel();
                return false;
            }
        }
    }

    pub(crate) fn cancel(&self) {
        self.request.cancel();
        let _ = self.control_tx.send(ControlMsg::StopPlayback {
            generation: self.generation,
        });
    }
}

impl Drop for PreparingAudioPlayTicket {
    fn drop(&mut self) {
        self.cancel();
    }
}

enum SourceAcknowledgement {
    Refresh(std_mpsc::Sender<ControlMsg>, u64),
    Ordinary(std_mpsc::Sender<()>),
    Preparing(Arc<PreparingAudioRequest>),
}

impl SourceAcknowledgement {
    fn preparing_request(&self) -> Option<Arc<PreparingAudioRequest>> {
        match self {
            Self::Ordinary(_) | Self::Refresh(..) => None,
            Self::Preparing(request) => Some(request.clone()),
        }
    }

    fn consumed(self) {
        match &self {
            Self::Refresh(..) => {}
            Self::Ordinary(sender) => {
                let _ = sender.send(());
            }
            Self::Preparing(request) => request.complete(true),
        }
    }
}

impl Drop for SourceAcknowledgement {
    fn drop(&mut self) {
        if let Self::Preparing(request) = self {
            request.complete(false);
        }
    }
}

/// Handle to the editor session's shared audio output. Owned by the editor
/// instance; playback sessions attach and detach sources through it.
pub struct AudioOutput {
    control_tx: std_mpsc::Sender<ControlMsg>,
    next_generation: AtomicU64,
}

impl Default for AudioOutput {
    fn default() -> Self {
        Self::new()
    }
}

/// Sample rate of the headless sink; matches the pipeline's master clock.
pub const HEADLESS_SAMPLE_RATE: u32 = 48_000;
/// Channel count of the headless sink.
pub const HEADLESS_CHANNELS: u16 = 2;
/// Frames per pulled block in the headless sink (a typical device period).
pub const HEADLESS_BLOCK_FRAMES: usize = 512;

/// Receives every interleaved f32 block the headless sink pulls, together
/// with the deadline at which a real output device would start playing the
/// block's first sample.
pub type HeadlessAudioTap = Box<dyn FnMut(&[f32], Instant) + Send>;

impl AudioOutput {
    pub fn new() -> Self {
        let (control_tx, control_rx) = std_mpsc::channel();

        if let Err(e) = std::thread::Builder::new()
            .name("cap-audio-output".into())
            .spawn(move || control_thread(control_rx))
        {
            // Sends will fail and playback degrades to video-only, matching
            // the behaviour when no output device exists.
            error!("Failed to spawn audio output thread: {e}");
        }

        Self {
            control_tx,
            next_generation: AtomicU64::new(0),
        }
    }

    /// An output that renders into `tap` instead of a device, pulling blocks
    /// on a real-time schedule the way a sound card would. Runs the exact
    /// production source pipeline (pre-render buffer, playhead sync policy),
    /// so sync harnesses can observe what a device would have played without
    /// needing audio hardware.
    pub fn new_headless(tap: HeadlessAudioTap) -> Self {
        let (control_tx, control_rx) = std_mpsc::channel();

        if let Err(e) = std::thread::Builder::new()
            .name("cap-audio-headless".into())
            .spawn(move || control_thread_headless(control_rx, tap))
        {
            error!("Failed to spawn headless audio output thread: {e}");
        }

        Self {
            control_tx,
            next_generation: AtomicU64::new(0),
        }
    }

    /// Opens (or restarts an idle-paused) output stream ahead of the first
    /// play so even the first press doesn't wait on the device (Bluetooth
    /// wake, etc.). Non-blocking.
    pub fn prewarm(&self) {
        let _ = self.control_tx.send(ControlMsg::EnsureStream);
    }

    /// Opens the output stream and keeps it running, never idle-paused, until
    /// the returned hold is dropped. For playback paths that start audio
    /// without a warmup to hide a stream restart behind.
    pub(crate) fn hold_awake(&self) -> AudioOutputAwakeHold {
        let _ = self.control_tx.send(ControlMsg::HoldAwake);
        AudioOutputAwakeHold {
            control_tx: self.control_tx.clone(),
        }
    }

    /// Starts playing `spec` on the shared stream. Blocks until the live
    /// callback acknowledges that it is consuming the source, so the caller
    /// can start the playback clock knowing audio is audible. Returns a
    /// generation token for [`AudioOutput::stop_playback`], or `None` when
    /// audio output isn't available (playback then runs video-only).
    pub fn play(&self, spec: PlaySpec) -> Option<u64> {
        let generation = self.next_generation.fetch_add(1, Ordering::Relaxed);
        let (result_tx, result_rx) = std_mpsc::channel();

        self.control_tx
            .send(ControlMsg::Play {
                spec: Box::new(spec),
                generation,
                result_tx,
            })
            .ok()?;

        match result_rx.recv_timeout(PLAY_REQUEST_TIMEOUT) {
            Ok(true) => Some(generation),
            Ok(false) => None,
            Err(_) => {
                error!("Audio play request timed out");
                None
            }
        }
    }

    pub(crate) fn prepare_playback(&self, spec: PlaySpec) -> PreparingAudioPlayTicket {
        let generation = self.next_generation.fetch_add(1, Ordering::Relaxed);
        let request = Arc::new(PreparingAudioRequest::new(PLAY_REQUEST_TIMEOUT));
        let ticket = PreparingAudioPlayTicket {
            generation,
            request: request.clone(),
            control_tx: self.control_tx.clone(),
        };
        if self
            .control_tx
            .send(ControlMsg::PreparePlayback {
                spec: Box::new(spec),
                generation,
                request: request.clone(),
            })
            .is_err()
        {
            request.complete(false);
        }
        ticket
    }

    pub(crate) fn prepare_progressive_playback(
        &self,
        sources: PreparingAudioSources,
        start_seconds: f64,
        playable_until: f64,
    ) -> PreparingAudioPlayTicket {
        let generation = self.next_generation.fetch_add(1, Ordering::Relaxed);
        let request = Arc::new(PreparingAudioRequest::new(PLAY_REQUEST_TIMEOUT));
        request.installed.send_replace(false);
        let ticket = PreparingAudioPlayTicket {
            generation,
            request: request.clone(),
            control_tx: self.control_tx.clone(),
        };
        let command = ControlMsg::PrepareProgressivePlayback {
            sources,
            start_seconds,
            generation,
            installation: PreparingAudioInstallation {
                request: request.clone(),
                runtime: tokio::runtime::Handle::current(),
                playable_until,
            },
        };
        if self.control_tx.send(command).is_err() {
            request.complete(false);
        }
        ticket
    }

    pub(crate) fn refresh_playback(&self, spec: PlaySpec, generation: u64) {
        let _ = self.control_tx.send(ControlMsg::Refresh {
            spec: Box::new(spec),
            generation,
            revision: self.next_generation.fetch_add(1, Ordering::Relaxed),
            retire_tx: self.control_tx.clone(),
        });
    }

    /// Detaches the source installed by the `play` call that returned this
    /// generation. A newer source (from a replacing play) is left untouched,
    /// so a stale playback shutting down can't cut off its successor.
    pub fn stop_playback(&self, generation: u64) {
        let _ = self
            .control_tx
            .send(ControlMsg::StopPlayback { generation });
    }

    /// Tears down the stream and thread. Also happens on drop.
    pub fn shutdown(&self) {
        let _ = self.control_tx.send(ControlMsg::Shutdown);
    }
}

impl Drop for AudioOutput {
    fn drop(&mut self) {
        let _ = self.control_tx.send(ControlMsg::Shutdown);
    }
}

pub(crate) struct AudioOutputAwakeHold {
    control_tx: std_mpsc::Sender<ControlMsg>,
}

impl Drop for AudioOutputAwakeHold {
    fn drop(&mut self) {
        let _ = self.control_tx.send(ControlMsg::ReleaseAwake);
    }
}

/// Per-playback state owned by the audio callback.
struct ActiveSource<T: FromSampleBytes> {
    generation: u64,
    refresh_revision: u64,
    buffer: ActiveSourceBuffer<T>,
    playhead_rx: watch::Receiver<f64>,
    ack: Option<SourceAcknowledgement>,
    preparing_request: Option<Arc<PreparingAudioRequest>>,
    #[cfg(not(target_os = "windows"))]
    latency_corrector: LatencyCorrector,
}

enum ActiveSourceBuffer<T: FromSampleBytes> {
    Ordinary(PrerenderedAudioBuffer<T>),
    Preparing(PreparingAudioBuffer<T>),
}

#[cfg(test)]
impl<T: FromSampleBytes + cpal::FromSample<f32>> ActiveSourceBuffer<T> {
    fn current_playhead_secs(&self) -> f64 {
        let Self::Ordinary(buffer) = self else {
            panic!("Preparing playback uses its consumed-span clock");
        };
        buffer.current_playhead_secs()
    }

    fn current_audible_playhead(&self, latency_seconds: f64) -> f64 {
        let Self::Ordinary(buffer) = self else {
            panic!("Preparing playback uses its consumed-span clock");
        };
        buffer.current_audible_playhead(latency_seconds)
    }
}

type InstallProgressiveAudio =
    dyn Fn(PreparingAudioSources, f64, u64, &PreparingAudioInstallation) -> Result<(), String>;

enum SourceCommand<T: FromSampleBytes> {
    Refresh {
        source: Box<ActiveSource<T>>,
        retire_tx: std_mpsc::Sender<ControlMsg>,
        requeue_tx: std_mpsc::Sender<SourceCommand<T>>,
    },
    Install(Box<ActiveSource<T>>),
    Remove {
        generation: Option<u64>,
    },
}

/// The type-erased face of a running stream. The closures capture the typed
/// channel to the callback, chosen by the device's sample format at build.
struct TypedStreamHandle {
    stream: cpal::Stream,
    source_active: Arc<AtomicBool>,
    #[allow(clippy::type_complexity)]
    install: Box<dyn Fn(Box<PlaySpec>, u64, SourceAcknowledgement) -> Result<(), String>>,
    install_progressive: Box<InstallProgressiveAudio>,
    remove: Box<dyn Fn(Option<u64>)>,
}

struct StreamState {
    device_name: Option<String>,
    failed: Arc<AtomicBool>,
    supports_idle_pause: bool,
    paused: bool,
    handle: TypedStreamHandle,
}

impl StreamState {
    fn idle_pausable(&self) -> bool {
        self.supports_idle_pause && !self.paused
    }
}

struct IdleTimer {
    last_activity: Instant,
}

impl IdleTimer {
    fn new(now: Instant) -> Self {
        Self { last_activity: now }
    }

    fn touch(&mut self, now: Instant) {
        self.last_activity = now;
    }

    fn remaining(&self, now: Instant) -> Duration {
        IDLE_PAUSE_AFTER.saturating_sub(now.saturating_duration_since(self.last_activity))
    }

    fn should_pause(&mut self, now: Instant, source_active: bool) -> bool {
        if source_active {
            self.touch(now);
            return false;
        }
        self.remaining(now).is_zero()
    }
}

fn pause_idle_stream(state: &mut Option<StreamState>) {
    let Some(stream) = state.as_mut() else {
        return;
    };
    match stream.handle.stream.pause() {
        Ok(()) => {
            stream.paused = true;
            info!("Paused idle audio output stream");
        }
        Err(error) => {
            error!(%error, "Failed to pause idle audio output stream; closing it");
            *state = None;
        }
    }
}

fn control_thread(control_rx: std_mpsc::Receiver<ControlMsg>) {
    // cpal streams aren't Send; this thread owns the stream for its lifetime.
    let mut state: Option<StreamState> = None;
    let mut idle = IdleTimer::new(Instant::now());
    let mut awake_holds = 0usize;

    loop {
        let msg = if state.as_ref().is_some_and(StreamState::idle_pausable) {
            match control_rx.recv_timeout(idle.remaining(Instant::now())) {
                Ok(msg) => msg,
                Err(std_mpsc::RecvTimeoutError::Timeout) => {
                    let keep_running = awake_holds > 0
                        || state.as_ref().is_some_and(|stream| {
                            stream.handle.source_active.load(Ordering::Acquire)
                        });
                    if idle.should_pause(Instant::now(), keep_running) {
                        pause_idle_stream(&mut state);
                    }
                    continue;
                }
                Err(std_mpsc::RecvTimeoutError::Disconnected) => break,
            }
        } else {
            match control_rx.recv() {
                Ok(msg) => msg,
                Err(_) => break,
            }
        };
        match msg {
            ControlMsg::Refresh {
                spec,
                generation,
                revision,
                retire_tx,
            } => {
                if let Some(stream) = &state
                    && let Err(error) = (stream.handle.install)(
                        spec,
                        generation,
                        SourceAcknowledgement::Refresh(retire_tx, revision),
                    )
                {
                    error!(%error, "Could not update microphone enhancement during playback");
                }
            }
            ControlMsg::EnsureStream => {
                ensure_stream(&mut state);
            }
            ControlMsg::HoldAwake => {
                awake_holds += 1;
                ensure_stream(&mut state);
            }
            ControlMsg::ReleaseAwake => awake_holds = awake_holds.saturating_sub(1),
            ControlMsg::Play {
                spec,
                generation,
                result_tx,
            } => {
                let ok = handle_play(&mut state, spec, generation);
                let _ = result_tx.send(ok);
            }
            ControlMsg::PreparePlayback {
                spec,
                generation,
                request,
            } => {
                if request.is_cancelled() || !ensure_stream(&mut state) || request.is_cancelled() {
                    request.complete(false);
                    continue;
                }
                let Some(stream) = state.as_ref() else {
                    request.complete(false);
                    continue;
                };
                if let Err(error) = (stream.handle.install)(
                    spec,
                    generation,
                    SourceAcknowledgement::Preparing(request.clone()),
                ) {
                    error!("Failed to install preparing audio source: {error}");
                    request.complete(false);
                }
            }
            ControlMsg::PrepareProgressivePlayback {
                sources,
                start_seconds,
                generation,
                installation,
            } => {
                let request = &installation.request;
                if request.is_cancelled() || !ensure_stream(&mut state) || request.is_cancelled() {
                    request.complete(false);
                    continue;
                }
                let Some(stream) = state.as_ref() else {
                    request.complete(false);
                    continue;
                };
                if let Err(error) = (stream.handle.install_progressive)(
                    sources,
                    start_seconds,
                    generation,
                    &installation,
                ) {
                    error!("Failed to install progressive preparing audio: {error}");
                    request.complete(false);
                }
            }
            ControlMsg::StopPlayback { generation } => {
                stop_stream_state(
                    &mut state,
                    generation,
                    |stream| stream.failed.load(Ordering::Acquire),
                    |stream, generation| (stream.handle.remove)(Some(generation)),
                );
            }
            ControlMsg::Retire(source) => drop(source),
            ControlMsg::Realign(realign) => realign(),
            ControlMsg::Shutdown => break,
        }
        idle.touch(Instant::now());
    }

    info!("Audio output thread finished");
}

fn stop_stream_state<S>(
    state: &mut Option<S>,
    generation: u64,
    is_failed: impl FnOnce(&S) -> bool,
    remove: impl FnOnce(&S, u64),
) {
    if state.as_ref().is_some_and(is_failed) {
        drop(state.take());
    } else if let Some(stream) = state.as_ref() {
        remove(stream, generation);
    }
}

/// Applies pending install/remove commands to the active source. Shared by
/// the live cpal callback and the headless sink.
fn drain_source_commands<T: FromSampleBytes + cpal::FromSample<f32>>(
    active: &mut Option<ActiveSource<T>>,
    source_rx: &std_mpsc::Receiver<SourceCommand<T>>,
) {
    while let Ok(command) = source_rx.try_recv() {
        match command {
            SourceCommand::Refresh {
                mut source,
                retire_tx,
                requeue_tx,
            } => {
                let retired = if let Some(current) = active.as_mut().filter(|current| {
                    current.generation == source.generation
                        && current.refresh_revision <= source.refresh_revision
                }) {
                    current.refresh_revision = source.refresh_revision;
                    if let (
                        ActiveSourceBuffer::Ordinary(previous),
                        ActiveSourceBuffer::Ordinary(replacement),
                    ) = (&current.buffer, &mut source.buffer)
                    {
                        let playhead = previous.current_audible_playhead(0.0);
                        if !replacement.try_align_prepared_playhead(playhead) {
                            let sender = retire_tx.clone();
                            let _ = sender.send(ControlMsg::Realign(Box::new(move || {
                                if let ActiveSourceBuffer::Ordinary(buffer) = &mut source.buffer {
                                    buffer.set_playhead(playhead);
                                    if !buffer.wait_until_ready(PRERENDER_READY_TIMEOUT) {
                                        return;
                                    }
                                }
                                let sender = requeue_tx.clone();
                                let _ = sender.send(SourceCommand::Refresh {
                                    source,
                                    retire_tx,
                                    requeue_tx,
                                });
                            })));
                            continue;
                        }
                    }
                    active.replace(*source).map(Box::new)
                } else {
                    Some(source)
                };
                if let Some(retired) = retired {
                    let _ = retire_tx.send(ControlMsg::Retire(retired));
                }
            }
            SourceCommand::Install(source) => {
                if !source
                    .preparing_request
                    .as_ref()
                    .is_some_and(|request| request.is_cancelled())
                {
                    *active = Some(*source);
                }
            }
            SourceCommand::Remove { generation } => {
                let matches = generation.is_none()
                    || active
                        .as_ref()
                        .map(|s| Some(s.generation) == generation)
                        .unwrap_or(false);
                if matches {
                    *active = None;
                }
            }
        }
    }
    if active.as_ref().is_some_and(|source| {
        source
            .preparing_request
            .as_ref()
            .is_some_and(|request| request.is_cancelled())
    }) {
        *active = None;
    }
}

/// Re-anchors the audio on the video playhead when they drift apart.
fn sync_video_playhead<T: FromSampleBytes + cpal::FromSample<f32>>(
    audio: &mut PrerenderedAudioBuffer<T>,
    playhead_rx: &mut watch::Receiver<f64>,
    latency_secs: f64,
) {
    if playhead_rx.has_changed().unwrap_or(false) {
        let video_playhead = *playhead_rx.borrow_and_update();
        let audible_playhead = audio.current_audible_playhead(latency_secs);
        let drift = (video_playhead - audible_playhead).abs();

        if drift > 0.04 {
            audio.set_playhead(video_playhead + latency_secs);
        }
    }
}

/// Renders one output block from the active source: applies the video
/// playhead sync policy, fills the buffer and acknowledges the first
/// consumed block. Shared by the live cpal callback and the headless sink so
/// harnesses exercise the exact production logic.
fn render_source_block<T: FromSampleBytes + cpal::FromSample<f32>>(
    source: &mut ActiveSource<T>,
    buffer: &mut [T],
    latency_secs: f64,
) {
    if source
        .preparing_request
        .as_ref()
        .is_some_and(|request| request.is_cancelled())
    {
        buffer.fill(T::EQUILIBRIUM);
        return;
    }
    match &mut source.buffer {
        ActiveSourceBuffer::Ordinary(audio) => {
            sync_video_playhead(audio, &mut source.playhead_rx, latency_secs);
            audio.fill(buffer);
        }
        ActiveSourceBuffer::Preparing(audio) => {
            if audio.fill(buffer, latency_secs) == 0 {
                if audio.is_terminal()
                    && let Some(request) = &source.preparing_request
                {
                    request.complete(false);
                }
                return;
            }
        }
    }

    if source
        .preparing_request
        .as_ref()
        .is_some_and(|request| request.is_cancelled())
    {
        buffer.fill(T::EQUILIBRIUM);
        return;
    }

    if let Some(ack) = source.ack.take() {
        ack.consumed();
    }
}

/// Builds the per-playback source from a play spec and hands it to the
/// output via `install_tx`. `use_device_latency_hint` is false for the
/// headless sink, which models a zero-latency device.
fn install_source<T: FromSampleBytes + cpal::FromSample<f32>>(
    spec: Box<PlaySpec>,
    generation: u64,
    ack: SourceAcknowledgement,
    output_info: AudioInfo,
    use_device_latency_hint: bool,
    install_tx: &std_mpsc::Sender<SourceCommand<T>>,
    cache: &PlaybackAudioCache,
) -> Result<(), String> {
    let preparing_request = ack.preparing_request();
    if preparing_request
        .as_ref()
        .is_some_and(|request| request.is_cancelled())
    {
        return Err("Preparing audio request cancelled".into());
    }
    let PlaySpec {
        segments,
        music,
        project,
        duration_secs,
        start_playhead_secs,
        playhead_rx,
    } = *spec;

    if !(duration_secs.is_finite() && duration_secs > 0.0) {
        return Err(format!(
            "Invalid audio pre-render duration: {duration_secs}"
        ));
    }

    #[cfg(not(target_os = "windows"))]
    let latency_corrector = {
        let hint = if use_device_latency_hint {
            default_output_latency_hint(output_info.sample_rate, output_info.buffer_size)
        } else {
            None
        };
        if let Some(hint) = hint
            && hint.latency_secs > 0.0
        {
            if hint.transport.is_wireless() {
                info!(
                    "Applying wireless audio output latency hint: {:.1} ms",
                    hint.latency_secs * 1_000.0
                );
            } else {
                info!(
                    "Applying audio output latency hint: {:.1} ms",
                    hint.latency_secs * 1_000.0
                );
            }
        }
        LatencyCorrector::new(hint, LatencyCorrectionConfig::default())
    };
    #[cfg(not(target_os = "windows"))]
    let initial_latency_secs = latency_corrector.initial_output_latency_secs();
    #[cfg(target_os = "windows")]
    let initial_latency_secs = {
        let _ = use_device_latency_hint;
        0.0
    };

    let start_playhead = start_playhead_secs + initial_latency_secs;
    let mut buffer = if matches!(ack, SourceAcknowledgement::Refresh(..)) {
        PrerenderedAudioBuffer::<T>::bounded(segments, music, &project, output_info, start_playhead)
    } else {
        PrerenderedAudioBuffer::<T>::new_cached(
            segments,
            music,
            &project,
            output_info,
            duration_secs,
            start_playhead,
            cache,
        )
    };
    if !matches!(ack, SourceAcknowledgement::Refresh(..)) {
        buffer.set_playhead(start_playhead);
    }
    // A few ms: guarantees the callback reads real samples at the
    // playhead, never leading silence.
    if !buffer.wait_until_ready(PRERENDER_READY_TIMEOUT) {
        return Err("Audio processing did not become ready in time".into());
    }

    if preparing_request
        .as_ref()
        .is_some_and(|request| request.is_cancelled())
    {
        return Err("Preparing audio request cancelled".into());
    }

    if let Some(request) = &preparing_request {
        request.awaiting_callback();
    }

    let retire_tx = match &ack {
        SourceAcknowledgement::Refresh(sender, _) => Some(sender.clone()),
        _ => None,
    };
    let refresh_revision = match &ack {
        SourceAcknowledgement::Refresh(_, revision) => *revision,
        _ => 0,
    };
    let source = Box::new(ActiveSource {
        generation,
        refresh_revision,
        buffer: ActiveSourceBuffer::Ordinary(buffer),
        playhead_rx,
        ack: Some(ack),
        preparing_request,
        #[cfg(not(target_os = "windows"))]
        latency_corrector,
    });
    install_tx
        .send(if let Some(retire_tx) = retire_tx {
            SourceCommand::Refresh {
                source,
                retire_tx,
                requeue_tx: install_tx.clone(),
            }
        } else {
            SourceCommand::Install(source)
        })
        .map_err(|_| "Audio callback channel closed".to_string())
}

fn install_progressive_source<T: FromSampleBytes + cpal::FromSample<f32>>(
    sources: PreparingAudioSources,
    start_seconds: f64,
    generation: u64,
    installation: &PreparingAudioInstallation,
    output_info: AudioInfo,
    use_device_latency_hint: bool,
    install_tx: &std_mpsc::Sender<SourceCommand<T>>,
) -> Result<(), String> {
    let request = &installation.request;
    if request.is_cancelled() {
        return Err("Preparing audio request cancelled".into());
    }
    #[cfg(not(target_os = "windows"))]
    let latency_corrector = LatencyCorrector::new(
        if use_device_latency_hint {
            default_output_latency_hint(output_info.sample_rate, output_info.buffer_size)
        } else {
            None
        },
        LatencyCorrectionConfig::default(),
    );
    #[cfg(target_os = "windows")]
    let _ = use_device_latency_hint;
    let (buffer, output) = PreparingAudioBuffer::<T>::spawn(
        sources,
        output_info,
        start_seconds,
        installation.runtime.clone(),
    )?;
    *request
        .output
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner) = Some(output.clone());
    output.set_playable_until(installation.playable_until)?;
    if request.is_cancelled() {
        return Err("Preparing audio request cancelled".into());
    }
    let (_, playhead_rx) = watch::channel(start_seconds);
    request.awaiting_callback();
    install_tx
        .send(SourceCommand::Install(Box::new(ActiveSource {
            generation,
            refresh_revision: 0,
            buffer: ActiveSourceBuffer::Preparing(buffer),
            playhead_rx,
            ack: Some(SourceAcknowledgement::Preparing(request.clone())),
            preparing_request: Some(request.clone()),
            #[cfg(not(target_os = "windows"))]
            latency_corrector,
        })))
        .map_err(|_| "Audio callback channel closed".to_string())
}

/// Control loop for the headless sink: a pump thread pulls blocks on a
/// real-time schedule (as a device would) and hands every block to `tap`.
fn control_thread_headless(control_rx: std_mpsc::Receiver<ControlMsg>, mut tap: HeadlessAudioTap) {
    let output_info = AudioInfo::new_raw(
        AudioData::SAMPLE_FORMAT,
        HEADLESS_SAMPLE_RATE,
        HEADLESS_CHANNELS,
    );

    let (source_tx, source_rx) = std_mpsc::channel::<SourceCommand<f32>>();
    let stop = Arc::new(AtomicBool::new(false));
    let cache = PlaybackAudioCache::default();

    let pump = {
        let stop = stop.clone();
        let channels = usize::from(HEADLESS_CHANNELS);
        std::thread::Builder::new()
            .name("cap-audio-headless-pump".into())
            .spawn(move || {
                let mut buffer = vec![0.0f32; HEADLESS_BLOCK_FRAMES * channels];
                let mut active: Option<ActiveSource<f32>> = None;
                let block = Duration::from_secs_f64(
                    HEADLESS_BLOCK_FRAMES as f64 / f64::from(HEADLESS_SAMPLE_RATE),
                );
                let start = Instant::now();
                let mut n: u32 = 0;

                while !stop.load(Ordering::Acquire) {
                    // Absolute schedule: a device consumes samples isochronously,
                    // so late wakeups must not stretch the sample clock.
                    let deadline = start + block * n;
                    let now = Instant::now();
                    if deadline > now {
                        std::thread::sleep(deadline - now);
                    }

                    drain_source_commands(&mut active, &source_rx);
                    match active.as_mut() {
                        Some(source) => render_source_block(source, &mut buffer, 0.0),
                        None => buffer.fill(0.0),
                    }
                    tap(&buffer, deadline);
                    n = n.saturating_add(1);
                }
            })
    };
    let pump = match pump {
        Ok(handle) => Some(handle),
        Err(e) => {
            error!("Failed to spawn headless audio pump: {e}");
            None
        }
    };

    while let Ok(msg) = control_rx.recv() {
        match msg {
            ControlMsg::Refresh {
                spec,
                generation,
                revision,
                retire_tx,
            } => {
                if let Err(error) = install_source::<f32>(
                    spec,
                    generation,
                    SourceAcknowledgement::Refresh(retire_tx, revision),
                    output_info,
                    false,
                    &source_tx,
                    &cache,
                ) {
                    error!(%error, "Could not update headless audio playback");
                }
            }
            ControlMsg::EnsureStream | ControlMsg::HoldAwake | ControlMsg::ReleaseAwake => {}
            ControlMsg::Play {
                spec,
                generation,
                result_tx,
            } => {
                let (ack_tx, ack_rx) = std_mpsc::channel();
                let ok = pump.is_some()
                    && match install_source::<f32>(
                        spec,
                        generation,
                        SourceAcknowledgement::Ordinary(ack_tx),
                        output_info,
                        false,
                        &source_tx,
                        &cache,
                    ) {
                        Ok(()) => ack_rx.recv_timeout(SOURCE_ACK_TIMEOUT).is_ok(),
                        Err(e) => {
                            error!("Failed to install headless audio source: {e}");
                            false
                        }
                    };
                let _ = result_tx.send(ok);
            }
            ControlMsg::PreparePlayback {
                spec,
                generation,
                request,
            } => {
                if request.is_cancelled() || pump.is_none() {
                    request.complete(false);
                    continue;
                }
                if let Err(error) = install_source::<f32>(
                    spec,
                    generation,
                    SourceAcknowledgement::Preparing(request.clone()),
                    output_info,
                    false,
                    &source_tx,
                    &cache,
                ) {
                    error!("Failed to install preparing headless audio source: {error}");
                    request.complete(false);
                }
            }
            ControlMsg::PrepareProgressivePlayback {
                sources,
                start_seconds,
                generation,
                installation,
            } => {
                let request = &installation.request;
                if request.is_cancelled() || pump.is_none() {
                    request.complete(false);
                    continue;
                }
                if let Err(error) = install_progressive_source::<f32>(
                    sources,
                    start_seconds,
                    generation,
                    &installation,
                    output_info,
                    false,
                    &source_tx,
                ) {
                    error!("Failed to install progressive headless audio: {error}");
                    request.complete(false);
                }
            }
            ControlMsg::StopPlayback { generation } => {
                let _ = source_tx.send(SourceCommand::Remove {
                    generation: Some(generation),
                });
            }
            ControlMsg::Retire(source) => drop(source),
            ControlMsg::Realign(realign) => realign(),
            ControlMsg::Shutdown => break,
        }
    }

    stop.store(true, Ordering::Release);
    if let Some(pump) = pump {
        let _ = pump.join();
    }

    info!("Headless audio output thread finished");
}

/// A sink with no device and no clock, for verification harnesses: the
/// caller pulls every block, and each pull first waits until the samples it
/// reads are rendered, so the PCM depends only on the sequence of plays,
/// seeks and pulls, never on render speed. Sources are built by the same
/// `install_source` as the device and headless sinks.
#[cfg(feature = "test-hooks")]
pub struct OfflineAudioSink {
    source_rx: std_mpsc::Receiver<SourceCommand<f32>>,
    active: Option<ActiveSource<f32>>,
}

#[cfg(feature = "test-hooks")]
impl AudioOutput {
    /// Output at [`HEADLESS_SAMPLE_RATE`] / [`HEADLESS_CHANNELS`] whose blocks
    /// are pulled through the returned sink. `play` returns once the source
    /// is installed.
    pub fn new_offline() -> (Self, OfflineAudioSink) {
        let (control_tx, control_rx) = std_mpsc::channel();
        let (source_tx, source_rx) = std_mpsc::channel();
        if let Err(e) = std::thread::Builder::new()
            .name("cap-audio-offline".into())
            .spawn(move || control_thread_offline(control_rx, source_tx))
        {
            error!("Failed to spawn offline audio output thread: {e}");
        }
        (
            Self {
                control_tx,
                next_generation: AtomicU64::new(0),
            },
            OfflineAudioSink {
                source_rx,
                active: None,
            },
        )
    }
}

#[cfg(feature = "test-hooks")]
impl OfflineAudioSink {
    /// Renders the next interleaved block. Returns false (and silence) when
    /// no source is installed or its samples did not render within
    /// `timeout`.
    pub fn pull(&mut self, block: &mut [f32], timeout: Duration) -> bool {
        drain_source_commands(&mut self.active, &self.source_rx);
        let Some(source) = self.active.as_mut() else {
            block.fill(0.0);
            return false;
        };
        let mut rendered = true;
        if let ActiveSourceBuffer::Ordinary(audio) = &mut source.buffer {
            sync_video_playhead(audio, &mut source.playhead_rx, 0.0);
            rendered = audio.wait_until_rendered(block.len(), timeout);
        }
        render_source_block(source, block, 0.0);
        rendered
    }
}

#[cfg(feature = "test-hooks")]
fn control_thread_offline(
    control_rx: std_mpsc::Receiver<ControlMsg>,
    source_tx: std_mpsc::Sender<SourceCommand<f32>>,
) {
    let output_info = AudioInfo::new_raw(
        AudioData::SAMPLE_FORMAT,
        HEADLESS_SAMPLE_RATE,
        HEADLESS_CHANNELS,
    );
    let cache = PlaybackAudioCache::default();
    while let Ok(msg) = control_rx.recv() {
        match msg {
            ControlMsg::Refresh {
                spec,
                generation,
                revision,
                retire_tx,
            } => {
                if let Err(error) = install_source::<f32>(
                    spec,
                    generation,
                    SourceAcknowledgement::Refresh(retire_tx, revision),
                    output_info,
                    false,
                    &source_tx,
                    &cache,
                ) {
                    error!(%error, "Could not update offline audio playback");
                }
            }
            ControlMsg::Play {
                spec,
                generation,
                result_tx,
            } => {
                let (ack_tx, _ack_rx) = std_mpsc::channel();
                let ok = install_source::<f32>(
                    spec,
                    generation,
                    SourceAcknowledgement::Ordinary(ack_tx),
                    output_info,
                    false,
                    &source_tx,
                    &cache,
                )
                .inspect_err(|e| error!("Failed to install offline audio source: {e}"))
                .is_ok();
                let _ = result_tx.send(ok);
            }
            ControlMsg::PreparePlayback { request, .. } => request.complete(false),
            ControlMsg::PrepareProgressivePlayback { installation, .. } => {
                installation.request.complete(false)
            }
            ControlMsg::StopPlayback { generation } => {
                let _ = source_tx.send(SourceCommand::Remove {
                    generation: Some(generation),
                });
            }
            ControlMsg::EnsureStream | ControlMsg::HoldAwake | ControlMsg::ReleaseAwake => {}
            ControlMsg::Retire(source) => drop(source),
            ControlMsg::Realign(realign) => realign(),
            ControlMsg::Shutdown => break,
        }
    }
}

fn handle_play(state: &mut Option<StreamState>, spec: Box<PlaySpec>, generation: u64) -> bool {
    if !ensure_stream(state) {
        return false;
    }
    let Some(s) = state.as_ref() else {
        return false;
    };

    let (ack_tx, ack_rx) = std_mpsc::channel();
    if let Err(e) = (s.handle.install)(spec, generation, SourceAcknowledgement::Ordinary(ack_tx)) {
        error!("Failed to install audio source: {e}");
        return false;
    }

    match ack_rx.recv_timeout(SOURCE_ACK_TIMEOUT) {
        Ok(()) => true,
        Err(_) => {
            error!("Audio output did not consume the new source in time");
            (s.handle.remove)(Some(generation));
            // Force a rebuild on the next play; the device likely died.
            s.failed.store(true, Ordering::Release);
            false
        }
    }
}

/// Returns true when a healthy stream for the current default device exists
/// (building one if needed).
fn ensure_stream(state: &mut Option<StreamState>) -> bool {
    let host = cpal::default_host();
    let Some(device) = host.default_output_device() else {
        error!("No default output device found");
        *state = None;
        return false;
    };
    let device_name = device.name().ok();

    if let Some(s) = state.as_mut() {
        if !s.failed.load(Ordering::Acquire) && s.device_name == device_name {
            if !s.paused {
                return true;
            }
            match s.handle.stream.play() {
                Ok(()) => {
                    s.paused = false;
                    return true;
                }
                Err(e) => error!("Failed to resume audio output stream: {e}"),
            }
        }
        info!("Rebuilding audio output stream (device changed or stream failed)");
    }
    *state = None;

    let supported_config = match device.default_output_config() {
        Ok(config) => config,
        Err(e) => {
            error!("Failed to get default output config: {e}");
            return false;
        }
    };

    let failed = Arc::new(AtomicBool::new(false));
    let result = match supported_config.sample_format() {
        SampleFormat::I16 => build_stream::<i16>(device, supported_config, failed.clone()),
        SampleFormat::I32 => build_stream::<i32>(device, supported_config, failed.clone()),
        SampleFormat::F32 => build_stream::<f32>(device, supported_config, failed.clone()),
        SampleFormat::I64 => build_stream::<i64>(device, supported_config, failed.clone()),
        SampleFormat::U8 => build_stream::<u8>(device, supported_config, failed.clone()),
        SampleFormat::F64 => build_stream::<f64>(device, supported_config, failed.clone()),
        format => {
            error!("Unsupported output sample format {format:?}");
            return false;
        }
    };

    match result {
        Ok(handle) => {
            info!(device = ?device_name, "Audio output stream ready");
            *state = Some(StreamState {
                device_name,
                failed,
                supports_idle_pause: cap_audio::default_output_supports_idle_pause(),
                paused: false,
                handle,
            });
            true
        }
        Err(e) => {
            error!("Failed to create audio output stream: {e}");
            false
        }
    }
}

fn playback_output_info(config: &cpal::SupportedStreamConfig) -> AudioInfo {
    // ALSA's supported maximum is not the queue size used by BufferSize::Default.
    let buffer_size = cfg!(target_os = "linux").then_some(1024);
    let mut info = AudioInfo::from_stream_config_with_buffer(config, buffer_size);
    info.sample_format = info.sample_format.packed();
    info.for_ffmpeg_output()
}

fn build_stream<T>(
    device: cpal::Device,
    supported_config: cpal::SupportedStreamConfig,
    failed: Arc<AtomicBool>,
) -> Result<TypedStreamHandle, String>
where
    T: FromSampleBytes + cpal::SizedSample + cpal::FromSample<f32>,
{
    let output_info = playback_output_info(&supported_config);
    // Clamp for FFmpeg compatibility (max 8 channels); the stream config must
    // match what the pre-render buffer produces.
    let mut config = supported_config.config();
    config.channels = output_info.channels as u16;

    let (source_tx, source_rx) = std_mpsc::channel::<SourceCommand<T>>();
    let source_active = Arc::new(AtomicBool::new(false));

    let mut active: Option<ActiveSource<T>> = None;
    let callback_source_active = source_active.clone();
    let stream = device
        .build_output_stream(
            &config,
            move |buffer: &mut [T], info| {
                drain_source_commands(&mut active, &source_rx);
                callback_source_active.store(active.is_some(), Ordering::Release);

                let Some(source) = active.as_mut() else {
                    buffer.fill(T::EQUILIBRIUM);
                    return;
                };

                #[cfg(not(target_os = "windows"))]
                let latency_secs = source.latency_corrector.update_from_callback(info);
                #[cfg(target_os = "windows")]
                let latency_secs = {
                    let _ = info;
                    0.0
                };

                render_source_block(source, buffer, latency_secs);
            },
            {
                let failed = failed.clone();
                move |err| {
                    failed.store(true, Ordering::Release);
                    error!("Audio stream error: {err}");
                }
            },
            None,
        )
        .map_err(|e| format!("Failed to build audio output stream: {e}"))?;

    stream
        .play()
        .map_err(|e| format!("Failed to start audio output stream: {e}"))?;

    let install_tx = source_tx.clone();
    let cache = PlaybackAudioCache::default();
    let install = Box::new(
        move |spec: Box<PlaySpec>, generation: u64, ack: SourceAcknowledgement| {
            install_source::<T>(
                spec,
                generation,
                ack,
                output_info,
                true,
                &install_tx,
                &cache,
            )
        },
    );

    let progressive_tx = source_tx.clone();
    let install_progressive = Box::new(
        move |sources, start_seconds, generation, installation: &PreparingAudioInstallation| {
            install_progressive_source::<T>(
                sources,
                start_seconds,
                generation,
                installation,
                output_info,
                true,
                &progressive_tx,
            )
        },
    );

    let remove = Box::new(move |generation: Option<u64>| {
        let _ = source_tx.send(SourceCommand::Remove { generation });
    });

    Ok(TypedStreamHandle {
        stream,
        source_active,
        install,
        install_progressive,
        remove,
    })
}

#[cfg(test)]
mod native_tests;

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

    pub(super) fn source(sample_rate: u32) -> (ActiveSource<f32>, watch::Sender<f64>) {
        source_with_info(
            AudioInfo::new_raw(AudioData::SAMPLE_FORMAT, sample_rate, 2),
            false,
        )
    }

    fn source_with_info(
        output_info: AudioInfo,
        use_device_latency_hint: bool,
    ) -> (ActiveSource<f32>, watch::Sender<f64>) {
        ffmpeg::init().unwrap();
        let (playhead_tx, playhead_rx) = watch::channel(0.0);
        let (install_tx, install_rx) = std_mpsc::channel();
        let (ack_tx, _ack_rx) = std_mpsc::channel();
        install_source(
            Box::new(PlaySpec {
                segments: Vec::new(),
                music: MusicTracks::new(),
                project: ProjectConfiguration::default(),
                duration_secs: 2.0,
                start_playhead_secs: 0.0,
                playhead_rx,
            }),
            0,
            SourceAcknowledgement::Ordinary(ack_tx),
            output_info,
            use_device_latency_hint,
            &install_tx,
            &PlaybackAudioCache::default(),
        )
        .unwrap();
        let SourceCommand::Install(source) = install_rx.recv().unwrap() else {
            panic!("expected installed audio source");
        };
        (*source, playhead_tx)
    }

    #[test]
    fn idle_timer_pauses_only_after_a_quiet_grace_period() {
        let start = Instant::now();
        let mut idle = IdleTimer::new(start);

        assert_eq!(idle.remaining(start), IDLE_PAUSE_AFTER);
        assert!(!idle.should_pause(start + IDLE_PAUSE_AFTER / 2, false));
        assert!(idle.should_pause(start + IDLE_PAUSE_AFTER, false));

        idle.touch(start + IDLE_PAUSE_AFTER);
        assert!(!idle.should_pause(start + IDLE_PAUSE_AFTER * 3 / 2, false));
        assert_eq!(
            idle.remaining(start + IDLE_PAUSE_AFTER * 3 / 2),
            IDLE_PAUSE_AFTER / 2
        );
        assert!(idle.should_pause(start + IDLE_PAUSE_AFTER * 2, false));
    }

    #[test]
    fn idle_timer_never_pauses_while_a_source_is_playing() {
        let start = Instant::now();
        let mut idle = IdleTimer::new(start);
        let playing_until = start + IDLE_PAUSE_AFTER * 4;

        assert!(!idle.should_pause(start + IDLE_PAUSE_AFTER, true));
        assert!(!idle.should_pause(playing_until, true));
        assert_eq!(idle.remaining(playing_until), IDLE_PAUSE_AFTER);
        assert!(!idle.should_pause(playing_until + IDLE_PAUSE_AFTER / 2, false));
        assert!(idle.should_pause(playing_until + IDLE_PAUSE_AFTER, false));
    }

    #[cfg(target_os = "linux")]
    #[test]
    fn supported_buffer_maximum_does_not_skip_the_start_of_playback() {
        for sample_rate in [44_100, 48_000] {
            let config = cpal::SupportedStreamConfig::new(
                2,
                cpal::SampleRate(sample_rate),
                cpal::SupportedBufferSize::Range {
                    min: 1,
                    max: 4_194_304,
                },
                SampleFormat::F32,
            );
            let (source, _) = source_with_info(playback_output_info(&config), true);
            let playhead = source.buffer.current_playhead_secs();
            assert!(
                (playhead - 0.03).abs() < 1.0 / f64::from(sample_rate),
                "sample_rate={sample_rate}, playhead={playhead}"
            );
        }
    }

    #[test]
    fn enhancement_refresh_only_replaces_its_active_playback_generation() {
        let (mut original, _playhead) = source(48_000);
        original.generation = 7;
        let mut active = Some(original);
        let (tx, rx) = std_mpsc::channel();
        let (retire_tx, retire_rx) = std_mpsc::channel();
        for (generation, should_replace) in [(7, true), (6, false), (8, false)] {
            let (mut replacement, _playhead) = source(48_000);
            replacement.generation = generation;
            let replacement_receiver = replacement.playhead_rx.clone();
            let ActiveSourceBuffer::Ordinary(buffer) = &mut replacement.buffer else {
                panic!("expected ordinary source");
            };
            buffer.set_playhead(0.5);
            let ActiveSourceBuffer::Ordinary(buffer) = &mut active.as_mut().unwrap().buffer else {
                panic!("expected ordinary source");
            };
            buffer.set_playhead(0.125);
            tx.send(SourceCommand::Refresh {
                source: Box::new(replacement),
                retire_tx: retire_tx.clone(),
                requeue_tx: tx.clone(),
            })
            .unwrap();
            drain_source_commands(&mut active, &rx);
            assert!(matches!(
                retire_rx.try_recv().unwrap(),
                ControlMsg::Retire(_)
            ));
            let actual = active.as_ref().unwrap();
            assert_eq!(actual.generation, 7);
            assert_eq!(
                actual.playhead_rx.same_channel(&replacement_receiver),
                should_replace
            );
            assert!((actual.buffer.current_playhead_secs() - 0.125).abs() < 1.0 / 48_000.0);
        }
        tx.send(SourceCommand::Remove {
            generation: Some(7),
        })
        .unwrap();
        let (mut replacement, _playhead) = source(48_000);
        replacement.generation = 7;
        tx.send(SourceCommand::Refresh {
            source: Box::new(replacement),
            retire_tx: retire_tx.clone(),
            requeue_tx: tx.clone(),
        })
        .unwrap();
        drain_source_commands(&mut active, &rx);
        assert!(active.is_none());
    }

    #[test]
    fn enhancement_refresh_realigns_off_callback_and_rejects_superseded_work() {
        for (newer_revision, stopped) in [(false, false), (true, false), (false, true)] {
            let (mut original, _playhead) = source(48_000);
            original.generation = 7;
            let ActiveSourceBuffer::Ordinary(buffer) = &mut original.buffer else {
                panic!("expected ordinary source");
            };
            buffer.set_playhead(1.0);
            let original_receiver = original.playhead_rx.clone();
            let mut active = Some(original);
            let (mut replacement, _playhead) = source(48_000);
            replacement.generation = 7;
            replacement.refresh_revision = 1;
            replacement.buffer = ActiveSourceBuffer::Ordinary(PrerenderedAudioBuffer::bounded(
                Vec::new(),
                MusicTracks::new(),
                &ProjectConfiguration::default(),
                AudioInfo::new_raw(AudioData::SAMPLE_FORMAT, 48_000, 2),
                3.0,
            ));
            let replacement_receiver = replacement.playhead_rx.clone();
            let (tx, rx) = std_mpsc::channel();
            let (retire_tx, retire_rx) = std_mpsc::channel();
            tx.send(SourceCommand::Refresh {
                source: Box::new(replacement),
                retire_tx,
                requeue_tx: tx.clone(),
            })
            .unwrap();
            drain_source_commands(&mut active, &rx);
            let current = active.as_mut().unwrap();
            assert!(current.playhead_rx.same_channel(&original_receiver));
            assert_eq!(current.refresh_revision, 1);
            let ControlMsg::Realign(realign) = retire_rx.try_recv().unwrap() else {
                panic!("expected deferred audio preparation");
            };
            if newer_revision {
                current.refresh_revision = 2;
            }
            let ActiveSourceBuffer::Ordinary(buffer) = &mut current.buffer else {
                panic!("expected ordinary source");
            };
            buffer.set_playhead(1.025);
            if stopped {
                active = None;
            }
            realign();
            drain_source_commands(&mut active, &rx);
            assert!(matches!(
                retire_rx.try_recv().unwrap(),
                ControlMsg::Retire(_)
            ));
            if stopped {
                assert!(active.is_none());
            } else {
                let current = active.as_ref().unwrap();
                assert_eq!(
                    current.playhead_rx.same_channel(&replacement_receiver),
                    !newer_revision
                );
                assert!((current.buffer.current_playhead_secs() - 1.025).abs() < 1.0 / 48_000.0);
            }
        }
    }

    #[test]
    fn coalesced_video_updates_preserve_synchronized_audio_position() {
        for sample_rate in [44_100, 48_000] {
            for latency_secs in [0.0, 0.025, 0.15] {
                let (mut source, playhead_tx) = source(sample_rate);
                let mut elapsed = vec![0.0; sample_rate as usize / 4 * 2];
                render_source_block(&mut source, &mut elapsed, latency_secs);
                let before = source.buffer.current_playhead_secs();
                let audible = source.buffer.current_audible_playhead(latency_secs);
                playhead_tx.send(audible - 0.02).unwrap();
                playhead_tx.send(audible - 0.002).unwrap();

                let mut block = [0.0; 512 * 2];
                render_source_block(&mut source, &mut block, latency_secs);

                let expected = before + 512.0 / f64::from(sample_rate);
                let actual = source.buffer.current_playhead_secs();
                assert!(
                    (actual - expected).abs() < 1.0 / f64::from(sample_rate),
                    "sample_rate={sample_rate}, latency={latency_secs}, expected={expected}, actual={actual}"
                );
            }
        }
    }

    #[test]
    fn video_drift_reseats_audio_for_forward_and_backward_seeks() {
        for sample_rate in [44_100, 48_000] {
            for latency_secs in [0.0, 0.025, 0.15] {
                let (mut source, playhead_tx) = source(sample_rate);
                let mut elapsed = vec![0.0; sample_rate as usize / 4 * 2];
                render_source_block(&mut source, &mut elapsed, latency_secs);
                let mut block = [0.0; 512 * 2];

                for target in [0.03, 0.6, 0.1] {
                    playhead_tx.send(target).unwrap();
                    render_source_block(&mut source, &mut block, latency_secs);
                    let expected = target + latency_secs + 512.0 / f64::from(sample_rate);
                    let actual = source.buffer.current_playhead_secs();
                    assert!(
                        (actual - expected).abs() <= 1.0 / f64::from(sample_rate),
                        "sample_rate={sample_rate}, latency={latency_secs}, target={target}, expected={expected}, actual={actual}"
                    );
                }
            }
        }
    }
}