Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

108 KB
Raw Blame
use crate::RecordingStartGate;
#[cfg(target_os = "macos")]
use crate::SendableShareableContent;
#[cfg(target_os = "linux")]
mod linux_camera;
#[cfg(target_os = "linux")]
pub use linux_camera::{
    LINUX_CAMERA_MAX_MASK_AGE, LinuxCameraBlur, LinuxCameraEffect, LinuxCameraMaskReceipt,
    LinuxCameraPixels, LinuxCameraPresentation, LinuxCameraPresentationError,
    LinuxCameraProcessing, LinuxCameraPublisher, LinuxCameraRect, LinuxCameraShape,
    LinuxProcessedCameraFrame, LinuxProcessedCameraSource,
};

use crate::{
    RecordingBaseInputs,
    capture_pipeline::{
        MakeCapturePipeline, ScreenCaptureMethod, Stop, target_to_display_and_crop,
    },
    feeds::microphone::MicrophoneFeedLock,
    output_pipeline::{self, OutputPipeline},
    resolution_limits::ensure_even,
    sources::screen_capture::{ScreenCaptureConfig, ScreenCaptureTarget},
};
use anyhow::Context as _;
use cap_media_info::VideoInfo;
use cap_project::InstantRecordingMeta;
use cap_timestamp::Timestamps;
use cap_utils::ensure_dir;
#[cfg(target_os = "linux")]
use futures::FutureExt as _;
use kameo::{Actor as _, prelude::*};
use std::{
    path::PathBuf,
    sync::Arc,
    time::{SystemTime, UNIX_EPOCH},
};
use tracing::*;

mod completion;
pub use completion::CleanInstantRecording;

#[cfg(target_os = "linux")]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
/// Joined covers this attempt's capture/output work, not shared preview feeds or physical device shutdown.
pub enum InstantQuiescence {
    Pending,
    Joined,
    Unconfirmed,
}

#[cfg(target_os = "linux")]
#[derive(Clone)]
pub struct InstantLifecycle(Arc<InstantLifecycleInner>);

#[cfg(target_os = "linux")]
struct InstantLifecycleInner {
    scope: output_pipeline::PipelineBuildScope,
    state: tokio::sync::watch::Sender<InstantQuiescence>,
    completion: tokio::sync::watch::Sender<Option<Result<(), output_pipeline::PipelineDoneError>>>,
    error: std::sync::Mutex<Option<String>>,
    runtime: std::sync::Mutex<Option<tokio::runtime::Handle>>,
}

#[cfg(target_os = "linux")]
impl InstantLifecycle {
    fn new() -> Self {
        let (state, _) = tokio::sync::watch::channel(InstantQuiescence::Pending);
        let (completion, _) = tokio::sync::watch::channel(None);
        Self(Arc::new(InstantLifecycleInner {
            scope: output_pipeline::PipelineBuildScope::new_lifetime(),
            state,
            completion,
            error: std::sync::Mutex::new(None),
            runtime: std::sync::Mutex::new(None),
        }))
    }

    /// Cancellation requests shutdown; callers must still await quiescence before revealing or deleting.
    pub fn cancel(&self) {
        self.0.scope.cancel();
        if let Some(report) = self.0.scope.idle_report() {
            self.publish_quiescence(report.quiescent);
        }
    }

    fn publish_quiescence(&self, quiescent: bool) {
        self.0.state.send_if_modified(|state| {
            if *state == InstantQuiescence::Unconfirmed {
                return false;
            }
            let next = if quiescent {
                InstantQuiescence::Joined
            } else {
                InstantQuiescence::Unconfirmed
            };
            let changed = *state != next;
            *state = next;
            changed
        });
    }

    pub fn quiescence(&self) -> InstantQuiescence {
        *self.0.state.borrow()
    }

    pub async fn wait_for_quiescence(&self) -> InstantQuiescence {
        let mut state = self.0.state.subscribe();
        loop {
            let value = *state.borrow_and_update();
            if value != InstantQuiescence::Pending {
                return value;
            }
            if state.changed().await.is_err() {
                return InstantQuiescence::Unconfirmed;
            }
        }
    }

    fn done_fut(&self) -> output_pipeline::DoneFut {
        let mut completion = self.0.completion.subscribe();
        async move {
            loop {
                if let Some(result) = completion.borrow_and_update().clone() {
                    return result;
                }
                if completion.changed().await.is_err() {
                    return Err(output_pipeline::PipelineDoneError::from_message(
                        "Instant completion acknowledgement was lost".into(),
                    ));
                }
            }
        }
        .boxed()
        .shared()
    }

    fn complete(
        &self,
        report: output_pipeline::PipelineJoinReport,
        error: Option<String>,
    ) -> anyhow::Result<()> {
        self.publish_quiescence(report.quiescent);
        let quiescent = self.quiescence() == InstantQuiescence::Joined;
        let mut stored = self.0.error.lock().unwrap();
        if stored.is_none() {
            *stored = error.or(report.error).or_else(|| {
                (!quiescent).then(|| "Instant capture quiescence is unconfirmed".into())
            });
        }
        let result = stored.as_ref().map_or(Ok(()), |error| {
            Err(output_pipeline::PipelineDoneError::from_message(
                error.clone(),
            ))
        });
        self.0.completion.send_if_modified(|current| {
            if current.is_none() {
                *current = Some(result.clone());
                true
            } else {
                false
            }
        });
        result.map_err(anyhow::Error::from)
    }

    fn spawn(&self, future: impl Future<Output = ()> + Send + 'static) {
        let runtime = self
            .0
            .runtime
            .lock()
            .unwrap()
            .clone()
            .or_else(|| tokio::runtime::Handle::try_current().ok());
        if let Some(runtime) = runtime {
            drop(runtime.spawn(future));
        } else if self.quiescence() == InstantQuiescence::Pending {
            self.0.state.send_replace(InstantQuiescence::Unconfirmed);
            self.0
                .error
                .lock()
                .unwrap()
                .get_or_insert_with(|| "Capture cleanup runtime is unavailable".into());
        }
    }
}

#[cfg(target_os = "linux")]
struct InstantLifetimeOwner {
    lifecycle: InstantLifecycle,
    armed: bool,
}

#[cfg(target_os = "linux")]
impl InstantLifetimeOwner {
    fn new() -> Self {
        Self {
            lifecycle: InstantLifecycle::new(),
            armed: true,
        }
    }

    async fn failed(mut self, error: String) -> InstantQuiescence {
        let report = self.lifecycle.0.scope.cancel_and_join_report().await;
        let _ = self.lifecycle.complete(report, Some(error));
        self.armed = false;
        self.lifecycle.quiescence()
    }
}

#[cfg(target_os = "linux")]
struct CleanupAcknowledgement {
    lifecycle: InstantLifecycle,
    armed: bool,
}

#[cfg(target_os = "linux")]
impl Drop for CleanupAcknowledgement {
    fn drop(&mut self) {
        if self.armed && self.lifecycle.quiescence() == InstantQuiescence::Pending {
            self.lifecycle
                .0
                .state
                .send_replace(InstantQuiescence::Unconfirmed);
        }
    }
}

#[cfg(target_os = "linux")]
impl Drop for InstantLifetimeOwner {
    fn drop(&mut self) {
        if !self.armed || self.lifecycle.quiescence() != InstantQuiescence::Pending {
            return;
        }
        self.lifecycle.0.scope.cancel();
        let message = "Instant recording owner dropped before shutdown acknowledgement".to_string();
        if let Some(report) = self.lifecycle.0.scope.idle_report() {
            let _ = self.lifecycle.complete(report, Some(message));
            return;
        }
        let lifecycle = self.lifecycle.clone();
        let guard = CleanupAcknowledgement {
            lifecycle: lifecycle.clone(),
            armed: true,
        };
        self.lifecycle.spawn(async move {
            let mut guard = guard;
            let report = lifecycle.0.scope.cancel_and_join_report().await;
            let _ = lifecycle.complete(report, Some(message));
            guard.armed = false;
        });
    }
}

#[cfg(target_os = "linux")]
struct BuildWaiter {
    lifecycle: InstantLifecycle,
    armed: bool,
}

#[cfg(target_os = "linux")]
impl Drop for BuildWaiter {
    fn drop(&mut self) {
        if self.armed {
            self.lifecycle.cancel();
        }
    }
}

struct Pipeline {
    video: OutputPipeline,
    audio: Option<OutputPipeline>,
    video_info: VideoInfo,
    segments_dir: PathBuf,
    segment_rx:
        Option<std::sync::mpsc::Receiver<cap_enc_ffmpeg::segmented_stream::SegmentCompletedEvent>>,
}

enum ActorState {
    Recording {
        pipeline: Pipeline,
        // pipeline_done_rx: oneshot::Receiver<Result<(), String>>,
        segment_start_time: f64,
    },
    Paused {
        pipeline: Pipeline,
        // pipeline_done_rx: oneshot::Receiver<Result<(), String>>,
        segment_start_time: f64,
    },
    Stopped,
}

pub struct ActorHandle {
    #[cfg(target_os = "linux")]
    lifecycle: InstantLifecycle,
    actor_ref: kameo::actor::ActorRef<Actor>,
    pub capture_target: ScreenCaptureTarget,
    done_fut: output_pipeline::DoneFut,
    health_rx: Option<output_pipeline::HealthReceiver>,
    segment_rx: Option<
        std::sync::Mutex<
            Option<
                std::sync::mpsc::Receiver<cap_enc_ffmpeg::segmented_stream::SegmentCompletedEvent>,
            >,
        >,
    >,
}

impl ActorHandle {
    #[cfg(target_os = "linux")]
    pub fn lifecycle(&self) -> InstantLifecycle {
        self.lifecycle.clone()
    }

    pub async fn stop(&self) -> anyhow::Result<CompletedRecording> {
        Ok(self.actor_ref.ask(Stop).await?)
    }

    pub fn done_fut(&self) -> output_pipeline::DoneFut {
        self.done_fut.clone()
    }

    pub fn take_health_rx(&mut self) -> Option<output_pipeline::HealthReceiver> {
        self.health_rx.take()
    }

    pub async fn pause(&self) -> anyhow::Result<()> {
        Ok(self.actor_ref.ask(Pause).await?)
    }

    pub async fn resume(&self) -> anyhow::Result<()> {
        Ok(self.actor_ref.ask(Resume).await?)
    }

    pub async fn cancel(&self) -> anyhow::Result<()> {
        Ok(self.actor_ref.ask(Cancel).await?)
    }

    pub fn is_paused(&self) -> impl Future<Output = anyhow::Result<bool>> + Send + 'static + use<> {
        let actor_ref = self.actor_ref.clone();
        async move { Ok(actor_ref.ask(IsPaused).await?) }
    }

    pub fn take_segment_rx(
        &self,
    ) -> Option<std::sync::mpsc::Receiver<cap_enc_ffmpeg::segmented_stream::SegmentCompletedEvent>>
    {
        self.segment_rx
            .as_ref()
            .and_then(|m| m.lock().ok().and_then(|mut guard| guard.take()))
    }
}

impl Drop for ActorHandle {
    fn drop(&mut self) {
        let actor_ref = self.actor_ref.clone();
        #[cfg(target_os = "linux")]
        {
            if self.lifecycle.quiescence() == InstantQuiescence::Joined {
                return;
            }
            if self.lifecycle.quiescence() == InstantQuiescence::Pending {
                self.lifecycle
                    .0
                    .scope
                    .fail_required("Instant handle dropped before shutdown acknowledgement".into());
            }
            self.lifecycle.cancel();
            self.lifecycle.spawn(async move {
                let _ = actor_ref.ask(Cancel).await;
            });
        }
        #[cfg(not(target_os = "linux"))]
        tokio::spawn(async move {
            let _ = actor_ref.tell(Stop).await;
        });
    }
}

#[derive(kameo::Actor)]
pub struct Actor {
    diagnostic: Option<cap_utils::operation_diagnostics::Operation>,
    recording_dir: PathBuf,
    output_dir: PathBuf,
    capture_target: ScreenCaptureTarget,
    video_info: VideoInfo,
    state: ActorState,
    total_pause_duration: std::time::Duration,
    pause_started_at: Option<f64>,
    terminal_stop_error: Option<String>,
    #[cfg(target_os = "linux")]
    lifetime: InstantLifetimeOwner,
}

impl Actor {
    #[cfg(target_os = "linux")]
    async fn stop(&mut self) -> anyhow::Result<()> {
        self.lifetime.lifecycle.0.scope.cancel();
        let pipeline = std::mem::replace(&mut self.state, ActorState::Stopped);
        let mut errors = Vec::new();
        if let ActorState::Recording { pipeline, .. } | ActorState::Paused { pipeline, .. } =
            pipeline
        {
            let video = pipeline.video.stop();
            let audio = async {
                match pipeline.audio {
                    Some(audio) => audio.stop().await.map(|_| ()),
                    None => Ok(()),
                }
            };
            let (video, audio) = tokio::join!(video, audio);
            if let Err(error) = video {
                errors.push(format!("Video pipeline: {error:#}"));
            }
            if let Err(error) = audio {
                errors.push(format!("Audio pipeline: {error:#}"));
            }
        }
        let report = self
            .lifetime
            .lifecycle
            .0
            .scope
            .cancel_and_join_report()
            .await;
        if let Some(error) = &report.error {
            errors.push(error.clone());
        }
        let result = if errors.is_empty() {
            Ok(())
        } else {
            Err(anyhow::anyhow!(errors.join("; ")))
        };
        let result = preserve_terminal_stop_error(&mut self.terminal_stop_error, result);
        let lifecycle_result = self
            .lifetime
            .lifecycle
            .complete(report, self.terminal_stop_error.clone());
        result.and(lifecycle_result)
    }

    #[cfg(not(target_os = "linux"))]
    async fn stop(&mut self) -> anyhow::Result<()> {
        if let Some(error) = &self.terminal_stop_error {
            return Err(anyhow::anyhow!(error.clone()));
        }
        let pipeline = replace_with::replace_with_or_abort_and_return(&mut self.state, |state| {
            (
                match state {
                    ActorState::Recording { pipeline, .. } => Some(pipeline),
                    ActorState::Paused { pipeline, .. } => Some(pipeline),
                    _ => None,
                },
                ActorState::Stopped,
            )
        });

        let result = async {
            if let Some(pipeline) = pipeline {
                if let Some(audio) = pipeline.audio {
                    let (audio_res, video_res) = tokio::join!(audio.stop(), pipeline.video.stop());
                    video_res?;
                    audio_res?;
                } else {
                    pipeline.video.stop().await?;
                }
            }
            Ok(())
        }
        .await;
        preserve_terminal_stop_error(&mut self.terminal_stop_error, result)
    }
}

fn preserve_terminal_stop_error(
    stored: &mut Option<String>,
    result: anyhow::Result<()>,
) -> anyhow::Result<()> {
    if let Some(error) = stored.as_ref() {
        return Err(anyhow::anyhow!(error.clone()));
    }
    if let Err(error) = &result {
        *stored = Some(format!("{error:#}"));
    }
    result
}

impl Message<Stop> for Actor {
    type Reply = anyhow::Result<CompletedRecording>;

    async fn handle(&mut self, _: Stop, _: &mut Context<Self, Self::Reply>) -> Self::Reply {
        if let Some(diagnostic) = &mut self.diagnostic {
            diagnostic.stage("finalizing");
        }
        let result = self.complete_recording().await;
        if let Some(mut diagnostic) = self.diagnostic.take() {
            if let Ok(recording) = &result {
                diagnostic.field(cap_utils::operation_diagnostics::Field::label(
                    "output_health",
                    match recording.health {
                        crate::RecordingHealth::Healthy => "healthy",
                        crate::RecordingHealth::Repaired { .. } => "repaired",
                        crate::RecordingHealth::Degraded { .. } => "degraded",
                        crate::RecordingHealth::Damaged { .. } => "damaged",
                    },
                ));
            }
            diagnostic.finish(result.is_ok());
        }
        result
    }
}

impl Actor {
    async fn complete_recording(&mut self) -> anyhow::Result<CompletedRecording> {
        if let Some(pause_start) = self.pause_started_at.take() {
            let pause_elapsed = current_time_f64() - pause_start;
            if pause_elapsed > 0.0 {
                self.total_pause_duration += std::time::Duration::from_secs_f64(pause_elapsed);
            }
        }

        let (segments_dir, completion_audio) =
            replace_with::replace_with_or_abort_and_return(&mut self.state, |state| {
                let result = match &state {
                    ActorState::Recording { pipeline, .. }
                    | ActorState::Paused { pipeline, .. } => (
                        pipeline.segments_dir.clone(),
                        Some(pipeline.audio.is_some()),
                    ),
                    ActorState::Stopped => (self.output_dir.clone(), None),
                };
                (result, state)
            });

        self.stop().await?;

        let has_init = segments_dir.join("init.mp4").exists();
        let has_segments = has_init
            && match std::fs::read_dir(&segments_dir) {
                Ok(entries) => entries
                    .filter_map(Result::ok)
                    .any(|e| e.path().extension().is_some_and(|ext| ext == "m4s")),
                Err(e) => {
                    warn!(
                        path = %segments_dir.display(),
                        error = %e,
                        "Failed to read segments directory, treating as no segments"
                    );
                    false
                }
            };

        let has_output_mp4 = segments_dir.join("output.mp4").exists()
            && std::fs::metadata(segments_dir.join("output.mp4"))
                .map(|m| m.len() > 0)
                .unwrap_or(false);

        let health = if has_segments || has_output_mp4 {
            crate::RecordingHealth::Healthy
        } else if has_init {
            crate::RecordingHealth::Degraded {
                issues: vec!["Recording too short — no complete segments produced".to_string()],
            }
        } else {
            crate::RecordingHealth::Damaged {
                reason: "No video segments produced".to_string(),
            }
        };

        // Only successfully finished segmented mux workers certify this output, not device shutdown.
        let clean_completion = completion_audio
            .filter(|_| has_segments && segments_dir == self.recording_dir.join("content/display"))
            .map(|expected_audio| {
                CleanInstantRecording::new(self.recording_dir.clone(), expected_audio)
            });

        Ok(CompletedRecording {
            project_path: self.recording_dir.clone(),
            meta: InstantRecordingMeta::Complete {
                fps: self.video_info.fps(),
                sample_rate: None,
            },
            display_source: self.capture_target.clone(),
            health,
            clean_completion,
        })
    }
}

pub struct Pause;

impl Message<Pause> for Actor {
    type Reply = ();

    async fn handle(&mut self, _: Pause, _: &mut Context<Self, Self::Reply>) -> Self::Reply {
        self.pause_started_at = Some(current_time_f64());
        replace_with::replace_with_or_abort(&mut self.state, |state| {
            if let ActorState::Recording {
                pipeline,
                segment_start_time,
            } = state
            {
                pipeline.video.pause();
                if let Some(ref audio) = pipeline.audio {
                    audio.pause();
                }
                return ActorState::Paused {
                    pipeline,
                    segment_start_time,
                };
            }

            state
        });
        if matches!(self.state, ActorState::Paused { .. })
            && let Some(diagnostic) = &mut self.diagnostic
        {
            diagnostic.stage("paused");
        }
    }
}

pub struct Resume;

impl Message<Resume> for Actor {
    type Reply = ();

    async fn handle(&mut self, _: Resume, _: &mut Context<Self, Self::Reply>) -> Self::Reply {
        if let Some(pause_start) = self.pause_started_at.take() {
            let pause_elapsed = current_time_f64() - pause_start;
            if pause_elapsed > 0.0 {
                self.total_pause_duration += std::time::Duration::from_secs_f64(pause_elapsed);
            }
        }
        replace_with::replace_with_or_abort(&mut self.state, |state| {
            if let ActorState::Paused {
                pipeline,
                segment_start_time,
            } = state
            {
                pipeline.video.resume();
                if let Some(ref audio) = pipeline.audio {
                    audio.resume();
                }
                return ActorState::Recording {
                    pipeline,
                    segment_start_time,
                };
            }

            state
        });
        if matches!(self.state, ActorState::Recording { .. })
            && let Some(diagnostic) = &mut self.diagnostic
        {
            diagnostic.stage("recording");
        }
    }
}

pub struct Cancel;

impl Message<Cancel> for Actor {
    type Reply = anyhow::Result<()>;

    async fn handle(&mut self, _: Cancel, _: &mut Context<Self, Self::Reply>) -> Self::Reply {
        if let Some(diagnostic) = &mut self.diagnostic {
            diagnostic.stage("cancelling");
        }
        let result = self.stop().await;
        if let Some(diagnostic) = self.diagnostic.take() {
            diagnostic.finish(result.is_ok());
        }
        result
    }
}

pub struct IsPaused;

impl Message<IsPaused> for Actor {
    type Reply = bool;

    async fn handle(&mut self, _: IsPaused, _: &mut Context<Self, Self::Reply>) -> Self::Reply {
        matches!(self.state, ActorState::Paused { .. })
    }
}

#[derive(Debug)]
pub struct CompletedRecording {
    pub project_path: PathBuf,
    pub display_source: ScreenCaptureTarget,
    pub meta: InstantRecordingMeta,
    pub health: crate::RecordingHealth,
    pub clean_completion: Option<CleanInstantRecording>,
}

struct ScreenPipelineInput {
    source: crate::sources::screen_capture::VideoSourceConfig,
    info: VideoInfo,
    #[cfg(target_os = "linux")]
    prepared_camera: Option<linux_camera::PreparedCamera>,
}

async fn create_pipeline(
    content_dir: PathBuf,
    screen: ScreenPipelineInput,
    mic_feed: Option<Arc<MicrophoneFeedLock>>,
    system_audio_source: Option<crate::sources::screen_capture::SystemAudioSourceConfig>,
    max_output_size: Option<u32>,
    start_time: Timestamps,
    start_gate: Option<RecordingStartGate>,
) -> anyhow::Result<Pipeline> {
    // Instant merges its screen and audio tracks by timestamp, and gated
    // audio starts at the arm point, so the screen must start there too.
    if let Some(gate) = &start_gate {
        gate.set_video_origin_at_arm();
    }
    let ScreenPipelineInput {
        source: screen_capture,
        info: screen_info,
        #[cfg(target_os = "linux")]
        prepared_camera,
    } = screen;
    let output_resolution = max_output_size
        .map(|max_output_size| {
            clamp_size(
                (screen_info.width, screen_info.height),
                (
                    max_output_size,
                    (max_output_size as f64 / 16.0 * 9.0) as u32,
                ),
            )
        })
        .unwrap_or_else(|| {
            (
                ensure_even(screen_info.width),
                ensure_even(screen_info.height),
            )
        });

    let segments_dir = content_dir.join("display");

    let segment_channel = {
        let (tx, rx) =
            std::sync::mpsc::channel::<cap_enc_ffmpeg::segmented_stream::SegmentCompletedEvent>();
        Some((tx, rx))
    };

    let segment_tx_for_video = segment_channel.as_ref().map(|(tx, _)| tx.clone());

    #[cfg(not(target_os = "linux"))]
    let video = ScreenCaptureMethod::make_instant_segmented_video_pipeline(
        screen_capture,
        segments_dir.clone(),
        output_resolution,
        start_time,
        start_gate.clone(),
        segment_tx_for_video,
    )
    .await?;

    #[cfg(target_os = "linux")]
    let video = if let Some(camera) = prepared_camera {
        OutputPipeline::builder(segments_dir.clone())
            .with_video::<linux_camera::CameraCompositeSource>(linux_camera::Config {
                screen_capture,
                camera,
            })
            .with_timestamps(start_time)
            .with_start_gate(start_gate.clone())
            .build::<crate::ffmpeg::SegmentedVideoMuxer>(crate::ffmpeg::SegmentedVideoMuxerConfig {
                timed_fragments: false,
                segment_duration: std::time::Duration::from_secs(2),
                preset: cap_enc_ffmpeg::h264::H264Preset::Ultrafast,
                output_size: Some(output_resolution),
                shared_pause_state: None,
                segment_tx: segment_tx_for_video,
            })
            .await?
    } else {
        ScreenCaptureMethod::make_instant_segmented_video_pipeline(
            screen_capture,
            segments_dir.clone(),
            output_resolution,
            start_time,
            start_gate.clone(),
            segment_tx_for_video,
        )
        .await?
    };

    let has_audio = mic_feed.is_some() || system_audio_source.is_some();
    let audio = if has_audio {
        let audio_dir = content_dir.join("audio");
        let mut builder = output_pipeline::OutputPipeline::builder(audio_dir.clone())
            .with_timestamps(start_time)
            .with_start_gate(start_gate.clone());
        // Behind a start gate, zero is the gate's arm time, which the screen
        // track also starts at (within a frame), not the first audio sample:
        // a mic that becomes ready late, or loopback system audio that
        // delivers only while sound plays, would otherwise move all audio
        // early. Without a gate the screen starts at its first encoded frame,
        // after capture setup, so the epoch would put audio late instead;
        // only Linux, whose video also starts at the epoch, anchors there.
        if start_gate.is_some() || cfg!(target_os = "linux") {
            builder = builder.with_audio_anchor(output_pipeline::AudioAnchor::PipelineEpoch);
        }

        if let Some(sys_audio) = system_audio_source {
            builder = builder
                .with_audio_source::<crate::sources::screen_capture::SystemAudioSource>(sys_audio);
        }

        if let Some(mic) = mic_feed {
            builder = builder.with_audio_source::<crate::sources::Microphone>(mic);
        }

        let segment_tx_for_audio = segment_channel.as_ref().map(|(tx, _)| tx.clone());

        let audio_pipeline = builder
            .build::<output_pipeline::DashSegmentedAudioMuxer>(
                output_pipeline::DashSegmentedAudioMuxerConfig {
                    shared_pause_state: None,
                    segment_tx: segment_tx_for_audio,
                    write_behind: cfg!(target_os = "macos"),
                    ..Default::default()
                },
            )
            .await
            .context("audio pipeline setup")?;

        Some(audio_pipeline)
    } else {
        None
    };

    let segment_rx = segment_channel.map(|(_, rx)| rx);

    Ok(Pipeline {
        video,
        audio,
        video_info: VideoInfo::from_raw_ffmpeg(
            screen_info.pixel_format,
            output_resolution.0,
            output_resolution.1,
            screen_info.fps(),
        ),
        segments_dir,
        segment_rx,
    })
}

impl Actor {
    pub fn builder(output: PathBuf, capture_target: ScreenCaptureTarget) -> ActorBuilder {
        ActorBuilder::new(output, capture_target)
    }
}

pub struct ActorBuilder {
    output_path: PathBuf,
    capture_target: ScreenCaptureTarget,
    window_only: bool,
    system_audio: bool,
    mic_feed: Option<Arc<MicrophoneFeedLock>>,
    camera_feed: Option<Arc<crate::feeds::camera::CameraFeedLock>>,
    #[cfg(target_os = "linux")]
    composite_camera: bool,
    #[cfg(target_os = "linux")]
    camera_presentation: Option<LinuxCameraPresentation>,
    #[cfg(target_os = "linux")]
    processed_camera: Option<LinuxProcessedCameraSource>,
    #[cfg(target_os = "linux")]
    camera_reference_size: Option<(u32, u32)>,
    max_output_size: Option<u32>,
    max_fps: u32,
    #[cfg(target_os = "macos")]
    excluded_windows: Vec<scap_targets::WindowId>,
    #[cfg(target_os = "linux")]
    lifetime: InstantLifetimeOwner,
    start_gate: Option<RecordingStartGate>,
}

impl ActorBuilder {
    pub fn new(output: PathBuf, capture_target: ScreenCaptureTarget) -> Self {
        Self {
            output_path: output,
            capture_target,
            window_only: false,
            system_audio: false,
            mic_feed: None,
            camera_feed: None,
            #[cfg(target_os = "linux")]
            composite_camera: false,
            #[cfg(target_os = "linux")]
            camera_presentation: None,
            #[cfg(target_os = "linux")]
            processed_camera: None,
            #[cfg(target_os = "linux")]
            camera_reference_size: None,
            max_output_size: None,
            max_fps: crate::defaults::DEFAULT_INSTANT_MODE_FPS,
            #[cfg(target_os = "linux")]
            lifetime: InstantLifetimeOwner::new(),
            #[cfg(target_os = "macos")]
            excluded_windows: Vec::new(),
            start_gate: None,
        }
    }

    /// Prime the capture pipeline ahead of the start cue; nothing is recorded
    /// until the gate is armed. See [`RecordingStartGate`].
    pub fn with_start_gate(mut self, start_gate: RecordingStartGate) -> Self {
        self.start_gate = Some(start_gate);
        self
    }

    #[cfg(target_os = "linux")]
    pub fn lifecycle(&self) -> InstantLifecycle {
        self.lifetime.lifecycle.clone()
    }

    pub fn with_system_audio(mut self, system_audio: bool) -> Self {
        self.system_audio = system_audio;
        self
    }

    /// Record only the target window, following it, on macOS and Windows.
    /// Ignored while a camera is attached there: Instant has no camera
    /// compositing on those platforms, so the camera bubble only reaches
    /// the video because the screen capture records it.
    pub fn with_window_only(mut self, window_only: bool) -> Self {
        self.window_only = window_only;
        self
    }

    pub fn with_mic_feed(mut self, mic_feed: Arc<MicrophoneFeedLock>) -> Self {
        self.mic_feed = Some(mic_feed);
        self
    }

    pub fn with_camera_feed(
        mut self,
        camera_feed: Arc<crate::feeds::camera::CameraFeedLock>,
    ) -> Self {
        self.camera_feed = Some(camera_feed);
        self
    }

    pub fn with_max_output_size(mut self, max_output_size: u32) -> Self {
        self.max_output_size = Some(max_output_size);
        self
    }

    #[cfg(target_os = "linux")]
    pub fn with_linux_camera_composition(mut self) -> Self {
        self.composite_camera = true;
        self
    }

    #[cfg(target_os = "linux")]
    pub fn with_linux_camera_presentation(mut self, presentation: LinuxCameraPresentation) -> Self {
        self.composite_camera = true;
        self.camera_presentation = Some(presentation);
        self
    }

    #[cfg(target_os = "linux")]
    pub fn with_linux_processed_camera(
        mut self,
        source: LinuxProcessedCameraSource,
        presentation: LinuxCameraPresentation,
        reference_size: (u32, u32),
    ) -> Self {
        self.composite_camera = true;
        self.camera_presentation = Some(presentation);
        self.processed_camera = Some(source);
        self.camera_reference_size = Some(reference_size);
        self
    }

    pub fn with_max_fps(mut self, max_fps: u32) -> Self {
        self.max_fps = max_fps.clamp(1, 120);
        self
    }

    #[cfg(target_os = "macos")]
    pub fn with_excluded_windows(mut self, excluded_windows: Vec<scap_targets::WindowId>) -> Self {
        self.excluded_windows = excluded_windows;
        self
    }

    pub async fn build(
        self,
        #[cfg(target_os = "macos")] shareable_content: Option<SendableShareableContent>,
    ) -> anyhow::Result<ActorHandle> {
        spawn_instant_recording_actor_inner(
            self.output_path,
            RecordingBaseInputs {
                capture_target: self.capture_target,
                window_only: self.window_only,
                capture_system_audio: self.system_audio,
                mic_feed: self.mic_feed,
                camera_feed: self.camera_feed,
                start_gate: self.start_gate,
                #[cfg(target_os = "macos")]
                shareable_content,
                #[cfg(target_os = "macos")]
                excluded_windows: self.excluded_windows,
            },
            self.max_output_size,
            self.max_fps,
            #[cfg(target_os = "linux")]
            LinuxCameraConfig {
                composite_camera: self.composite_camera,
                camera_presentation: self.camera_presentation,
                processed_camera: self.processed_camera,
                camera_reference_size: self.camera_reference_size,
            },
            #[cfg(target_os = "linux")]
            self.lifetime,
        )
        .await
    }
}

pub async fn spawn_instant_recording_actor(
    recording_dir: PathBuf,
    inputs: RecordingBaseInputs,
    max_output_size: Option<u32>,
    max_fps: u32,
) -> anyhow::Result<ActorHandle> {
    spawn_instant_recording_actor_inner(
        recording_dir,
        inputs,
        max_output_size,
        max_fps,
        #[cfg(target_os = "linux")]
        LinuxCameraConfig::default(),
        #[cfg(target_os = "linux")]
        InstantLifetimeOwner::new(),
    )
    .await
}

#[cfg(target_os = "linux")]
#[derive(Default)]
struct LinuxCameraConfig {
    composite_camera: bool,
    camera_presentation: Option<LinuxCameraPresentation>,
    processed_camera: Option<LinuxProcessedCameraSource>,
    camera_reference_size: Option<(u32, u32)>,
}

#[cfg(target_os = "linux")]
async fn run_owned_instant_build<T: Send + 'static>(
    mut owner: InstantLifetimeOwner,
    build: impl Future<Output = anyhow::Result<T>> + Send + 'static,
) -> anyhow::Result<T> {
    let lifecycle = owner.lifecycle.clone();
    *lifecycle.0.runtime.lock().unwrap() = Some(tokio::runtime::Handle::current());
    let scope = lifecycle.0.scope.clone();
    let mut waiter = BuildWaiter {
        lifecycle: lifecycle.clone(),
        armed: true,
    };
    let startup = scope.task_completion();
    let (sender, receiver) = tokio::sync::oneshot::channel();
    drop(tokio::spawn(async move {
        let cancel = scope.cancellation();
        let result = scope.run(async {
            tokio::select! {
                biased;
                _ = cancel.cancelled() => Err(anyhow::anyhow!("Instant recording startup cancelled")),
                result = std::panic::AssertUnwindSafe(build).catch_unwind() => {
                    result.unwrap_or_else(|_| Err(anyhow::anyhow!("Instant recording startup panicked")))
                }
            }
        }).await;
        drop(startup);
        let result = match result {
            Ok(value) if !cancel.is_cancelled() => {
                owner.armed = false;
                drop(owner);
                Ok(value)
            }
            result => {
                let message = match result {
                    Ok(value) => {
                        drop(value);
                        "Instant recording startup cancelled".to_string()
                    }
                    Err(error) => format!("{error:#}"),
                };
                let quiescence = owner.failed(message.clone()).await;
                Err(anyhow::anyhow!(
                    "{message}; capture cleanup: {quiescence:?}"
                ))
            }
        };
        let _ = sender.send(result);
    }));
    let result = receiver
        .await
        .context("Instant recording startup acknowledgement lost")?;
    waiter.armed = false;
    result
}

#[cfg(target_os = "linux")]
async fn spawn_instant_recording_actor_inner(
    recording_dir: PathBuf,
    inputs: RecordingBaseInputs,
    max_output_size: Option<u32>,
    max_fps: u32,
    camera: LinuxCameraConfig,
    owner: InstantLifetimeOwner,
) -> anyhow::Result<ActorHandle> {
    let lifecycle = owner.lifecycle.clone();
    run_owned_instant_build(
        owner,
        build_instant_recording_actor(
            recording_dir,
            inputs,
            max_output_size,
            max_fps,
            camera,
            lifecycle,
        ),
    )
    .await
}

#[cfg(not(target_os = "linux"))]
async fn spawn_instant_recording_actor_inner(
    recording_dir: PathBuf,
    inputs: RecordingBaseInputs,
    max_output_size: Option<u32>,
    max_fps: u32,
) -> anyhow::Result<ActorHandle> {
    let startup = build_instant_recording_actor(recording_dir, inputs, max_output_size, max_fps);
    #[cfg(windows)]
    {
        let scope = output_pipeline::PipelineBuildScope::new();
        output_pipeline::finish_pipeline_startup(&scope, startup).await
    }
    #[cfg(not(windows))]
    startup.await
}

#[tracing::instrument("instant_recording", skip_all)]
async fn build_instant_recording_actor(
    recording_dir: PathBuf,
    inputs: RecordingBaseInputs,
    max_output_size: Option<u32>,
    max_fps: u32,
    #[cfg(target_os = "linux")] camera: LinuxCameraConfig,
    #[cfg(target_os = "linux")] lifecycle: InstantLifecycle,
) -> anyhow::Result<ActorHandle> {
    use cap_utils::operation_diagnostics::{Field, Operation};
    let mut diagnostic = Operation::start(
        "instant_recording",
        &[
            Field::identifier(
                "resource",
                cap_utils::operation_diagnostics::resource_id(&recording_dir),
            ),
            Field::number("requested_fps", max_fps as u64),
            Field::flag("system_audio", inputs.capture_system_audio),
            Field::flag("microphone", inputs.mic_feed.is_some()),
            Field::flag("camera", inputs.camera_feed.is_some()),
        ],
    );
    if let Some(microphone) = &inputs.mic_feed {
        let info = microphone.audio_info();
        diagnostic.field(Field::number(
            "microphone_sample_rate",
            info.sample_rate as u64,
        ));
        diagnostic.field(Field::number("microphone_channels", info.channels as u64));
        diagnostic.field(Field::flag(
            "microphone_wireless",
            info.is_wireless_transport,
        ));
    }
    if let Some(camera) = &inputs.camera_feed {
        let info = camera.video_info();
        diagnostic.field(Field::number("camera_width", info.width as u64));
        diagnostic.field(Field::number("camera_height", info.height as u64));
        diagnostic.field(Field::number(
            "camera_fps_numerator",
            info.frame_rate.0 as u64,
        ));
        diagnostic.field(Field::number(
            "camera_fps_denominator",
            info.frame_rate.1 as u64,
        ));
    }
    diagnostic.stage("initializing_capture");

    #[cfg(target_os = "linux")]
    anyhow::ensure!(
        !matches!(inputs.capture_target, ScreenCaptureTarget::CameraOnly)
            || !inputs.capture_system_audio,
        "System audio is not supported for Linux Instant CameraOnly recordings. Disable system audio or choose a screen target."
    );
    #[cfg(target_os = "linux")]
    let LinuxCameraConfig {
        composite_camera,
        camera_presentation,
        processed_camera,
        camera_reference_size,
    } = camera;
    #[cfg(target_os = "linux")]
    if camera_presentation.is_some() && inputs.camera_feed.is_none() {
        return Err(LinuxCameraPresentationError::MissingCamera.into());
    }
    #[cfg(target_os = "linux")]
    if camera_presentation.is_some()
        && matches!(inputs.capture_target, ScreenCaptureTarget::CameraOnly)
    {
        return Err(LinuxCameraPresentationError::UnsupportedTarget.into());
    }
    ensure_dir(&recording_dir)?;

    let timestamps = Timestamps::now();

    trace!("creating recording actor");

    let content_dir = ensure_dir(&recording_dir.join("content"))?;

    #[cfg(windows)]
    cap_mediafoundation_utils::thread_init();

    let (mut pipeline, video_info) = match inputs.capture_target {
        ScreenCaptureTarget::CameraOnly => {
            #[cfg(target_os = "linux")]
            {
                let camera_feed = inputs.camera_feed.clone().ok_or_else(|| {
                    anyhow::anyhow!(
                        "Camera-only recording requires a camera, but no camera is currently available. \
                        Please select a camera in the recording settings before starting. \
                        If you have already selected a camera, it may have been disconnected or \
                        failed to initialize. Try reconnecting your camera or selecting a different one."
                    )
                })?;

                let output_path = content_dir.join("output.mp4");

                let mut builder = OutputPipeline::builder(output_path.clone())
                    .with_video::<crate::sources::Camera>(camera_feed.clone())
                    .with_timestamps(timestamps);

                if let Some(mic_feed) = inputs.mic_feed.clone() {
                    builder = builder.with_audio_source::<crate::sources::Microphone>(mic_feed);
                }

                let cam_pipeline = builder
                    .build::<output_pipeline::Mp4Muxer>(())
                    .await
                    .context("camera-only pipeline setup")?;

                let video_info = *camera_feed.video_info();
                (
                    Pipeline {
                        video: cam_pipeline,
                        audio: None,
                        video_info,
                        segments_dir: content_dir.clone(),
                        segment_rx: None,
                    },
                    video_info,
                )
            }

            #[cfg(any(target_os = "macos", windows))]
            {
                let camera_feed = inputs.camera_feed.clone().ok_or_else(|| {
                    anyhow::anyhow!(
                        "Camera-only recording requires a camera, but no camera is currently available. \
                        Please select a camera in the recording settings before starting. \
                        If you have already selected a camera, it may have been disconnected or \
                        failed to initialize. Try reconnecting your camera or selecting a different one."
                    )
                })?;

                let output_path = content_dir.join("output.mp4");

                let mut builder = OutputPipeline::builder(output_path.clone())
                    .with_video::<crate::sources::NativeCamera>(camera_feed.clone())
                    .with_timestamps(timestamps)
                    .with_start_gate(inputs.start_gate.clone());

                if let Some(mic_feed) = inputs.mic_feed.clone() {
                    builder = builder.with_audio_source::<crate::sources::Microphone>(mic_feed);
                }

                #[cfg(target_os = "macos")]
                let cam_pipeline = builder
                    .build::<output_pipeline::AVFoundationCameraMuxer>(
                        output_pipeline::AVFoundationCameraMuxerConfig {
                            instant_mode: true,
                            ..Default::default()
                        },
                    )
                    .await
                    .context("camera-only pipeline setup")?;

                #[cfg(windows)]
                let cam_pipeline = builder
                    .build::<output_pipeline::WindowsCameraMuxer>(
                        output_pipeline::WindowsCameraMuxerConfig {
                            encoder_preferences:
                                crate::capture_pipeline::EncoderPreferences::default(),
                            ..Default::default()
                        },
                    )
                    .await
                    .context("camera-only pipeline setup")?;

                let video_info = *camera_feed.video_info();
                (
                    Pipeline {
                        video: cam_pipeline,
                        audio: None,
                        video_info,
                        segments_dir: content_dir.clone(),
                        segment_rx: None,
                    },
                    video_info,
                )
            }
        }
        _ => {
            #[cfg(windows)]
            let d3d_device = crate::capture_pipeline::create_d3d_device()?;

            let (display, crop_bounds) = target_to_display_and_crop(&inputs.capture_target)
                .context("target_display_crop")?;

            #[cfg(target_os = "macos")]
            let max_capture_size = max_output_size.and_then(|max_output_size| {
                inputs.capture_target.physical_size().map(|size| {
                    capture_size_constraint(
                        (size.width() as u32, size.height() as u32),
                        max_output_size,
                    )
                })
            });
            #[cfg(not(target_os = "macos"))]
            let max_capture_size = None;

            #[cfg(any(target_os = "macos", windows))]
            let capture_window = instant_capture_window(
                &inputs.capture_target,
                inputs.window_only,
                inputs.camera_feed.is_some(),
            );

            let screen_source = ScreenCaptureConfig::<ScreenCaptureMethod>::init(
                display,
                crop_bounds,
                true,
                max_fps,
                max_capture_size,
                timestamps.system_time(),
                inputs.capture_system_audio,
                #[cfg(any(target_os = "macos", windows))]
                capture_window,
                #[cfg(target_os = "linux")]
                crate::sources::screen_capture::LinuxCaptureSource::from_target(
                    &inputs.capture_target,
                ),
                #[cfg(windows)]
                d3d_device,
                #[cfg(target_os = "macos")]
                inputs
                    .shareable_content
                    .clone()
                    .ok_or_else(|| anyhow::anyhow!("Missing shareable content"))?,
                #[cfg(target_os = "macos")]
                inputs.excluded_windows,
            )
            .await
            .context("screen capture init")?;

            debug!("screen capture: {screen_source:#?}");

            #[cfg(not(target_os = "linux"))]
            let screen_info = screen_source.info();
            let (screen_capture, system_audio_source) = screen_source.to_sources().await?;
            #[cfg(target_os = "linux")]
            let screen_info = screen_capture.video_info();
            #[cfg(target_os = "linux")]
            let (prepared_camera, timestamps) = if let Some(camera_feed) =
                inputs.camera_feed.clone().filter(|_| composite_camera)
            {
                let (camera, timestamps) = linux_camera::PreparedCamera::prepare(
                    camera_feed,
                    camera_presentation,
                    processed_camera,
                    camera_reference_size,
                    screen_info,
                )
                .await?;
                (Some(camera), timestamps)
            } else {
                (None, Timestamps::now())
            };

            let pipeline = create_pipeline(
                content_dir.clone(),
                ScreenPipelineInput {
                    source: screen_capture,
                    info: screen_info,
                    #[cfg(target_os = "linux")]
                    prepared_camera,
                },
                inputs.mic_feed.clone(),
                system_audio_source,
                max_output_size,
                timestamps,
                inputs.start_gate.clone(),
            )
            .await?;

            let video_info = pipeline.video_info;

            (pipeline, video_info)
        }
    };

    let segment_start_time = current_time_f64();

    trace!("spawning recording actor");

    let segment_rx = pipeline.segment_rx.take();
    let output_dir = pipeline.segments_dir.clone();
    #[cfg(not(target_os = "linux"))]
    let done_fut = pipeline.video.done_fut();
    #[cfg(target_os = "linux")]
    let video_done = pipeline.video.done_fut();
    #[cfg(target_os = "linux")]
    let audio_done = pipeline.audio.as_ref().map(OutputPipeline::done_fut);
    #[cfg(target_os = "linux")]
    let done_fut = lifecycle.done_fut();
    let health_rx = pipeline.video.take_health_rx();
    diagnostic.stage("recording");
    let actor_ref = Actor::spawn(Actor {
        diagnostic: Some(diagnostic),
        recording_dir,
        output_dir,
        capture_target: inputs.capture_target.clone(),
        video_info,
        state: ActorState::Recording {
            pipeline,
            segment_start_time,
        },
        total_pause_duration: std::time::Duration::ZERO,
        pause_started_at: None,
        terminal_stop_error: None,
        #[cfg(target_os = "linux")]
        lifetime: InstantLifetimeOwner {
            lifecycle: lifecycle.clone(),
            armed: true,
        },
    });

    let actor_handle = ActorHandle {
        #[cfg(target_os = "linux")]
        lifecycle: lifecycle.clone(),
        actor_ref: actor_ref.clone(),
        capture_target: inputs.capture_target,
        done_fut: done_fut.clone(),
        health_rx,
        segment_rx: segment_rx.map(|rx| std::sync::Mutex::new(Some(rx))),
    };

    #[cfg(not(target_os = "linux"))]
    tokio::spawn(async move {
        let _ = done_fut.await;
        let _ = actor_ref.ask(Stop).await;
    });
    #[cfg(target_os = "linux")]
    watch_instant_tracks(lifecycle, actor_ref, video_done, audio_done);

    Ok(actor_handle)
}

#[cfg(target_os = "linux")]
fn watch_instant_tracks(
    lifecycle: InstantLifecycle,
    actor_ref: kameo::actor::ActorRef<Actor>,
    video_done: output_pipeline::DoneFut,
    audio_done: Option<output_pipeline::DoneFut>,
) {
    drop(tokio::spawn(async move {
        let cancel = lifecycle.0.scope.cancellation();
        let audio = async {
            match audio_done {
                Some(done) => done.await,
                None => std::future::pending().await,
            }
        };
        let result = tokio::select! {
            _ = cancel.cancelled() => None,
            result = video_done => Some(("Video", result)),
            result = audio => Some(("Audio", result)),
        };
        if let Some((track, result)) = result {
            match result {
                Err(error) => lifecycle
                    .0
                    .scope
                    .fail_required(format!("{track} pipeline failed: {error}")),
                Ok(()) if !cancel.is_cancelled() => lifecycle
                    .0
                    .scope
                    .fail_required(format!("Required {track} pipeline ended before Stop")),
                Ok(()) => {}
            }
        }
        let _ = actor_ref.ask(Cancel).await;
    }));
}

fn current_time_f64() -> f64 {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_secs_f64()
}

#[cfg(target_os = "macos")]
fn capture_size_constraint(input: (u32, u32), max_output_size: u32) -> (u32, u32) {
    let aspect_ratio = input.0 as f64 / input.1 as f64;
    let max_short_edge = (max_output_size as f64 / 16.0 * 9.0) as u32;

    if input.0 >= input.1 && aspect_ratio <= 16.0 / 9.0 {
        (max_output_size, u32::MAX)
    } else if input.0 <= input.1 && aspect_ratio >= 9.0 / 16.0 {
        (u32::MAX, max_output_size)
    } else if input.0 >= input.1 {
        (u32::MAX, max_short_edge)
    } else {
        (max_short_edge, u32::MAX)
    }
}

fn clamp_size(input: (u32, u32), max: (u32, u32)) -> (u32, u32) {
    // 16/9-ish
    if input.0 >= input.1 && (input.0 as f64 / input.1 as f64) <= 16.0 / 9.0 {
        let width = ensure_even(max.0.min(input.0));

        let height_ratio = input.1 as f64 / input.0 as f64;
        let height = ensure_even((height_ratio * width as f64).round() as u32);

        (width, height)
    }
    // 9/16-ish
    else if input.0 <= input.1 && (input.0 as f64 / input.1 as f64) >= 9.0 / 16.0 {
        let height = ensure_even(max.0.min(input.1));

        let width_ratio = input.0 as f64 / input.1 as f64;
        let width = ensure_even((width_ratio * height as f64).round() as u32);

        (width, height)
    }
    // ultrawide
    else if input.0 >= input.1 && (input.0 as f64 / input.1 as f64) > 16.0 / 9.0 {
        let height = ensure_even(max.1.min(input.1));

        let width_ratio = input.0 as f64 / input.1 as f64;
        let width = ensure_even((width_ratio * height as f64).round() as u32);

        (width, height)
    }
    // ultratall
    else if input.0 < input.1 && (input.0 as f64 / input.1 as f64) <= 9.0 / 16.0 {
        // swapped since max_width/height assume horizontal
        let width = ensure_even(max.1.min(input.0));

        let height_ratio = input.1 as f64 / input.0 as f64;
        let height = ensure_even((height_ratio * width as f64).round() as u32);

        (width, height)
    } else {
        unreachable!()
    }
}

// Instant mode on macOS and Windows has no camera compositing: the camera
// preview only reaches the video because the display capture records it, so a
// window-only capture would drop it.
#[cfg(any(target_os = "macos", windows))]
fn instant_capture_window(
    target: &ScreenCaptureTarget,
    window_only: bool,
    camera_attached: bool,
) -> Option<scap_targets::WindowId> {
    crate::window_only_target(target, window_only).filter(|_| !camera_attached)
}

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

    #[cfg(any(target_os = "macos", windows))]
    #[test]
    fn instant_captures_the_window_only_when_asked_and_without_a_camera() {
        let id: scap_targets::WindowId = "247".parse().unwrap();
        let window = ScreenCaptureTarget::Window { id: id.clone() };

        assert_eq!(instant_capture_window(&window, true, false), Some(id));
        assert_eq!(instant_capture_window(&window, true, true), None);
        assert_eq!(instant_capture_window(&window, false, false), None);
        assert_eq!(
            instant_capture_window(&ScreenCaptureTarget::CameraOnly, true, false),
            None
        );
    }

    #[cfg(target_os = "linux")]
    #[test]
    fn linux_presentation_builder_preserves_explicit_config_and_cli_default() {
        let request = LinuxCameraPresentation {
            rect: LinuxCameraRect {
                x: 10,
                y: 20,
                width: 40,
                height: 30,
            },
            shape: LinuxCameraShape::RoundedRectangle { radius_pixels: 4 },
            mirrored: true,
            effect: LinuxCameraEffect::None,
        };
        let configured = ActorBuilder::new(PathBuf::new(), ScreenCaptureTarget::CameraOnly)
            .with_linux_camera_presentation(request);
        assert!(configured.composite_camera);
        assert_eq!(configured.camera_presentation, Some(request));
        let default = ActorBuilder::new(PathBuf::new(), ScreenCaptureTarget::CameraOnly)
            .with_linux_camera_composition();
        assert!(default.composite_camera);
        assert!(default.camera_presentation.is_none());
    }

    #[tokio::test]
    async fn actor_retains_terminal_error_after_internal_stop() {
        let mut actor = Actor {
            diagnostic: None,
            recording_dir: PathBuf::new(),
            output_dir: PathBuf::new(),
            capture_target: ScreenCaptureTarget::CameraOnly,
            video_info: VideoInfo::from_raw_ffmpeg(ffmpeg::format::Pixel::RGBA, 4, 4, 30),
            state: ActorState::Stopped,
            total_pause_duration: std::time::Duration::ZERO,
            pause_started_at: None,
            terminal_stop_error: Some("Required camera disconnected".to_string()),
            #[cfg(target_os = "linux")]
            lifetime: InstantLifetimeOwner::new(),
        };
        for _ in 0..2 {
            assert!(
                actor
                    .stop()
                    .await
                    .unwrap_err()
                    .to_string()
                    .contains("Required camera disconnected")
            );
        }
    }

    #[test]
    fn repeated_stop_cannot_turn_pipeline_failure_into_complete() {
        let mut stored = None;
        assert!(
            super::preserve_terminal_stop_error(
                &mut stored,
                Err(anyhow::anyhow!("Required camera disconnected"))
            )
            .is_err()
        );
        assert!(
            super::preserve_terminal_stop_error(&mut stored, Ok(()))
                .unwrap_err()
                .to_string()
                .contains("Required camera disconnected")
        );
        assert!(super::preserve_terminal_stop_error(&mut stored, Ok(())).is_err());
    }

    #[test]
    fn successful_stop_remains_idempotent() {
        let mut stored = None;
        assert!(super::preserve_terminal_stop_error(&mut stored, Ok(())).is_ok());
        assert!(super::preserve_terminal_stop_error(&mut stored, Ok(())).is_ok());
        assert!(stored.is_none());
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn capture_size_constraint_preserves_instant_output_axis() {
        assert_eq!(
            capture_size_constraint((3024, 1964), 1920),
            (1920, u32::MAX)
        );
        assert_eq!(
            capture_size_constraint((1964, 3024), 1920),
            (u32::MAX, 1920)
        );
        assert_eq!(
            capture_size_constraint((5120, 1440), 1920),
            (u32::MAX, 1080)
        );
        assert_eq!(
            capture_size_constraint((1440, 5120), 1920),
            (1080, u32::MAX)
        );
    }

    #[test]
    fn test_clamp_size_16_9_ish_landscape() {
        assert_eq!(clamp_size((2880, 1800), (1920, 1080)), (1920, 1200));

        // Test 16:9 aspect ratio (boundary case)
        let result = clamp_size((1920, 1080), (1920, 1080));
        assert_eq!(result, (1920, 1080));

        // Test aspect ratio less than 16:9 (wider than tall, but not ultrawide)
        let result = clamp_size((1600, 1200), (1920, 1080)); // 4:3 ratio
        assert_eq!(result, (1600, 1200));

        // Test scaling down when input exceeds max width
        let result = clamp_size((2560, 1440), (1920, 1080)); // 16:9 ratio, needs scaling
        assert_eq!(result, (1920, 1080));
    }

    #[test]
    fn test_clamp_size_9_16_ish_portrait() {
        // Test 9:16 aspect ratio (boundary case)
        let result = clamp_size((1080, 1920), (1920, 1080));
        assert_eq!(result, (1080, 1920));

        // Test aspect ratio greater than 9:16 but still portrait
        let result = clamp_size((1200, 1600), (1920, 1080)); // 3:4 ratio
        assert_eq!(result, (1200, 1600));

        // Test square format (1:1 ratio) - should use portrait path when width <= height
        let result = clamp_size((1080, 1080), (1920, 1080));
        assert_eq!(result, (1080, 1080));
    }

    #[test]
    fn test_clamp_size_ultrawide() {
        // Test ultrawide aspect ratio (> 16:9)
        let result = clamp_size((2560, 1080), (1920, 1080)); // ~2.37:1 ratio
        assert_eq!(result, (2560, 1080));

        // Test very ultrawide
        let result = clamp_size((3440, 1440), (1920, 1080)); // ~2.39:1 ratio
        assert_eq!(result, (2580, 1080));

        // Test when height constraint is the limiting factor
        let result = clamp_size((3840, 1600), (1920, 1080)); // 2.4:1 ratio
        assert_eq!(result, (2592, 1080));

        // Test even number enforcement for height
        let result = clamp_size((2561, 1080), (1920, 1081)); // Odd max height
        assert_eq!(result, (2560, 1080)); // Height should be made even

        // Test even number enforcement for calculated width
        let result = clamp_size((2561, 1080), (1920, 1080)); // Results in odd width calculation
        assert_eq!(result, (2560, 1080)); // Width should be made even
    }

    #[test]
    fn test_clamp_size_ultratall() {
        // Test ultratall aspect ratio (< 9:16)
        let result = clamp_size((1080, 2560), (1920, 1920)); // ~9:21.3 ratio
        assert_eq!(result, (1080, 2560));

        // Test very ultratall that needs scaling
        let result = clamp_size((800, 3200), (1920, 2000)); // 1:4 ratio
        assert_eq!(result, (800, 3200));

        // Test when width constraint is the limiting factor (using max.1 as width limit)
        let result = clamp_size((500, 3000), (1920, 1000)); // Very tall, width limited by max.1
        assert_eq!(result, (500, 3000));

        // Test even number enforcement for width (using max.1)
        let result = clamp_size((500, 3000), (1920, 1001)); // Odd max.1 used as width
        assert_eq!(result, (500, 3000)); // Width should be made even

        // Test even number enforcement for calculated height
        let result = clamp_size((500, 3000), (1920, 1000)); // Results in odd height calculation
        assert_eq!(result, (500, 3000)); // Height should be made even
    }

    #[test]
    fn test_clamp_size_edge_cases() {
        // Test minimum sizes
        let result = clamp_size((2, 2), (1920, 1080));
        assert_eq!(result, (2, 2));

        // Test when input is smaller than max in all dimensions
        let result = clamp_size((800, 600), (1920, 1080));
        assert_eq!(result, (800, 600));

        // Test exact 16:9 boundary
        let sixteen_nine = 16.0 / 9.0;
        let width = 1920;
        let height = (width as f64 / sixteen_nine) as u32; // Should be exactly 1080
        let result = clamp_size((width, height), (1920, 1080));
        assert_eq!(result, (1920, 1080));

        // Test exact 9:16 boundary
        let nine_sixteen = 9.0 / 16.0;
        let height = 1920;
        let width = (height as f64 * nine_sixteen) as u32; // Should be exactly 1080
        let result = clamp_size((width, height), (1920, 1080));
        assert_eq!(result, (1080, 1920));
    }
}

#[cfg(all(test, target_os = "linux"))]
mod quiescence_tests {
    use super::*;
    use crate::output_pipeline::{
        AudioFrame, AudioMuxer, AudioSource, ChannelAudioSource, ChannelAudioSourceConfig,
        ChannelVideoSource, ChannelVideoSourceConfig, Muxer, SetupCtx, TaskPool, VideoFrame,
        VideoMuxer,
    };
    use cap_timestamp::Timestamp;
    use std::{
        sync::{
            Mutex,
            atomic::{AtomicBool, Ordering},
        },
        time::Duration,
    };

    #[derive(Clone, Copy)]
    struct Frame(Timestamp);
    impl VideoFrame for Frame {
        fn timestamp(&self) -> Timestamp {
            self.0
        }
    }

    #[derive(Clone)]
    struct Finalizer {
        entered: Arc<tokio::sync::Notify>,
        release: Arc<Mutex<Option<std::sync::mpsc::Receiver<()>>>>,
        finished: Arc<AtomicBool>,
        fail: bool,
    }
    impl Finalizer {
        fn new(fail: bool) -> Self {
            Self {
                entered: Arc::new(tokio::sync::Notify::new()),
                release: Arc::new(Mutex::new(None)),
                finished: Arc::new(AtomicBool::new(false)),
                fail,
            }
        }
    }
    struct TestMuxer(Finalizer);
    impl Muxer for TestMuxer {
        type Config = Finalizer;
        async fn setup(
            config: Finalizer,
            _: PathBuf,
            _: Option<VideoInfo>,
            _: Option<cap_media_info::AudioInfo>,
            _: Arc<AtomicBool>,
            _: &mut TaskPool,
        ) -> anyhow::Result<Self> {
            Ok(Self(config))
        }
        fn finish(&mut self, _: Duration) -> anyhow::Result<anyhow::Result<()>> {
            self.0.entered.notify_one();
            if let Some(release) = self.0.release.lock().unwrap().take() {
                release.recv().unwrap();
            }
            self.0.finished.store(true, Ordering::Release);
            Ok(if self.0.fail {
                Err(anyhow::anyhow!("required track finalization failed"))
            } else {
                Ok(())
            })
        }
    }
    impl VideoMuxer for TestMuxer {
        type VideoFrame = Frame;
        fn send_video_frame(&mut self, _: Frame, _: Duration) -> anyhow::Result<()> {
            Ok(())
        }
    }
    impl AudioMuxer for TestMuxer {
        fn send_audio_frame(&mut self, _: AudioFrame, _: Duration) -> anyhow::Result<()> {
            Ok(())
        }
    }

    struct Fixture {
        handle: ActorHandle,
        audio_cancel: Option<tokio_util::sync::CancellationToken>,
        _video_sender: flume::Sender<Frame>,
        _audio_sender: Option<futures::channel::mpsc::Sender<AudioFrame>>,
    }

    async fn actor_fixture(
        directory: &std::path::Path,
        video_finish: Finalizer,
        audio_finish: Option<Finalizer>,
    ) -> Fixture {
        let owner = InstantLifetimeOwner::new();
        let lifecycle = owner.lifecycle.clone();
        *lifecycle.0.runtime.lock().unwrap() = Some(tokio::runtime::Handle::current());
        let info = VideoInfo::from_raw(cap_media_info::RawVideoFormat::Bgra, 4, 4, 30);
        let timestamps = Timestamps::now();
        let (video_sender, video_receiver) = flume::bounded(4);
        let video = lifecycle
            .0
            .scope
            .run(
                OutputPipeline::builder(directory.join("display"))
                    .with_video::<ChannelVideoSource<Frame>>(ChannelVideoSourceConfig::new(
                        info,
                        video_receiver,
                    ))
                    .with_timestamps(timestamps)
                    .build::<TestMuxer>(video_finish),
            )
            .await
            .unwrap();
        video_sender
            .send(Frame(Timestamp::Instant(timestamps.instant())))
            .unwrap();
        let mut audio_sender = None;
        let audio = if let Some(finalizer) = audio_finish {
            let (mut sender, receiver) = futures::channel::mpsc::channel(4);
            let info = cap_media_info::AudioInfo::new_raw(
                cap_media_info::Sample::F32(cap_media_info::Type::Packed),
                48_000,
                2,
            );
            let audio = lifecycle
                .0
                .scope
                .run(
                    OutputPipeline::builder(directory.join("audio"))
                        .with_audio_source::<ChannelAudioSource>(ChannelAudioSourceConfig::new(
                            info, receiver,
                        ))
                        .with_timestamps(timestamps)
                        .build::<TestMuxer>(finalizer),
                )
                .await
                .unwrap();
            sender
                .try_send(AudioFrame::new(
                    info.empty_frame(960),
                    Timestamp::Instant(timestamps.instant()),
                ))
                .unwrap();
            audio_sender = Some(sender);
            Some(audio)
        } else {
            None
        };
        let audio_cancel = audio.as_ref().map(OutputPipeline::cancel_token);
        let video_done = video.done_fut();
        let audio_done = audio.as_ref().map(OutputPipeline::done_fut);
        let actor_ref = Actor::spawn(Actor {
            diagnostic: None,
            recording_dir: directory.to_path_buf(),
            output_dir: directory.join("display"),
            capture_target: ScreenCaptureTarget::CameraOnly,
            video_info: info,
            state: ActorState::Recording {
                pipeline: Pipeline {
                    video,
                    audio,
                    video_info: info,
                    segments_dir: directory.join("display"),
                    segment_rx: None,
                },
                segment_start_time: current_time_f64(),
            },
            total_pause_duration: Duration::ZERO,
            pause_started_at: None,
            terminal_stop_error: None,
            lifetime: owner,
        });
        watch_instant_tracks(lifecycle.clone(), actor_ref.clone(), video_done, audio_done);
        Fixture {
            handle: ActorHandle {
                actor_ref,
                capture_target: ScreenCaptureTarget::CameraOnly,
                done_fut: lifecycle.done_fut(),
                health_rx: None,
                segment_rx: None,
                lifecycle,
            },
            audio_cancel,
            _video_sender: video_sender,
            _audio_sender: audio_sender,
        }
    }

    #[derive(Clone, Copy, PartialEq, Eq)]
    enum CombinedFailure {
        None,
        AudioSend,
        AudioTail,
        FlushInner,
        FlushOuter,
    }

    #[derive(Clone)]
    struct CombinedProbe {
        failure: CombinedFailure,
        finalizer: Finalizer,
        attempts: Arc<Mutex<Vec<f32>>>,
        audio_observed: Arc<tokio::sync::Notify>,
        source_stopped: Arc<AtomicBool>,
    }

    impl CombinedProbe {
        fn new(failure: CombinedFailure) -> Self {
            Self {
                failure,
                finalizer: Finalizer::new(failure == CombinedFailure::FlushInner),
                attempts: Arc::new(Mutex::new(Vec::new())),
                audio_observed: Arc::new(tokio::sync::Notify::new()),
                source_stopped: Arc::new(AtomicBool::new(false)),
            }
        }
    }

    struct CombinedMuxer(CombinedProbe);

    impl Muxer for CombinedMuxer {
        type Config = CombinedProbe;

        async fn setup(
            config: Self::Config,
            output: PathBuf,
            _: Option<VideoInfo>,
            _: Option<cap_media_info::AudioInfo>,
            _: Arc<AtomicBool>,
            _: &mut TaskPool,
        ) -> anyhow::Result<Self> {
            std::fs::write(output, b"preserved partial test video")?;
            Ok(Self(config))
        }

        fn finish(&mut self, timestamp: Duration) -> anyhow::Result<anyhow::Result<()>> {
            let result = TestMuxer(self.0.finalizer.clone()).finish(timestamp);
            if self.0.failure == CombinedFailure::FlushOuter {
                return Err(anyhow::anyhow!("combined audio outer flush failed"));
            }
            result
        }
    }

    impl VideoMuxer for CombinedMuxer {
        type VideoFrame = Frame;

        fn send_video_frame(&mut self, _: Frame, _: Duration) -> anyhow::Result<()> {
            Ok(())
        }
    }

    impl AudioMuxer for CombinedMuxer {
        fn send_audio_frame(&mut self, frame: AudioFrame, _: Duration) -> anyhow::Result<()> {
            let value = f32::from_ne_bytes(frame.inner.data(0)[..4].try_into().unwrap());
            self.0.attempts.lock().unwrap().push(value);
            self.0.audio_observed.notify_one();
            if self.0.failure == CombinedFailure::AudioSend
                || (self.0.failure == CombinedFailure::AudioTail && value == 0.0)
            {
                return Err(anyhow::anyhow!("required combined audio send failed"));
            }
            Ok(())
        }
    }

    struct DirectAudioSource(Arc<AtomicBool>);

    impl AudioSource for DirectAudioSource {
        type Config = (
            tokio::sync::oneshot::Sender<futures::channel::mpsc::Sender<AudioFrame>>,
            Arc<AtomicBool>,
        );

        fn setup(
            config: Self::Config,
            sender: futures::channel::mpsc::Sender<AudioFrame>,
            _: &mut SetupCtx,
        ) -> impl Future<Output = anyhow::Result<Self>> + Send + 'static {
            futures::future::lazy(move |_| {
                config
                    .0
                    .send(sender)
                    .map_err(|_| anyhow::anyhow!("test audio receiver dropped"))?;
                Ok(Self(config.1))
            })
        }

        fn audio_info(&self) -> cap_media_info::AudioInfo {
            combined_audio_info()
        }

        async fn stop(&mut self) -> anyhow::Result<()> {
            self.0.store(true, Ordering::Release);
            Ok(())
        }
    }

    fn combined_audio_info() -> cap_media_info::AudioInfo {
        cap_media_info::AudioInfo::new_raw(
            cap_media_info::Sample::F32(cap_media_info::Type::Packed),
            48_000,
            2,
        )
    }

    fn combined_audio_frame(timestamps: Timestamps, value: f32) -> AudioFrame {
        let mut frame = combined_audio_info().empty_frame(960);
        for sample in frame.data_mut(0).chunks_exact_mut(4) {
            sample.copy_from_slice(&value.to_ne_bytes());
        }
        AudioFrame::new(frame, Timestamp::Instant(timestamps.instant()))
    }

    struct CombinedFixture {
        handle: ActorHandle,
        audio: futures::channel::mpsc::Sender<AudioFrame>,
        additional_audio: Vec<futures::channel::mpsc::Sender<AudioFrame>>,
        pipeline_cancel: tokio_util::sync::CancellationToken,
        _video: flume::Sender<Frame>,
        timestamps: Timestamps,
    }

    async fn combined_actor_fixture(
        directory: &std::path::Path,
        probe: CombinedProbe,
        start_video: bool,
    ) -> CombinedFixture {
        combined_actor_fixture_sources(directory, probe, start_video, 1).await
    }

    async fn combined_actor_fixture_sources(
        directory: &std::path::Path,
        probe: CombinedProbe,
        start_video: bool,
        source_count: usize,
    ) -> CombinedFixture {
        let owner = InstantLifetimeOwner::new();
        let lifecycle = owner.lifecycle.clone();
        *lifecycle.0.runtime.lock().unwrap() = Some(tokio::runtime::Handle::current());
        let info = VideoInfo::from_raw(cap_media_info::RawVideoFormat::Bgra, 4, 4, 30);
        let timestamps = Timestamps::now();
        let (video_sender, video_receiver) = flume::bounded(4);
        let output = directory.join("output.mp4");
        let mut builder = OutputPipeline::builder(output.clone())
            .with_video::<ChannelVideoSource<Frame>>(ChannelVideoSourceConfig::new(
                info,
                video_receiver,
            ))
            .with_timestamps(timestamps);
        let mut receivers = Vec::new();
        for _ in 0..source_count {
            let (sender, receiver) = tokio::sync::oneshot::channel();
            builder = builder
                .with_audio_source::<DirectAudioSource>((sender, probe.source_stopped.clone()));
            receivers.push(receiver);
        }
        let video = lifecycle
            .0
            .scope
            .run(builder.build::<CombinedMuxer>(probe))
            .await
            .unwrap();
        let mut audio_sources = Vec::new();
        for receiver in receivers {
            audio_sources.push(receiver.await.unwrap());
        }
        let audio = audio_sources.remove(0);
        let pipeline_cancel = video.cancel_token();
        let done = video.done_fut();
        let actor_ref = Actor::spawn(Actor {
            diagnostic: None,
            recording_dir: directory.to_path_buf(),
            output_dir: output.clone(),
            capture_target: ScreenCaptureTarget::CameraOnly,
            video_info: info,
            state: ActorState::Recording {
                pipeline: Pipeline {
                    video,
                    audio: None,
                    video_info: info,
                    segments_dir: directory.to_path_buf(),
                    segment_rx: None,
                },
                segment_start_time: current_time_f64(),
            },
            total_pause_duration: Duration::ZERO,
            pause_started_at: None,
            terminal_stop_error: None,
            lifetime: owner,
        });
        watch_instant_tracks(lifecycle.clone(), actor_ref.clone(), done, None);
        let handle = ActorHandle {
            actor_ref,
            capture_target: ScreenCaptureTarget::CameraOnly,
            done_fut: lifecycle.done_fut(),
            health_rx: None,
            segment_rx: None,
            lifecycle,
        };
        if start_video {
            video_sender
                .send(Frame(Timestamp::Instant(timestamps.instant())))
                .unwrap();
        }
        CombinedFixture {
            handle,
            audio,
            additional_audio: audio_sources,
            pipeline_cancel,
            _video: video_sender,
            timestamps,
        }
    }

    async fn assert_combined_error(
        fixture: &CombinedFixture,
        probe: &CombinedProbe,
        message: &str,
    ) {
        let error = tokio::time::timeout(Duration::from_secs(3), fixture.handle.done_fut())
            .await
            .unwrap()
            .unwrap_err();
        assert!(error.to_string().contains(message), "{error:#}");
        assert_eq!(
            fixture.handle.lifecycle().quiescence(),
            InstantQuiescence::Joined
        );
        assert!(probe.source_stopped.load(Ordering::Acquire));
        assert!(probe.finalizer.finished.load(Ordering::Acquire));
        for _ in 0..2 {
            let error = fixture.handle.stop().await.unwrap_err();
            assert!(error.to_string().contains(message), "{error:#}");
            assert!(fixture.handle.cancel().await.is_err());
        }
    }

    #[tokio::test]
    async fn camera_only_system_request_fails_inside_joined_startup_without_capture() {
        let directory = tempfile::tempdir().unwrap();
        let output = directory.path().join("unsupported.cap");
        let builder =
            Actor::builder(output.clone(), ScreenCaptureTarget::CameraOnly).with_system_audio(true);
        let lifecycle = builder.lifecycle();
        let error = builder
            .build()
            .await
            .err()
            .expect("Unsupported system audio must fail");
        assert!(
            error.to_string().contains("System audio is not supported"),
            "{error:#}"
        );
        assert!(!output.exists());
        assert_eq!(
            lifecycle.wait_for_quiescence().await,
            InstantQuiescence::Joined
        );
        assert!(
            lifecycle
                .done_fut()
                .await
                .unwrap_err()
                .to_string()
                .contains("System audio is not supported")
        );
        let supported = Actor::builder(
            directory.path().join("camera.cap"),
            ScreenCaptureTarget::CameraOnly,
        );
        let lifecycle = supported.lifecycle();
        let error = supported
            .build()
            .await
            .err()
            .expect("Missing camera must still be validated");
        assert!(
            error
                .to_string()
                .contains("Camera-only recording requires a camera"),
            "{error:#}"
        );
        assert_eq!(
            lifecycle.wait_for_quiescence().await,
            InstantQuiescence::Joined
        );
    }

    #[tokio::test]
    async fn combined_mixer_errors_wait_for_owned_finalization_and_remain_terminal() {
        for (rate, message) in [
            (0, "filter input failed"),
            (u32::MAX, "filter rebuild failed"),
        ] {
            let directory = tempfile::tempdir().unwrap();
            let probe = CombinedProbe::new(CombinedFailure::FlushInner);
            let (release, blocked) = std::sync::mpsc::channel();
            *probe.finalizer.release.lock().unwrap() = Some(blocked);
            let mut fixture =
                combined_actor_fixture_sources(directory.path(), probe.clone(), true, 2).await;
            let mut invalid = combined_audio_frame(fixture.timestamps, 0.25);
            invalid.inner.set_rate(rate);
            fixture.audio.try_send(invalid).unwrap();
            fixture.additional_audio[0]
                .try_send(combined_audio_frame(fixture.timestamps, 0.25))
                .unwrap();
            tokio::time::timeout(Duration::from_secs(3), probe.finalizer.entered.notified())
                .await
                .unwrap();
            assert_eq!(
                fixture.handle.lifecycle().quiescence(),
                InstantQuiescence::Pending
            );
            assert!(
                tokio::time::timeout(Duration::from_millis(20), fixture.handle.done_fut())
                    .await
                    .is_err()
            );
            release.send(()).unwrap();
            assert_combined_error(&fixture, &probe, message).await;
            assert!(directory.path().join("output.mp4").is_file());
        }
    }

    #[tokio::test]
    async fn combined_closed_requested_mixer_input_cannot_complete() {
        let directory = tempfile::tempdir().unwrap();
        let probe = CombinedProbe::new(CombinedFailure::FlushInner);
        let (release, blocked) = std::sync::mpsc::channel();
        *probe.finalizer.release.lock().unwrap() = Some(blocked);
        let mut fixture =
            combined_actor_fixture_sources(directory.path(), probe.clone(), true, 2).await;
        drop(fixture.additional_audio.remove(0));
        tokio::time::timeout(Duration::from_secs(3), probe.finalizer.entered.notified())
            .await
            .unwrap();
        assert!(fixture.pipeline_cancel.is_cancelled());
        assert_eq!(
            fixture.handle.lifecycle().quiescence(),
            InstantQuiescence::Pending
        );
        release.send(()).unwrap();
        assert_combined_error(&fixture, &probe, "source 1 closed").await;
        assert!(directory.path().join("output.mp4").is_file());
    }

    #[tokio::test]
    async fn combined_closed_single_audio_input_cannot_complete() {
        let directory = tempfile::tempdir().unwrap();
        let probe = CombinedProbe::new(CombinedFailure::FlushInner);
        let (release, blocked) = std::sync::mpsc::channel();
        *probe.finalizer.release.lock().unwrap() = Some(blocked);
        let mut fixture = combined_actor_fixture(directory.path(), probe.clone(), true).await;
        assert!(!fixture.pipeline_cancel.is_cancelled());
        fixture.audio.close_channel();
        tokio::time::timeout(Duration::from_secs(3), probe.finalizer.entered.notified())
            .await
            .unwrap();
        assert!(fixture.pipeline_cancel.is_cancelled());
        assert_eq!(
            fixture.handle.lifecycle().quiescence(),
            InstantQuiescence::Pending
        );
        release.send(()).unwrap();
        assert_combined_error(&fixture, &probe, "Required audio source closed").await;
        assert!(directory.path().join("output.mp4").is_file());
    }

    #[tokio::test(flavor = "current_thread")]
    async fn combined_pipeline_cancellation_precedes_closed_source_error() {
        for source_count in [1, 2] {
            let directory = tempfile::tempdir().unwrap();
            let probe = CombinedProbe::new(CombinedFailure::None);
            let mut fixture =
                combined_actor_fixture_sources(directory.path(), probe.clone(), true, source_count)
                    .await;
            fixture
                .audio
                .try_send(combined_audio_frame(fixture.timestamps, 0.25))
                .unwrap();
            for source in &mut fixture.additional_audio {
                source
                    .try_send(combined_audio_frame(fixture.timestamps, 0.25))
                    .unwrap();
            }
            tokio::time::timeout(Duration::from_secs(3), probe.audio_observed.notified())
                .await
                .unwrap();
            let actor = fixture.handle.actor_ref.clone();
            let stop = tokio::spawn(async move { actor.ask(Stop).await });
            tokio::time::timeout(Duration::from_secs(3), fixture.pipeline_cancel.cancelled())
                .await
                .unwrap();
            fixture.audio.close_channel();
            fixture.additional_audio.clear();
            tokio::time::timeout(Duration::from_secs(3), stop)
                .await
                .unwrap()
                .unwrap()
                .unwrap();
            fixture.handle.done_fut().await.unwrap();
            assert_eq!(
                fixture.handle.lifecycle().quiescence(),
                InstantQuiescence::Joined
            );
            assert!(probe.finalizer.finished.load(Ordering::Acquire));
        }
    }

    #[tokio::test]
    async fn combined_requested_mixed_audio_success_still_completes() {
        let directory = tempfile::tempdir().unwrap();
        let probe = CombinedProbe::new(CombinedFailure::None);
        let mut fixture =
            combined_actor_fixture_sources(directory.path(), probe.clone(), true, 2).await;
        fixture
            .audio
            .try_send(combined_audio_frame(fixture.timestamps, 0.25))
            .unwrap();
        fixture.additional_audio[0]
            .try_send(combined_audio_frame(fixture.timestamps, 0.25))
            .unwrap();
        tokio::time::timeout(Duration::from_secs(3), probe.audio_observed.notified())
            .await
            .unwrap();
        tokio::time::timeout(Duration::from_secs(3), fixture.handle.stop())
            .await
            .unwrap()
            .unwrap();
        fixture.handle.done_fut().await.unwrap();
        assert_eq!(
            fixture.handle.lifecycle().quiescence(),
            InstantQuiescence::Joined
        );
        assert!(probe.source_stopped.load(Ordering::Acquire));
        assert!(probe.finalizer.finished.load(Ordering::Acquire));
        assert!(!probe.attempts.lock().unwrap().is_empty());
    }

    #[tokio::test]
    async fn combined_audio_send_failure_waits_for_finalizer_and_never_completes() {
        let directory = tempfile::tempdir().unwrap();
        let probe = CombinedProbe::new(CombinedFailure::AudioSend);
        let (release, blocked) = std::sync::mpsc::channel();
        *probe.finalizer.release.lock().unwrap() = Some(blocked);
        let mut fixture = combined_actor_fixture(directory.path(), probe.clone(), true).await;
        fixture
            .audio
            .try_send(combined_audio_frame(fixture.timestamps, 0.25))
            .unwrap();
        tokio::time::timeout(Duration::from_secs(3), probe.finalizer.entered.notified())
            .await
            .unwrap();
        assert_eq!(
            fixture.handle.lifecycle().quiescence(),
            InstantQuiescence::Pending
        );
        assert!(fixture.handle.done_fut().now_or_never().is_none());
        assert!(probe.source_stopped.load(Ordering::Acquire));
        release.send(()).unwrap();
        assert_combined_error(&fixture, &probe, "required combined audio send failed").await;
        assert_eq!(
            std::fs::read(directory.path().join("output.mp4")).unwrap(),
            b"preserved partial test video"
        );
    }

    #[tokio::test]
    async fn combined_audio_send_error_survives_later_flush_failure() {
        let directory = tempfile::tempdir().unwrap();
        let mut probe = CombinedProbe::new(CombinedFailure::AudioSend);
        probe.finalizer.fail = true;
        let mut fixture = combined_actor_fixture(directory.path(), probe.clone(), true).await;
        fixture
            .audio
            .try_send(combined_audio_frame(fixture.timestamps, 0.25))
            .unwrap();
        assert_combined_error(&fixture, &probe, "required combined audio send failed").await;
    }

    #[tokio::test]
    async fn combined_audio_drain_failure_is_retained_by_actor_stop() {
        let directory = tempfile::tempdir().unwrap();
        let probe = CombinedProbe::new(CombinedFailure::AudioSend);
        let mut fixture = combined_actor_fixture(directory.path(), probe.clone(), false).await;
        fixture
            .audio
            .try_send(combined_audio_frame(fixture.timestamps, 0.25))
            .unwrap();
        let mut full = false;
        for _ in 0..256 {
            if let Err(error) = fixture
                .audio
                .try_send(combined_audio_frame(fixture.timestamps, 0.75))
            {
                assert!(error.is_full());
                full = true;
                break;
            }
        }
        assert!(full);
        tokio::time::timeout(
            Duration::from_secs(2),
            futures::future::poll_fn(|cx| fixture.audio.poll_ready(cx)),
        )
        .await
        .unwrap()
        .unwrap();
        assert!(probe.attempts.lock().unwrap().is_empty());
        let error = tokio::time::timeout(Duration::from_secs(3), fixture.handle.stop())
            .await
            .unwrap()
            .unwrap_err();
        assert!(
            error
                .to_string()
                .contains("required combined audio send failed")
        );
        assert_eq!(*probe.attempts.lock().unwrap(), vec![0.75]);
        assert_combined_error(&fixture, &probe, "required combined audio send failed").await;
    }

    #[tokio::test]
    async fn combined_audio_tail_failure_is_retained_by_actor_stop() {
        let directory = tempfile::tempdir().unwrap();
        let probe = CombinedProbe::new(CombinedFailure::AudioTail);
        let mut fixture = combined_actor_fixture(directory.path(), probe.clone(), true).await;
        fixture
            .audio
            .try_send(combined_audio_frame(fixture.timestamps, 0.25))
            .unwrap();
        tokio::time::timeout(Duration::from_secs(2), probe.audio_observed.notified())
            .await
            .unwrap();
        tokio::time::sleep(Duration::from_millis(50)).await;
        let error = fixture.handle.stop().await.unwrap_err();
        assert!(error.to_string().contains("tail padding"), "{error:#}");
        let attempts = probe.attempts.lock().unwrap().clone();
        assert_eq!(attempts.first(), Some(&0.25));
        assert_eq!(attempts.last(), Some(&0.0));
        assert_combined_error(&fixture, &probe, "tail padding").await;
    }

    #[tokio::test]
    async fn combined_audio_flush_failures_never_become_complete() {
        for failure in [CombinedFailure::FlushInner, CombinedFailure::FlushOuter] {
            let directory = tempfile::tempdir().unwrap();
            let probe = CombinedProbe::new(failure);
            let mut fixture = combined_actor_fixture(directory.path(), probe.clone(), true).await;
            fixture
                .audio
                .try_send(combined_audio_frame(fixture.timestamps, 0.25))
                .unwrap();
            tokio::time::timeout(Duration::from_secs(2), probe.audio_observed.notified())
                .await
                .unwrap();
            assert!(fixture.handle.stop().await.is_err());
            let message = if failure == CombinedFailure::FlushInner {
                "required track finalization failed"
            } else {
                "combined audio outer flush failed"
            };
            assert_combined_error(&fixture, &probe, message).await;
        }
    }

    #[tokio::test]
    async fn combined_requested_audio_success_still_completes() {
        let directory = tempfile::tempdir().unwrap();
        let probe = CombinedProbe::new(CombinedFailure::None);
        let mut fixture = combined_actor_fixture(directory.path(), probe.clone(), true).await;
        fixture
            .audio
            .try_send(combined_audio_frame(fixture.timestamps, 0.25))
            .unwrap();
        tokio::time::timeout(Duration::from_secs(2), probe.audio_observed.notified())
            .await
            .unwrap();
        let completed = fixture.handle.stop().await.unwrap();
        assert!(matches!(
            completed.meta,
            InstantRecordingMeta::Complete { .. }
        ));
        assert!(fixture.handle.done_fut().await.is_ok());
        assert_eq!(
            fixture.handle.lifecycle().quiescence(),
            InstantQuiescence::Joined
        );
        assert!(probe.source_stopped.load(Ordering::Acquire));
        assert!(probe.finalizer.finished.load(Ordering::Acquire));
    }

    #[tokio::test]
    async fn stop_waits_for_actual_blocking_finalization_before_joined_or_complete() {
        let directory = tempfile::tempdir().unwrap();
        let finalizer = Finalizer::new(false);
        let (release, blocked) = std::sync::mpsc::channel();
        *finalizer.release.lock().unwrap() = Some(blocked);
        let fixture = actor_fixture(directory.path(), finalizer.clone(), None).await;
        let handle = &fixture.handle;
        let stopping = handle.stop();
        tokio::pin!(stopping);
        tokio::select! { _ = finalizer.entered.notified() => {}, _ = &mut stopping => panic!("Stop completed before finalizer entry") }
        assert_eq!(handle.lifecycle().quiescence(), InstantQuiescence::Pending);
        assert!(handle.done_fut().now_or_never().is_none());
        assert!(
            tokio::time::timeout(Duration::from_millis(20), &mut stopping)
                .await
                .is_err()
        );
        release.send(()).unwrap();
        tokio::time::timeout(Duration::from_secs(2), stopping)
            .await
            .unwrap()
            .unwrap();
        assert!(finalizer.finished.load(Ordering::Acquire));
        assert_eq!(handle.lifecycle().quiescence(), InstantQuiescence::Joined);
        assert!(handle.done_fut().await.is_ok());
    }

    #[tokio::test]
    async fn required_audio_error_stops_video_and_stays_error_for_stop_and_cancel() {
        let directory = tempfile::tempdir().unwrap();
        let video = Finalizer::new(false);
        let audio = Finalizer::new(true);
        let fixture = actor_fixture(directory.path(), video.clone(), Some(audio)).await;
        let handle = &fixture.handle;
        fixture.audio_cancel.as_ref().unwrap().cancel();
        let error = tokio::time::timeout(Duration::from_secs(2), handle.done_fut())
            .await
            .unwrap()
            .unwrap_err();
        assert!(error.to_string().contains("finalization failed"));
        assert!(video.finished.load(Ordering::Acquire));
        assert_eq!(handle.lifecycle().quiescence(), InstantQuiescence::Joined);
        assert!(handle.stop().await.is_err());
        assert!(handle.cancel().await.is_err());
        assert!(handle.stop().await.is_err());
    }

    #[tokio::test]
    async fn cancel_waits_for_joined_capture_and_retains_finalization_error() {
        let directory = tempfile::tempdir().unwrap();
        let finalizer = Finalizer::new(true);
        let (release, blocked) = std::sync::mpsc::channel();
        *finalizer.release.lock().unwrap() = Some(blocked);
        let fixture = actor_fixture(directory.path(), finalizer.clone(), None).await;
        let handle = &fixture.handle;
        let cancel = handle.cancel();
        tokio::pin!(cancel);
        tokio::select! { _ = finalizer.entered.notified() => {}, _ = &mut cancel => panic!("Cancel returned before encoder exit") }
        assert_eq!(handle.lifecycle().quiescence(), InstantQuiescence::Pending);
        release.send(()).unwrap();
        assert!(cancel.await.is_err());
        assert!(handle.stop().await.is_err());
        assert_eq!(handle.lifecycle().quiescence(), InstantQuiescence::Joined);
    }

    #[tokio::test]
    async fn dropped_build_waiter_keeps_native_cleanup_owned_until_exit() {
        let owner = InstantLifetimeOwner::new();
        let lifecycle = owner.lifecycle.clone();
        let (started, started_rx) = tokio::sync::oneshot::channel();
        let (release, blocked) = std::sync::mpsc::channel();
        let finished = Arc::new(AtomicBool::new(false));
        let worker_finished = finished.clone();
        let task = tokio::spawn(run_owned_instant_build(owner, async move {
            let mut tasks = TaskPool::default();
            tasks.spawn_thread("instant-build-native", move || {
                started.send(()).unwrap();
                blocked.recv().unwrap();
                worker_finished.store(true, Ordering::Release);
                Ok(())
            });
            std::future::pending::<anyhow::Result<()>>().await
        }));
        started_rx.await.unwrap();
        task.abort();
        assert!(task.await.unwrap_err().is_cancelled());
        assert!(
            tokio::time::timeout(Duration::from_millis(20), lifecycle.wait_for_quiescence())
                .await
                .is_err()
        );
        release.send(()).unwrap();
        assert_eq!(
            tokio::time::timeout(Duration::from_secs(2), lifecycle.wait_for_quiescence())
                .await
                .unwrap(),
            InstantQuiescence::Joined
        );
        assert!(finished.load(Ordering::Acquire));
        assert!(lifecycle.done_fut().await.is_err());
    }

    #[tokio::test]
    async fn build_error_waits_for_partial_native_work_before_returning() {
        let owner = InstantLifetimeOwner::new();
        let lifecycle = owner.lifecycle.clone();
        let (started, started_rx) = tokio::sync::oneshot::channel();
        let (release, blocked) = std::sync::mpsc::channel();
        let mut task = tokio::spawn(run_owned_instant_build(owner, async move {
            let mut tasks = TaskPool::default();
            tasks.spawn_thread("instant-failed-build-native", move || {
                started.send(()).unwrap();
                blocked.recv().unwrap();
                Ok(())
            });
            Err::<(), _>(anyhow::anyhow!("later setup stage failed"))
        }));
        started_rx.await.unwrap();
        assert!(
            tokio::time::timeout(Duration::from_millis(20), &mut task)
                .await
                .is_err()
        );
        assert_eq!(lifecycle.quiescence(), InstantQuiescence::Pending);
        release.send(()).unwrap();
        assert!(
            task.await
                .unwrap()
                .unwrap_err()
                .to_string()
                .contains("later setup stage failed")
        );
        assert_eq!(lifecycle.quiescence(), InstantQuiescence::Joined);
    }

    #[tokio::test]
    async fn successful_build_disarms_its_startup_owner_without_cancelling_capture() {
        let owner = InstantLifetimeOwner::new();
        let lifecycle = owner.lifecycle.clone();
        let completion = run_owned_instant_build(owner, async {
            Ok(crate::output_pipeline::PipelineBuildScope::current()
                .unwrap()
                .task_completion())
        })
        .await
        .unwrap();
        assert_eq!(lifecycle.quiescence(), InstantQuiescence::Pending);
        assert!(!lifecycle.0.scope.cancellation().is_cancelled());
        drop(completion);
        lifecycle.cancel();
        assert_eq!(
            lifecycle.wait_for_quiescence().await,
            InstantQuiescence::Joined
        );
    }

    #[tokio::test]
    async fn unused_and_cancelled_before_build_lifetimes_are_joined_without_capture() {
        let builder = Actor::builder(PathBuf::new(), ScreenCaptureTarget::CameraOnly);
        let lifecycle = builder.lifecycle();
        drop(builder);
        assert_eq!(
            lifecycle.wait_for_quiescence().await,
            InstantQuiescence::Joined
        );
        let builder = Actor::builder(PathBuf::new(), ScreenCaptureTarget::CameraOnly);
        let lifecycle = builder.lifecycle();
        lifecycle.cancel();
        assert_eq!(
            lifecycle.wait_for_quiescence().await,
            InstantQuiescence::Joined
        );
        assert!(builder.build().await.is_err());
        assert_eq!(lifecycle.quiescence(), InstantQuiescence::Joined);
    }
    #[tokio::test]
    async fn dropped_actor_handle_retains_cleanup_until_encoder_has_exited() {
        let directory = tempfile::tempdir().unwrap();
        let finalizer = Finalizer::new(false);
        let (release, blocked) = std::sync::mpsc::channel();
        *finalizer.release.lock().unwrap() = Some(blocked);
        let fixture = actor_fixture(directory.path(), finalizer.clone(), None).await;
        let lifecycle = fixture.handle.lifecycle();
        let done = fixture.handle.done_fut();
        drop(fixture);
        finalizer.entered.notified().await;
        assert_eq!(lifecycle.quiescence(), InstantQuiescence::Pending);
        assert!(done.clone().now_or_never().is_none());
        release.send(()).unwrap();
        assert_eq!(
            tokio::time::timeout(Duration::from_secs(2), lifecycle.wait_for_quiescence())
                .await
                .unwrap(),
            InstantQuiescence::Joined
        );
        assert!(finalizer.finished.load(Ordering::Acquire));
        assert!(done.await.is_err());
    }
    #[tokio::test]
    async fn lost_cleanup_acknowledgement_cannot_be_upgraded_to_joined_success() {
        let lifecycle = InstantLifecycle::new();
        drop(CleanupAcknowledgement {
            lifecycle: lifecycle.clone(),
            armed: true,
        });
        lifecycle.cancel();
        assert_eq!(lifecycle.quiescence(), InstantQuiescence::Unconfirmed);
        let report = lifecycle.0.scope.cancel_and_join_report().await;
        assert!(lifecycle.complete(report, None).is_err());
        assert_eq!(
            lifecycle.wait_for_quiescence().await,
            InstantQuiescence::Unconfirmed
        );
        assert!(lifecycle.done_fut().await.is_err());
    }
}

#[cfg(all(test, not(target_os = "linux")))]
mod non_linux_stop_tests {
    use super::*;
    use crate::output_pipeline::{
        AudioFrame, AudioMuxer, ChannelAudioSource, ChannelAudioSourceConfig, ChannelVideoSource,
        ChannelVideoSourceConfig, Muxer, TaskPool, VideoFrame, VideoMuxer,
    };
    use cap_timestamp::Timestamp;
    use std::{
        sync::atomic::{AtomicBool, Ordering},
        time::Duration,
    };

    #[derive(Clone, Copy)]
    struct Frame(Timestamp);

    impl VideoFrame for Frame {
        fn timestamp(&self) -> Timestamp {
            self.0
        }
    }

    struct Finalizer {
        entered: Arc<tokio::sync::Notify>,
        finished: Arc<AtomicBool>,
        release: Option<std::sync::mpsc::Receiver<()>>,
        error: Option<&'static str>,
    }

    struct TestMuxer(Finalizer);

    impl Muxer for TestMuxer {
        type Config = Finalizer;

        async fn setup(
            config: Self::Config,
            _: PathBuf,
            _: Option<VideoInfo>,
            _: Option<cap_media_info::AudioInfo>,
            _: Arc<AtomicBool>,
            _: &mut TaskPool,
        ) -> anyhow::Result<Self> {
            Ok(Self(config))
        }

        fn finish(&mut self, _: Duration) -> anyhow::Result<anyhow::Result<()>> {
            self.0.entered.notify_one();
            if let Some(release) = self.0.release.take() {
                release.recv()?;
            }
            self.0.finished.store(true, Ordering::Release);
            Ok(match self.0.error {
                Some(error) => Err(anyhow::anyhow!(error)),
                None => Ok(()),
            })
        }
    }

    impl VideoMuxer for TestMuxer {
        type VideoFrame = Frame;

        fn send_video_frame(&mut self, _: Frame, _: Duration) -> anyhow::Result<()> {
            Ok(())
        }
    }

    impl AudioMuxer for TestMuxer {
        fn send_audio_frame(&mut self, _: AudioFrame, _: Duration) -> anyhow::Result<()> {
            Ok(())
        }
    }

    fn stopped_actor(error: Option<String>) -> Actor {
        Actor {
            diagnostic: None,
            recording_dir: PathBuf::new(),
            output_dir: PathBuf::new(),
            capture_target: ScreenCaptureTarget::CameraOnly,
            video_info: VideoInfo::from_raw_ffmpeg(ffmpeg::format::Pixel::RGBA, 4, 4, 30),
            state: ActorState::Stopped,
            total_pause_duration: std::time::Duration::ZERO,
            pause_started_at: None,
            terminal_stop_error: error,
        }
    }

    #[tokio::test]
    async fn cancel_actor_retains_stop_error_instead_of_reporting_success() {
        let actor = Actor::spawn(stopped_actor(Some("stop cleanup failed".into())));
        for _ in 0..2 {
            assert!(
                actor
                    .ask(Stop)
                    .await
                    .unwrap_err()
                    .to_string()
                    .contains("stop cleanup failed")
            );
            assert!(
                actor
                    .ask(Cancel)
                    .await
                    .unwrap_err()
                    .to_string()
                    .contains("stop cleanup failed")
            );
        }
        actor.kill();
        actor.wait_for_stop().await;
    }

    async fn audio_failure_waits_for_video_and_remains_visible(cancel: bool) {
        let directory = tempfile::tempdir().unwrap();
        let timestamps = Timestamps::now();
        let video_info = VideoInfo::from_raw(cap_media_info::RawVideoFormat::Bgra, 4, 4, 30);
        let video_entered = Arc::new(tokio::sync::Notify::new());
        let video_finished = Arc::new(AtomicBool::new(false));
        let audio_finished = Arc::new(AtomicBool::new(false));
        let (release, blocked) = std::sync::mpsc::channel();
        let (video_sender, video_receiver) = flume::bounded(4);
        let video = OutputPipeline::builder(directory.path().join("display"))
            .with_video::<ChannelVideoSource<Frame>>(ChannelVideoSourceConfig::new(
                video_info,
                video_receiver,
            ))
            .with_timestamps(timestamps)
            .build::<TestMuxer>(Finalizer {
                entered: video_entered.clone(),
                finished: video_finished.clone(),
                release: Some(blocked),
                error: None,
            })
            .await
            .unwrap();
        video_sender
            .send(Frame(Timestamp::Instant(timestamps.instant())))
            .unwrap();
        let video_cancel = video.cancel_token();

        let audio_info = cap_media_info::AudioInfo::new_raw(
            cap_media_info::Sample::F32(cap_media_info::Type::Packed),
            48_000,
            2,
        );
        let (mut audio_sender, audio_receiver) = futures::channel::mpsc::channel(4);
        let audio = OutputPipeline::builder(directory.path().join("audio"))
            .with_audio_source::<ChannelAudioSource>(ChannelAudioSourceConfig::new(
                audio_info,
                audio_receiver,
            ))
            .with_timestamps(timestamps)
            .build::<TestMuxer>(Finalizer {
                entered: Arc::new(tokio::sync::Notify::new()),
                finished: audio_finished.clone(),
                release: None,
                error: Some("audio finalization failed"),
            })
            .await
            .unwrap();
        audio_sender
            .try_send(AudioFrame::new(
                audio_info.empty_frame(960),
                Timestamp::Instant(timestamps.instant()),
            ))
            .unwrap();
        let audio_done = audio.done_fut();
        let actor = Actor::spawn(Actor {
            diagnostic: None,
            recording_dir: directory.path().to_path_buf(),
            output_dir: directory.path().join("display"),
            capture_target: ScreenCaptureTarget::CameraOnly,
            video_info,
            state: ActorState::Recording {
                pipeline: Pipeline {
                    video,
                    audio: Some(audio),
                    video_info,
                    segments_dir: directory.path().join("display"),
                    segment_rx: None,
                },
                segment_start_time: current_time_f64(),
            },
            total_pause_duration: Duration::ZERO,
            pause_started_at: None,
            terminal_stop_error: None,
        });
        let stop_actor = actor.clone();
        let stop = tokio::spawn(async move {
            if cancel {
                stop_actor.ask(Cancel).await.map_err(|e| e.to_string())
            } else {
                stop_actor
                    .ask(Stop)
                    .await
                    .map(|_| ())
                    .map_err(|e| e.to_string())
            }
        });

        tokio::time::timeout(Duration::from_secs(2), video_cancel.cancelled())
            .await
            .unwrap();
        drop(video_sender);
        tokio::time::timeout(Duration::from_secs(2), video_entered.notified())
            .await
            .unwrap();
        let audio_error = tokio::time::timeout(Duration::from_secs(2), audio_done)
            .await
            .unwrap()
            .unwrap_err();
        assert!(
            audio_error
                .to_string()
                .contains("audio finalization failed")
        );
        assert!(audio_finished.load(Ordering::Acquire));
        assert!(!video_finished.load(Ordering::Acquire));
        assert!(!stop.is_finished());

        release.send(()).unwrap();
        let stop_error = tokio::time::timeout(Duration::from_secs(2), stop)
            .await
            .unwrap()
            .unwrap()
            .unwrap_err();
        assert!(stop_error.contains("audio finalization failed"));
        assert!(video_finished.load(Ordering::Acquire));
        assert!(
            actor
                .ask(Stop)
                .await
                .unwrap_err()
                .to_string()
                .contains("audio finalization failed")
        );
        assert!(
            actor
                .ask(Cancel)
                .await
                .unwrap_err()
                .to_string()
                .contains("audio finalization failed")
        );
        actor.kill();
        actor.wait_for_stop().await;
    }

    #[tokio::test]
    async fn stop_waits_for_video_after_audio_finalization_fails() {
        audio_failure_waits_for_video_and_remains_visible(false).await;
    }

    #[tokio::test]
    async fn cancel_waits_for_video_after_audio_finalization_fails() {
        audio_failure_waits_for_video_and_remains_visible(true).await;
    }

    #[tokio::test]
    async fn cancel_of_clean_stopped_actor_succeeds() {
        let actor = Actor::spawn(stopped_actor(None));
        actor.ask(Cancel).await.unwrap();
        actor.kill();
        actor.wait_for_stop().await;
    }
}