Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

248 KB
Raw Blame
use crate::RecordingStartGate;
#[cfg(target_os = "macos")]
use crate::SendableShareableContent;
#[cfg(target_os = "macos")]
use crate::output_pipeline::{
    AVFoundationCameraMuxer, AVFoundationCameraMuxerConfig, MacOSFragmentedM4SCameraMuxer,
    MacOSFragmentedM4SCameraMuxerConfig,
};
use crate::{
    ActorError, H264_MAX_DIMENSION, MediaError, RecordingBaseInputs, RecordingError,
    SharedPauseState, calculate_gpu_compatible_size,
    capture_pipeline::{
        MakeCapturePipeline, ScreenCaptureMethod, Stop, target_to_display_and_crop,
    },
    cursor::{
        CursorActor, CursorActorResponse, Cursors, IncrementalCaptureOutputs, spawn_cursor_recorder,
    },
    feeds::{camera::CameraFeedLock, microphone::MicrophoneFeedLock},
    ffmpeg::{FragmentedAudioMuxer, FragmentedAudioMuxerConfig, OggMuxer, OggMuxerConfig},
    output_pipeline::{
        AudioAnchor, AudioGapSummary, DoneFut, FinishedOutputPipeline, OutputPipeline,
        PipelineDoneError,
    },
    screen_capture::ScreenCaptureConfig,
    sources::{self, screen_capture},
};

#[cfg(windows)]
use crate::output_pipeline::{
    WindowsCameraMuxer, WindowsCameraMuxerConfig, WindowsFragmentedM4SCameraMuxer,
    WindowsFragmentedM4SCameraMuxerConfig,
};
use anyhow::{Context as _, anyhow, bail};
use cap_media_info::VideoInfo;
use cap_project::{
    CursorEvents, KeyboardEvents, MultipleSegment, MultipleSegments, Platform, RecordingMeta,
    RecordingMetaInner, StudioRecordingMeta, StudioRecordingStatus,
};
use cap_timestamp::{Timestamp, Timestamps};
use futures::{FutureExt, StreamExt, future::OptionFuture, stream::FuturesUnordered};
use kameo::{Actor as _, prelude::*};
use relative_path::RelativePathBuf;
use serde::Serialize;
use std::{
    path::{Path, PathBuf},
    pin::Pin,
    sync::Arc,
    time::{Duration, Instant, SystemTime, UNIX_EPOCH},
};
use tokio::{sync::watch, task::JoinHandle};
use tracing::{Instrument, debug, error_span, info, trace, warn};

const COMPATIBILITY_CAMERA_ACTIVE_MAX_SCREEN_WIDTH: u32 = 1600;
const COMPATIBILITY_CAMERA_ACTIVE_MAX_SCREEN_HEIGHT: u32 = 1000;
const UNCONFIRMED_CAPTURE_CLEANUP: &str =
    "Studio capture cleanup is unconfirmed; local recording preserved";

fn camera_active_max_capture_size(
    quality: crate::StudioQuality,
    camera_active: bool,
) -> Option<(u32, u32)> {
    if !camera_active {
        return None;
    }

    match quality {
        crate::StudioQuality::Compatibility => Some((
            COMPATIBILITY_CAMERA_ACTIVE_MAX_SCREEN_WIDTH,
            COMPATIBILITY_CAMERA_ACTIVE_MAX_SCREEN_HEIGHT,
        )),
        crate::StudioQuality::Balanced | crate::StudioQuality::Ultra => None,
    }
}

fn studio_max_capture_size(
    quality: crate::StudioQuality,
    camera_active: bool,
) -> Option<(u32, u32)> {
    // ScreenCaptureKit scales on the GPU. Unbounded, a 5K or 6K display is
    // captured at full size and every frame is scaled down to the H.264 limit
    // on the CPU, which also rules out zero-copy VideoToolbox input.
    camera_active_max_capture_size(quality, camera_active)
        .or_else(|| cfg!(target_os = "macos").then_some((H264_MAX_DIMENSION, H264_MAX_DIMENSION)))
}

#[allow(clippy::large_enum_variant)]
enum ActorState {
    Recording {
        pipeline: Pipeline,
        // pipeline_done_rx: oneshot::Receiver<Result<(), String>>,
        index: u32,
        segment_start_time: f64,
        segment_start_instant: Instant,
    },
    Paused {
        next_index: u32,
        cursors: Cursors,
        next_cursor_id: u32,
    },
}

#[derive(Clone)]
struct TerminalStopFailure {
    capture_stopped: bool,
    error: String,
}

#[derive(Debug, thiserror::Error)]
#[error("Studio capture stopped with unusable media: {source:#}")]
struct StudioCaptureStoppedError {
    #[source]
    source: anyhow::Error,
}

impl StudioCaptureStoppedError {
    fn new(source: anyhow::Error) -> Self {
        Self { source }
    }
}

fn studio_capture_stopped(error: &anyhow::Error) -> bool {
    error
        .chain()
        .any(|cause| cause.downcast_ref::<StudioCaptureStoppedError>().is_some())
}

fn accumulate_finalization_error(failure: &mut Option<anyhow::Error>, result: anyhow::Result<()>) {
    if let Err(error) = result {
        *failure = Some(match failure.take() {
            Some(previous) => previous.context(format!("{error:#}")),
            None => error,
        });
    }
}

fn persist_segment_input_events(
    response: CursorActorResponse,
    cursor_path: Option<&Path>,
    keyboard_path: Option<&Path>,
    failure: &mut Option<anyhow::Error>,
) -> (Cursors, u32) {
    if let Some(path) = cursor_path {
        let result = serde_json::to_string_pretty(&CursorEvents {
            clicks: response.clicks,
            moves: response.moves,
        })
        .map_err(anyhow::Error::from)
        .and_then(|events| {
            crate::cursor::write_atomically(path, &[events.as_bytes()]).map_err(anyhow::Error::from)
        })
        .with_context(|| format!("Could not save cursor events to {}", path.display()));
        accumulate_finalization_error(failure, result);
    }

    if !response.keyboard_presses.is_empty()
        && let Some(path) = keyboard_path
    {
        let result = KeyboardEvents {
            presses: response.keyboard_presses,
        }
        .to_bytes()
        .map_err(anyhow::Error::msg)
        .and_then(|bytes| {
            crate::cursor::write_atomically(path, &[&bytes]).map_err(anyhow::Error::from)
        })
        .with_context(|| format!("Could not save keyboard events to {}", path.display()));
        accumulate_finalization_error(failure, result);
    }

    (response.cursors, response.next_cursor_id)
}

fn minimum_segment_stop_deadline(discard: bool, segment_start: Instant) -> Option<Instant> {
    (!discard).then(|| segment_start + Duration::from_secs(1))
}

#[cfg(target_os = "linux")]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum StudioQuiescence {
    Pending,
    Joined,
    Unconfirmed,
}

#[cfg(any(target_os = "linux", target_os = "macos", windows))]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum StudioStopIntent {
    Preserve,
    Discard,
}

#[cfg(target_os = "linux")]
#[derive(Clone)]
pub struct StudioStopReport {
    pub accepted_intent: bool,
    pub quiescence: StudioQuiescence,
    pub result: Result<CompletedRecording, String>,
}

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

#[cfg(target_os = "linux")]
struct StudioLifecycleInner {
    scope: crate::output_pipeline::PipelineBuildScope,
    state: watch::Sender<StudioQuiescence>,
    failure: std::sync::Mutex<Option<String>>,
    terminal: tokio::sync::Mutex<Option<(StudioStopIntent, StudioStopReport)>>,
    terminal_started: std::sync::atomic::AtomicBool,
    runtime: std::sync::Mutex<Option<tokio::runtime::Handle>>,
}

#[cfg(target_os = "linux")]
impl StudioLifecycle {
    fn new() -> Self {
        let (state, _) = watch::channel(StudioQuiescence::Pending);
        Self(Arc::new(StudioLifecycleInner {
            scope: crate::output_pipeline::PipelineBuildScope::new_studio_lifetime(),
            state,
            failure: std::sync::Mutex::new(None),
            terminal: tokio::sync::Mutex::new(None),
            terminal_started: std::sync::atomic::AtomicBool::new(false),
            runtime: std::sync::Mutex::new(tokio::runtime::Handle::try_current().ok()),
        }))
    }

    fn fail(&self, error: String) {
        self.0.failure.lock().unwrap().get_or_insert(error);
    }

    fn failure(&self) -> Option<String> {
        self.0.failure.lock().unwrap().clone()
    }

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

    pub fn terminal_started(&self) -> bool {
        self.0
            .terminal_started
            .load(std::sync::atomic::Ordering::Acquire)
    }

    pub fn same_attempt(&self, other: &Self) -> bool {
        Arc::ptr_eq(&self.0, &other.0)
    }

    pub fn cancel(&self) {
        self.0.scope.cancel();
    }

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

    async fn join(&self) -> StudioQuiescence {
        let report = self.0.scope.cancel_and_join_report().await;
        if let Some(error) = report.error {
            self.fail(error);
        }
        let state = if report.quiescent {
            StudioQuiescence::Joined
        } else {
            StudioQuiescence::Unconfirmed
        };
        self.0.state.send_if_modified(|current| {
            if *current == StudioQuiescence::Unconfirmed {
                return false;
            }
            *current = state;
            true
        });
        self.quiescence()
    }
}

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

#[cfg(target_os = "linux")]
impl Drop for StudioLifetimeOwner {
    fn drop(&mut self) {
        if !self.armed {
            return;
        }
        self.lifecycle.cancel();
        let lifecycle = self.lifecycle.clone();
        let runtime = lifecycle.0.runtime.lock().unwrap().clone();
        if let Some(runtime) = runtime {
            drop(runtime.spawn(async move {
                lifecycle.join().await;
            }));
        } else {
            lifecycle
                .0
                .state
                .send_replace(StudioQuiescence::Unconfirmed);
        }
    }
}

#[derive(Clone)]
pub struct StudioStopOutcome {
    pub capture_stopped: bool,
    pub result: Result<CompletedRecording, String>,
}

#[cfg(any(target_os = "macos", windows))]
#[derive(Clone)]
pub struct WindowsStudioStopReport {
    pub accepted_intent: bool,
    pub stop_acknowledged: bool,
    pub result: Result<CompletedRecording, String>,
}

#[cfg(any(target_os = "macos", windows))]
#[derive(Default)]
struct WindowsStudioTerminal {
    result: tokio::sync::Mutex<Option<(StudioStopIntent, WindowsStudioStopReport)>>,
    started: std::sync::atomic::AtomicBool,
    acknowledged: std::sync::atomic::AtomicBool,
}

#[derive(Clone)]
pub struct ActorHandle {
    #[cfg(target_os = "linux")]
    lifecycle: StudioLifecycle,
    #[cfg(any(target_os = "linux", target_os = "macos", windows))]
    recording_dir: PathBuf,
    #[cfg(any(target_os = "macos", windows))]
    terminal: Arc<WindowsStudioTerminal>,
    actor_ref: kameo::actor::ActorRef<Actor>,
    pub capture_target: screen_capture::ScreenCaptureTarget,
    done_fut: DoneFut,
    // pub bounds: Bounds,
}

#[derive(kameo::Actor)]
pub struct Actor {
    diagnostic: Option<cap_utils::operation_diagnostics::Operation>,
    #[cfg(target_os = "linux")]
    lifetime: StudioLifetimeOwner,
    recording_dir: PathBuf,
    state: Option<ActorState>,
    all_tracks_stopped: bool,
    terminal_stop_failure: Option<TerminalStopFailure>,
    #[cfg(windows)]
    cancel_error: Option<String>,
    segment_factory: SegmentPipelineFactory,
    #[cfg(target_os = "linux")]
    resume_attempt: Option<ResumeAttempt>,
    #[cfg(target_os = "linux")]
    resume_generation: u64,
    #[cfg(target_os = "linux")]
    resume_cleanup_error: Option<String>,
    segments: Vec<RecordingSegment>,
    completion_tx: watch::Sender<Option<Result<(), PipelineDoneError>>>,
    // Resolved once at recording start: the display can be disconnected, or its
    // mode changed, by the time the recording stops.
    display_notch: Option<cap_project::DisplayNotch>,
}

impl Actor {
    #[cfg(target_os = "linux")]
    async fn cancel_resume(&mut self) -> anyhow::Result<()> {
        if let Some(mut attempt) = self.resume_attempt.take() {
            attempt.scope.cancel();
            let finished = attempt.finished.clone().await;
            let result = attempt.result.lock().unwrap().take();
            let cleanup = match result {
                Some(Err(error)) if error.quiescent => Ok(()),
                Some(Err(error)) => {
                    let cleanup = attempt.scope.cancel_and_join().await;
                    Err(cleanup.err().map_or(error.message.clone(), |cleanup| {
                        format!("{}; {cleanup}", error.message)
                    }))
                }
                result => {
                    discard_resume_pipeline(
                        result.and_then(Result::ok),
                        &attempt.scope,
                        &attempt.directory,
                    )
                    .await
                }
            };
            attempt.reply(Err("Recording resume was cancelled".into()));
            self.resume_cleanup_error = cleanup.err().or_else(|| finished.err());
        }
        if let Some(error) = &self.resume_cleanup_error {
            bail!("Resume cleanup is unconfirmed: {error}");
        }
        Ok(())
    }

    async fn stop_pipeline(
        &mut self,
        pipeline: Pipeline,
        segment_start_time: f64,
    ) -> anyhow::Result<(Cursors, u32)> {
        tracing::info!("pipeline shutting down");

        let stopped = pipeline.stop().await;
        #[cfg(windows)]
        let stopped = stopped.map_err(|error| self.preserve_windows_stop_failure(error));
        let PipelineStopOutcome {
            mut pipeline,
            mut media_error,
            all_tracks_stopped,
        } = stopped?;
        self.all_tracks_stopped &= all_tracks_stopped;

        tracing::info!("pipeline shutdown");

        let segment_stop_time = current_time_f64();

        let cursor_result = if let Some(cursor) = pipeline.cursor.as_mut() {
            match cursor.actor.rx.clone().await {
                Ok(result) => Some((cursor, result)),
                Err(_error) => {
                    #[cfg(windows)]
                    return Err(self.preserve_windows_stop_failure(anyhow!(
                        "Cursor shutdown acknowledgement failed: {_error}"
                    )));
                    #[cfg(not(windows))]
                    if media_error.is_some() {
                        return Err(anyhow!(
                            "Cursor shutdown acknowledgement failed after media finalization error: {_error}"
                        ));
                    } else {
                        None
                    }
                }
            }
        } else {
            None
        };
        let cursors = if let Some((cursor, res)) = cursor_result {
            persist_segment_input_events(
                res,
                cursor.output_path.as_deref(),
                cursor.keyboard_output_path.as_deref(),
                &mut media_error,
            )
        } else {
            (Default::default(), 0)
        };

        let camera_device_id = self.segment_factory.camera_device_id();
        let mic_device_id = self.segment_factory.mic_device_id();

        self.segments.push(RecordingSegment {
            start: segment_start_time,
            end: segment_stop_time,
            pipeline,
            camera_device_id,
            mic_device_id,
        });
        if let Some(error) = media_error {
            if self.all_tracks_stopped {
                return Err(anyhow::Error::new(StudioCaptureStoppedError::new(error)));
            }
            let message = format!("{UNCONFIRMED_CAPTURE_CLEANUP}: {error:#}");
            return Err(error.context(message));
        }

        Ok(cursors)
    }

    #[cfg(windows)]
    fn windows_failure(&self) -> Option<String> {
        self.cancel_error.clone().or_else(|| {
            self.completion_tx
                .borrow()
                .as_ref()
                .and_then(|result| result.as_ref().err().map(ToString::to_string))
        })
    }

    #[cfg(windows)]
    fn preserve_windows_stop_failure(&mut self, error: anyhow::Error) -> anyhow::Error {
        self.preserve_failure_evidence(error)
    }

    fn preserve_failure_evidence(&mut self, error: anyhow::Error) -> anyhow::Error {
        let error = match persist_failed_recording(&self.recording_dir, &format!("{error:#}")) {
            Ok(()) => error,
            Err(persist) => error.context(format!(
                "Could not persist failed Studio metadata: {persist:#}"
            )),
        };
        #[cfg(windows)]
        self.cancel_error
            .get_or_insert_with(|| format!("{error:#}"));
        error
    }

    fn preserve_terminal_stop_failure(
        &mut self,
        error: anyhow::Error,
        capture_stopped: bool,
    ) -> anyhow::Error {
        let error = self.preserve_failure_evidence(error);
        self.terminal_stop_failure = Some(TerminalStopFailure {
            capture_stopped,
            error: format!("{error:#}"),
        });
        error
    }

    fn notify_completion_ok(&self) {
        if self.completion_tx.borrow().is_none() {
            let _ = self.completion_tx.send(Some(Ok(())));
        }
    }

    fn update_diagnostic_segment_count(&mut self) {
        if let Some(diagnostic) = &mut self.diagnostic {
            diagnostic.field(cap_utils::operation_diagnostics::Field::number(
                "segments",
                self.segments.len() as u64,
            ));
        }
    }

    async fn handle_stop(
        &mut self,
        discard: bool,
        ctx: &mut Context<Self, anyhow::Result<CompletedRecording>>,
    ) -> anyhow::Result<CompletedRecording> {
        self.update_diagnostic_segment_count();
        if let Some(diagnostic) = &mut self.diagnostic {
            diagnostic.stage(if discard { "discarding" } else { "finalizing" });
        }
        let result = self.handle_stop_inner(discard, ctx).await;
        if !self.segments.is_empty() {
            self.update_diagnostic_segment_count();
        }
        if let Some(diagnostic) = self.diagnostic.take() {
            diagnostic.finish(result.is_ok());
        }
        result
    }

    async fn handle_stop_inner(
        &mut self,
        discard: bool,
        ctx: &mut Context<Self, anyhow::Result<CompletedRecording>>,
    ) -> anyhow::Result<CompletedRecording> {
        #[cfg(target_os = "linux")]
        self.cancel_resume().await?;
        if let Some(failure) = self.terminal_stop_failure.as_ref() {
            let error = anyhow!(failure.error.clone());
            if failure.capture_stopped && self.all_tracks_stopped {
                let error = anyhow::Error::new(StudioCaptureStoppedError::new(error));
                let error = match ctx.actor_ref().stop_gracefully().await {
                    Ok(()) => error,
                    Err(stop_error) => error.context(format!(
                        "Studio actor stop acknowledgement failed: {stop_error}"
                    )),
                };
                return Err(error);
            }
            return Err(error);
        }
        let cursors = match self.state.take() {
            Some(ActorState::Recording {
                pipeline,
                segment_start_time,
                segment_start_instant,
                ..
            }) => {
                let segment_start_instant = self
                    .segment_factory
                    .start_gate()
                    .and_then(RecordingStartGate::armed_at)
                    .map(|armed| armed.instant().max(segment_start_instant))
                    .unwrap_or(segment_start_instant);
                if let Some(deadline) =
                    minimum_segment_stop_deadline(discard, segment_start_instant)
                {
                    tokio::time::sleep_until(deadline.into()).await;
                }

                match self.stop_pipeline(pipeline, segment_start_time).await {
                    Ok((cursors, _)) => cursors,
                    Err(error) if studio_capture_stopped(&error) => {
                        let error = self.preserve_failure_evidence(error);
                        let error = match ctx.actor_ref().stop_gracefully().await {
                            Ok(()) => error,
                            Err(stop_error) => error.context(format!(
                                "Studio actor stop acknowledgement failed: {stop_error}"
                            )),
                        };
                        return Err(error);
                    }
                    Err(error) => return Err(error),
                }
            }
            Some(ActorState::Paused { cursors, .. }) => cursors,
            _ => return Err(anyhow!("Not recording")),
        };

        if let Err(stop_error) = ctx.actor_ref().stop_gracefully().await {
            let error = anyhow!("Studio actor stop acknowledgement failed: {stop_error}");
            let error = if self.all_tracks_stopped {
                anyhow::Error::new(StudioCaptureStoppedError::new(error))
            } else {
                error
            };
            return Err(self.preserve_failure_evidence(error));
        }

        #[cfg(target_os = "linux")]
        let known_failure = {
            if self.lifetime.lifecycle.join().await != StudioQuiescence::Joined {
                bail!("Studio capture cleanup is unconfirmed; recording preserved");
            }
            self.lifetime.lifecycle.failure()
        };
        #[cfg(windows)]
        let known_failure = self.windows_failure();
        #[cfg(not(any(target_os = "linux", windows)))]
        let known_failure = None;
        let known_failure = if self.all_tracks_stopped {
            known_failure
        } else {
            Some(match known_failure {
                Some(error) => format!("{UNCONFIRMED_CAPTURE_CLEANUP}: {error}"),
                None => UNCONFIRMED_CAPTURE_CLEANUP.to_string(),
            })
        };

        self.update_diagnostic_segment_count();
        let recording = stop_recording(
            self.recording_dir.clone(),
            std::mem::take(&mut self.segments),
            cursors,
            self.segment_factory.fragmented,
            self.display_notch,
            known_failure,
        )
        .await;
        let recording = match recording {
            Ok(recording) => recording,
            Err(error) => {
                let error = if self.all_tracks_stopped {
                    anyhow::Error::new(StudioCaptureStoppedError::new(error))
                } else {
                    error
                };
                return Err(self.preserve_failure_evidence(error));
            }
        };

        if !self.all_tracks_stopped {
            return Err(self.preserve_failure_evidence(anyhow!(UNCONFIRMED_CAPTURE_CLEANUP)));
        }

        self.notify_completion_ok();

        Ok(recording)
    }
}

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

    async fn handle(&mut self, _: Stop, ctx: &mut Context<Self, Self::Reply>) -> Self::Reply {
        self.handle_stop(false, ctx).await
    }
}

struct StopWithIntent {
    discard: bool,
}

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

    async fn handle(
        &mut self,
        message: StopWithIntent,
        ctx: &mut Context<Self, Self::Reply>,
    ) -> Self::Reply {
        self.handle_stop(message.discard, ctx).await
    }
}

struct Pause;

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

    async fn handle(&mut self, _: Pause, _: &mut Context<Self, Self::Reply>) -> Self::Reply {
        #[cfg(target_os = "linux")]
        self.cancel_resume().await?;
        match self.state.take() {
            Some(ActorState::Recording {
                pipeline,
                segment_start_time,
                index,
                ..
            }) => {
                if let Some(diagnostic) = &mut self.diagnostic {
                    diagnostic.stage("pausing");
                }
                let stopped = self
                    .stop_pipeline(pipeline, segment_start_time)
                    .await
                    .context("stop_pipeline");
                match stopped {
                    Ok((cursors, next_cursor_id)) if self.all_tracks_stopped => {
                        self.state = Some(ActorState::Paused {
                            next_index: index + 1,
                            cursors,
                            next_cursor_id,
                        });
                        if let Some(diagnostic) = &mut self.diagnostic {
                            diagnostic.stage("paused");
                        }
                    }
                    Ok(_) => {
                        let error = anyhow!(UNCONFIRMED_CAPTURE_CLEANUP);
                        return Err(self.preserve_terminal_stop_failure(error, false));
                    }
                    Err(error) => {
                        let capture_stopped = studio_capture_stopped(&error);
                        let error = self.preserve_terminal_stop_failure(error, capture_stopped);
                        return Err(error);
                    }
                }
            }
            state => self.state = state,
        }

        Ok(())
    }
}

#[cfg(target_os = "linux")]
type ResumeCompletion =
    futures::future::Shared<futures::future::BoxFuture<'static, Result<(), String>>>;

#[cfg(target_os = "linux")]
struct ResumeBuildError {
    message: String,
    quiescent: bool,
}

#[cfg(target_os = "linux")]
struct ResumeAttempt {
    generation: u64,
    scope: crate::output_pipeline::PipelineBuildScope,
    directory: PathBuf,
    result: Arc<std::sync::Mutex<Option<Result<Pipeline, ResumeBuildError>>>>,
    finished: ResumeCompletion,
    ready: ResumeCompletion,
    reply: Option<tokio::sync::oneshot::Sender<Result<(), String>>>,
}

#[cfg(target_os = "linux")]
struct ResumeWaiterGuard(crate::output_pipeline::PipelineBuildScope);

#[cfg(target_os = "linux")]
impl Drop for ResumeWaiterGuard {
    fn drop(&mut self) {
        self.0.cancel();
    }
}

#[cfg(target_os = "linux")]
impl ResumeAttempt {
    fn ready_future(&self) -> futures::future::BoxFuture<'static, anyhow::Result<()>> {
        let ready = self.ready.clone();
        let cancellation = ResumeWaiterGuard(self.scope.clone());
        async move {
            let _cancellation = cancellation;
            ready.await.map_err(anyhow::Error::msg)
        }
        .boxed()
    }

    fn reply(&mut self, result: Result<(), String>) {
        if let Some(reply) = self.reply.take() {
            let _ = reply.send(result);
        }
    }
}

#[cfg(target_os = "linux")]
async fn discard_resume_pipeline(
    pipeline: Option<Pipeline>,
    scope: &crate::output_pipeline::PipelineBuildScope,
    directory: &Path,
) -> Result<(), String> {
    scope.cancel();
    let mut cursor_error = None;
    if let Some(mut pipeline) = pipeline {
        if let Some(mut cursor) = pipeline.cursor.take() {
            cursor_error = tokio::task::spawn_blocking(move || cursor.actor.stop())
                .await
                .err()
                .map(|error| format!("Cursor setup cleanup failed: {error}"));
        }
        drop(pipeline);
    }
    scope.cancel_and_join().await?;
    if let Some(error) = cursor_error {
        return Err(error);
    }
    match tokio::fs::remove_dir_all(directory).await {
        Ok(()) => Ok(()),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
        Err(error) => Err(format!(
            "Failed to remove discarded resume segment: {error}"
        )),
    }
}

#[cfg(target_os = "linux")]
async fn prepare_resume_pipeline(
    factory: &mut SegmentPipelineFactory,
    cursors: Cursors,
    next_cursor_id: u32,
    scope: &crate::output_pipeline::PipelineBuildScope,
    directory: &Path,
) -> Result<Pipeline, ResumeBuildError> {
    let cancellation = scope.cancellation();
    let prepared = scope.run(async {
        tokio::select! {
            biased;
            _ = cancellation.cancelled() => Err("Recording resume was cancelled".to_string()),
            result = std::panic::AssertUnwindSafe(factory.prepare_next(cursors, next_cursor_id)).catch_unwind() => {
                match result {
                    Ok(result) => result.map_err(|error| format!("{error:#}")),
                    Err(_) => Err("Recording resume setup panicked".to_string()),
                }
            }
        }
    }).await;
    let (pipeline, message) = match prepared {
        Ok(pipeline) if !cancellation.is_cancelled() => return Ok(pipeline),
        Ok(pipeline) => (Some(pipeline), "Recording resume was cancelled".to_string()),
        Err(message) => (None, message),
    };
    let cleanup = discard_resume_pipeline(pipeline, scope, directory).await;
    Err(ResumeBuildError {
        message: cleanup.as_ref().err().map_or(message.clone(), |cleanup| {
            format!("{message}; cleanup unconfirmed: {cleanup}")
        }),
        quiescent: cleanup.is_ok(),
    })
}

#[cfg(target_os = "linux")]
struct ResumeFinished(u64);

#[cfg(target_os = "linux")]
impl Message<ResumeFinished> for Actor {
    type Reply = ();

    async fn handle(&mut self, msg: ResumeFinished, _: &mut Context<Self, Self::Reply>) {
        if self
            .resume_attempt
            .as_ref()
            .is_none_or(|attempt| attempt.generation != msg.0)
        {
            return;
        }
        let mut attempt = self.resume_attempt.take().unwrap();
        let result = attempt.result.lock().unwrap().take();
        match result {
            Some(Ok(mut pipeline)) if !attempt.scope.cancellation().is_cancelled() => {
                if let Some(error) = pipeline.completed_before_resume() {
                    let cleanup =
                        discard_resume_pipeline(Some(pipeline), &attempt.scope, &attempt.directory)
                            .await;
                    self.resume_cleanup_error = cleanup.err();
                    attempt.reply(Err(error));
                    return;
                }
                if let Some(ActorState::Paused { next_index, .. }) = self.state.as_ref()
                    && attempt.scope.commit()
                {
                    let index = *next_index;
                    self.segment_factory.commit_next(&mut pipeline);
                    self.state = Some(ActorState::Recording {
                        pipeline,
                        index,
                        segment_start_time: current_time_f64(),
                        segment_start_instant: Instant::now(),
                    });
                    if let Some(diagnostic) = &mut self.diagnostic {
                        diagnostic.stage("recording");
                    }
                    attempt.reply(Ok(()));
                } else {
                    let cleanup =
                        discard_resume_pipeline(Some(pipeline), &attempt.scope, &attempt.directory)
                            .await;
                    self.resume_cleanup_error = cleanup.err();
                    attempt.reply(Err("Recording changed during resume".into()));
                }
            }
            Some(Err(error)) => {
                if !error.quiescent {
                    self.resume_cleanup_error = Some(error.message.clone());
                }
                attempt.reply(Err(error.message));
            }
            result => {
                let pipeline = result.and_then(Result::ok);
                let cleanup =
                    discard_resume_pipeline(pipeline, &attempt.scope, &attempt.directory).await;
                self.resume_cleanup_error = cleanup.err();
                attempt.reply(Err("Recording resume was cancelled".into()));
            }
        }
    }
}

struct Resume;

#[cfg(target_os = "linux")]
impl Message<Resume> for Actor {
    type Reply = anyhow::Result<futures::future::BoxFuture<'static, anyhow::Result<()>>>;

    async fn handle(&mut self, _: Resume, ctx: &mut Context<Self, Self::Reply>) -> Self::Reply {
        if !self.all_tracks_stopped {
            bail!(UNCONFIRMED_CAPTURE_CLEANUP);
        }
        if self
            .completion_tx
            .borrow()
            .as_ref()
            .is_some_and(Result::is_err)
        {
            bail!("A requested recording track failed; stop and preserve this recording");
        }
        if let Some(error) = &self.resume_cleanup_error {
            bail!("Previous resume cleanup is unconfirmed: {error}");
        }
        if let Some(attempt) = &self.resume_attempt {
            return Ok(attempt.ready_future());
        }
        let (cursors, next_cursor_id) = match &self.state {
            Some(ActorState::Paused {
                cursors,
                next_cursor_id,
                ..
            }) => (cursors.clone(), *next_cursor_id),
            Some(ActorState::Recording { .. }) => return Ok(async { Ok(()) }.boxed()),
            None => bail!("Recording is no longer active"),
        };
        let mut factory = self.segment_factory.clone();
        let directory = factory
            .segments_dir
            .join(format!("segment-{}", factory.index));
        if directory.try_exists()? {
            bail!(
                "Resume segment directory already exists; stop and recover the recording before retrying"
            );
        }
        self.resume_generation = self.resume_generation.wrapping_add(1);
        let generation = self.resume_generation;
        let scope = self.lifetime.lifecycle.0.scope.child_transaction();
        let lifetime_completion = self.lifetime.lifecycle.0.scope.task_completion();
        let result = Arc::new(std::sync::Mutex::new(None));
        let (finished_tx, finished_rx) = tokio::sync::oneshot::channel();
        let (reply, ready) = tokio::sync::oneshot::channel();
        let attempt = ResumeAttempt {
            generation,
            scope: scope.clone(),
            directory: directory.clone(),
            result: result.clone(),
            finished: async move {
                finished_rx
                    .await
                    .map_err(|_| "Resume setup task exited unexpectedly".to_string())
            }
            .boxed()
            .shared(),
            ready: async move {
                ready
                    .await
                    .map_err(|_| "Resume acknowledgement was lost".to_string())?
            }
            .boxed()
            .shared(),
            reply: Some(reply),
        };
        let ready = attempt.ready_future();
        self.resume_attempt = Some(attempt);
        if let Some(diagnostic) = &mut self.diagnostic {
            diagnostic.stage("resuming");
        }
        let actor = ctx.actor_ref().clone();
        drop(tokio::spawn(async move {
            let prepared = std::panic::AssertUnwindSafe(prepare_resume_pipeline(
                &mut factory,
                cursors,
                next_cursor_id,
                &scope,
                &directory,
            ))
            .catch_unwind()
            .await
            .unwrap_or_else(|_| {
                scope.cancel();
                Err(ResumeBuildError {
                    message: "Resume setup or cleanup panicked; capture quiescence is unconfirmed"
                        .into(),
                    quiescent: false,
                })
            });
            *result.lock().unwrap() = Some(prepared);
            let _ = finished_tx.send(());
            let _ = notify_after_capture_publication(
                lifetime_completion,
                actor.tell(ResumeFinished(generation)),
            )
            .await;
        }));
        Ok(ready)
    }
}

#[cfg(target_os = "linux")]
async fn notify_after_capture_publication<T>(
    completion: crate::output_pipeline::BuildTaskCompletion,
    notification: impl std::future::IntoFuture<Output = T>,
) -> T {
    drop(completion);
    notification.await
}

#[cfg(not(target_os = "linux"))]
impl Message<Resume> for Actor {
    type Reply = anyhow::Result<()>;

    async fn handle(&mut self, _: Resume, _: &mut Context<Self, Self::Reply>) -> Self::Reply {
        if !self.all_tracks_stopped {
            bail!(UNCONFIRMED_CAPTURE_CLEANUP);
        }
        match self.state.as_ref() {
            Some(ActorState::Paused {
                next_index,
                cursors,
                next_cursor_id,
            }) => {
                let next_index = *next_index;
                let next_cursor_id = *next_cursor_id;
                let cursors = cursors.clone();
                if let Some(diagnostic) = &mut self.diagnostic {
                    diagnostic.stage("resuming");
                }
                let pipeline = self
                    .segment_factory
                    .create_next(cursors, next_cursor_id)
                    .await;
                let pipeline = match pipeline {
                    Ok(pipeline) => pipeline,
                    Err(error) => {
                        if error.downcast_ref::<crate::output_pipeline::PipelineStartupCleanupUnconfirmed>().is_some() {
                            self.all_tracks_stopped = false;
                            self.state = None;
                            if let Some(diagnostic) = &mut self.diagnostic {
                                diagnostic.stage("resume_cleanup_failed");
                            }
                            return Err(self.preserve_terminal_stop_failure(error, false));
                        }
                        warn!(error = %format!("{error:#}"), "Studio resume failed; retaining paused recording");
                        if let Some(diagnostic) = &mut self.diagnostic {
                            diagnostic.stage("paused");
                        }
                        let message = format!(
                            "Could not resume recording: {error:#}. Your recording is still paused; you can retry or press Stop to save it"
                        );
                        return Err(error.context(message));
                    }
                };

                if let Some(diagnostic) = &mut self.diagnostic {
                    diagnostic.stage("recording");
                }
                let new_segment_start_time = current_time_f64();

                self.state = Some(ActorState::Recording {
                    pipeline,
                    index: next_index,
                    segment_start_time: new_segment_start_time,
                    segment_start_instant: Instant::now(),
                });
            }
            Some(ActorState::Recording { .. }) => {}
            None => bail!("Recording no longer active"),
        }

        Ok(())
    }
}

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");
        }
        #[cfg(target_os = "linux")]
        self.cancel_resume().await?;
        if let Some(failure) = self.terminal_stop_failure.as_ref() {
            bail!("Previous Studio stop failed: {}", failure.error);
        }
        #[cfg(windows)]
        if let Some(error) = &self.cancel_error {
            bail!("Previous capture cancellation failed: {error}");
        }
        if let Some(ActorState::Recording { pipeline, .. }) = self.state.take() {
            let stopped = match pipeline.stop().await {
                Ok(stopped) => stopped,
                Err(error) => {
                    let error = error.context("Pipeline stop failed during Studio cancellation");
                    return Err(self.preserve_terminal_stop_failure(error, false));
                }
            };
            let PipelineStopOutcome {
                mut media_error,
                all_tracks_stopped,
                ..
            } = stopped;
            self.all_tracks_stopped &= all_tracks_stopped;
            if !self.all_tracks_stopped {
                let error = match media_error.take() {
                    Some(error) => {
                        let message = format!("{UNCONFIRMED_CAPTURE_CLEANUP}: {error:#}");
                        error.context(message)
                    }
                    None => anyhow!(UNCONFIRMED_CAPTURE_CLEANUP),
                };
                return Err(self.preserve_terminal_stop_failure(error, false));
            }
            if let Some(error) = media_error {
                let error = error.context("Studio cancellation found unusable media");
                return Err(self.preserve_terminal_stop_failure(error, false));
            }

            #[cfg(windows)]
            if let Some(error) = self.windows_failure() {
                return Err(self.preserve_windows_stop_failure(anyhow!(error)));
            }
            self.notify_completion_ok();
        }

        #[cfg(windows)]
        if let Some(error) = self.windows_failure() {
            return Err(self.preserve_windows_stop_failure(anyhow!(error)));
        }
        if let Some(diagnostic) = self.diagnostic.take() {
            diagnostic.finish(true);
        }
        Ok(())
    }
}

struct SetMicFeed {
    mic_feed: Option<Arc<MicrophoneFeedLock>>,
}

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

    async fn handle(&mut self, msg: SetMicFeed, _: &mut Context<Self, Self::Reply>) -> Self::Reply {
        #[cfg(target_os = "linux")]
        if self.resume_attempt.is_some() || self.resume_cleanup_error.is_some() {
            bail!("Recording resume or its cleanup is still pending");
        }
        match self.state.as_ref() {
            Some(ActorState::Recording { .. }) => {
                bail!("Pause the recording before changing microphone input")
            }
            Some(ActorState::Paused { .. }) => {
                self.segment_factory.set_mic_feed(msg.mic_feed);
                Ok(())
            }
            None => Err(anyhow!("Recording no longer active")),
        }
    }
}

struct SetCameraFeed {
    camera_feed: Option<Arc<CameraFeedLock>>,
}

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

    async fn handle(
        &mut self,
        msg: SetCameraFeed,
        _: &mut Context<Self, Self::Reply>,
    ) -> Self::Reply {
        #[cfg(target_os = "linux")]
        if self.resume_attempt.is_some() || self.resume_cleanup_error.is_some() {
            bail!("Recording resume or its cleanup is still pending");
        }
        match self.state.as_ref() {
            Some(ActorState::Recording { .. }) => {
                bail!("Pause the recording before changing camera input")
            }
            Some(ActorState::Paused { .. }) => {
                self.segment_factory.set_camera_feed(msg.camera_feed);
                Ok(())
            }
            None => Err(anyhow!("Recording no longer active")),
        }
    }
}

pub struct IsPaused;

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

    async fn handle(&mut self, _: IsPaused, _: &mut Context<Self, Self::Reply>) -> Self::Reply {
        #[cfg(target_os = "linux")]
        if self.resume_attempt.is_some() || self.resume_cleanup_error.is_some() {
            return false;
        }
        matches!(self.state, Some(ActorState::Paused { .. }))
    }
}

pub struct RecordingSegment {
    pub start: f64,
    pub end: f64,
    pipeline: FinishedPipeline,
    pub camera_device_id: Option<String>,
    pub mic_device_id: Option<String>,
}

pub struct ScreenPipelineOutput {
    pub inner: OutputPipeline,
    pub video_info: VideoInfo,
}

struct Pipeline {
    pub start_time: Timestamps,
    /// Present for a primed first segment; its arm point is the epoch every
    /// persisted start time and input event is measured from.
    pub start_gate: Option<RecordingStartGate>,
    // sources
    pub screen: OutputPipeline,
    pub microphone: Option<OutputPipeline>,
    pub camera: Option<OutputPipeline>,
    pub system_audio: Option<OutputPipeline>,
    pub cursor: Option<CursorPipeline>,
    pub track_failures: SharedTrackFailures,
    pub watcher_task: Option<JoinHandle<()>>,
    #[cfg(any(target_os = "linux", windows))]
    stopping: Arc<std::sync::atomic::AtomicBool>,
}

struct FinishedPipeline {
    pub start_time: Timestamps,
    // sources
    pub screen: FinishedOutputPipeline,
    pub microphone: Option<FinishedOutputPipeline>,
    pub camera: Option<FinishedOutputPipeline>,
    pub system_audio: Option<FinishedOutputPipeline>,
    pub cursor: Option<CursorPipeline>,
    pub track_failures: Vec<TrackFailureRecord>,
}

struct PipelineStopOutcome {
    pipeline: FinishedPipeline,
    media_error: Option<anyhow::Error>,
    all_tracks_stopped: bool,
}

fn classify_pipeline_stop_errors(
    stop_errors: &[String],
    media_errors: &[String],
) -> anyhow::Result<Option<anyhow::Error>> {
    if !media_errors.is_empty() && !stop_errors.is_empty() {
        bail!(
            "Studio media failed after one producer stopped, but other capture cleanup is unconfirmed: {}; media errors: {}",
            stop_errors.join("; "),
            media_errors.join("; ")
        );
    }

    Ok((!media_errors.is_empty()).then(|| {
        anyhow!(
            "Studio media finalization failed after all capture producers stopped: {}",
            media_errors.join("; ")
        )
    }))
}

#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
enum RecordingTrackKind {
    Display,
    Microphone,
    Camera,
    SystemAudio,
}

#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
enum TrackFailureStage {
    Runtime,
    Stop,
}

#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
struct TrackFailureRecord {
    track: RecordingTrackKind,
    stage: TrackFailureStage,
    error: String,
}

type SharedTrackFailures = Arc<std::sync::Mutex<Vec<TrackFailureRecord>>>;

#[derive(Debug, Clone, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
struct RecordingFailureDiagnostics {
    version: u32,
    segments: Vec<SegmentFailureDiagnostics>,
}

#[derive(Debug, Clone, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
struct SegmentFailureDiagnostics {
    segment_index: u32,
    start: f64,
    end: f64,
    track_failures: Vec<TrackFailureRecord>,
}

struct SegmentOutput {
    meta: MultipleSegment,
    diagnostics: Option<SegmentFailureDiagnostics>,
    duration: f64,
}

fn to_project_gap_summary(
    summary: Option<AudioGapSummary>,
) -> Option<cap_project::AudioGapSummary> {
    summary.map(|s| cap_project::AudioGapSummary {
        total_overlap_trimmed_ms: s.total_overlap_trimmed_ms,
        startup_overlap_trimmed_ms: s.startup_overlap_trimmed_ms,
        overlap_dropped_frames: s.overlap_dropped_frames,
        startup_overlap_drops: s.startup_overlap_drops,
    })
}

fn record_track_failure(
    failures: &SharedTrackFailures,
    track: RecordingTrackKind,
    stage: TrackFailureStage,
    error: impl Into<String>,
) {
    let error = error.into();
    match failures.lock() {
        Ok(mut failures) => failures.push(TrackFailureRecord {
            track,
            stage,
            error,
        }),
        Err(poisoned) => poisoned.into_inner().push(TrackFailureRecord {
            track,
            stage,
            error,
        }),
    }
}

fn take_track_failures(failures: &SharedTrackFailures) -> Vec<TrackFailureRecord> {
    match failures.lock() {
        Ok(mut failures) => std::mem::take(&mut *failures),
        Err(poisoned) => {
            let mut failures = poisoned.into_inner();
            std::mem::take(&mut *failures)
        }
    }
}

fn has_track_failure(failures: &SharedTrackFailures, track: RecordingTrackKind) -> bool {
    match failures.lock() {
        Ok(failures) => failures.iter().any(|failure| failure.track == track),
        Err(poisoned) => poisoned
            .into_inner()
            .iter()
            .any(|failure| failure.track == track),
    }
}

fn finalize_optional_track(
    track: RecordingTrackKind,
    result: Result<Option<FinishedOutputPipeline>, anyhow::Error>,
    failures: &SharedTrackFailures,
) -> Option<FinishedOutputPipeline> {
    match result {
        Ok(value) => value,
        Err(error) => {
            warn!(?track, error = %error, "Optional recording track failed during stop");
            if !has_track_failure(failures, track) {
                record_track_failure(failures, track, TrackFailureStage::Stop, error.to_string());
            }
            None
        }
    }
}

fn build_recording_failure_diagnostics(
    segments: &[SegmentFailureDiagnostics],
) -> Option<RecordingFailureDiagnostics> {
    if segments.is_empty() {
        None
    } else {
        Some(RecordingFailureDiagnostics {
            version: 2,
            segments: segments.to_vec(),
        })
    }
}

fn write_recording_failure_diagnostics(
    recording_dir: &Path,
    diagnostics: &RecordingFailureDiagnostics,
) -> Result<(), RecordingError> {
    std::fs::write(
        recording_dir.join("recording-diagnostics.json"),
        serde_json::to_string_pretty(diagnostics)?,
    )?;
    Ok(())
}

impl Pipeline {
    fn epoch(&self) -> Timestamps {
        pipeline_epoch(self.start_time, self.start_gate.as_ref())
    }

    /// Writes the tracks' start times beside the segment as soon as their
    /// first frames arrive and again as more tracks start, so a crash keeps
    /// the alignment a normal stop would persist.
    fn spawn_start_time_persister(&self) {
        let Some(segment_dir) = self.screen.path().parent().map(Path::to_path_buf) else {
            return;
        };
        let start_time = self.start_time;
        let start_gate = self.start_gate.clone();
        let mut display = Some(self.screen.first_timestamp_watch());
        let mut tracks = [
            self.microphone.as_ref().map(|p| p.first_timestamp_watch()),
            self.camera.as_ref().map(|p| p.first_timestamp_watch()),
            self.system_audio
                .as_ref()
                .map(|p| p.first_timestamp_watch()),
        ];
        tokio::spawn(async move {
            const WRITE_ATTEMPTS: u32 = 5;
            let mut firsts: [Option<Timestamp>; 4] = [None; 4];
            let mut written = None;
            let mut failed_writes = 0;
            loop {
                if let Some(watch) = &mut display {
                    firsts[0] = firsts[0].or(*watch.borrow_and_update());
                }
                for (first, watch) in firsts[1..].iter_mut().zip(tracks.iter_mut()) {
                    if let Some(watch) = watch {
                        *first = first.or(*watch.borrow_and_update());
                    }
                }
                if let Some(display_first) = firsts[0] {
                    let times = SegmentStartTimes::compute(
                        pipeline_epoch(start_time, start_gate.as_ref()),
                        display_first,
                        firsts[1],
                        firsts[2],
                        firsts[3],
                    );
                    if written != Some(times) {
                        // A blocking write and two fsyncs: keep them off the
                        // runtime workers the capture pipelines run on.
                        let dir = segment_dir.clone();
                        let result = tokio::task::spawn_blocking(move || {
                            write_segment_start_times(&dir, &times)
                        })
                        .await
                        .unwrap_or_else(|error| Err(std::io::Error::other(error)));
                        match result {
                            Ok(()) => written = Some(times),
                            Err(error) => {
                                failed_writes += 1;
                                warn!(%error, failed_writes, "Failed to persist segment start times");
                                if failed_writes >= WRITE_ATTEMPTS {
                                    return;
                                }
                                tokio::time::sleep(Duration::from_millis(200)).await;
                                continue;
                            }
                        }
                    }
                }
                let display_waiting = firsts[0].is_none() && display.is_some();
                let tracks_waiting: [bool; 3] =
                    std::array::from_fn(|i| firsts[i + 1].is_none() && tracks[i].is_some());
                if !display_waiting && !tracks_waiting.contains(&true) {
                    return;
                }
                let [mic, camera, system_audio] = &mut tracks;
                tokio::select! {
                    result = changed(&mut display), if display_waiting => {
                        if result.is_err() {
                            return;
                        }
                    }
                    result = changed(mic), if tracks_waiting[0] => {
                        if result.is_err() {
                            *mic = None;
                        }
                    }
                    result = changed(camera), if tracks_waiting[1] => {
                        if result.is_err() {
                            *camera = None;
                        }
                    }
                    result = changed(system_audio), if tracks_waiting[2] => {
                        if result.is_err() {
                            *system_audio = None;
                        }
                    }
                }
            }
        });
    }

    #[cfg(target_os = "linux")]
    fn completed_before_resume(&self) -> Option<String> {
        [
            ("display", Some(&self.screen)),
            ("microphone", self.microphone.as_ref()),
            ("camera", self.camera.as_ref()),
            ("system audio", self.system_audio.as_ref()),
        ]
        .into_iter()
        .find_map(|(track, pipeline)| {
            pipeline
                .and_then(|pipeline| pipeline.done_fut().now_or_never())
                .map(|result| match result {
                    Ok(()) => format!("{track} capture ended before resume was committed"),
                    Err(error) => {
                        format!("{track} capture failed before resume was committed: {error}")
                    }
                })
        })
    }

    pub async fn stop(mut self) -> anyhow::Result<PipelineStopOutcome> {
        let stop_started = Instant::now();
        let epoch = self.epoch();
        #[cfg(any(target_os = "linux", windows))]
        self.stopping
            .store(true, std::sync::atomic::Ordering::Release);
        #[cfg(target_os = "macos")]
        let (screen, microphone, camera, system_audio) = {
            let (microphone, camera, (screen, system_audio)) = futures::join!(
                OptionFuture::from(self.microphone.map(|s| s.stop_with_outcome())),
                OptionFuture::from(self.camera.map(|s| s.stop_with_outcome())),
                async {
                    // These sources share a capturer; only the first stop awaits its native acknowledgement.
                    let system_audio =
                        OptionFuture::from(self.system_audio.map(|s| s.stop_with_outcome())).await;
                    (self.screen.stop_with_outcome().await, system_audio)
                }
            );
            (screen, microphone, camera, system_audio)
        };
        #[cfg(not(target_os = "macos"))]
        let (screen, microphone, camera, system_audio) = futures::join!(
            self.screen.stop_with_outcome(),
            OptionFuture::from(self.microphone.map(|s| s.stop_with_outcome())),
            OptionFuture::from(self.camera.map(|s| s.stop_with_outcome())),
            OptionFuture::from(self.system_audio.map(|s| s.stop_with_outcome()))
        );

        tracing::info!(
            elapsed_ms = stop_started.elapsed().as_secs_f64() * 1000.0,
            "Studio capture pipelines stopped"
        );

        if let Some(cursor) = self.cursor.as_mut() {
            cursor.actor.stop();
        }

        if let Some(watcher_task) = self.watcher_task.take()
            && let Err(error) = watcher_task.await
        {
            warn!(error = %error, "Studio recording watcher task ended unexpectedly");
            return Err(anyhow!(
                "Studio recording watcher acknowledgement failed: {error}"
            ));
        }

        let stop_errors = [
            ("display", screen.as_ref().err()),
            (
                "microphone",
                microphone.as_ref().and_then(|result| result.as_ref().err()),
            ),
            (
                "camera",
                camera.as_ref().and_then(|result| result.as_ref().err()),
            ),
            (
                "system audio",
                system_audio
                    .as_ref()
                    .and_then(|result| result.as_ref().err()),
            ),
        ]
        .into_iter()
        .filter_map(|(track, error)| error.map(|error| format!("{track}: {error:#}")))
        .collect::<Vec<_>>();

        let media_errors = [
            (
                "display",
                screen
                    .as_ref()
                    .ok()
                    .and_then(|outcome| outcome.media_error.as_ref()),
            ),
            (
                "microphone",
                microphone
                    .as_ref()
                    .and_then(|result| result.as_ref().ok())
                    .and_then(|outcome| outcome.media_error.as_ref()),
            ),
            (
                "camera",
                camera
                    .as_ref()
                    .and_then(|result| result.as_ref().ok())
                    .and_then(|outcome| outcome.media_error.as_ref()),
            ),
            (
                "system audio",
                system_audio
                    .as_ref()
                    .and_then(|result| result.as_ref().ok())
                    .and_then(|outcome| outcome.media_error.as_ref()),
            ),
        ]
        .into_iter()
        .filter_map(|(track, error)| error.map(|error| format!("{track}: {error:#}")))
        .collect::<Vec<_>>();

        let media_error = classify_pipeline_stop_errors(&stop_errors, &media_errors)?;

        #[cfg(windows)]
        if !stop_errors.is_empty() {
            bail!(
                "Requested Studio track stop failed; capture cleanup is unconfirmed: {}",
                stop_errors.join("; ")
            );
        }

        let microphone = microphone
            .transpose()
            .map(|outcome| outcome.map(|outcome| outcome.finished));
        let camera = camera
            .transpose()
            .map(|outcome| outcome.map(|outcome| outcome.finished));
        let system_audio = system_audio
            .transpose()
            .map(|outcome| outcome.map(|outcome| outcome.finished));

        Ok(PipelineStopOutcome {
            pipeline: FinishedPipeline {
                start_time: epoch,
                screen: screen.context("display")?.finished,
                microphone: finalize_optional_track(
                    RecordingTrackKind::Microphone,
                    microphone,
                    &self.track_failures,
                ),
                camera: finalize_optional_track(
                    RecordingTrackKind::Camera,
                    camera,
                    &self.track_failures,
                ),
                system_audio: finalize_optional_track(
                    RecordingTrackKind::SystemAudio,
                    system_audio,
                    &self.track_failures,
                ),
                cursor: self.cursor,
                track_failures: take_track_failures(&self.track_failures),
            },
            media_error,
            all_tracks_stopped: stop_errors.is_empty(),
        })
    }

    fn spawn_watcher(
        &mut self,
        completion_tx: watch::Sender<Option<Result<(), PipelineDoneError>>>,
    ) {
        let mut futures = FuturesUnordered::<
            Pin<
                Box<
                    dyn futures::Future<
                            Output = (RecordingTrackKind, bool, Result<(), PipelineDoneError>),
                        > + Send,
                >,
            >,
        >::new();
        futures.push(Box::pin({
            let done_fut = self.screen.done_fut();
            async move { (RecordingTrackKind::Display, true, done_fut.await) }
        }));

        if let Some(ref microphone) = self.microphone {
            futures.push(Box::pin({
                let done_fut = microphone.done_fut();
                async move { (RecordingTrackKind::Microphone, false, done_fut.await) }
            }));
        }

        if let Some(ref camera) = self.camera {
            futures.push(Box::pin({
                let done_fut = camera.done_fut();
                async move { (RecordingTrackKind::Camera, false, done_fut.await) }
            }));
        }

        if let Some(ref system_audio) = self.system_audio {
            futures.push(Box::pin({
                let done_fut = system_audio.done_fut();
                async move { (RecordingTrackKind::SystemAudio, false, done_fut.await) }
            }));
        }

        // Ensure non-video pipelines stop promptly when the video pipeline completes
        #[cfg(not(any(target_os = "linux", windows)))]
        {
            let mic_cancel = self.microphone.as_ref().map(|p| p.cancel_token());
            let cam_cancel = self.camera.as_ref().map(|p| p.cancel_token());
            let sys_cancel = self.system_audio.as_ref().map(|p| p.cancel_token());

            let screen_done = self.screen.done_fut();
            tokio::spawn(async move {
                // When screen (video) finishes, cancel the other pipelines
                let _ = screen_done.await;
                if let Some(token) = mic_cancel.as_ref() {
                    token.cancel();
                }
                if let Some(token) = cam_cancel.as_ref() {
                    token.cancel();
                }
                if let Some(token) = sys_cancel.as_ref() {
                    token.cancel();
                }
            });
        }

        #[cfg(any(target_os = "linux", windows))]
        let cancel_tokens = [
            Some(self.screen.cancel_token()),
            self.microphone.as_ref().map(OutputPipeline::cancel_token),
            self.camera.as_ref().map(OutputPipeline::cancel_token),
            self.system_audio.as_ref().map(OutputPipeline::cancel_token),
        ]
        .into_iter()
        .flatten()
        .collect::<Vec<_>>();
        #[cfg(any(target_os = "linux", windows))]
        let stopping = self.stopping.clone();
        let track_failures = self.track_failures.clone();
        self.watcher_task = Some(tokio::spawn(async move {
            while let Some((track, required, res)) = futures.next().await {
                #[cfg(any(target_os = "linux", windows))]
                let res = match res {
                    Ok(()) if !stopping.load(std::sync::atomic::Ordering::Acquire) => {
                        Err(PipelineDoneError::from_message(format!(
                            "Requested {track:?} track ended before Stop"
                        )))
                    }
                    result => result,
                };
                if let Err(err) = res {
                    let required = required || cfg!(any(target_os = "linux", windows));
                    if required {
                        record_track_failure(
                            &track_failures,
                            track,
                            TrackFailureStage::Runtime,
                            err.to_string(),
                        );
                        #[cfg(any(target_os = "linux", windows))]
                        {
                            stopping.store(true, std::sync::atomic::Ordering::Release);
                            for token in &cancel_tokens {
                                token.cancel();
                            }
                        }
                        completion_tx.send_if_modified(|current| {
                            if current.is_none() {
                                *current = Some(Err(err.clone()));
                                true
                            } else {
                                false
                            }
                        });
                    } else {
                        warn!(?track, error = %err, "Optional recording track failed during runtime");
                        record_track_failure(
                            &track_failures,
                            track,
                            TrackFailureStage::Runtime,
                            err.to_string(),
                        );
                    }
                }
            }
        }));
    }
}

struct CursorPipeline {
    output_path: Option<PathBuf>,
    keyboard_output_path: Option<PathBuf>,
    actor: CursorActor,
}

impl ActorHandle {
    pub async fn stop(&self) -> anyhow::Result<CompletedRecording> {
        self.stop_with_outcome()
            .await
            .result
            .map_err(anyhow::Error::msg)
    }

    pub async fn stop_with_outcome(&self) -> StudioStopOutcome {
        #[cfg(target_os = "linux")]
        {
            let report = self.stop_with_report().await;
            let capture_stopped =
                report.accepted_intent && report.quiescence == StudioQuiescence::Joined;
            let result = if capture_stopped {
                report.result
            } else {
                Err(report.result.err().unwrap_or_else(|| {
                    "Studio capture cleanup is unconfirmed; local recording preserved".into()
                }))
            };
            StudioStopOutcome {
                capture_stopped,
                result,
            }
        }
        #[cfg(any(target_os = "macos", windows))]
        {
            let report = self.stop_with_intent(StudioStopIntent::Preserve).await;
            let capture_stopped = report.accepted_intent && report.stop_acknowledged;
            let result = if capture_stopped {
                report.result
            } else {
                Err(report.result.err().unwrap_or_else(|| {
                    "Studio stop is unconfirmed; terminal acknowledgement missing".into()
                }))
            };
            StudioStopOutcome {
                capture_stopped,
                result,
            }
        }
        #[cfg(not(any(target_os = "linux", target_os = "macos", windows)))]
        {
            let result = self.actor_ref.ask(Stop).await;
            let capture_stopped = match &result {
                Ok(_) => true,
                Err(kameo::error::SendError::HandlerError(error)) => studio_capture_stopped(error),
                Err(_) => false,
            };
            StudioStopOutcome {
                capture_stopped,
                result: result.map_err(|error| format!("{error:#}")),
            }
        }
    }

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

    #[cfg(target_os = "linux")]
    pub async fn stop_with_report(&self) -> StudioStopReport {
        self.stop_with_intent(StudioStopIntent::Preserve).await
    }

    #[cfg(target_os = "linux")]
    pub async fn stop_with_intent(&self, intent: StudioStopIntent) -> StudioStopReport {
        let lifecycle = self.lifecycle.clone();
        let actor = self.actor_ref.clone();
        let recording_dir = self.recording_dir.clone();
        let (sender, receiver) = tokio::sync::oneshot::channel();
        drop(tokio::spawn(async move {
            let mut terminal = lifecycle.0.terminal.lock().await;
            let report = match terminal.as_ref() {
                Some((previous, report)) if *previous == intent => report.clone(),
                Some((_, report)) => StudioStopReport {
                    accepted_intent: false,
                    quiescence: report.quiescence,
                    result: Err(
                        "A different Studio terminal action already owns this attempt".into(),
                    ),
                },
                None => {
                    lifecycle
                        .0
                        .terminal_started
                        .store(true, std::sync::atomic::Ordering::Release);
                    let result = actor
                        .ask(StopWithIntent {
                            discard: intent == StudioStopIntent::Discard,
                        })
                        .await
                        .map_err(|error| format!("{error:#}"));
                    if let Err(error) = &result {
                        lifecycle.fail(error.clone());
                    }
                    let quiescence = lifecycle.join().await;
                    let result = match lifecycle.failure() {
                        Some(error) => {
                            if let Err(persist_error) =
                                persist_failed_recording(&recording_dir, &error)
                            {
                                Err(format!(
                                    "{error}; failed to persist failure metadata: {persist_error:#}"
                                ))
                            } else {
                                Err(error)
                            }
                        }
                        None => result,
                    };
                    let report = StudioStopReport {
                        accepted_intent: true,
                        quiescence,
                        result,
                    };
                    *terminal = Some((intent, report.clone()));
                    report
                }
            };
            let _ = sender.send(report);
        }));
        receiver.await.unwrap_or_else(|_| StudioStopReport {
            accepted_intent: false,
            quiescence: StudioQuiescence::Unconfirmed,
            result: Err("Studio terminal cleanup acknowledgement lost".into()),
        })
    }

    #[cfg(any(target_os = "macos", windows))]
    pub fn same_attempt(&self, other: &Self) -> bool {
        Arc::ptr_eq(&self.terminal, &other.terminal)
    }

    #[cfg(any(target_os = "macos", windows))]
    pub fn terminal_started(&self) -> bool {
        self.terminal
            .started
            .load(std::sync::atomic::Ordering::Acquire)
    }

    #[cfg(any(target_os = "macos", windows))]
    pub fn stop_acknowledged(&self) -> bool {
        self.terminal
            .acknowledged
            .load(std::sync::atomic::Ordering::Acquire)
    }

    #[cfg(any(target_os = "macos", windows))]
    pub async fn stop_with_intent(&self, intent: StudioStopIntent) -> WindowsStudioStopReport {
        let terminal = self.terminal.clone();
        let actor = self.actor_ref.clone();
        let recording_dir = self.recording_dir.clone();
        let (sender, receiver) = tokio::sync::oneshot::channel();
        drop(tokio::spawn(async move {
            let mut cached = terminal.result.lock().await;
            let report = match cached.as_ref() {
                Some((previous, report)) if *previous == intent => report.clone(),
                Some((_, report)) => WindowsStudioStopReport {
                    accepted_intent: false,
                    stop_acknowledged: report.stop_acknowledged,
                    result: Err("Another Studio terminal action owns this attempt".into()),
                },
                None => {
                    terminal
                        .started
                        .store(true, std::sync::atomic::Ordering::Release);
                    let result = actor
                        .ask(StopWithIntent {
                            discard: intent == StudioStopIntent::Discard,
                        })
                        .await;
                    let stop_acknowledged = match &result {
                        Ok(_) => true,
                        Err(kameo::error::SendError::HandlerError(error)) => {
                            studio_capture_stopped(error)
                        }
                        Err(_) => false,
                    };
                    let result = result.map_err(|error| format!("{error:#}"));
                    let result = match result {
                        Err(error) => match persist_failed_recording(&recording_dir, &error) {
                            Ok(()) => Err(error),
                            Err(persist) => Err(format!(
                                "{error}; failed to preserve Failed metadata: {persist:#}"
                            )),
                        },
                        result => result,
                    };
                    let report = WindowsStudioStopReport {
                        accepted_intent: true,
                        stop_acknowledged,
                        result,
                    };
                    terminal.acknowledged.store(
                        report.stop_acknowledged,
                        std::sync::atomic::Ordering::Release,
                    );
                    *cached = Some((intent, report.clone()));
                    report
                }
            };
            let _ = sender.send(report);
        }));
        receiver.await.unwrap_or_else(|_| WindowsStudioStopReport {
            accepted_intent: false,
            stop_acknowledged: false,
            result: Err("Studio terminal acknowledgement lost; local files preserved".into()),
        })
    }

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

    pub async fn pause(&self) -> anyhow::Result<()> {
        #[cfg(any(target_os = "macos", windows))]
        if self.terminal_started() {
            bail!("Studio terminal cleanup already owns this attempt");
        }
        Ok(self.actor_ref.ask(Pause).await?)
    }

    pub async fn resume(&self) -> anyhow::Result<()> {
        #[cfg(any(target_os = "macos", windows))]
        if self.terminal_started() {
            bail!("Studio terminal cleanup already owns this attempt");
        }
        #[cfg(target_os = "linux")]
        {
            self.actor_ref.ask(Resume).await?.await
        }
        #[cfg(not(target_os = "linux"))]
        {
            Ok(self.actor_ref.ask(Resume).await?)
        }
    }

    pub async fn cancel(&self) -> anyhow::Result<()> {
        #[cfg(target_os = "linux")]
        {
            let report = self.stop_with_intent(StudioStopIntent::Discard).await;
            if !report.accepted_intent || report.quiescence != StudioQuiescence::Joined {
                bail!("Studio cancellation cleanup is unconfirmed");
            }
            report.result.map(|_| ()).map_err(anyhow::Error::msg)
        }
        #[cfg(not(target_os = "linux"))]
        {
            Ok(self.actor_ref.ask(Cancel).await?)
        }
    }

    pub async fn set_mic_feed(
        &self,
        mic_feed: Option<Arc<MicrophoneFeedLock>>,
    ) -> anyhow::Result<()> {
        Ok(self.actor_ref.ask(SetMicFeed { mic_feed }).await?)
    }

    pub async fn set_camera_feed(
        &self,
        camera_feed: Option<Arc<CameraFeedLock>>,
    ) -> anyhow::Result<()> {
        Ok(self.actor_ref.ask(SetCameraFeed { camera_feed }).await?)
    }

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

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

pub struct ActorBuilder {
    #[cfg(target_os = "linux")]
    lifetime: StudioLifetimeOwner,
    output_path: PathBuf,
    capture_target: screen_capture::ScreenCaptureTarget,
    window_only: bool,
    system_audio: bool,
    mic_feed: Option<Arc<MicrophoneFeedLock>>,
    camera_feed: Option<Arc<CameraFeedLock>>,
    custom_cursor: bool,
    keyboard_capture: bool,
    fragmented: bool,
    use_oop_muxer: bool,
    max_fps: u32,
    quality: crate::StudioQuality,
    #[cfg(target_os = "macos")]
    excluded_windows: Vec<scap_targets::WindowId>,
    start_gate: Option<RecordingStartGate>,
}

impl ActorBuilder {
    pub fn new(output: PathBuf, capture_target: screen_capture::ScreenCaptureTarget) -> Self {
        Self {
            #[cfg(target_os = "linux")]
            lifetime: StudioLifetimeOwner {
                lifecycle: StudioLifecycle::new(),
                armed: true,
            },
            output_path: output,
            capture_target,
            window_only: false,
            system_audio: false,
            mic_feed: None,
            camera_feed: None,
            custom_cursor: false,
            keyboard_capture: true,
            fragmented: true,
            use_oop_muxer: false,
            max_fps: 60,
            quality: crate::StudioQuality::Balanced,
            #[cfg(target_os = "macos")]
            excluded_windows: Vec::new(),
            start_gate: None,
        }
    }

    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.
    pub fn with_window_only(mut self, window_only: bool) -> Self {
        self.window_only = window_only;
        self
    }

    /// Prime the capture pipeline ahead of the start cue: every source, encoder
    /// and muxer is live once `build` returns, but 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
    }

    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<CameraFeedLock>) -> Self {
        self.camera_feed = Some(camera_feed);
        self
    }

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

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

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

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

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

    pub fn with_quality(mut self, quality: crate::StudioQuality) -> Self {
        self.quality = quality;
        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
    }

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

    pub async fn build(
        self,
        #[cfg(target_os = "macos")] shareable_content: Option<SendableShareableContent>,
    ) -> anyhow::Result<ActorHandle> {
        #[cfg(any(target_os = "linux", windows))]
        let recording_dir = self.output_path.clone();
        #[cfg(target_os = "linux")]
        let lifecycle = self.lifetime.lifecycle.clone();
        #[cfg(target_os = "linux")]
        {
            *lifecycle.0.runtime.lock().unwrap() = Some(tokio::runtime::Handle::current());
        }
        let startup = spawn_studio_recording_actor(
            #[cfg(target_os = "linux")]
            self.lifetime,
            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.custom_cursor,
            self.keyboard_capture,
            self.fragmented,
            self.use_oop_muxer,
            self.max_fps,
            self.quality,
        );
        #[cfg(windows)]
        {
            let scope = crate::output_pipeline::PipelineBuildScope::new();
            let result = crate::output_pipeline::finish_pipeline_startup(&scope, startup).await;
            match result {
                Err(error) if recording_dir.join("recording-meta.json").exists() => {
                    match persist_failed_recording(&recording_dir, &format!("{error:#}")) {
                        Ok(()) => Err(error),
                        Err(persist) => Err(error.context(format!(
                            "Could not preserve failed Studio startup: {persist:#}"
                        ))),
                    }
                }
                result => result,
            }
        }
        #[cfg(target_os = "linux")]
        {
            let result = lifecycle.0.scope.run(startup).await;
            if let Err(error) = &result {
                lifecycle.fail(format!("{error:#}"));
                lifecycle.join().await;
                if recording_dir.join("recording-meta.json").exists()
                    && let Err(persist_error) =
                        persist_failed_recording(&recording_dir, &format!("{error:#}"))
                {
                    warn!(%persist_error, "Failed to persist Studio startup failure");
                }
            }
            result
        }
        #[cfg(not(any(windows, target_os = "linux")))]
        startup.await
    }
}

#[tracing::instrument("studio_recording", skip_all)]
#[allow(clippy::too_many_arguments)]
async fn spawn_studio_recording_actor(
    #[cfg(target_os = "linux")] lifetime: StudioLifetimeOwner,
    recording_dir: PathBuf,
    base_inputs: RecordingBaseInputs,
    custom_cursor_capture: bool,
    keyboard_capture: bool,
    fragmented: bool,
    use_oop_muxer: bool,
    max_fps: u32,
    quality: crate::StudioQuality,
) -> anyhow::Result<ActorHandle> {
    use cap_utils::operation_diagnostics::{Field, Operation};
    let mut diagnostic = Operation::start(
        "studio_recording",
        &[
            Field::identifier(
                "resource",
                cap_utils::operation_diagnostics::resource_id(&recording_dir),
            ),
            Field::number("requested_fps", max_fps as u64),
            Field::flag("system_audio", base_inputs.capture_system_audio),
            Field::flag("microphone", base_inputs.mic_feed.is_some()),
            Field::flag("camera", base_inputs.camera_feed.is_some()),
            Field::flag("fragmented", fragmented),
            Field::flag("out_of_process_muxer", use_oop_muxer),
            Field::flag("custom_cursor", custom_cursor_capture),
        ],
    );
    if let Some(microphone) = &base_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) = &base_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");
    ensure_dir(&recording_dir)?;

    trace!("creating recording actor");

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

    let segments_dir = ensure_dir(&content_dir.join("segments"))?;
    let cursors_dir = ensure_dir(&content_dir.join("cursors"))?;

    let (completion_tx, completion_rx) =
        watch::channel::<Option<Result<(), PipelineDoneError>>>(None);

    if let Some(camera_feed) = &base_inputs.camera_feed {
        debug!("camera device info: {:#?}", camera_feed.camera_info());
        debug!("camera video info: {:#?}", camera_feed.video_info());
    }

    if let Some(mic_feed) = &base_inputs.mic_feed {
        debug!("mic audio info: {:#?}", mic_feed.audio_info());
    };

    #[cfg(target_os = "linux")]
    let lifecycle = lifetime.lifecycle.clone();
    let mut segment_pipeline_factory = SegmentPipelineFactory::new(
        segments_dir,
        cursors_dir,
        base_inputs.clone(),
        custom_cursor_capture,
        keyboard_capture,
        fragmented,
        use_oop_muxer,
        max_fps,
        quality,
        completion_tx.clone(),
    );

    if fragmented || cfg!(any(target_os = "linux", windows)) {
        write_in_progress_meta(&recording_dir)?;
    }

    let index = 0;
    let pipeline = segment_pipeline_factory
        .create_next(Default::default(), 0)
        .await?;

    let done_fut = completion_rx_to_done_fut(completion_rx);

    let segment_start_time = current_time_f64();

    trace!("spawning recording actor");

    let base_inputs = base_inputs.clone();

    #[cfg(any(target_os = "linux", target_os = "macos", windows))]
    let actor_recording_dir = recording_dir.clone();
    diagnostic.stage("recording");
    let actor_ref = Actor::spawn(Actor {
        diagnostic: Some(diagnostic),
        #[cfg(target_os = "linux")]
        lifetime,
        #[cfg(windows)]
        cancel_error: None,
        recording_dir,
        state: Some(ActorState::Recording {
            pipeline,
            /*pipeline_done_rx,*/
            index,
            segment_start_time,
            segment_start_instant: Instant::now(),
        }),
        all_tracks_stopped: true,
        terminal_stop_failure: None,
        segment_factory: segment_pipeline_factory,
        #[cfg(target_os = "linux")]
        resume_attempt: None,
        #[cfg(target_os = "linux")]
        resume_generation: 0,
        #[cfg(target_os = "linux")]
        resume_cleanup_error: None,
        segments: Vec::new(),
        completion_tx: completion_tx.clone(),
        display_notch: crate::capture_pipeline::resolve_display_notch(&base_inputs.capture_target),
    });

    Ok(ActorHandle {
        #[cfg(target_os = "linux")]
        lifecycle,
        #[cfg(any(target_os = "linux", target_os = "macos", windows))]
        recording_dir: actor_recording_dir,
        #[cfg(any(target_os = "macos", windows))]
        terminal: Arc::new(WindowsStudioTerminal::default()),
        actor_ref,
        capture_target: base_inputs.capture_target,
        done_fut,
    })
}

const MAX_PREPARING_SEGMENTS: usize = 1024;
const MAX_PREPARING_CURSOR_IMAGES: usize = 4096;
const MAX_PREPARING_METADATA_STRING_BYTES: usize = 1024 * 1024;

struct BoundedStoppedStudioMeta(RecordingMeta);

impl BoundedStoppedStudioMeta {
    fn new(meta: RecordingMeta) -> Option<Self> {
        let RecordingMetaInner::Studio(studio) = &meta.inner else {
            return None;
        };
        let StudioRecordingMeta::MultipleSegments { inner } = studio.as_ref() else {
            return None;
        };
        if !matches!(inner.status, Some(StudioRecordingStatus::NeedsRemux))
            || inner.segments.is_empty()
            || inner.segments.len() > MAX_PREPARING_SEGMENTS
            || inner.segments.capacity() > MAX_PREPARING_SEGMENTS * 2
            || meta.sharing.is_some()
            || meta.upload.is_some()
        {
            return None;
        }
        let cap_project::Cursors::Correct(cursors) = &inner.cursors else {
            return None;
        };
        if cursors.len() > MAX_PREPARING_CURSOR_IMAGES
            || cursors.capacity() > MAX_PREPARING_CURSOR_IMAGES * 2
        {
            return None;
        }
        let mut remaining = MAX_PREPARING_METADATA_STRING_BYTES;
        let mut account = |bytes: usize| -> Option<()> {
            remaining = remaining.checked_sub(bytes)?;
            Some(())
        };
        account(meta.project_path.capacity())?;
        account(meta.pretty_name.capacity())?;
        for segment in &inner.segments {
            account(segment.display.path.as_str().len())?;
            account(
                segment
                    .display
                    .device_id
                    .as_ref()
                    .map_or(0, String::capacity),
            )?;
            if let Some(camera) = &segment.camera {
                account(camera.path.as_str().len())?;
                account(camera.device_id.as_ref().map_or(0, String::capacity))?;
            }
            for audio in [&segment.mic, &segment.system_audio].into_iter().flatten() {
                account(audio.path.as_str().len())?;
                account(audio.device_id.as_ref().map_or(0, String::capacity))?;
            }
            for path in [&segment.cursor, &segment.keyboard].into_iter().flatten() {
                account(path.as_str().len())?;
            }
        }
        for (id, cursor) in cursors {
            account(id.capacity())?;
            account(cursor.image_path.as_str().len())?;
        }
        Some(Self(meta))
    }
}

#[derive(Clone)]
pub struct CleanStoppedStudio {
    snapshot: Arc<CleanStoppedStudioSnapshot>,
}

struct CleanStoppedStudioSnapshot {
    metadata: RecordingMeta,
    configuration: cap_project::ProjectConfiguration,
    claimed: std::sync::atomic::AtomicBool,
}

pub(crate) struct CleanStoppedStudioClaim {
    snapshot: Arc<CleanStoppedStudioSnapshot>,
}

impl CleanStoppedStudio {
    #[cfg(test)]
    pub(crate) fn for_test(
        metadata: RecordingMeta,
        configuration: cap_project::ProjectConfiguration,
    ) -> Option<Self> {
        Self::new(BoundedStoppedStudioMeta::new(metadata)?, configuration)
    }

    fn new(
        metadata: BoundedStoppedStudioMeta,
        configuration: cap_project::ProjectConfiguration,
    ) -> Option<Self> {
        if configuration.clips.len() > MAX_PREPARING_SEGMENTS
            || configuration.clips.capacity() > MAX_PREPARING_SEGMENTS * 2
        {
            return None;
        }
        if let Some(timeline) = &configuration.timeline {
            if timeline.segments.len() > MAX_PREPARING_SEGMENTS
                || timeline.segments.capacity() > MAX_PREPARING_SEGMENTS * 2
            {
                return None;
            }
            let mut remaining = MAX_PREPARING_METADATA_STRING_BYTES;
            for segment in &timeline.segments {
                remaining =
                    remaining.checked_sub(segment.name.as_ref().map_or(0, String::capacity))?;
            }
        }
        Some(Self {
            snapshot: Arc::new(CleanStoppedStudioSnapshot {
                metadata: metadata.0,
                configuration,
                claimed: std::sync::atomic::AtomicBool::new(false),
            }),
        })
    }

    pub(crate) fn claim(&self, project_path: &Path) -> Option<CleanStoppedStudioClaim> {
        if project_path != self.snapshot.metadata.project_path.as_path() {
            return None;
        }
        self.snapshot
            .claimed
            .compare_exchange(
                false,
                true,
                std::sync::atomic::Ordering::AcqRel,
                std::sync::atomic::Ordering::Acquire,
            )
            .ok()?;
        Some(CleanStoppedStudioClaim {
            snapshot: self.snapshot.clone(),
        })
    }
}

impl CleanStoppedStudioClaim {
    #[cfg(test)]
    pub(crate) fn for_test(
        metadata: RecordingMeta,
        configuration: cap_project::ProjectConfiguration,
    ) -> Option<Self> {
        let receipt = CleanStoppedStudio::for_test(metadata, configuration)?;
        receipt.claim(&receipt.snapshot.metadata.project_path)
    }

    pub(crate) fn metadata(&self) -> &RecordingMeta {
        &self.snapshot.metadata
    }

    pub(crate) fn configuration(&self) -> &cap_project::ProjectConfiguration {
        &self.snapshot.configuration
    }
}

#[derive(Clone)]
pub struct CompletedRecording {
    pub project_path: PathBuf,
    pub meta: StudioRecordingMeta,
    pub cursor_data: cap_project::CursorImages,
    pub clean_stopped: Option<CleanStoppedStudio>,
}

/// Tracks starting within one audio output buffer of each other are treated
/// as simultaneous.
const CROSS_TRACK_SNAP_SECS: f64 =
    cap_timestamp::AUDIO_OUTPUT_FRAMES as f64 / cap_timestamp::DEFAULT_SAMPLE_RATE as f64;

/// Each track's start relative to the segment epoch, as persisted in the
/// recording meta. Also written beside an in-progress segment
/// (`crate::recovery::SEGMENT_START_TIMES_FILE`) so crash recovery aligns the
/// tracks exactly like a normal stop.
#[derive(Clone, Copy, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
pub struct SegmentStartTimes {
    pub display: f64,
    pub camera: Option<f64>,
    pub mic: Option<f64>,
    pub system_audio: Option<f64>,
}

impl SegmentStartTimes {
    pub fn compute(
        epoch: Timestamps,
        display: Timestamp,
        mic: Option<Timestamp>,
        camera: Option<Timestamp>,
        system_audio: Option<Timestamp>,
    ) -> Self {
        let to_start_time = |timestamp: Timestamp| timestamp.signed_duration_since_secs(epoch);
        let mic = mic.map(to_start_time);
        let camera = camera.map(|camera| {
            snap_nearby_start_time(to_start_time(camera), mic, CROSS_TRACK_SNAP_SECS)
        });
        let raw_display = to_start_time(display);
        let display = if camera.is_some() {
            snap_nearby_start_time(raw_display, camera, CROSS_TRACK_SNAP_SECS)
        } else {
            snap_nearby_start_time(raw_display, mic, CROSS_TRACK_SNAP_SECS)
        };
        let system_audio = system_audio.map(|audio| {
            let reference = mic.or(Some(display));
            snap_nearby_start_time(to_start_time(audio), reference, CROSS_TRACK_SNAP_SECS)
        });
        Self {
            display,
            camera,
            mic,
            system_audio,
        }
    }
}

fn snap_nearby_start_time(
    raw_start: f64,
    reference_start: Option<f64>,
    threshold_secs: f64,
) -> f64 {
    match reference_start {
        Some(reference_start) if (raw_start - reference_start).abs() <= threshold_secs => {
            reference_start
        }
        _ => raw_start,
    }
}

async fn stop_recording(
    recording_dir: PathBuf,
    segments: Vec<RecordingSegment>,
    cursors: Cursors,
    fragmented: bool,
    display_notch: Option<cap_project::DisplayNotch>,
    known_failure: Option<String>,
) -> anyhow::Result<CompletedRecording> {
    use cap_project::*;

    const DEFAULT_FPS: u32 = 30;

    let make_relative = |path: &PathBuf| -> RelativePathBuf {
        match path.strip_prefix(&recording_dir) {
            Ok(stripped) => RelativePathBuf::from_path(stripped).unwrap_or_else(|_| {
                tracing::warn!(
                    "Failed to convert path to relative: {:?}, using filename only",
                    path
                );
                RelativePathBuf::from(
                    path.file_name()
                        .unwrap_or_default()
                        .to_string_lossy()
                        .as_ref(),
                )
            }),
            Err(_) => {
                tracing::warn!(
                    "Path {:?} is not inside recording_dir {:?}, using filename only",
                    path,
                    recording_dir
                );
                RelativePathBuf::from(
                    path.file_name()
                        .unwrap_or_default()
                        .to_string_lossy()
                        .as_ref(),
                )
            }
        }
    };

    let segment_outputs: Vec<_> = segments
        .into_iter()
        .enumerate()
        .map(|(segment_index, s)| {
            let start_times = SegmentStartTimes::compute(
                s.pipeline.start_time,
                s.pipeline.screen.first_timestamp,
                s.pipeline
                    .microphone
                    .as_ref()
                    .map(|mic| mic.first_timestamp),
                s.pipeline
                    .camera
                    .as_ref()
                    .map(|camera| camera.first_timestamp),
                s.pipeline
                    .system_audio
                    .as_ref()
                    .map(|audio| audio.first_timestamp),
            );
            let mic_start_time = start_times.mic;
            let camera_start_time = start_times.camera;
            let display_start_time = start_times.display;

            let diagnostics =
                (!s.pipeline.track_failures.is_empty()).then(|| SegmentFailureDiagnostics {
                    segment_index: segment_index as u32,
                    start: s.start,
                    end: s.end,
                    track_failures: s.pipeline.track_failures.clone(),
                });

            let display_fps = s
                .pipeline
                .screen
                .video_info
                .map(|v| v.fps())
                .unwrap_or_else(|| {
                    tracing::warn!(
                        "Screen video_info missing, using default fps: {}",
                        DEFAULT_FPS
                    );
                    DEFAULT_FPS
                });
            // Use the encoded display-media span (first to last muxed timestamp plus one
            // nominal frame), not the wall-clock recording span which includes
            // pipeline-drain latency, and not frame_count / fps, which under-reports VFR
            // content by the length of every capture gap (static screens, dropped frames).
            // This is the timeline the recorder persists to project-config.json, so it is
            // what un-edited recordings use.
            let display_media_duration = match s.pipeline.screen.video_timestamp_span {
                Some((first, last)) if display_fps > 0 => {
                    last.saturating_sub(first).as_secs_f64() + 1.0 / f64::from(display_fps)
                }
                _ if display_fps > 0 => {
                    s.pipeline.screen.video_frame_count as f64 / f64::from(display_fps)
                }
                _ => 0.0,
            };

            // Non-fragmented recordings have their final display file already;
            // verify the muxed container matches the timestamps we sent it.
            // Fragmented recordings get the same check after remux in recovery.
            if s.pipeline
                .screen
                .path
                .extension()
                .is_some_and(|e| e == "mp4")
                && s.pipeline.screen.path.is_file()
                && display_media_duration > 0.0
            {
                crate::output_validation::check_display_sync_span(
                    &s.pipeline.screen.path,
                    Duration::from_secs_f64(display_media_duration),
                );
            }

            SegmentOutput {
                meta: MultipleSegment {
                    display: VideoMeta {
                        path: make_relative(&s.pipeline.screen.path),
                        fps: display_fps,
                        start_time: Some(display_start_time),
                        device_id: None,
                    },
                    camera: s.pipeline.camera.map(|camera| VideoMeta {
                        path: make_relative(&camera.path),
                        fps: camera.video_info.map(|v| v.fps()).unwrap_or_else(|| {
                            tracing::warn!(
                                "Camera video_info missing, using default fps: {}",
                                DEFAULT_FPS
                            );
                            DEFAULT_FPS
                        }),
                        start_time: camera_start_time,
                        device_id: s.camera_device_id.clone(),
                    }),
                    mic: s.pipeline.microphone.map(|mic| AudioMeta {
                        path: make_relative(&mic.path),
                        start_time: mic_start_time,
                        device_id: s.mic_device_id.clone(),
                        gap_summary: to_project_gap_summary(mic.audio_gap_summary),
                        digital_silence_ms: mic.digital_silence_ms,
                    }),
                    system_audio: s.pipeline.system_audio.map(|audio| AudioMeta {
                        path: make_relative(&audio.path),
                        start_time: start_times.system_audio,
                        device_id: None,
                        gap_summary: to_project_gap_summary(audio.audio_gap_summary),
                        digital_silence_ms: None,
                    }),
                    cursor: s
                        .pipeline
                        .cursor
                        .as_ref()
                        .and_then(|cursor| cursor.output_path.as_ref().map(make_relative)),
                    keyboard: s.pipeline.cursor.as_ref().and_then(|cursor| {
                        cursor
                            .keyboard_output_path
                            .as_ref()
                            .filter(|path| path.exists())
                            .map(make_relative)
                    }),
                    display_notch,
                },
                diagnostics,
                duration: display_media_duration,
            }
        })
        .collect();
    let timeline_segments: Vec<_> = segment_outputs
        .iter()
        .enumerate()
        .filter_map(|(i, segment)| {
            (segment.duration > 0.0).then_some(TimelineSegment {
                recording_clip: i as u32,
                start: 0.0,
                end: segment.duration,
                timescale: 1.0,
                name: None,
                speed_audio_mode: None,
                hide_cursor: None,
                volume: None,
            })
        })
        .collect();
    let segment_failure_diagnostics: Vec<_> = segment_outputs
        .iter()
        .filter_map(|segment| segment.diagnostics.clone())
        .collect();
    let segment_metas: Vec<_> = segment_outputs
        .into_iter()
        .map(|segment| segment.meta)
        .collect();
    let clip_configs = segment_metas
        .iter()
        .all(|segment| segment.camera.is_none())
        .then(|| {
            segment_metas
                .iter()
                .enumerate()
                .map(|(i, segment)| ClipConfiguration {
                    index: i as u32,
                    offsets: segment.calculate_audio_offsets(),
                    offsets_auto_calculated: true,
                })
                .collect::<Vec<_>>()
        });

    let needs_remux = if fragmented {
        segment_metas.iter().any(|seg| {
            let display_path = seg.display.path.to_path(&recording_dir);
            display_path.is_dir()
        })
    } else {
        false
    };

    let required_track_failure = known_failure.or_else(|| {
        segment_failure_diagnostics.first().map(|segment| {
            let failure = &segment.track_failures[0];
            format!(
                "Requested {:?} track failed in segment {}: {}",
                failure.track, segment.segment_index, failure.error
            )
        })
    });
    let status = if let Some(error) = required_track_failure.as_ref() {
        Some(StudioRecordingStatus::Failed {
            error: error.clone(),
        })
    } else if needs_remux {
        Some(StudioRecordingStatus::NeedsRemux)
    } else {
        Some(StudioRecordingStatus::Complete)
    };

    let meta = StudioRecordingMeta::MultipleSegments {
        inner: MultipleSegments {
            segments: segment_metas,
            cursors: cap_project::Cursors::Correct(
                cursors
                    .into_values()
                    .map(|cursor| {
                        (
                            cursor.id.to_string(),
                            CursorMeta {
                                image_path: RelativePathBuf::from("content/cursors")
                                    .join(&cursor.file_name),
                                hotspot: cursor.hotspot,
                                shape: cursor.shape,
                            },
                        )
                    })
                    .collect(),
            ),
            status,
        },
    };

    if let Some(diagnostics) = build_recording_failure_diagnostics(&segment_failure_diagnostics)
        && let Err(error) = write_recording_failure_diagnostics(&recording_dir, &diagnostics)
    {
        warn!(
            error = %error,
            path = %recording_dir.join("recording-diagnostics.json").display(),
            "Failed to persist recording diagnostics sidecar"
        );
    }

    let persisted_meta = persist_final_recording_meta(&recording_dir, &meta)?;
    let bounded_meta = if required_track_failure.is_none() {
        BoundedStoppedStudioMeta::new(persisted_meta)
    } else {
        drop(persisted_meta);
        None
    };

    let mut project_config = cap_project::ProjectConfiguration::default();
    if !timeline_segments.is_empty() {
        project_config.timeline = Some(TimelineConfiguration {
            segments: timeline_segments,
            transitions: Vec::new(),
            zoom_segments: Vec::new(),
            scene_segments: Vec::new(),
            style_segments: Vec::new(),
            image_segments: Vec::new(),
            mask_segments: Vec::new(),
            text_segments: Vec::new(),
            caption_segments: Vec::new(),
            keyboard_segments: Vec::new(),
            audio_segments: Vec::new(),
            camera3d_segments: Vec::new(),
        });
    }
    if let Some(clips) = clip_configs {
        project_config.clips = clips;
    }
    project_config
        .write(&recording_dir)
        .map_err(RecordingError::from)?;

    if let Some(error) = required_track_failure {
        bail!(error);
    }

    let clean_stopped = bounded_meta.and_then(|meta| CleanStoppedStudio::new(meta, project_config));

    Ok(CompletedRecording {
        project_path: recording_dir,
        meta,
        cursor_data: Default::default(),
        clean_stopped,
        // display_source: actor.options.capture_target,
        // segments: actor.segments,
    })
}

#[cfg(test)]
type ResumeTestFactory = Arc<
    dyn Fn(Cursors, u32) -> futures::future::BoxFuture<'static, anyhow::Result<Pipeline>>
        + Send
        + Sync,
>;

#[derive(Clone)]
struct SegmentPipelineFactory {
    #[cfg(test)]
    prepare_override: Option<ResumeTestFactory>,
    segments_dir: PathBuf,
    cursors_dir: PathBuf,
    base_inputs: RecordingBaseInputs,
    custom_cursor_capture: bool,
    keyboard_capture: bool,
    fragmented: bool,
    use_oop_muxer: bool,
    max_fps: u32,
    quality: crate::StudioQuality,
    index: u32,
    completion_tx: watch::Sender<Option<Result<(), PipelineDoneError>>>,
    #[cfg(windows)]
    encoder_preferences: crate::capture_pipeline::EncoderPreferences,
}

impl SegmentPipelineFactory {
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        segments_dir: PathBuf,
        cursors_dir: PathBuf,
        base_inputs: RecordingBaseInputs,
        custom_cursor_capture: bool,
        keyboard_capture: bool,
        fragmented: bool,
        use_oop_muxer: bool,
        max_fps: u32,
        quality: crate::StudioQuality,
        completion_tx: watch::Sender<Option<Result<(), PipelineDoneError>>>,
    ) -> Self {
        Self {
            #[cfg(test)]
            prepare_override: None,
            segments_dir,
            cursors_dir,
            base_inputs,
            custom_cursor_capture,
            keyboard_capture,
            fragmented,
            use_oop_muxer,
            max_fps,
            quality,
            index: 0,
            completion_tx,
            #[cfg(windows)]
            encoder_preferences: crate::capture_pipeline::EncoderPreferences::new(),
        }
    }

    #[cfg(target_os = "linux")]
    pub async fn create_next(
        &mut self,
        cursors: Cursors,
        next_cursors_id: u32,
    ) -> anyhow::Result<Pipeline> {
        let mut pipeline = self.prepare_next(cursors, next_cursors_id).await?;
        self.commit_next(&mut pipeline);
        Ok(pipeline)
    }

    #[cfg(target_os = "linux")]
    async fn prepare_next(
        &mut self,
        cursors: Cursors,
        next_cursors_id: u32,
    ) -> anyhow::Result<Pipeline> {
        #[cfg(test)]
        if let Some(prepare) = &self.prepare_override {
            return prepare(cursors, next_cursors_id).await;
        }
        let segment_start_time = Timestamps::now();
        create_segment_pipeline(
            &self.segments_dir,
            &self.cursors_dir,
            self.index,
            self.segment_base_inputs(),
            cursors,
            next_cursors_id,
            self.custom_cursor_capture,
            self.keyboard_capture,
            self.fragmented,
            self.use_oop_muxer,
            self.max_fps,
            self.quality,
            segment_start_time,
            #[cfg(windows)]
            self.encoder_preferences.clone(),
        )
        .await
    }

    #[cfg(target_os = "linux")]
    fn commit_next(&mut self, pipeline: &mut Pipeline) {
        self.index += 1;
        pipeline.spawn_watcher(self.completion_tx.clone());
        pipeline.spawn_start_time_persister();
    }

    #[cfg(not(target_os = "linux"))]
    pub async fn create_next(
        &mut self,
        cursors: Cursors,
        next_cursors_id: u32,
    ) -> anyhow::Result<Pipeline> {
        let startup = async {
            #[cfg(test)]
            if let Some(prepare) = &self.prepare_override {
                return prepare(cursors, next_cursors_id).await;
            }
            create_segment_pipeline(
                &self.segments_dir,
                &self.cursors_dir,
                self.index,
                self.segment_base_inputs(),
                cursors,
                next_cursors_id,
                self.custom_cursor_capture,
                self.keyboard_capture,
                self.fragmented,
                self.use_oop_muxer,
                self.max_fps,
                self.quality,
                Timestamps::now(),
                #[cfg(windows)]
                self.encoder_preferences.clone(),
            )
            .await
        };
        let mut pipeline = if crate::output_pipeline::PipelineBuildScope::current().is_some() {
            startup.await?
        } else {
            #[cfg(target_os = "macos")]
            let scope = crate::output_pipeline::PipelineBuildScope::new_macos_segment();
            #[cfg(not(target_os = "macos"))]
            let scope = crate::output_pipeline::PipelineBuildScope::new();
            crate::output_pipeline::finish_pipeline_startup(&scope, startup).await?
        };

        self.index += 1;

        pipeline.spawn_watcher(self.completion_tx.clone());
        if self.fragmented || cfg!(windows) {
            pipeline.spawn_start_time_persister();
        }

        Ok(pipeline)
    }

    /// Only the first segment is primed behind the start gate; resumed
    /// segments record from their own build instant.
    fn segment_base_inputs(&self) -> RecordingBaseInputs {
        let mut inputs = self.base_inputs.clone();
        if self.index > 0 {
            inputs.start_gate = None;
        }
        inputs
    }

    pub fn start_gate(&self) -> Option<&RecordingStartGate> {
        self.base_inputs.start_gate.as_ref()
    }

    pub fn set_mic_feed(&mut self, mic_feed: Option<Arc<MicrophoneFeedLock>>) {
        self.base_inputs.mic_feed = mic_feed;
    }

    pub fn set_camera_feed(&mut self, camera_feed: Option<Arc<CameraFeedLock>>) {
        self.base_inputs.camera_feed = camera_feed;
    }

    pub fn camera_device_id(&self) -> Option<String> {
        self.base_inputs
            .camera_feed
            .as_ref()
            .map(|f| f.camera_info().device_id().to_string())
    }

    pub fn mic_device_id(&self) -> Option<String> {
        self.base_inputs
            .mic_feed
            .as_ref()
            .map(|f| f.device_name().to_string())
    }
}

fn completion_rx_to_done_fut(
    mut rx: watch::Receiver<Option<Result<(), PipelineDoneError>>>,
) -> DoneFut {
    async move {
        loop {
            if let Some(result) = rx.borrow().clone() {
                return result;
            }

            if rx.changed().await.is_err() {
                #[cfg(target_os = "linux")]
                return Err(PipelineDoneError::from_message(
                    "Studio completion acknowledgement was lost".into(),
                ));
                #[cfg(not(target_os = "linux"))]
                return Ok(());
            }
        }
    }
    .boxed()
    .shared()
}

#[derive(Debug, thiserror::Error)]
pub enum CreateSegmentPipelineError {
    #[error("NoDisplay")]
    NoDisplay,
    #[error("NoBounds")]
    NoBounds,
    #[error("PipelineBuild/{0}")]
    PipelineBuild(MediaError),
    #[error("PipelinePlay/{0}")]
    PipelinePlay(MediaError),
    #[error("Actor/{0}")]
    Actor(#[from] ActorError),
    #[error("{0}")]
    Recording(#[from] RecordingError),
    #[error("{0}")]
    Media(#[from] MediaError),
}

#[tracing::instrument(skip_all, name = "segment", fields(index = index))]
#[allow(clippy::too_many_arguments)]
async fn create_segment_pipeline(
    segments_dir: &Path,
    cursors_dir: &Path,
    index: u32,
    base_inputs: RecordingBaseInputs,
    prev_cursors: Cursors,
    next_cursors_id: u32,
    custom_cursor_capture: bool,
    keyboard_capture: bool,
    fragmented: bool,
    use_oop_muxer: bool,
    max_fps: u32,
    quality: crate::StudioQuality,
    start_time: Timestamps,
    #[cfg(windows)] encoder_preferences: crate::capture_pipeline::EncoderPreferences,
) -> anyhow::Result<Pipeline> {
    #[cfg(windows)]
    let d3d_device = crate::capture_pipeline::create_d3d_device()
        .context("D3D11 device creation failed - this may happen in VMs, RDP sessions, or systems without GPU drivers")?;

    let dir = ensure_dir(&segments_dir.join(format!("segment-{index}")))?;

    let screen_output_path = dir.join("display.mp4");

    trace!("preparing segment pipeline {index}");

    let start_gate = base_inputs.start_gate.clone();
    let pipeline_start_gate = start_gate.clone();

    let camera_active = base_inputs.camera_feed.is_some();
    #[cfg(target_os = "macos")]
    let segment_fragmented = fragmented && !camera_active;
    #[cfg(not(target_os = "macos"))]
    let segment_fragmented = fragmented;

    let shared_pause_state = if segment_fragmented {
        Some(SharedPauseState::new(Arc::new(
            std::sync::atomic::AtomicBool::new(false),
        )))
    } else {
        None
    };

    let camera_only = matches!(
        base_inputs.capture_target,
        screen_capture::ScreenCaptureTarget::CameraOnly
    );
    #[cfg(target_os = "linux")]
    let custom_cursor_capture = custom_cursor_capture && !screen_capture::prefers_wayland_portal();
    #[cfg(target_os = "linux")]
    let mut start_time = start_time;

    let (screen, system_audio, cursor_display) = if camera_only {
        #[cfg(target_os = "linux")]
        {
            let camera_feed = base_inputs.camera_feed.clone().ok_or_else(|| {
                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 builder = if segment_fragmented {
                OutputPipeline::builder(dir.join("display"))
            } else {
                OutputPipeline::builder(screen_output_path.clone())
            }
            .with_video::<sources::Camera>(camera_feed)
            .with_timestamps(start_time)
            .with_start_gate(start_gate.clone());

            let screen = if segment_fragmented {
                builder
                    .build::<crate::ffmpeg::SegmentedVideoMuxer>(
                        crate::ffmpeg::SegmentedVideoMuxerConfig {
                            timed_fragments: true,
                            segment_duration: Duration::from_secs(2),
                            shared_pause_state: shared_pause_state.clone(),
                            ..Default::default()
                        },
                    )
                    .instrument(error_span!("screen-out"))
                    .await
            } else {
                builder
                    .build::<crate::ffmpeg::Mp4Muxer>(())
                    .instrument(error_span!("screen-out"))
                    .await
            }
            .context("camera-only screen pipeline setup")?;

            (screen, None, None)
        }

        #[cfg(any(target_os = "macos", windows))]
        {
            let camera_feed = base_inputs.camera_feed.clone().ok_or_else(|| {
                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."
                )
            })?;

            #[cfg(target_os = "macos")]
            let screen = OutputPipeline::builder(screen_output_path.clone())
                .with_video::<sources::NativeCamera>(camera_feed.clone())
                .with_timestamps(start_time)
                .with_start_gate(start_gate.clone())
                .build::<AVFoundationCameraMuxer>(AVFoundationCameraMuxerConfig::default())
                .instrument(error_span!("screen-out"))
                .await
                .context("camera-only screen pipeline setup")?;

            #[cfg(windows)]
            let screen = OutputPipeline::builder(screen_output_path.clone())
                .with_video::<sources::NativeCamera>(camera_feed.clone())
                .with_timestamps(start_time)
                .with_start_gate(start_gate.clone())
                .build::<WindowsCameraMuxer>(WindowsCameraMuxerConfig {
                    encoder_preferences: encoder_preferences.clone(),
                    ..Default::default()
                })
                .instrument(error_span!("screen-out"))
                .await
                .context("camera-only screen pipeline setup")?;

            (screen, None, None)
        }
    } else {
        let capture_target = base_inputs.capture_target.clone();

        #[cfg(windows)]
        let d3d_device = d3d_device;

        let (display, crop) =
            target_to_display_and_crop(&capture_target).context("target_display_crop")?;
        let compatibility_quality = matches!(quality, crate::StudioQuality::Compatibility);
        let max_capture_size = studio_max_capture_size(quality, camera_active);
        let effective_max_fps = if compatibility_quality && camera_active {
            max_fps.min(24)
        } else {
            max_fps
        };

        let screen_config = ScreenCaptureConfig::<ScreenCaptureMethod>::init(
            display,
            crop,
            !custom_cursor_capture,
            effective_max_fps,
            max_capture_size,
            start_time.system_time(),
            base_inputs.capture_system_audio,
            #[cfg(any(target_os = "macos", windows))]
            crate::window_only_target(&capture_target, base_inputs.window_only),
            #[cfg(target_os = "linux")]
            sources::screen_capture::LinuxCaptureSource::from_target(&capture_target),
            #[cfg(windows)]
            d3d_device,
            #[cfg(target_os = "macos")]
            base_inputs
                .shareable_content
                .clone()
                .ok_or_else(|| anyhow!("Missing shareable content"))?,
            #[cfg(target_os = "macos")]
            base_inputs.excluded_windows.clone(),
        )
        .await
        .context("screen capture init")?;

        let screen_info = screen_config.info();
        let output_size = calculate_gpu_compatible_size(
            screen_info.width,
            screen_info.height,
            H264_MAX_DIMENSION,
        );

        let (capture_source, system_audio) = screen_config.to_sources().await?;
        #[cfg(target_os = "linux")]
        {
            start_time = Timestamps::now();
        }

        let screen = ScreenCaptureMethod::make_studio_mode_pipeline(
            capture_source,
            screen_output_path.clone(),
            start_time,
            start_gate.clone(),
            segment_fragmented,
            use_oop_muxer,
            shared_pause_state.clone(),
            output_size,
            quality,
            #[cfg(windows)]
            encoder_preferences.clone(),
        )
        .instrument(error_span!("screen-out"))
        .await
        .context("screen pipeline setup")?;

        (screen, system_audio, Some(display))
    };

    #[cfg(target_os = "macos")]
    let camera = if camera_only {
        None
    } else if let Some(camera_feed) = base_inputs.camera_feed {
        let pipeline = if segment_fragmented {
            let fragments_dir = dir.join("camera");
            OutputPipeline::builder(fragments_dir)
                .with_video::<sources::NativeCamera>(camera_feed)
                .with_timestamps(start_time)
                .with_start_gate(start_gate.clone())
                .build::<MacOSFragmentedM4SCameraMuxer>(MacOSFragmentedM4SCameraMuxerConfig {
                    shared_pause_state: shared_pause_state.clone(),
                    ..Default::default()
                })
                .instrument(error_span!("camera-out"))
                .await
        } else {
            OutputPipeline::builder(dir.join("camera.mp4"))
                .with_video::<sources::NativeCamera>(camera_feed)
                .with_timestamps(start_time)
                .with_start_gate(start_gate.clone())
                .build::<AVFoundationCameraMuxer>(AVFoundationCameraMuxerConfig {
                    compatibility_quality: matches!(quality, crate::StudioQuality::Compatibility),
                    ..Default::default()
                })
                .instrument(error_span!("camera-out"))
                .await
        };
        Some(pipeline.context("camera pipeline setup")?)
    } else {
        None
    };

    #[cfg(windows)]
    let camera = if camera_only {
        None
    } else if let Some(camera_feed) = base_inputs.camera_feed {
        let pipeline = if segment_fragmented {
            let fragments_dir = dir.join("camera");
            OutputPipeline::builder(fragments_dir)
                .with_video::<sources::NativeCamera>(camera_feed)
                .with_timestamps(start_time)
                .with_start_gate(start_gate.clone())
                .build::<WindowsFragmentedM4SCameraMuxer>(WindowsFragmentedM4SCameraMuxerConfig {
                    shared_pause_state: shared_pause_state.clone(),
                    ..Default::default()
                })
                .instrument(error_span!("camera-out"))
                .await
        } else {
            OutputPipeline::builder(dir.join("camera.mp4"))
                .with_video::<sources::NativeCamera>(camera_feed)
                .with_timestamps(start_time)
                .with_start_gate(start_gate.clone())
                .build::<WindowsCameraMuxer>(WindowsCameraMuxerConfig {
                    encoder_preferences: encoder_preferences.clone(),
                    ..Default::default()
                })
                .instrument(error_span!("camera-out"))
                .await
        };
        Some(pipeline.context("camera pipeline setup")?)
    } else {
        None
    };

    #[cfg(target_os = "linux")]
    let camera = if camera_only {
        None
    } else if let Some(camera_feed) = base_inputs.camera_feed {
        let pipeline = if segment_fragmented {
            OutputPipeline::builder(dir.join("camera"))
                .with_video::<sources::Camera>(camera_feed)
                .with_timestamps(start_time)
                .with_start_gate(start_gate.clone())
                .build::<crate::ffmpeg::SegmentedVideoMuxer>(
                    crate::ffmpeg::SegmentedVideoMuxerConfig {
                        timed_fragments: true,
                        segment_duration: Duration::from_secs(2),
                        shared_pause_state: shared_pause_state.clone(),
                        ..Default::default()
                    },
                )
                .instrument(error_span!("camera-out"))
                .await
        } else {
            OutputPipeline::builder(dir.join("camera.mp4"))
                .with_video::<sources::Camera>(camera_feed)
                .with_timestamps(start_time)
                .with_start_gate(start_gate.clone())
                .build::<crate::ffmpeg::Mp4Muxer>(())
                .instrument(error_span!("camera-out"))
                .await
        };
        Some(pipeline.context("camera pipeline setup")?)
    } else {
        None
    };

    let microphone = if let Some(mic_feed) = base_inputs.mic_feed {
        let pipeline = if segment_fragmented {
            let output_path = dir.join("audio-input.m4a");
            OutputPipeline::builder(output_path)
                .with_audio_source::<sources::Microphone>(mic_feed)
                .with_timestamps(start_time)
                .with_start_gate(start_gate.clone())
                .build::<FragmentedAudioMuxer>(FragmentedAudioMuxerConfig {
                    shared_pause_state: shared_pause_state.clone(),
                    write_behind: cfg!(target_os = "macos"),
                })
                .instrument(error_span!("mic-out"))
                .await
        } else {
            OutputPipeline::builder(dir.join("audio-input.ogg"))
                .with_audio_source::<sources::Microphone>(mic_feed)
                .with_timestamps(start_time)
                .with_start_gate(start_gate.clone())
                .build::<OggMuxer>(OggMuxerConfig {
                    write_behind: cfg!(target_os = "macos"),
                })
                .instrument(error_span!("mic-out"))
                .await
        };
        Some(pipeline.context("microphone pipeline setup")?)
    } else {
        None
    };

    let system_audio = if let Some(system_audio_source) = system_audio {
        // System audio is intermittent (WASAPI loopback only delivers while
        // sound plays), so its first packet is not a "source ready" marker:
        // anchor the track at the recording epoch. This keeps a late first
        // sound from becoming the latest start_time and cutting the head off
        // the display/mic/camera tracks at playback.
        let pipeline = if segment_fragmented {
            let output_path = dir.join("system_audio.m4a");
            OutputPipeline::builder(output_path)
                .with_audio_source::<screen_capture::SystemAudioSource>(system_audio_source)
                .with_timestamps(start_time)
                .with_start_gate(start_gate.clone())
                .with_audio_anchor(AudioAnchor::PipelineEpoch)
                .build::<FragmentedAudioMuxer>(FragmentedAudioMuxerConfig {
                    shared_pause_state: shared_pause_state.clone(),
                    write_behind: cfg!(target_os = "macos"),
                })
                .instrument(error_span!("system-audio-out"))
                .await
        } else {
            OutputPipeline::builder(dir.join("system_audio.ogg"))
                .with_audio_source::<screen_capture::SystemAudioSource>(system_audio_source)
                .with_timestamps(start_time)
                .with_start_gate(start_gate.clone())
                .with_audio_anchor(AudioAnchor::PipelineEpoch)
                .build::<OggMuxer>(OggMuxerConfig {
                    write_behind: cfg!(target_os = "macos"),
                })
                .instrument(error_span!("system-audio-out"))
                .await
        };
        Some(pipeline.context("system audio pipeline setup")?)
    } else {
        None
    };

    let cursor = if camera_only {
        None
    } else {
        (custom_cursor_capture || keyboard_capture)
            .then(move || {
                let cursor_crop_bounds = base_inputs
                    .capture_target
                    .cursor_crop()
                    .ok_or(CreateSegmentPipelineError::NoBounds)?;

                let cursor_output_path = dir.join("cursor.json");
                let keyboard_output_path = dir.join(cap_project::KEYBOARD_EVENTS_FILE_NAME);
                let incremental_output = if fragmented && custom_cursor_capture {
                    Some(cursor_output_path.clone())
                } else {
                    None
                };
                let keyboard_incremental_output = if fragmented && keyboard_capture {
                    Some(keyboard_output_path.clone())
                } else {
                    None
                };

                let cursor_display = cursor_display.ok_or(CreateSegmentPipelineError::NoDisplay)?;

                let cursor = spawn_cursor_recorder(
                    crate::cursor::CursorCaptureTarget {
                        crop_bounds: cursor_crop_bounds,
                        display: cursor_display,
                        #[cfg(target_os = "linux")]
                        window: base_inputs.capture_target.window(),
                        #[cfg(not(target_os = "linux"))]
                        window: crate::window_only_target(
                            &base_inputs.capture_target,
                            base_inputs.window_only,
                        ),
                    },
                    cursors_dir.to_path_buf(),
                    prev_cursors,
                    next_cursors_id,
                    start_time,
                    start_gate.clone(),
                    IncrementalCaptureOutputs {
                        cursor: incremental_output,
                        keyboard: keyboard_incremental_output,
                    },
                    keyboard_capture,
                );

                Ok::<_, CreateSegmentPipelineError>(CursorPipeline {
                    output_path: custom_cursor_capture.then_some(cursor_output_path),
                    keyboard_output_path: keyboard_capture.then_some(keyboard_output_path),
                    actor: cursor,
                })
            })
            .transpose()?
    };

    info!("pipeline playing");

    Ok(Pipeline {
        start_time,
        start_gate: pipeline_start_gate,
        screen,
        microphone,
        camera,
        cursor,
        system_audio,
        track_failures: Arc::new(std::sync::Mutex::new(Vec::new())),
        watcher_task: None,
        #[cfg(any(target_os = "linux", windows))]
        stopping: Arc::new(std::sync::atomic::AtomicBool::new(false)),
    })
}

fn ensure_dir(path: &PathBuf) -> Result<PathBuf, MediaError> {
    std::fs::create_dir_all(path)?;
    Ok(path.clone())
}

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

fn persist_failed_recording(recording_dir: &Path, error: &str) -> anyhow::Result<()> {
    let mut meta = RecordingMeta::load_for_project(recording_dir)
        .map_err(|error| anyhow!("load failed Studio recording metadata: {error}"))?;
    let RecordingMetaInner::Studio(studio) = &mut meta.inner else {
        bail!("Failed Studio recording has incompatible metadata");
    };
    let StudioRecordingMeta::MultipleSegments { inner } = studio.as_mut() else {
        bail!("Failed Studio recording has incompatible segment metadata");
    };
    inner.status = Some(StudioRecordingStatus::Failed {
        error: error.to_string(),
    });
    meta.save_for_project()
        .context("persist failed Studio metadata")
}

fn persist_final_recording_meta(
    recording_dir: &Path,
    studio_meta: &StudioRecordingMeta,
) -> anyhow::Result<RecordingMeta> {
    use chrono::Local;

    let pretty_name = Local::now().format("Cap %Y-%m-%d at %H.%M.%S").to_string();
    let recording_meta = RecordingMeta {
        platform: Some(Platform::default()),
        project_path: recording_dir.to_path_buf(),
        pretty_name,
        sharing: None,
        inner: RecordingMetaInner::Studio(Box::new(studio_meta.clone())),
        upload: None,
    };

    recording_meta
        .save_for_project()
        .context("persist final recording metadata")?;
    Ok(recording_meta)
}

async fn changed(
    watch: &mut Option<tokio::sync::watch::Receiver<Option<Timestamp>>>,
) -> Result<(), tokio::sync::watch::error::RecvError> {
    match watch {
        Some(watch) => watch.changed().await,
        None => std::future::pending().await,
    }
}

fn pipeline_epoch(start_time: Timestamps, start_gate: Option<&RecordingStartGate>) -> Timestamps {
    start_gate
        .and_then(RecordingStartGate::armed_at)
        .filter(|armed| armed.instant() > start_time.instant())
        .unwrap_or(start_time)
}

fn write_segment_start_times(segment_dir: &Path, times: &SegmentStartTimes) -> std::io::Result<()> {
    use std::io::Write;
    let path = segment_dir.join(crate::recovery::SEGMENT_START_TIMES_FILE);
    let temp = path.with_extension("json.tmp");
    let mut file = std::fs::File::create(&temp)?;
    file.write_all(&serde_json::to_vec(times).map_err(std::io::Error::other)?)?;
    file.sync_all()?;
    drop(file);
    std::fs::rename(&temp, &path)?;
    if let Ok(dir) = std::fs::File::open(segment_dir)
        && let Err(error) = dir.sync_all()
    {
        warn!(%error, "Directory fsync failed after persisting segment start times");
    }
    Ok(())
}

fn write_in_progress_meta(recording_dir: &Path) -> anyhow::Result<()> {
    use chrono::Local;

    let pretty_name = Local::now().format("Cap %Y-%m-%d at %H.%M.%S").to_string();

    let meta = RecordingMeta {
        platform: Some(Platform::default()),
        project_path: recording_dir.to_path_buf(),
        pretty_name,
        sharing: None,
        inner: RecordingMetaInner::Studio(Box::new(StudioRecordingMeta::MultipleSegments {
            inner: MultipleSegments {
                segments: Vec::new(),
                cursors: cap_project::Cursors::default(),
                status: Some(StudioRecordingStatus::InProgress),
            },
        })),
        upload: None,
    };

    meta.save_for_project()
        .map_err(|e| anyhow!("Failed to save in-progress meta: {:?}", e))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::output_pipeline::{
        AudioMuxer, AudioSource, ChannelAudioSource, ChannelAudioSourceConfig, ChannelVideoSource,
        ChannelVideoSourceConfig, Muxer, SetupCtx, TaskPool, VideoFrame, VideoMuxer,
    };

    fn sidecar_response() -> CursorActorResponse {
        CursorActorResponse {
            cursors: [(
                42,
                crate::cursor::Cursor {
                    file_name: "cursor.png".into(),
                    id: 7,
                    hotspot: cap_project::XY { x: 0.25, y: 0.75 },
                    shape: None,
                },
            )]
            .into(),
            next_cursor_id: 8,
            moves: Vec::new(),
            clicks: Vec::new(),
            keyboard_presses: vec![cap_project::KeyPressEvent {
                key: "a".into(),
                key_code: "KeyA".into(),
                time_ms: 125.0,
                down: true,
            }],
        }
    }

    #[test]
    fn sidecar_cursor_failure_still_saves_keyboard_and_keeps_cursor_registry() {
        let temp = tempfile::tempdir().unwrap();
        let keyboard = temp.path().join("keyboard.bin");
        let response = sidecar_response();
        let expected_keys = response.keyboard_presses.clone();
        let mut failure = None;
        let (cursors, next_id) = persist_segment_input_events(
            response,
            Some(temp.path()),
            Some(&keyboard),
            &mut failure,
        );

        assert!(format!("{:#}", failure.unwrap()).contains("Could not save cursor events"));
        assert_eq!(
            KeyboardEvents::load_from_file(&keyboard).unwrap().presses,
            expected_keys
        );
        assert_eq!(cursors.get(&42).unwrap().id, 7);
        assert_eq!(next_id, 8);
    }

    #[test]
    fn sidecar_keyboard_failure_preserves_cursor_file_and_media_error() {
        let temp = tempfile::tempdir().unwrap();
        let cursor = temp.path().join("cursor.json");
        let mut failure = Some(anyhow!("encoder media failed"));
        persist_segment_input_events(
            sidecar_response(),
            Some(&cursor),
            Some(temp.path()),
            &mut failure,
        );

        let saved: CursorEvents = serde_json::from_slice(&std::fs::read(cursor).unwrap()).unwrap();
        assert!(saved.clicks.is_empty() && saved.moves.is_empty());
        let error = format!("{:#}", failure.unwrap());
        assert!(error.contains("Could not save keyboard events"));
        assert!(error.contains("encoder media failed"));
    }

    #[test]
    fn sidecar_failures_aggregate_without_losing_disk_full_or_stop_acknowledgement() {
        let temp = tempfile::tempdir().unwrap();
        let mut failure = Some(anyhow::Error::from(std::io::Error::from_raw_os_error(
            libc::ENOSPC,
        )));
        persist_segment_input_events(
            sidecar_response(),
            Some(temp.path()),
            Some(temp.path()),
            &mut failure,
        );
        let error = anyhow::Error::new(StudioCaptureStoppedError::new(failure.unwrap()));
        assert!(studio_capture_stopped(&error));
        let message = format!("{error:#}");
        assert!(message.contains("Could not save cursor events"));
        assert!(message.contains("Could not save keyboard events"));
        assert!(error.chain().any(|cause| {
            cause
                .downcast_ref::<std::io::Error>()
                .is_some_and(|error| error.raw_os_error() == Some(libc::ENOSPC))
        }));
    }

    #[test]
    fn sidecar_success_preserves_existing_json_and_keyboard_formats() {
        let temp = tempfile::tempdir().unwrap();
        let cursor = temp.path().join("cursor.json");
        let keyboard = temp.path().join("keyboard.bin");
        let response = sidecar_response();
        let expected_cursor = serde_json::to_string_pretty(&CursorEvents {
            moves: response.moves.clone(),
            clicks: response.clicks.clone(),
        })
        .unwrap();
        let expected_keyboard = temp.path().join("expected.bin");
        KeyboardEvents {
            presses: response.keyboard_presses.clone(),
        }
        .write_to_file(&expected_keyboard)
        .unwrap();
        let mut failure = None;
        persist_segment_input_events(response, Some(&cursor), Some(&keyboard), &mut failure);
        assert!(failure.is_none());
        assert_eq!(std::fs::read_to_string(cursor).unwrap(), expected_cursor);
        assert_eq!(
            std::fs::read(keyboard).unwrap(),
            std::fs::read(expected_keyboard).unwrap()
        );
    }

    #[test]
    fn sidecar_disabled_paths_and_empty_keyboard_do_not_write_or_clear_failures() {
        let temp = tempfile::tempdir().unwrap();
        let mut response = sidecar_response();
        response.keyboard_presses.clear();
        let mut failure = Some(anyhow!("retained media error"));
        persist_segment_input_events(response, None, Some(temp.path()), &mut failure);
        assert_eq!(failure.unwrap().to_string(), "retained media error");
        assert_eq!(std::fs::read_dir(temp.path()).unwrap().count(), 0);
    }

    #[test]
    fn media_failure_requires_every_producer_stop_to_be_confirmed() {
        let error = classify_pipeline_stop_errors(
            &["microphone: stop timed out".into()],
            &["display: subprocess exited".into()],
        )
        .expect_err("one stopped producer cannot acknowledge the whole Studio pipeline");

        assert!(error.to_string().contains("cleanup is unconfirmed"));
    }

    #[test]
    fn media_failure_remains_visible_after_every_producer_stops() {
        let error = classify_pipeline_stop_errors(&[], &["display: subprocess exited".into()])
            .expect("confirmed producer stops should return the media result")
            .expect("unusable media must remain an error");

        assert!(error.to_string().contains("all capture producers stopped"));
    }

    #[test]
    fn discard_skips_the_minimum_segment_deadline() {
        let segment_start = Instant::now();

        assert_eq!(minimum_segment_stop_deadline(true, segment_start), None);
        assert_eq!(
            minimum_segment_stop_deadline(false, segment_start),
            Some(segment_start + Duration::from_secs(1))
        );
    }

    #[cfg(any(target_os = "macos", windows))]
    #[tokio::test]
    async fn stop_diagnostics_retain_segment_counts_when_final_metadata_cannot_be_saved() {
        use cap_utils::operation_diagnostics::{Operation, snapshot};

        for fail_metadata in [false, true] {
            for count in [1, 2] {
                let directory = tempfile::tempdir().unwrap();
                let root = directory.path();
                if fail_metadata {
                    std::fs::create_dir(root.join("recording-meta.json")).unwrap();
                }
                let (completion_tx, _) = watch::channel(None);
                let segment_factory = SegmentPipelineFactory::new(
                    root.join("content/segments"),
                    root.join("content/cursors"),
                    RecordingBaseInputs {
                        capture_target: screen_capture::ScreenCaptureTarget::CameraOnly,
                        window_only: false,
                        capture_system_audio: false,
                        mic_feed: None,
                        camera_feed: None,
                        start_gate: None,
                        #[cfg(target_os = "macos")]
                        shareable_content: None,
                        #[cfg(target_os = "macos")]
                        excluded_windows: Vec::new(),
                    },
                    false,
                    false,
                    false,
                    false,
                    30,
                    crate::StudioQuality::Balanced,
                    completion_tx.clone(),
                );
                let timestamps = Timestamps::now();
                let segments = (0..count)
                    .map(|index| {
                        let path = root.join(format!("display-{index}.mp4"));
                        std::fs::write(&path, b"preserved capture").unwrap();
                        RecordingSegment {
                            start: index as f64,
                            end: index as f64 + 1.0,
                            pipeline: FinishedPipeline {
                                start_time: timestamps,
                                screen: test_finished_output_pipeline_at(
                                    path,
                                    Timestamp::Instant(timestamps.instant()),
                                    Some(test_video_info()),
                                    30,
                                ),
                                microphone: None,
                                camera: None,
                                system_audio: None,
                                cursor: None,
                                track_failures: Vec::new(),
                            },
                            camera_device_id: None,
                            mic_device_id: None,
                        }
                    })
                    .collect();
                let diagnostic = Operation::start("studio_recording", &[]);
                let operation_id = serde_json::to_value(diagnostic.id()).unwrap();
                let actor = Actor::spawn(Actor {
                    diagnostic: Some(diagnostic),
                    recording_dir: root.to_path_buf(),
                    state: Some(ActorState::Paused {
                        next_index: count,
                        cursors: Default::default(),
                        next_cursor_id: 0,
                    }),
                    all_tracks_stopped: true,
                    terminal_stop_failure: None,
                    #[cfg(windows)]
                    cancel_error: None,
                    segment_factory,
                    segments,
                    completion_tx,
                    display_notch: None,
                });
                let result = actor.ask(Stop).await;
                if fail_metadata {
                    assert!(result.is_err());
                } else {
                    assert!(result.is_ok());
                }
                let snapshot = serde_json::to_value(snapshot()).unwrap();
                let record = snapshot["records"]
                    .as_array()
                    .unwrap()
                    .iter()
                    .find(|record| record["operationId"] == operation_id)
                    .unwrap();
                assert_eq!(
                    record["outcome"],
                    if fail_metadata {
                        "returned_error"
                    } else {
                        "returned_ok"
                    }
                );
                let segments = record["fields"]
                    .as_array()
                    .unwrap()
                    .iter()
                    .find(|field| field["name"] == "segments")
                    .unwrap();
                assert_eq!(segments["value"].as_u64(), Some(u64::from(count)));
                for index in 0..count {
                    assert_eq!(
                        std::fs::read(root.join(format!("display-{index}.mp4"))).unwrap(),
                        b"preserved capture"
                    );
                }
            }
        }
    }

    #[cfg(any(target_os = "macos", windows))]
    fn terminal_failure_handle(path: &Path) -> ActorHandle {
        let (completion_tx, completion_rx) = watch::channel(None);
        let target = screen_capture::ScreenCaptureTarget::CameraOnly;
        let segment_factory = SegmentPipelineFactory::new(
            path.join("content/segments"),
            path.join("content/cursors"),
            RecordingBaseInputs {
                capture_target: target.clone(),
                window_only: false,
                capture_system_audio: false,
                mic_feed: None,
                camera_feed: None,
                start_gate: None,
                #[cfg(target_os = "macos")]
                shareable_content: None,
                #[cfg(target_os = "macos")]
                excluded_windows: Vec::new(),
            },
            false,
            false,
            false,
            false,
            30,
            crate::StudioQuality::Balanced,
            completion_tx.clone(),
        );
        let mut actor = Actor {
            diagnostic: None,
            recording_dir: path.to_path_buf(),
            state: None,
            all_tracks_stopped: true,
            terminal_stop_failure: None,
            #[cfg(windows)]
            cancel_error: None,
            segment_factory,
            segments: Vec::new(),
            completion_tx,
            display_notch: None,
        };
        let error = anyhow::Error::new(StudioCaptureStoppedError::new(anyhow!(
            "pause found unusable media"
        )));
        let error = actor.preserve_terminal_stop_failure(error, true);
        assert!(studio_capture_stopped(&error));
        let actor_ref = Actor::spawn(actor);
        ActorHandle {
            recording_dir: path.to_path_buf(),
            terminal: Arc::new(WindowsStudioTerminal::default()),
            actor_ref,
            capture_target: target,
            done_fut: completion_rx_to_done_fut(completion_rx),
        }
    }

    #[cfg(any(target_os = "macos", windows))]
    #[tokio::test]
    async fn pause_media_failure_replays_as_acknowledged_terminal_error() {
        let temp = tempfile::tempdir().unwrap();
        std::fs::create_dir(temp.path().join("content")).unwrap();
        write_in_progress_meta(temp.path()).unwrap();
        std::fs::write(temp.path().join("content/partial.m4s"), b"partial").unwrap();
        let handle = terminal_failure_handle(temp.path());
        assert!(matches!(
            RecordingMeta::load_for_project(temp.path())
                .unwrap()
                .studio_meta()
                .unwrap()
                .status(),
            StudioRecordingStatus::Failed { .. }
        ));

        let report = handle.stop_with_intent(StudioStopIntent::Preserve).await;
        assert!(report.accepted_intent);
        assert!(report.stop_acknowledged);
        let error = report
            .result
            .err()
            .expect("media failure must remain visible");
        assert!(handle.stop_acknowledged());
        assert!(matches!(
            RecordingMeta::load_for_project(temp.path())
                .unwrap()
                .studio_meta()
                .unwrap()
                .status(),
            StudioRecordingStatus::Failed { .. }
        ));
        assert_eq!(
            std::fs::read(temp.path().join("content/partial.m4s")).unwrap(),
            b"partial"
        );

        let replay = handle.stop_with_intent(StudioStopIntent::Preserve).await;
        assert!(replay.accepted_intent);
        assert!(replay.stop_acknowledged);
        assert_eq!(replay.result.err().expect("cached media failure"), error);
    }

    #[cfg(target_os = "macos")]
    fn prior_unconfirmed_optional_stop_handle(path: &Path) -> ActorHandle {
        let (completion_tx, completion_rx) = watch::channel(None);
        let target = screen_capture::ScreenCaptureTarget::CameraOnly;
        let segment_factory = SegmentPipelineFactory::new(
            path.join("content/segments"),
            path.join("content/cursors"),
            RecordingBaseInputs {
                capture_target: target.clone(),
                window_only: false,
                capture_system_audio: false,
                mic_feed: None,
                camera_feed: None,
                start_gate: None,
                shareable_content: None,
                excluded_windows: Vec::new(),
            },
            false,
            false,
            true,
            false,
            30,
            crate::StudioQuality::Balanced,
            completion_tx.clone(),
        );
        let timestamps = Timestamps::now();
        let actor_ref = Actor::spawn(Actor {
            diagnostic: None,
            recording_dir: path.to_path_buf(),
            state: Some(ActorState::Paused {
                next_index: 1,
                cursors: Default::default(),
                next_cursor_id: 0,
            }),
            all_tracks_stopped: false,
            terminal_stop_failure: None,
            segment_factory,
            segments: vec![RecordingSegment {
                start: 0.0,
                end: 1.0,
                pipeline: FinishedPipeline {
                    start_time: timestamps,
                    screen: test_finished_output_pipeline_at(
                        path.join("content/partial.m4s"),
                        Timestamp::Instant(timestamps.instant()),
                        Some(test_video_info()),
                        1,
                    ),
                    microphone: None,
                    camera: None,
                    system_audio: None,
                    cursor: None,
                    track_failures: vec![TrackFailureRecord {
                        track: RecordingTrackKind::Camera,
                        stage: TrackFailureStage::Stop,
                        error: "camera encoder join timed out".into(),
                    }],
                },
                camera_device_id: None,
                mic_device_id: None,
            }],
            completion_tx,
            display_notch: None,
        });
        ActorHandle {
            recording_dir: path.to_path_buf(),
            terminal: Arc::new(WindowsStudioTerminal::default()),
            actor_ref,
            capture_target: target,
            done_fut: completion_rx_to_done_fut(completion_rx),
        }
    }

    #[cfg(target_os = "macos")]
    #[tokio::test]
    async fn prior_optional_join_timeout_cannot_ack_after_final_metadata() {
        let temp = tempfile::tempdir().unwrap();
        std::fs::create_dir(temp.path().join("content")).unwrap();
        write_in_progress_meta(temp.path()).unwrap();
        std::fs::write(temp.path().join("content/partial.m4s"), b"partial").unwrap();
        let handle = prior_unconfirmed_optional_stop_handle(temp.path());

        let report = handle.stop_with_intent(StudioStopIntent::Preserve).await;
        assert!(report.accepted_intent);
        assert!(!report.stop_acknowledged);
        let error = report.result.err().expect("unconfirmed optional stop");
        assert!(error.contains(UNCONFIRMED_CAPTURE_CLEANUP));
        assert!(matches!(
            RecordingMeta::load_for_project(temp.path())
                .unwrap()
                .studio_meta()
                .unwrap()
                .status(),
            StudioRecordingStatus::Failed { .. }
        ));
        assert_eq!(
            std::fs::read(temp.path().join("content/partial.m4s")).unwrap(),
            b"partial"
        );

        let replay = handle.stop_with_intent(StudioStopIntent::Preserve).await;
        assert!(replay.accepted_intent);
        assert!(!replay.stop_acknowledged);
        assert_eq!(replay.result.err().expect("cached unconfirmed stop"), error);
    }

    #[cfg(any(target_os = "macos", windows))]
    mod failed_resume_tests {
        use super::*;

        struct Snapshot;

        impl Message<Snapshot> for Actor {
            type Reply = (u32, u32, usize, u32);

            async fn handle(
                &mut self,
                _: Snapshot,
                _: &mut Context<Self, Self::Reply>,
            ) -> Self::Reply {
                let Some(ActorState::Paused {
                    next_index,
                    next_cursor_id,
                    cursors,
                }) = &self.state
                else {
                    panic!("failed resume must retain paused state");
                };
                assert_eq!(cursors.get(&42).unwrap().id, 7);
                (
                    *next_index,
                    *next_cursor_id,
                    self.segments.len(),
                    self.segment_factory.index,
                )
            }
        }

        fn paused_handle(path: &Path, prepare: ResumeTestFactory) -> ActorHandle {
            write_in_progress_meta(path).unwrap();
            let (completion_tx, completion_rx) = watch::channel(None);
            let target = screen_capture::ScreenCaptureTarget::CameraOnly;
            let mut factory = SegmentPipelineFactory::new(
                path.join("content/segments"),
                path.join("content/cursors"),
                RecordingBaseInputs {
                    capture_target: target.clone(),
                    window_only: false,
                    capture_system_audio: false,
                    mic_feed: None,
                    camera_feed: None,
                    start_gate: None,
                    #[cfg(target_os = "macos")]
                    shareable_content: None,
                    #[cfg(target_os = "macos")]
                    excluded_windows: Vec::new(),
                },
                false,
                false,
                false,
                false,
                30,
                crate::StudioQuality::Balanced,
                completion_tx.clone(),
            );
            factory.prepare_override = Some(prepare);
            factory.index = 2;
            let timestamps = Timestamps::now();
            let segments = (0..2)
                .map(|index| {
                    let file = path.join(format!("saved-{index}.m4s"));
                    std::fs::write(&file, format!("saved segment {index}")).unwrap();
                    RecordingSegment {
                        start: index as f64,
                        end: index as f64 + 1.0,
                        pipeline: FinishedPipeline {
                            start_time: timestamps,
                            screen: test_finished_output_pipeline_at(
                                file,
                                Timestamp::Instant(timestamps.instant()),
                                Some(test_video_info()),
                                30,
                            ),
                            microphone: None,
                            camera: None,
                            system_audio: None,
                            cursor: None,
                            track_failures: Vec::new(),
                        },
                        camera_device_id: None,
                        mic_device_id: None,
                    }
                })
                .collect();
            let response = sidecar_response();
            let actor_ref = Actor::spawn(Actor {
                diagnostic: None,
                recording_dir: path.to_path_buf(),
                state: Some(ActorState::Paused {
                    next_index: 2,
                    cursors: response.cursors,
                    next_cursor_id: response.next_cursor_id,
                }),
                all_tracks_stopped: true,
                terminal_stop_failure: None,
                #[cfg(windows)]
                cancel_error: None,
                segment_factory: factory,
                segments,
                completion_tx,
                display_notch: None,
            });
            ActorHandle {
                recording_dir: path.to_path_buf(),
                terminal: Arc::new(WindowsStudioTerminal::default()),
                actor_ref,
                capture_target: target,
                done_fut: completion_rx_to_done_fut(completion_rx),
            }
        }

        #[tokio::test]
        async fn repeated_resume_failures_preserve_segments_and_allow_stop() {
            for failure in [
                "Insufficient disk space to start recording: 193MB available, 500MB required",
                "camera pipeline setup failed",
                "microphone pipeline setup failed",
                "screen capture init failed",
            ] {
                let temp = tempfile::tempdir().unwrap();
                let handle = paused_handle(
                    temp.path(),
                    Arc::new(move |cursors, next_id| {
                        assert_eq!(cursors.get(&42).unwrap().id, 7);
                        assert_eq!(next_id, 8);
                        async move { Err(anyhow!(failure)) }.boxed()
                    }),
                );
                for _ in 0..3 {
                    let error = handle.resume().await.unwrap_err();
                    assert!(error.to_string().contains(failure));
                    assert!(handle.is_paused().await.unwrap());
                    assert_eq!(handle.actor_ref.ask(Snapshot).await.unwrap(), (2, 8, 2, 2));
                }
                let report = handle.stop_with_intent(StudioStopIntent::Preserve).await;
                assert!(report.accepted_intent && report.stop_acknowledged);
                let completed = report.result.unwrap();
                let StudioRecordingMeta::MultipleSegments { inner } = completed.meta else {
                    panic!("expected saved segments");
                };
                assert_eq!(inner.segments.len(), 2);
                assert!(handle.done_fut().await.is_ok());
                assert!(
                    handle
                        .resume()
                        .await
                        .unwrap_err()
                        .to_string()
                        .contains("terminal cleanup")
                );
                let replay = handle.stop_with_intent(StudioStopIntent::Preserve).await;
                assert!(replay.stop_acknowledged && replay.result.is_ok());
                for index in 0..2 {
                    assert_eq!(
                        std::fs::read_to_string(temp.path().join(format!("saved-{index}.m4s")))
                            .unwrap(),
                        format!("saved segment {index}")
                    );
                }
                let saved = RecordingMeta::load_for_project(temp.path()).unwrap();
                let StudioRecordingMeta::MultipleSegments { inner } = saved.studio_meta().unwrap()
                else {
                    panic!("expected saved segments");
                };
                assert_eq!(inner.segments.len(), 2);
            }
        }

        #[tokio::test]
        async fn failed_resume_waits_for_owned_cleanup_before_stop() {
            let temp = tempfile::tempdir().unwrap();
            let (release, hold) = tokio::sync::oneshot::channel::<()>();
            let hold = Arc::new(std::sync::Mutex::new(Some(hold)));
            let entered = Arc::new(tokio::sync::Notify::new());
            let ready = entered.clone();
            let handle = paused_handle(
                temp.path(),
                Arc::new(move |_, _| {
                    let hold = hold.lock().unwrap().take().unwrap();
                    let ready = ready.clone();
                    async move {
                        let scope = crate::output_pipeline::PipelineBuildScope::current().unwrap();
                        scope.spawn_cleanup(async move {
                            ready.notify_one();
                            hold.await.unwrap();
                            Ok(())
                        });
                        Err(anyhow!("camera setup failed after screen setup"))
                    }
                    .boxed()
                }),
            );
            let resume_handle = handle.clone();
            let resume = tokio::spawn(async move { resume_handle.resume().await });
            entered.notified().await;
            assert!(!resume.is_finished());
            release.send(()).unwrap();
            assert!(resume.await.unwrap().is_err());
            assert!(handle.is_paused().await.unwrap());
            let report = handle.stop_with_intent(StudioStopIntent::Preserve).await;
            assert!(report.stop_acknowledged && report.result.is_ok());
        }

        #[tokio::test]
        async fn unconfirmed_resume_cleanup_cannot_acknowledge_stop_or_retry() {
            let temp = tempfile::tempdir().unwrap();
            let handle = paused_handle(
                temp.path(),
                Arc::new(|_, _| {
                    async {
                        let scope = crate::output_pipeline::PipelineBuildScope::current().unwrap();
                        scope.spawn_cleanup(async {
                            Err(anyhow!("source stop acknowledgement lost"))
                        });
                        Err(anyhow!("screen setup failed"))
                    }
                    .boxed()
                }),
            );
            assert!(
                handle
                    .resume()
                    .await
                    .unwrap_err()
                    .to_string()
                    .contains("cleanup is unconfirmed")
            );
            assert!(
                handle
                    .resume()
                    .await
                    .unwrap_err()
                    .to_string()
                    .contains(UNCONFIRMED_CAPTURE_CLEANUP)
            );
            let report = handle.stop_with_intent(StudioStopIntent::Preserve).await;
            assert!(!report.stop_acknowledged);
            assert!(report.result.is_err());
            handle.actor_ref.stop_gracefully().await.unwrap();
        }
    }

    #[cfg(target_os = "linux")]
    mod resume_transaction_tests {
        use super::*;
        struct ResumeStateSnapshot;

        impl Message<ResumeStateSnapshot> for Actor {
            type Reply = (bool, u32, u32, usize, usize, u32);

            async fn handle(
                &mut self,
                _: ResumeStateSnapshot,
                _: &mut Context<Self, Self::Reply>,
            ) -> Self::Reply {
                let (paused, index, cursor_id, cursors) = match &self.state {
                    Some(ActorState::Paused {
                        next_index,
                        next_cursor_id,
                        cursors,
                    }) => (true, *next_index, *next_cursor_id, cursors.len()),
                    _ => (false, 0, 0, 0),
                };
                (
                    paused,
                    index,
                    cursor_id,
                    cursors,
                    self.segments.len(),
                    self.segment_factory.index,
                )
            }
        }

        fn paused_resume_actor(path: &Path, prepare: ResumeTestFactory) -> ActorHandle {
            let (completion_tx, completion_rx) = watch::channel(None);
            let target = screen_capture::ScreenCaptureTarget::CameraOnly;
            let mut factory = SegmentPipelineFactory::new(
                path.join("content/segments"),
                path.join("content/cursors"),
                RecordingBaseInputs {
                    capture_target: target.clone(),
                    window_only: false,
                    capture_system_audio: false,
                    mic_feed: None,
                    camera_feed: None,
                    start_gate: None,
                    #[cfg(target_os = "macos")]
                    shareable_content: None,
                    #[cfg(target_os = "macos")]
                    excluded_windows: Vec::new(),
                },
                false,
                false,
                false,
                false,
                30,
                crate::StudioQuality::Balanced,
                completion_tx.clone(),
            );
            factory.index = 1;
            factory.prepare_override = Some(prepare);
            let cursors = [(
                17,
                crate::cursor::Cursor {
                    id: 12,
                    file_name: "retained.png".into(),
                    hotspot: cap_project::XY { x: 0.25, y: 0.75 },
                    shape: None,
                },
            )]
            .into_iter()
            .collect();
            let start_time = Timestamps::now();
            let prior_segment = RecordingSegment {
                start: 0.0,
                end: 1.0,
                camera_device_id: None,
                mic_device_id: None,
                pipeline: FinishedPipeline {
                    start_time,
                    screen: FinishedOutputPipeline {
                        path: path.join("content/segments/segment-0/display.mp4"),
                        first_timestamp: Timestamp::Instant(start_time.instant()),
                        video_info: Some(test_video_info()),
                        video_frame_count: 30,
                        video_timestamp_span: Some((Duration::ZERO, Duration::from_millis(967))),
                        audio_gap_summary: None,
                        digital_silence_ms: None,
                    },
                    microphone: None,
                    camera: None,
                    system_audio: None,
                    cursor: None,
                    track_failures: Vec::new(),
                },
            };
            let lifecycle = StudioLifecycle::new();
            ActorHandle {
                lifecycle: lifecycle.clone(),
                recording_dir: path.to_path_buf(),
                actor_ref: Actor::spawn(Actor {
                    diagnostic: None,
                    lifetime: StudioLifetimeOwner {
                        lifecycle,
                        armed: true,
                    },
                    recording_dir: path.to_path_buf(),
                    state: Some(ActorState::Paused {
                        next_index: 1,
                        cursors,
                        next_cursor_id: 13,
                    }),
                    all_tracks_stopped: true,
                    terminal_stop_failure: None,
                    segment_factory: factory,
                    resume_attempt: None,
                    resume_generation: 0,
                    resume_cleanup_error: None,
                    segments: vec![prior_segment],
                    completion_tx,
                    display_notch: None,
                }),
                capture_target: target,
                done_fut: completion_rx_to_done_fut(completion_rx),
            }
        }

        #[tokio::test]
        async fn dropped_stop_waiter_does_not_abort_owned_studio_shutdown() {
            let directory = tempfile::tempdir().unwrap();
            let handle = paused_resume_actor(
                directory.path(),
                Arc::new(|_, _| async { Err(anyhow!("not resumed")) }.boxed()),
            );
            let scope = handle.lifecycle.0.scope.clone();
            let (release_tx, release_rx) = tokio::sync::oneshot::channel();
            let (entered_tx, entered_rx) = tokio::sync::oneshot::channel();
            scope
                .run(async {
                    let completion = scope.task_completion();
                    drop(tokio::spawn(async move {
                        let _completion = completion;
                        let _ = entered_tx.send(());
                        let _ = release_rx.await;
                    }));
                })
                .await;
            entered_rx.await.unwrap();
            let waiter = tokio::spawn({
                let handle = handle.clone();
                async move { handle.stop_with_report().await }
            });
            tokio::task::yield_now().await;
            waiter.abort();
            assert_eq!(handle.lifecycle.quiescence(), StudioQuiescence::Pending);
            release_tx.send(()).unwrap();
            let report = handle.stop_with_report().await;
            assert_eq!(report.quiescence, StudioQuiescence::Joined);
            assert!(report.result.is_ok());
            let replay = handle.stop_with_report().await;
            assert!(replay.result.is_ok());
        }

        #[tokio::test]
        async fn queued_discard_cannot_replay_a_successful_preserving_stop() {
            let directory = tempfile::tempdir().unwrap();
            let handle = paused_resume_actor(
                directory.path(),
                Arc::new(|_, _| async { Err(anyhow!("not resumed")) }.boxed()),
            );
            let first = handle.stop_with_report().await;
            assert_eq!(first.quiescence, StudioQuiescence::Joined);
            assert!(first.result.is_ok());
            let discarded = handle.stop_with_intent(StudioStopIntent::Discard).await;
            assert_eq!(discarded.quiescence, StudioQuiescence::Joined);
            assert!(discarded.result.is_err());
            assert!(!discarded.accepted_intent);
            assert!(directory.path().join("recording-meta.json").exists());
        }

        #[tokio::test]
        async fn queued_preserve_cannot_take_a_successful_discard_terminal_action() {
            let directory = tempfile::tempdir().unwrap();
            let handle = paused_resume_actor(
                directory.path(),
                Arc::new(|_, _| async { Err(anyhow!("not resumed")) }.boxed()),
            );
            let first = handle.stop_with_intent(StudioStopIntent::Discard).await;
            assert!(first.accepted_intent);
            assert_eq!(first.quiescence, StudioQuiescence::Joined);
            assert!(first.result.is_ok());
            let preserving = handle.stop_with_report().await;
            assert!(!preserving.accepted_intent);
            assert_eq!(preserving.quiescence, StudioQuiescence::Joined);
            assert!(preserving.result.is_err());
        }

        #[derive(kameo::Actor)]
        struct BlockedCompletionMailbox {
            entered: Option<tokio::sync::oneshot::Sender<()>>,
            release: Option<tokio::sync::oneshot::Receiver<()>>,
        }

        impl Message<u8> for BlockedCompletionMailbox {
            type Reply = ();

            async fn handle(&mut self, message: u8, _: &mut Context<Self, Self::Reply>) {
                if message == 0 {
                    self.entered.take().unwrap().send(()).unwrap();
                    self.release.take().unwrap().await.unwrap();
                }
            }
        }

        #[tokio::test]
        async fn full_actor_mailbox_cannot_retain_published_capture_completion() {
            let (entered, entry) = tokio::sync::oneshot::channel();
            let (release, released) = tokio::sync::oneshot::channel();
            let actor = BlockedCompletionMailbox::spawn(BlockedCompletionMailbox {
                entered: Some(entered),
                release: Some(released),
            });
            actor.tell(0u8).await.unwrap();
            entry.await.unwrap();
            for _ in 0..64 {
                actor.tell(1u8).try_send().unwrap();
            }
            let scope = crate::output_pipeline::PipelineBuildScope::new_studio_lifetime();
            let completion = scope.task_completion();
            let notifying = tokio::spawn({
                let actor = actor.clone();
                async move { notify_after_capture_publication(completion, actor.tell(2u8)).await }
            });
            let report =
                tokio::time::timeout(Duration::from_secs(1), scope.cancel_and_join_report())
                    .await
                    .unwrap();
            assert!(report.quiescent);
            assert!(!notifying.is_finished());
            release.send(()).unwrap();
            notifying.await.unwrap().unwrap();
            actor.kill();
            actor.wait_for_stop().await;
        }

        #[tokio::test]
        async fn source_stop_scope_failure_is_failed_before_actor_completion() {
            let directory = tempfile::tempdir().unwrap();
            let handle = paused_resume_actor(
                directory.path(),
                Arc::new(|_, _| async { Err(anyhow!("not resumed")) }.boxed()),
            );
            handle
                .lifecycle
                .0
                .scope
                .fail_required("unresolved backend error at source Stop".into());
            let report = handle.stop_with_report().await;
            assert!(report.accepted_intent);
            assert_eq!(report.quiescence, StudioQuiescence::Joined);
            assert!(report.result.is_err());
            assert!(handle.done_fut().await.is_err());
            let meta = RecordingMeta::load_for_project(directory.path()).unwrap();
            assert!(matches!(
                meta.studio_meta().unwrap().status(),
                StudioRecordingStatus::Failed { .. }
            ));
        }

        #[tokio::test]
        async fn joined_studio_failure_remains_error_for_queued_stop() {
            let directory = tempfile::tempdir().unwrap();
            let handle = paused_resume_actor(
                directory.path(),
                Arc::new(|_, _| async { Err(anyhow!("not resumed")) }.boxed()),
            );
            handle.lifecycle.fail("requested microphone failed".into());
            let (first, second) =
                futures::join!(handle.stop_with_report(), handle.stop_with_report());
            for report in [first, second] {
                assert_eq!(report.quiescence, StudioQuiescence::Joined);
                assert!(
                    report
                        .result
                        .err()
                        .unwrap()
                        .contains("requested microphone failed")
                );
            }
            let meta = RecordingMeta::load_for_project(directory.path()).unwrap();
            assert!(matches!(
                meta.studio_meta().unwrap().status(),
                StudioRecordingStatus::Failed { .. }
            ));
        }

        #[tokio::test]
        async fn resume_failure_waits_for_owned_cleanup_and_preserves_paused_cursor_state() {
            let directory = tempfile::tempdir().unwrap();
            let started = Arc::new(tokio::sync::Notify::new());
            let release = Arc::new(tokio::sync::Notify::new());
            let stopped = Arc::new(std::sync::atomic::AtomicBool::new(false));
            let calls = Arc::new(std::sync::atomic::AtomicUsize::new(0));
            let handle = paused_resume_actor(
                directory.path(),
                Arc::new({
                    let started = started.clone();
                    let release = release.clone();
                    let stopped = stopped.clone();
                    let calls = calls.clone();
                    move |cursors, next_id| {
                        assert_eq!(next_id, 13);
                        assert_eq!(cursors[&17].id, 12);
                        let started = started.clone();
                        let release = release.clone();
                        let stopped = stopped.clone();
                        let calls = calls.clone();
                        async move {
                            if calls.fetch_add(1, std::sync::atomic::Ordering::AcqRel) == 0 {
                                drop(crate::output_pipeline::spawn_capture_task(async move {
                                    started.notify_one();
                                    release.notified().await;
                                    stopped.store(true, std::sync::atomic::Ordering::Release);
                                }));
                            }
                            bail!("late segment setup failure")
                        }
                        .boxed()
                    }
                }),
            );
            let ready = handle.actor_ref.ask(Resume).await.unwrap();
            started.notified().await;
            assert!(!handle.is_paused().await.unwrap());
            tokio::pin!(ready);
            assert!(
                tokio::time::timeout(Duration::from_millis(20), &mut ready)
                    .await
                    .is_err()
            );
            assert!(handle.done_fut().now_or_never().is_none());
            release.notify_one();
            assert!(ready.await.is_err());
            assert!(stopped.load(std::sync::atomic::Ordering::Acquire));
            assert!(handle.is_paused().await.unwrap());
            assert_eq!(
                handle.actor_ref.ask(ResumeStateSnapshot).await.unwrap(),
                (true, 1, 13, 1, 1, 1)
            );
            assert!(handle.resume().await.is_err());
            assert_eq!(calls.load(std::sync::atomic::Ordering::Acquire), 2);
            assert_eq!(
                handle.actor_ref.ask(ResumeStateSnapshot).await.unwrap(),
                (true, 1, 13, 1, 1, 1)
            );
            handle.actor_ref.stop_gracefully().await.unwrap();
        }

        #[tokio::test]
        async fn stop_cancels_pending_resume_and_joins_before_finalizing_only_prior_segments() {
            let directory = tempfile::tempdir().unwrap();
            let started = Arc::new(tokio::sync::Notify::new());
            let cancelled = Arc::new(tokio::sync::Notify::new());
            let release = Arc::new(tokio::sync::Notify::new());
            let failed_dir = directory.path().join("content/segments/segment-1");
            let handle = paused_resume_actor(
                directory.path(),
                Arc::new({
                    let started = started.clone();
                    let cancelled = cancelled.clone();
                    let release = release.clone();
                    let failed_dir = failed_dir.clone();
                    move |_, _| {
                        let started = started.clone();
                        let cancelled = cancelled.clone();
                        let release = release.clone();
                        let failed_dir = failed_dir.clone();
                        async move {
                            tokio::fs::create_dir_all(&failed_dir).await.unwrap();
                            let scope =
                                crate::output_pipeline::PipelineBuildScope::current().unwrap();
                            drop(crate::output_pipeline::spawn_capture_task(async move {
                                scope.cancellation().cancelled().await;
                                cancelled.notify_one();
                                release.notified().await;
                            }));
                            started.notify_one();
                            std::future::pending::<anyhow::Result<Pipeline>>().await
                        }
                        .boxed()
                    }
                }),
            );
            let ready = handle.actor_ref.ask(Resume).await.unwrap();
            started.notified().await;
            let stopping = handle.stop();
            tokio::pin!(stopping);
            tokio::select! {
                _ = cancelled.notified() => {},
                _ = &mut stopping => panic!("Stop acknowledged before setup cleanup"),
                _ = tokio::time::sleep(Duration::from_secs(2)) => panic!("Stop did not reach pending resume"),
            }
            assert!(
                tokio::time::timeout(Duration::from_millis(20), &mut stopping)
                    .await
                    .is_err()
            );
            assert!(handle.done_fut().now_or_never().is_none());
            release.notify_one();
            let completed = tokio::time::timeout(Duration::from_secs(2), stopping)
                .await
                .unwrap()
                .unwrap();
            assert!(ready.await.is_err());
            let StudioRecordingMeta::MultipleSegments { inner } = completed.meta else {
                panic!("wrong metadata")
            };
            assert_eq!(inner.segments.len(), 1);
            assert_eq!(
                inner.segments[0].display.path.as_str(),
                "content/segments/segment-0/display.mp4"
            );
            assert!(!failed_dir.exists());
        }

        #[tokio::test]
        async fn dropped_resume_waiter_cancels_owned_setup_without_late_commit() {
            let directory = tempfile::tempdir().unwrap();
            let started = Arc::new(tokio::sync::Notify::new());
            let finished = Arc::new(tokio::sync::Notify::new());
            let handle = paused_resume_actor(
                directory.path(),
                Arc::new({
                    let started = started.clone();
                    let finished = finished.clone();
                    move |_, _| {
                        let started = started.clone();
                        let finished = finished.clone();
                        async move {
                            let scope =
                                crate::output_pipeline::PipelineBuildScope::current().unwrap();
                            drop(crate::output_pipeline::spawn_capture_task(async move {
                                scope.cancellation().cancelled().await;
                                finished.notify_one();
                            }));
                            started.notify_one();
                            std::future::pending::<anyhow::Result<Pipeline>>().await
                        }
                        .boxed()
                    }
                }),
            );
            let ready = handle.actor_ref.ask(Resume).await.unwrap();
            started.notified().await;
            drop(ready);
            tokio::time::timeout(Duration::from_secs(2), finished.notified())
                .await
                .unwrap();
            tokio::time::timeout(Duration::from_secs(2), async {
                while !handle.is_paused().await.unwrap() {
                    tokio::task::yield_now().await;
                }
            })
            .await
            .unwrap();
            handle.actor_ref.tell(ResumeFinished(0)).await.unwrap();
            assert_eq!(
                handle.actor_ref.ask(ResumeStateSnapshot).await.unwrap(),
                (true, 1, 13, 1, 1, 1)
            );
            assert!(handle.done_fut().now_or_never().is_none());
            handle.actor_ref.stop_gracefully().await.unwrap();
        }

        #[tokio::test]
        async fn unconfirmed_resume_cleanup_never_acknowledges_paused_retry_or_complete() {
            let directory = tempfile::tempdir().unwrap();
            let handle = paused_resume_actor(
                directory.path(),
                Arc::new(|_, _| {
                    async {
                        crate::output_pipeline::PipelineBuildScope::current()
                            .unwrap()
                            .spawn_cleanup(async { bail!("native stop failed") });
                        bail!("setup failed")
                    }
                    .boxed()
                }),
            );
            assert!(handle.resume().await.is_err());
            assert!(!handle.is_paused().await.unwrap());
            assert!(handle.resume().await.is_err());
            assert!(handle.stop().await.is_err());
            assert!(handle.done_fut().now_or_never().is_none());
            assert_eq!(
                handle.actor_ref.ask(ResumeStateSnapshot).await.unwrap(),
                (true, 1, 13, 1, 1, 1)
            );
            handle.actor_ref.stop_gracefully().await.unwrap();
        }

        struct ResumeVideo {
            sender: Option<futures::channel::mpsc::Sender<TestVideoFrame>>,
        }

        impl crate::output_pipeline::VideoSource for ResumeVideo {
            type Config = Arc<std::sync::Mutex<Option<tokio_util::sync::CancellationToken>>>;
            type Frame = TestVideoFrame;

            async fn setup(
                stop: Self::Config,
                sender: futures::channel::mpsc::Sender<Self::Frame>,
                ctx: &mut SetupCtx,
            ) -> anyhow::Result<Self> {
                *stop.lock().unwrap() = Some(ctx.stop_token());
                Ok(Self {
                    sender: Some(sender),
                })
            }

            fn video_info(&self) -> VideoInfo {
                test_video_info()
            }

            fn start(&mut self) -> futures::future::BoxFuture<'_, anyhow::Result<()>> {
                async move {
                    self.sender.as_mut().unwrap().try_send(TestVideoFrame {
                        timestamp: Timestamp::Instant(Instant::now()),
                    })?;
                    Ok(())
                }
                .boxed()
            }

            fn stop(&mut self) -> futures::future::BoxFuture<'_, anyhow::Result<()>> {
                drop(self.sender.take());
                async { Ok(()) }.boxed()
            }
        }

        #[tokio::test]
        async fn successful_resume_commits_once_and_stop_handles_the_committed_race() {
            let directory = tempfile::tempdir().unwrap();
            let stop = Arc::new(std::sync::Mutex::new(None));
            let next_path = directory
                .path()
                .join("content/segments/segment-1/display.mp4");
            let handle = paused_resume_actor(
                directory.path(),
                Arc::new({
                    let stop = stop.clone();
                    move |_, _| {
                        let stop = stop.clone();
                        let next_path = next_path.clone();
                        async move {
                            let start_time = Timestamps::now();
                            let screen = OutputPipeline::builder(next_path)
                                .with_video::<ResumeVideo>(stop)
                                .with_timestamps(start_time)
                                .build::<SuccessfulVideoMuxer>(())
                                .await?;
                            Ok(Pipeline {
                                start_time,
                                start_gate: None,
                                screen,
                                microphone: None,
                                camera: None,
                                system_audio: None,
                                cursor: None,
                                track_failures: Arc::new(std::sync::Mutex::new(Vec::new())),
                                watcher_task: None,
                                #[cfg(target_os = "linux")]
                                stopping: Arc::new(std::sync::atomic::AtomicBool::new(false)),
                            })
                        }
                        .boxed()
                    }
                }),
            );
            handle.resume().await.unwrap();
            assert!(!handle.is_paused().await.unwrap());
            assert!(!stop.lock().unwrap().as_ref().unwrap().is_cancelled());
            handle.resume().await.unwrap();
            assert_eq!(
                handle.actor_ref.ask(ResumeStateSnapshot).await.unwrap().5,
                2
            );
            let completed = tokio::time::timeout(Duration::from_secs(3), handle.stop())
                .await
                .unwrap()
                .unwrap();
            let StudioRecordingMeta::MultipleSegments { inner } = completed.meta else {
                panic!("wrong metadata")
            };
            assert_eq!(inner.segments.len(), 2);
            assert!(stop.lock().unwrap().as_ref().unwrap().is_cancelled());
        }
    }

    struct DelayedStopAudioSource {
        tx: Option<futures::channel::mpsc::Sender<crate::output_pipeline::AudioFrame>>,
        started: Arc<tokio::sync::Notify>,
        release: Arc<tokio::sync::Notify>,
    }

    impl AudioSource for DelayedStopAudioSource {
        type Config = (Arc<tokio::sync::Notify>, Arc<tokio::sync::Notify>);

        fn setup(
            (started, release): Self::Config,
            mut tx: futures::channel::mpsc::Sender<crate::output_pipeline::AudioFrame>,
            _: &mut SetupCtx,
        ) -> impl std::future::Future<Output = anyhow::Result<Self>> + Send + 'static {
            let result = (|| {
                tx.try_send(crate::output_pipeline::AudioFrame::new(
                    test_audio_info().empty_frame(960),
                    Timestamp::Instant(Instant::now()),
                ))?;
                Ok(Self {
                    tx: Some(tx),
                    started,
                    release,
                })
            })();
            futures::future::ready(result)
        }

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

        async fn stop(&mut self) -> anyhow::Result<()> {
            self.started.notify_one();
            self.release.notified().await;
            drop(self.tx.take());
            Ok(())
        }
    }

    #[tokio::test]
    async fn screen_stop_does_not_wait_for_optional_audio_shutdown() {
        let temp_dir = tempfile::tempdir().unwrap();
        let timestamps = Timestamps::now();
        let (screen_tx, screen_rx) = flume::bounded(4);
        let started = Arc::new(tokio::sync::Notify::new());
        let release = Arc::new(tokio::sync::Notify::new());

        let screen = OutputPipeline::builder(temp_dir.path().join("display.mp4"))
            .with_video::<ChannelVideoSource<TestVideoFrame>>(ChannelVideoSourceConfig::new(
                test_video_info(),
                screen_rx,
            ))
            .with_timestamps(timestamps)
            .build::<SuccessfulVideoMuxer>(())
            .await
            .unwrap();
        let screen_stop = screen.cancel_token();
        let microphone = OutputPipeline::builder(temp_dir.path().join("audio-input.ogg"))
            .with_audio_source::<DelayedStopAudioSource>((started.clone(), release.clone()))
            .with_timestamps(timestamps)
            .build::<SuccessfulVideoMuxer>(())
            .await
            .unwrap();
        screen_tx
            .send_async(TestVideoFrame {
                timestamp: Timestamp::Instant(timestamps.instant()),
            })
            .await
            .unwrap();
        let pipeline = Pipeline {
            start_time: timestamps,
            start_gate: None,
            screen,
            microphone: Some(microphone),
            camera: None,
            system_audio: None,
            cursor: None,
            track_failures: Arc::new(std::sync::Mutex::new(Vec::new())),
            watcher_task: None,
            #[cfg(any(target_os = "linux", windows))]
            stopping: Arc::new(std::sync::atomic::AtomicBool::new(false)),
        };

        let stopping = tokio::spawn(pipeline.stop());
        tokio::time::timeout(Duration::from_secs(2), started.notified())
            .await
            .unwrap();
        let screen_stopped_while_audio_waited = screen_stop.is_cancelled();
        release.notify_one();
        drop(screen_tx);
        let finished = stopping.await.unwrap().unwrap();

        assert!(screen_stopped_while_audio_waited);
        assert!(finished.media_error.is_none());
        assert!(finished.pipeline.microphone.is_some());
    }

    #[cfg(target_os = "macos")]
    mod macos_stop_order_tests {
        use super::*;

        struct AudioFinalizer(bool);

        impl Muxer for AudioFinalizer {
            type Config = bool;

            async fn setup(
                fail: bool,
                _: PathBuf,
                _: Option<VideoInfo>,
                _: Option<cap_media_info::AudioInfo>,
                _: Arc<std::sync::atomic::AtomicBool>,
                _: &mut TaskPool,
            ) -> anyhow::Result<Self> {
                Ok(Self(fail))
            }

            fn finish(&mut self, _: Duration) -> anyhow::Result<anyhow::Result<()>> {
                Ok(if self.0 {
                    Err(anyhow!("system audio finalization failed"))
                } else {
                    Ok(())
                })
            }
        }

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

        async fn assert_stop_order(fail_system_audio: bool) -> FinishedPipeline {
            let directory = tempfile::tempdir().unwrap();
            let timestamps = Timestamps::now();
            let (screen_tx, screen_rx) = flume::bounded(4);
            let (camera_tx, camera_rx) = flume::bounded(4);
            let screen = OutputPipeline::builder(directory.path().join("display.mp4"))
                .with_video::<ChannelVideoSource<TestVideoFrame>>(ChannelVideoSourceConfig::new(
                    test_video_info(),
                    screen_rx,
                ))
                .with_timestamps(timestamps)
                .build::<SuccessfulVideoMuxer>(())
                .await
                .unwrap();
            let camera = OutputPipeline::builder(directory.path().join("camera.mp4"))
                .with_video::<ChannelVideoSource<TestVideoFrame>>(ChannelVideoSourceConfig::new(
                    test_video_info(),
                    camera_rx,
                ))
                .with_timestamps(timestamps)
                .build::<SuccessfulVideoMuxer>(())
                .await
                .unwrap();
            let screen_stop = screen.cancel_token();
            let camera_stop = camera.cancel_token();
            for sender in [&screen_tx, &camera_tx] {
                sender
                    .send_async(TestVideoFrame {
                        timestamp: Timestamp::Instant(timestamps.instant()),
                    })
                    .await
                    .unwrap();
            }

            let microphone_started = Arc::new(tokio::sync::Notify::new());
            let microphone_release = Arc::new(tokio::sync::Notify::new());
            let microphone = OutputPipeline::builder(directory.path().join("microphone.ogg"))
                .with_audio_source::<DelayedStopAudioSource>((
                    microphone_started.clone(),
                    microphone_release.clone(),
                ))
                .with_timestamps(timestamps)
                .build::<SuccessfulVideoMuxer>(())
                .await
                .unwrap();
            let system_audio_started = Arc::new(tokio::sync::Notify::new());
            let system_audio_release = Arc::new(tokio::sync::Notify::new());
            let system_audio = OutputPipeline::builder(directory.path().join("system-audio.ogg"))
                .with_audio_source::<DelayedStopAudioSource>((
                    system_audio_started.clone(),
                    system_audio_release.clone(),
                ))
                .with_timestamps(timestamps)
                .build::<AudioFinalizer>(fail_system_audio)
                .await
                .unwrap();
            let pipeline = Pipeline {
                start_time: timestamps,
                start_gate: None,
                screen,
                microphone: Some(microphone),
                camera: Some(camera),
                system_audio: Some(system_audio),
                cursor: None,
                track_failures: Arc::new(std::sync::Mutex::new(Vec::new())),
                watcher_task: None,
            };

            let stopping = tokio::spawn(pipeline.stop());
            tokio::time::timeout(Duration::from_secs(2), async {
                futures::join!(
                    system_audio_started.notified(),
                    microphone_started.notified(),
                    camera_stop.cancelled()
                );
            })
            .await
            .unwrap();
            drop(camera_tx);
            assert!(!screen_stop.is_cancelled());
            assert!(!stopping.is_finished());

            system_audio_release.notify_one();
            tokio::time::timeout(Duration::from_secs(2), screen_stop.cancelled())
                .await
                .unwrap();
            drop(screen_tx);
            assert!(!stopping.is_finished());
            microphone_release.notify_one();
            let stopped = tokio::time::timeout(Duration::from_secs(2), stopping)
                .await
                .unwrap()
                .unwrap()
                .unwrap();
            assert_eq!(stopped.all_tracks_stopped, !fail_system_audio);
            assert!(stopped.media_error.is_none());
            let finished = stopped.pipeline;
            assert!(finished.microphone.is_some());
            assert!(finished.camera.is_some());
            finished
        }

        #[tokio::test]
        async fn system_audio_stop_precedes_screen_without_blocking_other_tracks() {
            let finished = assert_stop_order(false).await;
            assert!(finished.system_audio.is_some());
            assert!(finished.track_failures.is_empty());
        }

        #[tokio::test]
        async fn failed_system_audio_stop_still_stops_screen_and_preserves_failure() {
            let finished = assert_stop_order(true).await;
            assert!(finished.system_audio.is_none());
            assert_eq!(finished.track_failures.len(), 1);
            let failure = &finished.track_failures[0];
            assert_eq!(failure.track, RecordingTrackKind::SystemAudio);
            assert_eq!(failure.stage, TrackFailureStage::Stop);
            assert!(failure.error.contains("system audio finalization failed"));
        }
    }

    fn test_finished_output_pipeline() -> FinishedOutputPipeline {
        let timestamps = Timestamps::now();
        test_finished_output_pipeline_at(
            PathBuf::from("track.mp4"),
            Timestamp::Instant(timestamps.instant()),
            None,
            1,
        )
    }

    fn test_finished_output_pipeline_at(
        path: PathBuf,
        first_timestamp: Timestamp,
        video_info: Option<VideoInfo>,
        video_frame_count: u64,
    ) -> FinishedOutputPipeline {
        FinishedOutputPipeline {
            path,
            first_timestamp,
            video_info,
            video_frame_count,
            video_timestamp_span: None,
            audio_gap_summary: None,
            digital_silence_ms: None,
        }
    }

    #[derive(Clone, Copy)]
    struct TestVideoFrame {
        timestamp: Timestamp,
    }

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

    struct SuccessfulVideoMuxer;

    impl Muxer for SuccessfulVideoMuxer {
        type Config = ();

        async fn setup(
            _config: Self::Config,
            _output_path: PathBuf,
            _video_config: Option<VideoInfo>,
            _audio_config: Option<cap_media_info::AudioInfo>,
            _pause_flag: Arc<std::sync::atomic::AtomicBool>,
            _tasks: &mut TaskPool,
        ) -> anyhow::Result<Self>
        where
            Self: Sized,
        {
            Ok(Self)
        }

        fn finish(&mut self, _timestamp: Duration) -> anyhow::Result<anyhow::Result<()>> {
            Ok(Ok(()))
        }
    }

    impl AudioMuxer for SuccessfulVideoMuxer {
        fn send_audio_frame(
            &mut self,
            _frame: crate::output_pipeline::AudioFrame,
            _timestamp: Duration,
        ) -> anyhow::Result<()> {
            Ok(())
        }
    }

    impl VideoMuxer for SuccessfulVideoMuxer {
        type VideoFrame = TestVideoFrame;

        fn send_video_frame(
            &mut self,
            _frame: Self::VideoFrame,
            _timestamp: Duration,
        ) -> anyhow::Result<()> {
            Ok(())
        }
    }

    #[derive(Clone, Copy)]
    struct FailingAudioMuxerConfig {
        fail_after_frame: u64,
    }

    struct FailingAudioMuxer {
        fail_after_frame: u64,
        sent_frames: u64,
    }

    impl Muxer for FailingAudioMuxer {
        type Config = FailingAudioMuxerConfig;

        async fn setup(
            config: Self::Config,
            _output_path: PathBuf,
            _video_config: Option<VideoInfo>,
            _audio_config: Option<cap_media_info::AudioInfo>,
            _pause_flag: Arc<std::sync::atomic::AtomicBool>,
            _tasks: &mut TaskPool,
        ) -> anyhow::Result<Self>
        where
            Self: Sized,
        {
            Ok(Self {
                fail_after_frame: config.fail_after_frame,
                sent_frames: 0,
            })
        }

        fn finish(&mut self, _timestamp: Duration) -> anyhow::Result<anyhow::Result<()>> {
            Ok(Ok(()))
        }
    }

    impl AudioMuxer for FailingAudioMuxer {
        fn send_audio_frame(
            &mut self,
            _frame: crate::output_pipeline::AudioFrame,
            _timestamp: Duration,
        ) -> anyhow::Result<()> {
            self.sent_frames += 1;
            if self.sent_frames >= self.fail_after_frame {
                return Err(anyhow!("optional audio mux send failed"));
            }
            Ok(())
        }
    }

    #[tokio::test]
    async fn in_progress_segments_persist_the_start_times_a_normal_stop_records() {
        let temp = tempfile::tempdir().unwrap();
        let segment_dir = temp.path().join("content/segments/segment-0");
        std::fs::create_dir_all(&segment_dir).unwrap();
        let timestamps = Timestamps::now();
        let (screen_tx, screen_rx) = flume::bounded(4);
        let screen = OutputPipeline::builder(segment_dir.join("display"))
            .with_video::<ChannelVideoSource<TestVideoFrame>>(ChannelVideoSourceConfig::new(
                test_video_info(),
                screen_rx,
            ))
            .with_timestamps(timestamps)
            .build::<SuccessfulVideoMuxer>(())
            .await
            .unwrap();
        let (mut mic_tx, mic_rx) = futures::channel::mpsc::channel(16);
        let microphone = OutputPipeline::builder(segment_dir.join("audio-input"))
            .with_audio_source::<ChannelAudioSource>(ChannelAudioSourceConfig::new(
                test_audio_info(),
                mic_rx,
            ))
            .with_timestamps(timestamps)
            .build::<SuccessfulVideoMuxer>(())
            .await
            .unwrap();
        let pipeline = Pipeline {
            start_time: timestamps,
            start_gate: None,
            screen,
            microphone: Some(microphone),
            camera: None,
            system_audio: None,
            cursor: None,
            track_failures: Arc::new(std::sync::Mutex::new(Vec::new())),
            watcher_task: None,
            #[cfg(any(target_os = "linux", windows))]
            stopping: Arc::new(std::sync::atomic::AtomicBool::new(false)),
        };
        pipeline.spawn_start_time_persister();
        let persisted = || -> Option<SegmentStartTimes> {
            serde_json::from_slice(
                &std::fs::read(segment_dir.join(crate::recovery::SEGMENT_START_TIMES_FILE)).ok()?,
            )
            .ok()
        };

        let base = timestamps.instant();
        screen_tx
            .send_async(TestVideoFrame {
                timestamp: Timestamp::Instant(base + Duration::from_millis(200)),
            })
            .await
            .unwrap();
        let deadline = Instant::now() + Duration::from_secs(5);
        while persisted().is_none() && Instant::now() < deadline {
            tokio::time::sleep(Duration::from_millis(10)).await;
        }
        let display_only = persisted().expect("display start persisted before the mic starts");
        assert_eq!(display_only.mic, None);

        for k in 0..10u64 {
            mic_tx
                .try_send(crate::output_pipeline::AudioFrame::new(
                    test_audio_info().empty_frame(960),
                    Timestamp::Instant(base + Duration::from_millis(500 + k * 20)),
                ))
                .unwrap();
        }
        let deadline = Instant::now() + Duration::from_secs(5);
        while persisted().is_none_or(|times| times.mic.is_none()) && Instant::now() < deadline {
            tokio::time::sleep(Duration::from_millis(10)).await;
        }
        let during = persisted().expect("start times persisted");

        drop(screen_tx);
        drop(mic_tx);
        let finished = pipeline.stop().await.unwrap().pipeline;
        let at_stop = SegmentStartTimes::compute(
            finished.start_time,
            finished.screen.first_timestamp,
            finished.microphone.as_ref().map(|mic| mic.first_timestamp),
            None,
            None,
        );
        assert_eq!(during, at_stop);
        assert!(during.mic.unwrap() > during.display);
    }

    #[tokio::test]
    async fn a_track_that_ends_before_starting_does_not_stop_start_time_persistence() {
        let temp = tempfile::tempdir().unwrap();
        let segment_dir = temp.path().join("content/segments/segment-0");
        std::fs::create_dir_all(&segment_dir).unwrap();
        let timestamps = Timestamps::now();
        let (screen_tx, screen_rx) = flume::bounded(4);
        let screen = OutputPipeline::builder(segment_dir.join("display"))
            .with_video::<ChannelVideoSource<TestVideoFrame>>(ChannelVideoSourceConfig::new(
                test_video_info(),
                screen_rx,
            ))
            .with_timestamps(timestamps)
            .build::<SuccessfulVideoMuxer>(())
            .await
            .unwrap();
        let (mic_tx, mic_rx) = futures::channel::mpsc::channel(16);
        let microphone = OutputPipeline::builder(segment_dir.join("audio-input"))
            .with_audio_source::<ChannelAudioSource>(ChannelAudioSourceConfig::new(
                test_audio_info(),
                mic_rx,
            ))
            .with_timestamps(timestamps)
            .build::<SuccessfulVideoMuxer>(())
            .await
            .unwrap();
        let microphone_watch = microphone.first_timestamp_watch();
        let pipeline = Pipeline {
            start_time: timestamps,
            start_gate: None,
            screen,
            microphone: None,
            camera: None,
            system_audio: None,
            cursor: None,
            track_failures: Arc::new(std::sync::Mutex::new(Vec::new())),
            watcher_task: None,
            #[cfg(any(target_os = "linux", windows))]
            stopping: Arc::new(std::sync::atomic::AtomicBool::new(false)),
        };
        let pipeline = Pipeline {
            microphone: Some(microphone),
            ..pipeline
        };
        pipeline.spawn_start_time_persister();

        drop(mic_tx);
        let Pipeline {
            microphone, screen, ..
        } = pipeline;
        let _ = microphone.unwrap().stop().await;
        assert!(microphone_watch.borrow().is_none());

        screen_tx
            .send_async(TestVideoFrame {
                timestamp: Timestamp::Instant(timestamps.instant() + Duration::from_millis(200)),
            })
            .await
            .unwrap();
        let path = segment_dir.join(crate::recovery::SEGMENT_START_TIMES_FILE);
        let deadline = Instant::now() + Duration::from_secs(5);
        while !path.exists() && Instant::now() < deadline {
            tokio::time::sleep(Duration::from_millis(10)).await;
        }
        let times: SegmentStartTimes =
            serde_json::from_slice(&std::fs::read(&path).unwrap()).unwrap();
        assert_eq!(times.mic, None);
        drop(screen_tx);
        let _ = screen.stop().await;
    }

    fn test_video_info() -> VideoInfo {
        VideoInfo::from_raw(cap_media_info::RawVideoFormat::Bgra, 16, 16, 30)
    }

    fn test_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,
        )
    }

    #[test]
    fn snap_nearby_start_time_keeps_far_track_start() {
        assert_eq!(snap_nearby_start_time(0.2, Some(0.0), 0.04), 0.2);
    }

    #[test]
    fn snap_nearby_start_time_aligns_near_track_start() {
        assert_eq!(snap_nearby_start_time(0.02, Some(0.0), 0.04), 0.0);
    }

    #[tokio::test]
    async fn stop_recording_preserves_far_display_start_time() {
        let temp_dir = tempfile::tempdir().expect("temp dir should be created");
        let recording_dir = temp_dir.path().join("recording");
        let start_time = Timestamps::now();
        std::fs::create_dir_all(recording_dir.join("content"))
            .expect("recording content dir should be created");

        let segment = RecordingSegment {
            start: 0.0,
            end: 1.0,
            pipeline: FinishedPipeline {
                start_time,
                screen: test_finished_output_pipeline_at(
                    recording_dir.join("content/display.mp4"),
                    Timestamp::Instant(start_time.instant() + Duration::from_millis(200)),
                    Some(test_video_info()),
                    60,
                ),
                microphone: Some(test_finished_output_pipeline_at(
                    recording_dir.join("content/mic.ogg"),
                    Timestamp::Instant(start_time.instant()),
                    None,
                    0,
                )),
                camera: None,
                system_audio: None,
                cursor: None,
                track_failures: Vec::new(),
            },
            camera_device_id: None,
            mic_device_id: Some("mic".to_string()),
        };

        let completed = stop_recording(
            recording_dir.clone(),
            vec![segment],
            Default::default(),
            false,
            None,
            None,
        )
        .await
        .expect("recording should stop");

        let StudioRecordingMeta::MultipleSegments { inner } = completed.meta else {
            panic!("expected multiple segments meta");
        };
        let segment = inner.segments.first().expect("segment should be present");

        assert_eq!(segment.display.start_time, Some(0.2));
        assert_eq!(
            segment.mic.as_ref().and_then(|mic| mic.start_time),
            Some(0.0)
        );
    }

    #[test]
    fn camera_active_capture_size_leaves_non_compatibility_native() {
        for quality in [crate::StudioQuality::Balanced, crate::StudioQuality::Ultra] {
            assert!(camera_active_max_capture_size(quality, true).is_none());
        }
    }

    #[test]
    fn camera_active_capture_size_keeps_guardrail_for_compatibility() {
        assert_eq!(
            camera_active_max_capture_size(crate::StudioQuality::Compatibility, true),
            Some((
                COMPATIBILITY_CAMERA_ACTIVE_MAX_SCREEN_WIDTH,
                COMPATIBILITY_CAMERA_ACTIVE_MAX_SCREEN_HEIGHT,
            ))
        );
    }

    #[test]
    fn inactive_camera_capture_size_is_unbounded() {
        for quality in [
            crate::StudioQuality::Compatibility,
            crate::StudioQuality::Balanced,
            crate::StudioQuality::Ultra,
        ] {
            assert!(camera_active_max_capture_size(quality, false).is_none());
        }
    }

    #[test]
    fn studio_capture_is_bounded_to_the_h264_limit_on_macos() {
        for quality in [
            crate::StudioQuality::Compatibility,
            crate::StudioQuality::Balanced,
            crate::StudioQuality::Ultra,
        ] {
            let expected =
                cfg!(target_os = "macos").then_some((H264_MAX_DIMENSION, H264_MAX_DIMENSION));
            assert_eq!(studio_max_capture_size(quality, false), expected);
        }
        assert_eq!(
            studio_max_capture_size(crate::StudioQuality::Compatibility, true),
            camera_active_max_capture_size(crate::StudioQuality::Compatibility, true),
        );
    }

    #[test]
    fn finalize_optional_track_records_stop_failure() {
        let failures = Arc::new(std::sync::Mutex::new(Vec::new()));
        let output = finalize_optional_track(
            RecordingTrackKind::Camera,
            Err(anyhow!("camera stop failed")),
            &failures,
        );

        assert!(output.is_none());

        let recorded = take_track_failures(&failures);
        assert_eq!(
            recorded,
            vec![TrackFailureRecord {
                track: RecordingTrackKind::Camera,
                stage: TrackFailureStage::Stop,
                error: "camera stop failed".to_string(),
            }]
        );
    }

    #[test]
    fn finalize_optional_track_preserves_successful_track() {
        let failures = Arc::new(std::sync::Mutex::new(Vec::new()));
        let output = finalize_optional_track(
            RecordingTrackKind::Microphone,
            Ok(Some(test_finished_output_pipeline())),
            &failures,
        );

        assert!(output.is_some());
        assert!(take_track_failures(&failures).is_empty());
    }

    #[test]
    fn finalize_optional_track_does_not_duplicate_runtime_failure() {
        let failures = Arc::new(std::sync::Mutex::new(Vec::new()));
        record_track_failure(
            &failures,
            RecordingTrackKind::SystemAudio,
            TrackFailureStage::Runtime,
            "system audio writer failed",
        );

        let output = finalize_optional_track(
            RecordingTrackKind::SystemAudio,
            Err(anyhow!("system audio writer failed")),
            &failures,
        );

        assert!(output.is_none());
        assert_eq!(
            take_track_failures(&failures),
            vec![TrackFailureRecord {
                track: RecordingTrackKind::SystemAudio,
                stage: TrackFailureStage::Runtime,
                error: "system audio writer failed".to_string(),
            }]
        );
    }

    #[test]
    fn build_recording_failure_diagnostics_skips_clean_recordings() {
        assert!(build_recording_failure_diagnostics(&[]).is_none());
    }

    #[test]
    fn build_recording_failure_diagnostics_keeps_segment_failures() {
        let diagnostics = build_recording_failure_diagnostics(&[SegmentFailureDiagnostics {
            segment_index: 2,
            start: 10.0,
            end: 20.0,
            track_failures: vec![
                TrackFailureRecord {
                    track: RecordingTrackKind::Microphone,
                    stage: TrackFailureStage::Runtime,
                    error: "microphone writer failed".to_string(),
                },
                TrackFailureRecord {
                    track: RecordingTrackKind::SystemAudio,
                    stage: TrackFailureStage::Stop,
                    error: "system audio finalize failed".to_string(),
                },
            ],
        }]);

        assert_eq!(
            diagnostics,
            Some(RecordingFailureDiagnostics {
                version: 2,
                segments: vec![SegmentFailureDiagnostics {
                    segment_index: 2,
                    start: 10.0,
                    end: 20.0,
                    track_failures: vec![
                        TrackFailureRecord {
                            track: RecordingTrackKind::Microphone,
                            stage: TrackFailureStage::Runtime,
                            error: "microphone writer failed".to_string(),
                        },
                        TrackFailureRecord {
                            track: RecordingTrackKind::SystemAudio,
                            stage: TrackFailureStage::Stop,
                            error: "system audio finalize failed".to_string(),
                        },
                    ],
                }],
            })
        );
    }

    #[tokio::test]
    async fn failed_requested_track_remains_failed_when_diagnostics_sidecar_write_fails() {
        let temp_dir = tempfile::tempdir().expect("temp dir should be created");
        let recording_dir = temp_dir.path().join("recording");
        let start_time = Timestamps::now();
        std::fs::create_dir_all(recording_dir.join("content"))
            .expect("recording content dir should be created");
        std::fs::create_dir_all(recording_dir.join("recording-diagnostics.json"))
            .expect("diagnostics path should be pre-created as a directory");

        let segment = RecordingSegment {
            start: 0.0,
            end: 1.0,
            pipeline: FinishedPipeline {
                start_time,
                screen: test_finished_output_pipeline_at(
                    recording_dir.join("content/display.mp4"),
                    Timestamp::Instant(start_time.instant() + Duration::from_millis(33)),
                    Some(test_video_info()),
                    1,
                ),
                microphone: None,
                camera: None,
                system_audio: None,
                cursor: None,
                track_failures: vec![TrackFailureRecord {
                    track: RecordingTrackKind::Microphone,
                    stage: TrackFailureStage::Runtime,
                    error: "microphone runtime failure".to_string(),
                }],
            },
            camera_device_id: None,
            mic_device_id: None,
        };

        let result = stop_recording(
            recording_dir.clone(),
            vec![segment],
            Default::default(),
            false,
            None,
            None,
        )
        .await;
        assert!(result.is_err());
        let meta = RecordingMeta::load_for_project(&recording_dir).unwrap();
        assert!(matches!(
            meta.studio_meta().unwrap().status(),
            StudioRecordingStatus::Failed { .. }
        ));

        assert!(
            recording_dir.join("project-config.json").is_file(),
            "project config should still be written"
        );
        assert!(
            recording_dir.join("recording-diagnostics.json").is_dir(),
            "the pre-existing diagnostics directory should remain, proving the sidecar write failed"
        );
    }

    #[tokio::test]
    async fn requested_track_failure_never_finalizes_complete_or_needs_remux() {
        for track in [
            RecordingTrackKind::Microphone,
            RecordingTrackKind::Camera,
            RecordingTrackKind::SystemAudio,
        ] {
            for fragmented in [false, true] {
                let temp_dir = tempfile::tempdir().unwrap();
                let recording_dir = temp_dir.path().join("recording");
                std::fs::create_dir_all(recording_dir.join("content")).unwrap();
                let display_path = recording_dir.join("content/display");
                if fragmented {
                    std::fs::create_dir(&display_path).unwrap();
                    std::fs::write(display_path.join("preserved-fragment"), b"partial").unwrap();
                } else {
                    std::fs::write(&display_path, b"preserved-display").unwrap();
                }
                let timestamps = Timestamps::now();
                let segment = RecordingSegment {
                    start: 0.0,
                    end: 1.0,
                    pipeline: FinishedPipeline {
                        start_time: timestamps,
                        screen: test_finished_output_pipeline_at(
                            display_path.clone(),
                            Timestamp::Instant(timestamps.instant()),
                            Some(test_video_info()),
                            1,
                        ),
                        microphone: None,
                        camera: None,
                        system_audio: None,
                        cursor: None,
                        track_failures: vec![TrackFailureRecord {
                            track,
                            stage: TrackFailureStage::Stop,
                            error: "required output failed".to_string(),
                        }],
                    },
                    camera_device_id: None,
                    mic_device_id: None,
                };
                let result = stop_recording(
                    recording_dir.clone(),
                    vec![segment],
                    Default::default(),
                    fragmented,
                    None,
                    None,
                )
                .await;
                assert!(result.is_err());
                let meta = RecordingMeta::load_for_project(&recording_dir).unwrap();
                assert!(matches!(
                    meta.studio_meta().unwrap().status(),
                    StudioRecordingStatus::Failed { .. }
                ));
                assert!(display_path.exists());
                assert!(recording_dir.join("recording-diagnostics.json").is_file());
            }
        }
    }

    #[cfg(windows)]
    struct HeldEncoderMuxer(Option<std::thread::JoinHandle<anyhow::Result<()>>>);

    #[cfg(windows)]
    impl Muxer for HeldEncoderMuxer {
        type Config = (
            std::sync::mpsc::Receiver<()>,
            tokio::sync::oneshot::Sender<()>,
        );
        async fn setup(
            (release, exited): Self::Config,
            _output_path: PathBuf,
            _video_config: Option<VideoInfo>,
            _audio_config: Option<cap_media_info::AudioInfo>,
            _pause_flag: Arc<std::sync::atomic::AtomicBool>,
            _tasks: &mut TaskPool,
        ) -> anyhow::Result<Self> {
            Ok(Self(Some(std::thread::spawn(move || {
                release.recv().map_err(|error| anyhow!("{error}"))?;
                let _ = exited.send(());
                Ok(())
            }))))
        }
        fn finish(&mut self, _timestamp: Duration) -> anyhow::Result<anyhow::Result<()>> {
            use crate::output_pipeline::{BlockingThreadFinish, wait_for_blocking_thread_finish};
            let handle = self.0.take().unwrap();
            Ok(
                match wait_for_blocking_thread_finish(handle, Duration::ZERO, "held-test-encoder") {
                    BlockingThreadFinish::Clean => Ok(()),
                    BlockingThreadFinish::Failed(error) | BlockingThreadFinish::TimedOut(error) => {
                        Err(error)
                    }
                },
            )
        }
    }

    #[cfg(windows)]
    impl AudioMuxer for HeldEncoderMuxer {
        fn send_audio_frame(
            &mut self,
            _frame: crate::output_pipeline::AudioFrame,
            _timestamp: Duration,
        ) -> anyhow::Result<()> {
            Ok(())
        }
    }

    #[cfg(windows)]
    impl VideoMuxer for HeldEncoderMuxer {
        type VideoFrame = TestVideoFrame;
        fn send_video_frame(
            &mut self,
            _frame: TestVideoFrame,
            _timestamp: Duration,
        ) -> anyhow::Result<()> {
            Ok(())
        }
    }

    #[cfg(windows)]
    #[tokio::test]
    async fn windows_actual_encoder_join_timeout_preserves_failed_without_acknowledgement() {
        let temp = tempfile::tempdir().unwrap();
        std::fs::create_dir(temp.path().join("content")).unwrap();
        write_in_progress_meta(temp.path()).unwrap();
        std::fs::write(temp.path().join("content/partial.m4s"), b"partial").unwrap();
        let (release, held) = std::sync::mpsc::channel();
        let (exited, mut joined) = tokio::sync::oneshot::channel();
        let (frames, receiver) = flume::bounded(4);
        let timestamps = Timestamps::now();
        let screen = OutputPipeline::builder(temp.path().join("content/display.mp4"))
            .with_video::<ChannelVideoSource<TestVideoFrame>>(ChannelVideoSourceConfig::new(
                test_video_info(),
                receiver,
            ))
            .with_timestamps(timestamps)
            .build::<HeldEncoderMuxer>((held, exited))
            .await
            .unwrap();
        let mut actor = super::windows_cancel_tests::cancelled_actor(None);
        actor.recording_dir = temp.path().to_owned();
        actor.state = Some(ActorState::Recording {
            pipeline: Pipeline {
                start_time: timestamps,
                start_gate: None,
                screen,
                microphone: None,
                camera: None,
                system_audio: None,
                cursor: None,
                track_failures: Arc::new(std::sync::Mutex::new(Vec::new())),
                watcher_task: None,
                stopping: Arc::new(std::sync::atomic::AtomicBool::new(false)),
            },
            index: 0,
            segment_start_time: 0.0,
            segment_start_instant: Instant::now().checked_sub(Duration::from_secs(2)).unwrap(),
        });
        let done_fut = completion_rx_to_done_fut(actor.completion_tx.subscribe());
        let actor_ref = Actor::spawn(actor);
        let handle = ActorHandle {
            recording_dir: temp.path().to_owned(),
            terminal: Arc::new(WindowsStudioTerminal::default()),
            actor_ref: actor_ref.clone(),
            capture_target: screen_capture::ScreenCaptureTarget::CameraOnly,
            done_fut,
        };
        let report = handle.stop_with_intent(StudioStopIntent::Preserve).await;
        assert!(!report.stop_acknowledged);
        assert!(report.result.err().unwrap().contains("held-test-encoder"));
        assert!(matches!(
            joined.try_recv(),
            Err(tokio::sync::oneshot::error::TryRecvError::Empty)
        ));
        assert!(matches!(
            RecordingMeta::load_for_project(temp.path())
                .unwrap()
                .studio_meta()
                .unwrap()
                .status(),
            StudioRecordingStatus::Failed { .. }
        ));
        assert_eq!(
            std::fs::read(temp.path().join("content/partial.m4s")).unwrap(),
            b"partial"
        );
        release.send(()).unwrap();
        joined.await.unwrap();
        drop(frames);
        actor_ref.kill();
        actor_ref.wait_for_stop().await;
    }

    #[cfg(windows)]
    async fn failing_requested_actor(
        recording_dir: &Path,
        role: RecordingTrackKind,
    ) -> (Actor, flume::Sender<TestVideoFrame>) {
        std::fs::create_dir_all(recording_dir.join("content")).unwrap();
        write_in_progress_meta(recording_dir).unwrap();
        std::fs::write(
            recording_dir.join("content/partial.m4s"),
            b"retained-real-output",
        )
        .unwrap();
        let timestamps = Timestamps::now();
        let (screen_tx, screen_rx) = flume::bounded(4);
        let (completion_tx, _completion_rx) = watch::channel(None);
        let (mut microphone_tx, microphone_rx) = futures::channel::mpsc::channel(4);
        let screen = OutputPipeline::builder(recording_dir.join("content/display.mp4"))
            .with_video::<ChannelVideoSource<TestVideoFrame>>(ChannelVideoSourceConfig::new(
                test_video_info(),
                screen_rx,
            ))
            .with_timestamps(timestamps)
            .build::<SuccessfulVideoMuxer>(())
            .await
            .unwrap();
        let microphone = OutputPipeline::builder(recording_dir.join("content/audio-input.ogg"))
            .with_audio_source::<ChannelAudioSource>(ChannelAudioSourceConfig::new(
                test_audio_info(),
                microphone_rx,
            ))
            .with_timestamps(timestamps)
            .build::<FailingAudioMuxer>(FailingAudioMuxerConfig {
                fail_after_frame: 1,
            })
            .await
            .unwrap();
        let microphone_done = microphone.done_fut();
        let mut pipeline = Pipeline {
            start_time: timestamps,
            start_gate: None,
            screen,
            microphone: None,
            camera: None,
            system_audio: None,
            cursor: None,
            track_failures: Arc::new(std::sync::Mutex::new(Vec::new())),
            watcher_task: None,
            stopping: Arc::new(std::sync::atomic::AtomicBool::new(false)),
        };
        match role {
            RecordingTrackKind::Microphone => pipeline.microphone = Some(microphone),
            RecordingTrackKind::Camera => pipeline.camera = Some(microphone),
            RecordingTrackKind::SystemAudio => pipeline.system_audio = Some(microphone),
            _ => panic!("requested-role fixture only"),
        }
        pipeline.spawn_watcher(completion_tx.clone());
        screen_tx
            .send_async(TestVideoFrame {
                timestamp: Timestamp::Instant(timestamps.instant()),
            })
            .await
            .unwrap();
        microphone_tx
            .try_send(crate::output_pipeline::AudioFrame::new(
                test_audio_info().empty_frame(960),
                Timestamp::Instant(timestamps.instant()),
            ))
            .unwrap();
        drop(microphone_tx);
        assert!(microphone_done.await.is_err());
        let segment_factory = SegmentPipelineFactory::new(
            recording_dir.join("content/segments"),
            recording_dir.join("content/cursors"),
            RecordingBaseInputs {
                capture_target: screen_capture::ScreenCaptureTarget::CameraOnly,
                window_only: false,
                capture_system_audio: false,
                mic_feed: None,
                camera_feed: None,
                start_gate: None,
            },
            false,
            false,
            true,
            false,
            30,
            crate::StudioQuality::Balanced,
            completion_tx.clone(),
        );
        (
            Actor {
                diagnostic: None,
                recording_dir: recording_dir.to_owned(),
                cancel_error: None,
                state: Some(ActorState::Recording {
                    pipeline,
                    index: 0,
                    segment_start_time: 0.0,
                    segment_start_instant: Instant::now()
                        .checked_sub(Duration::from_secs(2))
                        .unwrap(),
                }),
                all_tracks_stopped: true,
                terminal_stop_failure: None,
                segment_factory,
                segments: Vec::new(),
                completion_tx,
                display_notch: None,
            },
            screen_tx,
        )
    }

    #[cfg(windows)]
    #[tokio::test]
    async fn windows_required_failure_stop_and_cancel_preserve_failed_raw_data() {
        for (cancel, role) in [false, true].into_iter().flat_map(|cancel| {
            [
                RecordingTrackKind::Microphone,
                RecordingTrackKind::Camera,
                RecordingTrackKind::SystemAudio,
            ]
            .into_iter()
            .map(move |role| (cancel, role))
        }) {
            let temp = tempfile::tempdir().unwrap();
            let (actor, screen_tx) = failing_requested_actor(temp.path(), role).await;
            let completion = actor.completion_tx.subscribe();
            let actor = Actor::spawn(actor);
            if cancel {
                assert!(actor.ask(Cancel).await.is_err());
            } else {
                assert!(actor.ask(Stop).await.is_err());
            }
            assert!(completion.borrow().as_ref().is_some_and(Result::is_err));
            assert!(matches!(
                RecordingMeta::load_for_project(temp.path())
                    .unwrap()
                    .studio_meta()
                    .unwrap()
                    .status(),
                StudioRecordingStatus::Failed { .. }
            ));
            assert_eq!(
                std::fs::read(temp.path().join("content/partial.m4s")).unwrap(),
                b"retained-real-output"
            );
            assert!(actor.ask(Cancel).await.is_err());
            drop(screen_tx);
            actor.kill();
            actor.wait_for_stop().await;
        }
    }

    #[cfg(windows)]
    #[tokio::test]
    async fn windows_terminal_failure_is_cached_and_conflicting_intent_is_rejected() {
        for first in [StudioStopIntent::Preserve, StudioStopIntent::Discard] {
            let temp = tempfile::tempdir().unwrap();
            let (actor, screen_tx) =
                failing_requested_actor(temp.path(), RecordingTrackKind::Microphone).await;
            let done_fut = completion_rx_to_done_fut(actor.completion_tx.subscribe());
            let actor_ref = Actor::spawn(actor);
            let handle = ActorHandle {
                recording_dir: temp.path().to_owned(),
                terminal: Arc::new(WindowsStudioTerminal::default()),
                actor_ref: actor_ref.clone(),
                capture_target: screen_capture::ScreenCaptureTarget::CameraOnly,
                done_fut,
            };
            let report = handle.stop_with_intent(first).await;
            assert!(report.accepted_intent);
            assert!(!report.stop_acknowledged);
            assert!(report.result.is_err());
            assert!(handle.terminal_started());
            assert!(!handle.stop_acknowledged());
            assert!(handle.same_attempt(&handle.clone()));
            let repeated = handle.stop_with_intent(first).await;
            assert_eq!(repeated.result.err(), report.result.err());
            let other = match first {
                StudioStopIntent::Preserve => StudioStopIntent::Discard,
                StudioStopIntent::Discard => StudioStopIntent::Preserve,
            };
            let rejected = handle.stop_with_intent(other).await;
            assert!(!rejected.accepted_intent);
            assert!(!rejected.stop_acknowledged);
            assert!(temp.path().join("content/partial.m4s").exists());
            drop(screen_tx);
            actor_ref.kill();
            actor_ref.wait_for_stop().await;
        }
    }

    #[tokio::test]
    async fn stop_preserves_display_when_optional_track_fails_during_runtime() {
        let temp_dir = tempfile::tempdir().expect("temp dir should be created");
        let timestamps = Timestamps::now();
        let (screen_tx, screen_rx) = flume::bounded(4);
        let (completion_tx, completion_rx) = watch::channel(None);
        let (mut microphone_tx, microphone_rx) = futures::channel::mpsc::channel(4);

        let screen = OutputPipeline::builder(temp_dir.path().join("display.mp4"))
            .with_video::<ChannelVideoSource<TestVideoFrame>>(ChannelVideoSourceConfig::new(
                test_video_info(),
                screen_rx,
            ))
            .with_timestamps(timestamps)
            .build::<SuccessfulVideoMuxer>(())
            .await
            .expect("display pipeline should build");

        let microphone = OutputPipeline::builder(temp_dir.path().join("audio-input.ogg"))
            .with_audio_source::<ChannelAudioSource>(ChannelAudioSourceConfig::new(
                test_audio_info(),
                microphone_rx,
            ))
            .with_timestamps(timestamps)
            .build::<FailingAudioMuxer>(FailingAudioMuxerConfig {
                fail_after_frame: 1,
            })
            .await
            .expect("microphone pipeline should build");
        let microphone_done = microphone.done_fut();

        let mut pipeline = Pipeline {
            start_time: timestamps,
            start_gate: None,
            screen,
            microphone: Some(microphone),
            camera: None,
            system_audio: None,
            cursor: None,
            track_failures: Arc::new(std::sync::Mutex::new(Vec::new())),
            watcher_task: None,
            #[cfg(any(target_os = "linux", windows))]
            stopping: Arc::new(std::sync::atomic::AtomicBool::new(false)),
        };
        pipeline.spawn_watcher(completion_tx);

        screen_tx
            .send_async(TestVideoFrame {
                timestamp: Timestamp::Instant(timestamps.instant() + Duration::from_millis(33)),
            })
            .await
            .expect("display frame should send");

        microphone_tx
            .try_send(crate::output_pipeline::AudioFrame::new(
                test_audio_info().empty_frame(960),
                Timestamp::Instant(timestamps.instant() + Duration::from_millis(20)),
            ))
            .expect("microphone frame should send");
        drop(microphone_tx);

        let microphone_error = microphone_done
            .await
            .expect_err("optional microphone pipeline should fail at runtime");
        assert!(
            microphone_error
                .to_string()
                .contains("Audio muxer stopped accepting frames at frame 1"),
            "runtime error should retain the mux send-failure context"
        );

        let stopped = pipeline.stop().await;
        #[cfg(windows)]
        {
            assert!(stopped.is_err());
            assert!(completion_rx.borrow().as_ref().is_some_and(Result::is_err));
            drop(screen_tx);
        }
        #[cfg(not(windows))]
        let finished = stopped
            .expect("display success should still allow the recording to stop cleanly")
            .pipeline;

        #[cfg(not(windows))]
        drop(screen_tx);
        #[cfg(not(windows))]
        {
            assert_eq!(
                finished.screen.video_frame_count, 1,
                "display output should be preserved"
            );
            assert!(
                finished.microphone.is_none(),
                "optional microphone output should be dropped after runtime failure"
            );
            assert_eq!(
                finished.track_failures.len(),
                1,
                "runtime failure should be recorded exactly once"
            );
            #[cfg(target_os = "linux")]
            assert!(completion_rx.borrow().as_ref().is_some_and(Result::is_err));
            #[cfg(not(target_os = "linux"))]
            assert!(completion_rx.borrow().is_none());
            assert_eq!(
                finished.track_failures[0].track,
                RecordingTrackKind::Microphone
            );
            assert_eq!(finished.track_failures[0].stage, TrackFailureStage::Runtime);
            assert!(
                finished.track_failures[0]
                    .error
                    .contains("Audio muxer stopped accepting frames at frame 1"),
                "recorded runtime failure should preserve the mux send-failure context"
            );
        }
    }
}

#[cfg(all(test, windows))]
mod windows_cancel_tests {
    use super::*;

    pub(super) fn cancelled_actor(error: Option<String>) -> Actor {
        let (completion_tx, _completion_rx) = watch::channel(None);
        let segment_factory = SegmentPipelineFactory::new(
            PathBuf::new(),
            PathBuf::new(),
            RecordingBaseInputs {
                capture_target: screen_capture::ScreenCaptureTarget::CameraOnly,
                window_only: false,
                capture_system_audio: false,
                mic_feed: None,
                camera_feed: None,
                start_gate: None,
            },
            false,
            false,
            true,
            false,
            30,
            crate::StudioQuality::Balanced,
            completion_tx.clone(),
        );
        Actor {
            diagnostic: None,
            recording_dir: PathBuf::new(),
            state: None,
            all_tracks_stopped: true,
            terminal_stop_failure: None,
            cancel_error: error,
            segment_factory,
            segments: Vec::new(),
            completion_tx,
            display_notch: None,
        }
    }

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

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

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

    fn metadata(segments: usize, cursors: usize) -> RecordingMeta {
        let segment = MultipleSegment {
            display: cap_project::VideoMeta {
                path: "content/segments/segment-0/display".into(),
                fps: 30,
                start_time: Some(0.0),
                device_id: None,
            },
            camera: None,
            mic: None,
            system_audio: None,
            cursor: None,
            keyboard: None,
            display_notch: None,
        };
        RecordingMeta {
            platform: Some(Platform::default()),
            project_path: PathBuf::from("synthetic.cap"),
            pretty_name: "Synthetic".to_string(),
            sharing: None,
            inner: RecordingMetaInner::Studio(Box::new(StudioRecordingMeta::MultipleSegments {
                inner: MultipleSegments {
                    segments: vec![segment; segments],
                    cursors: cap_project::Cursors::Correct(
                        (0..cursors)
                            .map(|index| {
                                (
                                    index.to_string(),
                                    cap_project::CursorMeta {
                                        image_path: format!("content/cursors/cursor_{index}.png")
                                            .into(),
                                        hotspot: cap_project::XY::new(0.0, 0.0),
                                        shape: None,
                                    },
                                )
                            })
                            .collect(),
                    ),
                    status: Some(StudioRecordingStatus::NeedsRemux),
                },
            })),
            upload: None,
        }
    }

    fn receipt(metadata: RecordingMeta) -> Option<CleanStoppedStudio> {
        CleanStoppedStudio::new(
            BoundedStoppedStudioMeta::new(metadata)?,
            cap_project::ProjectConfiguration::default(),
        )
    }

    #[test]
    fn clean_stop_receipt_is_single_use_across_completion_clones() {
        let metadata = metadata(1, 1);
        let RecordingMetaInner::Studio(studio) = &metadata.inner else {
            unreachable!();
        };
        let completed = CompletedRecording {
            project_path: metadata.project_path.clone(),
            meta: studio.as_ref().clone(),
            cursor_data: Default::default(),
            clean_stopped: receipt(metadata),
        };
        let second = completed.clone();
        let first_receipt = completed.clean_stopped.as_ref().unwrap();
        let second_receipt = second.clean_stopped.as_ref().unwrap();
        assert!(Arc::ptr_eq(
            &first_receipt.snapshot,
            &second_receipt.snapshot
        ));
        assert!(first_receipt.claim(Path::new("different.cap")).is_none());
        let claim = first_receipt.claim(&completed.project_path).unwrap();
        assert_eq!(claim.metadata().project_path, completed.project_path);
        assert!(second_receipt.claim(&second.project_path).is_none());
        assert!(first_receipt.claim(&completed.project_path).is_none());
    }

    #[test]
    fn clean_stop_receipt_has_one_winner_under_concurrent_claims() {
        let receipt = receipt(metadata(1, 0)).unwrap();
        let winners = std::thread::scope(|scope| {
            let workers = (0..8)
                .map(|_| {
                    let receipt = &receipt;
                    scope.spawn(move || receipt.claim(Path::new("synthetic.cap")).is_some())
                })
                .collect::<Vec<_>>();
            workers
                .into_iter()
                .map(|worker| worker.join().unwrap())
                .filter(|winner| *winner)
                .count()
        });
        assert_eq!(winners, 1);
    }

    #[test]
    fn clean_stop_receipt_bounds_are_preview_eligibility_only() {
        assert!(receipt(metadata(MAX_PREPARING_SEGMENTS, 0)).is_some());
        let oversized = metadata(MAX_PREPARING_SEGMENTS + 1, 0);
        let RecordingMetaInner::Studio(studio) = &oversized.inner else {
            unreachable!();
        };
        let completed = CompletedRecording {
            project_path: oversized.project_path.clone(),
            meta: studio.as_ref().clone(),
            cursor_data: Default::default(),
            clean_stopped: receipt(oversized),
        };
        assert!(completed.clean_stopped.is_none());
        let StudioRecordingMeta::MultipleSegments { inner } = completed.meta else {
            unreachable!();
        };
        assert_eq!(inner.segments.len(), MAX_PREPARING_SEGMENTS + 1);
        assert!(receipt(metadata(1, MAX_PREPARING_CURSOR_IMAGES)).is_some());
        assert!(receipt(metadata(1, MAX_PREPARING_CURSOR_IMAGES + 1)).is_none());
    }

    #[test]
    fn clean_stop_receipt_string_budget_accepts_boundary_and_rejects_one_more_byte() {
        for extra in [0, 1] {
            let mut metadata = metadata(1, 0);
            let fixed = metadata.project_path.capacity() + metadata.pretty_name.capacity();
            let RecordingMetaInner::Studio(studio) = &mut metadata.inner else {
                unreachable!();
            };
            let StudioRecordingMeta::MultipleSegments { inner } = studio.as_mut() else {
                unreachable!();
            };
            let fixed = fixed + inner.segments[0].display.path.as_str().len();
            inner.segments[0].display.device_id =
                Some("x".repeat(MAX_PREPARING_METADATA_STRING_BYTES - fixed + extra));
            assert_eq!(receipt(metadata).is_some(), extra == 0);
        }
    }

    #[test]
    fn clean_stop_receipt_rejects_complete_failed_and_empty_recordings() {
        for status in [
            Some(StudioRecordingStatus::Complete),
            Some(StudioRecordingStatus::InProgress),
            Some(StudioRecordingStatus::Failed {
                error: "retained failure".into(),
            }),
            None,
        ] {
            let mut metadata = metadata(1, 0);
            let RecordingMetaInner::Studio(studio) = &mut metadata.inner else {
                unreachable!();
            };
            let StudioRecordingMeta::MultipleSegments { inner } = studio.as_mut() else {
                unreachable!();
            };
            inner.status = status;
            assert!(receipt(metadata).is_none());
        }
        assert!(receipt(metadata(0, 0)).is_none());
    }

    #[test]
    fn clean_stop_receipt_moves_existing_persistence_and_configuration_allocations() {
        let metadata = metadata(1, 1);
        let RecordingMetaInner::Studio(studio) = &metadata.inner else {
            unreachable!();
        };
        let metadata_pointer = studio.as_ref() as *const StudioRecordingMeta;
        let mut configuration = cap_project::ProjectConfiguration::default();
        configuration
            .clips
            .push(cap_project::ClipConfiguration::default());
        let clips_pointer = configuration.clips.as_ptr();
        let receipt = CleanStoppedStudio::new(
            BoundedStoppedStudioMeta::new(metadata).unwrap(),
            configuration,
        )
        .unwrap();
        let claim = receipt.claim(Path::new("synthetic.cap")).unwrap();
        let RecordingMetaInner::Studio(studio) = &claim.metadata().inner else {
            unreachable!();
        };
        assert_eq!(
            studio.as_ref() as *const StudioRecordingMeta,
            metadata_pointer
        );
        assert_eq!(claim.configuration().clips.as_ptr(), clips_pointer);
    }

    #[test]
    fn clean_stop_receipt_declines_oversized_config_capacity_without_changing_config() {
        let mut configuration = cap_project::ProjectConfiguration {
            clips: Vec::with_capacity(MAX_PREPARING_SEGMENTS * 2 + 1),
            ..cap_project::ProjectConfiguration::default()
        };
        configuration
            .clips
            .push(cap_project::ClipConfiguration::default());
        assert!(
            CleanStoppedStudio::new(
                BoundedStoppedStudioMeta::new(metadata(1, 0)).unwrap(),
                configuration,
            )
            .is_none()
        );
    }

    #[test]
    fn clean_stop_receipt_snapshot_matches_existing_persisted_bytes() {
        let directory = tempfile::tempdir().unwrap();
        let metadata = metadata(1, 1);
        let RecordingMetaInner::Studio(studio) = &metadata.inner else {
            unreachable!();
        };
        let persisted = persist_final_recording_meta(directory.path(), studio).unwrap();
        let expected = serde_json::to_vec_pretty(&persisted).unwrap();
        assert_eq!(
            std::fs::read(directory.path().join("recording-meta.json")).unwrap(),
            expected
        );
        let configuration = cap_project::ProjectConfiguration::default();
        configuration.write(directory.path()).unwrap();
        let receipt = CleanStoppedStudio::new(
            BoundedStoppedStudioMeta::new(persisted).unwrap(),
            configuration,
        )
        .unwrap();
        let claim = receipt.claim(directory.path()).unwrap();
        assert_eq!(
            serde_json::to_vec_pretty(claim.metadata()).unwrap(),
            expected
        );
        assert_eq!(
            std::fs::read(directory.path().join("project-config.json")).unwrap(),
            serde_json::to_vec_pretty(claim.configuration()).unwrap()
        );
    }
}