use std::sync::atomic::{AtomicBool, Ordering as AtomicOrdering}; use std::sync::{Arc, Mutex as StdMutex, TryLockError, mpsc as std_mpsc}; use std::thread; use std::time::{Duration, Instant}; use chrono::Utc; use futures_util::FutureExt; use image::ImageEncoder; use image::codecs::png::PngEncoder; use image::imageops::FilterType; #[cfg(any(target_os = "macos", test))] use rayon::prelude::*; use tokio::sync::{Notify, oneshot}; use tokio::task::JoinHandle; use tokio::time::MissedTickBehavior; use uuid::Uuid; use crate::camera_capture::{ CameraFormatSummary, camera_capability_matrix_for_id, parse_native_camera_id, parse_windows_dshow_camera_id, }; #[cfg(target_os = "macos")] use crate::camera_capture::{CameraFrameRateEndpoint, resolve_camera_frame_rate}; #[cfg(any(target_os = "macos", test))] use crate::color::{ycbcr_bt709_full_to_bgr, ycbcr_bt709_video_to_bgr}; use crate::diagnostics::{ PreviewCameraCaptureStats, PreviewCameraCaptureTimingStats, apply_preview_camera_capability_stats, apply_preview_camera_capture_stats, apply_preview_camera_capture_timing_stats, apply_preview_camera_source_stats, apply_preview_source_frame_store_stats, }; use crate::ffmpeg::resolve_ffmpeg_path; use crate::frame_store::{FrameHandle, FrameStore, FrameStoreStats, SurfaceBackingTrackerHandle}; use crate::preview_bmp::{LatestPreviewBmpPoll, PreviewBmpCursor, encode_latest_bgra_bmp}; use crate::protocol::{ CameraCapabilityFormat, LayoutSettings, PreviewCameraDropReasonStats, PreviewCameraStartParams, PreviewCameraState, PreviewCameraStatus, SourceSelection, VideoSettings, }; use crate::source_registry::{SourceConsumerReason, SourceKey}; use crate::source_status::SourceLifecycleStatus; use crate::state::{AppState, CaptureRecoveryExplicitCameraMutationLease}; const PREVIEW_CAMERA_DEFAULT_PNG_WIDTH: u32 = 1280; const PREVIEW_CAMERA_MAX_PNG_WIDTH: u32 = 1920; #[cfg(target_os = "macos")] const CAMERA_CAPTURE_CPU_COPY_ENV: &str = "VIDEORC_CAMERA_CAPTURE_CPU_COPY"; /// Must stay inside the 10 s mutation contract together with the up-to-2 s /// device inventory that precedes it: past that contract the whole backend /// restarts (UHD 620 field log: two restarts, preview never came up). The /// native thread bounds itself to `WINDOWS_CAMERA_START_BUDGET`; this is only /// the backstop. const WINDOWS_CAMERA_PREVIEW_STARTUP_TIMEOUT: Duration = Duration::from_secs(7); #[cfg(target_os = "windows")] const WINDOWS_CAMERA_START_BUDGET: Duration = Duration::from_secs(6); #[cfg(any(target_os = "windows", test))] const WINDOWS_CAMERA_ATTEMPT_FIRST_FRAME_TIMEOUT: Duration = Duration::from_secs(4); /// Kept free for the `-framerate`/default-format attempts so a stalled MJPEG /// mode cannot spend them; the HP HD Camera's default format delivered its /// first frame in ~1.0-1.3 s. #[cfg(any(target_os = "windows", test))] const WINDOWS_CAMERA_DEFAULT_FORMAT_RESERVE: Duration = Duration::from_millis(2500); /// Kept free by the `-framerate` attempt for the final negotiated-default /// attempt, so a stalled exact rate cannot leave it no time. The reserve must /// cover the stalled attempt's own teardown (kill, wait, killer join) and /// still leave the ~1.0-1.3 s the HP HD Camera's default format needs for /// its first frame. #[cfg(any(target_os = "windows", test))] const WINDOWS_CAMERA_NEGOTIATED_DEFAULT_RESERVE: Duration = Duration::from_millis(1500); /// An attempt that still has a fallback after it is skipped below this: it /// cannot realistically go live, and the fallback gets the time instead. #[cfg(any(target_os = "windows", test))] const WINDOWS_CAMERA_MIN_EARLY_ATTEMPT: Duration = Duration::from_secs(1); const LINUX_CAMERA_PREVIEW_STARTUP_TIMEOUT: Duration = Duration::from_secs(12); /// One DirectShow inventory or mode probe (`-list_devices` / `-list_options`). #[cfg(any(target_os = "windows", test))] const WINDOWS_CAMERA_INVENTORY_TIMEOUT: Duration = Duration::from_secs(2); /// How long `preview.camera.start` waits for the transition before it replies /// Starting; the detached supervisor keeps owning the start. With the Windows /// inventory ahead of it, the reply must land inside the 10 s mutation /// execution contract, past which the backend restarts (a C920 start of /// 10-15 s did, when this was 15 s). pub(crate) const CAMERA_COMMAND_TRANSITION_TIMEOUT: Duration = Duration::from_secs(7); /// The command-facing worst case: inventory, then the bounded transition wait. #[cfg(test)] pub(crate) const CAMERA_COMMAND_RESPONSE_BUDGET: Duration = Duration::from_secs( WINDOWS_CAMERA_INVENTORY_TIMEOUT.as_secs() + CAMERA_COMMAND_TRANSITION_TIMEOUT.as_secs(), ); const CAMERA_STOP_RESPONSE_TIMEOUT: Duration = Duration::from_secs(2); #[cfg(any(target_os = "windows", test))] const WINDOWS_CAMERA_RATE_CAP_EPSILON_SECONDS: f64 = 0.000_001; /// A DirectShow mode listed this close under the target rate still reaches /// it (29.97 for 30), the same tolerance the Sources shortfall check uses. #[cfg(any(target_os = "windows", test))] const WINDOWS_CAMERA_MODE_FPS_TOLERANCE: f64 = 1.0; /// How many of the camera's own modes the start ladder tries before the /// exact-rate and negotiated fallbacks. Each failing rung costs about a /// quarter second, and the budget reserve skips any that would eat the /// fallbacks' time. #[cfg(any(target_os = "windows", test))] const WINDOWS_CAMERA_EXPLICIT_MODE_RUNGS: usize = 3; /// The native thread never answered its start. A thread that outlived the /// startup timeout is stopped next, and its stop path keeps the DirectShow /// modes cached for this camera, so a timeout forgets them here: whatever /// made the start that slow (a replugged or re-driven device) may have /// changed them. A deliberate stop disconnects the channel instead, and keeps /// the cache. fn native_camera_startup_unanswered( error: std_mpsc::RecvTimeoutError, device_unique_id: &str, ) -> NativeCameraStartup { #[cfg(target_os = "windows")] if error == std_mpsc::RecvTimeoutError::Timeout { windows::forget_dshow_modes(device_unique_id); } #[cfg(not(target_os = "windows"))] let _ = (error, device_unique_id); NativeCameraStartup::Failed("Timed out while starting native camera preview.".to_string()) } fn native_camera_preview_thread_startup_timeout() -> Duration { // FFmpeg-fed cameras (DirectShow, V4L2) pay a child spawn plus device // negotiation per attempt before the first frame. if cfg!(target_os = "windows") { WINDOWS_CAMERA_PREVIEW_STARTUP_TIMEOUT } else if cfg!(target_os = "linux") { LINUX_CAMERA_PREVIEW_STARTUP_TIMEOUT } else { Duration::from_secs(4) } } #[cfg(target_os = "macos")] fn native_preview_surface_env_enabled() -> bool { // v1 default: the native CAMetalLayer surface IS the production preview. The env // var remains a developer kill switch only (VIDEORC_NATIVE_PREVIEW_SURFACE=0). match std::env::var("VIDEORC_NATIVE_PREVIEW_SURFACE").ok() { Some(value) => truthy_env_value(Some(value.as_str())), None => true, } } #[cfg(target_os = "macos")] fn forced_camera_capture_cpu_copy_enabled() -> bool { truthy_env_value(std::env::var(CAMERA_CAPTURE_CPU_COPY_ENV).ok().as_deref()) } #[cfg(target_os = "macos")] fn truthy_env_value(value: Option<&str>) -> bool { matches!( value.map(|value| value.trim().to_ascii_lowercase()), Some(value) if matches!(value.as_str(), "1" | "true" | "yes" | "on") ) } #[cfg(any(target_os = "macos", test))] fn should_skip_camera_capture_cpu_copy_for_config( zero_copy_source_handle_available: bool, source_zerocopy_enabled: bool, native_preview_surface_enabled: bool, forced_cpu_copy_enabled: bool, ) -> bool { zero_copy_source_handle_available && source_zerocopy_enabled && native_preview_surface_enabled && !forced_cpu_copy_enabled } #[cfg(target_os = "macos")] fn should_skip_camera_capture_cpu_copy(zero_copy_source_handle_available: bool) -> bool { should_skip_camera_capture_cpu_copy_for_config( zero_copy_source_handle_available, source_zerocopy_enabled(), native_preview_surface_env_enabled(), forced_camera_capture_cpu_copy_enabled(), ) } #[cfg(target_os = "macos")] use crate::metal_compositor::source_zerocopy_enabled; pub type PreviewCameraSlot = Arc>; #[derive(Debug)] pub struct PreviewCameraRuntime { #[cfg(all(test, target_os = "windows"))] test_dshow_inventory: Option, pub status: PreviewCameraStatus, /// Plan 224 D6: the camera is lent to the talk show's room (the renderer /// publishes it). Every start is refused until the room gives it back. pub(crate) lent_to_talk_show: bool, /// Source-level ownership keeps surface-backed frames observable while a /// capture session replaces its per-session `FrameStore`. surface_backing_tracker: SurfaceBackingTrackerHandle, run_id: Option, source_key: Option, starting: Option, /// Completion boundary for the persistent supervisor that owns the current /// Starting generation. Layout work that holds shutdown admission across a /// delayed transition clones this token before runtime ownership can move. starting_transition_completion: Option>, /// Present only when `starting` was admitted by capture recovery. An /// operator start with the same exact key must supersede that lease instead /// of joining a worker whose recovery ticket has just been invalidated. starting_recovery_epoch: Option, /// Layout intent that currently owns cancellation authority for this /// Starting generation. Same-key layout joins transfer this owner; a public /// camera command clears it so stale layout timeouts cannot stop that /// operator-owned generation. starting_layout_intent_id: Option, start_generation: u64, /// Desired stop generation. The native owner is deliberately retained in /// `active` until the transition supervisor has stopped and joined it. /// This lets command callers time out without losing physical ownership. pending_stop_generation: Option, /// Generation of `active`. Kept separate from the next/in-flight start /// lease so readers can never observe an old session under a new identity. active_generation: Option, /// Serializes stop/join/start transitions. A recovery restart must never /// overlap the native session it is replacing (or a concurrent user start). transition_gate: Arc>, /// Opaque authority for retrying a recovery start that reached a terminal /// Failed state before publishing a replacement session. The token is /// generation-bound and is invalidated by every ordinary start/stop. failed_recovery_retry: Option, /// Native ownership registered immediately after a successful thread spawn /// and before startup readiness can suspend or panic. pending_native: Option, disconnected: Option, active: Option, poll_task: Option>, /// When the current session acked Live. macOS acks Live as soon as /// startRunning() returns — before any frame exists — so a session can be /// "live" and frameless. This timestamp bounds how long that is treated /// as normal startup rather than a dead session (see /// camera_live_session_is_frameless_zombie). live_acked_at: Option, } #[derive(Debug, Clone, PartialEq, Eq)] struct PreviewCameraStartKey { source_key: SourceKey, ffmpeg_path: String, video: VideoSettings, target_fps: u32, /// Derived capture box (inset overlay vs full canvas). Two starts that /// agree on everything else but need different capture geometry must not /// join each other's in-flight session. capture_target: (u32, u32), } #[derive(Debug, Clone)] struct PreviewCameraStartLease { key: PreviewCameraStartKey, generation: u64, transition_completion: Arc, } impl PreviewCameraStartLease { fn new(key: PreviewCameraStartKey, generation: u64) -> Self { Self { key, generation, transition_completion: Arc::new(PreviewCameraTransitionCompletion::default()), } } } impl PartialEq for PreviewCameraStartLease { fn eq(&self, other: &Self) -> bool { self.key == other.key && self.generation == other.generation } } impl Eq for PreviewCameraStartLease {} #[derive(Debug, Default)] struct PreviewCameraTransitionCompletion { completed: AtomicBool, notify: Notify, } impl PreviewCameraTransitionCompletion { fn complete(&self) { if !self.completed.swap(true, AtomicOrdering::AcqRel) { self.notify.notify_waiters(); } } async fn wait(&self) { loop { let notified = self.notify.notified(); tokio::pin!(notified); let _ = notified.as_mut().enable(); if self.completed.load(AtomicOrdering::Acquire) { return; } notified.await; } } } struct PreviewCameraTransitionCompletionGuard { completion: Arc, } impl PreviewCameraTransitionCompletionGuard { fn new(completion: Arc) -> Self { Self { completion } } } impl Drop for PreviewCameraTransitionCompletionGuard { fn drop(&mut self) { self.completion.complete(); } } /// Exact authority for cancelling one camera generation that was observed /// while it was still Starting. Layout timeout cleanup must carry this token /// from its readiness sample to the stop CAS: a newer public camera start does /// not share the layout-intent mutex and must never be mistaken for the expired /// generation. #[derive(Debug, Clone, PartialEq, Eq)] pub(crate) struct PreviewCameraStartingIdentity { pub source_key: SourceKey, pub generation: u64, pub layout_intent_id: Option, } #[derive(Debug, Clone, PartialEq)] pub(crate) struct PreviewCameraLayoutStart { pub status: PreviewCameraStatus, /// Present only when this layout request admitted a fresh generation. A /// joined/reused public generation remains owned by that independent /// request and layout timeout cleanup must leave it alone. pub admitted_starting_identity: Option, } impl PreviewCameraLayoutStart { fn without_admission(status: PreviewCameraStatus) -> Self { Self { status, admitted_starting_identity: None, } } } #[derive(Debug, Clone)] enum PreviewCameraStartRegistration { JoinExisting { admitted_starting_identity: Option, transition_completion: Arc, }, Reused(PreviewCameraStatus), RejectedSuperseded(PreviewCameraStatus), RejectedShutdown(PreviewCameraStatus), Started { lease: PreviewCameraStartLease, }, } impl PartialEq for PreviewCameraStartRegistration { fn eq(&self, other: &Self) -> bool { match (self, other) { ( Self::JoinExisting { admitted_starting_identity: left, .. }, Self::JoinExisting { admitted_starting_identity: right, .. }, ) => left == right, (Self::Reused(left), Self::Reused(right)) => left == right, (Self::RejectedSuperseded(left), Self::RejectedSuperseded(right)) => left == right, (Self::RejectedShutdown(left), Self::RejectedShutdown(right)) => left == right, (Self::Started { lease: left }, Self::Started { lease: right }) => left == right, _ => false, } } } #[derive(Debug, Clone, Copy, PartialEq, Eq)] enum PreviewCameraStartWait { /// Reply once the persistent transition supervisor owns the admitted /// generation. Live, failed and every later state reach the client as /// `preview.camera.status` events. `session.start` still drains that /// supervisor through `source_transition_fence`, not through this reply. Admitted, Bounded, TransitionComplete, } /// The wait behind the public `preview.camera.start` command (issue #1068). /// The command sits on the ordered WebSocket lane, so every later ordered /// command used to wait out the whole native open: about 2–4 s for a /// DirectShow camera on Windows. Windows replies at admission instead. macOS /// and Linux keep the bounded wait: their `permission-needed` result is /// discovered by the supervisor and the renderer reports it from the reply. const fn public_camera_start_wait() -> PreviewCameraStartWait { if cfg!(target_os = "windows") { PreviewCameraStartWait::Admitted } else { PreviewCameraStartWait::Bounded } } #[derive(Debug, Clone, PartialEq)] struct PreviewCameraRestartConfig { camera_id: String, device_unique_id: String, ffmpeg_path: String, layout: LayoutSettings, video: VideoSettings, target_fps: u32, } #[derive(Debug, Clone, PartialEq)] struct PreviewCameraFailedRecoveryRetry { source_key: SourceKey, generation: u64, config_fingerprint: u64, config: PreviewCameraRestartConfig, } /// Generation-bound authority to restart the exact live camera configuration. /// The configuration stays private to this module so recovery never has to /// reconstruct capture parameters from renderer state. #[derive(Debug, Clone, PartialEq)] pub(crate) struct PreviewCameraRestartSnapshot { pub source_key: SourceKey, pub generation: u64, pub config_fingerprint: u64, config: PreviewCameraRestartConfig, } #[derive(Debug, Clone, PartialEq)] // Recovery consumes this result immediately. Keeping the generation-bound // status snapshot inline avoids adding heap ownership to the restart handoff. #[allow(clippy::large_enum_variant)] pub(crate) enum PreviewCameraForceRestartResult { Restarted { status: PreviewCameraStatus, generation: u64, }, RejectedStale, } /// A recovery generation whose source-transition ownership has already been /// registered with the process-wide fence. Session startup may safely snapshot /// that fence after this value is returned; waiting for native stop/start is a /// separate, potentially blocking completion phase. pub(crate) struct PreviewCameraForceRestartAttempt { generation: u64, source_key: SourceKey, completion: JoinHandle, } #[derive(Debug, Clone, PartialEq)] pub(crate) struct PreviewCameraRecoveryEvidence { pub source_key: SourceKey, pub generation: u64, pub target_fps: u32, pub source_fps: Option, pub capture_callback_count: u64, pub frame_store_publications: u64, pub did_drop_callback_count: u64, pub out_of_buffers: u64, pub surface_backing_live_count: u64, pub surface_backing_peak_count: u64, pub latest_sequence: Option, pub frame_age_ms: Option, pub requested_width: Option, pub requested_height: Option, pub configured_width: Option, pub configured_height: Option, pub actual_width: Option, pub actual_height: Option, } #[derive(Clone)] struct PreparedCameraStart { camera_id: String, device_unique_id: String, ffmpeg_path: String, target_fps: u32, source_key: SourceKey, params: PreviewCameraStartParams, lease: PreviewCameraStartLease, layout_intent_id: Option, recovery: Option, } #[derive(Clone)] struct PreparedCameraRecoveryAdmission { epoch: u64, previous_status: PreviewCameraStatus, previous_run_id: Option, previous_live_acked_at: Option, } #[derive(Debug)] struct NativeCameraPreviewThread { stop_tx: std_mpsc::Sender<()>, join_handle: Option>, shared: Arc>, camera_id: String, device_unique_id: String, ffmpeg_path: String, layout: LayoutSettings, video: VideoSettings, /// Stable cadence negotiated when this generation started. This is never /// replaced with the observed delivery rate: doing so would let a decaying /// source lower its own liveness threshold. effective_fps: u32, /// Immutable output geometry selected at startup for this generation. /// Recovery compares direct FrameStore dimensions against this exact box. configured_output: (u32, u32), /// The capture target box this session's AVFoundation output geometry was /// derived from at start. `layout` above is refreshed on reuse as /// bookkeeping, so it cannot answer "what geometry is this session /// actually delivering" — this field can. capture_target: (u32, u32), } #[derive(Debug)] struct PendingNativeCameraThread { generation: u64, stop_tx: std_mpsc::Sender<()>, join_handle: Option>, } /// Wait handle for a camera stop that was admitted and handed to a persistent /// transition supervisor. Dropping this value only detaches the waiter; the /// supervisor continues to own and retire the native session. pub(crate) struct PreviewCameraStop { status: PreviewCameraStatus, completion: Option>, } #[cfg(test)] pub(crate) type PreviewCameraTransitionGuard = tokio::sync::OwnedMutexGuard<()>; #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum PreviewCameraPixelFormat { Bgra8, } #[cfg(any(target_os = "macos", test))] #[derive(Debug, Clone, Copy, PartialEq, Eq)] #[cfg_attr(target_os = "windows", allow(dead_code))] enum CameraCaptureDropReason { FrameWasLate, OutOfBuffers, Discontinuity, Unknown, } #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] struct CameraCaptureDropReasonCounts { frame_was_late: u64, out_of_buffers: u64, discontinuity: u64, unknown: u64, } impl CameraCaptureDropReasonCounts { #[cfg(any(target_os = "macos", test))] fn record(&mut self, reason: CameraCaptureDropReason) { let counter = match reason { CameraCaptureDropReason::FrameWasLate => &mut self.frame_was_late, CameraCaptureDropReason::OutOfBuffers => &mut self.out_of_buffers, CameraCaptureDropReason::Discontinuity => &mut self.discontinuity, CameraCaptureDropReason::Unknown => &mut self.unknown, }; *counter = counter.saturating_add(1); } fn total(self) -> u64 { self.frame_was_late .saturating_add(self.out_of_buffers) .saturating_add(self.discontinuity) .saturating_add(self.unknown) } fn diagnostic_stats(self) -> PreviewCameraDropReasonStats { PreviewCameraDropReasonStats { frame_was_late: self.frame_was_late, out_of_buffers: self.out_of_buffers, discontinuity: self.discontinuity, unknown: self.unknown, } } } #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct PreviewCameraFrameInfo { pub sequence: u64, pub width: u32, pub height: u32, pub frame_age_ms: u64, } #[derive(Debug, Clone)] pub struct PreviewCameraFrameSource { shared: Arc>, layout: LayoutSettings, source_key: Option, target_fps: u32, generation: u64, } impl PreviewCameraFrameSource { pub fn source_key(&self) -> Option<&SourceKey> { self.source_key.as_ref() } pub fn target_fps(&self) -> u32 { self.target_fps } pub fn generation(&self) -> u64 { self.generation } pub fn try_latest_frame_result( &self, ) -> Result, LayoutSettings)>, ()> { match self.shared.try_lock() { Ok(guard) => Ok(guard .frame_store .latest() .map(|frame| (frame, self.layout.clone()))), Err(TryLockError::WouldBlock) => Err(()), Err(TryLockError::Poisoned(poisoned)) => Ok(poisoned .into_inner() .frame_store .latest() .map(|frame| (frame, self.layout.clone()))), } } pub fn latest_frame_blocking( &self, ) -> Option<(FrameHandle, LayoutSettings)> { let frame = self .shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) .frame_store .latest()?; Some((frame, self.layout.clone())) } } #[derive(Debug, Default)] pub struct PreviewCameraShared { frame_store: FrameStore, capture_callback_count: u64, frames_captured: u64, dropped_frames: u64, capture_drop_reasons: CameraCaptureDropReasonCounts, capture_pixel_format: Option, frames_in_window: u64, window_started_at: Option, source_fps: Option, capture_timings: CameraCaptureTimingWindow, /// Plan 258 S4: the system's own effects on this camera, as the camera /// thread last read them from the device. system_effect: Option, } impl PreviewCameraShared { fn with_surface_backing_tracker(tracker: SurfaceBackingTrackerHandle) -> Self { Self { frame_store: FrameStore::new_with_surface_backing_tracker(1, tracker), ..Self::default() } } /// A frame read from the capture process pipe (Windows dshow, Linux v4l2) /// is that platform's capture callback. Count it like the AVFoundation /// sample-buffer callback: capture recovery verifies a restarted camera by /// this counter, and a pipe camera that never advanced it was restarted /// while live and latched Failed. #[cfg(any(not(target_os = "macos"), test))] fn record_pipe_frame_callback(&mut self, at: Instant) { self.capture_timings.record_callback_at(at); self.capture_callback_count = self.capture_callback_count.saturating_add(1); } } #[derive(Debug, Default)] struct CameraCaptureTimingWindow { last_callback_at: Option, last_sample_pts_seconds: Option, callback_gap_ms: Vec, sample_pts_gap_ms: Vec, pixel_buffer_lock_ms: Vec, row_copy_ms: Vec, publish_ms: Vec, frame_bytes: u64, } impl CameraCaptureTimingWindow { fn record_callback_at(&mut self, now: Instant) { if let Some(previous) = self.last_callback_at.replace(now) { push_timing_sample( &mut self.callback_gap_ms, now.duration_since(previous).as_secs_f64() * 1000.0, ); } } #[cfg(any(target_os = "macos", test))] fn record_sample_pts(&mut self, sample_pts_seconds: Option) { let Some(sample_pts_seconds) = sample_pts_seconds else { return; }; if let Some(previous) = self.last_sample_pts_seconds.replace(sample_pts_seconds) { let gap_ms = (sample_pts_seconds - previous).abs() * 1000.0; if gap_ms.is_finite() { push_timing_sample(&mut self.sample_pts_gap_ms, gap_ms); } } } fn record_valid_frame( &mut self, pixel_buffer_lock_ms: f64, row_copy_ms: f64, publish_ms: f64, frame_bytes: u64, ) { push_timing_sample(&mut self.pixel_buffer_lock_ms, pixel_buffer_lock_ms); push_timing_sample(&mut self.row_copy_ms, row_copy_ms); push_timing_sample(&mut self.publish_ms, publish_ms); self.frame_bytes = frame_bytes; } /// Gap samples available for a cadence verdict (the larger of the two /// windows; AVFoundation feeds sample PTS, dshow only callbacks). fn gap_sample_count(&self) -> usize { self.sample_pts_gap_ms.len().max(self.callback_gap_ms.len()) } fn reset(&mut self) { self.last_callback_at = None; self.last_sample_pts_seconds = None; self.callback_gap_ms.clear(); self.sample_pts_gap_ms.clear(); self.pixel_buffer_lock_ms.clear(); self.row_copy_ms.clear(); self.publish_ms.clear(); } fn snapshot(&self) -> PreviewCameraCaptureTimingStats { PreviewCameraCaptureTimingStats { capture_gap_p95_ms: percentile(&self.callback_gap_ms, 95), capture_gap_p99_ms: percentile(&self.callback_gap_ms, 99), capture_gap_max_ms: max_sample(&self.callback_gap_ms), sample_pts_gap_p95_ms: percentile(&self.sample_pts_gap_ms, 95), sample_pts_gap_p99_ms: percentile(&self.sample_pts_gap_ms, 99), sample_pts_gap_max_ms: max_sample(&self.sample_pts_gap_ms), pixel_buffer_lock_p95_ms: percentile(&self.pixel_buffer_lock_ms, 95), row_copy_p95_ms: percentile(&self.row_copy_ms, 95), publish_p95_ms: percentile(&self.publish_ms, 95), frame_bytes: self.frame_bytes, } } } fn push_timing_sample(samples: &mut Vec, value: f64) { const MAX_SAMPLES: usize = 240; if samples.len() >= MAX_SAMPLES { samples.remove(0); } samples.push(value); } fn percentile(samples: &[f64], p: u32) -> Option { if samples.is_empty() { return None; } let mut sorted = samples.to_vec(); sorted.sort_by(|left, right| left.total_cmp(right)); let index = (((p as f64 / 100.0) * sorted.len() as f64).ceil() as usize) .saturating_sub(1) .min(sorted.len() - 1); Some(sorted[index]) } fn max_sample(samples: &[f64]) -> Option { samples.iter().copied().max_by(f64::total_cmp) } fn stable_capture_config_fingerprint(bytes: &[u8]) -> u64 { // Explicit FNV-1a keeps the diagnostic stable across processes and Rust // versions (unlike DefaultHasher, whose algorithm is not a contract). let mut hash = 0xcbf2_9ce4_8422_2325_u64; for byte in bytes { hash ^= u64::from(*byte); hash = hash.wrapping_mul(0x0000_0100_0000_01b3); } hash } fn camera_config_fingerprint(start_key: &PreviewCameraStartKey, layout: &LayoutSettings) -> u64 { let encoded = serde_json::to_vec(&( &start_key.source_key, &start_key.ffmpeg_path, &start_key.video, start_key.target_fps, start_key.capture_target, layout, )) .unwrap_or_default(); stable_capture_config_fingerprint(&encoded) } fn camera_restart_start_key( source_key: &SourceKey, config: &PreviewCameraRestartConfig, ) -> PreviewCameraStartKey { PreviewCameraStartKey { source_key: source_key.clone(), ffmpeg_path: config.ffmpeg_path.clone(), video: config.video.clone(), target_fps: config.target_fps, capture_target: camera_capture_target_dimensions(&config.layout, &config.video), } } fn camera_restart_config_fingerprint( source_key: &SourceKey, config: &PreviewCameraRestartConfig, ) -> u64 { camera_config_fingerprint( &camera_restart_start_key(source_key, config), &config.layout, ) } fn stable_effective_camera_fps(selected_fps: f64, requested_fps: u32) -> u32 { if selected_fps.is_finite() && selected_fps > 0.0 { selected_fps.round().clamp(1.0, 120.0) as u32 } else { requested_fps.clamp(1, 120) } } #[cfg(any(target_os = "macos", test))] fn negotiated_camera_fps( active_duration_fps: Option, applied_fps: Option, native_format_fallback_fps: f64, ) -> f64 { active_duration_fps .filter(|fps| fps.is_finite() && *fps > 0.0) .or_else(|| applied_fps.filter(|fps| fps.is_finite() && *fps > 0.0)) .unwrap_or_else(|| { if native_format_fallback_fps.is_finite() && native_format_fallback_fps > 0.0 { native_format_fallback_fps } else { 30.0 } }) } fn log_camera_generation( generation: u64, reason: &'static str, start_key: &PreviewCameraStartKey, layout: &LayoutSettings, ) { tracing::info!( "[capture-generation] source=camera generation={} reason={} config={:016x}", generation, reason, camera_config_fingerprint(start_key, layout), ); } pub fn initial_preview_camera_state() -> PreviewCameraRuntime { PreviewCameraRuntime { #[cfg(all(test, target_os = "windows"))] test_dshow_inventory: None, status: idle_status(Some("Native camera preview is not running.".to_string())), lent_to_talk_show: false, surface_backing_tracker: SurfaceBackingTrackerHandle::default(), run_id: None, source_key: None, starting: None, starting_transition_completion: None, starting_recovery_epoch: None, starting_layout_intent_id: None, start_generation: 0, pending_stop_generation: None, active_generation: None, transition_gate: Arc::new(tokio::sync::Mutex::new(())), failed_recovery_retry: None, pending_native: None, disconnected: None, active: None, poll_task: None, live_acked_at: None, } } /// Reconcile operator-owned camera configuration truth on the process runtime. /// Awaiting the returned JoinHandle preserves prompt command semantics, while /// cancellation of a disposable caller drops only its waiter: the recovery /// reset itself still completes. pub(crate) async fn reconcile_explicit_camera_configuration_change(state: &AppState) { let reconciliation_state = state.clone(); let completion = state.spawn_process_task(async move { crate::capture_recovery::note_explicit_camera_configuration_changed(&reconciliation_state) .await; }); if let Err(error) = completion.await { tracing::error!("Explicit camera recovery reconciliation task failed: {error}"); } } /// Order an explicit scene/configuration intent against the final native /// camera install boundary. The synchronous recovery-admission gate advances /// the sampled camera-mutation epoch and clears physical admission together, /// while this preview lock orders that publication against installation. pub(crate) async fn begin_capture_recovery_explicit_camera_configuration_mutation( state: &AppState, ) -> CaptureRecoveryExplicitCameraMutationLease { let _camera_authority = state.preview_camera.lock().await; state.begin_capture_recovery_explicit_camera_mutation() } async fn finish_capture_recovery_explicit_camera_configuration_mutation( state: &AppState, mutation: CaptureRecoveryExplicitCameraMutationLease, ) { mutation.finish(); reconcile_explicit_camera_configuration_change(state).await; } fn camera_start_rejected_for_shutdown(mut status: PreviewCameraStatus) -> PreviewCameraStatus { status.updated_at = Utc::now().to_rfc3339(); status.message = Some("Camera start rejected because backend shutdown is already in progress.".to_string()); status } pub async fn start_preview_camera( state: AppState, params: PreviewCameraStartParams, ) -> PreviewCameraStatus { start_preview_camera_with_owner(state, params, None, None, public_camera_start_wait()) .await .status } pub(crate) async fn start_preview_camera_for_layout( state: AppState, params: PreviewCameraStartParams, layout_intent_id: u64, admission_ready: oneshot::Sender>, ) -> PreviewCameraLayoutStart { start_preview_camera_with_owner( state, params, Some(layout_intent_id), Some(admission_ready), PreviewCameraStartWait::Bounded, ) .await } /// Layout-owned start whose caller also owns a shutdown-admission fence. Unlike /// the command-facing start, this does not release its caller at the 15-second /// response boundary: it waits for the persistent transition supervisor that /// owns the exact admitted generation to finish. Same-key joins share that /// generation completion boundary, even if runtime `starting` is superseded. pub(crate) async fn start_preview_camera_for_layout_until_transition_complete( state: AppState, params: PreviewCameraStartParams, layout_intent_id: u64, admission_ready: oneshot::Sender>, ) -> PreviewCameraLayoutStart { start_preview_camera_with_owner( state, params, Some(layout_intent_id), Some(admission_ready), PreviewCameraStartWait::TransitionComplete, ) .await } #[cfg(target_os = "windows")] async fn resolve_windows_camera_target( state: &AppState, ffmpeg: &str, selected: &str, ) -> Result { #[cfg(test)] if let Some(inventory) = state .preview_camera .lock() .await .test_dshow_inventory .clone() { return crate::audio_capture_adapter::resolve_dshow_video_name(&inventory, selected) .map_err(|error| error.to_string()); } #[cfg(not(test))] let _ = state; static INVENTORY_OWNERS: std::sync::OnceLock> = std::sync::OnceLock::new(); let permit = INVENTORY_OWNERS .get_or_init(|| Arc::new(tokio::sync::Semaphore::new(2))) .clone() .try_acquire_owned() .map_err(|_| "Camera inventory is still closing. Retry shortly.".to_string())?; let ffmpeg = ffmpeg.to_string(); let selected = selected.to_string(); tokio::task::spawn_blocking(move || { let _permit = permit; let output = crate::process_job::output_owned_std_with_timeout( std::process::Command::new(ffmpeg).args([ "-hide_banner", "-list_devices", "true", "-f", "dshow", "-i", "dummy", ]), WINDOWS_CAMERA_INVENTORY_TIMEOUT, ) .map_err(|error| format!("Could not verify the selected camera: {error}"))?; crate::audio_capture_adapter::resolve_dshow_video_name( &String::from_utf8_lossy(&output.stderr), &selected, ) .map_err(|error| error.to_string()) }) .await .map_err(|error| format!("Camera inventory owner failed: {error}"))? } async fn start_preview_camera_with_owner( state: AppState, params: PreviewCameraStartParams, layout_intent_id: Option, mut admission_ready: Option>>, wait: PreviewCameraStartWait, ) -> PreviewCameraLayoutStart { #[cfg(test)] if params.sources.camera_id.as_deref() == Some("camera:iso-runtime") { if preview_camera_frame_source(&state).await.is_none() { test_install_live_camera_for_layout( &state, "camera:iso-runtime", ¶ms.layout, ¶ms.video, ) .await; } signal_camera_layout_admission(&mut admission_ready, None); return PreviewCameraLayoutStart::without_admission(preview_camera_status(&state).await); } if state.process_shutdown_requested() { let status = camera_start_rejected_for_shutdown(preview_camera_status(&state).await); signal_camera_layout_admission(&mut admission_ready, None); return PreviewCameraLayoutStart::without_admission(status); } // Plan 224 D6: one owner at a time. While the room holds the camera, a // layout transaction or the Sources page must not take it back under // the renderer's `getUserMedia`; the status says why. if camera_lent_to_talk_show(&state).await { let mut status = preview_camera_status(&state).await; status.message = Some(CAMERA_LENT_TO_TALK_SHOW_MESSAGE.to_string()); signal_camera_layout_admission(&mut admission_ready, None); return PreviewCameraLayoutStart::without_admission(status); } if layout_intent_id.is_some_and(|intent_id| intent_id < state.latest_layout_intent_id()) { let status = preview_camera_status(&state).await; signal_camera_layout_admission(&mut admission_ready, None); return PreviewCameraLayoutStart::without_admission(status); } let Some(camera_id) = params.sources.camera_id.clone() else { let status = status_for_missing_camera(None, "No camera is selected."); if layout_intent_id.is_some() { signal_camera_layout_admission(&mut admission_ready, None); return PreviewCameraLayoutStart::without_admission(status); } let explicit_mutation = begin_capture_recovery_explicit_camera_configuration_mutation(&state).await; let stop = begin_preview_camera_stop(&state).await; let _ = finish_preview_camera_stop(stop).await; refresh_camera_capability_diagnostics(&state, None).await; set_camera_status(&state, status.clone()).await; finish_capture_recovery_explicit_camera_configuration_mutation(&state, explicit_mutation) .await; signal_camera_layout_admission(&mut admission_ready, None); return PreviewCameraLayoutStart::without_admission(status); }; let Some(camera_source) = selected_camera_source(&camera_id) else { let status = status_for_missing_camera( Some(camera_id.clone()), "Selected camera is not a supported Videorc camera source.", ); if layout_intent_id.is_some() { signal_camera_layout_admission(&mut admission_ready, None); return PreviewCameraLayoutStart::without_admission(status); } let explicit_mutation = begin_capture_recovery_explicit_camera_configuration_mutation(&state).await; let stop = begin_preview_camera_stop(&state).await; let _ = finish_preview_camera_stop(stop).await; refresh_camera_capability_diagnostics(&state, Some(camera_id.clone())).await; set_camera_status(&state, status.clone()).await; finish_capture_recovery_explicit_camera_configuration_mutation(&state, explicit_mutation) .await; signal_camera_layout_admission(&mut admission_ready, None); return PreviewCameraLayoutStart::without_admission(status); }; let unique_id = camera_source.device_unique_id().to_string(); let ffmpeg_path = resolve_ffmpeg_path(params.ffmpeg_path.clone()); #[cfg(target_os = "windows")] let unique_id = match resolve_windows_camera_target(&state, &ffmpeg_path, &unique_id).await { Ok(target) => target, Err(error) => { // Inventory admission precedes old-owner retirement. A missing or // ambiguous DirectShow target cannot evict a healthy camera. let status = status_for_missing_camera(Some(camera_id.clone()), &error); signal_camera_layout_admission(&mut admission_ready, None); return PreviewCameraLayoutStart::without_admission(status); } }; let explicit_mutation = begin_capture_recovery_explicit_camera_configuration_mutation(&state).await; refresh_camera_capability_diagnostics(&state, Some(camera_id.clone())).await; let target_fps = params.video.fps.clamp(1, 120); let source_key = SourceKey::camera(camera_id.clone()); let starting = PreviewCameraStatus { state: PreviewCameraState::Starting, camera_id: Some(camera_id.clone()), device_unique_id: Some(unique_id.clone()), target_fps, width: None, height: None, requested_width: None, requested_height: None, actual_width: None, actual_height: None, selected_format_width: None, selected_format_height: None, selected_format_min_fps: None, selected_format_max_fps: None, source_fps: None, frame_age_ms: None, frames_captured: 0, dropped_frames: 0, sequence: None, updated_at: Utc::now().to_rfc3339(), message: Some("Starting native camera preview.".to_string()), no_video: None, system_effect: None, }; let start_key = PreviewCameraStartKey { source_key: source_key.clone(), ffmpeg_path: ffmpeg_path.clone(), video: params.video.clone(), target_fps, capture_target: camera_capture_target_dimensions(¶ms.layout, ¶ms.video), }; let start_lease = match begin_camera_start( &state, start_key.clone(), ¶ms.layout, starting, layout_intent_id, ) .await { PreviewCameraStartRegistration::JoinExisting { admitted_starting_identity, transition_completion, } => { signal_camera_layout_admission( &mut admission_ready, admitted_starting_identity.clone(), ); let status = match wait { // The joined generation's own supervisor publishes its result. PreviewCameraStartWait::Admitted => preview_camera_status(&state).await, PreviewCameraStartWait::Bounded => wait_for_camera_start(&state, &start_key).await, PreviewCameraStartWait::TransitionComplete => { transition_completion.wait().await; preview_camera_status(&state).await } }; finish_capture_recovery_explicit_camera_configuration_mutation( &state, explicit_mutation, ) .await; return PreviewCameraLayoutStart { status, admitted_starting_identity, }; } PreviewCameraStartRegistration::Reused(status) => { signal_camera_layout_admission(&mut admission_ready, None); finish_capture_recovery_explicit_camera_configuration_mutation( &state, explicit_mutation, ) .await; return PreviewCameraLayoutStart::without_admission(status); } PreviewCameraStartRegistration::RejectedSuperseded(status) | PreviewCameraStartRegistration::RejectedShutdown(status) => { signal_camera_layout_admission(&mut admission_ready, None); finish_capture_recovery_explicit_camera_configuration_mutation( &state, explicit_mutation, ) .await; return PreviewCameraLayoutStart::without_admission(status); } PreviewCameraStartRegistration::Started { lease } => lease, }; log_camera_generation( start_lease.generation, "normal-start", &start_key, ¶ms.layout, ); let lease = start_lease.clone(); let completion = queue_registered_preview_camera( state.clone(), PreparedCameraStart { camera_id, device_unique_id: unique_id, ffmpeg_path, target_fps, source_key, params, lease: start_lease, layout_intent_id, recovery: None, }, Some(explicit_mutation), ); // The detached process supervisor already owns the admitted generation, // including the explicit-mutation lease. Cancelling the command waiter // cannot expose recovery while native startup is still in flight. Private // force-recovery/retry paths bypass this public operator boundary. let admitted_starting_identity = layout_intent_id.map(|layout_intent_id| PreviewCameraStartingIdentity { source_key: lease.key.source_key.clone(), generation: lease.generation, layout_intent_id: Some(layout_intent_id), }); signal_camera_layout_admission(&mut admission_ready, admitted_starting_identity.clone()); PreviewCameraLayoutStart { status: match wait { PreviewCameraStartWait::Admitted => { // Dropping the handle detaches the supervisor; it keeps the // generation, the explicit-mutation lease and the source // transition guard until the camera is live or has failed. drop(completion); preview_camera_status(&state).await } PreviewCameraStartWait::Bounded => { wait_for_camera_transition_response(&state, completion, &lease).await } PreviewCameraStartWait::TransitionComplete => { wait_for_camera_transition_completion(&state, completion, &lease).await } }, admitted_starting_identity, } } fn signal_camera_layout_admission( admission_ready: &mut Option>>, identity: Option, ) { if let Some(admission_ready) = admission_ready.take() { let _ = admission_ready.send(identity); } } /// Synchronously transfers a registered generation into a persistent Tokio /// supervisor. There is intentionally no await between registration and this /// spawn: cancellation of the command waiter can never strand a Starting lease /// without an owner. fn queue_registered_preview_camera( state: AppState, prepared: PreparedCameraStart, explicit_mutation: Option, ) -> JoinHandle { let source_transition_guard = state.source_transition_fence.begin(); let panic_prepared = prepared.clone(); let panic_lease = prepared.lease.clone(); let transition_completion = PreviewCameraTransitionCompletionGuard::new(Arc::clone(&panic_lease.transition_completion)); let panic_status = failed_status( Some(prepared.camera_id.clone()), Some(prepared.device_unique_id.clone()), prepared.target_fps, "Native camera transition panicked after capture ownership was registered.".to_string(), ); let supervisor_state = state.clone(); state.spawn_process_task(async move { let _source_transition_guard = source_transition_guard; let _transition_completion = transition_completion; let transition = async { let transition_gate = { let slot = supervisor_state.preview_camera.lock().await; Arc::clone(&slot.transition_gate) }; let _transition = transition_gate.lock().await; if let Err(status) = ensure_registered_preview_camera_start_is_current(&supervisor_state, &prepared) .await { return *status; } publish_camera_start_admission(&supervisor_state, &prepared).await; if !camera_start_lease_is_current(&supervisor_state, &prepared.lease).await { return preview_camera_status(&supervisor_state).await; } start_registered_preview_camera(supervisor_state.clone(), prepared).await }; let status = match std::panic::AssertUnwindSafe(transition) .catch_unwind() .await { Ok(status) => status, Err(_) => { retire_panicked_camera_generation( &supervisor_state, &panic_lease, panic_status, Some(&panic_prepared), ) .await } }; if let Some(explicit_mutation) = explicit_mutation { finish_capture_recovery_explicit_camera_configuration_mutation( &supervisor_state, explicit_mutation, ) .await; } status }) } async fn ensure_registered_preview_camera_start_is_current( state: &AppState, prepared: &PreparedCameraStart, ) -> std::result::Result<(), Box> { if !prepared_camera_admission_is_current(state, prepared) { return Err(Box::new( retire_superseded_camera_start(state, prepared).await, )); } ensure_prepared_camera_layout_is_current(state, prepared).await } fn prepared_camera_admission_is_current(state: &AppState, prepared: &PreparedCameraStart) -> bool { !state.process_shutdown_requested() && prepared .recovery .as_ref() .is_none_or(|recovery| state.capture_recovery_admission_is_current(recovery.epoch)) } fn prepared_camera_layout_is_current_locked( state: &AppState, slot: &PreviewCameraRuntime, prepared: &PreparedCameraStart, ) -> bool { let Some(prepared_intent_id) = prepared.layout_intent_id else { return true; }; let latest_intent_id = state.latest_layout_intent_id(); prepared_intent_id == latest_intent_id || (slot.start_generation == prepared.lease.generation && slot.starting.as_ref() == Some(&prepared.lease.key) && slot.starting_layout_intent_id != Some(prepared_intent_id)) } async fn prepared_camera_layout_is_current( state: &AppState, prepared: &PreparedCameraStart, ) -> bool { let slot = state.preview_camera.lock().await; prepared_camera_layout_is_current_locked(state, &slot, prepared) } async fn ensure_prepared_camera_layout_is_current( state: &AppState, prepared: &PreparedCameraStart, ) -> std::result::Result<(), Box> { if prepared_camera_layout_is_current(state, prepared).await { return Ok(()); } let Some(layout_intent_id) = prepared.layout_intent_id else { return Ok(()); }; let expected = PreviewCameraStartingIdentity { source_key: prepared.lease.key.source_key.clone(), generation: prepared.lease.generation, layout_intent_id: Some(layout_intent_id), }; if let Some(stop) = begin_preview_camera_stop_if_starting(state, &expected).await { return Err(Box::new(stop.status)); } if prepared_camera_layout_is_current(state, prepared).await { Ok(()) } else { Err(Box::new(preview_camera_status(state).await)) } } fn camera_start_admission_is_current_locked( state: &AppState, slot: &PreviewCameraRuntime, lease: Option<&PreviewCameraStartLease>, recovery_epoch: Option, ) -> bool { !state.process_shutdown_requested() && recovery_epoch.is_none_or(|epoch| state.capture_recovery_admission_is_current(epoch)) && lease.is_none_or(|lease| { slot.start_generation == lease.generation && slot.pending_stop_generation.is_none() && slot.starting.as_ref() == Some(&lease.key) }) } fn claim_camera_start_if_admitted( state: &AppState, slot: &mut PreviewCameraRuntime, lease: &PreviewCameraStartLease, recovery_epoch: Option, ) -> bool { camera_start_admission_is_current_locked(state, slot, Some(lease), recovery_epoch) && claim_camera_start(slot, lease) } async fn retire_superseded_camera_recovery( state: &AppState, prepared: &PreparedCameraStart, ) -> PreviewCameraStatus { let Some(recovery) = prepared.recovery.as_ref() else { return camera_start_rejected_for_shutdown(preview_camera_status(state).await); }; let (status, lifecycle, release_source) = { let mut slot = state.preview_camera.lock().await; if slot.start_generation != prepared.lease.generation || slot.starting.as_ref() != Some(&prepared.lease.key) || slot.starting_recovery_epoch != Some(recovery.epoch) { return slot.status.clone(); } slot.starting = None; slot.starting_transition_completion = None; slot.starting_recovery_epoch = None; slot.starting_layout_intent_id = None; slot.failed_recovery_retry = None; if slot.active.is_some() { slot.status = recovery.previous_status.clone(); slot.run_id = recovery.previous_run_id.clone(); slot.live_acked_at = recovery.previous_live_acked_at; (slot.status.clone(), SourceLifecycleStatus::Live, false) } else if recovery.previous_status.state == PreviewCameraState::Failed { slot.status = recovery.previous_status.clone(); slot.run_id = None; slot.live_acked_at = None; (slot.status.clone(), SourceLifecycleStatus::Failed, false) } else { let status = idle_status(Some( "Camera recovery was superseded after the previous native session retired; no replacement was started." .to_string(), )); slot.status = status.clone(); slot.run_id = None; slot.source_key = None; slot.active_generation = None; slot.live_acked_at = None; (status, SourceLifecycleStatus::Stopped, true) } }; { let mut registry = state.source_registry.lock().await; if release_source { registry.release( &prepared.lease.key.source_key, &SourceConsumerReason::Preview, ); } registry.set_status(prepared.lease.key.source_key.clone(), lifecycle); } { let mut diagnostics = state.diagnostics.lock().await; *diagnostics = apply_preview_camera_source_stats(diagnostics.clone(), &status); } state.emit_event("preview.camera.status", status.clone()); status } async fn retire_superseded_camera_start( state: &AppState, prepared: &PreparedCameraStart, ) -> PreviewCameraStatus { if prepared.recovery.is_some() { return retire_superseded_camera_recovery(state, prepared).await; } if let Some(layout_intent_id) = prepared.layout_intent_id { let expected = PreviewCameraStartingIdentity { source_key: prepared.lease.key.source_key.clone(), generation: prepared.lease.generation, layout_intent_id: Some(layout_intent_id), }; if let Some(stop) = begin_preview_camera_stop_if_starting(state, &expected).await { // The current transition supervisor may own the physical gate. // Stop completion is independently process-owned and will run as // soon as that supervisor returns, so never wait here. return stop.status; } return preview_camera_status(state).await; } camera_start_rejected_for_shutdown(preview_camera_status(state).await) } async fn current_or_retire_superseded_camera_start( state: &AppState, prepared: &PreparedCameraStart, ) -> PreviewCameraStatus { if !prepared_camera_admission_is_current(state, prepared) { retire_superseded_camera_start(state, prepared).await } else if let Err(status) = ensure_prepared_camera_layout_is_current(state, prepared).await { *status } else { preview_camera_status(state).await } } async fn wait_for_camera_transition_response( state: &AppState, mut completion: JoinHandle, lease: &PreviewCameraStartLease, ) -> PreviewCameraStatus { match tokio::time::timeout(CAMERA_COMMAND_TRANSITION_TIMEOUT, &mut completion).await { Ok(Ok(status)) => status, Ok(Err(error)) => { tracing::error!( "Camera transition supervisor failed for generation {}: {error}", lease.generation ); preview_camera_status(state).await } Err(_) => delayed_camera_transition_status(state, lease).await, } } async fn wait_for_camera_transition_completion( state: &AppState, completion: JoinHandle, lease: &PreviewCameraStartLease, ) -> PreviewCameraStatus { match completion.await { Ok(status) => status, Err(error) => { tracing::error!( "Camera transition supervisor failed for fenced generation {}: {error}", lease.generation ); preview_camera_status(state).await } } } async fn start_registered_preview_camera( state: AppState, prepared: PreparedCameraStart, ) -> PreviewCameraStatus { if !prepared_camera_admission_is_current(&state, &prepared) { return retire_superseded_camera_start(&state, &prepared).await; } if let Err(status) = ensure_prepared_camera_layout_is_current(&state, &prepared).await { return *status; } let retirement_prepared = prepared.clone(); let PreparedCameraStart { camera_id, device_unique_id: unique_id, ffmpeg_path, target_fps, source_key, params, lease: start_lease, layout_intent_id: _, recovery: _, } = prepared; if !camera_start_lease_is_current(&state, &start_lease).await { return preview_camera_status(&state).await; } let recovery_epoch = retirement_prepared .recovery .as_ref() .map(|recovery| recovery.epoch); if !stop_current_camera_for_restart_if_admitted(&state, Some(&start_lease), recovery_epoch) .await { if !prepared_camera_admission_is_current(&state, &retirement_prepared) { return retire_superseded_camera_start(&state, &retirement_prepared).await; } if let Err(status) = ensure_prepared_camera_layout_is_current(&state, &retirement_prepared).await { return *status; } return preview_camera_status(&state).await; } // A stop or newer start can supersede this generation while the old // native session is synchronously stopping. Never create its replacement // unless the lease is still desired after the join completes. if !prepared_camera_admission_is_current(&state, &retirement_prepared) { return retire_superseded_camera_start(&state, &retirement_prepared).await; } if let Err(status) = ensure_prepared_camera_layout_is_current(&state, &retirement_prepared).await { return *status; } if !camera_start_lease_is_current(&state, &start_lease).await { return preview_camera_status(&state).await; } let run_id = Uuid::new_v4().to_string(); let surface_backing_tracker = state .preview_camera .lock() .await .surface_backing_tracker .clone(); let shared = Arc::new(StdMutex::new( PreviewCameraShared::with_surface_backing_tracker(surface_backing_tracker), )); let (stop_tx, stop_rx) = std_mpsc::channel(); let (startup_tx, startup_rx) = std_mpsc::channel(); let thread_shared = Arc::clone(&shared); // Issue #1066: the camera keeps its frame rate in low light unless the // user turned compensation on. Written beside the start, never before it. crate::camera_low_light::apply_stored_on_open(&state.database, &camera_id); let thread_config = NativeCameraPreviewConfig { camera_id: camera_id.clone(), unique_id: unique_id.clone(), ffmpeg_path: ffmpeg_path.clone(), video: params.video.clone(), layout: params.layout.clone(), // Plan 258 D12: Videorc's own background effect never runs on a // Windows camera until the Windows stage (S10), so Studio Effects is // only reported for now; S10 sets `turn_off_background_blur` while it // processes this camera. studio_effects: crate::camera_system_effect::StudioEffectsPolicy { turn_off_background_blur: false, restore_ledger: Some(state.database.clone()), }, }; // Acquire the runtime before spawning so there is no suspension point // between a successful native spawn and registration of its stop/join // ownership. Cancellation before this guard arrives creates no thread. let (mut ownership_slot, join_handle) = loop { let ownership_slot = state.preview_camera.lock().await; let layout_admission = state.lock_layout_source_admission(); let recovery_is_stale = recovery_epoch.is_some_and(|epoch| !state.capture_recovery_admission_is_current(epoch)); let physical_admission_is_current = camera_start_admission_is_current_locked( &state, &ownership_slot, Some(&start_lease), recovery_epoch, ); if !prepared_camera_admission_is_current(&state, &retirement_prepared) || !physical_admission_is_current { let status = ownership_slot.status.clone(); drop(ownership_slot); drop(layout_admission); if recovery_is_stale { return retire_superseded_camera_start(&state, &retirement_prepared).await; } return status; } if !prepared_camera_layout_is_current_locked(&state, &ownership_slot, &retirement_prepared) { drop(ownership_slot); drop(layout_admission); match ensure_prepared_camera_layout_is_current(&state, &retirement_prepared).await { Ok(()) => continue, Err(status) => return *status, } } let join_handle = thread::Builder::new() .name("videorc-preview-camera".to_string()) .spawn(move || { run_native_camera_preview(thread_config, thread_shared, stop_rx, startup_tx) }); drop(layout_admission); break (ownership_slot, join_handle); }; match join_handle { Ok(join_handle) => { ownership_slot.pending_native = Some(PendingNativeCameraThread { generation: start_lease.generation, stop_tx, join_handle: Some(join_handle), }); drop(ownership_slot); } Err(error) => { drop(ownership_slot); let status = failed_status( Some(camera_id), Some(unique_id), target_fps, format!("Could not start camera thread: {error}"), ); if set_camera_status_for_start(&state, &start_lease, recovery_epoch, status.clone()) .await { acquire_preview_camera_source(&state, source_key, SourceLifecycleStatus::Failed) .await; return status; } return current_or_retire_superseded_camera_start(&state, &retirement_prepared).await; } } let startup_camera = unique_id.clone(); let startup = tokio::task::spawn_blocking(move || { startup_rx .recv_timeout(native_camera_preview_thread_startup_timeout()) .unwrap_or_else(|error| native_camera_startup_unanswered(error, &startup_camera)) }) .await .unwrap_or_else(|error| { NativeCameraStartup::Failed(format!("Camera startup task failed: {error}")) }); match startup { NativeCameraStartup::Live { requested_width, requested_height, selected_format_width, selected_format_height, selected_format_min_fps, selected_format_max_fps, width, height, selected_fps, message, } => { let effective_fps = stable_effective_camera_fps(selected_fps, target_fps); let status = PreviewCameraStatus { state: PreviewCameraState::Live, camera_id: Some(camera_id.clone()), device_unique_id: Some(unique_id.clone()), target_fps, width: Some(width), height: Some(height), requested_width: Some(requested_width), requested_height: Some(requested_height), actual_width: None, actual_height: None, selected_format_width: Some(selected_format_width), selected_format_height: Some(selected_format_height), selected_format_min_fps: Some(selected_format_min_fps), selected_format_max_fps: Some(selected_format_max_fps), source_fps: Some(selected_fps), frame_age_ms: None, frames_captured: 0, dropped_frames: 0, sequence: None, updated_at: Utc::now().to_rfc3339(), message, no_video: None, system_effect: None, }; let capture_target = camera_capture_target_dimensions(¶ms.layout, ¶ms.video); let installed = { let mut slot = state.preview_camera.lock().await; let pending_matches = slot .pending_native .as_ref() .is_some_and(|pending| pending.generation == start_lease.generation); if !pending_matches || !claim_camera_start_if_admitted( &state, &mut slot, &start_lease, recovery_epoch, ) { false } else { let mut owned = slot .pending_native .take() .expect("matching pending camera owner"); slot.status = status.clone(); slot.run_id = Some(run_id.clone()); slot.source_key = Some(source_key.clone()); slot.active = Some(NativeCameraPreviewThread { stop_tx: owned.stop_tx, join_handle: owned.join_handle.take(), shared: Arc::clone(&shared), camera_id, device_unique_id: unique_id, ffmpeg_path, layout: params.layout, video: params.video, effective_fps, configured_output: (width, height), capture_target, }); slot.active_generation = Some(start_lease.generation); slot.failed_recovery_retry = None; slot.live_acked_at = Some(Instant::now()); true } }; if !installed { stop_pending_camera_generation(&state, start_lease.generation, "stale-start").await; return current_or_retire_superseded_camera_start(&state, &retirement_prepared) .await; } let poll_task = state.spawn_process_task(poll_camera_metrics( state.clone(), run_id.clone(), Arc::clone(&shared), effective_fps, )); { let mut slot = state.preview_camera.lock().await; if slot.run_id.as_deref() == Some(run_id.as_str()) { slot.poll_task = Some(poll_task); } else { poll_task.abort(); } } acquire_preview_camera_source(&state, source_key, SourceLifecycleStatus::Live).await; state.emit_event("preview.camera.status", status.clone()); status } NativeCameraStartup::PermissionNeeded(message) => { stop_pending_camera_generation(&state, start_lease.generation, "permission-needed") .await; let status = PreviewCameraStatus { state: PreviewCameraState::PermissionNeeded, camera_id: Some(camera_id), device_unique_id: Some(unique_id), target_fps, width: None, height: None, requested_width: None, requested_height: None, actual_width: None, actual_height: None, selected_format_width: None, selected_format_height: None, selected_format_min_fps: None, selected_format_max_fps: None, source_fps: None, frame_age_ms: None, frames_captured: 0, dropped_frames: 0, sequence: None, updated_at: Utc::now().to_rfc3339(), message: Some(message), no_video: None, system_effect: None, }; if set_camera_status_for_start(&state, &start_lease, recovery_epoch, status.clone()) .await { acquire_preview_camera_source( &state, source_key, SourceLifecycleStatus::PermissionNeeded, ) .await; status } else { current_or_retire_superseded_camera_start(&state, &retirement_prepared).await } } NativeCameraStartup::DeviceMissing(message) => { stop_pending_camera_generation(&state, start_lease.generation, "device-missing").await; let status = PreviewCameraStatus { state: PreviewCameraState::DeviceMissing, camera_id: Some(camera_id), device_unique_id: Some(unique_id), target_fps, width: None, height: None, requested_width: None, requested_height: None, actual_width: None, actual_height: None, selected_format_width: None, selected_format_height: None, selected_format_min_fps: None, selected_format_max_fps: None, source_fps: None, frame_age_ms: None, frames_captured: 0, dropped_frames: 0, sequence: None, updated_at: Utc::now().to_rfc3339(), message: Some(message), no_video: None, system_effect: None, }; if set_camera_status_for_start(&state, &start_lease, recovery_epoch, status.clone()) .await { acquire_preview_camera_source( &state, source_key, SourceLifecycleStatus::SourceMissing, ) .await; status } else { current_or_retire_superseded_camera_start(&state, &retirement_prepared).await } } NativeCameraStartup::Failed(message) => { stop_pending_camera_generation(&state, start_lease.generation, "failed-start").await; let status = failed_status(Some(camera_id), Some(unique_id), target_fps, message); if set_camera_status_for_start(&state, &start_lease, recovery_epoch, status.clone()) .await { acquire_preview_camera_source(&state, source_key, SourceLifecycleStatus::Failed) .await; status } else { current_or_retire_superseded_camera_start(&state, &retirement_prepared).await } } } } async fn stop_pending_camera_generation(state: &AppState, generation: u64, reason: &'static str) { let pending = { let mut slot = state.preview_camera.lock().await; if slot .pending_native .as_ref() .is_some_and(|pending| pending.generation == generation) { slot.pending_native.take() } else { None } }; if let Some(mut pending) = pending { let _ = pending.stop_tx.send(()); if let Some(join_handle) = pending.join_handle.take() { join_camera_capture_thread(join_handle, Some(generation), reason).await; } } } async fn retire_panicked_camera_generation( state: &AppState, lease: &PreviewCameraStartLease, failed: PreviewCameraStatus, prepared: Option<&PreparedCameraStart>, ) -> PreviewCameraStatus { let (pending, active, poll_task, terminal_candidate, owns_active, recovery_was_superseded) = { let mut slot = state.preview_camera.lock().await; // Explicit configuration invalidation shares this runtime lock. Check // the recovery epoch while holding it so the panic terminal cannot win // a TOCTOU race after an operator mutation has already been admitted. let recovery_was_superseded = prepared .and_then(|prepared| prepared.recovery.as_ref()) .is_some_and(|recovery| !state.capture_recovery_admission_is_current(recovery.epoch)); if recovery_was_superseded { (None, None, None, false, false, true) } else { // While this function runs the physical transition gate is still held. // Any registered pending owner, or any active owner, is therefore the // predecessor/current native session this panicked transition must // reconcile before a replacement is admitted physically. let pending = slot.pending_native.take(); let owns_active = slot.active_generation == Some(lease.generation); let active = slot.active.take(); let had_active = active.is_some(); if had_active { slot.active_generation = None; slot.run_id = None; slot.live_acked_at = None; } let terminal_candidate = slot.start_generation == lease.generation && slot.pending_stop_generation.is_none() && (slot.starting.as_ref() == Some(&lease.key) || owns_active); ( pending, active, if had_active { slot.poll_task.take() } else { None }, terminal_candidate, owns_active, false, ) } }; if recovery_was_superseded { stop_pending_camera_generation(state, lease.generation, "stale-recovery-panic").await; return retire_superseded_camera_recovery_after_panic( state, prepared.expect("superseded recovery panic retains its prepared admission"), lease, ) .await; } if let Some(poll_task) = poll_task { poll_task.abort(); } if let Some(mut pending) = pending { let pending_generation = pending.generation; let _ = pending.stop_tx.send(()); if let Some(join_handle) = pending.join_handle.take() { join_camera_capture_thread(join_handle, Some(pending_generation), "panic").await; } } if let Some(mut active) = active { let _ = active.stop_tx.send(()); if let Some(join_handle) = active.join_handle.take() { join_camera_capture_thread(join_handle, Some(lease.generation), "panic").await; } } // Native joins are intentionally unbounded. A newer operator start can be // admitted while this supervisor waits, so Failed is committed only after // teardown and only while the exact lease/admission still owns public truth. let mut slot = state.preview_camera.lock().await; if prepared .and_then(|prepared| prepared.recovery.as_ref()) .is_some_and(|recovery| !state.capture_recovery_admission_is_current(recovery.epoch)) { drop(slot); return retire_superseded_camera_recovery_after_panic( state, prepared.expect("superseded recovery panic retains its prepared admission"), lease, ) .await; } if !terminal_candidate || !panicked_camera_terminal_is_current_locked(state, &slot, lease, prepared, owns_active) { return slot.status.clone(); } // Start admission already establishes preview-camera -> registry order. // Hold the same authority through diagnostics/event publication so no // newer Starting state can be followed by this older Failed terminal. let mut registry = state.source_registry.lock().await; let mut diagnostics = state.diagnostics.lock().await; if !panicked_camera_terminal_is_current_locked(state, &slot, lease, prepared, owns_active) { return slot.status.clone(); } slot.starting = None; slot.starting_transition_completion = None; slot.starting_recovery_epoch = None; slot.starting_layout_intent_id = None; slot.source_key = Some(lease.key.source_key.clone()); slot.status = failed.clone(); registry.acquire(lease.key.source_key.clone(), SourceConsumerReason::Preview); registry.set_status(lease.key.source_key.clone(), SourceLifecycleStatus::Failed); *diagnostics = apply_preview_camera_source_stats(diagnostics.clone(), &failed); state.emit_event("preview.camera.status", failed.clone()); failed } fn panicked_camera_terminal_is_current_locked( state: &AppState, slot: &PreviewCameraRuntime, lease: &PreviewCameraStartLease, prepared: Option<&PreparedCameraStart>, owns_active: bool, ) -> bool { if state.process_shutdown_requested() || slot.start_generation != lease.generation || slot.pending_stop_generation.is_some() || slot.pending_native.is_some() || prepared .and_then(|prepared| prepared.recovery.as_ref()) .is_some_and(|recovery| !state.capture_recovery_admission_is_current(recovery.epoch)) { return false; } if slot.starting.as_ref() == Some(&lease.key) { return match prepared.and_then(|prepared| prepared.recovery.as_ref()) { Some(recovery) => slot.starting_recovery_epoch == Some(recovery.epoch), None => slot.starting_recovery_epoch.is_none(), }; } owns_active && slot.starting.is_none() && slot.source_key.as_ref() == Some(&lease.key.source_key) && slot.active.is_none() && slot.active_generation.is_none() } async fn retire_superseded_camera_recovery_after_panic( state: &AppState, prepared: &PreparedCameraStart, lease: &PreviewCameraStartLease, ) -> PreviewCameraStatus { let status = retire_superseded_camera_recovery(state, prepared).await; let mut slot = state.preview_camera.lock().await; let orphaned_installed_generation = slot.start_generation == lease.generation && slot.pending_stop_generation.is_none() && slot.starting.is_none() && slot.active.is_none() && slot.active_generation.is_none() && slot.source_key.as_ref() == Some(&lease.key.source_key); if !orphaned_installed_generation { return status; } let mut registry = state.source_registry.lock().await; let mut diagnostics = state.diagnostics.lock().await; if slot.start_generation != lease.generation || slot.pending_stop_generation.is_some() || slot.starting.is_some() || slot.active.is_some() || slot.active_generation.is_some() || slot.source_key.as_ref() != Some(&lease.key.source_key) { return slot.status.clone(); } let status = idle_status(Some( "Camera recovery was superseded after its panicked native generation retired.".to_string(), )); slot.status = status.clone(); slot.run_id = None; slot.source_key = None; slot.starting_recovery_epoch = None; slot.starting_layout_intent_id = None; slot.failed_recovery_retry = None; slot.live_acked_at = None; registry.release(&lease.key.source_key, &SourceConsumerReason::Preview); registry.set_status(lease.key.source_key.clone(), SourceLifecycleStatus::Stopped); *diagnostics = apply_preview_camera_source_stats(diagnostics.clone(), &status); state.emit_event("preview.camera.status", status.clone()); status } #[cfg(test)] async fn retire_uninstalled_camera_thread( mut stale_thread: NativeCameraPreviewThread, generation: u64, ) { let _ = stale_thread.stop_tx.send(()); if let Some(join_handle) = stale_thread.join_handle.take() { join_camera_capture_thread(join_handle, Some(generation), "stale-start").await; } } pub(crate) async fn preview_camera_restart_snapshot( state: &AppState, ) -> Option { let slot = state.preview_camera.lock().await; camera_restart_snapshot_from_slot(&slot) } /// True only when `expected` still names the exact stable Live generation and /// that generation has remained frameless past the existing startup grace. /// Health recovery uses this identity-bound query so a delayed sample from a /// retired source cannot make its replacement immediately restartable. pub(crate) async fn preview_camera_restart_snapshot_is_frameless_zombie( state: &AppState, expected: &PreviewCameraRestartSnapshot, ) -> bool { let slot = state.preview_camera.lock().await; camera_restart_snapshot_from_slot(&slot).as_ref() == Some(expected) && camera_slot_is_frameless_zombie(&slot) } /// Read recovery proof directly from the exact active capture generation. /// Diagnostics are intentionally bypassed because their asynchronously-updated /// counters may still describe the session that recovery just retired. pub(crate) async fn preview_camera_recovery_evidence( state: &AppState, expected: &PreviewCameraRestartSnapshot, ) -> Option { let ( shared, target_fps, requested_width, requested_height, configured_width, configured_height, ) = { let slot = state.preview_camera.lock().await; if camera_restart_snapshot_from_slot(&slot).as_ref() != Some(expected) { return None; } let active = slot.active.as_ref()?; ( Arc::clone(&active.shared), active.effective_fps, slot.status.requested_width, slot.status.requested_height, Some(active.configured_output.0), Some(active.configured_output.1), ) }; let ( source_fps, capture_callback_count, frame_store_publications, did_drop_callback_count, out_of_buffers, surface_backing_live_count, surface_backing_peak_count, latest_sequence, frame_age_ms, actual_width, actual_height, ) = { let shared = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); let latest = shared.frame_store.latest(); let frame_store_stats = shared.frame_store.stats(); ( shared.source_fps, shared.capture_callback_count, shared.frames_captured, shared.capture_drop_reasons.total(), shared.capture_drop_reasons.out_of_buffers, frame_store_stats.surface_backing_live_count, frame_store_stats.surface_backing_peak_count, latest.as_ref().map(|frame| frame.sequence), latest .as_ref() .map(|frame| frame.captured_at.elapsed().as_millis() as u64), latest.as_ref().map(|frame| frame.width), latest.as_ref().map(|frame| frame.height), ) }; { let slot = state.preview_camera.lock().await; if camera_restart_snapshot_from_slot(&slot).as_ref() != Some(expected) || !slot .active .as_ref() .is_some_and(|active| Arc::ptr_eq(&active.shared, &shared)) { return None; } } Some(PreviewCameraRecoveryEvidence { source_key: expected.source_key.clone(), generation: expected.generation, target_fps, source_fps, capture_callback_count, frame_store_publications, did_drop_callback_count, out_of_buffers, surface_backing_live_count, surface_backing_peak_count, latest_sequence, frame_age_ms, requested_width, requested_height, configured_width, configured_height, actual_width, actual_height, }) } /// Force-restart the exact camera session named by `expected`. /// /// The compare-and-swap happens before the old session is touched. A user /// source/config change or another restart therefore wins cleanly and makes /// this request a no-op instead of restarting the wrong device. #[cfg(test)] pub(crate) async fn force_restart_preview_camera( state: AppState, expected: &PreviewCameraRestartSnapshot, recovery_epoch: u64, ) -> PreviewCameraForceRestartResult { let Some(attempt) = admit_force_restart_preview_camera(&state, expected, recovery_epoch).await else { return PreviewCameraForceRestartResult::RejectedStale; }; complete_force_restart_preview_camera(&state, attempt).await } /// Compare-and-swap the exact Live camera generation and synchronously queue /// its process-lifetime transition supervisor. No native stop/start work is /// awaited here; callers that serialize admission with session startup must /// release that short-lived mutex before awaiting completion. pub(crate) async fn admit_force_restart_preview_camera( state: &AppState, expected: &PreviewCameraRestartSnapshot, recovery_epoch: u64, ) -> Option { if state.process_shutdown_requested() || !state.capture_recovery_admission_is_current(recovery_epoch) { return None; } let prepared = begin_forced_camera_restart(state, expected, recovery_epoch).await?; let generation = prepared.lease.generation; let source_key = prepared.lease.key.source_key.clone(); log_camera_generation( generation, "force-recovery", &prepared.lease.key, &prepared.params.layout, ); let completion = queue_registered_preview_camera(state.clone(), prepared, None); Some(PreviewCameraForceRestartAttempt { generation, source_key, completion, }) } /// Await the native transition of an already-admitted recovery generation. /// Dropping this future detaches only the waiter; the process-lifetime /// supervisor and its source-transition guard remain authoritative. pub(crate) async fn complete_force_restart_preview_camera( state: &AppState, attempt: PreviewCameraForceRestartAttempt, ) -> PreviewCameraForceRestartResult { let PreviewCameraForceRestartAttempt { generation, source_key, completion, } = attempt; // Awaiting the handle preserves the recovery API's exact result contract. // If its watchdog cancels this future, dropping the handle detaches only // the waiter; the transition supervisor and native ownership continue. let Ok(status) = completion.await else { return PreviewCameraForceRestartResult::RejectedStale; }; let restart_still_current = { let slot = state.preview_camera.lock().await; slot.start_generation == generation && slot.source_key.as_ref() == Some(&source_key) && slot.starting.is_none() }; if !restart_still_current { return PreviewCameraForceRestartResult::RejectedStale; } PreviewCameraForceRestartResult::Restarted { status, generation } } /// True only while `expected_generation` still names the untouched terminal /// failure produced by a recovery restart. This is the read-only half used to /// keep the externally reported `retryable` bit truthful; the retry operation /// repeats the same checks while holding the transition gate. pub(crate) async fn failed_preview_camera_retry_is_current( state: &AppState, expected_source_key: &SourceKey, expected_generation: u64, ) -> bool { let slot = state.preview_camera.lock().await; failed_camera_recovery_retry_from_slot(&slot, expected_source_key, expected_generation) .is_some() } /// Reserve and queue the exact retained failed-recovery configuration without /// awaiting native completion. This mirrors `admit_force_restart_preview_camera` /// for the one-click retry path. pub(crate) async fn admit_failed_preview_camera_recovery_retry( state: &AppState, expected_source_key: &SourceKey, expected_generation: u64, recovery_epoch: u64, ) -> Option { if state.process_shutdown_requested() || !state.capture_recovery_admission_is_current(recovery_epoch) { return None; } let prepared = begin_failed_camera_recovery_retry( state, expected_source_key, expected_generation, recovery_epoch, ) .await?; let generation = prepared.lease.generation; let source_key = prepared.lease.key.source_key.clone(); log_camera_generation( generation, "force-recovery-retry", &prepared.lease.key, &prepared.params.layout, ); let completion = queue_registered_preview_camera(state.clone(), prepared, None); Some(PreviewCameraForceRestartAttempt { generation, source_key, completion, }) } fn camera_restart_snapshot_from_slot( slot: &PreviewCameraRuntime, ) -> Option { if slot.status.state != PreviewCameraState::Live || slot.starting.is_some() || slot.pending_stop_generation.is_some() { return None; } let active = slot.active.as_ref()?; let generation = slot.active_generation?; let source_key = slot.source_key.clone()?; let camera_id = active.camera_id.clone(); if source_key != SourceKey::camera(camera_id.clone()) { return None; } let device_unique_id = active.device_unique_id.clone(); if slot.status.camera_id.as_ref() != Some(&camera_id) || slot.status.device_unique_id.as_ref() != Some(&device_unique_id) { return None; } let config = PreviewCameraRestartConfig { camera_id, device_unique_id, ffmpeg_path: active.ffmpeg_path.clone(), layout: active.layout.clone(), video: active.video.clone(), target_fps: slot.status.target_fps, }; let mut start_key = camera_restart_start_key(&source_key, &config); // Preserve the session's immutable start geometry even if later layout // bookkeeping changed presentation-only fields. start_key.capture_target = active.capture_target; Some(PreviewCameraRestartSnapshot { source_key, generation, config_fingerprint: camera_config_fingerprint(&start_key, &config.layout), config, }) } fn failed_camera_recovery_retry_from_slot<'a>( slot: &'a PreviewCameraRuntime, expected_source_key: &SourceKey, expected_generation: u64, ) -> Option<&'a PreviewCameraFailedRecoveryRetry> { let retry = slot.failed_recovery_retry.as_ref()?; if slot.status.state != PreviewCameraState::Failed || slot.active.is_some() || slot.active_generation.is_some() || slot.starting.is_some() || slot.pending_stop_generation.is_some() || slot.run_id.is_some() || slot.start_generation != expected_generation || retry.generation != expected_generation || &retry.source_key != expected_source_key || slot.source_key.as_ref() != Some(expected_source_key) || expected_source_key != &SourceKey::camera(retry.config.camera_id.clone()) || slot.status.camera_id.as_ref() != Some(&retry.config.camera_id) || slot.status.device_unique_id.as_ref() != Some(&retry.config.device_unique_id) || slot.status.target_fps != retry.config.target_fps || retry.config_fingerprint != camera_restart_config_fingerprint(&retry.source_key, &retry.config) { return None; } Some(retry) } async fn begin_forced_camera_restart( state: &AppState, expected: &PreviewCameraRestartSnapshot, recovery_epoch: u64, ) -> Option { let (prepared, starting) = { let mut slot = state.preview_camera.lock().await; if state.process_shutdown_requested() || !state.capture_recovery_admission_is_current(recovery_epoch) { return None; } if camera_restart_snapshot_from_slot(&slot).as_ref() != Some(expected) { return None; } let recovery = PreparedCameraRecoveryAdmission { epoch: recovery_epoch, previous_status: slot.status.clone(), previous_run_id: slot.run_id.clone(), previous_live_acked_at: slot.live_acked_at, }; let config = expected.config.clone(); let start_key = camera_restart_start_key(&expected.source_key, &config); { let mut registry = state.source_registry.lock().await; registry.acquire(expected.source_key.clone(), SourceConsumerReason::Preview); registry.set_status(expected.source_key.clone(), SourceLifecycleStatus::Starting); } slot.disconnected = None; slot.start_generation = slot.start_generation.wrapping_add(1).max(1); let lease = PreviewCameraStartLease::new(start_key.clone(), slot.start_generation); slot.starting_transition_completion = Some(Arc::clone(&lease.transition_completion)); slot.pending_stop_generation = None; slot.failed_recovery_retry = Some(PreviewCameraFailedRecoveryRetry { source_key: expected.source_key.clone(), generation: lease.generation, config_fingerprint: camera_config_fingerprint(&start_key, &config.layout), config: config.clone(), }); let starting = PreviewCameraStatus { state: PreviewCameraState::Starting, camera_id: Some(config.camera_id.clone()), device_unique_id: Some(config.device_unique_id.clone()), target_fps: config.target_fps, width: None, height: None, requested_width: None, requested_height: None, actual_width: None, actual_height: None, selected_format_width: None, selected_format_height: None, selected_format_min_fps: None, selected_format_max_fps: None, source_fps: None, frame_age_ms: None, frames_captured: 0, dropped_frames: 0, sequence: None, updated_at: Utc::now().to_rfc3339(), message: Some( "Restarting native camera capture after verified degradation.".to_string(), ), no_video: None, system_effect: None, }; slot.status = starting.clone(); slot.run_id = None; slot.source_key = Some(expected.source_key.clone()); slot.starting = Some(start_key); slot.starting_recovery_epoch = Some(recovery_epoch); slot.starting_layout_intent_id = None; let params = PreviewCameraStartParams { sources: SourceSelection { screen_id: None, window_id: None, camera_id: Some(config.camera_id.clone()), microphone_id: None, test_pattern: false, }, layout: config.layout, video: config.video, ffmpeg_path: Some(config.ffmpeg_path.clone()), }; ( PreparedCameraStart { camera_id: config.camera_id, device_unique_id: config.device_unique_id, ffmpeg_path: config.ffmpeg_path, target_fps: config.target_fps, source_key: expected.source_key.clone(), params, lease, layout_intent_id: None, recovery: Some(recovery), }, starting, ) }; // No await is allowed after the lease becomes visible: the caller queues // its persistent supervisor immediately after this function returns. state.emit_event("preview.camera.status", starting); Some(prepared) } async fn begin_failed_camera_recovery_retry( state: &AppState, expected_source_key: &SourceKey, expected_generation: u64, recovery_epoch: u64, ) -> Option { let (prepared, starting) = { let mut slot = state.preview_camera.lock().await; if state.process_shutdown_requested() || !state.capture_recovery_admission_is_current(recovery_epoch) { return None; } let config = failed_camera_recovery_retry_from_slot( &slot, expected_source_key, expected_generation, )? .config .clone(); let recovery = PreparedCameraRecoveryAdmission { epoch: recovery_epoch, previous_status: slot.status.clone(), previous_run_id: slot.run_id.clone(), previous_live_acked_at: slot.live_acked_at, }; let start_key = camera_restart_start_key(expected_source_key, &config); { let mut registry = state.source_registry.lock().await; registry.acquire(expected_source_key.clone(), SourceConsumerReason::Preview); registry.set_status(expected_source_key.clone(), SourceLifecycleStatus::Starting); } slot.disconnected = None; slot.start_generation = slot.start_generation.wrapping_add(1).max(1); let lease = PreviewCameraStartLease::new(start_key.clone(), slot.start_generation); slot.starting_transition_completion = Some(Arc::clone(&lease.transition_completion)); slot.pending_stop_generation = None; slot.failed_recovery_retry = Some(PreviewCameraFailedRecoveryRetry { source_key: expected_source_key.clone(), generation: lease.generation, config_fingerprint: camera_config_fingerprint(&start_key, &config.layout), config: config.clone(), }); let starting = PreviewCameraStatus { state: PreviewCameraState::Starting, camera_id: Some(config.camera_id.clone()), device_unique_id: Some(config.device_unique_id.clone()), target_fps: config.target_fps, width: None, height: None, requested_width: None, requested_height: None, actual_width: None, actual_height: None, selected_format_width: None, selected_format_height: None, selected_format_min_fps: None, selected_format_max_fps: None, source_fps: None, frame_age_ms: None, frames_captured: 0, dropped_frames: 0, sequence: None, updated_at: Utc::now().to_rfc3339(), message: Some("Retrying the failed native camera recovery generation.".to_string()), no_video: None, system_effect: None, }; slot.status = starting.clone(); slot.run_id = None; slot.source_key = Some(expected_source_key.clone()); slot.starting = Some(start_key); slot.starting_recovery_epoch = Some(recovery_epoch); slot.starting_layout_intent_id = None; let params = PreviewCameraStartParams { sources: SourceSelection { screen_id: None, window_id: None, camera_id: Some(config.camera_id.clone()), microphone_id: None, test_pattern: false, }, layout: config.layout, video: config.video, ffmpeg_path: Some(config.ffmpeg_path.clone()), }; ( PreparedCameraStart { camera_id: config.camera_id, device_unique_id: config.device_unique_id, ffmpeg_path: config.ffmpeg_path, target_fps: config.target_fps, source_key: expected_source_key.clone(), params, lease, layout_intent_id: None, recovery: Some(recovery), }, starting, ) }; state.emit_event("preview.camera.status", starting); Some(prepared) } pub async fn stop_preview_camera(state: &AppState) -> PreviewCameraStatus { let stop = begin_preview_camera_stop(state).await; finish_preview_camera_stop(stop).await } /// The status message when the renderer's stop is refused because a separate /// source take still records the camera. pub const CAMERA_STOP_REFUSED_BY_SOURCE_TAKE_MESSAGE: &str = "Camera kept running: the separate Camera file of the current take records it."; /// `preview.camera.stop` from a client. The renderer stops the preview camera /// whenever its own scene shows none (an app scene, screen-only), but a /// record+stream take armed with Separate source recordings and a camera /// composes that camera into its Camera file on every tick: the compositor's /// completed-batch store promotes a tick only when every live member rendered /// (`SourceIsoBatchStore::publish`), so a torn-down camera leaves the Combined /// recording, the Screen file and the Clips ring on their first frame for the /// whole take while the stream leg stays live (2026-11-03, smoke:smart-scenes /// `hide`). Layout transactions own source retirement during a take /// (`retire_unused_camera_after_grace` rechecks the take's demand); the /// client's stop honours the same demand and is refused while the take needs /// the camera. The status reports the refusal. pub async fn stop_preview_camera_from_client(state: &AppState) -> PreviewCameraStatus { if source_take_records_camera(state).await { let mut status = preview_camera_status(state).await; status.message = Some(CAMERA_STOP_REFUSED_BY_SOURCE_TAKE_MESSAGE.to_string()); return status; } stop_preview_camera(state).await } /// Plan 224 D6: the status message while the room holds the camera. pub const CAMERA_LENT_TO_TALK_SHOW_MESSAGE: &str = "Camera lent to the talk show. It comes back when the room closes."; /// Plan 224 D6: "Open the room" refused because a take still records the /// camera (the ISO-take trap, 2026-11-03). pub const CAMERA_LEND_REFUSED_BY_SOURCE_TAKE_MESSAGE: &str = "Camera kept running: the separate Camera file of the current take records it. Stop the take, then open the room."; pub const CAMERA_RETURNED_FROM_TALK_SHOW_MESSAGE: &str = "Camera returned by the talk show."; /// True while the talk show's room holds the camera. pub async fn camera_lent_to_talk_show(state: &AppState) -> bool { state.preview_camera.lock().await.lent_to_talk_show } /// "Open the room" (plan 224 D6): stop the preview camera with reason /// `talk-show` and refuse every start until `return_camera_from_talk_show`. /// Refused while a separate-source take records the camera, like the /// renderer's own stop: the Combined recording, the Screen file and the /// Clips ring would freeze on their first frame. pub async fn lend_camera_to_talk_show(state: &AppState) -> std::result::Result<(), String> { if source_take_records_camera(state).await { return Err(CAMERA_LEND_REFUSED_BY_SOURCE_TAKE_MESSAGE.to_string()); } { let mut slot = state.preview_camera.lock().await; if slot.lent_to_talk_show { return Ok(()); } slot.lent_to_talk_show = true; } let _ = stop_preview_camera(state).await; let status = { let mut slot = state.preview_camera.lock().await; slot.status.message = Some(CAMERA_LENT_TO_TALK_SHOW_MESSAGE.to_string()); slot.status.clone() }; state.emit_event("preview.camera.status", status); Ok(()) } /// The room closed (plan 224 D6): the preview camera may run again. The /// renderer restarts it for the scene that shows one; nothing starts here. pub async fn return_camera_from_talk_show(state: &AppState) { let status = { let mut slot = state.preview_camera.lock().await; if !slot.lent_to_talk_show { return; } slot.lent_to_talk_show = false; slot.status.message = Some(CAMERA_RETURNED_FROM_TALK_SHOW_MESSAGE.to_string()); slot.status.clone() }; state.emit_event("preview.camera.status", status); } /// True while the installed program scene names a camera that an armed /// separate source take still records (the Camera member is active). pub(crate) async fn source_take_records_camera(state: &AppState) -> bool { state .compositor .lock() .await .source_iso_capture_needs() .camera } pub(crate) async fn begin_preview_camera_stop(state: &AppState) -> PreviewCameraStop { try_begin_preview_camera_stop_supervised(state, false, None, None) .await .expect("unconditional camera stop admission") } /// Cancel only the exact generation sampled while it was pending startup. The /// identity CAS, Starting check, and desired-generation invalidation share the /// preview-runtime lock, so neither a native Live callback nor a newer camera /// start can be torn down by a stale layout-readiness sample. pub(crate) async fn begin_preview_camera_stop_if_starting( state: &AppState, expected: &PreviewCameraStartingIdentity, ) -> Option { try_begin_preview_camera_stop_supervised(state, false, Some(expected), None).await } fn camera_starting_identity_from_slot( slot: &PreviewCameraRuntime, ) -> Option { let starting = slot.starting.as_ref()?; (slot.status.state == PreviewCameraState::Starting && slot.pending_stop_generation.is_none()) .then(|| PreviewCameraStartingIdentity { source_key: starting.source_key.clone(), generation: slot.start_generation, layout_intent_id: slot.starting_layout_intent_id, }) } /// Return status and its pending-start identity from one runtime-lock sample. /// Keeping these together prevents timeout code from pairing an old status /// with a newer generation. #[cfg(test)] pub(crate) async fn preview_camera_status_and_starting_identity( state: &AppState, ) -> (PreviewCameraStatus, Option) { let slot = state.preview_camera.lock().await; ( slot.status.clone(), camera_starting_identity_from_slot(&slot), ) } /// Legacy test seam for proving physical exclusivity. Production callers must /// not wait for this gate before registering intent: stop/start supersession is /// admitted under the runtime lock and the persistent supervisor waits here. #[cfg(test)] pub(crate) async fn acquire_preview_camera_transition( state: &AppState, ) -> PreviewCameraTransitionGuard { let transition_gate = { let slot = state.preview_camera.lock().await; Arc::clone(&slot.transition_gate) }; transition_gate.lock_owned().await } /// Release only an abandoned, already-live source generation. A replacement /// owner can never be stopped by a late transaction cleanup. pub(crate) async fn stop_abandoned_camera_generation( state: &AppState, expected: &(SourceKey, u64), ) -> Option { try_begin_preview_camera_stop_supervised(state, false, None, Some(expected)).await } async fn try_begin_preview_camera_stop_supervised( state: &AppState, force_shutdown: bool, expected_starting: Option<&PreviewCameraStartingIdentity>, expected_active: Option<&(SourceKey, u64)>, ) -> Option { let (status, generation, poll_task, explicit_mutation) = { // Same preview-runtime -> source-registry order as start admission. // No mutation precedes the registry await, and there is no suspension // between consumer release and desired-generation invalidation. let mut slot = state.preview_camera.lock().await; if expected_active .is_some_and(|expected| source_identity_locked(&slot).as_ref() != Some(expected)) { return None; } if let Some(expected) = expected_starting && camera_starting_identity_from_slot(&slot).as_ref() != Some(expected) { return None; } let explicit_mutation = (!force_shutdown).then(|| state.begin_capture_recovery_explicit_camera_mutation()); let keep_alive = if let Some(source_key) = slot.source_key.as_ref() { let snapshot = state .source_registry .lock() .await .release(source_key, &SourceConsumerReason::Preview); !force_shutdown && snapshot .entries .iter() .find(|entry| &entry.key == source_key) .is_some_and(|entry| !entry.consumers.is_empty()) } else { false }; slot.failed_recovery_retry = None; if keep_alive { let mut status = slot.status.clone(); status.updated_at = Utc::now().to_rfc3339(); status.message = Some("Preview consumer released; camera source is still in use.".to_string()); slot.status = status.clone(); slot.starting = None; slot.starting_transition_completion = None; slot.starting_recovery_epoch = None; slot.starting_layout_intent_id = None; (status, None, None, explicit_mutation) } else { slot.disconnected = None; slot.start_generation = slot.start_generation.wrapping_add(1).max(1); let generation = slot.start_generation; slot.pending_stop_generation = Some(generation); let status = idle_status(Some( "Stopping native camera preview; teardown remains exclusively owned.".to_string(), )); slot.status = status.clone(); slot.run_id = None; slot.source_key = None; slot.starting = None; slot.starting_transition_completion = None; slot.starting_recovery_epoch = None; slot.starting_layout_intent_id = None; let poll_task = slot.poll_task.take(); (status, Some(generation), poll_task, explicit_mutation) } }; if let Some(task) = poll_task { task.abort(); } state.emit_event("preview.camera.status", status.clone()); let completion = if let Some(generation) = generation { let source_transition_guard = state.source_transition_fence.begin(); let supervisor_state = state.clone(); let admitted_status = status.clone(); // Spawn is synchronous and immediately follows admission. Dropping the // returned wait handle never cancels this process-lifetime physical // owner, even when admission originated on a disposable compositor // runtime. Some(state.spawn_process_task(async move { let _source_transition_guard = source_transition_guard; let status = run_camera_stop_supervisor(supervisor_state.clone(), generation, admitted_status) .await; if let Some(explicit_mutation) = explicit_mutation { finish_capture_recovery_explicit_camera_configuration_mutation( &supervisor_state, explicit_mutation, ) .await; } status })) } else { if let Some(explicit_mutation) = explicit_mutation { finish_capture_recovery_explicit_camera_configuration_mutation( state, explicit_mutation, ) .await; } None }; Some(PreviewCameraStop { status, completion }) } async fn run_camera_stop_supervisor( state: AppState, generation: u64, admitted_status: PreviewCameraStatus, ) -> PreviewCameraStatus { { let mut diagnostics = state.diagnostics.lock().await; *diagnostics = apply_preview_camera_source_stats(diagnostics.clone(), &admitted_status); } let transition_gate = { let slot = state.preview_camera.lock().await; Arc::clone(&slot.transition_gate) }; let _transition = transition_gate.lock().await; let (previous, active_generation) = { let mut slot = state.preview_camera.lock().await; if slot.start_generation != generation || slot.pending_stop_generation != Some(generation) { return slot.status.clone(); } let active_generation = slot.active_generation.take(); slot.live_acked_at = None; (slot.active.take(), active_generation) }; if let Some(mut previous) = previous { let _ = previous.stop_tx.send(()); if let Some(join_handle) = previous.join_handle.take() { join_camera_capture_thread(join_handle, active_generation, "stop").await; } } let status = { let mut slot = state.preview_camera.lock().await; if slot.start_generation != generation || slot.pending_stop_generation != Some(generation) { return slot.status.clone(); } slot.pending_stop_generation = None; if slot.status == admitted_status { let status = idle_status(Some("Native camera preview stopped.".to_string())); slot.status = status.clone(); status } else { // A later explicit selection error may have replaced the admitted // stopping copy while physical teardown was in flight. Preserve // that newer public status; only native ownership is finalized. slot.status.clone() } }; { let mut diagnostics = state.diagnostics.lock().await; *diagnostics = apply_preview_camera_source_stats(diagnostics.clone(), &status); } state.emit_event("preview.camera.status", status.clone()); status } pub(crate) async fn finish_preview_camera_stop(stop: PreviewCameraStop) -> PreviewCameraStatus { finish_preview_camera_stop_with_timeout(stop, CAMERA_STOP_RESPONSE_TIMEOUT).await } /// Graceful application shutdown must request native release and wait for the /// supervised join, even if another logical consumer was still registered. /// The wait remains bounded; on an unusually slow driver teardown the detached /// supervisor retains the physical owner while the process shutdown continues. pub(crate) async fn shutdown_preview_camera(state: &AppState) -> bool { shutdown_preview_camera_with_timeout(state, CAMERA_STOP_RESPONSE_TIMEOUT).await } async fn shutdown_preview_camera_with_timeout(state: &AppState, timeout: Duration) -> bool { let mut stop = try_begin_preview_camera_stop_supervised(state, true, None, None) .await .expect("unconditional camera shutdown admission"); let Some(mut completion) = stop.completion.take() else { return true; }; matches!( tokio::time::timeout(timeout, &mut completion).await, Ok(Ok(_)) ) } async fn finish_preview_camera_stop_with_timeout( mut stop: PreviewCameraStop, response_timeout: Duration, ) -> PreviewCameraStatus { let Some(mut completion) = stop.completion.take() else { return stop.status; }; match tokio::time::timeout(response_timeout, &mut completion).await { Ok(Ok(status)) => status, Ok(Err(error)) => { tracing::error!("Camera stop supervisor failed: {error}"); stop.status } Err(_) => stop.status, } } // Disconnects retain the native owner and its frame store. Reconnect admission // compares the saved generation under the same lock as ordinary start/stop. pub(crate) async fn camera_connection_changed( state: &AppState, event: &crate::device_watch::CameraConnectionEvent, ) { let mut slot = state.preview_camera.lock().await; if slot.status.device_unique_id.as_deref() != Some(&event.unique_id) || slot.starting.is_some() || slot.pending_stop_generation.is_some() || state.process_shutdown_requested() { return; } if !event.connected { let Some(snapshot) = camera_restart_snapshot_from_slot(&slot) else { return; }; let mutation = state.begin_capture_recovery_explicit_camera_mutation(); slot.disconnected = Some(snapshot); slot.status.state = PreviewCameraState::Disconnected; slot.status.message = Some(format!("{} disconnected", event.name)); slot.status.updated_at = Utc::now().to_rfc3339(); let status = slot.status.clone(); drop(slot); state.emit_event("preview.camera.status", status); finish_capture_recovery_explicit_camera_configuration_mutation(state, mutation).await; return; } let Some((prepared, mutation)) = prepare_camera_reconnect(state, &mut slot, event) else { return; }; let status = slot.status.clone(); drop(slot); state.emit_event("preview.camera.status", status); queue_registered_preview_camera(state.clone(), prepared, Some(mutation)); } fn prepare_camera_reconnect( state: &AppState, slot: &mut PreviewCameraRuntime, event: &crate::device_watch::CameraConnectionEvent, ) -> Option<( PreparedCameraStart, CaptureRecoveryExplicitCameraMutationLease, )> { if !event.connected || slot.status.device_unique_id.as_deref() != Some(event.unique_id.as_str()) { return None; } let expected = slot.disconnected.take()?; if slot.active_generation != Some(expected.generation) || slot.source_key.as_ref() != Some(&expected.source_key) || slot.status.state != PreviewCameraState::Disconnected { return None; } let mutation = state.begin_capture_recovery_explicit_camera_mutation(); let config = expected.config; let mut key = camera_restart_start_key(&expected.source_key, &config); key.capture_target = slot.active.as_ref().unwrap().capture_target; slot.disconnected = None; slot.start_generation = slot.start_generation.wrapping_add(1).max(1); let lease = PreviewCameraStartLease::new(key.clone(), slot.start_generation); slot.starting_transition_completion = Some(Arc::clone(&lease.transition_completion)); slot.status.state = PreviewCameraState::Starting; slot.status.message = Some(format!("Reconnecting {}", event.name)); slot.run_id = None; slot.starting = Some(key); slot.starting_recovery_epoch = None; slot.starting_layout_intent_id = None; slot.failed_recovery_retry = None; let prepared = PreparedCameraStart { camera_id: config.camera_id.clone(), device_unique_id: config.device_unique_id, ffmpeg_path: config.ffmpeg_path.clone(), target_fps: config.target_fps, source_key: expected.source_key, params: PreviewCameraStartParams { sources: SourceSelection { camera_id: Some(config.camera_id), screen_id: None, window_id: None, microphone_id: None, test_pattern: false, }, layout: config.layout, video: config.video, ffmpeg_path: Some(config.ffmpeg_path), }, lease, layout_intent_id: None, recovery: None, }; Some((prepared, mutation)) } pub async fn preview_camera_status(state: &AppState) -> PreviewCameraStatus { state.preview_camera.lock().await.status.clone() } pub async fn preview_camera_frame_store_stats(state: &AppState) -> FrameStoreStats { let shared = { let slot = state.preview_camera.lock().await; let Some(active) = slot.active.as_ref() else { return FrameStoreStats::from_surface_backing(slot.surface_backing_tracker.snapshot()); }; Arc::clone(&active.shared) }; shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) .frame_store .stats() } pub async fn preview_camera_latest_frame_info(state: &AppState) -> Option { let shared = { let slot = state.preview_camera.lock().await; Arc::clone(&slot.active.as_ref()?.shared) }; let frame = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) .frame_store .latest()?; Some(PreviewCameraFrameInfo { sequence: frame.sequence, width: frame.width, height: frame.height, frame_age_ms: frame.captured_at.elapsed().as_millis() as u64, }) } pub(crate) fn source_identity_locked(slot: &PreviewCameraRuntime) -> Option<(SourceKey, u64)> { slot.active.as_ref()?; Some((slot.source_key.clone()?, slot.active_generation?)) } #[cfg(any(target_os = "windows", test))] pub(crate) fn available_frame_source_locked( slot: &PreviewCameraRuntime, ) -> Option { (slot.status.state == PreviewCameraState::Live) .then(|| frame_source_locked(slot)) .flatten() } pub(crate) fn frame_source_locked(slot: &PreviewCameraRuntime) -> Option { let active = slot.active.as_ref()?; let generation = slot.active_generation?; Some(PreviewCameraFrameSource { shared: Arc::clone(&active.shared), layout: active.layout.clone(), // Admission can name replacement B while active A still owns this // store/generation. Frames retain A's immutable canonical identity; // a missing desired key still makes explicit stop admission keyless. source_key: slot .source_key .as_ref() .map(|_| SourceKey::camera(active.camera_id.clone())), target_fps: active.effective_fps, generation, }) } pub async fn preview_camera_frame_source(state: &AppState) -> Option { frame_source_locked(&*state.preview_camera.lock().await) } pub fn try_preview_camera_frame_source( state: &AppState, ) -> Result, ()> { let slot = state.preview_camera.try_lock().map_err(|_| ())?; Ok(frame_source_locked(&slot)) } /// Rolling camera cadence evidence read straight from the active capture /// session (instant-record P3). The record start used to wipe this window and /// then wait on the 250 ms diagnostics ticker to refill it; reading it directly /// gives an instant verdict on a camera that has been delivering steadily. #[derive(Debug, Clone, Copy, PartialEq)] pub struct CameraCadenceEvidence { pub sample_pts_gap_p95_ms: Option, pub callback_gap_p95_ms: Option, pub frame_age_ms: Option, pub source_fps: Option, pub gap_sample_count: usize, } pub async fn preview_camera_cadence_evidence(state: &AppState) -> Option { let shared = { let slot = state.preview_camera.lock().await; slot.active .as_ref() .map(|active| Arc::clone(&active.shared)) }?; let guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); let timings = guard.capture_timings.snapshot(); let frame_age_ms = guard .frame_store .latest() .map(|frame| frame.captured_at.elapsed().as_millis() as u64); Some(CameraCadenceEvidence { sample_pts_gap_p95_ms: timings.sample_pts_gap_p95_ms, callback_gap_p95_ms: timings.capture_gap_p95_ms, frame_age_ms, source_fps: guard.source_fps, gap_sample_count: guard.capture_timings.gap_sample_count(), }) } pub async fn reset_preview_camera_capture_timings(state: &AppState) { let shared = { let slot = state.preview_camera.lock().await; slot.active .as_ref() .map(|active| Arc::clone(&active.shared)) }; if let Some(shared) = shared { let mut guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); guard.capture_timings.reset(); } } pub async fn latest_preview_camera_png( state: &AppState, requested_max_width: Option, ) -> Option> { let (frame, layout) = { let slot = state.preview_camera.lock().await; let active = slot.active.as_ref()?; let shared = Arc::clone(&active.shared); let layout = active.layout.clone(); drop(slot); let guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); (guard.frame_store.latest()?, layout) }; let max_width = preview_camera_png_max_width(requested_max_width); tokio::task::spawn_blocking(move || encode_preview_camera_png(frame, layout, max_width)) .await .ok() .flatten() } /// Latest-wins BGRA/BMP transport used by the production Windows proof /// surface. Unlike the debug PNG route this performs no compression and /// preserves the capture frame sequence for duplicate suppression. pub async fn latest_preview_camera_bmp( state: &AppState, requested_max_width: Option, cursor: Option, ) -> Option { let (generation, frame) = { let slot = state.preview_camera.lock().await; let active = slot.active.as_ref()?; let generation = slot.run_id.clone()?; let shared = Arc::clone(&active.shared); drop(slot); let guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); (generation, guard.frame_store.latest()?) }; let max_width = preview_camera_png_max_width(requested_max_width); tokio::task::spawn_blocking(move || { encode_latest_bgra_bmp( cursor.as_ref(), generation, frame.sequence, frame.width, frame.height, &frame.bytes, max_width, ) }) .await .ok() .flatten() } fn encode_preview_camera_png( frame: FrameHandle, layout: LayoutSettings, max_width: u32, ) -> Option> { let expected_len = frame.width as usize * frame.height as usize * 4; if frame.bytes.len() < expected_len { return None; } let mut rgba = Vec::with_capacity(frame.bytes.len()); for pixel in frame.bytes.as_chunks::<4>().0 { rgba.extend_from_slice(&[pixel[2], pixel[1], pixel[0], pixel[3]]); } if layout.camera_mirror { mirror_rgba_in_place(&mut rgba, frame.width as usize, frame.height as usize); } let (rgba, width, height) = downscale_rgba_for_preview(rgba, frame.width, frame.height, max_width); let mut png = Vec::new(); let encoder = PngEncoder::new(&mut png); encoder .write_image(&rgba, width, height, image::ExtendedColorType::Rgba8) .ok()?; Some(png) } async fn refresh_camera_capability_diagnostics(state: &AppState, camera_id: Option) { let (formats, error) = match camera_id.as_deref() { Some(camera_id) => match camera_capability_matrix_for_id(camera_id) { Ok(formats) => ( formats .into_iter() .map(camera_capability_format_for_protocol) .collect(), None, ), Err(error) => (Vec::new(), Some(error)), }, None => (Vec::new(), None), }; let mut diagnostics = state.diagnostics.lock().await; *diagnostics = apply_preview_camera_capability_stats(diagnostics.clone(), camera_id, formats, error); } fn camera_capability_format_for_protocol(format: CameraFormatSummary) -> CameraCapabilityFormat { CameraCapabilityFormat { width: format.width, height: format.height, min_fps: format.min_fps, max_fps: format.max_fps, } } fn preview_camera_png_max_width(requested_max_width: Option) -> u32 { requested_max_width .unwrap_or(PREVIEW_CAMERA_DEFAULT_PNG_WIDTH) .clamp(1, PREVIEW_CAMERA_MAX_PNG_WIDTH) } async fn set_camera_status(state: &AppState, status: PreviewCameraStatus) { { let mut slot = state.preview_camera.lock().await; slot.status = status.clone(); slot.run_id = None; slot.source_key = status.camera_id.clone().map(SourceKey::camera); slot.starting = None; slot.starting_transition_completion = None; slot.starting_recovery_epoch = None; slot.starting_layout_intent_id = None; slot.failed_recovery_retry = None; if slot.active.is_none() { slot.active_generation = None; } } { let mut diagnostics = state.diagnostics.lock().await; *diagnostics = apply_preview_camera_source_stats(diagnostics.clone(), &status); } state.emit_event("preview.camera.status", status); } #[cfg(test)] async fn stop_current_camera_for_restart(state: &AppState) { let _ = stop_current_camera_for_restart_if_admitted(state, None, None).await; } async fn stop_current_camera_for_restart_if_admitted( state: &AppState, lease: Option<&PreviewCameraStartLease>, recovery_epoch: Option, ) -> bool { let (previous, poll_task, generation) = { let mut slot = state.preview_camera.lock().await; if !camera_start_admission_is_current_locked(state, &slot, lease, recovery_epoch) { return false; } let generation = slot.active_generation; slot.run_id = None; slot.active_generation = None; slot.live_acked_at = None; (slot.active.take(), slot.poll_task.take(), generation) }; if let Some(task) = poll_task { task.abort(); } if let Some(mut previous) = previous { let _ = previous.stop_tx.send(()); if let Some(join_handle) = previous.join_handle.take() { join_camera_capture_thread(join_handle, generation, "restart").await; } } true } async fn join_camera_capture_thread( join_handle: thread::JoinHandle<()>, generation: Option, reason: &'static str, ) { let started_at = Instant::now(); // AVCaptureSession::stopRunning is synchronous and exposes no independent // cancellation handle. A Tokio timeout would only abandon this join while // the native session kept the device; starting its replacement then would // overlap exclusive capture sessions. Preserve the no-overlap invariant and // make any over-target Apple stop explicit in diagnostics instead. let _ = tokio::task::spawn_blocking(move || join_handle.join()).await; let elapsed_ms = started_at.elapsed().as_millis() as u64; if elapsed_ms > 2_000 { tracing::warn!( "[capture-generation] source=camera generation={} reason={} stop_join_ms={} target_ms=2000 bounded=false", generation.unwrap_or_default(), reason, elapsed_ms, ); } else { tracing::info!( "[capture-generation] source=camera generation={} reason={} stop_join_ms={}", generation.unwrap_or_default(), reason, elapsed_ms, ); } } async fn begin_camera_start( state: &AppState, start_key: PreviewCameraStartKey, layout: &LayoutSettings, status: PreviewCameraStatus, layout_intent_id: Option, ) -> PreviewCameraStartRegistration { // Lock-order invariant for atomic admission: a preview runtime may acquire // the source registry, but code holding the source registry must never wait // for a preview runtime. Cancellation while this function waits for the // registry therefore happens before any observable admission mutation. let mut slot = state.preview_camera.lock().await; if state.process_shutdown_requested() { return PreviewCameraStartRegistration::RejectedShutdown( camera_start_rejected_for_shutdown(slot.status.clone()), ); } { let _layout_admission = state.lock_layout_source_admission(); if layout_intent_id.is_some_and(|intent_id| intent_id < state.latest_layout_intent_id()) { return PreviewCameraStartRegistration::RejectedSuperseded(slot.status.clone()); } if slot.starting.as_ref() == Some(&start_key) && slot.starting_recovery_epoch.is_none() { let transition_completion = Arc::clone( slot.starting_transition_completion .as_ref() .expect("Starting camera generation must retain its transition completion"), ); let admitted_starting_identity = match (slot.starting_layout_intent_id, layout_intent_id) { // A newer layout joining an older layout-owned generation becomes // its sole timeout owner. The stale intent's token stops matching. (Some(current_owner), Some(intent_id)) if intent_id >= current_owner => { slot.starting_layout_intent_id = Some(intent_id); Some(PreviewCameraStartingIdentity { source_key: start_key.source_key.clone(), generation: slot.start_generation, layout_intent_id: Some(intent_id), }) } // A superseded layout task can reach admission after the winning // task because both transition supervisors are detached. Never // transfer authority backward to that stale intent. (Some(_), Some(_)) => None, // A public camera command takes durable ownership from any layout // warm-up. No layout timeout may cancel it afterward. (Some(_), None) => { slot.starting_layout_intent_id = None; None } // A layout may observe a matching public-owned warm-up, but it // does not acquire cancellation authority over that command. (None, Some(_)) | (None, None) => None, }; return PreviewCameraStartRegistration::JoinExisting { admitted_starting_identity, transition_completion, }; } } let can_reuse = slot.pending_stop_generation.is_none() && slot.starting.is_none() && slot.status.state == PreviewCameraState::Live && slot.source_key.as_ref() == Some(&start_key.source_key) && !camera_slot_is_frameless_zombie(&slot) && slot.active.as_ref().is_some_and(|active| { active.ffmpeg_path == start_key.ffmpeg_path && active.video == start_key.video && slot.status.target_fps == start_key.target_fps && active.capture_target == start_key.capture_target }); if can_reuse { // Reacquiring the preview consumer and committing reuse happen under // the same fast admission authority. A concurrent stop/new start // cannot invalidate the active generation between the check and the // Live result returned to this caller. let mut registry = state.source_registry.lock().await; let _layout_admission = state.lock_layout_source_admission(); if layout_intent_id.is_some_and(|intent_id| intent_id < state.latest_layout_intent_id()) { return PreviewCameraStartRegistration::RejectedSuperseded(slot.status.clone()); } registry.acquire(start_key.source_key.clone(), SourceConsumerReason::Preview); registry.set_status(start_key.source_key.clone(), SourceLifecycleStatus::Live); if let Some(active) = slot.active.as_mut() { active.layout = layout.clone(); } let mut reused = slot.status.clone(); reused.updated_at = Utc::now().to_rfc3339(); reused.message = Some("Native camera preview source reused.".to_string()); slot.status = reused.clone(); log_camera_generation( slot.active_generation.unwrap_or(slot.start_generation), "reuse", &start_key, layout, ); drop(slot); state.emit_event("preview.camera.status", reused.clone()); return PreviewCameraStartRegistration::Reused(reused); } let previous_source_key = slot.source_key.clone(); let mut registry = state.source_registry.lock().await; let _layout_admission = state.lock_layout_source_admission(); if layout_intent_id.is_some_and(|intent_id| intent_id < state.latest_layout_intent_id()) { return PreviewCameraStartRegistration::RejectedSuperseded(slot.status.clone()); } if let Some(previous_source_key) = previous_source_key.as_ref() && previous_source_key != &start_key.source_key { registry.release(previous_source_key, &SourceConsumerReason::Preview); } registry.acquire(start_key.source_key.clone(), SourceConsumerReason::Preview); registry.set_status( start_key.source_key.clone(), SourceLifecycleStatus::Starting, ); slot.failed_recovery_retry = None; slot.disconnected = None; slot.start_generation = slot.start_generation.wrapping_add(1).max(1); slot.pending_stop_generation = None; let lease = PreviewCameraStartLease::new(start_key.clone(), slot.start_generation); slot.starting_transition_completion = Some(Arc::clone(&lease.transition_completion)); slot.status = status.clone(); slot.run_id = None; slot.source_key = Some(start_key.source_key.clone()); slot.starting = Some(start_key); slot.starting_recovery_epoch = None; slot.starting_layout_intent_id = layout_intent_id; drop(registry); drop(_layout_admission); drop(slot); // Emission is synchronous, so registration is followed by an immediate // return to the caller, which queues the persistent supervisor without a // cancellation point. state.emit_event("preview.camera.status", status); PreviewCameraStartRegistration::Started { lease } } async fn camera_start_lease_is_current(state: &AppState, lease: &PreviewCameraStartLease) -> bool { let slot = state.preview_camera.lock().await; slot.start_generation == lease.generation && slot.pending_stop_generation.is_none() && slot.starting.as_ref() == Some(&lease.key) } async fn publish_camera_start_admission(state: &AppState, prepared: &PreparedCameraStart) { if !camera_start_lease_is_current(state, &prepared.lease).await { return; } let status = { let slot = state.preview_camera.lock().await; if slot.start_generation != prepared.lease.generation || slot.starting.as_ref() != Some(&prepared.lease.key) { return; } slot.status.clone() }; let mut diagnostics = state.diagnostics.lock().await; *diagnostics = apply_preview_camera_source_stats(diagnostics.clone(), &status); } async fn delayed_camera_transition_status( state: &AppState, lease: &PreviewCameraStartLease, ) -> PreviewCameraStatus { let status = { let mut slot = state.preview_camera.lock().await; if slot.start_generation == lease.generation && slot.starting.as_ref() == Some(&lease.key) { slot.status.updated_at = Utc::now().to_rfc3339(); slot.status.message = Some( "Camera is still starting; its status updates when the native session goes live or fails, without overlapping capture." .to_string(), ); } slot.status.clone() }; state.emit_event("preview.camera.status", status.clone()); status } fn claim_camera_start(slot: &mut PreviewCameraRuntime, lease: &PreviewCameraStartLease) -> bool { if slot.start_generation != lease.generation || slot.pending_stop_generation.is_some() || slot.starting.as_ref() != Some(&lease.key) { return false; } slot.starting = None; slot.starting_transition_completion = None; slot.starting_recovery_epoch = None; slot.starting_layout_intent_id = None; true } async fn wait_for_camera_start( state: &AppState, start_key: &PreviewCameraStartKey, ) -> PreviewCameraStatus { // A join replies inside the same command budget as the owning start. let timeout = CAMERA_COMMAND_TRANSITION_TIMEOUT; let started_at = Instant::now(); loop { let (still_starting, status) = { let slot = state.preview_camera.lock().await; ( slot.starting.as_ref() == Some(start_key) && matches!(slot.status.state, PreviewCameraState::Starting), slot.status.clone(), ) }; if !still_starting || started_at.elapsed() >= timeout { return status; } tokio::time::sleep(Duration::from_millis(100)).await; } } async fn set_camera_status_for_start( state: &AppState, lease: &PreviewCameraStartLease, recovery_epoch: Option, status: PreviewCameraStatus, ) -> bool { let source_key = status.camera_id.clone().map(SourceKey::camera); { let mut slot = state.preview_camera.lock().await; if !claim_camera_start_if_admitted(state, &mut slot, lease, recovery_epoch) { return false; } slot.status = status.clone(); slot.run_id = None; slot.source_key = source_key; if status.state != PreviewCameraState::Failed { slot.failed_recovery_retry = None; } if slot.active.is_none() { slot.active_generation = None; } } { let mut diagnostics = state.diagnostics.lock().await; *diagnostics = apply_preview_camera_source_stats(diagnostics.clone(), &status); } state.emit_event("preview.camera.status", status); true } #[cfg(test)] async fn current_camera_source_key(state: &AppState) -> Option { state.preview_camera.lock().await.source_key.clone() } async fn acquire_preview_camera_source( state: &AppState, source_key: SourceKey, status: SourceLifecycleStatus, ) { let mut registry = state.source_registry.lock().await; registry.acquire(source_key.clone(), SourceConsumerReason::Preview); registry.set_status(source_key, status); } #[cfg(test)] async fn release_current_preview_camera_source(state: &AppState) -> bool { let Some(source_key) = current_camera_source_key(state).await else { return false; }; release_preview_camera_source(state, &source_key).await } #[cfg(test)] async fn release_preview_camera_source(state: &AppState, source_key: &SourceKey) -> bool { let snapshot = state .source_registry .lock() .await .release(source_key, &SourceConsumerReason::Preview); snapshot .entries .iter() .find(|entry| &entry.key == source_key) .is_some_and(|entry| !entry.consumers.is_empty()) } /// How long a Live-acked session may stay frameless before reuse treats it as /// dead. This MUST exceed the camera's layout warm-start budget /// (`live_layout::WARM_CAMERA_START_TIMEOUT`): a readiness bail deliberately /// leaves the still-warming session in place, and the next switch attempt has /// to JOIN that warm-up — tearing it down restarts the device clock from zero, /// so a camera whose first frame is slower than the grace could never come /// back (0.9.51 Cam Link retry-storm regression). Only a session frameless /// longer than any legitimate warm-up is treated as dead. pub(crate) const CAMERA_FIRST_FRAME_REUSE_GRACE: Duration = Duration::from_secs(20); /// True when the current camera session acked Live, has never produced any /// frame evidence (no captured-frame count, nothing in the frame store), and /// has been in that state longer than the first-frame grace. #[cfg(test)] async fn camera_live_session_is_frameless_zombie(state: &AppState) -> bool { let slot = state.preview_camera.lock().await; camera_slot_is_frameless_zombie(&slot) } fn camera_slot_is_frameless_zombie(slot: &PreviewCameraRuntime) -> bool { if slot.status.state != PreviewCameraState::Live { return false; } let has_frame_evidence = slot.status.frames_captured > 0 || slot.status.sequence.is_some() || slot.active.as_ref().is_some_and(|active| { // WouldBlock means the capture thread holds the frame lock right // now — that is evidence of life, not a zombie. match active.shared.try_lock() { Ok(shared) => shared.frame_store.latest().is_some(), Err(TryLockError::WouldBlock) => true, Err(TryLockError::Poisoned(poisoned)) => { poisoned.into_inner().frame_store.latest().is_some() } } }); if has_frame_evidence { return false; } slot.live_acked_at .is_none_or(|acked| acked.elapsed() >= CAMERA_FIRST_FRAME_REUSE_GRACE) } /// Plan 216 D2: mark the status of a Live session that has sent no frame /// past the grace, by the same rule reuse and capture recovery use, so the /// streamer is told which camera sends no video. The metrics poll calls this /// every tick; any frame evidence clears it. fn refresh_camera_no_video(slot: &mut PreviewCameraRuntime) { slot.status.no_video = camera_slot_is_frameless_zombie(slot).then_some(true); } /// Test-only: install a healthy Live camera slot whose capture target was /// derived from `layout`, so cross-module tests (live_layout's geometry /// resync) can arm a staleness scenario without reaching into private slot /// fields. #[cfg(test)] pub(crate) async fn test_install_live_camera_for_layout( state: &AppState, camera_id: &str, layout: &LayoutSettings, video: &VideoSettings, ) { test_install_live_camera_slot_for_layout(state, camera_id, layout, video, true).await; } /// Test-only: a camera that acked Live and never delivered a frame, past the /// reuse grace (the streamer's MacBook camera in plan 216). Zero frames and /// sequence, an empty frame store, and a `live_acked_at` old enough that /// `camera_live_session_is_frameless_zombie` says so. #[cfg(test)] pub(crate) async fn test_install_frameless_live_camera_for_layout( state: &AppState, camera_id: &str, layout: &LayoutSettings, video: &VideoSettings, ) { test_install_live_camera_slot_for_layout(state, camera_id, layout, video, false).await; } #[cfg(test)] async fn test_install_live_camera_slot_for_layout( state: &AppState, camera_id: &str, layout: &LayoutSettings, video: &VideoSettings, fresh_frame: bool, ) { let (stop_tx, _stop_rx) = std_mpsc::channel(); let shared = Arc::new(StdMutex::new(PreviewCameraShared::default())); if fresh_frame { shared.lock().unwrap().frame_store.publish( 42, video.width, video.height, PreviewCameraPixelFormat::Bgra8, Instant::now(), vec![0; video.width as usize * video.height as usize * 4], ); } let mut slot = state.preview_camera.lock().await; slot.source_key = Some(SourceKey::camera(camera_id.to_string())); slot.status.state = PreviewCameraState::Live; slot.status.camera_id = Some(camera_id.to_string()); slot.status.device_unique_id = Some(camera_id.to_string()); slot.status.target_fps = video.fps; slot.status.width = Some(video.width); slot.status.height = Some(video.height); slot.status.requested_width = Some(video.width); slot.status.requested_height = Some(video.height); slot.status.actual_width = Some(video.width); slot.status.actual_height = Some(video.height); slot.status.frames_captured = if fresh_frame { 42 } else { 0 }; slot.status.sequence = fresh_frame.then_some(42); slot.disconnected = None; slot.start_generation = slot.start_generation.wrapping_add(1).max(1); slot.active_generation = Some(slot.start_generation); slot.live_acked_at = Some(if fresh_frame { Instant::now() } else { Instant::now() - CAMERA_FIRST_FRAME_REUSE_GRACE - Duration::from_secs(1) }); slot.active = Some(NativeCameraPreviewThread { stop_tx, join_handle: None, shared, camera_id: camera_id.to_string(), device_unique_id: camera_id.to_string(), ffmpeg_path: "ffmpeg".to_string(), layout: layout.clone(), video: video.clone(), effective_fps: video.fps, configured_output: (video.width, video.height), capture_target: camera_capture_target_dimensions(layout, video), }); } /// Admit through the real start boundary without opening a native device. /// The caller retains the transition gate and must stop the admitted runtime; /// this seam isolates desired-key registration from active-producer retirement. #[cfg(test)] pub(crate) async fn test_admit_camera_start_for_layout( state: &AppState, camera_id: &str, layout: &LayoutSettings, video: &VideoSettings, ) -> Option { let source_key = SourceKey::camera(camera_id); let mut status = idle_status(Some("Controlled camera start admission.".into())); status.state = PreviewCameraState::Starting; status.camera_id = Some(camera_id.into()); status.device_unique_id = Some(camera_id.into()); status.target_fps = video.fps.clamp(1, 120); let key = PreviewCameraStartKey { source_key, ffmpeg_path: "ffmpeg".into(), video: video.clone(), target_fps: status.target_fps, capture_target: camera_capture_target_dimensions(layout, video), }; match begin_camera_start(state, key, layout, status, None).await { PreviewCameraStartRegistration::Started { lease } => Some(lease.generation), _ => None, } } #[cfg(test)] pub(crate) async fn test_publish_camera_pixels( state: &AppState, sequence: u64, pixel: [u8; 4], captured_at: Instant, ) -> [u64; 4] { let began = Instant::now(); let (width, height, shared, fixture_camera) = { let slot = state.preview_camera.lock().await; let Some(active) = slot.active.as_ref() else { return [0; 4]; }; let video = &active.video; ( video.width, video.height, Arc::clone(&active.shared), active.camera_id == "camera:iso-runtime", ) }; let admitted = Instant::now(); let bytes = pixel.repeat((width * height) as usize); // Native callbacks own this generation's shared store and never retain // the admission authority while publishing. A replaced generation may // finish its callback, but cannot publish into the replacement's store. let allocated = Instant::now(); let mut shared = shared.lock().unwrap(); let locked = Instant::now(); if fixture_camera { shared.capture_timings.record_callback_at(captured_at); shared .capture_timings .record_sample_pts(Some(sequence as f64 / 100.0)); shared.source_fps = Some(100.0); } shared.frame_store.publish( sequence, width, height, PreviewCameraPixelFormat::Bgra8, captured_at, bytes, ); let published = Instant::now(); [ admitted.duration_since(began).as_micros() as u64, allocated.duration_since(admitted).as_micros() as u64, locked.duration_since(allocated).as_micros() as u64, published.duration_since(locked).as_micros() as u64, ] } /// Test-only: register a fully identified Starting generation without touching /// a physical camera. Cross-module race tests use the returned identity to /// exercise the same generation-and-key CAS as production timeout cleanup. #[cfg(test)] pub(crate) async fn test_install_starting_camera_generation( state: &AppState, camera_id: &str, layout: &LayoutSettings, video: &VideoSettings, layout_intent_id: Option, ) -> PreviewCameraStartingIdentity { let source_key = SourceKey::camera(camera_id.to_string()); let start_key = PreviewCameraStartKey { source_key: source_key.clone(), ffmpeg_path: "ffmpeg".to_string(), video: video.clone(), target_fps: video.fps, capture_target: camera_capture_target_dimensions(layout, video), }; let mut slot = state.preview_camera.lock().await; slot.disconnected = None; slot.start_generation = slot.start_generation.wrapping_add(1).max(1); slot.pending_stop_generation = None; slot.active_generation = None; slot.source_key = Some(source_key.clone()); slot.starting = Some(start_key); slot.starting_recovery_epoch = None; slot.starting_layout_intent_id = layout_intent_id; slot.status.state = PreviewCameraState::Starting; slot.status.camera_id = Some(camera_id.to_string()); slot.status.device_unique_id = Some(camera_id.to_string()); slot.status.target_fps = video.fps; slot.status.frames_captured = 0; slot.status.sequence = None; slot.active = None; PreviewCameraStartingIdentity { source_key, generation: slot.start_generation, layout_intent_id, } } /// Test-only: publish Live for the exact Starting generation without advancing /// its identity. This models the native callback racing timeout cancellation. #[cfg(test)] pub(crate) async fn test_publish_starting_camera_live( state: &AppState, expected: &PreviewCameraStartingIdentity, camera_id: &str, layout: &LayoutSettings, video: &VideoSettings, ) { let (stop_tx, _stop_rx) = std_mpsc::channel(); let shared = Arc::new(StdMutex::new(PreviewCameraShared::default())); shared.lock().unwrap().frame_store.publish( 42, video.width, video.height, PreviewCameraPixelFormat::Bgra8, Instant::now(), vec![0; video.width as usize * video.height as usize * 4], ); let mut slot = state.preview_camera.lock().await; assert_eq!( camera_starting_identity_from_slot(&slot).as_ref(), Some(expected), "test callback must publish the sampled generation" ); slot.status.state = PreviewCameraState::Live; slot.status.camera_id = Some(camera_id.to_string()); slot.status.device_unique_id = Some(camera_id.to_string()); slot.status.target_fps = video.fps; slot.status.width = Some(video.width); slot.status.height = Some(video.height); slot.status.actual_width = Some(video.width); slot.status.actual_height = Some(video.height); slot.status.frames_captured = 42; slot.status.sequence = Some(42); slot.active_generation = Some(expected.generation); slot.starting = None; slot.starting_transition_completion = None; slot.starting_layout_intent_id = None; slot.live_acked_at = Some(Instant::now()); slot.active = Some(NativeCameraPreviewThread { stop_tx, join_handle: None, shared, camera_id: camera_id.to_string(), device_unique_id: camera_id.to_string(), ffmpeg_path: "ffmpeg".to_string(), layout: layout.clone(), video: video.clone(), effective_fps: video.fps, configured_output: (video.width, video.height), capture_target: camera_capture_target_dimensions(layout, video), }); } /// Test-only: replace a Live camera session with a same-key, new-generation /// owner and a deterministic frame. Cross-module compositor tests use this to /// prove held-frame/fetch state is reset on generation identity, not source key. #[cfg(test)] #[allow(dead_code)] pub(crate) async fn test_advance_live_camera_generation(state: &AppState, sequence: u64) -> u64 { let mut slot = state.preview_camera.lock().await; let active = slot.active.as_ref().expect("test live camera"); let camera_id = active.camera_id.clone(); let device_unique_id = active.device_unique_id.clone(); let ffmpeg_path = active.ffmpeg_path.clone(); let layout = active.layout.clone(); let video = active.video.clone(); let effective_fps = active.effective_fps; let configured_output = active.configured_output; let capture_target = active.capture_target; let shared = Arc::new(StdMutex::new(PreviewCameraShared::default())); shared.lock().unwrap().frame_store.publish( sequence, configured_output.0, configured_output.1, PreviewCameraPixelFormat::Bgra8, Instant::now(), vec![0; configured_output.0 as usize * configured_output.1 as usize * 4], ); let (stop_tx, _stop_rx) = std_mpsc::channel(); slot.disconnected = None; slot.start_generation = slot.start_generation.wrapping_add(1).max(1); let generation = slot.start_generation; slot.active_generation = Some(generation); slot.failed_recovery_retry = None; slot.status.state = PreviewCameraState::Live; slot.status.frames_captured = sequence; slot.status.sequence = Some(sequence); slot.status.actual_width = Some(configured_output.0); slot.status.actual_height = Some(configured_output.1); slot.active = Some(NativeCameraPreviewThread { stop_tx, join_handle: None, shared, camera_id, device_unique_id, ffmpeg_path, layout, video, effective_fps, configured_output, capture_target, }); generation } /// True when the live camera session's configured capture box no longer /// matches what `layout`/`video` require. A hot preset switch (inset overlay /// <-> full canvas) keeps the session alive while its AVFoundation output /// stays sized for the old scene; only a restart re-derives the geometry. pub(crate) async fn camera_capture_geometry_is_stale( state: &AppState, layout: &LayoutSettings, video: &VideoSettings, ) -> bool { let slot = state.preview_camera.lock().await; if slot.status.state != PreviewCameraState::Live { return false; } slot.active.as_ref().is_some_and(|active| { active.capture_target != camera_capture_target_dimensions(layout, video) }) } #[cfg(test)] async fn reuse_current_camera_source( state: &AppState, source_key: &SourceKey, ffmpeg_path: &str, layout: &LayoutSettings, video: &VideoSettings, target_fps: u32, ) -> Option { let mut slot = state.preview_camera.lock().await; if slot.source_key.as_ref() != Some(source_key) || slot.starting.is_some() || slot.pending_stop_generation.is_some() || camera_slot_is_frameless_zombie(&slot) { return None; } let can_reuse = slot.active.as_ref().is_some_and(|active| { active.ffmpeg_path == ffmpeg_path && active.video == *video && slot.status.target_fps == target_fps // AVFoundation output geometry is fixed at session start; a layout // whose capture box differs (inset overlay vs full canvas) must // restart the session, not adopt frames sized for the old scene. && active.capture_target == camera_capture_target_dimensions(layout, video) }); if !can_reuse { return None; } if let Some(active) = slot.active.as_mut() { active.layout = layout.clone(); } let mut status = slot.status.clone(); status.updated_at = Utc::now().to_rfc3339(); status.message = Some("Native camera preview source reused.".to_string()); slot.status = status.clone(); let start_key = PreviewCameraStartKey { source_key: source_key.clone(), ffmpeg_path: ffmpeg_path.to_string(), video: video.clone(), target_fps, capture_target: camera_capture_target_dimensions(layout, video), }; log_camera_generation( slot.active_generation.unwrap_or(slot.start_generation), "reuse", &start_key, layout, ); Some(status) } async fn poll_camera_metrics( state: AppState, run_id: String, shared: Arc>, target_fps: u32, ) { let mut ticker = tokio::time::interval(Duration::from_millis(250)); ticker.set_missed_tick_behavior(MissedTickBehavior::Skip); loop { ticker.tick().await; let snapshot = { let guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); let latest_frame = guard.frame_store.latest(); CameraSharedSnapshot { frames_captured: guard.frames_captured, dropped_frames: guard.dropped_frames, source_fps: guard.source_fps, capture: PreviewCameraCaptureStats { callback_count: guard.capture_callback_count, did_drop_callback_count: guard.capture_drop_reasons.total(), frame_store_publications: guard.frames_captured, callback_age_ms: guard .capture_timings .last_callback_at .map(|at| at.elapsed().as_millis() as u64), latest_sequence: latest_frame.as_ref().map(|frame| frame.sequence), pixel_format: camera_capture_pixel_format_label(guard.capture_pixel_format), drop_reasons: guard.capture_drop_reasons.diagnostic_stats(), }, latest_frame, frame_store_stats: guard.frame_store.stats(), capture_timings: guard.capture_timings.snapshot(), system_effect: guard.system_effect, } }; let status = { let mut slot = state.preview_camera.lock().await; if slot.run_id.as_deref() != Some(run_id.as_str()) { break; } slot.status.frames_captured = snapshot.frames_captured; slot.status.dropped_frames = snapshot.dropped_frames; slot.status.source_fps = snapshot.source_fps.or(Some(f64::from(target_fps))); slot.status.system_effect = snapshot.system_effect; if let Some(frame) = snapshot.latest_frame { if slot.status.state != PreviewCameraState::Disconnected { slot.status.state = PreviewCameraState::Live; } slot.status.width = Some(frame.width); slot.status.height = Some(frame.height); slot.status.actual_width = Some(frame.width); slot.status.actual_height = Some(frame.height); slot.status.sequence = Some(frame.sequence); let _frame_bytes = frame.bytes.len(); slot.status.frame_age_ms = Some(frame.captured_at.elapsed().as_millis() as u64); match frame.pixel_format { PreviewCameraPixelFormat::Bgra8 => {} } } refresh_camera_no_video(&mut slot); slot.status.updated_at = Utc::now().to_rfc3339(); slot.status.clone() }; { let screen_frame_store_stats = crate::preview_screen::preview_screen_frame_store_stats(&state).await; let mut diagnostics = state.diagnostics.lock().await; let stats = apply_preview_camera_source_stats(diagnostics.clone(), &status); let stats = apply_preview_camera_capture_stats(stats, snapshot.capture); let stats = apply_preview_camera_capture_timing_stats(stats, snapshot.capture_timings); *diagnostics = apply_preview_source_frame_store_stats( stats, snapshot.frame_store_stats, screen_frame_store_stats, ); } state.emit_event("preview.camera.status", status); } } #[derive(Debug)] struct CameraSharedSnapshot { system_effect: Option, frames_captured: u64, dropped_frames: u64, source_fps: Option, capture: PreviewCameraCaptureStats, latest_frame: Option>, frame_store_stats: FrameStoreStats, capture_timings: PreviewCameraCaptureTimingStats, } #[cfg(target_os = "macos")] fn camera_capture_pixel_format_label(pixel_format: Option) -> Option { pixel_format.map(macos::format_fourcc) } #[cfg(not(target_os = "macos"))] fn camera_capture_pixel_format_label(_pixel_format: Option) -> Option { None } fn idle_status(message: Option) -> PreviewCameraStatus { PreviewCameraStatus { state: PreviewCameraState::DeviceMissing, camera_id: None, device_unique_id: None, target_fps: 0, width: None, height: None, requested_width: None, requested_height: None, actual_width: None, actual_height: None, selected_format_width: None, selected_format_height: None, selected_format_min_fps: None, selected_format_max_fps: None, source_fps: None, frame_age_ms: None, frames_captured: 0, dropped_frames: 0, sequence: None, updated_at: Utc::now().to_rfc3339(), message, no_video: None, system_effect: None, } } fn status_for_missing_camera(camera_id: Option, message: &str) -> PreviewCameraStatus { PreviewCameraStatus { state: PreviewCameraState::DeviceMissing, camera_id, device_unique_id: None, target_fps: 0, width: None, height: None, requested_width: None, requested_height: None, actual_width: None, actual_height: None, selected_format_width: None, selected_format_height: None, selected_format_min_fps: None, selected_format_max_fps: None, source_fps: None, frame_age_ms: None, frames_captured: 0, dropped_frames: 0, sequence: None, updated_at: Utc::now().to_rfc3339(), message: Some(message.to_string()), no_video: None, system_effect: None, } } fn failed_status( camera_id: Option, unique_id: Option, target_fps: u32, message: String, ) -> PreviewCameraStatus { PreviewCameraStatus { state: PreviewCameraState::Failed, camera_id, device_unique_id: unique_id, target_fps, width: None, height: None, requested_width: None, requested_height: None, actual_width: None, actual_height: None, selected_format_width: None, selected_format_height: None, selected_format_min_fps: None, selected_format_max_fps: None, source_fps: None, frame_age_ms: None, frames_captured: 0, dropped_frames: 0, sequence: None, updated_at: Utc::now().to_rfc3339(), message: Some(message), no_video: None, system_effect: None, } } fn mirror_rgba_in_place(bytes: &mut [u8], width: usize, height: usize) { let row_bytes = width.saturating_mul(4); if row_bytes == 0 || bytes.len() < row_bytes.saturating_mul(height) { return; } for row in 0..height { let start = row * row_bytes; let end = start + row_bytes; let row = &mut bytes[start..end]; for column in 0..(width / 2) { let left = column * 4; let right = (width - 1 - column) * 4; for channel in 0..4 { row.swap(left + channel, right + channel); } } } } fn downscale_rgba_for_preview( bytes: Vec, width: u32, height: u32, max_width: u32, ) -> (Vec, u32, u32) { if width <= max_width || width == 0 || height == 0 { return (bytes, width, height); } let next_width = max_width.max(1); let next_height = ((u64::from(height) * u64::from(next_width)) / u64::from(width)) .clamp(1, u64::from(u32::MAX)) as u32; let expected_len = (width as usize) .checked_mul(height as usize) .and_then(|pixels| pixels.checked_mul(4)); if expected_len != Some(bytes.len()) { return (bytes, width, height); } let image = image::RgbaImage::from_raw(width, height, bytes).expect("valid RGBA buffer length"); let next = image::imageops::resize(&image, next_width, next_height, FilterType::Lanczos3); (next.into_raw(), next_width, next_height) } #[cfg(any(target_os = "macos", target_os = "windows", test))] fn fit_camera_source_in_target_box( source_width: u32, source_height: u32, target_width: u32, target_height: u32, ) -> (u32, u32) { if source_width == 0 || source_height == 0 || target_width == 0 || target_height == 0 { return (source_width, source_height); } let box_width = target_width.min(source_width).max(1); let box_height = target_height.min(source_height).max(1); let height_for_width = scale_preserving_aspect(source_height, box_width, source_width); if height_for_width <= box_height { return (box_width, height_for_width.max(1)); } ( scale_preserving_aspect(source_width, box_height, source_height).max(1), box_height, ) } #[cfg(any(target_os = "macos", target_os = "windows", test))] fn scale_preserving_aspect(source_dimension: u32, target_dimension: u32, source_basis: u32) -> u32 { if source_basis == 0 { return target_dimension; } ((u64::from(source_dimension) * u64::from(target_dimension) + (u64::from(source_basis) / 2)) / u64::from(source_basis)) .clamp(1, u64::from(u32::MAX)) as u32 } #[derive(Clone)] struct NativeCameraPreviewConfig { #[cfg_attr(not(any(target_os = "macos", target_os = "windows")), allow(dead_code))] // the AVFoundation start and the Studio Effects watch read it camera_id: String, unique_id: String, ffmpeg_path: String, video: VideoSettings, layout: LayoutSettings, /// Plan 258 S4: what to do with Windows Studio Effects on this camera. #[cfg_attr(not(target_os = "windows"), allow(dead_code))] studio_effects: crate::camera_system_effect::StudioEffectsPolicy, } #[derive(Debug, Clone, PartialEq, Eq)] enum SelectedCameraSource { MacAvFoundation { unique_id: String }, WindowsDshow { device_name: String }, LinuxV4l2 { device_path: String }, } impl SelectedCameraSource { fn device_unique_id(&self) -> &str { match self { SelectedCameraSource::MacAvFoundation { unique_id } => unique_id, SelectedCameraSource::WindowsDshow { device_name } => device_name, SelectedCameraSource::LinuxV4l2 { device_path } => device_path, } } } fn selected_camera_source(camera_id: &str) -> Option { parse_native_camera_id(camera_id) .map(|unique_id| SelectedCameraSource::MacAvFoundation { unique_id }) .or_else(|| { parse_windows_dshow_camera_id(camera_id) .map(|device_name| SelectedCameraSource::WindowsDshow { device_name }) }) .or_else(|| { crate::linux_v4l2_camera::parse_linux_v4l2_camera_id(camera_id) .map(|device_path| SelectedCameraSource::LinuxV4l2 { device_path }) }) // Plan 214 A5: a saved id naming Videorc Camera resolves to nothing // (no silent substitute, plan 213 E): the camera never captures itself. .filter(|source| !source.is_videorc_camera()) } impl SelectedCameraSource { fn is_videorc_camera(&self) -> bool { match self { Self::MacAvFoundation { unique_id } => { crate::virtual_camera::is_videorc_camera_macos(unique_id, "") } Self::WindowsDshow { device_name } => { crate::virtual_camera::is_videorc_camera_windows(None, device_name) } Self::LinuxV4l2 { device_path } => { crate::virtual_camera::is_videorc_camera_linux_path(device_path) } } } } /// The box a Windows camera fills: the full output canvas for every preset, /// the same layout-invariant box `camera_capture_target_dimensions` gives the /// restart key (issue #1066). The inset presets used to pipe an overlay-sized /// frame, but a preset switch never restarts the camera, so a camera started /// under Screen + Camera kept piping ~540x304 after a switch to camera-only /// and the compositor stretched it to the canvas (a custom inset enlarged by /// hand did the same). Each attempt still pipes its mode's native size fitted /// into this box (`windows_camera_attempt_output_dimensions`), and the /// compositor fits that frame into whatever box the scene gives it. #[cfg(any(target_os = "windows", test))] fn windows_camera_preview_output_dimensions(config: &NativeCameraPreviewConfig) -> (u32, u32) { camera_capture_target_dimensions(&config.layout, &config.video) } /// The size an attempt pipes its frames at (issue #1271). An explicit mode /// keeps the camera's native size and shape, fitted into the target box and /// never enlarged, as the macOS path does (`fit_camera_source_in_target_box`): /// the compositor fits or covers each frame by its own size, so a 720p /// webcam on a 1440p canvas pipes 1280x720 (3.7 MB a frame), not 2560x1440 /// (14.7 MB). The fallbacks don't know the mode DirectShow will pick, so they /// keep the target's shape, shrunk to fit the camera's largest listed size. #[cfg(any(target_os = "windows", test))] fn windows_camera_attempt_output_dimensions( attempt: &WindowsCameraCaptureAttempt, (target_width, target_height): (u32, u32), advertised: Option<&DshowAdvertisedVideoModes>, ) -> (u32, u32) { match attempt { WindowsCameraCaptureAttempt::Mode { mode, .. } => { fit_camera_source_in_target_box(mode.width, mode.height, target_width, target_height) } WindowsCameraCaptureAttempt::ExactRate(_) | WindowsCameraCaptureAttempt::NegotiatedDefault => { match advertised.and_then(DshowAdvertisedVideoModes::largest_size) { Some((largest_width, largest_height)) => fit_camera_source_in_target_box( target_width, target_height, largest_width, largest_height, ), None => (target_width, target_height), } } } } /// What a Windows start that went live reports (issue #1271): the mode that /// actually runs, not the size it is piped at. "Selected format" used to /// name the output size when no MJPEG size was used, so a support bundle /// read "2560x1440 @30" for a camera running something else at 15 fps. /// /// A mode short of the target, in rate or in size, says so in the words the /// macOS start uses (`camera_capture::select_camera_format`), which the /// Sources shortfall warning reads. The fallbacks don't know their mode, so /// they report the piped size at the requested rate, as before. #[cfg(any(target_os = "windows", test))] fn windows_camera_live_startup( attempt: &WindowsCameraCaptureAttempt, (target_width, target_height): (u32, u32), (width, height): (u32, u32), fps: u32, ) -> NativeCameraStartup { let (selected_format, selected_fps, message) = match attempt { WindowsCameraCaptureAttempt::Mode { mode, fps: request_fps, .. } => { let label = format!( "{} {}x{}@{}", mode.format.label(), mode.width, mode.height, format_dshow_fps(*request_fps) ); let short = !mode.sustains(fps) || mode.width < target_width || mode.height < target_height; let message = if short { format!( "Requested {target_width}x{target_height}@{fps} was not available; selected native {}x{} at {:.0}-{:.0} fps. Windows camera preview is using {label}, piped at {width}x{height}.", mode.width, mode.height, mode.min_fps, mode.max_fps ) } else { format!( "Windows camera preview is using the camera's native {label}, piped at {width}x{height}." ) }; ( (mode.width, mode.height, mode.min_fps, mode.max_fps), *request_fps, message, ) } WindowsCameraCaptureAttempt::ExactRate(_) => ( (width, height, f64::from(fps), f64::from(fps)), f64::from(fps), format!( "Windows camera preview is using the driver's default format at {fps} fps, piped at {width}x{height}." ), ), WindowsCameraCaptureAttempt::NegotiatedDefault => ( (width, height, f64::from(fps), f64::from(fps)), f64::from(fps), format!( "Windows camera preview is using the driver's negotiated default format, piped at {width}x{height}." ), ), }; let (selected_format_width, selected_format_height, min_fps, max_fps) = selected_format; NativeCameraStartup::Live { requested_width: target_width, requested_height: target_height, selected_format_width, selected_format_height, selected_format_min_fps: min_fps, selected_format_max_fps: max_fps, width, height, selected_fps, message: Some(message), } } /// The FFmpeg arguments for one attempt. The scale stays even when the /// output is the mode's own size: the raw pipe has no frame header, so a /// camera that changes size mid-stream must not misalign the frames. #[cfg(any(target_os = "windows", test))] fn windows_camera_preview_ffmpeg_args_for( config: &NativeCameraPreviewConfig, attempt: &WindowsCameraCaptureAttempt, (width, height): (u32, u32), fps: u32, ) -> Vec { use crate::capture_input::WindowsDshowInputFormat; let mut args = vec![ "-hide_banner".to_string(), "-loglevel".to_string(), "warning".to_string(), "-nostdin".to_string(), ]; let (framerate, video_size, format) = match attempt { WindowsCameraCaptureAttempt::Mode { mode, fps, .. } => ( Some(format_dshow_fps(*fps)), Some((mode.width, mode.height)), match &mode.format { DshowModeFormat::Mjpeg => Some(WindowsDshowInputFormat::Codec("mjpeg")), DshowModeFormat::Raw(pixel_format) => { Some(WindowsDshowInputFormat::PixelFormat(pixel_format.as_str())) } DshowModeFormat::OtherCodec(codec) => { Some(WindowsDshowInputFormat::Codec(codec.as_str())) } }, ), WindowsCameraCaptureAttempt::ExactRate(fps) => (Some(fps.to_string()), None, None), WindowsCameraCaptureAttempt::NegotiatedDefault => (None, None, None), }; crate::capture_input::append_windows_dshow_video_input_native_mode( &mut args, &config.unique_id, framerate.as_deref(), video_size, format, ); let mut filters = Vec::with_capacity(3); if *attempt == WindowsCameraCaptureAttempt::NegotiatedDefault { // The retry lets dshow negotiate a native cadence. Cap devices whose // default exceeds the session target without manufacturing duplicates // for 10/15/25fps cameras (the `fps` filter does both). filters.push(format!( "select='isnan(prev_selected_t)+gte(t-prev_selected_t+{WINDOWS_CAMERA_RATE_CAP_EPSILON_SECONDS:.6}\\,1/{fps})'" )); } filters.push(format!( "scale={width}:{height}:force_original_aspect_ratio=decrease,pad={width}:{height}:(ow-iw)/2:(oh-ih)/2" )); filters.push("format=bgra".to_string()); args.extend([ "-an".to_string(), "-vf".to_string(), filters.join(","), "-fps_mode".to_string(), "passthrough".to_string(), "-f".to_string(), "rawvideo".to_string(), "-pix_fmt".to_string(), "bgra".to_string(), "-".to_string(), ]); args } #[cfg(any(target_os = "windows", test))] fn windows_camera_mjpeg_capture_modes(width: u32, height: u32) -> Vec<(u32, u32)> { const COMMON_MODES: &[(u32, u32)] = &[ (160, 90), (160, 120), (176, 144), (320, 180), (320, 240), (352, 288), (432, 240), (640, 360), (640, 480), (800, 448), (800, 600), (864, 480), (960, 720), (1024, 576), (1280, 720), (1600, 896), (1920, 1080), ]; sort_windows_camera_capture_modes(COMMON_MODES.to_vec(), width, height) } /// Closest usable capture shape first: not undersized, then aspect, then area. #[cfg(any(target_os = "windows", test))] fn sort_windows_camera_capture_modes( mut modes: Vec<(u32, u32)>, width: u32, height: u32, ) -> Vec<(u32, u32)> { let target_width = u64::from(width.max(1)); let target_height = u64::from(height.max(1)); let target_pixels = target_width.saturating_mul(target_height); modes.sort_by_key(|&(mode_width, mode_height)| { let mode_width = u64::from(mode_width); let mode_height = u64::from(mode_height); let mode_pixels = mode_width.saturating_mul(mode_height); let undersized = u8::from(mode_width < target_width || mode_height < target_height); let aspect_error = mode_width .saturating_mul(target_height) .abs_diff(target_width.saturating_mul(mode_height)); ( undersized, aspect_error, mode_pixels.abs_diff(target_pixels), ) }); modes } /// How a DirectShow mode delivers pixels: MJPEG, a raw pixel format by /// FFmpeg's name (`yuyv422`, `nv12`, ...), or another codec (H.264 on some /// webcams) that the preview does not ask for explicitly. #[cfg(any(target_os = "windows", test))] #[derive(Debug, Clone, PartialEq, Eq)] enum DshowModeFormat { Mjpeg, Raw(String), OtherCodec(String), } #[cfg(any(target_os = "windows", test))] impl DshowModeFormat { fn label(&self) -> String { match self { Self::Mjpeg => "MJPEG".to_string(), Self::Raw(name) | Self::OtherCodec(name) => name.to_ascii_uppercase(), } } } /// One native capture mode a DirectShow camera advertises: a format at one /// size, with the frame-rate range the driver lists for it. #[cfg(any(target_os = "windows", test))] #[derive(Debug, Clone, PartialEq)] struct DshowVideoMode { format: DshowModeFormat, width: u32, height: u32, min_fps: f64, max_fps: f64, } #[cfg(any(target_os = "windows", test))] impl DshowVideoMode { fn pixels(&self) -> u64 { u64::from(self.width) * u64::from(self.height) } /// Whether the mode's listed rate reaches `fps`. A mode listed at 29.97 /// keeps a 30 fps target, as the Sources shortfall check rounds it. fn sustains(&self, fps: u32) -> bool { self.max_fps + WINDOWS_CAMERA_MODE_FPS_TOLERANCE >= f64::from(fps) } /// The `-framerate` to ask this mode for: the target, or the mode's own /// top rate when it lists less. DirectShow refuses a rate outside the /// mode's range, so 30 on a 29.97 mode would fail the rung. fn request_fps(&self, fps: u32) -> f64 { let fps = f64::from(fps); if self.max_fps < fps { self.max_fps } else { fps.max(self.min_fps) } } /// The area of the largest `target` shaped picture inside this mode, /// capped at the target's own area: what the mode can put on screen /// once it is fitted to a target of that shape. A 1280x960 camera on a /// 16:9 target is worth 1280x720, and a mode bigger than the target is /// worth no more than one that just covers it. fn usable_pixels(&self, target_width: u32, target_height: u32) -> u64 { let (tw, th) = ( u64::from(target_width.max(1)), u64::from(target_height.max(1)), ); let (w, h) = (u64::from(self.width), u64::from(self.height)); let (usable_w, usable_h) = if w * th >= h * tw { (h * tw / th, h) } else { (w, w * th / tw) }; (usable_w * usable_h).min(tw * th) } } /// The capture modes one DirectShow camera advertises (`-list_options true`), /// in the order it lists them, one per format and size. #[cfg(any(target_os = "windows", test))] #[derive(Debug, Clone, Default, PartialEq)] struct DshowAdvertisedVideoModes { modes: Vec, } #[cfg(any(target_os = "windows", test))] impl DshowAdvertisedVideoModes { fn is_empty(&self) -> bool { self.modes.is_empty() } fn mjpeg_count(&self) -> usize { self.modes .iter() .filter(|mode| mode.format == DshowModeFormat::Mjpeg) .count() } /// The largest size the camera lists, in any format. fn largest_size(&self) -> Option<(u32, u32)> { self.modes .iter() .max_by_key(|mode| mode.pixels()) .map(|mode| (mode.width, mode.height)) } /// One line for the log: every mode, as `YUY2 1280x720@5-30`. fn summary(&self) -> String { self.modes .iter() .map(|mode| { format!( "{} {}x{}@{}", mode.format.label(), mode.width, mode.height, format_dshow_fps_range(mode.min_fps, mode.max_fps) ) }) .collect::>() .join(", ") } } #[cfg(any(target_os = "windows", test))] fn format_dshow_fps(fps: f64) -> String { let rounded = (fps * 1000.0).round() / 1000.0; if rounded.fract() == 0.0 { format!("{rounded:.0}") } else { format!("{rounded}") } } #[cfg(any(target_os = "windows", test))] fn format_dshow_fps_range(min_fps: f64, max_fps: f64) -> String { if (max_fps - min_fps).abs() < 0.001 { format_dshow_fps(max_fps) } else { format!( "{}-{}", format_dshow_fps(min_fps), format_dshow_fps(max_fps) ) } } /// Parses the stderr of `ffmpeg -list_options true -f dshow -i video=...`: /// one `vcodec=` or `pixel_format=` line per mode, each with /// `min s=WxH fps=A max s=WxH fps=B`. The two rates are the ends of the /// mode's frame-rate range (FFmpeg prints them from the longest and shortest /// frame interval), not one per size. A format listed twice at one size (a /// fixed-rate line and a range line) keeps the widest range. #[cfg(any(target_os = "windows", test))] fn parse_dshow_advertised_video_modes(stderr: &str) -> DshowAdvertisedVideoModes { fn format_of(line: &str) -> Option { let value_after = |key: &str| { let rest = &line[line.find(key)? + key.len()..]; rest.split_whitespace().next().map(str::to_string) }; if let Some(codec) = value_after("vcodec=") { return Some(if codec == "mjpeg" { DshowModeFormat::Mjpeg } else { DshowModeFormat::OtherCodec(codec) }); } value_after("pixel_format=").map(DshowModeFormat::Raw) } /// `(size, fps)` after `min` or `max`: the `s=WxH` and `fps=F` tokens. fn end_after(line: &str, key: &str) -> Option<((u32, u32), Option)> { let mut tokens = line[line.find(key)? + key.len()..].split_whitespace(); let (width, height) = tokens.next()?.strip_prefix("s=")?.split_once('x')?; let size = (width.parse().ok()?, height.parse().ok()?); let fps = tokens .next() .and_then(|token| token.strip_prefix("fps=")) .and_then(|fps| fps.parse::().ok()) .filter(|fps| fps.is_finite() && *fps > 0.0); Some((size, fps)) } let mut advertised = DshowAdvertisedVideoModes::default(); for line in stderr.lines() { let Some(format) = format_of(line) else { continue; }; let min = end_after(line, "min "); let max = end_after(line, "max "); if min.is_none() && max.is_none() { continue; } let rates = [min.and_then(|end| end.1), max.and_then(|end| end.1)]; let rates = rates.iter().flatten().copied(); let (min_fps, max_fps) = rates.fold((f64::INFINITY, 0.0_f64), |(lo, hi), fps| { (lo.min(fps), hi.max(fps)) }); // A line without a readable rate still names a mode the camera has; // its range is unknown, so it never claims to reach a target. let (min_fps, max_fps) = if max_fps > 0.0 { (min_fps, max_fps) } else { (0.0, 0.0) }; for (width, height) in [min.map(|end| end.0), max.map(|end| end.0)] .into_iter() .flatten() { if let Some(known) = advertised .modes .iter_mut() .find(|mode| mode.format == format && mode.width == width && mode.height == height) { known.min_fps = known.min_fps.min(min_fps); known.max_fps = known.max_fps.max(max_fps); continue; } advertised.modes.push(DshowVideoMode { format: format.clone(), width, height, min_fps, max_fps, }); } } advertised } /// The camera's advertised modes, best first, for a `width`x`height` target /// at `fps` (issue #1271). /// /// - A mode that reaches the target rate beats one that does not. /// - Among modes that reach it: the most usable picture for the target's /// shape, then the fewest pixels (a mode that just covers the target beats /// a bigger one), then MJPEG before raw (the start ladder's long-standing /// order), then the camera's own listing order. /// - When no mode reaches the target rate, the fastest wins, then the most /// usable picture. A smooth smaller picture the compositor scales up beats /// a sharp one at half the rate: a 720p webcam that offers YUY2 1280x720 at /// 10 fps and 640x480 at 30 runs at 640x480. /// /// Other codecs (H.264 webcams) are never asked for explicitly. #[cfg(any(target_os = "windows", test))] fn rank_windows_camera_modes( advertised: &DshowAdvertisedVideoModes, width: u32, height: u32, fps: u32, ) -> Vec { let mut modes = advertised .modes .iter() .filter(|mode| !matches!(mode.format, DshowModeFormat::OtherCodec(_))) .cloned() .collect::>(); modes.sort_by(|a, b| { let (a_reaches, b_reaches) = (a.sustains(fps), b.sustains(fps)); b_reaches.cmp(&a_reaches).then_with(|| { let by_picture = b .usable_pixels(width, height) .cmp(&a.usable_pixels(width, height)) .then_with(|| a.pixels().cmp(&b.pixels())); let by_format = || { let raw = |mode: &DshowVideoMode| u8::from(mode.format != DshowModeFormat::Mjpeg); raw(a).cmp(&raw(b)) }; if a_reaches { by_picture.then_with(by_format) } else { b.max_fps .total_cmp(&a.max_fps) .then(by_picture) .then_with(by_format) } }) }); modes } /// One DirectShow rung: an explicit native mode at a rate, the exact target /// rate in the driver's default format, or the driver's negotiated default. #[cfg(any(target_os = "windows", test))] #[derive(Debug, Clone, PartialEq)] enum WindowsCameraCaptureAttempt { Mode { mode: DshowVideoMode, fps: f64, /// The best mode the camera itself listed: not a guess, so it gets /// the exact-rate rung's deadline (see `WindowsCameraAttemptKind`). best_listed: bool, }, ExactRate(u32), NegotiatedDefault, } #[cfg(any(target_os = "windows", test))] impl WindowsCameraCaptureAttempt { fn kind(&self) -> WindowsCameraAttemptKind { match self { Self::Mode { best_listed: true, .. } => WindowsCameraAttemptKind::BestListedMode, Self::Mode { .. } => WindowsCameraAttemptKind::ExplicitMode, Self::ExactRate(_) => WindowsCameraAttemptKind::ExactRate, Self::NegotiatedDefault => WindowsCameraAttemptKind::NegotiatedDefault, } } fn label(&self) -> String { match self { Self::Mode { mode, fps, .. } => format!( "{} {}x{}@{}", mode.format.label(), mode.width, mode.height, format_dshow_fps(*fps) ), Self::ExactRate(fps) => format!("default format @{fps}"), Self::NegotiatedDefault => "negotiated default format".to_string(), } } } /// The DirectShow attempt ladder (issue #1271): the camera's own modes, best /// first, then the exact rate, then the negotiated default. /// /// With the camera's advertised modes the explicit rungs are the best /// `WINDOWS_CAMERA_EXPLICIT_MODE_RUNGS` of them, raw formats included: a /// camera that lists only YUY2 used to fall through to `-framerate 30`, where /// DirectShow chose its own mode (a LifeCam HD-3000 ran at 15 fps that way). /// Without them (the probe failed or parsed nothing) the ladder keeps every /// common MJPEG size. #[cfg(any(target_os = "windows", test))] fn windows_camera_capture_attempts( width: u32, height: u32, fps: u32, advertised: Option<&DshowAdvertisedVideoModes>, ) -> Vec { let modes = match advertised.filter(|modes| !modes.is_empty()) { Some(advertised) => rank_windows_camera_modes(advertised, width, height, fps) .into_iter() .take(WINDOWS_CAMERA_EXPLICIT_MODE_RUNGS) .collect::>(), None => windows_camera_mjpeg_capture_modes(width, height) .into_iter() .map(|(width, height)| DshowVideoMode { format: DshowModeFormat::Mjpeg, width, height, min_fps: f64::from(fps), max_fps: f64::from(fps), }) .collect(), }; let listed = advertised.is_some_and(|modes| !modes.is_empty()); let mut attempts = modes .into_iter() .enumerate() .map(|(index, mode)| { let fps = mode.request_fps(fps); WindowsCameraCaptureAttempt::Mode { mode, fps, best_listed: listed && index == 0, } }) .collect::>(); attempts.extend([ WindowsCameraCaptureAttempt::ExactRate(fps), WindowsCameraCaptureAttempt::NegotiatedDefault, ]); attempts } /// What the DirectShow `-list_options true` probe learned about a camera. #[cfg(any(target_os = "windows", test))] #[derive(Debug, PartialEq)] enum WindowsDshowModeProbe { /// The camera listed its modes, possibly without any MJPEG. Modes(DshowAdvertisedVideoModes), /// No modes and no known cause: the ladder keeps every common mode. Unreadable, /// A failure no capture mode can fix; no attempt should be spawned. ModeIndependentError(String), } /// Classifies `-list_options true` output. A camera that lists only raw modes /// (the UHD 620 field laptop's YUY2-only "HP HD Camera", the frame-server /// C920) gets no MJPEG rung; a busy, missing or refused one gets no rung. #[cfg(any(target_os = "windows", test))] fn classify_windows_dshow_mode_probe(stderr: &str) -> WindowsDshowModeProbe { let modes = parse_dshow_advertised_video_modes(stderr); if !modes.is_empty() { return WindowsDshowModeProbe::Modes(modes); } match stderr .lines() .find(|line| windows_dshow_error_is_mode_independent(line)) { Some(line) => WindowsDshowModeProbe::ModeIndependentError(line.trim().to_string()), None => WindowsDshowModeProbe::Unreadable, } } /// #1068 step 3: the modes each DirectShow camera advertised, by moniker, for /// the life of the backend. The `-list_options` probe cost about 1.45 s of /// every Windows camera start (C920 behind the Frame Server) while the ordered /// lane waited; a camera's modes don't change while it stays plugged in. Only /// a probe that listed modes is kept, and a start that finds no working mode /// or hits a device error forgets the camera, so the next start probes again. #[cfg(any(target_os = "windows", test))] #[derive(Debug, Default)] struct DshowModeCache { modes: StdMutex>, } #[cfg(any(target_os = "windows", test))] impl DshowModeCache { /// The camera's remembered modes, or the probe's answer (remembered when /// it listed modes). The flag says whether the probe was skipped. fn probe_through( &self, camera: &str, probe: impl FnOnce() -> WindowsDshowModeProbe, ) -> (WindowsDshowModeProbe, bool) { if let Some(modes) = self .modes .lock() .unwrap_or_else(|p| p.into_inner()) .get(camera) .cloned() { return (WindowsDshowModeProbe::Modes(modes), true); } let probed = probe(); if let WindowsDshowModeProbe::Modes(modes) = &probed { self.modes .lock() .unwrap_or_else(|p| p.into_inner()) .insert(camera.to_string(), modes.clone()); } (probed, false) } /// Drops the camera's modes; its next start probes again. fn forget(&self, camera: &str) -> bool { self.modes .lock() .unwrap_or_else(|p| p.into_inner()) .remove(camera) .is_some() } } /// DirectShow failures no other capture mode can fix: retrying them only /// burns the start budget. #[cfg(any(target_os = "windows", test))] fn windows_dshow_error_is_mode_independent(stderr: &str) -> bool { // Not "already in use": FFmpeg's dshow appends that hint to every // `Could not run graph`, whatever the cause, and a later rung can still // run. let stderr = stderr.to_ascii_lowercase(); stderr.contains("access is denied") || stderr.contains("permission denied") || stderr.contains("could not find video device") } /// The Windows camera start ladder: explicit native modes, then the exact /// rate in the default format, then whatever the driver negotiates. /// /// The best mode the camera listed is not a guess the way a common MJPEG /// size is: it reserves only the negotiated default's share, like the /// exact-rate rung it replaces as the first try. The HP HD Camera (YUY2 only) /// needs 1.6-2.8 s to its first frame; with the speculative reserve, a cold /// 1.9 s mode probe left it 1.6 s and the start failed (issue #1271 field /// check). #[cfg(any(target_os = "windows", test))] #[derive(Clone, Copy, Debug, PartialEq, Eq)] enum WindowsCameraAttemptKind { BestListedMode, ExplicitMode, ExactRate, NegotiatedDefault, } #[cfg(any(target_os = "windows", test))] impl WindowsCameraAttemptKind { /// Start budget this attempt must leave for the attempts after it. fn reserve(self) -> Duration { match self { Self::ExplicitMode => WINDOWS_CAMERA_DEFAULT_FORMAT_RESERVE, Self::BestListedMode | Self::ExactRate => WINDOWS_CAMERA_NEGOTIATED_DEFAULT_RESERVE, Self::NegotiatedDefault => Duration::ZERO, } } } /// First-frame deadline for one attempt, or `None` to skip it. Every attempt /// but the last leaves its kind's reserve of the start budget unspent. #[cfg(any(target_os = "windows", test))] fn windows_camera_attempt_first_frame_timeout( remaining: Duration, kind: WindowsCameraAttemptKind, ) -> Option { let timeout = remaining .saturating_sub(kind.reserve()) .min(WINDOWS_CAMERA_ATTEMPT_FIRST_FRAME_TIMEOUT); let has_fallback = kind != WindowsCameraAttemptKind::NegotiatedDefault; if timeout.is_zero() || (has_fallback && timeout < WINDOWS_CAMERA_MIN_EARLY_ATTEMPT) { return None; } Some(timeout) } fn camera_capture_target_dimensions(_layout: &LayoutSettings, video: &VideoSettings) -> (u32, u32) { // Capture geometry is LAYOUT-INVARIANT on purpose: always the full output // canvas, for every preset. The inset scenes used to capture a small // overlay box as an optimization, which made camera-only <-> screen+camera // the one preset pair whose capture boxes differed — so exactly those // switches force-restarted the camera (device power-cycles, renegotiation // garbage on screen; owner-reported through 0.9.64). The compositor's // scene math scales the full-size frame into any inset, capturing big and // scaling down only improves inset quality, and a preset switch can now // NEVER invalidate a running camera session. Only genuine output-canvas // changes (video preset/orientation) re-derive capture geometry. // Windows uses the same box (windows_camera_preview_output_dimensions). (video.width, video.height) } #[derive(Debug)] enum NativeCameraStartup { Live { requested_width: u32, requested_height: u32, selected_format_width: u32, selected_format_height: u32, selected_format_min_fps: f64, selected_format_max_fps: f64, width: u32, height: u32, selected_fps: f64, message: Option, }, #[cfg_attr(target_os = "windows", allow(dead_code))] // macOS and Linux startups report it PermissionNeeded(String), #[cfg_attr(target_os = "windows", allow(dead_code))] // macOS and Linux startups report it DeviceMissing(String), Failed(String), } fn run_native_camera_preview( config: NativeCameraPreviewConfig, shared: Arc>, stop_rx: std_mpsc::Receiver<()>, startup_tx: std_mpsc::Sender, ) { let _ = config.ffmpeg_path.as_str(); #[cfg(target_os = "macos")] macos::run_native_camera_preview(config, shared, stop_rx, startup_tx); #[cfg(target_os = "windows")] { windows::run_native_camera_preview(config, shared, stop_rx, startup_tx); } #[cfg(target_os = "linux")] { linux::run_native_camera_preview(config, shared, stop_rx, startup_tx); } #[cfg(not(any(target_os = "macos", target_os = "windows", target_os = "linux")))] { let _ = config; let _ = shared; let _ = stop_rx; let _ = startup_tx.send(NativeCameraStartup::Failed( "Native camera preview is only available on macOS, Windows and Linux.".to_string(), )); } } /// Linux (L3): an owned FFmpeg V4L2 child writes scaled BGRA frames to the /// camera frame store, the Windows DirectShow shape. The capture box is the /// full output canvas (`camera_capture_target_dimensions`), so a layout /// switch never restarts the device. #[cfg(target_os = "linux")] mod linux { use std::io::Read; use std::process::{Child, Command, Stdio}; use std::sync::atomic::{AtomicBool, Ordering}; use super::*; use crate::linux_v4l2_camera::{ V4l2StartFailure, classify_v4l2_failure, v4l2_preview_ffmpeg_args, }; use crate::process_job::spawn_owned_std; enum Attempt { ProducedFrames, Stopped, FailedBeforeFirstFrame(String), } pub fn run_native_camera_preview( config: NativeCameraPreviewConfig, shared: Arc>, stop_rx: std_mpsc::Receiver<()>, startup_tx: std_mpsc::Sender, ) { let (width, height) = camera_capture_target_dimensions(&config.layout, &config.video); let fps = config.video.fps.clamp(1, 120); let Some(frame_len) = (width as usize) .checked_mul(height as usize) .and_then(|pixels| pixels.checked_mul(4)) else { let _ = startup_tx.send(NativeCameraStartup::Failed( "Linux camera preview dimensions are too large.".to_string(), )); return; }; let stop_flag = Arc::new(AtomicBool::new(false)); { let stop_flag = Arc::clone(&stop_flag); thread::spawn(move || { let _ = stop_rx.recv(); stop_flag.store(true, Ordering::Release); }); } // Ask for the canvas size at the session rate (the driver settles on // its nearest mode), then fall back to the device default. let attempts = [Some((width, height, fps)), None]; let mut last_stderr = String::new(); for request in attempts { if stop_flag.load(Ordering::Acquire) { return; } match run_attempt( &config, &shared, &startup_tx, &stop_flag, (width, height, fps, frame_len), request, ) { Attempt::ProducedFrames | Attempt::Stopped => return, Attempt::FailedBeforeFirstFrame(stderr) => { let fatal = matches!( classify_v4l2_failure(&config.unique_id, &stderr), V4l2StartFailure::PermissionNeeded(_) | V4l2StartFailure::DeviceMissing(_) ); last_stderr = stderr; if fatal { break; } } } } let _ = startup_tx.send( match classify_v4l2_failure(&config.unique_id, &last_stderr) { V4l2StartFailure::PermissionNeeded(message) => { NativeCameraStartup::PermissionNeeded(message) } V4l2StartFailure::DeviceMissing(message) => { NativeCameraStartup::DeviceMissing(message) } V4l2StartFailure::Failed(message) => NativeCameraStartup::Failed(message), }, ); } fn run_attempt( config: &NativeCameraPreviewConfig, shared: &Arc>, startup_tx: &std_mpsc::Sender, stop_flag: &Arc, (width, height, fps, frame_len): (u32, u32, u32, usize), request: Option<(u32, u32, u32)>, ) -> Attempt { let mut command = Command::new(&config.ffmpeg_path); command .args(v4l2_preview_ffmpeg_args( &config.unique_id, width, height, request, )) .stdin(Stdio::null()) .stdout(Stdio::piped()) .stderr(Stdio::piped()); let mut child = match spawn_owned_std(&mut command) { Ok(child) => child, Err(error) => { return Attempt::FailedBeforeFirstFrame(format!( "Could not start {}: {error}", config.ffmpeg_path )); } }; let Some(mut stdout) = child.stdout.take() else { let _ = child.kill(); let _ = child.wait(); return Attempt::FailedBeforeFirstFrame("FFmpeg stdout was not piped".to_string()); }; let stderr = collect_stderr(child.stderr.take()); let child = Arc::new(StdMutex::new(child)); let done = Arc::new(AtomicBool::new(false)); let killer = spawn_stop_flag_killer(Arc::clone(&child), Arc::clone(&done), Arc::clone(stop_flag)); let mut buffer = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) .frame_store .checkout_overwrite_buffer(frame_len); let mut startup_sent = false; loop { if stdout.read_exact(&mut buffer).is_err() { break; } buffer = publish_bgra_frame(shared, width, height, buffer); if !startup_sent { let _ = startup_tx.send(NativeCameraStartup::Live { requested_width: width, requested_height: height, selected_format_width: request.map_or(width, |request| request.0), selected_format_height: request.map_or(height, |request| request.1), selected_format_min_fps: fps as f64, selected_format_max_fps: fps as f64, width, height, selected_fps: fps as f64, message: Some(if request.is_some() { format!( "Linux V4L2 camera preview requested {width}x{height}@{fps} from {}; the driver streams its nearest mode, scaled to fit.", config.unique_id ) } else { format!( "Linux V4L2 camera preview is using the device default mode of {}, scaled to {width}x{height}.", config.unique_id ) }), }); startup_sent = true; } } done.store(true, Ordering::Release); let _ = child .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) .wait(); let _ = killer.join(); if startup_sent { Attempt::ProducedFrames } else if stop_flag.load(Ordering::Acquire) { Attempt::Stopped } else { Attempt::FailedBeforeFirstFrame( String::from_utf8_lossy( &stderr .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()), ) .into_owned(), ) } } fn collect_stderr(stderr: Option) -> Arc>> { let bytes = Arc::new(StdMutex::new(Vec::new())); if let Some(mut stderr) = stderr { let target = Arc::clone(&bytes); thread::spawn(move || { let mut chunk = [0_u8; 4096]; while let Ok(read) = stderr.read(&mut chunk) { if read == 0 { break; } let mut target = target .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); // Keep the tail: FFmpeg's last lines carry the reason. target.extend_from_slice(&chunk[..read]); let excess = target.len().saturating_sub(16 * 1024); target.drain(..excess); } }); } bytes } fn spawn_stop_flag_killer( child: Arc>, done: Arc, stop_flag: Arc, ) -> thread::JoinHandle<()> { thread::spawn(move || { while !done.load(Ordering::Acquire) { if stop_flag.load(Ordering::Acquire) { let _ = child .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) .kill(); return; } thread::sleep(Duration::from_millis(50)); } }) } fn publish_bgra_frame( shared: &Arc>, width: u32, height: u32, bytes: Vec, ) -> Vec { let callback_started_at = Instant::now(); let frame_len = bytes.len(); let mut guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); guard.record_pipe_frame_callback(callback_started_at); let now = Instant::now(); guard.frames_captured = guard.frames_captured.saturating_add(1); guard.frames_in_window = guard.frames_in_window.saturating_add(1); let window_started = *guard.window_started_at.get_or_insert(now); let elapsed = window_started.elapsed(); if elapsed >= Duration::from_millis(500) { guard.source_fps = Some(guard.frames_in_window as f64 / elapsed.as_secs_f64().max(0.001)); guard.frames_in_window = 0; guard.window_started_at = Some(now); } let sequence = guard.frames_captured; guard.frame_store.publish_with_metadata( sequence, width, height, PreviewCameraPixelFormat::Bgra8, (), now, bytes, ); let next_buffer = guard.frame_store.checkout_overwrite_buffer(frame_len); let publish_ms = callback_started_at.elapsed().as_secs_f64() * 1000.0; guard .capture_timings .record_valid_frame(0.0, 0.0, publish_ms, frame_len as u64); next_buffer } } #[cfg(target_os = "windows")] mod windows { use std::io::Read; use std::process::{Child, Command, Stdio}; use std::sync::atomic::{AtomicBool, Ordering}; use super::*; use crate::process_job::spawn_owned_std; pub fn run_native_camera_preview( config: NativeCameraPreviewConfig, shared: Arc>, stop_rx: std_mpsc::Receiver<()>, startup_tx: std_mpsc::Sender, ) { // The box the camera fills; each attempt pipes at its own size. let target = windows_camera_preview_output_dimensions(&config); let fps = config.video.fps.clamp(1, 120); // One stop signal shared across attempts; a per-attempt killer reacts // to it (the read loop unblocks when the ffmpeg child is killed). let stop_flag = Arc::new(AtomicBool::new(false)); { let stop_flag = Arc::clone(&stop_flag); // Plan 258 S4: the same thread watches Windows Studio Effects on // this camera until the stop, then puts back anything it turned // off, so the restore never outlives the camera session. let camera_id = config.camera_id.clone(); let policy = config.studio_effects.clone(); let effect_shared = Arc::clone(&shared); thread::spawn(move || { crate::camera_system_effect::windows_device::watch_session( &camera_id, &policy, &stop_rx, |effect| { effect_shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) .system_effect = effect; }, ); stop_flag.store(true, Ordering::Release); }); } // The whole start, mode probe included, must finish inside the // command contract; see WINDOWS_CAMERA_PREVIEW_STARTUP_TIMEOUT. let started_at = Instant::now(); let start_deadline = started_at + WINDOWS_CAMERA_START_BUDGET; // Ask for one of the camera's own modes (issue #1271): the one that // reaches the target rate with the most picture, MJPEG or raw. // Consumer webcams commonly reserve 720p30 for MJPEG while their // uncompressed mode tops out at 5-10 fps, and a camera left to pick // its own mode can pick a slow one. The exact-rate and // negotiated-default fallbacks stay for cameras no mode works on. let (probe, cached) = windows_dshow_mode_cache().probe_through(&config.unique_id, || { probe_dshow_advertised_video_modes(&config) }); if cached { tracing::info!( camera = %config.unique_id, "[camera-modes] reusing the modes this camera advertised earlier; probe skipped" ); } if stop_flag.load(Ordering::Acquire) { return; } let advertised = match probe { WindowsDshowModeProbe::Modes(modes) => Some(modes), WindowsDshowModeProbe::Unreadable => None, WindowsDshowModeProbe::ModeIndependentError(reason) => { // Busy, missing or refused: every capture mode would fail the // same way, so spend none of the start budget on them. windows_dshow_mode_cache().forget(&config.unique_id); tracing::warn!( camera = %config.unique_id, elapsed_ms = started_at.elapsed().as_millis() as u64, "Windows camera preview mode probe hit an error no capture mode can fix: {reason}" ); let _ = startup_tx.send(NativeCameraStartup::Failed(format!( "Windows camera preview could not open the device in {} ms: {reason}", started_at.elapsed().as_millis() ))); return; } }; let attempts = windows_camera_capture_attempts(target.0, target.1, fps, advertised.as_ref()); let attempt_count = attempts.len(); let mut failures = Vec::new(); for (attempt_index, attempt) in attempts.into_iter().enumerate() { if stop_flag.load(Ordering::Acquire) { return; } let remaining = start_deadline.saturating_duration_since(Instant::now()); if remaining.is_zero() { failures.push(format!( "start budget of {} s spent after {attempt_index} of {attempt_count} attempts", WINDOWS_CAMERA_START_BUDGET.as_secs() )); break; } let Some(first_frame_timeout) = windows_camera_attempt_first_frame_timeout(remaining, attempt.kind()) else { // An early attempt may not eat the time its fallbacks need. continue; }; let mode = attempt.label(); let output = windows_camera_attempt_output_dimensions(&attempt, target, advertised.as_ref()); let Some(frame_len) = bgra_frame_len(output.0, output.1) else { failures.push(format!("{mode}: {}x{} is too large", output.0, output.1)); continue; }; let attempt_started_at = Instant::now(); let outcome = run_windows_camera_preview_attempt( &config, &shared, &startup_tx, &stop_flag, WindowsCameraAttemptPlan { attempt: &attempt, target, output, fps, frame_len, first_frame_timeout, }, ); let attempt_ms = attempt_started_at.elapsed().as_millis() as u64; match outcome { CameraPreviewAttempt::ProducedFrames => { tracing::info!( camera = %config.unique_id, attempt = attempt_index + 1, ran_ms = attempt_ms, "Windows camera preview with {mode} ended after running live" ); return; } CameraPreviewAttempt::Stopped => return, CameraPreviewAttempt::FailedBeforeFirstFrame(reason) => { tracing::warn!( camera = %config.unique_id, attempt = attempt_index + 1, attempts = attempt_count, attempt_ms, "Windows camera preview attempt {mode} produced no frame: {reason}" ); let mode_independent = windows_dshow_error_is_mode_independent(&reason); failures.push(format!("{mode}: {reason}")); if mode_independent { break; } } } } let summary = failures .last() .cloned() .unwrap_or_else(|| "no capture mode was attempted".to_string()); // Modes remembered from an earlier start may be what failed here (a // different driver, a replugged device): probe again next time. windows_dshow_mode_cache().forget(&config.unique_id); let _ = startup_tx.send(NativeCameraStartup::Failed(format!( "Windows camera preview found no working capture mode after {} attempt(s) in {} ms; last: {summary}", failures.len(), started_at.elapsed().as_millis() ))); } pub(super) fn windows_dshow_mode_cache() -> &'static DshowModeCache { static CACHE: std::sync::OnceLock = std::sync::OnceLock::new(); CACHE.get_or_init(DshowModeCache::default) } /// For a start whose native thread outlived the startup timeout; see /// `native_camera_startup_unanswered`. pub(super) fn forget_dshow_modes(camera: &str) { if windows_dshow_mode_cache().forget(camera) { tracing::info!( camera, "[camera-modes] forgot this camera's cached modes after its start timed out" ); } } /// One bounded `-list_options` probe. Unreadable when it fails or reports /// no modes; the ladder then keeps every common MJPEG mode. fn probe_dshow_advertised_video_modes( config: &NativeCameraPreviewConfig, ) -> WindowsDshowModeProbe { let started_at = Instant::now(); let output = crate::process_job::output_owned_std_with_timeout( Command::new(&config.ffmpeg_path).args([ "-hide_banner", "-list_options", "true", "-f", "dshow", "-i", &format!("video={}", config.unique_id), ]), WINDOWS_CAMERA_INVENTORY_TIMEOUT, ); let probe = match output { Ok(output) => { classify_windows_dshow_mode_probe(&String::from_utf8_lossy(&output.stderr)) } Err(error) => { tracing::warn!("[camera-modes] DirectShow mode probe failed: {error}"); return WindowsDshowModeProbe::Unreadable; } }; if let WindowsDshowModeProbe::Modes(modes) = &probe { tracing::info!( "[camera-modes] DirectShow advertises {} mode(s), {} MJPEG, in {}ms: {}", modes.modes.len(), modes.mjpeg_count(), started_at.elapsed().as_millis(), modes.summary() ); } probe } enum CameraPreviewAttempt { ProducedFrames, Stopped, FailedBeforeFirstFrame(String), } /// One rung of the start ladder, sized: the box the camera fills, the /// size its frames are piped at, and the session rate. struct WindowsCameraAttemptPlan<'a> { attempt: &'a WindowsCameraCaptureAttempt, target: (u32, u32), output: (u32, u32), fps: u32, frame_len: usize, first_frame_timeout: Duration, } fn run_windows_camera_preview_attempt( config: &NativeCameraPreviewConfig, shared: &Arc>, startup_tx: &std_mpsc::Sender, stop_flag: &Arc, plan: WindowsCameraAttemptPlan<'_>, ) -> CameraPreviewAttempt { let (width, height) = plan.output; let frame_len = plan.frame_len; let first_frame_timeout = plan.first_frame_timeout; let attempt_started_at = Instant::now(); // Fixed before the spawn: a slow spawn spends this attempt's budget, // never the startup receiver's. let first_frame_deadline = attempt_started_at + first_frame_timeout; let args = windows_camera_preview_ffmpeg_args_for(config, plan.attempt, plan.output, plan.fps); let mut command = Command::new(&config.ffmpeg_path); command .args(&args) .stdin(Stdio::null()) .stdout(Stdio::piped()) .stderr(Stdio::piped()); let mut child = match spawn_owned_std(&mut command) { Ok(child) => child, Err(error) => { return CameraPreviewAttempt::FailedBeforeFirstFrame(format!( "could not start {}: {error}", config.ffmpeg_path )); } }; if Instant::now() >= first_frame_deadline { let _ = child.kill(); let _ = child.wait(); return CameraPreviewAttempt::FailedBeforeFirstFrame(format!( "FFmpeg took longer than {} ms to start", first_frame_timeout.as_millis() )); } let Some(mut stdout) = child.stdout.take() else { let _ = child.kill(); let _ = child.wait(); return CameraPreviewAttempt::FailedBeforeFirstFrame( "FFmpeg exposed no stdout".to_string(), ); }; let stderr = collect_stderr(child.stderr.take()); let child = Arc::new(StdMutex::new(child)); let done = Arc::new(AtomicBool::new(false)); let race = Arc::new(FirstFrameRace::default()); let killer = spawn_stop_flag_killer( Arc::clone(&child), Arc::clone(&done), Arc::clone(stop_flag), FirstFrameDeadline { at: first_frame_deadline, race: Arc::clone(&race), }, ); let mut startup_sent = false; let mut buffer = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) .frame_store .checkout_overwrite_buffer(frame_len); let mut outcome = None; let mut read_error = None; loop { match stdout.read_exact(&mut buffer) { Ok(()) => { if !startup_sent && !race.claim_live() { // The deadline passed while this frame was still in // the pipe: the killer owns the attempt. Reporting // Live now would hand the ladder a preview that is // already dead and never retried. The killer may not // have taken the child yet, so end FFmpeg here too: // otherwise it blocks on the unread pipe and the // `wait` below never returns. let _ = child .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) .kill(); break; } buffer = publish_bgra_frame(shared, width, height, buffer); if !startup_sent { let _ = startup_tx.send(windows_camera_live_startup( plan.attempt, plan.target, plan.output, plan.fps, )); startup_sent = true; outcome = Some(CameraPreviewAttempt::ProducedFrames); tracing::info!( camera = %config.unique_id, first_frame_ms = attempt_started_at.elapsed().as_millis() as u64, "Windows camera preview went live with {}, piped at {width}x{height}", plan.attempt.label() ); } } Err(error) => { if startup_sent { // Ran and then ended (stop, unplug, or EOF); the caller // must not retry a preview that already went live. outcome = Some(CameraPreviewAttempt::ProducedFrames); } else if stop_flag.load(Ordering::Acquire) { outcome = Some(CameraPreviewAttempt::Stopped); } else { read_error = Some(error); } break; } } } done.store(true, Ordering::Release); // Nothing reads the pipe any more; closing it lets an FFmpeg still // writing exit instead of blocking the `wait`. drop(stdout); let _ = child .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) .wait(); let _ = killer.join(); outcome.unwrap_or_else(|| { let timed_out = race.timed_out(); let cause = if timed_out { format!("no frame within {} ms", first_frame_timeout.as_millis()) } else { read_error.map_or_else( || "ended before the first frame".to_string(), |error| format!("ended before the first frame ({error})"), ) }; // A killed attempt has nothing more to say; waiting for its // stderr would spend the time the next attempt was reserved. let stderr_wait = if timed_out { Duration::ZERO } else { STDERR_TAIL_WAIT }; CameraPreviewAttempt::FailedBeforeFirstFrame(format!( "{cause}{}", stderr_tail(&stderr, stderr_wait) )) }) } struct FirstFrameDeadline { at: Instant, race: Arc, } const FIRST_FRAME_IDLE: u8 = 0; const FIRST_FRAME_LIVE: u8 = 1; const FIRST_FRAME_TIMED_OUT: u8 = 2; /// The attempt's first-frame race, settled exactly once. The reader claims /// Live the moment `read_exact` hands it a frame; the killer claims /// TimedOut when the deadline passes with no claim; only the winner acts. /// Two separate flags let a deadline landing between the frame's arrival /// and the Live flag kill a preview that had just gone live, which the /// ladder then treated as "ran live, do not retry". #[derive(Debug, Default)] pub(super) struct FirstFrameRace(std::sync::atomic::AtomicU8); impl FirstFrameRace { pub(super) fn claim_live(&self) -> bool { self.0 .compare_exchange( FIRST_FRAME_IDLE, FIRST_FRAME_LIVE, Ordering::AcqRel, Ordering::Acquire, ) .is_ok() } pub(super) fn claim_timed_out(&self) -> bool { self.0 .compare_exchange( FIRST_FRAME_IDLE, FIRST_FRAME_TIMED_OUT, Ordering::AcqRel, Ordering::Acquire, ) .is_ok() } pub(super) fn timed_out(&self) -> bool { self.0.load(Ordering::Acquire) == FIRST_FRAME_TIMED_OUT } } fn bgra_frame_len(width: u32, height: u32) -> Option { (width as usize) .checked_mul(height as usize)? .checked_mul(4) } fn collect_stderr(stderr: Option) -> Arc>> { let bytes = Arc::new(StdMutex::new(Vec::new())); if let Some(mut stderr) = stderr { let target = Arc::clone(&bytes); thread::spawn(move || { let mut buffer = Vec::new(); let _ = stderr.read_to_end(&mut buffer); *target .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) = buffer; }); } bytes } /// Kills the attempt's FFmpeg on Stop, or when it has produced no frame by /// the deadline: a dshow graph that opens but never delivers would /// otherwise block `read_exact` past the whole start budget. fn spawn_stop_flag_killer( child: Arc>, done: Arc, stop_flag: Arc, first_frame: FirstFrameDeadline, ) -> thread::JoinHandle<()> { thread::spawn(move || { while !done.load(Ordering::Acquire) { // Past the deadline the killer may act only if it wins the // race; a reader that already claimed Live keeps its child. let stalled = Instant::now() >= first_frame.at && first_frame.race.claim_timed_out(); if stop_flag.load(Ordering::Acquire) || stalled { let _ = child .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) .kill(); return; } thread::sleep(Duration::from_millis(50)); } }) } fn publish_bgra_frame( shared: &Arc>, width: u32, height: u32, bytes: Vec, ) -> Vec { let callback_started_at = Instant::now(); let publish_started_at = Instant::now(); let frame_len = bytes.len(); let frame_bytes = frame_len as u64; let mut guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); guard.record_pipe_frame_callback(callback_started_at); let now = Instant::now(); guard.frames_captured = guard.frames_captured.saturating_add(1); guard.frames_in_window = guard.frames_in_window.saturating_add(1); let window_started = *guard.window_started_at.get_or_insert(now); let elapsed = window_started.elapsed(); if elapsed >= Duration::from_millis(500) { guard.source_fps = Some(guard.frames_in_window as f64 / elapsed.as_secs_f64().max(0.001)); guard.frames_in_window = 0; guard.window_started_at = Some(now); } let sequence = guard.frames_captured; guard.frame_store.publish_with_metadata( sequence, width, height, PreviewCameraPixelFormat::Bgra8, (), now, bytes, ); let next_buffer = guard.frame_store.checkout_overwrite_buffer(frame_len); let publish_ms = publish_started_at.elapsed().as_secs_f64() * 1000.0; guard .capture_timings .record_valid_frame(0.0, 0.0, publish_ms, frame_bytes); next_buffer } /// How long a failed attempt waits for FFmpeg's last stderr lines. const STDERR_TAIL_WAIT: Duration = Duration::from_millis(300); /// The last FFmpeg lines of a reaped attempt. The reader thread publishes /// only at EOF, which can trail the child's exit by a few milliseconds. fn stderr_tail(stderr: &Arc>>, wait: Duration) -> String { let deadline = Instant::now() + wait; loop { let message = { let bytes = stderr .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); String::from_utf8_lossy(&bytes).trim().to_string() }; if !message.is_empty() { let lines = message .lines() .map(str::trim) .filter(|line| !line.is_empty()) .collect::>(); let tail = &lines[lines.len().saturating_sub(2)..]; return format!(": {}", tail.join(" | ")); } if Instant::now() >= deadline { return String::new(); } thread::sleep(Duration::from_millis(10)); } } } /// NV12 (4:2:0 bi-planar Y'CbCr) -> BGRA, parallelized across output rows. /// /// The conversion is platform-neutral even though AVFoundation is currently /// its only production caller. Keeping it outside the macOS module makes the /// pixel seam available to future Linux PipeWire capture without importing an /// Apple framework module. #[cfg(any(target_os = "macos", test))] #[allow(clippy::too_many_arguments)] #[cfg_attr(target_os = "windows", allow(dead_code))] fn nv12_to_bgra( y: &[u8], y_stride: usize, cbcr: &[u8], cbcr_stride: usize, width: usize, height: usize, full_range: bool, out: &mut [u8], ) { let row_bytes = width * 4; out.par_chunks_mut(row_bytes) .enumerate() .for_each(|(row, out_row)| { if row >= height { return; } let y_row = &y[row * y_stride..]; let cbcr_row = &cbcr[(row / 2) * cbcr_stride..]; for (x, pixel) in out_row.as_chunks_mut::<4>().0.iter_mut().enumerate() { let chroma = (x / 2) * 2; let (b, g, r) = if full_range { ycbcr_bt709_full_to_bgr(y_row[x], cbcr_row[chroma], cbcr_row[chroma + 1]) } else { ycbcr_bt709_video_to_bgr(y_row[x], cbcr_row[chroma], cbcr_row[chroma + 1]) }; pixel[0] = b; pixel[1] = g; pixel[2] = r; pixel[3] = 255; } }); } /// Packed 4:2:2 Y'CbCr -> BGRA, parallelized by row. `uyvy` selects the byte /// order: UYVY (`2vuy`, Cb Y0 Cr Y1) when true, YUY2 (`yuvs`, Y0 Cb Y1 Cr) /// when false. #[cfg(any(target_os = "macos", test))] fn yuv422_to_bgra( plane: &[u8], stride: usize, width: usize, height: usize, uyvy: bool, out: &mut [u8], ) { let row_bytes = width * 4; out.par_chunks_mut(row_bytes) .enumerate() .for_each(|(row, out_row)| { if row >= height { return; } let src = &plane[row * stride..]; for (pair, out8) in out_row.as_chunks_mut::<8>().0.iter_mut().enumerate() { let i = pair * 4; let (cb, y0, cr, y1) = if uyvy { (src[i], src[i + 1], src[i + 2], src[i + 3]) } else { (src[i + 1], src[i], src[i + 3], src[i + 2]) }; let (b0, g0, r0) = ycbcr_bt709_video_to_bgr(y0, cb, cr); let (b1, g1, r1) = ycbcr_bt709_video_to_bgr(y1, cb, cr); out8[0] = b0; out8[1] = g0; out8[2] = r0; out8[3] = 255; out8[4] = b1; out8[5] = g1; out8[6] = r1; out8[7] = 255; } }); } #[cfg(target_os = "macos")] mod macos { use std::slice; use super::*; use crate::camera_capture::{ CameraFormatSummary, NativeCameraPermission, choose_camera_format, }; use dispatch2::DispatchQueue; use objc2::rc::{Retained, autoreleasepool}; use objc2::runtime::{AnyObject, ProtocolObject}; use objc2::{AnyThread, DefinedClass, define_class, msg_send}; use objc2_av_foundation::{ AVAuthorizationStatus, AVCaptureConnection, AVCaptureDevice, AVCaptureDeviceFormat, AVCaptureDeviceInput, AVCaptureOutput, AVCaptureSession, AVCaptureSessionPresetInputPriority, AVCaptureVideoDataOutput, AVCaptureVideoDataOutputSampleBufferDelegate, AVMediaTypeVideo, }; use objc2_core_foundation::{CFString, CFType}; use objc2_core_media::{ CMSampleBuffer, CMTime, CMVideoFormatDescriptionGetDimensions, kCMSampleBufferAttachmentKey_DroppedFrameReason, kCMSampleBufferDroppedFrameReason_Discontinuity, kCMSampleBufferDroppedFrameReason_FrameWasLate, kCMSampleBufferDroppedFrameReason_OutOfBuffers, }; use objc2_core_video::{ CVPixelBuffer, CVPixelBufferGetBaseAddress, CVPixelBufferGetBaseAddressOfPlane, CVPixelBufferGetBytesPerRow, CVPixelBufferGetBytesPerRowOfPlane, CVPixelBufferGetHeight, CVPixelBufferGetHeightOfPlane, CVPixelBufferGetPixelFormatType, CVPixelBufferGetPlaneCount, CVPixelBufferGetWidth, CVPixelBufferLockBaseAddress, CVPixelBufferLockFlags, CVPixelBufferUnlockBaseAddress, kCVPixelBufferHeightKey, kCVPixelBufferPixelFormatTypeKey, kCVPixelBufferWidthKey, kCVPixelFormatType_32BGRA, kCVPixelFormatType_420YpCbCr8BiPlanarFullRange, kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange, kCVPixelFormatType_422YpCbCr8, kCVPixelFormatType_422YpCbCr8_yuvs, }; use objc2_foundation::{NSDictionary, NSNumber, NSObject, NSObjectProtocol, NSString}; unsafe extern "C-unwind" { /// Borrow an existing CoreMedia attachment without retaining or allocating on the /// AVFoundation callback queue. objc2-core-media gates its owning wrapper behind the /// optional CMAttachment feature, so keep this narrow declaration local. #[link_name = "CMGetAttachment"] fn cm_get_attachment_borrowed( target: &CFType, key: &CFString, attachment_mode_out: *mut u32, ) -> *const CFType; } struct CameraDelegateIvars { shared: Arc>, } define_class!( #[unsafe(super(NSObject))] #[thread_kind = AnyThread] #[ivars = CameraDelegateIvars] struct CameraPreviewDelegate; unsafe impl NSObjectProtocol for CameraPreviewDelegate {} unsafe impl AVCaptureVideoDataOutputSampleBufferDelegate for CameraPreviewDelegate { #[unsafe(method(captureOutput:didOutputSampleBuffer:fromConnection:))] fn capture_output( &self, _output: &AVCaptureOutput, sample_buffer: &CMSampleBuffer, _connection: &AVCaptureConnection, ) { copy_sample_buffer(sample_buffer, &self.ivars().shared); } #[unsafe(method(captureOutput:didDropSampleBuffer:fromConnection:))] fn capture_drop( &self, _output: &AVCaptureOutput, sample_buffer: &CMSampleBuffer, _connection: &AVCaptureConnection, ) { let reason = capture_drop_reason(sample_buffer); let mut guard = self .ivars() .shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); guard.dropped_frames = guard.dropped_frames.saturating_add(1); guard.capture_drop_reasons.record(reason); } } ); impl CameraPreviewDelegate { fn new(shared: Arc>) -> Retained { let delegate = Self::alloc().set_ivars(CameraDelegateIvars { shared }); unsafe { msg_send![super(delegate), init] } } } fn capture_drop_reason(sample_buffer: &CMSampleBuffer) -> CameraCaptureDropReason { // SAFETY: CMSampleBuffer is a CoreFoundation attachment bearer. AVFoundation owns both the // sample buffer and its attachment throughout this callback, so the borrowed attachment is // valid for these bounded type/constant comparisons. let bearer = unsafe { &*(std::ptr::from_ref(sample_buffer).cast::()) }; let reason = unsafe { cm_get_attachment_borrowed( bearer, kCMSampleBufferAttachmentKey_DroppedFrameReason, std::ptr::null_mut(), ) }; classify_capture_drop_reason_value(unsafe { reason.as_ref() }) } pub(super) fn classify_capture_drop_reason_value( reason: Option<&CFType>, ) -> CameraCaptureDropReason { let Some(reason) = reason else { return CameraCaptureDropReason::Unknown; }; let Some(reason) = reason.downcast_ref::() else { return CameraCaptureDropReason::Unknown; }; if reason == unsafe { kCMSampleBufferDroppedFrameReason_FrameWasLate } { CameraCaptureDropReason::FrameWasLate } else if reason == unsafe { kCMSampleBufferDroppedFrameReason_OutOfBuffers } { CameraCaptureDropReason::OutOfBuffers } else if reason == unsafe { kCMSampleBufferDroppedFrameReason_Discontinuity } { CameraCaptureDropReason::Discontinuity } else { CameraCaptureDropReason::Unknown } } pub fn run_native_camera_preview( config: NativeCameraPreviewConfig, shared: Arc>, stop_rx: std_mpsc::Receiver<()>, startup_tx: std_mpsc::Sender, ) { autoreleasepool(|_| match start_session(config, Arc::clone(&shared)) { Ok(session) => { let _ = startup_tx.send(NativeCameraStartup::Live { requested_width: session.requested_width, requested_height: session.requested_height, selected_format_width: session.selected_format_width, selected_format_height: session.selected_format_height, selected_format_min_fps: session.selected_format_min_fps, selected_format_max_fps: session.selected_format_max_fps, width: session.width, height: session.height, selected_fps: session.selected_fps, message: session.message, }); watch_system_effects_until_stop(&session.device, &shared, &stop_rx); unsafe { session.session.stopRunning(); session.output.setSampleBufferDelegate_queue(None, None); } } Err(error) => { let _ = startup_tx.send(error); } }); } /// Plan 258 S4: until the camera is told to stop, reads macOS Video /// Effects on the device every `MACOS_POLL_INTERVAL` into the shared /// state the status poll publishes. Apps can't turn these off, so this /// only reports them. fn watch_system_effects_until_stop( device: &AVCaptureDevice, shared: &Arc>, stop_rx: &std_mpsc::Receiver<()>, ) { loop { let effect = autoreleasepool(|_| read_system_effect(device)); shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) .system_effect = effect; match stop_rx.recv_timeout(crate::camera_system_effect::MACOS_POLL_INTERVAL) { Err(std_mpsc::RecvTimeoutError::Timeout) => {} Ok(()) | Err(std_mpsc::RecvTimeoutError::Disconnected) => return, } } } /// The device's Video Effects flags. Each getter is asked only when the /// running macOS has it (Portrait 12, Studio Light 13, background /// replacement 15); a missing one reads as off. `None` when the system /// has none of them, so the status stays absent. fn read_system_effect(device: &AVCaptureDevice) -> Option { let responds = |selector: objc2::runtime::Sel| -> bool { let responds: bool = unsafe { msg_send![device, respondsToSelector: selector] }; responds }; let portrait_known = responds(objc2::sel!(isPortraitEffectActive)); let studio_light_known = responds(objc2::sel!(isStudioLightActive)); let replacement_known = responds(objc2::sel!(isBackgroundReplacementActive)); if !portrait_known && !studio_light_known && !replacement_known { return None; } let portrait = portrait_known && unsafe { device.isPortraitEffectActive() }; let studio_light = studio_light_known && unsafe { device.isStudioLightActive() }; let replacement = replacement_known && unsafe { device.isBackgroundReplacementActive() }; Some(crate::camera_system_effect::macos_effect( portrait, replacement, studio_light, )) } struct CameraSession { device: Retained, session: Retained, output: Retained, _input: Retained, _delegate: Retained, _queue: dispatch2::DispatchRetained, requested_width: u32, requested_height: u32, selected_format_width: u32, selected_format_height: u32, selected_format_min_fps: f64, selected_format_max_fps: f64, width: u32, height: u32, selected_fps: f64, message: Option, } fn start_session( config: NativeCameraPreviewConfig, shared: Arc>, ) -> Result { let permission = native_camera_permission(); if permission != NativeCameraPermission::Authorized { return Err(NativeCameraStartup::PermissionNeeded( permission_message(permission).to_string(), )); } let unique_id = NSString::from_str(&config.unique_id); let Some(device) = (unsafe { AVCaptureDevice::deviceWithUniqueID(&unique_id) }) else { return Err(NativeCameraStartup::DeviceMissing(format!( "Camera device is missing: {}", config.camera_id ))); }; let selected = select_camera_format(&device, &config.camera_id, &config.layout, &config.video) .ok_or_else(|| { NativeCameraStartup::Failed("Camera did not report usable formats.".to_string()) })?; crate::camera_capture::record_negotiated_camera_format( &config.camera_id, selected.format.width, selected.format.height, ); tracing::info!( "Camera capture format selected: {}x{}@{:.2} (requested {}x{}@{}, ceiling {:?})", selected.format.width, selected.format.height, selected.format.max_fps, selected.requested_width, selected.requested_height, config.video.fps, crate::camera_capture::camera_format_ceiling(&config.camera_id), ); let configured_fps = configure_device(&device, &selected, config.video.fps)?; let input = unsafe { AVCaptureDeviceInput::deviceInputWithDevice_error(&device) }.map_err( |error| NativeCameraStartup::Failed(format!("Could not open camera: {error}")), )?; let session = unsafe { AVCaptureSession::new() }; let output = unsafe { AVCaptureVideoDataOutput::new() }; let delegate = CameraPreviewDelegate::new(shared); // Camera delivery feeds the live preview and the recording. Under // system load (2026-08-31 field capture: load ~10/10 cores, camera // delivered 17fps into a healthy callback) the default QoS lets // macOS starve capture before our own encode/diagnostics work. // Targeting the UserInitiated global queue at CREATION confers that // QoS; a property setter after creation is a libdispatch client bug // that SIGTRAPs on every camera start (the 0.9.88 crash loop — // "dispatch queue property setter called after activation"). let queue = DispatchQueue::new_with_target( "com.videorc.preview.camera", None, Some(&DispatchQueue::global_queue( dispatch2::GlobalQueueIdentifier::QualityOfService( dispatch2::DispatchQoS::UserInitiated, ), )), ); // AVCaptureSession mutators (`addInput`/`addOutput`/`startRunning`) can also // raise NSExceptions for sources AVFoundation refuses; guard them so a // refusal fails the camera gracefully instead of aborting the backend. let session_result = unsafe { objc2::exception::catch(std::panic::AssertUnwindSafe(|| { session.beginConfiguration(); if session.canSetSessionPreset(AVCaptureSessionPresetInputPriority) { session.setSessionPreset(AVCaptureSessionPresetInputPriority); } // VIDEORC_CAMERA_NATIVE_FORMAT=1 opts the camera out of the // BGRA zero-copy preference: the device's native YUV wire // format halves-or-better the per-frame bytes crossing the // system CMIO/XPC camera path AND removes the system-side // format conversion (UVCAssistant measured at 45% CPU // converting for us, 2026-08-31). Our own CPU converter // takes over; A/B with the self_cpu telemetry before making // it the default via Metal YUV ingestion. let camera_native_format_override = std::env::var("VIDEORC_CAMERA_NATIVE_FORMAT").as_deref() == Ok("1"); let prefer_zero_copy_source_format = crate::metal_compositor::source_zerocopy_enabled() && !camera_native_format_override; let capture_pixel_format = preferred_capture_pixel_format(&output, prefer_zero_copy_source_format); tracing::info!( "Native camera capture pixel format: {} ({})", format_fourcc(capture_pixel_format), if capture_pixel_format == kCVPixelFormatType_32BGRA { "BGRA, zero-copy source import" } else { "Y'CbCr, reduced bandwidth" } ); set_capture_video_settings( &output, capture_pixel_format, selected.output_width, selected.output_height, ); output.setAlwaysDiscardsLateVideoFrames(true); output.setSampleBufferDelegate_queue( Some(ProtocolObject::from_ref(&*delegate)), Some(&queue), ); if !session.canAddInput(&input) { session.commitConfiguration(); return Err(NativeCameraStartup::Failed( "AVFoundation refused the camera input.".to_string(), )); } session.addInput(&input); if !session.canAddOutput(&output) { session.commitConfiguration(); return Err(NativeCameraStartup::Failed( "AVFoundation refused the camera preview output.".to_string(), )); } session.addOutput(&output); session.commitConfiguration(); session.startRunning(); Ok(negotiated_camera_fps( active_camera_fps(&device), Some(configured_fps), selected.format.max_fps, )) })) }; let negotiated_fps = match session_result { Err(exception) => { return Err(NativeCameraStartup::Failed(format!( "Camera capture session was rejected by AVFoundation: {}", describe_camera_exception(exception) ))); } Ok(Err(startup)) => return Err(startup), Ok(Ok(negotiated_fps)) => negotiated_fps, }; let layout_detail = layout_detail(&config.layout); let message = selected .fallback_reason .map(|reason| format!("{reason} {layout_detail}")) .or_else(|| { Some(format!( "Native camera preview running with {}x{} at {:.0} fps. {layout_detail}", selected.output_width, selected.output_height, negotiated_fps )) }); Ok(CameraSession { device, session, output, _input: input, _delegate: delegate, _queue: queue, requested_width: selected.requested_width, requested_height: selected.requested_height, selected_format_width: selected.format.width, selected_format_height: selected.format.height, selected_format_min_fps: selected.format.min_fps, selected_format_max_fps: selected.format.max_fps, width: selected.output_width, height: selected.output_height, selected_fps: negotiated_fps, message, }) } struct NativeCameraFormatSelection { format: CameraFormatSummary, native_format: Retained, requested_width: u32, requested_height: u32, output_width: u32, output_height: u32, fallback_reason: Option, } fn select_camera_format( camera: &AVCaptureDevice, camera_id: &str, layout: &LayoutSettings, video: &VideoSettings, ) -> Option { let formats = unsafe { camera.formats() }; let mut entries = Vec::new(); for index in 0..formats.count() { let native_format = formats.objectAtIndex(index); let description = unsafe { native_format.formatDescription() }; let dimensions = unsafe { CMVideoFormatDescriptionGetDimensions(&description) }; let ranges = unsafe { native_format.videoSupportedFrameRateRanges() }; for range_index in 0..ranges.count() { let range = ranges.objectAtIndex(range_index); entries.push(( CameraFormatSummary { width: dimensions.width.max(0) as u32, height: dimensions.height.max(0) as u32, min_fps: unsafe { range.minFrameRate() }, max_fps: unsafe { range.maxFrameRate() }, }, native_format.clone(), )); } } let summaries = entries .iter() .map(|(summary, _)| summary.clone()) .collect::>(); let (mut target_width, mut target_height) = camera_capture_target_dimensions(layout, video); // An armed adaptive ceiling (Cam Link-class USB bandwidth shortfall) // caps the requested capture box; the chooser then prefers the // highest format inside it (1080p60 on the Cam Link 4K). if let Some((ceiling_width, ceiling_height)) = crate::camera_capture::camera_format_ceiling(camera_id) { target_width = target_width.min(ceiling_width); target_height = target_height.min(ceiling_height); } let choice = choose_camera_format(&summaries, target_width, target_height, video.fps)?; let selected_entry = entries .into_iter() .find(|(summary, _)| *summary == choice.format)?; let (output_width, output_height) = fit_camera_source_in_target_box( selected_entry.0.width, selected_entry.0.height, target_width, target_height, ); Some(NativeCameraFormatSelection { format: selected_entry.0, native_format: selected_entry.1, requested_width: target_width, requested_height: target_height, output_width, output_height, fallback_reason: choice.fallback_reason, }) } fn configure_device( device: &AVCaptureDevice, format: &NativeCameraFormatSelection, requested_fps: u32, ) -> Result { unsafe { device.lockForConfiguration() }.map_err(|error| { NativeCameraStartup::Failed(format!("Could not configure camera: {error}")) })?; // `setActiveFormat` and the frame-duration setters raise Objective-C // NSExceptions for inputs the device rejects — capture cards such as the // Cam Link 4K only run at a fixed fractional rate (e.g. 59.94fps), so an // integer frame duration like 1/60 is "not supported". A foreign exception // unwinding into Rust aborts the entire backend (SIGABRT), so every // throwing call is guarded with `objc2::exception::catch`. The active format // is essential (fail gracefully if rejected); the frame-duration is // best-effort (keep the device's native cadence if rejected). let format_result = unsafe { objc2::exception::catch(std::panic::AssertUnwindSafe(|| { device.setActiveFormat(&format.native_format) })) }; if let Err(exception) = format_result { unsafe { device.unlockForConfiguration() }; return Err(NativeCameraStartup::Failed(format!( "Camera rejected the selected {}x{} format: {}", format.output_width, format.output_height, describe_camera_exception(exception) ))); } // Resolve the requested rate against the ACTIVE format's own advertised // ranges, and at a range endpoint request the range's own CMTime // verbatim — AVFoundation validates the duration against those // rationals exactly, so no decimal approximation of a fractional // endpoint (29.97, 30.00003) survives the comparison. let ranges = unsafe { format.native_format.videoSupportedFrameRateRanges() }; let range_bounds = (0..ranges.count()) .map(|index| { let range = ranges.objectAtIndex(index); unsafe { (range.minFrameRate(), range.maxFrameRate()) } }) .collect::>(); tracing::info!( "Camera capture configured: {}x{} (requested {}x{}), advertised ranges {:?}, requesting {} fps", format.format.width, format.format.height, format.requested_width, format.requested_height, range_bounds, requested_fps, ); let mut applied_fps = None; if let Some(resolution) = resolve_camera_frame_rate(requested_fps, &range_bounds) { let range = ranges.objectAtIndex(resolution.range_index); let frame_duration = match resolution.endpoint { CameraFrameRateEndpoint::RangeMax => unsafe { range.minFrameDuration() }, CameraFrameRateEndpoint::RangeMin => unsafe { range.maxFrameDuration() }, CameraFrameRateEndpoint::Interior => { // Nanosecond timescale keeps an interior rate within any // range wide enough to contain it. let timescale = 1_000_000_000_i32; let value = (f64::from(timescale) / resolution.effective_fps).round() as i64; unsafe { CMTime::new(value.max(1), timescale) } } }; let effective_fps = resolution.effective_fps; let frame_rate_result = unsafe { objc2::exception::catch(std::panic::AssertUnwindSafe(|| { device.setActiveVideoMinFrameDuration(frame_duration); device.setActiveVideoMaxFrameDuration(frame_duration); })) }; if let Err(exception) = frame_rate_result { tracing::warn!( "Camera kept its native frame cadence ({effective_fps:.3} fps frame duration was rejected): {}", describe_camera_exception(exception) ); } else { tracing::info!( "Camera frame duration set: {effective_fps:.3} fps ({:?} of range {})", resolution.endpoint, resolution.range_index, ); applied_fps = Some(effective_fps); } } let negotiated_fps = negotiated_camera_fps( active_camera_fps(device), applied_fps, format.format.max_fps, ); unsafe { device.unlockForConfiguration() }; Ok(negotiated_fps) } fn active_camera_fps(device: &AVCaptureDevice) -> Option { unsafe { objc2::exception::catch(std::panic::AssertUnwindSafe(|| { let seconds = device.activeVideoMinFrameDuration().seconds(); if seconds.is_finite() && seconds > 0.0 { Some(1.0 / seconds) } else { None } })) } .ok() .flatten() } /// Format an Objective-C exception caught around an AVFoundation call into a /// human-readable reason (name + reason), for diagnostics instead of a crash. fn describe_camera_exception( exception: Option>, ) -> String { match exception { Some(exception) => format!("{exception:?}"), None => "unknown Objective-C exception".to_string(), } } /// Whether a capture pixel format is a Y'CbCr format the conversion path handles. fn is_yuv_capture_format(format: u32) -> bool { format == kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange || format == kCVPixelFormatType_420YpCbCr8BiPlanarFullRange || format == kCVPixelFormatType_422YpCbCr8 || format == kCVPixelFormatType_422YpCbCr8_yuvs } /// Pick the best capture pixel format for the current source import mode. /// Source zero-copy needs a BGRA CoreVideo texture view today; otherwise keep the /// previous bandwidth-efficient Y'CbCr preference. fn preferred_capture_pixel_format( output: &AVCaptureVideoDataOutput, prefer_zero_copy_source_format: bool, ) -> u32 { let available = unsafe { output.availableVideoCVPixelFormatTypes() }; let formats: Vec = (0..available.count()) .map(|index| available.objectAtIndex(index).unsignedIntValue()) .collect(); tracing::info!( "Camera advertises capture formats (native first): {}", formats .iter() .map(|format| format_fourcc(*format)) .collect::>() .join(", ") ); select_preferred_capture_pixel_format(&formats, prefer_zero_copy_source_format) } /// Pick the best capture pixel format from an advertised list. /// 4:2:0 / 4:2:2 Y'CbCr are ~3/8 and ~1/2 the bytes of BGRA, so a bandwidth-limited /// USB capture card (e.g. a Cam Link 4K at 4K) can deliver more frames per second. /// `availableVideoCVPixelFormatTypes` is ordered most-efficient-first, so without /// source zero-copy the first entry is the device's native wire format. Requesting a /// *non*-native format forces a slow host conversion (NV12 on a 4:2:2 card drops it /// to a few fps), so we take the first advertised format we can convert ourselves; /// BGRA only if no YUV is offered. pub(super) fn select_preferred_capture_pixel_format( formats: &[u32], prefer_zero_copy_source_format: bool, ) -> u32 { if prefer_zero_copy_source_format && formats.contains(&kCVPixelFormatType_32BGRA) { return kCVPixelFormatType_32BGRA; } formats .iter() .copied() .find(|format| is_yuv_capture_format(*format)) .unwrap_or(kCVPixelFormatType_32BGRA) } unsafe fn set_capture_video_settings( output: &AVCaptureVideoDataOutput, pixel_format_type: u32, width: u32, height: u32, ) { let pixel_format_key: &NSString = unsafe { &*(kCVPixelBufferPixelFormatTypeKey as *const _ as *const NSString) }; let width_key: &NSString = unsafe { &*(kCVPixelBufferWidthKey as *const _ as *const NSString) }; let height_key: &NSString = unsafe { &*(kCVPixelBufferHeightKey as *const _ as *const NSString) }; let pixel_format = NSNumber::new_u32(pixel_format_type); let width = NSNumber::new_u32(width); let height = NSNumber::new_u32(height); let settings = NSDictionary::::from_slices( &[pixel_format_key, width_key, height_key], &[&pixel_format, &width, &height], ); let settings = unsafe { settings.cast_unchecked::() }; unsafe { output.setVideoSettings(Some(settings)); } } fn copy_sample_buffer( sample_buffer: &CMSampleBuffer, shared: &Arc>, ) { let callback_started_at = Instant::now(); let sample_pts_seconds = cm_time_seconds(unsafe { sample_buffer.presentation_time_stamp() }); { let mut guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); guard .capture_timings .record_callback_at(callback_started_at); guard.capture_timings.record_sample_pts(sample_pts_seconds); guard.capture_callback_count = guard.capture_callback_count.saturating_add(1); } let Some(pixel_buffer) = (unsafe { sample_buffer.image_buffer() }) else { let mut guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); guard.dropped_frames = guard.dropped_frames.saturating_add(1); return; }; let pixel_format = CVPixelBufferGetPixelFormatType(&pixel_buffer); if !is_supported_capture_format(pixel_format) { let mut guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); guard.dropped_frames = guard.dropped_frames.saturating_add(1); return; } let width = CVPixelBufferGetWidth(&pixel_buffer) as u32; let height = CVPixelBufferGetHeight(&pixel_buffer) as u32; if width == 0 || height == 0 { let mut guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); guard.dropped_frames = guard.dropped_frames.saturating_add(1); return; } let width_usize = width as usize; let height_usize = height as usize; let row_bytes = width_usize * 4; let frame_bytes = row_bytes * height_usize; let source_zerocopy_enabled = crate::metal_compositor::source_zerocopy_enabled(); let source_pixel_buffer = if source_zerocopy_enabled && pixel_format == kCVPixelFormatType_32BGRA { Some(crate::frame_store::RetainedPixelBuffer::new( pixel_buffer.clone(), )) } else { None }; let skip_cpu_copy = should_skip_camera_capture_cpu_copy(source_pixel_buffer.is_some()); let (bytes, pixel_buffer_lock_ms, row_copy_ms) = if skip_cpu_copy { (Vec::new(), 0.0, 0.0) } else { let lock_started_at = Instant::now(); let lock_result = unsafe { CVPixelBufferLockBaseAddress(&pixel_buffer, CVPixelBufferLockFlags::ReadOnly) }; let pixel_buffer_lock_ms = lock_started_at.elapsed().as_secs_f64() * 1000.0; if lock_result != 0 { let mut guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); guard.dropped_frames = guard.dropped_frames.saturating_add(1); return; } let mut bytes = { let mut guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); if let Some(buffer) = guard.frame_store.checkout_spare_buffer(frame_bytes) { buffer } else { guard.frame_store.record_buffer_allocation(); drop(guard); vec![0; frame_bytes] } }; // Fill `bytes` with BGRA, converting from whichever pixel format the device // delivers (BGRA passthrough, or NV12 / UYVY Y'CbCr -> BGRA). The downstream // pipeline stays BGRA, so only this fill changes per format. let copy_started_at = Instant::now(); let filled = unsafe { fill_bgra_from_pixel_buffer( &pixel_buffer, pixel_format, width_usize, height_usize, &mut bytes, ) }; let row_copy_ms = copy_started_at.elapsed().as_secs_f64() * 1000.0; unsafe { CVPixelBufferUnlockBaseAddress(&pixel_buffer, CVPixelBufferLockFlags::ReadOnly); } if !filled { let mut guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); guard.dropped_frames = guard.dropped_frames.saturating_add(1); return; } (bytes, pixel_buffer_lock_ms, row_copy_ms) }; let publish_started_at = Instant::now(); let mut guard = shared .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()); let now = Instant::now(); guard.frames_captured = guard.frames_captured.saturating_add(1); guard.capture_pixel_format = Some(pixel_format); guard.frames_in_window = guard.frames_in_window.saturating_add(1); let window_started = *guard.window_started_at.get_or_insert(now); let elapsed = window_started.elapsed(); if elapsed >= Duration::from_millis(500) { guard.source_fps = Some(guard.frames_in_window as f64 / elapsed.as_secs_f64().max(0.001)); guard.frames_in_window = 0; guard.window_started_at = Some(now); } let sequence = guard.frames_captured; guard.frame_store.publish_with_source_handles( sequence, width, height, PreviewCameraPixelFormat::Bgra8, now, bytes, None, source_pixel_buffer, ); let publish_ms = publish_started_at.elapsed().as_secs_f64() * 1000.0; guard.capture_timings.record_valid_frame( pixel_buffer_lock_ms, row_copy_ms, publish_ms, frame_bytes as u64, ); } /// Render a CoreVideo pixel-format OSType as its FourCC string (e.g. `420v`). pub(super) fn format_fourcc(format: u32) -> String { String::from_utf8_lossy(&format.to_be_bytes()).into_owned() } /// Capture pixel formats the conversion path can turn into BGRA. fn is_supported_capture_format(format: u32) -> bool { format == kCVPixelFormatType_32BGRA || is_yuv_capture_format(format) } /// Fill `out` (width*height*4 BGRA) from a locked capture `CVPixelBuffer`, /// converting Y'CbCr (NV12 / UYVY) to BGRA when needed. Returns false if the /// buffer's planes are unexpectedly missing. The caller holds the buffer lock. unsafe fn fill_bgra_from_pixel_buffer( pixel_buffer: &CVPixelBuffer, pixel_format: u32, width: usize, height: usize, out: &mut [u8], ) -> bool { if pixel_format == kCVPixelFormatType_32BGRA { let base = CVPixelBufferGetBaseAddress(pixel_buffer); if base.is_null() { return false; } let stride = CVPixelBufferGetBytesPerRow(pixel_buffer); let row_bytes = width * 4; let source = base.cast::(); for row in 0..height { let source_row = unsafe { slice::from_raw_parts(source.add(row * stride), row_bytes) }; out[row * row_bytes..(row + 1) * row_bytes].copy_from_slice(source_row); } return true; } if pixel_format == kCVPixelFormatType_422YpCbCr8 || pixel_format == kCVPixelFormatType_422YpCbCr8_yuvs { let base = CVPixelBufferGetBaseAddress(pixel_buffer); if base.is_null() { return false; } let stride = CVPixelBufferGetBytesPerRow(pixel_buffer); let plane = unsafe { slice::from_raw_parts(base.cast::(), stride * height) }; // '2vuy' is UYVY (Cb Y0 Cr Y1); 'yuvs' is YUY2 (Y0 Cb Y1 Cr). let uyvy = pixel_format == kCVPixelFormatType_422YpCbCr8; yuv422_to_bgra(plane, stride, width, height, uyvy, out); return true; } // Bi-planar NV12: plane 0 = Y, plane 1 = interleaved CbCr (Cb, Cr, ...). if CVPixelBufferGetPlaneCount(pixel_buffer) < 2 { return false; } let full_range = pixel_format == kCVPixelFormatType_420YpCbCr8BiPlanarFullRange; let y_base = CVPixelBufferGetBaseAddressOfPlane(pixel_buffer, 0); let cbcr_base = CVPixelBufferGetBaseAddressOfPlane(pixel_buffer, 1); if y_base.is_null() || cbcr_base.is_null() { return false; } let y_stride = CVPixelBufferGetBytesPerRowOfPlane(pixel_buffer, 0); let cbcr_stride = CVPixelBufferGetBytesPerRowOfPlane(pixel_buffer, 1); let y_height = CVPixelBufferGetHeightOfPlane(pixel_buffer, 0); let cbcr_height = CVPixelBufferGetHeightOfPlane(pixel_buffer, 1); let y = unsafe { slice::from_raw_parts(y_base.cast::(), y_stride * y_height) }; let cbcr = unsafe { slice::from_raw_parts(cbcr_base.cast::(), cbcr_stride * cbcr_height) }; nv12_to_bgra( y, y_stride, cbcr, cbcr_stride, width, height, full_range, out, ); true } fn cm_time_seconds(time: CMTime) -> Option { let seconds = unsafe { time.seconds() }; seconds.is_finite().then_some(seconds) } fn native_camera_permission() -> NativeCameraPermission { let Some(video_media_type) = (unsafe { AVMediaTypeVideo }) else { return NativeCameraPermission::Unknown; }; match unsafe { AVCaptureDevice::authorizationStatusForMediaType(video_media_type) } { status if status == AVAuthorizationStatus::Authorized => { NativeCameraPermission::Authorized } status if status == AVAuthorizationStatus::NotDetermined => { NativeCameraPermission::NotDetermined } status if status == AVAuthorizationStatus::Denied => NativeCameraPermission::Denied, status if status == AVAuthorizationStatus::Restricted => { NativeCameraPermission::Restricted } _ => NativeCameraPermission::Unknown, } } fn permission_message(permission: NativeCameraPermission) -> &'static str { match permission { NativeCameraPermission::Authorized => "Camera permission is authorized.", NativeCameraPermission::NotDetermined => "Camera permission has not been granted yet.", NativeCameraPermission::Denied => "Camera permission is denied.", NativeCameraPermission::Restricted => "Camera permission is restricted by macOS.", NativeCameraPermission::Unknown => "Camera permission state is unknown.", } } fn layout_detail(layout: &LayoutSettings) -> String { format!( "Layout preserves {:?} fit, mirror {}, zoom {}%.", layout.camera_fit, if layout.camera_mirror { "on" } else { "off" }, layout.camera_zoom ) } } #[cfg(test)] mod tests { use std::sync::atomic::{AtomicUsize, Ordering}; use super::*; use crate::protocol::{ CameraCorner, CameraFit, CameraShape, CameraSize, CameraTransformMode, LayoutPreset, SideBySideCameraSide, SideBySideSplit, VideoPreset, }; use crate::storage::Database; use tokio::sync::{broadcast, oneshot}; #[test] fn capture_drop_reason_counts_preserve_every_bucket() { let mut counts = CameraCaptureDropReasonCounts::default(); for reason in [ CameraCaptureDropReason::FrameWasLate, CameraCaptureDropReason::OutOfBuffers, CameraCaptureDropReason::Discontinuity, CameraCaptureDropReason::Unknown, ] { counts.record(reason); } assert_eq!(counts.frame_was_late, 1); assert_eq!(counts.out_of_buffers, 1); assert_eq!(counts.discontinuity, 1); assert_eq!(counts.unknown, 1); assert_eq!(counts.total(), 4); } #[cfg(target_os = "macos")] #[test] fn capture_drop_reason_classifies_every_apple_fixture() { use objc2_core_foundation::{CFString, CFType}; use objc2_core_media::{ kCMSampleBufferAttachmentKey_DroppedFrameReason, kCMSampleBufferDroppedFrameReason_Discontinuity, kCMSampleBufferDroppedFrameReason_FrameWasLate, kCMSampleBufferDroppedFrameReason_OutOfBuffers, }; fn as_cf_type(value: &CFString) -> &CFType { // SAFETY: Every concrete CoreFoundation value has the CFType root representation. unsafe { &*(std::ptr::from_ref(value).cast::()) } } for (value, expected) in [ ( unsafe { kCMSampleBufferDroppedFrameReason_FrameWasLate }, CameraCaptureDropReason::FrameWasLate, ), ( unsafe { kCMSampleBufferDroppedFrameReason_OutOfBuffers }, CameraCaptureDropReason::OutOfBuffers, ), ( unsafe { kCMSampleBufferDroppedFrameReason_Discontinuity }, CameraCaptureDropReason::Discontinuity, ), ( unsafe { kCMSampleBufferAttachmentKey_DroppedFrameReason }, CameraCaptureDropReason::Unknown, ), ] { assert_eq!( macos::classify_capture_drop_reason_value(Some(as_cf_type(value))), expected ); } assert_eq!( macos::classify_capture_drop_reason_value(None), CameraCaptureDropReason::Unknown ); } fn test_state() -> AppState { let (events, _) = broadcast::channel(16); AppState::new( "test-token".to_string(), 1234, events, Database::open_in_memory_for_tests(), ) } fn test_layout(camera_mirror: bool) -> LayoutSettings { LayoutSettings { layout_preset: LayoutPreset::CameraOnly, camera_transform_mode: CameraTransformMode::Preset, camera_transform: None, camera_corner: CameraCorner::TopRight, camera_size: CameraSize::Medium, camera_shape: CameraShape::Rectangle, camera_corner_radius_pct: 12, camera_aspect: crate::protocol::CameraAspect::Source, camera_margin: 24, camera_fit: CameraFit::Fill, camera_mirror, camera_zoom: 100, camera_offset_x: 0, camera_offset_y: 0, side_by_side_split: SideBySideSplit::Even, side_by_side_camera_side: SideBySideCameraSide::Right, vertical_screen_framing: crate::protocol::VerticalScreenFraming::Fill, horizontal_screen_framing: crate::protocol::HorizontalScreenFraming::Fit, arrangement_mode: crate::protocol::ArrangementMode::Preset, source_transform_overrides: std::collections::BTreeMap::new(), source_visibility: Default::default(), camera_look: Default::default(), camera_chroma_key_enabled: false, camera_chroma_key_color: "#00FF00".to_string(), camera_chroma_key_similarity_pct: 40, camera_chroma_key_smoothness_pct: 8, camera_chroma_key_spill_pct: 10, camera_chroma_key_edges: Default::default(), } } fn test_video() -> VideoSettings { VideoSettings { preset: VideoPreset::Stream1080p60, width: 1920, height: 1080, fps: 60, bitrate_kbps: 9000, } } fn test_camera_start_key( source_key: SourceKey, layout: &LayoutSettings, video: &VideoSettings, ) -> PreviewCameraStartKey { PreviewCameraStartKey { source_key, ffmpeg_path: "ffmpeg".to_string(), video: video.clone(), target_fps: video.fps, capture_target: camera_capture_target_dimensions(layout, video), } } fn test_camera_starting_status( source_key: &SourceKey, video: &VideoSettings, ) -> PreviewCameraStatus { PreviewCameraStatus { state: PreviewCameraState::Starting, camera_id: Some(source_key.id.clone()), device_unique_id: Some("fake-supervisor".to_string()), target_fps: video.fps, width: None, height: None, requested_width: None, requested_height: None, actual_width: None, actual_height: None, selected_format_width: None, selected_format_height: None, selected_format_min_fps: None, selected_format_max_fps: None, source_fps: None, frame_age_ms: None, frames_captured: 0, dropped_frames: 0, sequence: None, updated_at: Utc::now().to_rfc3339(), message: Some("Starting fake native camera.".to_string()), no_video: None, system_effect: None, } } fn test_camera_params( camera_id: Option<&str>, layout: &LayoutSettings, video: &VideoSettings, ) -> PreviewCameraStartParams { PreviewCameraStartParams { sources: SourceSelection { screen_id: None, window_id: None, camera_id: camera_id.map(str::to_string), microphone_id: None, test_pattern: false, }, layout: layout.clone(), video: video.clone(), ffmpeg_path: Some("ffmpeg".to_string()), } } fn test_prepared_camera_start( source_key: &SourceKey, layout: &LayoutSettings, video: &VideoSettings, lease: PreviewCameraStartLease, layout_intent_id: Option, ) -> PreparedCameraStart { PreparedCameraStart { camera_id: source_key.id.clone(), device_unique_id: "fake-supervisor".to_string(), ffmpeg_path: "ffmpeg".to_string(), target_fps: video.fps, source_key: source_key.clone(), params: test_camera_params(Some(&source_key.id), layout, video), lease, layout_intent_id, recovery: None, } } async fn assert_queued_camera_supervisor_survives_owner_transfer( next_layout_intent_id: Option, ) { let state = test_state(); let video = test_video(); let layout = test_layout(false); let source_key = SourceKey::camera("camera:avfoundation-native:queued-owner-transfer"); let start_key = test_camera_start_key(source_key.clone(), &layout, &video); state.publish_latest_layout_intent_id(100); let held_transition = acquire_preview_camera_transition(&state).await; let lease = match begin_camera_start( &state, start_key.clone(), &layout, test_camera_starting_status(&source_key, &video), Some(100), ) .await { PreviewCameraStartRegistration::Started { lease } => lease, other => panic!("first layout must own the queued generation: {other:?}"), }; let prepared = test_prepared_camera_start(&source_key, &layout, &video, lease.clone(), Some(100)); let transition_gate = Arc::clone(&state.preview_camera.lock().await.transition_gate); let queued_state = state.clone(); let (queued_tx, queued_rx) = oneshot::channel(); let queued = tokio::spawn(async move { let mut transition = Box::pin(transition_gate.lock_owned()); assert!( futures_util::poll!(&mut transition).is_pending(), "the held physical gate must queue the registered supervisor" ); let _ = queued_tx.send(()); let _transition = transition.await; ensure_registered_preview_camera_start_is_current(&queued_state, &prepared).await }); queued_rx.await.expect("camera supervisor queued"); { let _layout_admission = state.lock_layout_source_admission(); state.publish_latest_layout_intent_id(101); } let transfer = begin_camera_start( &state, start_key, &layout, test_camera_starting_status(&source_key, &video), next_layout_intent_id, ) .await; match next_layout_intent_id { Some(101) => assert!(matches!( transfer, PreviewCameraStartRegistration::JoinExisting { admitted_starting_identity: Some(_), .. } )), None => assert!(matches!( transfer, PreviewCameraStartRegistration::JoinExisting { admitted_starting_identity: None, .. } )), other => panic!("unexpected test owner transfer: {other:?}"), } drop(held_transition); tokio::time::timeout(Duration::from_secs(1), queued) .await .expect("queued camera supervisor must resume") .expect("queued camera supervisor task") .expect("owner transfer must preserve the registered generation"); let slot = state.preview_camera.lock().await; assert_eq!(slot.start_generation, lease.generation); assert_eq!(slot.starting.as_ref(), Some(&lease.key)); assert_eq!(slot.starting_layout_intent_id, next_layout_intent_id); } struct FakeNativeCameraControl { release_tx: std_mpsc::Sender<()>, stop_seen_rx: oneshot::Receiver<()>, exited_rx: oneshot::Receiver<()>, } async fn install_blocking_fake_native_camera( state: &AppState, live_sessions: Arc, max_live_sessions: Arc, ) -> FakeNativeCameraControl { let layout = test_layout(false); let video = test_video(); let source_key = SourceKey::camera("camera:avfoundation-native:fake-supervisor"); let (stop_tx, stop_rx) = std_mpsc::channel(); let (release_tx, release_rx) = std_mpsc::channel(); let (ready_tx, ready_rx) = oneshot::channel(); let (stop_seen_tx, stop_seen_rx) = oneshot::channel(); let (exited_tx, exited_rx) = oneshot::channel(); let thread_live_sessions = Arc::clone(&live_sessions); let thread_max_live_sessions = Arc::clone(&max_live_sessions); let join_handle = thread::Builder::new() .name("videorc-test-fake-camera".to_string()) .spawn(move || { let live = thread_live_sessions.fetch_add(1, Ordering::SeqCst) + 1; thread_max_live_sessions.fetch_max(live, Ordering::SeqCst); let _ = ready_tx.send(()); let _ = stop_rx.recv(); let _ = stop_seen_tx.send(()); let _ = release_rx.recv(); thread_live_sessions.fetch_sub(1, Ordering::SeqCst); let _ = exited_tx.send(()); }) .expect("spawn fake camera native thread"); tokio::time::timeout(Duration::from_secs(1), ready_rx) .await .expect("fake native camera readiness deadline") .expect("fake native camera readiness sender"); let shared = Arc::new(StdMutex::new(PreviewCameraShared::default())); let mut slot = state.preview_camera.lock().await; slot.disconnected = None; slot.start_generation = slot.start_generation.wrapping_add(1).max(1); let generation = slot.start_generation; slot.pending_stop_generation = None; slot.active_generation = Some(generation); slot.source_key = Some(source_key.clone()); slot.status = PreviewCameraStatus { state: PreviewCameraState::Live, camera_id: Some(source_key.id.clone()), device_unique_id: Some("fake-supervisor".to_string()), target_fps: video.fps, width: Some(video.width), height: Some(video.height), requested_width: Some(video.width), requested_height: Some(video.height), actual_width: Some(video.width), actual_height: Some(video.height), selected_format_width: Some(video.width), selected_format_height: Some(video.height), selected_format_min_fps: Some(f64::from(video.fps)), selected_format_max_fps: Some(f64::from(video.fps)), source_fps: Some(f64::from(video.fps)), frame_age_ms: Some(0), frames_captured: 1, dropped_frames: 0, sequence: Some(1), updated_at: Utc::now().to_rfc3339(), message: Some("Fake native camera live.".to_string()), no_video: None, system_effect: None, }; slot.active = Some(NativeCameraPreviewThread { stop_tx, join_handle: Some(join_handle), shared, camera_id: source_key.id, device_unique_id: "fake-supervisor".to_string(), ffmpeg_path: "ffmpeg".to_string(), layout: layout.clone(), video: video.clone(), effective_fps: video.fps, configured_output: (video.width, video.height), capture_target: camera_capture_target_dimensions(&layout, &video), }); drop(slot); FakeNativeCameraControl { release_tx, stop_seen_rx, exited_rx, } } #[test] fn rejected_requested_duration_freezes_the_observed_native_camera_cadence() { let observed_fractional_fps = 60_000.0 / 1_001.0; let selected = negotiated_camera_fps(Some(observed_fractional_fps), None, 60.0); assert!((selected - observed_fractional_fps).abs() < f64::EPSILON); assert_ne!( selected, 60.0, "the rejected requested cadence must not leak" ); assert_eq!(stable_effective_camera_fps(selected, 60), 60); assert_eq!( negotiated_camera_fps(None, None, observed_fractional_fps), observed_fractional_fps, "getter failure must fall back to the native format range, not the request" ); } #[tokio::test] async fn same_key_camera_start_joins_while_the_physical_gate_is_busy() { let state = test_state(); let video = test_video(); let layout = test_layout(false); let source_key = SourceKey::camera("camera:avfoundation-native:fake-supervisor"); let start_key = test_camera_start_key(source_key.clone(), &layout, &video); let transition_gate = Arc::clone(&state.preview_camera.lock().await.transition_gate); let physical_guard = transition_gate.lock_owned().await; let first = begin_camera_start( &state, start_key.clone(), &layout, test_camera_starting_status(&source_key, &video), None, ) .await; let lease = match first { PreviewCameraStartRegistration::Started { lease, .. } => lease, PreviewCameraStartRegistration::JoinExisting { .. } => { panic!("first start must own") } PreviewCameraStartRegistration::Reused(_) => panic!("first start cannot reuse"), PreviewCameraStartRegistration::RejectedSuperseded(_) | PreviewCameraStartRegistration::RejectedShutdown(_) => { panic!("test process is not shutting down") } }; let joined = tokio::time::timeout( Duration::from_millis(100), begin_camera_start( &state, start_key, &layout, test_camera_starting_status(&source_key, &video), None, ), ) .await .expect("same-key admission must not wait for native teardown"); assert!(matches!( joined, PreviewCameraStartRegistration::JoinExisting { .. } )); let stop = begin_preview_camera_stop(&state).await; assert!( !state .preview_camera .lock() .await .starting .as_ref() .is_some_and(|starting| starting == &lease.key), "stop admission must invalidate the abandoned test lease" ); drop(physical_guard); let _ = finish_preview_camera_stop(stop).await; } #[tokio::test] async fn published_camera_producer_identity_readers_ignore_different_desired_key() { let state = test_state(); let layout = test_layout(false); let video = test_video(); let camera_a = "camera:avfoundation-native:producer-a"; let camera_b = "camera:avfoundation-native:desired-b"; test_install_live_camera_for_layout(&state, camera_a, &layout, &video).await; let captured_at = Instant::now(); test_publish_camera_pixels(&state, 7, [0, 0, 255, 255], captured_at).await; let old_generation = preview_camera_frame_source(&state) .await .unwrap() .generation(); let gate = acquire_preview_camera_transition(&state).await; let registered = test_admit_camera_start_for_layout(&state, camera_b, &layout, &video).await; let admission_identity = { let slot = state.preview_camera.lock().await; ( slot.source_key.clone(), slot.active.as_ref().map(|active| active.camera_id.clone()), source_identity_locked(&slot), ) }; let async_reader = tokio::time::timeout(Duration::from_secs(1), preview_camera_frame_source(&state)).await; let nonblocking_reader = try_preview_camera_frame_source(&state); let stop = begin_preview_camera_stop(&state).await; drop(gate); let _ = tokio::time::timeout(Duration::from_secs(1), finish_preview_camera_stop(stop)) .await .expect("owned admitted runtime must stop"); assert_ne!( registered.expect("actual B start admission"), old_generation ); assert_eq!( admission_identity, ( Some(SourceKey::camera(camera_b)), Some(camera_a.into()), Some((SourceKey::camera(camera_b), old_generation)), ), "desired-key admission/CAS remains independent of the active producer" ); for reader in [ async_reader .expect("bounded async reader") .expect("active A"), nonblocking_reader .expect("available runtime") .expect("active A"), ] { assert_eq!(reader.source_key(), Some(&SourceKey::camera(camera_a))); assert_eq!(reader.generation(), old_generation); let (frame, _) = reader.try_latest_frame_result().unwrap().unwrap(); assert_eq!(frame.sequence, 7); assert_eq!(frame.captured_at, captured_at); } assert!(preview_camera_frame_source(&state).await.is_none()); } #[tokio::test] async fn layout_join_transfers_timeout_owner_forward_and_never_backward() { let state = test_state(); let video = test_video(); let layout = test_layout(false); let source_key = SourceKey::camera("camera:avfoundation-native:layout-transfer"); let start_key = test_camera_start_key(source_key.clone(), &layout, &video); let first_lease = match begin_camera_start( &state, start_key.clone(), &layout, test_camera_starting_status(&source_key, &video), Some(100), ) .await { PreviewCameraStartRegistration::Started { lease } => lease, other => panic!("first layout must own a fresh generation: {other:?}"), }; let stale_owner = PreviewCameraStartingIdentity { source_key: source_key.clone(), generation: first_lease.generation, layout_intent_id: Some(100), }; let winner = match begin_camera_start( &state, start_key.clone(), &layout, test_camera_starting_status(&source_key, &video), Some(101), ) .await { PreviewCameraStartRegistration::JoinExisting { admitted_starting_identity: Some(identity), .. } => identity, other => panic!("same-key winner must inherit the generation: {other:?}"), }; assert_eq!(winner.generation, first_lease.generation); assert_eq!(winner.layout_intent_id, Some(101)); let delayed_stale = begin_camera_start( &state, start_key, &layout, test_camera_starting_status(&source_key, &video), Some(100), ) .await; assert!(matches!( delayed_stale, PreviewCameraStartRegistration::JoinExisting { admitted_starting_identity: None, .. } )); assert_eq!( state.preview_camera.lock().await.starting_layout_intent_id, Some(101), "a delayed superseded source task must not steal timeout ownership backward" ); assert!( begin_preview_camera_stop_if_starting(&state, &stale_owner) .await .is_none(), "superseded layout token must stop matching after ownership transfer" ); let stop = begin_preview_camera_stop_if_starting(&state, &winner) .await .expect("winning layout retains exact timeout cleanup authority"); let status = finish_preview_camera_stop(stop).await; assert_ne!(status.state, PreviewCameraState::Starting); } #[tokio::test] async fn different_key_layout_rechecks_supersession_after_registry_wait() { let state = test_state(); let video = test_video(); let layout = test_layout(false); let current_key = SourceKey::camera("camera:avfoundation-native:current-layout"); let stale_key = SourceKey::camera("camera:avfoundation-native:blocked-layout"); state.publish_latest_layout_intent_id(300); let current_lease = match begin_camera_start( &state, test_camera_start_key(current_key.clone(), &layout, &video), &layout, test_camera_starting_status(¤t_key, &video), Some(300), ) .await { PreviewCameraStartRegistration::Started { lease } => lease, other => panic!("current layout must own a fresh generation: {other:?}"), }; let registry_guard = state.source_registry.lock().await; let registry_before = registry_guard.snapshot(); let blocked_state = state.clone(); let blocked_layout = layout.clone(); let blocked_video = video.clone(); let blocked_key = stale_key.clone(); let blocked = tokio::spawn(async move { begin_camera_start( &blocked_state, test_camera_start_key(blocked_key.clone(), &blocked_layout, &blocked_video), &blocked_layout, test_camera_starting_status(&blocked_key, &blocked_video), Some(300), ) .await }); tokio::time::timeout(Duration::from_secs(1), async { while state.preview_camera.try_lock().is_ok() { tokio::task::yield_now().await; } }) .await .expect("different-key camera admission must reach the registry wait"); { let _layout_admission = state.lock_layout_source_admission(); state.publish_latest_layout_intent_id(301); } drop(registry_guard); let stale = blocked.await.expect("blocked camera admission task"); assert!(matches!( stale, PreviewCameraStartRegistration::RejectedSuperseded(_) )); let slot = state.preview_camera.lock().await; assert_eq!(slot.start_generation, current_lease.generation); assert_eq!(slot.starting.as_ref(), Some(¤t_lease.key)); assert_eq!(slot.source_key.as_ref(), Some(¤t_key)); drop(slot); assert_eq!( state.source_registry.lock().await.snapshot(), registry_before ); } #[tokio::test] async fn queued_camera_supervisor_survives_newer_layout_adoption() { assert_queued_camera_supervisor_survives_owner_transfer(Some(101)).await; } #[tokio::test] async fn queued_camera_supervisor_survives_public_owner_transfer() { assert_queued_camera_supervisor_survives_owner_transfer(None).await; } #[tokio::test(start_paused = true)] async fn camera_start_response_timeout_does_not_release_source_transition_fence() { let state = test_state(); let video = test_video(); let layout = test_layout(false); let source_key = SourceKey::camera("camera:avfoundation-native:fenced-timeout"); let start_key = test_camera_start_key(source_key.clone(), &layout, &video); let held_transition = acquire_preview_camera_transition(&state).await; let lease = match begin_camera_start( &state, start_key, &layout, test_camera_starting_status(&source_key, &video), None, ) .await { PreviewCameraStartRegistration::Started { lease } => lease, other => panic!("camera timeout test must own a fresh generation: {other:?}"), }; let completion = queue_registered_preview_camera( state.clone(), test_prepared_camera_start(&source_key, &layout, &video, lease.clone(), None), None, ); let transition_snapshot = state.source_transition_fence.observe(); let response_state = state.clone(); let response_lease = lease.clone(); let response = tokio::spawn(async move { wait_for_camera_transition_response(&response_state, completion, &response_lease).await }); tokio::time::advance(CAMERA_COMMAND_TRANSITION_TIMEOUT + Duration::from_secs(1)).await; let status = response.await.expect("bounded camera response task"); assert_eq!(status.state, PreviewCameraState::Starting); let mut transition_wait = Box::pin(transition_snapshot.wait()); assert!( futures_util::poll!(&mut transition_wait).is_pending(), "caller timeout must not release physical camera transition ownership" ); { let mut slot = state.preview_camera.lock().await; slot.disconnected = None; slot.start_generation = slot.start_generation.wrapping_add(1).max(1); slot.starting = None; slot.starting_transition_completion = None; slot.starting_layout_intent_id = None; } drop(held_transition); transition_wait.await; } #[tokio::test(start_paused = true)] async fn admitted_camera_start_replies_before_the_native_open_and_keeps_the_fence() { // Issue #1068: the public start replies once its generation is owned, // so the ordered command lane is not held for the native open. The // supervisor still owns the generation and the source transition fence // that `session.start` drains. let state = test_state(); #[cfg(target_os = "windows")] { state.preview_camera.lock().await.test_dshow_inventory = Some( "[dshow] \"abc\" (video)\n[dshow] Alternative name \"@device_pnp_test_abc\"\n" .into(), ); } let video = test_video(); let layout = test_layout(false); let camera_id = "camera:avfoundation-native:616263"; let held_transition = acquire_preview_camera_transition(&state).await; let generation_before = state.preview_camera.lock().await.start_generation; let replied_at = tokio::time::Instant::now(); let result = start_preview_camera_with_owner( state.clone(), test_camera_params(Some(camera_id), &layout, &video), None, None, PreviewCameraStartWait::Admitted, ) .await; assert_eq!( replied_at.elapsed(), Duration::ZERO, "the admitted reply must not wait on the held native transition" ); assert_eq!(result.status.state, PreviewCameraState::Starting); assert_eq!(result.status.camera_id.as_deref(), Some(camera_id)); { let slot = state.preview_camera.lock().await; assert_ne!(slot.start_generation, generation_before); assert_eq!( slot.starting.as_ref().map(|key| &key.source_key), Some(&SourceKey::camera(camera_id)), "the supervisor, not the reply, owns the starting generation" ); } let transition_snapshot = state.source_transition_fence.observe(); let mut transition_wait = Box::pin(transition_snapshot.wait()); assert!( futures_util::poll!(&mut transition_wait).is_pending(), "an early reply must not release the source transition session.start drains" ); { let mut slot = state.preview_camera.lock().await; slot.disconnected = None; slot.start_generation = slot.start_generation.wrapping_add(1).max(1); slot.starting = None; slot.starting_transition_completion = None; slot.starting_layout_intent_id = None; } drop(held_transition); transition_wait.await; } #[test] fn only_windows_replies_to_a_public_camera_start_at_admission() { let expected = if cfg!(target_os = "windows") { PreviewCameraStartWait::Admitted } else { PreviewCameraStartWait::Bounded }; assert_eq!(public_camera_start_wait(), expected); } #[tokio::test(start_paused = true)] async fn fenced_layout_join_waits_past_command_timeout_and_starting_clear() { let state = test_state(); // This ownership test seeds a known in-flight generation. Its exact // inventory is scoped to this AppState, never real host hardware or a // process-global bypass; production still resolves before retirement. #[cfg(target_os = "windows")] { state.preview_camera.lock().await.test_dshow_inventory = Some( "[dshow] \"abc\" (video)\n[dshow] Alternative name \"@device_cm_test_abc\"\n" .into(), ); } let video = test_video(); let layout = test_layout(false); let source_key = SourceKey::camera("camera:avfoundation-native:616263"); let start_key = test_camera_start_key(source_key.clone(), &layout, &video); state.publish_latest_layout_intent_id(100); let lease = match begin_camera_start( &state, start_key, &layout, test_camera_starting_status(&source_key, &video), Some(100), ) .await { PreviewCameraStartRegistration::Started { lease } => lease, other => panic!("first layout must own the fenced generation: {other:?}"), }; // Deterministic stand-in for the persistent transition owner. The // completion token, not the mutable runtime `starting` field, is the // physical ownership boundary used by the fenced join below. let completion_guard = PreviewCameraTransitionCompletionGuard::new(Arc::clone(&lease.transition_completion)); let (release_tx, release_rx) = oneshot::channel(); let supervisor = tokio::spawn(async move { let _completion_guard = completion_guard; let _ = release_rx.await; }); { let _layout_admission = state.lock_layout_source_admission(); state.publish_latest_layout_intent_id(101); } let (admission_tx, admission_rx) = oneshot::channel(); let fenced_state = state.clone(); let fenced_layout = layout.clone(); let fenced_video = video.clone(); let fenced_source_id = source_key.id.clone(); let fenced = tokio::spawn(async move { start_preview_camera_for_layout_until_transition_complete( fenced_state, test_camera_params(Some(&fenced_source_id), &fenced_layout, &fenced_video), 101, admission_tx, ) .await }); let admitted = admission_rx .await .expect("fenced layout join admission") .expect("newer layout adopts the starting generation"); assert_eq!(admitted.generation, lease.generation); assert_eq!(admitted.layout_intent_id, Some(101)); tokio::time::advance(CAMERA_COMMAND_TRANSITION_TIMEOUT + Duration::from_secs(1)).await; tokio::task::yield_now().await; assert!( !fenced.is_finished(), "fenced layout work must remain live beyond the command response cap" ); { let mut slot = state.preview_camera.lock().await; slot.disconnected = None; slot.start_generation = slot.start_generation.wrapping_add(1).max(1); slot.starting = None; slot.starting_transition_completion = None; slot.starting_layout_intent_id = None; slot.source_key = None; slot.status = idle_status(Some("Fenced generation superseded.".to_string())); } tokio::task::yield_now().await; assert!( !fenced.is_finished(), "clearing logical Starting must not outrun physical supervisor completion" ); release_tx .send(()) .expect("release fake persistent transition owner"); supervisor.await.expect("fake persistent transition owner"); let result = fenced.await.expect("fenced layout join task"); assert_eq!(result.status.state, PreviewCameraState::DeviceMissing); assert_eq!(result.admitted_starting_identity, Some(admitted)); } #[tokio::test] async fn layout_invalid_camera_sources_do_not_mutate_public_start() { let state = test_state(); let video = test_video(); let layout = test_layout(false); let public_key = SourceKey::camera("camera:avfoundation-native:public-owner"); let public_lease = match begin_camera_start( &state, test_camera_start_key(public_key.clone(), &layout, &video), &layout, test_camera_starting_status(&public_key, &video), None, ) .await { PreviewCameraStartRegistration::Started { lease } => lease, other => panic!("public camera start must own a generation: {other:?}"), }; let public_status = state.preview_camera.lock().await.status.clone(); let registry_before = state.source_registry.lock().await.snapshot(); let mutation_epoch_before = state.capture_recovery_camera_mutation_epoch(); state.publish_latest_layout_intent_id(400); for invalid_camera_id in [None, Some("camera:unsupported:device")] { let result = start_preview_camera_with_owner( state.clone(), test_camera_params(invalid_camera_id, &layout, &video), Some(400), None, PreviewCameraStartWait::Bounded, ) .await; assert_eq!(result.status.state, PreviewCameraState::DeviceMissing); assert!(result.admitted_starting_identity.is_none()); let slot = state.preview_camera.lock().await; assert_eq!(slot.start_generation, public_lease.generation); assert_eq!(slot.starting.as_ref(), Some(&public_lease.key)); assert_eq!(slot.starting_layout_intent_id, None); assert_eq!(slot.source_key.as_ref(), Some(&public_key)); assert_eq!(slot.status, public_status); drop(slot); assert_eq!( state.source_registry.lock().await.snapshot(), registry_before ); assert_eq!( state.capture_recovery_camera_mutation_epoch(), mutation_epoch_before, "layout validation failures must not enter the public camera mutation path" ); } } #[tokio::test] async fn public_invalid_camera_sources_still_stop_and_publish_missing_status() { let video = test_video(); let layout = test_layout(false); for invalid_camera_id in [None, Some("camera:unsupported:device")] { let state = test_state(); let public_key = SourceKey::camera("camera:avfoundation-native:public-owner"); assert!(matches!( begin_camera_start( &state, test_camera_start_key(public_key.clone(), &layout, &video), &layout, test_camera_starting_status(&public_key, &video), None, ) .await, PreviewCameraStartRegistration::Started { .. } )); let mutation_epoch_before = state.capture_recovery_camera_mutation_epoch(); let status = start_preview_camera( state.clone(), test_camera_params(invalid_camera_id, &layout, &video), ) .await; assert_eq!(status.state, PreviewCameraState::DeviceMissing); let slot = state.preview_camera.lock().await; assert!(slot.starting.is_none()); assert_eq!(slot.status, status); drop(slot); assert!( state.capture_recovery_camera_mutation_epoch() > mutation_epoch_before, "public validation failures retain explicit stop/recovery reconciliation" ); let snapshot = state.source_registry.lock().await.snapshot(); assert!(snapshot.entries.iter().all(|entry| { entry.key != public_key || !entry.consumers.contains(&SourceConsumerReason::Preview) })); } } #[tokio::test] async fn queued_camera_start_retains_explicit_mutation_until_terminal_supervisor_state() { let state = test_state(); let video = test_video(); let layout = test_layout(false); let source_key = SourceKey::camera("camera:avfoundation-native:fake-supervisor"); let start_key = test_camera_start_key(source_key.clone(), &layout, &video); let held_transition = acquire_preview_camera_transition(&state).await; let explicit_mutation = begin_capture_recovery_explicit_camera_configuration_mutation(&state).await; let lease = match begin_camera_start( &state, start_key, &layout, test_camera_starting_status(&source_key, &video), None, ) .await { PreviewCameraStartRegistration::Started { lease } => lease, PreviewCameraStartRegistration::JoinExisting { .. } => { panic!("first start must own") } PreviewCameraStartRegistration::Reused(_) => panic!("first start cannot reuse"), PreviewCameraStartRegistration::RejectedSuperseded(_) | PreviewCameraStartRegistration::RejectedShutdown(_) => { panic!("test process is not shutting down") } }; let completion = queue_registered_preview_camera( state.clone(), PreparedCameraStart { camera_id: source_key.id.clone(), device_unique_id: "fake-supervisor".to_string(), ffmpeg_path: "ffmpeg".to_string(), target_fps: video.fps, source_key: source_key.clone(), params: PreviewCameraStartParams { sources: SourceSelection { screen_id: None, window_id: None, camera_id: Some(source_key.id.clone()), microphone_id: None, test_pattern: false, }, layout, video, ffmpeg_path: Some("ffmpeg".to_string()), }, lease: lease.clone(), layout_intent_id: None, recovery: None, }, Some(explicit_mutation), ); let in_flight_mutation_epoch = state.capture_recovery_camera_mutation_epoch(); assert!( state .lock_capture_recovery_admission_gate() .explicit_camera_mutation_is_active(), "the queued process supervisor must own the start mutation lease" ); // End this generation deterministically before releasing the physical // gate, so the test never opens a platform camera device. { let mut slot = state.preview_camera.lock().await; slot.disconnected = None; slot.start_generation = slot.start_generation.wrapping_add(1).max(1); slot.starting = None; } drop(held_transition); tokio::time::timeout(Duration::from_secs(1), completion) .await .expect("superseded start supervisor deadline") .expect("superseded start supervisor task"); assert!( !state .lock_capture_recovery_admission_gate() .explicit_camera_mutation_is_active(), "terminal supervisor state must release the start mutation lease" ); assert!( state.capture_recovery_camera_mutation_epoch() > in_flight_mutation_epoch, "terminal start must stale health sampled while the transition gate was blocked" ); } #[tokio::test] async fn camera_cancellation_at_registry_admission_preserves_old_runtime_and_consumer() { let state = test_state(); let video = test_video(); let layout = test_layout(false); let old_source_key = SourceKey::camera("camera:avfoundation-native:old"); let new_source_key = SourceKey::camera("camera:avfoundation-native:new"); let mut old_status = test_camera_starting_status(&old_source_key, &video); old_status.state = PreviewCameraState::Live; old_status.message = Some("Existing camera session remains live.".to_string()); { let mut slot = state.preview_camera.lock().await; slot.source_key = Some(old_source_key.clone()); slot.status = old_status.clone(); slot.start_generation = 7; } let mut registry_guard = state.source_registry.lock().await; registry_guard.acquire(old_source_key.clone(), SourceConsumerReason::Preview); registry_guard.set_status(old_source_key.clone(), SourceLifecycleStatus::Live); let caller_state = state.clone(); let caller_new_source_key = new_source_key.clone(); let caller_video = video.clone(); let caller_layout = layout.clone(); let caller = tokio::spawn(async move { begin_camera_start( &caller_state, test_camera_start_key(caller_new_source_key.clone(), &caller_layout, &caller_video), &caller_layout, test_camera_starting_status(&caller_new_source_key, &caller_video), None, ) .await }); tokio::time::timeout(Duration::from_secs(1), async { loop { if state.preview_camera.try_lock().is_err() { break; } tokio::task::yield_now().await; } }) .await .expect("camera admission must reach the registry boundary"); caller.abort(); assert!( caller .await .expect_err("camera admission caller must abort") .is_cancelled() ); drop(registry_guard); let slot = state.preview_camera.lock().await; assert_eq!(slot.source_key.as_ref(), Some(&old_source_key)); assert_eq!(slot.status, old_status); assert_eq!(slot.start_generation, 7); assert!(slot.starting.is_none()); assert!(slot.pending_stop_generation.is_none()); drop(slot); let snapshot = state.source_registry.lock().await.snapshot(); let old_entry = snapshot .entries .iter() .find(|entry| entry.key == old_source_key) .expect("old camera registry entry"); assert_eq!(old_entry.consumers, vec![SourceConsumerReason::Preview]); assert!( snapshot .entries .iter() .all(|entry| entry.key != new_source_key), "a cancelled camera admission must not register the new Preview consumer" ); } #[tokio::test] async fn cancelling_camera_stop_waiter_does_not_abandon_native_ownership() { let state = test_state(); let live_sessions = Arc::new(AtomicUsize::new(0)); let max_live_sessions = Arc::new(AtomicUsize::new(0)); let FakeNativeCameraControl { release_tx, stop_seen_rx, exited_rx, } = install_blocking_fake_native_camera( &state, Arc::clone(&live_sessions), Arc::clone(&max_live_sessions), ) .await; let stop = begin_preview_camera_stop(&state).await; tokio::time::timeout(Duration::from_secs(1), stop_seen_rx) .await .expect("supervisor must signal the fake native stop") .expect("fake native stop sender"); let waiter = tokio::spawn(async move { finish_preview_camera_stop(stop).await }); tokio::task::yield_now().await; assert!( !waiter.is_finished(), "native join is still deliberately blocked" ); waiter.abort(); assert!(waiter.await.expect_err("waiter must abort").is_cancelled()); release_tx.send(()).expect("release fake native join"); tokio::time::timeout(Duration::from_secs(1), exited_rx) .await .expect("fake native must exit after caller cancellation") .expect("fake native exit sender"); tokio::time::timeout(Duration::from_secs(1), async { loop { let finished = { let slot = state.preview_camera.lock().await; slot.active.is_none() && slot.pending_stop_generation.is_none() }; if finished { break; } tokio::task::yield_now().await; } }) .await .expect("detached stop supervisor must finish cleanup"); let gate = Arc::clone(&state.preview_camera.lock().await.transition_gate); let _guard = tokio::time::timeout(Duration::from_secs(1), gate.lock_owned()) .await .expect("physical transition authority must be released"); assert_eq!(live_sessions.load(Ordering::SeqCst), 0); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); } #[tokio::test] async fn graceful_camera_shutdown_forces_release_and_joins_the_native_owner() { let state = test_state(); let live_sessions = Arc::new(AtomicUsize::new(0)); let max_live_sessions = Arc::new(AtomicUsize::new(0)); let FakeNativeCameraControl { release_tx, stop_seen_rx, exited_rx, } = install_blocking_fake_native_camera( &state, Arc::clone(&live_sessions), Arc::clone(&max_live_sessions), ) .await; let source_key = SourceKey::camera("camera:avfoundation-native:fake-supervisor"); { let mut registry = state.source_registry.lock().await; registry.acquire(source_key.clone(), SourceConsumerReason::Preview); registry.acquire(source_key, SourceConsumerReason::Recording); } let shutdown_state = state.clone(); let shutdown = tokio::spawn(async move { shutdown_preview_camera_with_timeout(&shutdown_state, Duration::from_secs(1)).await }); tokio::time::timeout(Duration::from_secs(1), stop_seen_rx) .await .expect("graceful shutdown must signal the camera owner") .expect("fake camera stop sender"); assert!( !shutdown.is_finished(), "shutdown must retain the join until native teardown completes" ); release_tx.send(()).expect("release shutdown camera join"); tokio::time::timeout(Duration::from_secs(1), exited_rx) .await .expect("shutdown camera exit deadline") .expect("shutdown camera exit sender"); assert!( shutdown.await.expect("camera shutdown supervisor"), "the graceful shutdown deadline must observe the completed join" ); let slot = state.preview_camera.lock().await; assert!(slot.active.is_none()); assert!(slot.pending_native.is_none()); assert!(slot.pending_stop_generation.is_none()); assert_eq!(slot.status.state, PreviewCameraState::DeviceMissing); assert_eq!(live_sessions.load(Ordering::SeqCst), 0); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); } #[tokio::test] async fn graceful_camera_shutdown_deadline_keeps_slow_join_process_owned() { let state = test_state(); let live_sessions = Arc::new(AtomicUsize::new(0)); let max_live_sessions = Arc::new(AtomicUsize::new(0)); let FakeNativeCameraControl { release_tx, stop_seen_rx, exited_rx, } = install_blocking_fake_native_camera( &state, Arc::clone(&live_sessions), Arc::clone(&max_live_sessions), ) .await; let started_at = Instant::now(); assert!( !shutdown_preview_camera_with_timeout(&state, Duration::from_millis(20)).await, "a blocked native join must be reported as continuing" ); assert!(started_at.elapsed() < Duration::from_millis(500)); tokio::time::timeout(Duration::from_secs(1), stop_seen_rx) .await .expect("bounded shutdown must still signal the camera owner") .expect("fake camera stop sender"); { let slot = state.preview_camera.lock().await; assert!(slot.active.is_none()); assert!(slot.pending_stop_generation.is_some()); assert!( slot.status .message .as_deref() .is_some_and(|message| message.contains("exclusively owned")) ); } release_tx .send(()) .expect("release slow graceful camera join"); tokio::time::timeout(Duration::from_secs(1), exited_rx) .await .expect("slow graceful camera exit deadline") .expect("slow graceful camera exit sender"); tokio::time::timeout(Duration::from_secs(1), async { loop { let terminal = { let slot = state.preview_camera.lock().await; slot.pending_stop_generation.is_none() && slot.status.state == PreviewCameraState::DeviceMissing }; if terminal { break; } tokio::task::yield_now().await; } }) .await .expect("process-owned camera join must finish after deadline return"); assert_eq!(live_sessions.load(Ordering::SeqCst), 0); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); } #[tokio::test] async fn shutdown_latch_rejects_late_camera_start_and_recovery_without_new_native_generation() { let state = test_state(); let live_sessions = Arc::new(AtomicUsize::new(0)); let max_live_sessions = Arc::new(AtomicUsize::new(0)); let FakeNativeCameraControl { release_tx, stop_seen_rx, exited_rx, } = install_blocking_fake_native_camera( &state, Arc::clone(&live_sessions), Arc::clone(&max_live_sessions), ) .await; let restart = preview_camera_restart_snapshot(&state) .await .expect("fake live camera must expose an exact restart snapshot"); let generation = state.preview_camera.lock().await.start_generation; assert!(state.request_process_shutdown()); let rejected = start_preview_camera( state.clone(), PreviewCameraStartParams { sources: SourceSelection { screen_id: None, window_id: None, camera_id: Some("camera:avfoundation-native:fake-supervisor".to_string()), microphone_id: None, test_pattern: false, }, layout: test_layout(false), video: test_video(), ffmpeg_path: Some("ffmpeg".to_string()), }, ) .await; assert!( rejected .message .as_deref() .is_some_and(|message| message.contains("shutdown")) ); assert_eq!( state.preview_camera.lock().await.start_generation, generation ); assert_eq!( force_restart_preview_camera(state.clone(), &restart, 1).await, PreviewCameraForceRestartResult::RejectedStale ); assert_eq!( state.preview_camera.lock().await.start_generation, generation ); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); let started_at = Instant::now(); assert!( !shutdown_preview_camera_with_timeout(&state, Duration::from_millis(20)).await, "the process shutdown drain must stay bounded while the fake driver is blocked" ); assert!(started_at.elapsed() < Duration::from_millis(500)); tokio::time::timeout(Duration::from_secs(1), stop_seen_rx) .await .expect("shutdown must signal the original camera generation") .expect("fake camera stop sender"); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); release_tx .send(()) .expect("release shutdown-latched camera join"); tokio::time::timeout(Duration::from_secs(1), exited_rx) .await .expect("shutdown-latched camera exit deadline") .expect("shutdown-latched camera exit sender"); tokio::time::timeout(Duration::from_secs(1), async { loop { let terminal = { let slot = state.preview_camera.lock().await; slot.pending_stop_generation.is_none() && slot.status.state == PreviewCameraState::DeviceMissing }; if terminal { break; } tokio::task::yield_now().await; } }) .await .expect("process-owned camera drain must reach terminal state"); assert_eq!(live_sessions.load(Ordering::SeqCst), 0); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); } #[tokio::test] async fn camera_stop_survives_disposable_caller_runtime_drop_without_overlap() { let state = test_state(); let live_sessions = Arc::new(AtomicUsize::new(0)); let max_live_sessions = Arc::new(AtomicUsize::new(0)); let FakeNativeCameraControl { release_tx, stop_seen_rx, exited_rx, } = install_blocking_fake_native_camera( &state, Arc::clone(&live_sessions), Arc::clone(&max_live_sessions), ) .await; let caller_state = state.clone(); let caller = thread::spawn(move || { let runtime = tokio::runtime::Builder::new_current_thread() .enable_all() .build() .expect("disposable camera caller runtime"); runtime.block_on(async move { let stop = begin_preview_camera_stop(&caller_state).await; // Dropping both the waiter and this runtime must not own or // cancel the process-lifetime physical transition. drop(stop); }); }); tokio::task::spawn_blocking(move || caller.join()) .await .expect("disposable camera caller join task") .expect("disposable camera caller thread"); tokio::time::timeout(Duration::from_secs(1), stop_seen_rx) .await .expect("process supervisor must outlive the caller runtime") .expect("fake camera stop sender"); let gate = Arc::clone(&state.preview_camera.lock().await.transition_gate); let replacement_live = Arc::clone(&live_sessions); let replacement_max = Arc::clone(&max_live_sessions); let (replacement_started_tx, mut replacement_started_rx) = oneshot::channel(); let replacement = tokio::spawn(async move { let _physical_guard = gate.lock_owned().await; let live = replacement_live.fetch_add(1, Ordering::SeqCst) + 1; replacement_max.fetch_max(live, Ordering::SeqCst); let _ = replacement_started_tx.send(()); replacement_live.fetch_sub(1, Ordering::SeqCst); }); assert!( tokio::time::timeout(Duration::from_millis(20), &mut replacement_started_rx) .await .is_err(), "runtime drop must not release the gate before the native join" ); assert_eq!(live_sessions.load(Ordering::SeqCst), 1); release_tx .send(()) .expect("release camera join after caller runtime drop"); tokio::time::timeout(Duration::from_secs(1), exited_rx) .await .expect("camera exit after caller runtime drop") .expect("fake camera exit sender"); replacement_started_rx .await .expect("replacement starts after old camera joins"); replacement.await.expect("replacement camera task"); tokio::time::timeout(Duration::from_secs(1), async { loop { let terminal = { let slot = state.preview_camera.lock().await; slot.active.is_none() && slot.pending_native.is_none() && slot.pending_stop_generation.is_none() && slot.status.state == PreviewCameraState::DeviceMissing }; if terminal { break; } tokio::task::yield_now().await; } }) .await .expect("camera supervisor publishes terminal state"); assert_eq!(live_sessions.load(Ordering::SeqCst), 0); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); } #[tokio::test] async fn stop_supersession_promptly_blocks_same_session_reuse_and_stale_install() { let state = test_state(); let live_sessions = Arc::new(AtomicUsize::new(0)); let max_live_sessions = Arc::new(AtomicUsize::new(0)); let FakeNativeCameraControl { release_tx, stop_seen_rx, exited_rx, } = install_blocking_fake_native_camera( &state, Arc::clone(&live_sessions), Arc::clone(&max_live_sessions), ) .await; let video = test_video(); let layout = test_layout(false); let source_key = SourceKey::camera("camera:avfoundation-native:fake-supervisor"); let start_key = test_camera_start_key(source_key.clone(), &layout, &video); let gate = Arc::clone(&state.preview_camera.lock().await.transition_gate); let physical_guard = gate.lock_owned().await; let first_stop = begin_preview_camera_stop(&state).await; let registration = tokio::time::timeout( Duration::from_millis(100), begin_camera_start( &state, start_key, &layout, test_camera_starting_status(&source_key, &video), None, ), ) .await .expect("superseding start admission must not wait for physical teardown"); let lease = match registration { PreviewCameraStartRegistration::Started { lease, .. } => lease, PreviewCameraStartRegistration::JoinExisting { .. } => { panic!("the stopped generation must not remain joinable") } PreviewCameraStartRegistration::Reused(_) => { panic!("a teardown-pending native session must never be reused") } PreviewCameraStartRegistration::RejectedSuperseded(_) | PreviewCameraStartRegistration::RejectedShutdown(_) => { panic!("test process is not shutting down") } }; let final_stop = begin_preview_camera_stop(&state).await; let stale_install_claimed = { let mut slot = state.preview_camera.lock().await; claim_camera_start(&mut slot, &lease) }; assert!( !stale_install_claimed, "newer stop intent must immediately invalidate the unstarted lease" ); drop(physical_guard); tokio::time::timeout(Duration::from_secs(1), stop_seen_rx) .await .expect("the current stop generation must retire the old native owner") .expect("fake native stop sender"); release_tx.send(()).expect("release fake native join"); tokio::time::timeout(Duration::from_secs(1), exited_rx) .await .expect("fake native exit deadline") .expect("fake native exit sender"); let (_first_status, _final_status) = tokio::join!( finish_preview_camera_stop(first_stop), finish_preview_camera_stop(final_stop), ); assert_eq!(live_sessions.load(Ordering::SeqCst), 0); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); } #[tokio::test] async fn bounded_camera_stop_response_keeps_the_next_native_session_exclusive() { let state = test_state(); let live_sessions = Arc::new(AtomicUsize::new(0)); let max_live_sessions = Arc::new(AtomicUsize::new(0)); let FakeNativeCameraControl { release_tx, stop_seen_rx, exited_rx, } = install_blocking_fake_native_camera( &state, Arc::clone(&live_sessions), Arc::clone(&max_live_sessions), ) .await; let stop = begin_preview_camera_stop(&state).await; tokio::time::timeout(Duration::from_secs(1), stop_seen_rx) .await .expect("fake native must receive stop") .expect("fake native stop sender"); let gate = Arc::clone(&state.preview_camera.lock().await.transition_gate); let next_live_sessions = Arc::clone(&live_sessions); let next_max_live_sessions = Arc::clone(&max_live_sessions); let (next_started_tx, mut next_started_rx) = oneshot::channel(); let next_session = tokio::spawn(async move { let _physical_guard = gate.lock_owned().await; let live = next_live_sessions.fetch_add(1, Ordering::SeqCst) + 1; next_max_live_sessions.fetch_max(live, Ordering::SeqCst); let _ = next_started_tx.send(()); next_live_sessions.fetch_sub(1, Ordering::SeqCst); }); let returned = finish_preview_camera_stop_with_timeout(stop, Duration::from_millis(20)).await; assert!( returned .message .as_deref() .is_some_and(|message| message.contains("exclusively owned")), "the bounded response must truthfully report delayed teardown" ); assert!( tokio::time::timeout(Duration::from_millis(20), &mut next_started_rx) .await .is_err(), "a replacement native session must remain behind the blocked join" ); assert_eq!(live_sessions.load(Ordering::SeqCst), 1); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); let in_flight_mutation_epoch = state.capture_recovery_camera_mutation_epoch(); assert!( state .lock_capture_recovery_admission_gate() .explicit_camera_mutation_is_active(), "the explicit stop mutation must remain active after its bounded waiter detaches" ); release_tx.send(()).expect("release fake native join"); tokio::time::timeout(Duration::from_secs(1), exited_rx) .await .expect("old native session exit deadline") .expect("old native session exit sender"); tokio::time::timeout(Duration::from_secs(1), &mut next_started_rx) .await .expect("next native session starts after retirement") .expect("next native start sender"); next_session.await.expect("next fake native session task"); tokio::time::timeout(Duration::from_secs(1), async { while state .lock_capture_recovery_admission_gate() .explicit_camera_mutation_is_active() { tokio::task::yield_now().await; } }) .await .expect("the terminal stop supervisor must release its mutation lease"); assert!( state.capture_recovery_camera_mutation_epoch() > in_flight_mutation_epoch, "the terminal stop edge must stale health sampled during native join" ); assert_eq!(live_sessions.load(Ordering::SeqCst), 0); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); } #[tokio::test] async fn late_unneeded_live_camera_thread_is_stopped_and_joined() { let state = test_state(); let live_sessions = Arc::new(AtomicUsize::new(0)); let max_live_sessions = Arc::new(AtomicUsize::new(0)); let FakeNativeCameraControl { release_tx, stop_seen_rx, exited_rx, } = install_blocking_fake_native_camera( &state, Arc::clone(&live_sessions), Arc::clone(&max_live_sessions), ) .await; let stale_thread = { let mut slot = state.preview_camera.lock().await; slot.source_key = None; slot.active_generation = None; slot.status = idle_status(Some("The late session is no longer desired.".to_string())); slot.active.take().expect("fake late native thread") }; let retirement = tokio::spawn(async move { retire_uninstalled_camera_thread(stale_thread, 99).await }); tokio::time::timeout(Duration::from_secs(1), stop_seen_rx) .await .expect("late Live must be told to stop") .expect("fake native stop sender"); assert_eq!(live_sessions.load(Ordering::SeqCst), 1); assert!( !retirement.is_finished(), "retirement must retain the native join" ); release_tx.send(()).expect("release late fake native join"); tokio::time::timeout(Duration::from_secs(1), exited_rx) .await .expect("late fake native exit deadline") .expect("late fake native exit sender"); tokio::time::timeout(Duration::from_secs(1), retirement) .await .expect("late native retirement deadline") .expect("late native retirement task"); assert_eq!(live_sessions.load(Ordering::SeqCst), 0); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); } #[tokio::test] async fn panic_after_camera_spawn_reaps_pending_owner_before_replacement_starts() { let state = test_state(); let live_sessions = Arc::new(AtomicUsize::new(0)); let max_live_sessions = Arc::new(AtomicUsize::new(0)); let FakeNativeCameraControl { release_tx, stop_seen_rx, exited_rx, } = install_blocking_fake_native_camera( &state, Arc::clone(&live_sessions), Arc::clone(&max_live_sessions), ) .await; let video = test_video(); let layout = test_layout(false); let source_key = SourceKey::camera("camera:avfoundation-native:fake-supervisor"); let lease = PreviewCameraStartLease::new( test_camera_start_key(source_key.clone(), &layout, &video), 99, ); { let mut slot = state.preview_camera.lock().await; let mut spawned = slot.active.take().expect("fake spawned native camera"); slot.active_generation = None; slot.start_generation = lease.generation; slot.starting = Some(lease.key.clone()); slot.source_key = Some(source_key.clone()); slot.status = test_camera_starting_status(&source_key, &video); slot.pending_native = Some(PendingNativeCameraThread { generation: lease.generation, stop_tx: spawned.stop_tx, join_handle: spawned.join_handle.take(), }); } let gate = Arc::clone(&state.preview_camera.lock().await.transition_gate); let cleanup_state = state.clone(); let cleanup_lease = lease.clone(); let cleanup = tokio::spawn(async move { let _physical_guard = gate.lock_owned().await; let panicked = std::panic::AssertUnwindSafe(async { panic!("injected panic after pending camera ownership registration"); }) .catch_unwind() .await; assert!(panicked.is_err()); retire_panicked_camera_generation( &cleanup_state, &cleanup_lease, failed_status( Some(source_key.id.clone()), Some("fake-supervisor".to_string()), video.fps, "Injected camera transition panic.".to_string(), ), None, ) .await }); tokio::time::timeout(Duration::from_secs(1), stop_seen_rx) .await .expect("panic cleanup must signal pending camera") .expect("fake camera stop sender"); let replacement_gate = Arc::clone(&state.preview_camera.lock().await.transition_gate); let replacement_live_sessions = Arc::clone(&live_sessions); let replacement_max_live_sessions = Arc::clone(&max_live_sessions); let (replacement_started_tx, mut replacement_started_rx) = oneshot::channel(); let replacement = tokio::spawn(async move { let _physical_guard = replacement_gate.lock_owned().await; let live = replacement_live_sessions.fetch_add(1, Ordering::SeqCst) + 1; replacement_max_live_sessions.fetch_max(live, Ordering::SeqCst); let _ = replacement_started_tx.send(()); replacement_live_sessions.fetch_sub(1, Ordering::SeqCst); }); assert!( tokio::time::timeout(Duration::from_millis(20), &mut replacement_started_rx) .await .is_err(), "replacement must remain behind the panicked owner's native join" ); assert_eq!(live_sessions.load(Ordering::SeqCst), 1); release_tx.send(()).expect("release pending camera join"); tokio::time::timeout(Duration::from_secs(1), exited_rx) .await .expect("pending camera exit deadline") .expect("pending camera exit sender"); let failed = cleanup.await.expect("camera panic cleanup task"); assert_eq!(failed.state, PreviewCameraState::Failed); replacement_started_rx .await .expect("replacement starts after camera join"); replacement.await.expect("replacement camera task"); assert_eq!(live_sessions.load(Ordering::SeqCst), 0); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); assert!(state.preview_camera.lock().await.pending_native.is_none()); } #[tokio::test] async fn panic_before_camera_detach_reconciles_old_native_and_runtime_owner() { let state = test_state(); let live_sessions = Arc::new(AtomicUsize::new(0)); let max_live_sessions = Arc::new(AtomicUsize::new(0)); let FakeNativeCameraControl { release_tx, stop_seen_rx, exited_rx, } = install_blocking_fake_native_camera( &state, Arc::clone(&live_sessions), Arc::clone(&max_live_sessions), ) .await; let video = test_video(); let layout = test_layout(false); let source_key = SourceKey::camera("camera:avfoundation-native:replacement"); let lease = PreviewCameraStartLease::new( test_camera_start_key(source_key.clone(), &layout, &video), 2, ); { let mut slot = state.preview_camera.lock().await; slot.start_generation = lease.generation; slot.starting = Some(lease.key.clone()); slot.source_key = Some(source_key.clone()); slot.status = test_camera_starting_status(&source_key, &video); assert_eq!(slot.active_generation, Some(1)); } let gate = Arc::clone(&state.preview_camera.lock().await.transition_gate); let cleanup_state = state.clone(); let cleanup_lease = lease.clone(); let cleanup = tokio::spawn(async move { let _physical_guard = gate.lock_owned().await; retire_panicked_camera_generation( &cleanup_state, &cleanup_lease, failed_status( Some(source_key.id), Some("replacement".to_string()), video.fps, "Injected panic before old camera detachment.".to_string(), ), None, ) .await }); tokio::time::timeout(Duration::from_secs(1), stop_seen_rx) .await .expect("pre-detach panic must stop the old camera owner") .expect("fake camera stop sender"); assert!( !cleanup.is_finished(), "cleanup must retain the old native join" ); { let slot = state.preview_camera.lock().await; assert!(slot.active.is_none()); assert!(slot.active_generation.is_none()); } release_tx.send(()).expect("release old camera join"); tokio::time::timeout(Duration::from_secs(1), exited_rx) .await .expect("old camera exit deadline") .expect("old camera exit sender"); let failed = cleanup.await.expect("pre-detach panic cleanup"); assert_eq!(failed.state, PreviewCameraState::Failed); assert_eq!(live_sessions.load(Ordering::SeqCst), 0); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); } async fn install_restartable_camera( state: &AppState, generation: u64, layout: &LayoutSettings, video: &VideoSettings, ) -> (SourceKey, Arc>) { let source_key = SourceKey::camera("camera:avfoundation-native:test"); let shared = Arc::new(StdMutex::new(PreviewCameraShared::default())); let (stop_tx, _stop_rx) = std_mpsc::channel(); let mut slot = state.preview_camera.lock().await; slot.source_key = Some(source_key.clone()); slot.start_generation = generation; slot.active_generation = Some(generation); slot.status = PreviewCameraStatus { state: PreviewCameraState::Live, camera_id: Some(source_key.id.clone()), device_unique_id: Some("test".to_string()), target_fps: video.fps, width: Some(video.width), height: Some(video.height), requested_width: Some(video.width), requested_height: Some(video.height), actual_width: Some(video.width), actual_height: Some(video.height), selected_format_width: Some(video.width), selected_format_height: Some(video.height), selected_format_min_fps: Some(1.0), selected_format_max_fps: Some(f64::from(video.fps)), source_fps: Some(f64::from(video.fps)), frame_age_ms: Some(1), frames_captured: 1, dropped_frames: 0, sequence: Some(1), updated_at: Utc::now().to_rfc3339(), message: Some("Live".to_string()), no_video: None, system_effect: None, }; slot.active = Some(NativeCameraPreviewThread { stop_tx, join_handle: None, shared: Arc::clone(&shared), camera_id: source_key.id.clone(), device_unique_id: "test".to_string(), ffmpeg_path: "/resolved/ffmpeg".to_string(), layout: layout.clone(), video: video.clone(), effective_fps: video.fps, configured_output: (video.width, video.height), capture_target: camera_capture_target_dimensions(layout, video), }); (source_key, shared) } #[tokio::test] async fn camera_disconnect_reconnect_retains_frames_and_fences_the_generation() { let state = test_state(); let layout = test_layout(true); let video = test_video(); let (_, shared) = install_restartable_camera(&state, 7, &layout, &video).await; let mut event = crate::device_watch::CameraConnectionEvent { unique_id: "other".to_string(), name: "iPhone".to_string(), connected: false, timestamp: Utc::now().to_rfc3339(), device_type: "AVCaptureDeviceTypeContinuityCamera".to_string(), transport: 0, }; camera_connection_changed(&state, &event).await; assert_eq!( preview_camera_status(&state).await.state, PreviewCameraState::Live ); event.unique_id = "test".to_string(); camera_connection_changed(&state, &event).await; let status = preview_camera_status(&state).await; assert_eq!(status.state, PreviewCameraState::Disconnected); assert_eq!(status.message.as_deref(), Some("iPhone disconnected")); assert!(preview_camera_restart_snapshot(&state).await.is_none()); assert!(Arc::ptr_eq( &state .preview_camera .lock() .await .active .as_ref() .unwrap() .shared, &shared )); camera_connection_changed(&state, &event).await; let mut slot = state.preview_camera.lock().await; assert!( slot.disconnected.is_some(), "duplicate disconnect retains reconnect authority" ); event.connected = true; let (prepared, mutation) = prepare_camera_reconnect(&state, &mut slot, &event).unwrap(); assert_eq!(prepared.lease.generation, 8); assert_eq!(prepared.params.layout, layout); assert_eq!(prepared.params.video, video); assert!( prepared.recovery.is_none(), "reconnect spends no recovery restart attempt" ); assert!(prepare_camera_reconnect(&state, &mut slot, &event).is_none()); drop(mutation); } #[tokio::test] async fn camera_disconnect_cannot_reconnect_a_replaced_generation() { let state = test_state(); install_restartable_camera(&state, 7, &test_layout(false), &test_video()).await; let event = crate::device_watch::CameraConnectionEvent { unique_id: "test".to_string(), name: "iPhone".to_string(), connected: false, timestamp: Utc::now().to_rfc3339(), device_type: "AVCaptureDeviceTypeContinuityCamera".to_string(), transport: 0, }; camera_connection_changed(&state, &event).await; let mut slot = state.preview_camera.lock().await; slot.active_generation = Some(8); let event = crate::device_watch::CameraConnectionEvent { connected: true, ..event }; assert!(prepare_camera_reconnect(&state, &mut slot, &event).is_none()); } #[tokio::test] async fn forced_camera_restart_is_generation_and_key_cas_and_preserves_exact_config() { let state = test_state(); let layout = test_layout(true); let video = test_video(); let (source_key, _) = install_restartable_camera(&state, 7, &layout, &video).await; assert!( reuse_current_camera_source( &state, &source_key, "/resolved/ffmpeg", &layout, &video, video.fps, ) .await .is_some(), "the fixture is intentionally eligible for ordinary same-key reuse" ); let expected = preview_camera_restart_snapshot(&state) .await .expect("live restart snapshot"); assert_eq!(expected.source_key, source_key); assert_eq!(expected.generation, 7); assert_eq!(expected.config.layout, layout); assert_eq!(expected.config.video, video); assert_eq!(expected.config.ffmpeg_path, "/resolved/ffmpeg"); assert_eq!(expected.config.device_unique_id, "test"); let recovery_epoch = 101; state.set_capture_recovery_admission_epoch(recovery_epoch); let mut stale_generation = expected.clone(); stale_generation.generation = 6; assert!( begin_forced_camera_restart(&state, &stale_generation, recovery_epoch) .await .is_none() ); let mut stale_key = expected.clone(); stale_key.source_key = SourceKey::camera("camera:avfoundation-native:other"); assert!( begin_forced_camera_restart(&state, &stale_key, recovery_epoch) .await .is_none() ); let prepared = begin_forced_camera_restart(&state, &expected, recovery_epoch) .await .expect("exact snapshot must reserve a forced restart"); assert_eq!(prepared.lease.generation, 8); assert_eq!(prepared.lease.key.source_key, source_key); assert_eq!(prepared.params.layout, layout); assert_eq!(prepared.params.video, video); assert_eq!( prepared.params.ffmpeg_path.as_deref(), Some("/resolved/ffmpeg") ); assert_eq!( prepared.params.sources.camera_id.as_deref(), Some("camera:avfoundation-native:test") ); let slot = state.preview_camera.lock().await; assert_eq!(slot.start_generation, 8); assert_eq!(slot.active_generation, Some(7)); assert!( slot.active.is_some(), "CAS alone must not overlap or discard the old session" ); drop(slot); stop_current_camera_for_restart(&state).await; } #[tokio::test] async fn same_generation_operator_reuse_invalidates_recovery_before_force_cas() { let state = test_state(); let old_layout = test_layout(false); let new_layout = test_layout(true); let video = test_video(); let (source_key, _) = install_restartable_camera(&state, 17, &old_layout, &video).await; let expected = preview_camera_restart_snapshot(&state) .await .expect("live restart snapshot"); let recovery_epoch = 201; state.set_capture_recovery_admission_epoch(recovery_epoch); let start_key = camera_restart_start_key(&source_key, &expected.config); let _explicit_mutation = begin_capture_recovery_explicit_camera_configuration_mutation(&state).await; let registration = begin_camera_start( &state, start_key, &new_layout, test_camera_starting_status(&source_key, &video), None, ) .await; assert!(matches!( registration, PreviewCameraStartRegistration::Reused(_) )); assert!( !state.capture_recovery_admission_is_current(recovery_epoch), "same-generation operator reuse must invalidate the queued recovery ticket" ); assert_eq!(state.preview_camera.lock().await.start_generation, 17); assert!( begin_forced_camera_restart(&state, &expected, recovery_epoch) .await .is_none(), "the stale recovery ticket cannot turn a Hot layout reuse into a physical restart" ); let slot = state.preview_camera.lock().await; assert_eq!(slot.active_generation, Some(17)); assert!( slot.active .as_ref() .expect("reused active camera") .layout .camera_mirror ); } #[tokio::test] async fn same_key_operator_start_supersedes_recovery_owned_starting_generation() { let state = test_state(); let old_layout = test_layout(false); let new_layout = test_layout(true); let video = test_video(); let (source_key, _) = install_restartable_camera(&state, 19, &old_layout, &video).await; let expected = preview_camera_restart_snapshot(&state) .await .expect("live restart snapshot"); let recovery_epoch = 211; state.set_capture_recovery_admission_epoch(recovery_epoch); let recovery = begin_forced_camera_restart(&state, &expected, recovery_epoch) .await .expect("recovery generation admitted"); let _explicit_mutation = begin_capture_recovery_explicit_camera_configuration_mutation(&state).await; let registration = begin_camera_start( &state, recovery.lease.key.clone(), &new_layout, test_camera_starting_status(&source_key, &video), None, ) .await; let operator_lease = match registration { PreviewCameraStartRegistration::Started { lease } => lease, PreviewCameraStartRegistration::JoinExisting { .. } => { panic!("operator start must not join a recovery-owned generation") } PreviewCameraStartRegistration::Reused(_) => { panic!("a recovery-owned Starting generation cannot be reused") } PreviewCameraStartRegistration::RejectedSuperseded(_) | PreviewCameraStartRegistration::RejectedShutdown(_) => { panic!("test process is not shutting down") } }; assert_eq!(operator_lease.generation, recovery.lease.generation + 1); assert!(!state.capture_recovery_admission_is_current(recovery_epoch)); let slot = state.preview_camera.lock().await; assert_eq!(slot.starting.as_ref(), Some(&operator_lease.key)); assert_eq!(slot.starting_recovery_epoch, None); assert_eq!(slot.active_generation, Some(expected.generation)); } #[tokio::test] async fn invalidated_recovery_panic_preserves_predecessor_and_rejects_failed_terminal() { let state = test_state(); let layout = test_layout(false); let video = test_video(); let (_, old_shared) = install_restartable_camera(&state, 20, &layout, &video).await; let expected = preview_camera_restart_snapshot(&state) .await .expect("live restart snapshot"); let predecessor_status = preview_camera_status(&state).await; let recovery_epoch = 214; state.set_capture_recovery_admission_epoch(recovery_epoch); let prepared = begin_forced_camera_restart(&state, &expected, recovery_epoch) .await .expect("recovery generation admitted"); let _explicit_mutation = begin_capture_recovery_explicit_camera_configuration_mutation(&state).await; let status = retire_panicked_camera_generation( &state, &prepared.lease, failed_status( Some(prepared.camera_id.clone()), Some(prepared.device_unique_id.clone()), prepared.target_fps, "Injected stale recovery panic.".to_string(), ), Some(&prepared), ) .await; assert_eq!(status.state, PreviewCameraState::Live); let slot = state.preview_camera.lock().await; assert_eq!(slot.status, predecessor_status); assert_eq!(slot.active_generation, Some(expected.generation)); assert!(slot.starting.is_none()); assert!(slot.starting_recovery_epoch.is_none()); assert!( slot.active .as_ref() .is_some_and(|active| Arc::ptr_eq(&active.shared, &old_shared)), "stale panic cleanup must not detach the predecessor" ); } #[tokio::test] async fn invalidation_during_blocked_recovery_panic_join_rejects_late_failed_terminal() { let state = test_state(); let live_sessions = Arc::new(AtomicUsize::new(0)); let max_live_sessions = Arc::new(AtomicUsize::new(0)); let FakeNativeCameraControl { release_tx, stop_seen_rx, exited_rx, } = install_blocking_fake_native_camera( &state, Arc::clone(&live_sessions), Arc::clone(&max_live_sessions), ) .await; let expected = preview_camera_restart_snapshot(&state) .await .expect("blocking camera restart snapshot"); let recovery_epoch = 215; state.set_capture_recovery_admission_epoch(recovery_epoch); let prepared = begin_forced_camera_restart(&state, &expected, recovery_epoch) .await .expect("recovery generation admitted"); let gate = Arc::clone(&state.preview_camera.lock().await.transition_gate); let cleanup_state = state.clone(); let cleanup = tokio::spawn(async move { let _physical_guard = gate.lock_owned().await; retire_panicked_camera_generation( &cleanup_state, &prepared.lease, failed_status( Some(prepared.camera_id.clone()), Some(prepared.device_unique_id.clone()), prepared.target_fps, "Injected recovery panic with blocked predecessor join.".to_string(), ), Some(&prepared), ) .await }); tokio::time::timeout(Duration::from_secs(1), stop_seen_rx) .await .expect("panic cleanup must signal predecessor stop") .expect("blocking predecessor stop sender"); let _explicit_mutation = begin_capture_recovery_explicit_camera_configuration_mutation(&state).await; assert_eq!( preview_camera_status(&state).await.state, PreviewCameraState::Starting, "Failed must not be committed before the native join finishes" ); release_tx.send(()).expect("release blocked panic join"); tokio::time::timeout(Duration::from_secs(1), exited_rx) .await .expect("predecessor exit deadline") .expect("predecessor exit sender"); let status = cleanup.await.expect("panic cleanup task"); assert_eq!(status.state, PreviewCameraState::DeviceMissing); assert_ne!(status.state, PreviewCameraState::Failed); let slot = state.preview_camera.lock().await; assert_eq!(slot.status, status); assert!(slot.active.is_none()); assert!(slot.starting.is_none()); assert_eq!(live_sessions.load(Ordering::SeqCst), 0); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); } #[tokio::test] async fn compositor_lifecycle_churn_during_blocked_recovery_join_keeps_replacement_live() { let state = test_state(); let live_sessions = Arc::new(AtomicUsize::new(0)); let max_live_sessions = Arc::new(AtomicUsize::new(0)); let FakeNativeCameraControl { release_tx, stop_seen_rx, exited_rx, } = install_blocking_fake_native_camera( &state, Arc::clone(&live_sessions), Arc::clone(&max_live_sessions), ) .await; let expected = preview_camera_restart_snapshot(&state) .await .expect("blocking camera restart snapshot"); let recovery_epoch = crate::capture_recovery::test_admit_camera_recovery_attempt( &state, expected.source_key.clone(), expected.generation, ) .await; let prepared = begin_forced_camera_restart(&state, &expected, recovery_epoch) .await .expect("recovery generation admitted"); let replacement_generation = prepared.lease.generation; let stop_state = state.clone(); let stop_lease = prepared.lease.clone(); let stop = tokio::spawn(async move { stop_current_camera_for_restart_if_admitted( &stop_state, Some(&stop_lease), Some(recovery_epoch), ) .await }); tokio::time::timeout(Duration::from_secs(1), stop_seen_rx) .await .expect("recovery restart must signal predecessor stop") .expect("blocking predecessor stop sender"); assert!( state.preview_camera.lock().await.active.is_none(), "the predecessor must already be detached while its native join blocks" ); crate::capture_recovery::note_compositor_lifecycle_changed( &state, Some("compositor-after-surface-restart".to_string()), ) .await; assert!( state.capture_recovery_admission_is_current(recovery_epoch), "downstream compositor churn must not revoke an admitted physical camera replacement" ); release_tx .send(()) .expect("release blocked predecessor join"); tokio::time::timeout(Duration::from_secs(1), exited_rx) .await .expect("predecessor exit deadline") .expect("predecessor exit sender"); assert!( tokio::time::timeout(Duration::from_secs(1), stop) .await .expect("predecessor retirement deadline") .expect("predecessor retirement task"), "compositor churn must not supersede the camera restart lease" ); // Exercise the exact admission claim used by the real native Live // install without opening a platform camera in this deterministic test. let layout = prepared.params.layout.clone(); let video = prepared.params.video.clone(); let source_key = prepared.source_key.clone(); let mut live_status = test_camera_starting_status(&source_key, &video); live_status.state = PreviewCameraState::Live; live_status.width = Some(video.width); live_status.height = Some(video.height); live_status.actual_width = Some(video.width); live_status.actual_height = Some(video.height); live_status.frames_captured = 1; live_status.sequence = Some(1); live_status.message = Some("Replacement fake native camera live.".to_string()); let (replacement_stop_tx, _replacement_stop_rx) = std_mpsc::channel(); let installed = { let mut slot = state.preview_camera.lock().await; if !claim_camera_start_if_admitted( &state, &mut slot, &prepared.lease, Some(recovery_epoch), ) { false } else { slot.status = live_status.clone(); slot.run_id = Some("replacement-camera-run".to_string()); slot.source_key = Some(source_key.clone()); slot.active = Some(NativeCameraPreviewThread { stop_tx: replacement_stop_tx, join_handle: None, shared: Arc::new(StdMutex::new(PreviewCameraShared::default())), camera_id: prepared.camera_id, device_unique_id: prepared.device_unique_id, ffmpeg_path: prepared.ffmpeg_path, layout: layout.clone(), video: video.clone(), effective_fps: video.fps, configured_output: (video.width, video.height), capture_target: camera_capture_target_dimensions(&layout, &video), }); slot.active_generation = Some(replacement_generation); slot.live_acked_at = Some(Instant::now()); true } }; assert!( installed, "the admitted replacement must cross Live install" ); acquire_preview_camera_source(&state, source_key, SourceLifecycleStatus::Live).await; assert_eq!( preview_camera_status(&state).await.state, PreviewCameraState::Live ); assert_eq!( state.preview_camera.lock().await.active_generation, Some(replacement_generation) ); assert_eq!(live_sessions.load(Ordering::SeqCst), 0); assert_eq!(max_live_sessions.load(Ordering::SeqCst), 1); } #[tokio::test] async fn recovery_invalidated_after_old_stop_cannot_cross_native_spawn_boundary() { let state = test_state(); let layout = test_layout(false); let video = test_video(); let (_, old_shared) = install_restartable_camera(&state, 21, &layout, &video).await; let expected = preview_camera_restart_snapshot(&state) .await .expect("live restart snapshot"); let recovery_epoch = 212; state.set_capture_recovery_admission_epoch(recovery_epoch); let prepared = begin_forced_camera_restart(&state, &expected, recovery_epoch) .await .expect("recovery generation admitted"); assert!( stop_current_camera_for_restart_if_admitted( &state, Some(&prepared.lease), Some(recovery_epoch), ) .await, "the current ticket may retire its old generation" ); assert_eq!(Arc::strong_count(&old_shared), 1); let _explicit_mutation = begin_capture_recovery_explicit_camera_configuration_mutation(&state).await; { let slot = state.preview_camera.lock().await; assert!( !camera_start_admission_is_current_locked( &state, &slot, Some(&prepared.lease), Some(recovery_epoch), ), "an operator intent admitted after the old join must prevent native spawn" ); assert!(slot.pending_native.is_none()); assert!(slot.active.is_none()); } let status = current_or_retire_superseded_camera_start(&state, &prepared).await; assert_eq!(status.state, PreviewCameraState::DeviceMissing); let slot = state.preview_camera.lock().await; assert!(slot.starting.is_none()); assert!(slot.pending_native.is_none()); assert!(slot.active.is_none()); } #[tokio::test] async fn recovery_invalidated_after_native_spawn_cannot_cross_live_install_boundary() { let state = test_state(); let layout = test_layout(false); let video = test_video(); let _ = install_restartable_camera(&state, 25, &layout, &video).await; let expected = preview_camera_restart_snapshot(&state) .await .expect("live restart snapshot"); let recovery_epoch = 213; state.set_capture_recovery_admission_epoch(recovery_epoch); let prepared = begin_forced_camera_restart(&state, &expected, recovery_epoch) .await .expect("recovery generation admitted"); assert!( stop_current_camera_for_restart_if_admitted( &state, Some(&prepared.lease), Some(recovery_epoch), ) .await ); let (stop_tx, stop_rx) = std_mpsc::channel(); { let mut slot = state.preview_camera.lock().await; slot.pending_native = Some(PendingNativeCameraThread { generation: prepared.lease.generation, stop_tx, join_handle: None, }); } let _explicit_mutation = begin_capture_recovery_explicit_camera_configuration_mutation(&state).await; { let mut slot = state.preview_camera.lock().await; assert!( !claim_camera_start_if_admitted( &state, &mut slot, &prepared.lease, Some(recovery_epoch), ), "a registered pending native owner must not install after operator supersession" ); assert!(slot.active.is_none()); assert!(slot.pending_native.is_some()); } stop_pending_camera_generation(&state, prepared.lease.generation, "test-superseded").await; stop_rx .recv_timeout(Duration::from_secs(1)) .expect("superseded pending native owner receives stop"); let status = current_or_retire_superseded_camera_start(&state, &prepared).await; assert_eq!(status.state, PreviewCameraState::DeviceMissing); let slot = state.preview_camera.lock().await; assert!(slot.starting.is_none()); assert!(slot.pending_native.is_none()); assert!(slot.active.is_none()); } #[tokio::test] async fn recovery_epoch_invalidated_after_queue_check_cannot_stop_old_or_spawn_new_camera() { let state = test_state(); let layout = test_layout(false); let video = test_video(); let (_source_key, old_shared) = install_restartable_camera(&state, 23, &layout, &video).await; let expected = preview_camera_restart_snapshot(&state) .await .expect("live restart snapshot"); let recovery_epoch = 202; state.set_capture_recovery_admission_epoch(recovery_epoch); let prepared = begin_forced_camera_restart(&state, &expected, recovery_epoch) .await .expect("recovery generation admitted"); assert!( prepared_camera_admission_is_current(&state, &prepared), "fixture crosses the queue supervisor's first epoch check" ); // This is the adversarial barrier: explicit configuration wins after // the queue-level check but before start_registered acquires physical // stop authority. let _explicit_mutation = begin_capture_recovery_explicit_camera_configuration_mutation(&state).await; let status = start_registered_preview_camera(state.clone(), prepared).await; assert_eq!(status.state, PreviewCameraState::Live); let slot = state.preview_camera.lock().await; assert_eq!(slot.start_generation, 24); assert_eq!(slot.active_generation, Some(23)); assert!(slot.starting.is_none()); assert!(slot.starting_recovery_epoch.is_none()); assert!( slot.active .as_ref() .is_some_and(|active| Arc::ptr_eq(&active.shared, &old_shared)) ); assert!(slot.pending_native.is_none()); } #[tokio::test] async fn failed_recovery_retry_is_generation_cas_and_preserves_private_config() { let state = test_state(); let layout = test_layout(true); let video = test_video(); let (source_key, _) = install_restartable_camera(&state, 31, &layout, &video).await; let expected = preview_camera_restart_snapshot(&state) .await .expect("live restart snapshot"); let recovery_epoch = 102; state.set_capture_recovery_admission_epoch(recovery_epoch); let prepared = begin_forced_camera_restart(&state, &expected, recovery_epoch) .await .expect("forced reservation"); let failed_generation = prepared.lease.generation; stop_current_camera_for_restart(&state).await; let failure = failed_status( Some(prepared.camera_id.clone()), Some(prepared.device_unique_id.clone()), prepared.target_fps, "synthetic startup failure".to_string(), ); assert!( set_camera_status_for_start(&state, &prepared.lease, Some(recovery_epoch), failure,) .await ); assert!( failed_preview_camera_retry_is_current(&state, &source_key, failed_generation).await ); assert!( !failed_preview_camera_retry_is_current(&state, &source_key, expected.generation).await ); assert!( !failed_preview_camera_retry_is_current( &state, &SourceKey::camera("camera:avfoundation-native:other"), failed_generation, ) .await ); let retry = begin_failed_camera_recovery_retry( &state, &source_key, failed_generation, recovery_epoch, ) .await .expect("exact failed generation is retryable"); assert_eq!(retry.lease.generation, failed_generation + 1); assert_eq!(retry.params.layout, layout); assert_eq!(retry.params.video, video); assert_eq!(retry.ffmpeg_path, "/resolved/ffmpeg"); assert_eq!(retry.device_unique_id, "test"); assert!( !failed_preview_camera_retry_is_current(&state, &source_key, failed_generation).await, "reserving the next generation consumes the old failed token" ); stop_current_camera_for_restart(&state).await; let second_failure = failed_status( Some(retry.camera_id.clone()), Some(retry.device_unique_id.clone()), retry.target_fps, "synthetic retry failure".to_string(), ); assert!( set_camera_status_for_start( &state, &retry.lease, Some(recovery_epoch), second_failure, ) .await ); assert!( failed_preview_camera_retry_is_current(&state, &source_key, retry.lease.generation) .await ); let stop = begin_preview_camera_stop(&state).await; let _ = finish_preview_camera_stop(stop).await; assert!( !failed_preview_camera_retry_is_current(&state, &source_key, retry.lease.generation) .await, "an ordinary stop invalidates the opaque retry authority" ); } #[tokio::test] async fn same_key_new_camera_generation_replaces_source_and_releases_old_owner() { let state = test_state(); let layout = test_layout(false); let video = test_video(); let (source_key, old_shared) = install_restartable_camera(&state, 11, &layout, &video).await; let old_source = preview_camera_frame_source(&state) .await .expect("old frame source"); let expected = preview_camera_restart_snapshot(&state) .await .expect("restart snapshot"); let recovery_epoch = 103; state.set_capture_recovery_admission_epoch(recovery_epoch); let prepared = begin_forced_camera_restart(&state, &expected, recovery_epoch) .await .expect("forced restart reservation"); stop_current_camera_for_restart(&state).await; assert_eq!( Arc::strong_count(&old_shared), 2, "only test + old reader remain" ); let new_shared = Arc::new(StdMutex::new(PreviewCameraShared::default())); let (stop_tx, _stop_rx) = std_mpsc::channel(); { let mut slot = state.preview_camera.lock().await; assert!(claim_camera_start(&mut slot, &prepared.lease)); slot.status.state = PreviewCameraState::Live; slot.source_key = Some(source_key.clone()); slot.active_generation = Some(prepared.lease.generation); slot.active = Some(NativeCameraPreviewThread { stop_tx, join_handle: None, shared: Arc::clone(&new_shared), camera_id: prepared.camera_id, device_unique_id: prepared.device_unique_id, ffmpeg_path: prepared.ffmpeg_path, layout: prepared.params.layout, video: prepared.params.video, effective_fps: prepared.target_fps, configured_output: (video.width, video.height), capture_target: prepared.lease.key.capture_target, }); } let new_source = preview_camera_frame_source(&state) .await .expect("new frame source"); assert_eq!(old_source.source_key(), new_source.source_key()); assert_eq!(old_source.generation(), 11); assert_eq!(new_source.generation(), 12); assert!(!Arc::ptr_eq(&old_source.shared, &new_source.shared)); drop(old_source); assert_eq!( Arc::strong_count(&old_shared), 1, "old reader releases its session owner" ); } #[tokio::test] async fn pipe_camera_frames_advance_recovery_callback_evidence() { let state = test_state(); let video = test_video(); let (_, shared) = install_restartable_camera(&state, 22, &test_layout(false), &video).await; let snapshot = preview_camera_restart_snapshot(&state) .await .expect("restart snapshot"); let baseline = preview_camera_recovery_evidence(&state, &snapshot) .await .expect("baseline evidence"); assert_eq!(baseline.capture_callback_count, 0); let started = Instant::now(); { let mut shared = shared.lock().unwrap(); for frame in 0..3u64 { shared.record_pipe_frame_callback(started + Duration::from_millis(33 * frame)); } } let evidence = preview_camera_recovery_evidence(&state, &snapshot) .await .expect("current evidence"); assert_eq!( evidence.capture_callback_count, 3, "a pipe camera's frames are its capture callbacks" ); assert_eq!(shared.lock().unwrap().capture_timings.gap_sample_count(), 2); } #[tokio::test] async fn camera_recovery_evidence_is_bound_to_exact_active_generation() { let state = test_state(); let video = test_video(); let (_, shared) = install_restartable_camera(&state, 21, &test_layout(false), &video).await; { let mut shared = shared.lock().unwrap(); shared.capture_callback_count = 4; shared.frames_captured = 3; shared.source_fps = Some(29.97); shared .capture_drop_reasons .record(CameraCaptureDropReason::FrameWasLate); shared .capture_drop_reasons .record(CameraCaptureDropReason::OutOfBuffers); shared .capture_drop_reasons .record(CameraCaptureDropReason::OutOfBuffers); shared.frame_store.publish( 9, video.width, video.height, PreviewCameraPixelFormat::Bgra8, Instant::now(), vec![0; 4], ); } { let mut slot = state.preview_camera.lock().await; slot.status.actual_width = None; slot.status.actual_height = None; } let snapshot = preview_camera_restart_snapshot(&state) .await .expect("restart snapshot"); let evidence = preview_camera_recovery_evidence(&state, &snapshot) .await .expect("current evidence"); assert_eq!(evidence.generation, 21); assert_eq!(evidence.capture_callback_count, 4); assert_eq!(evidence.frame_store_publications, 3); assert_eq!(evidence.source_fps, Some(29.97)); assert_eq!(evidence.did_drop_callback_count, 3); assert_eq!(evidence.out_of_buffers, 2); assert_eq!(evidence.surface_backing_live_count, 0); assert_eq!(evidence.surface_backing_peak_count, 0); assert_eq!(evidence.latest_sequence, Some(9)); assert_eq!(evidence.requested_width, Some(video.width)); assert_eq!(evidence.configured_width, Some(video.width)); assert_eq!(evidence.configured_height, Some(video.height)); assert_eq!(evidence.actual_width, Some(video.width)); assert_eq!(evidence.actual_height, Some(video.height)); state.preview_camera.lock().await.active_generation = Some(22); assert!( preview_camera_recovery_evidence(&state, &snapshot) .await .is_none(), "a same-key replacement must invalidate old evidence authority" ); } #[tokio::test] async fn negotiated_low_camera_fps_remains_the_generation_liveness_target() { let state = test_state(); let mut video = test_video(); video.fps = 30; let (_, shared) = install_restartable_camera(&state, 25, &test_layout(false), &video).await; shared.lock().unwrap().frame_store.publish( 2, video.width, video.height, PreviewCameraPixelFormat::Bgra8, Instant::now(), vec![0; 4], ); { let mut slot = state.preview_camera.lock().await; slot.active.as_mut().unwrap().effective_fps = stable_effective_camera_fps(14.985, video.fps); // Dynamic delivery can decay below the negotiated cadence; it must // not lower the expected-rate oracle for its own generation. slot.status.source_fps = Some(3.0); } let source = preview_camera_frame_source(&state) .await .expect("camera frame source"); assert_eq!(source.target_fps(), 15); let snapshot = preview_camera_restart_snapshot(&state) .await .expect("restart snapshot"); let evidence = preview_camera_recovery_evidence(&state, &snapshot) .await .expect("generation evidence"); assert_eq!(evidence.target_fps, 15); assert_eq!(evidence.configured_width, Some(video.width)); assert_eq!(evidence.actual_width, Some(video.width)); } #[tokio::test] async fn public_camera_stop_waits_for_the_capture_transition_gate() { let state = test_state(); let gate = Arc::clone(&state.preview_camera.lock().await.transition_gate); let guard = gate.lock_owned().await; let stop_state = state.clone(); let stop = tokio::spawn(async move { stop_preview_camera(&stop_state).await }); tokio::task::yield_now().await; assert!( !stop.is_finished(), "stop must not cross an active start/restart edge" ); drop(guard); let status = tokio::time::timeout(Duration::from_secs(1), stop) .await .expect("stop should proceed once transition completes") .expect("stop task"); assert_eq!(status.state, PreviewCameraState::DeviceMissing); } #[test] fn shared_nv12_conversion_preserves_bt709_video_range_pixels() { let y = [16, 235, 81, 145]; let cbcr = [128, 128]; let mut out = [0; 16]; nv12_to_bgra(&y, 2, &cbcr, 2, 2, 2, false, &mut out); for (index, luma) in y.into_iter().enumerate() { let (b, g, r) = ycbcr_bt709_video_to_bgr(luma, 128, 128); assert_eq!(&out[index * 4..index * 4 + 4], &[b, g, r, 255]); } } #[test] fn shared_yuv422_conversion_accepts_uyvy_and_yuy2_ordering() { let mut uyvy_out = [0; 8]; let mut yuy2_out = [0; 8]; yuv422_to_bgra(&[128, 16, 128, 235], 4, 2, 1, true, &mut uyvy_out); yuv422_to_bgra(&[16, 128, 235, 128], 4, 2, 1, false, &mut yuy2_out); assert_eq!(uyvy_out, yuy2_out); assert_eq!(uyvy_out[3], 255); assert_eq!(uyvy_out[7], 255); } #[test] fn missing_camera_status_is_device_missing() { let status = status_for_missing_camera(None, "No camera"); assert_eq!(status.state, PreviewCameraState::DeviceMissing); assert_eq!(status.frames_captured, 0); assert_eq!(status.dropped_frames, 0); } #[test] fn idle_status_has_no_active_camera_identity() { let status = idle_status(None); assert_eq!(status.state, PreviewCameraState::DeviceMissing); assert_eq!(status.camera_id, None); assert_eq!(status.device_unique_id, None); } #[test] fn mirrors_rgba_rows_in_place() { let mut pixels = vec![1, 0, 0, 255, 2, 0, 0, 255, 3, 0, 0, 255, 4, 0, 0, 255]; mirror_rgba_in_place(&mut pixels, 4, 1); assert_eq!( pixels, vec![4, 0, 0, 255, 3, 0, 0, 255, 2, 0, 0, 255, 1, 0, 0, 255] ); } #[test] fn downscales_camera_preview_png_payload() { let bytes = vec![255; 8 * 4 * 4]; let (scaled, width, height) = downscale_rgba_for_preview(bytes, 8, 4, 4); assert_eq!(width, 4); assert_eq!(height, 2); assert_eq!(scaled.len(), 4 * 2 * 4); } #[test] fn downscales_camera_preview_with_filtered_sampling() { let bytes = vec![0, 0, 0, 255, 255, 255, 255, 255]; let (scaled, width, height) = downscale_rgba_for_preview(bytes, 2, 1, 1); assert_eq!(width, 1); assert_eq!(height, 1); assert!( scaled[0] > 0 && scaled[0] < 255, "expected filtered red channel, got {}", scaled[0] ); assert_eq!(scaled[0], scaled[1]); assert_eq!(scaled[1], scaled[2]); assert_eq!(scaled[3], 255); } #[test] fn camera_png_width_defaults_and_clamps_requested_quality() { assert_eq!(preview_camera_png_max_width(None), 1280); assert_eq!(preview_camera_png_max_width(Some(0)), 1); assert_eq!(preview_camera_png_max_width(Some(1280)), 1280); assert_eq!(preview_camera_png_max_width(Some(4096)), 1920); } #[test] fn camera_capture_cpu_copy_is_skipped_only_for_native_zero_copy_source_handle() { assert!(should_skip_camera_capture_cpu_copy_for_config( true, true, true, false )); assert!(!should_skip_camera_capture_cpu_copy_for_config( false, true, true, false )); assert!(!should_skip_camera_capture_cpu_copy_for_config( true, false, true, false )); assert!(!should_skip_camera_capture_cpu_copy_for_config( true, true, false, false )); assert!(!should_skip_camera_capture_cpu_copy_for_config( true, true, true, true )); } #[test] fn camera_start_params_keep_layout_and_video_contract() { let params = PreviewCameraStartParams { sources: crate::protocol::SourceSelection { screen_id: None, window_id: None, camera_id: Some("camera:avfoundation-native:abc123".to_string()), microphone_id: None, test_pattern: false, }, layout: test_layout(true), video: test_video(), ffmpeg_path: None, }; assert_eq!(params.video.fps, 60); assert!(params.layout.camera_mirror); } #[test] fn selects_avfoundation_camera_source() { assert_eq!( selected_camera_source("camera:avfoundation-native:616263").unwrap(), SelectedCameraSource::MacAvFoundation { unique_id: "abc".to_string() } ); } #[test] fn selects_windows_dshow_camera_source() { assert_eq!( selected_camera_source("camera:windows-dshow:5553422043616d657261").unwrap(), SelectedCameraSource::WindowsDshow { device_name: "USB Camera".to_string() } ); } #[test] fn windows_camera_preview_ffmpeg_args_emit_raw_bgra_frames() { let config = NativeCameraPreviewConfig { camera_id: "camera:windows-dshow:5553422043616d657261".to_string(), unique_id: "USB Camera".to_string(), ffmpeg_path: "C:\\ffmpeg\\bin\\ffmpeg.exe".to_string(), video: test_video(), layout: test_layout(false), studio_effects: Default::default(), }; let (width, height) = windows_camera_preview_output_dimensions(&config); let args = windows_camera_preview_ffmpeg_args_for( &config, &WindowsCameraCaptureAttempt::ExactRate(config.video.fps), (width, height), config.video.fps, ); assert_eq!((width, height), (1920, 1080)); let framerate = config.video.fps.to_string(); assert!( args.windows(2) .any(|pair| pair[0] == "-framerate" && pair[1] == framerate) ); assert!(args.windows(2).any(|pair| pair == ["-f", "dshow"])); assert!( args.windows(2) .any(|pair| pair == ["-i", "video=USB Camera"]) ); assert!(args.iter().any(|arg| arg.contains("scale=1920:1080"))); assert!(!args.iter().any(|arg| arg.starts_with("fps="))); assert!(args.windows(2).any(|pair| pair == ["-pix_fmt", "bgra"])); assert!(args.windows(2).any(|pair| pair == ["-f", "rawvideo"])); assert_eq!(args.last().map(String::as_str), Some("-")); } #[test] fn windows_camera_preview_prefers_explicit_mjpeg_device_mode() { let config = NativeCameraPreviewConfig { camera_id: "camera:windows-dshow:5553422043616d657261".to_string(), unique_id: "USB Camera".to_string(), ffmpeg_path: "C:\\ffmpeg\\bin\\ffmpeg.exe".to_string(), video: test_video(), layout: test_layout(false), studio_effects: Default::default(), }; let attempt = WindowsCameraCaptureAttempt::Mode { mode: test_dshow_mode(DshowModeFormat::Mjpeg, 1280, 720, 5.0, 30.0), fps: 30.0, best_listed: true, }; let args = windows_camera_preview_ffmpeg_args_for(&config, &attempt, (1280, 720), 30); let input_index = args .iter() .position(|arg| arg == "-i") .expect("DirectShow input marker"); assert!( args[..input_index] .windows(2) .any(|pair| { pair == ["-video_size", "1280x720"] }) ); assert!( args[..input_index] .windows(2) .any(|pair| pair == ["-vcodec", "mjpeg"]) ); assert!( args[..input_index] .windows(2) .any(|pair| pair == ["-framerate", "30"]) ); assert!(!args.iter().any(|arg| arg == "-pixel_format")); } fn test_dshow_mode( format: DshowModeFormat, width: u32, height: u32, min_fps: f64, max_fps: f64, ) -> DshowVideoMode { DshowVideoMode { format, width, height, min_fps, max_fps, } } fn yuy2() -> DshowModeFormat { DshowModeFormat::Raw("yuyv422".to_string()) } fn explicit_modes(attempts: &[WindowsCameraCaptureAttempt]) -> Vec { attempts .iter() .map(WindowsCameraCaptureAttempt::label) .collect() } #[test] fn windows_camera_raw_mode_is_asked_for_by_pixel_format_size_and_listed_rate() { let config = NativeCameraPreviewConfig { camera_id: "camera:windows-dshow:5553422043616d657261".to_string(), unique_id: "USB Camera".to_string(), ffmpeg_path: "C:\\ffmpeg\\bin\\ffmpeg.exe".to_string(), video: test_video(), layout: test_layout(false), studio_effects: Default::default(), }; // A mode listed at 29.97 is asked for at 29.97: DirectShow refuses // a rate outside the mode's range, so 30 would fail the rung. let mode = test_dshow_mode(yuy2(), 640, 480, 7.5, 29.97); assert_eq!(mode.request_fps(30), 29.97); let attempt = WindowsCameraCaptureAttempt::Mode { fps: mode.request_fps(30), mode, best_listed: true, }; let args = windows_camera_preview_ffmpeg_args_for(&config, &attempt, (640, 480), 30); let input_index = args.iter().position(|arg| arg == "-i").unwrap(); let input = &args[..input_index]; assert!( input .windows(2) .any(|pair| pair == ["-pixel_format", "yuyv422"]) ); assert!( input .windows(2) .any(|pair| pair == ["-video_size", "640x480"]) ); assert!(input.windows(2).any(|pair| pair == ["-framerate", "29.97"])); assert!(!input.iter().any(|arg| arg == "-vcodec")); // Piped at the mode's own size, scaled only to pin the frame length. assert!(args.iter().any(|arg| arg.contains("scale=640:480"))); assert!(!args.iter().any(|arg| arg.contains("prev_selected_t"))); } // `ffmpeg -list_options true -f dshow` on a Logitech C920 behind the // Windows camera frame server (2026-10-27): uncompressed modes only. const C920_FRAME_SERVER_OPTIONS: &str = "[dshow @ 0000025dbdd84e00] DirectShow video device options (from video devices) [dshow @ 0000025dbdd84e00] Pin \"Capture\" (alternative pin name \"0\") [in#0 @ 0000025dbdd84e00] pixel_format=yuyv422 min s=1920x1080 fps=30 max s=1920x1080 fps=30 [in#0 @ 0000025dbdd84e00] pixel_format=nv12 min s=1920x1080 fps=30 max s=1920x1080 fps=30 [in#0 @ 0000025dbdd84e00] Error opening input file video=HD Pro Webcam C920."; const MJPEG_WEBCAM_OPTIONS: &str = "[in#0 @ 000001] vcodec=mjpeg min s=1280x720 fps=30 max s=1280x720 fps=30 [in#0 @ 000001] vcodec=mjpeg min s=640x360 fps=30 max s=640x360 fps=30 [in#0 @ 000001] vcodec=mjpeg min s=1280x720 fps=5 max s=1280x720 fps=30 [in#0 @ 000001] pixel_format=yuyv422 min s=1280x720 fps=10 max s=1280x720 fps=10"; /// A LifeCam HD-3000 style listing (issue #1271): no MJPEG, eleven raw /// modes, 720p only at 10 fps over USB 2. const LIFECAM_STYLE_OPTIONS: &str = "[in#0 @ 0] pixel_format=yuyv422 min s=640x480 fps=7.5 max s=640x480 fps=30 [in#0 @ 0] pixel_format=yuyv422 min s=1280x720 fps=7.5 max s=1280x720 fps=10 [in#0 @ 0] pixel_format=yuyv422 min s=960x544 fps=7.5 max s=960x544 fps=15 [in#0 @ 0] pixel_format=yuyv422 min s=800x448 fps=7.5 max s=800x448 fps=30 [in#0 @ 0] pixel_format=yuyv422 min s=640x360 fps=7.5 max s=640x360 fps=30 [in#0 @ 0] pixel_format=yuyv422 min s=424x240 fps=7.5 max s=424x240 fps=30 [in#0 @ 0] pixel_format=yuyv422 min s=352x288 fps=7.5 max s=352x288 fps=30 [in#0 @ 0] pixel_format=yuyv422 min s=320x240 fps=7.5 max s=320x240 fps=30 [in#0 @ 0] pixel_format=yuyv422 min s=800x600 fps=7.5 max s=800x600 fps=30 [in#0 @ 0] pixel_format=yuyv422 min s=176x144 fps=7.5 max s=176x144 fps=30 [in#0 @ 0] pixel_format=yuyv422 min s=160x120 fps=7.5 max s=160x120 fps=30"; #[test] fn dshow_mode_probe_reads_every_mode_with_its_format_and_rate_range() { assert_eq!( parse_dshow_advertised_video_modes(C920_FRAME_SERVER_OPTIONS).modes, vec![ test_dshow_mode(yuy2(), 1920, 1080, 30.0, 30.0), test_dshow_mode( DshowModeFormat::Raw("nv12".to_string()), 1920, 1080, 30.0, 30.0 ), ] ); // The two 1280x720 MJPEG lines merge into the widest range. assert_eq!( parse_dshow_advertised_video_modes(MJPEG_WEBCAM_OPTIONS).modes, vec![ test_dshow_mode(DshowModeFormat::Mjpeg, 1280, 720, 5.0, 30.0), test_dshow_mode(DshowModeFormat::Mjpeg, 640, 360, 30.0, 30.0), test_dshow_mode(yuy2(), 1280, 720, 10.0, 10.0), ] ); let lifecam = parse_dshow_advertised_video_modes(LIFECAM_STYLE_OPTIONS); assert_eq!(lifecam.modes.len(), 11); assert_eq!(lifecam.mjpeg_count(), 0); assert_eq!(lifecam.largest_size(), Some((1280, 720))); assert!( lifecam .summary() .starts_with("YUYV422 640x480@7.5-30, YUYV422 1280x720@7.5-10") ); // A codec the preview never asks for explicitly is still listed. let h264 = parse_dshow_advertised_video_modes( "[in#0 @ 0] vcodec=h264 min s=1920x1080 fps=30 max s=1920x1080 fps=30", ); assert_eq!( h264.modes[0].format, DshowModeFormat::OtherCodec("h264".to_string()) ); assert!( parse_dshow_advertised_video_modes("Error opening input files: I/O error").is_empty() ); } #[test] fn windows_camera_720p_webcam_on_a_1440p_canvas_runs_its_largest_30fps_mode() { // Issue #1271: the LifeCam was asked for 2560x1440 and ran at 15 fps. let lifecam = parse_dshow_advertised_video_modes(LIFECAM_STYLE_OPTIONS); let attempts = windows_camera_capture_attempts(2560, 1440, 30, Some(&lifecam)); assert_eq!( explicit_modes(&attempts), vec![ // 800x600 is 4:3 but holds an 800x450 16:9 picture, a // little more than 800x448. 640x360 and 640x480 hold the // same picture; the smaller one wins. "YUYV422 800x600@30", "YUYV422 800x448@30", "YUYV422 640x360@30", "default format @30", "negotiated default format", ] ); // The 10 fps 720p mode is never chosen over a 30 fps one. assert!( !explicit_modes(&attempts) .iter() .any(|label| label.contains("1280x720")) ); // Piped at the mode's own size, not the canvas. let output = windows_camera_attempt_output_dimensions(&attempts[0], (2560, 1440), Some(&lifecam)); assert_eq!(output, (800, 600)); // The fallbacks keep the canvas shape, shrunk to the camera's largest size. assert_eq!( windows_camera_attempt_output_dimensions(&attempts[3], (2560, 1440), Some(&lifecam)), (1280, 720) ); assert_eq!( windows_camera_attempt_output_dimensions(&attempts[3], (2560, 1440), None), (2560, 1440), "without a listing the fallbacks keep the target" ); } #[test] fn windows_camera_mode_choice_prefers_the_target_rate_then_the_picture() { // A camera that reaches 30 only in MJPEG: MJPEG 1080p30 beats the // raw 10 fps 720p mode and the bigger raw mode at 5 fps. let webcam = DshowAdvertisedVideoModes { modes: vec![ test_dshow_mode(yuy2(), 1920, 1080, 5.0, 5.0), test_dshow_mode(yuy2(), 1280, 720, 10.0, 10.0), test_dshow_mode(DshowModeFormat::Mjpeg, 1920, 1080, 30.0, 30.0), test_dshow_mode(DshowModeFormat::Mjpeg, 1280, 720, 30.0, 30.0), ], }; assert_eq!( explicit_modes(&windows_camera_capture_attempts( 1920, 1080, 30, Some(&webcam) )), vec![ "MJPEG 1920x1080@30", "MJPEG 1280x720@30", "YUYV422 1280x720@10", "default format @30", "negotiated default format", ] ); // Bigger than the target buys nothing: the mode that just covers a // 360x203 inset wins over 1080p, and MJPEG before raw at one size. let both = DshowAdvertisedVideoModes { modes: vec![ test_dshow_mode(yuy2(), 640, 360, 30.0, 30.0), test_dshow_mode(DshowModeFormat::Mjpeg, 1920, 1080, 30.0, 30.0), test_dshow_mode(DshowModeFormat::Mjpeg, 640, 360, 30.0, 30.0), ], }; assert_eq!( explicit_modes(&windows_camera_capture_attempts(360, 203, 30, Some(&both)))[..3], [ "MJPEG 640x360@30", "YUYV422 640x360@30", "MJPEG 1920x1080@30" ] ); // The frame-server C920 lists only raw 1080p30: it is asked for it. let c920 = parse_dshow_advertised_video_modes(C920_FRAME_SERVER_OPTIONS); assert_eq!( explicit_modes(&windows_camera_capture_attempts( 1920, 1080, 30, Some(&c920) )), vec![ "YUYV422 1920x1080@30", "NV12 1920x1080@30", "default format @30", "negotiated default format", ] ); } #[test] fn windows_camera_without_a_mode_at_the_target_rate_takes_the_fastest() { // Nothing reaches 60: the 30 fps mode beats the bigger 15 fps one, // and is asked for at its own top rate. let camera = DshowAdvertisedVideoModes { modes: vec![ test_dshow_mode(yuy2(), 1920, 1080, 5.0, 15.0), test_dshow_mode(yuy2(), 1280, 720, 5.0, 30.0), test_dshow_mode(yuy2(), 640, 360, 5.0, 30.0), ], }; let attempts = windows_camera_capture_attempts(1920, 1080, 60, Some(&camera)); assert_eq!( explicit_modes(&attempts)[..3], [ "YUYV422 1280x720@30", "YUYV422 640x360@30", "YUYV422 1920x1080@15" ] ); // H.264 modes are never asked for explicitly. let h264_only = DshowAdvertisedVideoModes { modes: vec![test_dshow_mode( DshowModeFormat::OtherCodec("h264".to_string()), 1920, 1080, 30.0, 30.0, )], }; assert_eq!( explicit_modes(&windows_camera_capture_attempts( 1920, 1080, 30, Some(&h264_only) )), vec!["default format @30", "negotiated default format"] ); } #[test] fn windows_camera_live_status_names_the_mode_that_runs() { let mode = test_dshow_mode(yuy2(), 800, 600, 7.5, 30.0); let attempt = WindowsCameraCaptureAttempt::Mode { mode, fps: 30.0, best_listed: true, }; let NativeCameraStartup::Live { requested_width, requested_height, selected_format_width, selected_format_height, selected_format_min_fps, selected_format_max_fps, width, height, selected_fps, message, } = windows_camera_live_startup(&attempt, (2560, 1440), (800, 600), 30) else { panic!("a live start"); }; assert_eq!((requested_width, requested_height), (2560, 1440)); assert_eq!((selected_format_width, selected_format_height), (800, 600)); assert_eq!( (selected_format_min_fps, selected_format_max_fps), (7.5, 30.0) ); assert_eq!((width, height, selected_fps), (800, 600, 30.0)); // The Sources shortfall warning reads this sentence (plan 024 S5). let message = message.unwrap(); assert!( message.starts_with( "Requested 2560x1440@30 was not available; selected native 800x600 at 8-30 fps." ), "{message}" ); assert!(message.contains("YUYV422 800x600@30"), "{message}"); // A mode that covers the target at its rate is no shortfall. let covering = WindowsCameraCaptureAttempt::Mode { mode: test_dshow_mode(DshowModeFormat::Mjpeg, 640, 360, 30.0, 30.0), fps: 30.0, best_listed: true, }; let NativeCameraStartup::Live { message, .. } = windows_camera_live_startup(&covering, (360, 203), (360, 203), 30) else { panic!("a live start"); }; assert!(!message.unwrap().contains("Requested")); // A fallback keeps naming the piped size at the requested rate. let NativeCameraStartup::Live { selected_format_width, selected_format_max_fps, message, .. } = windows_camera_live_startup( &WindowsCameraCaptureAttempt::ExactRate(30), (2560, 1440), (1280, 720), 30, ) else { panic!("a live start"); }; assert_eq!( (selected_format_width, selected_format_max_fps), (1280, 30.0) ); assert!(!message.unwrap().contains("Requested")); } #[test] fn windows_camera_ladder_keeps_every_common_mode_without_a_probe() { let full = windows_camera_capture_attempts(1920, 1080, 30, None); assert_eq!( full.len(), windows_camera_mjpeg_capture_modes(1920, 1080).len() + 2 ); assert_eq!( full.first() .map(WindowsCameraCaptureAttempt::label) .as_deref(), Some("MJPEG 1920x1080@30") ); assert_eq!( windows_camera_capture_attempts( 1920, 1080, 30, Some(&DshowAdvertisedVideoModes::default()) ), full, "a probe that parsed nothing is no evidence" ); } #[test] fn windows_camera_overlay_uses_supported_mjpeg_capture_shape() { let modes = windows_camera_mjpeg_capture_modes(360, 203); assert_eq!(modes.first().copied(), Some((640, 360))); } /// Verbatim `-list_options` answer from the UHD 620 field laptop's /// YUY2-only "HP HD Camera". const HP_HD_CAMERA_LIST_OPTIONS: &str = r#"[in#0 @ 000001f58116f6c0] DirectShow video device options (from video devices) [in#0 @ 000001f58116f6c0] Pin "Capture" (alternative pin name "Capture") [in#0 @ 000001f58116f6c0] pixel_format=yuyv422 min s=1280x720 fps=15 max s=1280x720 fps=30 [in#0 @ 000001f58116f6c0] pixel_format=yuyv422 min s=320x180 fps=15 max s=320x180 fps=30 [in#0 @ 000001f58116f6c0] pixel_format=yuyv422 min s=640x480 fps=15 max s=640x480 fps=30 Error opening input file video=HP HD Camera."#; #[test] fn windows_dshow_mode_probe_skips_mjpeg_on_a_yuy2_only_camera() { let WindowsDshowModeProbe::Modes(modes) = classify_windows_dshow_mode_probe(HP_HD_CAMERA_LIST_OPTIONS) else { panic!("the HP HD Camera listed its modes"); }; let attempts = explicit_modes(&windows_camera_capture_attempts( 1920, 1080, 30, Some(&modes), )); assert!( !attempts.iter().any(|label| label.starts_with("MJPEG")), "a device that answered without MJPEG must not get a single MJPEG spawn" ); // Its own modes instead, largest 30 fps picture first. assert_eq!( attempts, vec![ "YUYV422 1280x720@30", "YUYV422 640x480@30", "YUYV422 320x180@30", "default format @30", "negotiated default format", ] ); } #[test] fn windows_dshow_mode_probe_without_a_listing_or_known_cause_falls_back() { assert_eq!( classify_windows_dshow_mode_probe(""), WindowsDshowModeProbe::Unreadable ); assert_eq!( classify_windows_dshow_mode_probe("[in#0 @ 0] Error opening input: I/O error"), WindowsDshowModeProbe::Unreadable ); } #[test] fn windows_dshow_mode_probe_stops_on_a_mode_independent_error() { assert_eq!( classify_windows_dshow_mode_probe( "[dshow @ 0] Could not find video device with name [Gone] among source devices of type video.\n\ Error opening input file video=Gone." ), WindowsDshowModeProbe::ModeIndependentError( "[dshow @ 0] Could not find video device with name [Gone] among source devices of type video." .to_string() ) ); // A listing wins over an error line: the device did answer. assert!(matches!( classify_windows_dshow_mode_probe(HP_HD_CAMERA_LIST_OPTIONS), WindowsDshowModeProbe::Modes(_) )); } /// A start whose native thread outlived the startup timeout is stopped, /// and the thread's stop path keeps the cache, so the timeout forgets the /// camera's modes. A deliberate stop (the channel disconnects) keeps them. #[cfg(target_os = "windows")] #[test] fn a_timed_out_windows_camera_start_forgets_its_cached_modes() { let cache = windows::windows_dshow_mode_cache(); let listing = || classify_windows_dshow_mode_probe(HP_HD_CAMERA_LIST_OPTIONS); for camera in ["@device_pnp_timed_out_start", "@device_pnp_stopped_start"] { let _ = cache.probe_through(camera, listing); assert!(cache.probe_through(camera, listing).1, "{camera} is cached"); } let startup = native_camera_startup_unanswered( std_mpsc::RecvTimeoutError::Timeout, "@device_pnp_timed_out_start", ); assert!(matches!(startup, NativeCameraStartup::Failed(_))); assert!( !cache.forget("@device_pnp_timed_out_start"), "a timed-out start must forget the camera's modes" ); let _ = native_camera_startup_unanswered( std_mpsc::RecvTimeoutError::Disconnected, "@device_pnp_stopped_start", ); assert!( cache.forget("@device_pnp_stopped_start"), "a deliberately stopped start keeps the camera's modes" ); } /// #1068 step 3: a camera's `-list_options` probe runs once; later starts /// reuse its modes until a failed start forgets them. Only a listing is /// kept, never an unreadable or error result. #[test] fn windows_dshow_mode_probe_runs_once_per_camera_until_forgotten() { let cache = DshowModeCache::default(); let probes = std::cell::Cell::new(0); let listing = || { probes.set(probes.get() + 1); classify_windows_dshow_mode_probe(HP_HD_CAMERA_LIST_OPTIONS) }; let (first, cached) = cache.probe_through("@device_pnp_cam", listing); assert!(matches!(first, WindowsDshowModeProbe::Modes(_)) && !cached); let (second, cached) = cache.probe_through("@device_pnp_cam", listing); assert!(cached, "the second start reuses the modes"); assert_eq!(first, second); assert_eq!(probes.get(), 1); // Another camera has its own entry. let (_, cached) = cache.probe_through("@device_pnp_other", listing); assert!(!cached); assert_eq!(probes.get(), 2); // A failed start forgets; the next start probes again. assert!(cache.forget("@device_pnp_cam")); assert!(!cache.forget("@device_pnp_cam")); let (_, cached) = cache.probe_through("@device_pnp_cam", listing); assert!(!cached); assert_eq!(probes.get(), 3); // Unreadable and mode-independent results are never kept. for answer in [ WindowsDshowModeProbe::Unreadable, WindowsDshowModeProbe::ModeIndependentError("Access is denied".into()), ] { let expected = format!("{answer:?}"); let (probed, cached) = cache.probe_through("@device_pnp_flaky", || answer); assert_eq!(format!("{probed:?}"), expected); assert!(!cached); assert!(!cache.forget("@device_pnp_flaky"), "{expected} was cached"); } } #[test] fn windows_dshow_mode_independent_errors_stop_the_ladder() { // FFmpeg prints this for every graph Run failure, busy device or not. assert!(!windows_dshow_error_is_mode_independent( "ended before the first frame: Could not run graph (sometimes caused by a device already in use by other application)" )); assert!(windows_dshow_error_is_mode_independent( "Could not find video device with name [HP HD Camera] among source devices of type video." )); assert!(!windows_dshow_error_is_mode_independent( "ended before the first frame: Could not set video options | Error opening input: I/O error" )); } #[test] fn windows_camera_early_attempts_leave_time_for_their_fallbacks() { use WindowsCameraAttemptKind::{ BestListedMode, ExactRate, ExplicitMode as Mjpeg, NegotiatedDefault, }; let secs = Duration::from_secs_f64; let mode = |best_listed| WindowsCameraCaptureAttempt::Mode { mode: test_dshow_mode(DshowModeFormat::Mjpeg, 1280, 720, 30.0, 30.0), fps: 30.0, best_listed, }; assert_eq!(mode(false).kind(), Mjpeg); assert_eq!(mode(true).kind(), BestListedMode); assert_eq!(WindowsCameraCaptureAttempt::ExactRate(30).kind(), ExactRate); assert_eq!( WindowsCameraCaptureAttempt::NegotiatedDefault.kind(), NegotiatedDefault ); // Issue #1271 field check: the HP HD Camera's best listed mode // after a cold 1.9 s probe. It must get the exact-rate rung's 2.6 s // (its first frame takes 1.6-2.8 s), not the speculative 1.6 s. assert_eq!( windows_camera_attempt_first_frame_timeout(Duration::from_millis(4100), BestListedMode), windows_camera_attempt_first_frame_timeout(Duration::from_millis(4100), ExactRate), ); assert_eq!( windows_camera_attempt_first_frame_timeout(Duration::from_millis(4100), BestListedMode), Some(Duration::from_millis(2600)) ); // Only the camera's own first mode is the best listed one; the // common-size ladder without a probe stays speculative. let hp = classify_windows_dshow_mode_probe(HP_HD_CAMERA_LIST_OPTIONS); let WindowsDshowModeProbe::Modes(hp) = hp else { panic!("the HP HD Camera listed its modes"); }; let kinds = |attempts: Vec| { attempts .iter() .map(WindowsCameraCaptureAttempt::kind) .collect::>() }; assert_eq!( kinds(windows_camera_capture_attempts(1920, 1080, 30, Some(&hp))), vec![BestListedMode, Mjpeg, Mjpeg, ExactRate, NegotiatedDefault] ); assert!( kinds(windows_camera_capture_attempts(1920, 1080, 30, None)) .iter() .all(|kind| *kind != BestListedMode) ); // Fresh budget: MJPEG gets its full deadline. assert_eq!( windows_camera_attempt_first_frame_timeout(secs(6.0), Mjpeg), Some(secs(3.5)) ); // A 2 s mode probe: MJPEG is cut short so the reserve survives. assert_eq!( windows_camera_attempt_first_frame_timeout(secs(4.0), Mjpeg), Some(secs(1.5)) ); // Too little left for MJPEG: skip it, but the fallbacks still run. assert_eq!( windows_camera_attempt_first_frame_timeout(secs(3.0), Mjpeg), None ); // The exact rate keeps its full deadline while the budget is fresh... assert_eq!( windows_camera_attempt_first_frame_timeout(secs(5.5), ExactRate), Some(secs(4.0)) ); // ...but after a 2 s probe it leaves the negotiated default its share. assert_eq!( windows_camera_attempt_first_frame_timeout(secs(4.0), ExactRate), Some(secs(2.5)) ); // What MJPEG left behind still fits both fallbacks. assert_eq!( windows_camera_attempt_first_frame_timeout(secs(2.5), ExactRate), Some(secs(1.0)) ); assert_eq!( windows_camera_attempt_first_frame_timeout(secs(2.0), ExactRate), None ); // The last attempt takes whatever is left, capped at the deadline. assert_eq!( windows_camera_attempt_first_frame_timeout(secs(1.25), NegotiatedDefault), Some(secs(1.25)) ); assert_eq!( windows_camera_attempt_first_frame_timeout(secs(0.5), NegotiatedDefault), Some(secs(0.5)) ); assert_eq!( windows_camera_attempt_first_frame_timeout(secs(9.0), NegotiatedDefault), Some(secs(4.0)) ); assert_eq!( windows_camera_attempt_first_frame_timeout(Duration::ZERO, NegotiatedDefault), None ); } #[cfg(target_os = "windows")] #[test] fn windows_camera_first_frame_race_has_exactly_one_winner() { use super::windows::FirstFrameRace; // The reader's frame arrives first: the killer may not kill. let reader_first = FirstFrameRace::default(); assert!(reader_first.claim_live()); assert!(!reader_first.claim_timed_out()); assert!(!reader_first.timed_out()); // The deadline passes first: the frame in the pipe is not Live. let killer_first = FirstFrameRace::default(); assert!(killer_first.claim_timed_out()); assert!(!killer_first.claim_live()); assert!(killer_first.timed_out()); // A second claim by the same side changes nothing. assert!(!killer_first.claim_timed_out()); } #[test] fn windows_camera_default_format_retry_caps_high_fps_without_duplicating_low_fps() { fn selected_frame_count(source_fps: u32, target_fps: u32) -> usize { let mut previous_selected_t = None; let mut selected = 0; for frame_index in 0..source_fps { let timestamp = f64::from(frame_index) / f64::from(source_fps); let should_select = previous_selected_t.is_none_or(|previous| { timestamp - previous + WINDOWS_CAMERA_RATE_CAP_EPSILON_SECONDS >= 1.0 / f64::from(target_fps) }); if should_select { previous_selected_t = Some(timestamp); selected += 1; } } selected } let config = NativeCameraPreviewConfig { camera_id: "camera:windows-dshow:5553422043616d657261".to_string(), unique_id: "USB Camera".to_string(), ffmpeg_path: "C:\\ffmpeg\\bin\\ffmpeg.exe".to_string(), video: test_video(), layout: test_layout(false), studio_effects: Default::default(), }; let args = windows_camera_preview_ffmpeg_args_for( &config, &WindowsCameraCaptureAttempt::NegotiatedDefault, (1920, 1080), 30, ); let filter = args .windows(2) .find_map(|pair| (pair[0] == "-vf").then_some(pair[1].as_str())) .expect("video filter"); assert!(!args.iter().any(|arg| arg == "-framerate")); assert!(filter.contains("select='isnan(prev_selected_t)")); assert!(filter.contains("gte(t-prev_selected_t+0.000001\\,1/30)")); assert!(!filter.starts_with("fps=")); assert!( args.windows(2) .any(|pair| pair == ["-fps_mode", "passthrough"]) ); assert_eq!(selected_frame_count(60, 30), 30); assert_eq!(selected_frame_count(15, 30), 15); let just_below_boundary = (1.0 / 30.0) - (WINDOWS_CAMERA_RATE_CAP_EPSILON_SECONDS / 2.0); assert!( just_below_boundary + WINDOWS_CAMERA_RATE_CAP_EPSILON_SECONDS >= 1.0 / 30.0, "the epsilon must retain a frame whose timestamp rounds just below the boundary" ); } #[test] fn rejects_unsupported_camera_source_ids() { assert!(selected_camera_source("camera:avfoundation:0").is_none()); assert!(selected_camera_source("camera:windows-dshow:not-hex").is_none()); // Plan 214 A5: a saved id naming Videorc Camera resolves to nothing. assert!( selected_camera_source(&crate::camera_capture::native_camera_device_id( crate::virtual_camera::VIRTUAL_CAMERA_MACOS_DEVICE_UUID )) .is_none() ); assert!( selected_camera_source(&crate::camera_capture::windows_dshow_camera_device_id( "Videorc Camera Windows Virtual Camera" )) .is_none() ); assert!( selected_camera_source(&crate::linux_v4l2_camera::linux_v4l2_camera_id( "/dev/video42" )) .is_none() ); } #[cfg(target_os = "macos")] #[test] fn zero_copy_camera_capture_prefers_bgra_when_available() { use objc2_core_video::{kCVPixelFormatType_32BGRA, kCVPixelFormatType_422YpCbCr8}; let selected = super::macos::select_preferred_capture_pixel_format( &[kCVPixelFormatType_422YpCbCr8, kCVPixelFormatType_32BGRA], true, ); assert_eq!(selected, kCVPixelFormatType_32BGRA); } #[cfg(target_os = "macos")] #[test] fn non_zero_copy_camera_capture_keeps_yuv_preference() { use objc2_core_video::{kCVPixelFormatType_32BGRA, kCVPixelFormatType_422YpCbCr8}; let selected = super::macos::select_preferred_capture_pixel_format( &[kCVPixelFormatType_422YpCbCr8, kCVPixelFormatType_32BGRA], false, ); assert_eq!(selected, kCVPixelFormatType_422YpCbCr8); } #[test] fn camera_only_capture_target_keeps_output_resolution() { let layout = test_layout(false); let video = test_video(); assert_eq!( camera_capture_target_dimensions(&layout, &video), (video.width, video.height) ); } #[test] fn side_by_side_capture_target_keeps_output_resolution() { let mut layout = test_layout(false); layout.layout_preset = LayoutPreset::SideBySide; let video = test_video(); assert_eq!( camera_capture_target_dimensions(&layout, &video), (video.width, video.height) ); } #[test] fn screen_camera_capture_target_keeps_output_resolution() { // Capture geometry is layout-invariant: the inset preset captures the // SAME full canvas as every other preset, so a camera-only <-> // screen+camera switch can never invalidate a running camera session // (owner-reported restarts with renegotiation garbage through 0.9.64). let mut layout = test_layout(false); layout.layout_preset = LayoutPreset::ScreenCamera; layout.camera_size = CameraSize::Medium; layout.camera_shape = CameraShape::Rectangle; let video = test_video(); assert_eq!( camera_capture_target_dimensions(&layout, &video), (video.width, video.height) ); } #[test] fn windows_camera_box_is_the_canvas_for_every_preset() { // Issue #1066: a preset switch never restarts the camera (the restart // key is layout-invariant), so the box a Windows camera pipes into // must not depend on the preset or the inset either. An inset-sized // box left a camera started under Screen + Camera at ~540x304 after // a switch to camera-only, stretched to the canvas. let config_for = |layout: LayoutSettings| NativeCameraPreviewConfig { camera_id: "camera:windows-dshow:5553422043616d657261".to_string(), unique_id: "USB Camera".to_string(), ffmpeg_path: "C:\\ffmpeg\\bin\\ffmpeg.exe".to_string(), video: test_video(), layout, studio_effects: Default::default(), }; let camera_only = test_layout(false); let mut inset = test_layout(false); inset.layout_preset = LayoutPreset::ScreenCamera; inset.camera_size = CameraSize::Small; inset.camera_shape = CameraShape::Circle; let mut custom = inset.clone(); custom.camera_transform_mode = CameraTransformMode::Custom; custom.camera_transform = Some(crate::protocol::CameraTransform { x: 0.7, y: 0.7, width: 0.2, height: 0.2, }); let mut vertical = inset.clone(); vertical.layout_preset = LayoutPreset::VerticalScreenCamera; let canvas = (test_video().width, test_video().height); for layout in [camera_only, inset, custom, vertical] { let config = config_for(layout); assert_eq!(windows_camera_preview_output_dimensions(&config), canvas); assert_eq!( windows_camera_preview_output_dimensions(&config), camera_capture_target_dimensions(&config.layout, &config.video) ); } // A 720p mode under the inset pipes its own 1280x720, not the inset. let mode = DshowVideoMode { format: DshowModeFormat::Mjpeg, width: 1280, height: 720, min_fps: 5.0, max_fps: 30.0, }; assert_eq!( windows_camera_attempt_output_dimensions( &WindowsCameraCaptureAttempt::Mode { mode, fps: 30.0, best_listed: true, }, canvas, None, ), (1280, 720) ); } #[test] fn camera_overlay_publish_dimensions_preserve_source_aspect() { assert_eq!( fit_camera_source_in_target_box(1920, 1080, 1280, 720), (1280, 720) ); assert_eq!( fit_camera_source_in_target_box(1920, 1080, 1000, 720), (1000, 563) ); } #[test] fn camera_overlay_publish_dimensions_do_not_upscale_source() { assert_eq!( fit_camera_source_in_target_box(640, 480, 1280, 720), (640, 480) ); } #[test] fn camera_capture_timing_window_reset_drops_warmup_gaps() { let mut timings = CameraCaptureTimingWindow::default(); let now = Instant::now(); timings.record_callback_at(now); timings.record_callback_at(now + Duration::from_millis(180)); timings.record_sample_pts(Some(0.0)); timings.record_sample_pts(Some(0.180)); assert_eq!(timings.snapshot().sample_pts_gap_p95_ms, Some(180.0)); timings.reset(); let reset_snapshot = timings.snapshot(); assert_eq!(reset_snapshot.capture_gap_p95_ms, None); assert_eq!(reset_snapshot.sample_pts_gap_p95_ms, None); timings.record_callback_at(now + Duration::from_millis(220)); timings.record_callback_at(now + Duration::from_millis(253)); timings.record_sample_pts(Some(0.220)); timings.record_sample_pts(Some(0.253)); assert_eq!(timings.snapshot().capture_gap_p95_ms, Some(33.0)); assert_eq!(timings.snapshot().sample_pts_gap_p95_ms, Some(33.0)); } #[tokio::test] async fn camera_registry_preview_consumer_releases_on_stop() { let state = test_state(); let source_key = SourceKey::camera("camera:avfoundation-native:test"); { let mut slot = state.preview_camera.lock().await; slot.source_key = Some(source_key.clone()); } acquire_preview_camera_source(&state, source_key.clone(), SourceLifecycleStatus::Live) .await; let keep_alive = release_current_preview_camera_source(&state).await; let snapshot = state.source_registry.lock().await.snapshot(); let entry = snapshot .entries .iter() .find(|entry| entry.key == source_key) .expect("camera source entry"); assert!(!keep_alive); assert!(entry.consumers.is_empty()); assert_eq!(entry.status, SourceLifecycleStatus::Stopped); } #[tokio::test] async fn camera_start_cannot_install_after_screen_only_retirement() { let state = test_state(); let video = test_video(); let layout = test_layout(false); let source_key = SourceKey::camera("camera:avfoundation-native:test"); let start_key = PreviewCameraStartKey { source_key: source_key.clone(), ffmpeg_path: "ffmpeg".to_string(), video: video.clone(), target_fps: video.fps, capture_target: camera_capture_target_dimensions(&layout, &video), }; let starting = PreviewCameraStatus { state: PreviewCameraState::Starting, camera_id: Some(source_key.id.clone()), device_unique_id: Some("test".to_string()), target_fps: video.fps, width: None, height: None, requested_width: None, requested_height: None, actual_width: None, actual_height: None, selected_format_width: None, selected_format_height: None, selected_format_min_fps: None, selected_format_max_fps: None, source_fps: None, frame_age_ms: None, frames_captured: 0, dropped_frames: 0, sequence: None, updated_at: Utc::now().to_rfc3339(), message: Some("Starting native camera preview.".to_string()), no_video: None, system_effect: None, }; let lease = match begin_camera_start(&state, start_key, &layout, starting, None).await { PreviewCameraStartRegistration::Started { lease } => lease, PreviewCameraStartRegistration::JoinExisting { .. } => { panic!("first start must own a lease") } PreviewCameraStartRegistration::Reused(_) => panic!("first start cannot reuse"), PreviewCameraStartRegistration::RejectedSuperseded(_) | PreviewCameraStartRegistration::RejectedShutdown(_) => { panic!("test process is not shutting down") } }; // Screen-only retires camera capture while the old native startup thread // is still discovering/starting its device. let stopped = stop_preview_camera(&state).await; assert_eq!(stopped.state, PreviewCameraState::DeviceMissing); let stale_start_claimed = { let mut slot = state.preview_camera.lock().await; claim_camera_start(&mut slot, &lease) }; assert!(!stale_start_claimed); assert_eq!( preview_camera_status(&state).await.state, PreviewCameraState::DeviceMissing ); } #[tokio::test] async fn layout_only_reuse_updates_camera_layout_without_new_run() { let state = test_state(); let source_key = SourceKey::camera("camera:avfoundation-native:test"); let (stop_tx, _stop_rx) = std_mpsc::channel(); let video = test_video(); { let mut slot = state.preview_camera.lock().await; slot.source_key = Some(source_key.clone()); slot.run_id = Some("run-1".to_string()); slot.status = PreviewCameraStatus { state: PreviewCameraState::Live, camera_id: Some(source_key.id.clone()), device_unique_id: Some("test".to_string()), target_fps: video.fps, width: Some(video.width), height: Some(video.height), requested_width: Some(video.width), requested_height: Some(video.height), actual_width: Some(video.width), actual_height: Some(video.height), selected_format_width: Some(video.width), selected_format_height: Some(video.height), selected_format_min_fps: Some(1.0), selected_format_max_fps: Some(f64::from(video.fps)), source_fps: Some(f64::from(video.fps)), frame_age_ms: Some(5), frames_captured: 42, dropped_frames: 0, sequence: Some(42), updated_at: Utc::now().to_rfc3339(), message: Some("Live".to_string()), no_video: None, system_effect: None, }; slot.start_generation = 1; slot.active_generation = Some(1); slot.active = Some(NativeCameraPreviewThread { stop_tx, join_handle: None, shared: Arc::new(StdMutex::new(PreviewCameraShared::default())), camera_id: source_key.id.clone(), device_unique_id: "test".to_string(), ffmpeg_path: "ffmpeg".to_string(), layout: test_layout(false), video: video.clone(), effective_fps: video.fps, configured_output: (video.width, video.height), capture_target: camera_capture_target_dimensions(&test_layout(false), &video), }); } assert!( reuse_current_camera_source( &state, &source_key, "/custom/ffmpeg", &test_layout(true), &video, video.fps ) .await .is_none() ); let status = reuse_current_camera_source( &state, &source_key, "ffmpeg", &test_layout(true), &video, video.fps, ) .await .expect("camera source should be reused"); let slot = state.preview_camera.lock().await; assert_eq!(status.sequence, Some(42)); assert_eq!(slot.run_id.as_deref(), Some("run-1")); assert!( slot.active .as_ref() .expect("active camera") .layout .camera_mirror ); assert_eq!( status.message.as_deref(), Some("Native camera preview source reused.") ); } #[tokio::test] async fn reuse_refuses_a_session_with_stale_capture_geometry() { // Capture geometry is layout-invariant, so only a genuine output // canvas change (video preset/orientation) can make it stale. A // session capturing the old canvas keeps delivering frames sized for // it, so reuse must force a restart instead of adopting them. let state = test_state(); let video = test_video(); let mut larger_canvas = test_video(); larger_canvas.preset = VideoPreset::Tutorial1440p30; larger_canvas.width = 2560; larger_canvas.height = 1440; let source_key = SourceKey::camera("camera:avfoundation-native:test"); let full_canvas_layout = test_layout(false); let inset_layout = { let mut layout = test_layout(false); layout.layout_preset = LayoutPreset::ScreenCamera; layout }; assert_eq!( camera_capture_target_dimensions(&full_canvas_layout, &video), camera_capture_target_dimensions(&inset_layout, &video), "presets must share ONE capture box — a preset switch never restarts the camera" ); assert_ne!( camera_capture_target_dimensions(&full_canvas_layout, &video), camera_capture_target_dimensions(&full_canvas_layout, &larger_canvas), "an output canvas change must derive a different capture box for this test" ); let (stop_tx, _stop_rx) = std_mpsc::channel(); { let mut slot = state.preview_camera.lock().await; slot.source_key = Some(source_key.clone()); slot.status.state = PreviewCameraState::Live; slot.status.target_fps = video.fps; slot.start_generation = 1; slot.active_generation = Some(1); slot.active = Some(NativeCameraPreviewThread { stop_tx, join_handle: None, shared: Arc::new(StdMutex::new(PreviewCameraShared::default())), camera_id: source_key.id.clone(), device_unique_id: "test".to_string(), ffmpeg_path: "ffmpeg".to_string(), layout: inset_layout.clone(), video: video.clone(), effective_fps: video.fps, configured_output: (video.width, video.height), capture_target: camera_capture_target_dimensions(&inset_layout, &video), }); } assert!( reuse_current_camera_source( &state, &source_key, "ffmpeg", &full_canvas_layout, &larger_canvas, larger_canvas.fps ) .await .is_none(), "a capture-geometry mismatch must not be reused" ); assert!( camera_capture_geometry_is_stale(&state, &full_canvas_layout, &larger_canvas).await, "the staleness probe must agree with reuse" ); assert!( !camera_capture_geometry_is_stale(&state, &full_canvas_layout, &video).await, "the same canvas must not report stale — regardless of preset" ); assert!( !camera_capture_geometry_is_stale(&state, &inset_layout, &video).await, "a preset switch alone must NEVER report stale" ); } #[tokio::test] async fn frameless_live_slot_past_grace_is_a_zombie() { // The Cam Link failure shape: Live acked, zero frames ever, grace long // gone. The next same-key start must tear down and truly restart. let state = test_state(); { let mut slot = state.preview_camera.lock().await; slot.status.state = PreviewCameraState::Live; slot.status.camera_id = Some("camera:test".to_string()); slot.status.frames_captured = 0; slot.status.sequence = None; slot.source_key = Some(SourceKey::camera("camera:test".to_string())); slot.live_acked_at = Some(Instant::now() - CAMERA_FIRST_FRAME_REUSE_GRACE - Duration::from_millis(1)); } assert!(camera_live_session_is_frameless_zombie(&state).await); } #[tokio::test] async fn frameless_live_slot_past_grace_reports_no_video() { // Plan 216 D2: the streamer's bundle shape. Live, zero callbacks, // nothing in the frame store, the grace gone: the status says so. let state = test_state(); let mut slot = state.preview_camera.lock().await; slot.status.state = PreviewCameraState::Live; slot.status.frames_captured = 0; slot.status.sequence = None; slot.live_acked_at = Some(Instant::now() - CAMERA_FIRST_FRAME_REUSE_GRACE - Duration::from_millis(1)); refresh_camera_no_video(&mut slot); assert_eq!(slot.status.no_video, Some(true)); let json = serde_json::to_value(&slot.status).unwrap(); assert_eq!(json["noVideo"], serde_json::json!(true)); // The first frame clears it on the next tick. slot.status.frames_captured = 1; refresh_camera_no_video(&mut slot); assert_eq!(slot.status.no_video, None); let json = serde_json::to_value(&slot.status).unwrap(); assert!(json.get("noVideo").is_none()); } #[tokio::test] async fn frameless_live_slot_within_grace_reports_video_pending() { // Starting up is not "no video": macOS acks Live before any frame. let state = test_state(); let mut slot = state.preview_camera.lock().await; slot.status.state = PreviewCameraState::Live; slot.status.no_video = Some(true); slot.live_acked_at = Some(Instant::now()); refresh_camera_no_video(&mut slot); assert_eq!(slot.status.no_video, None); } #[tokio::test] async fn frameless_recovery_eligibility_is_live_generation_exact() { let state = test_state(); let layout = crate::protocol::default_layout_settings(); let video = test_video(); test_install_live_camera_for_layout(&state, "camera:test", &layout, &video).await; { let mut slot = state.preview_camera.lock().await; slot.status.frames_captured = 0; slot.status.sequence = None; slot.status.actual_width = None; slot.status.actual_height = None; slot.live_acked_at = Some(Instant::now()); slot.active.as_mut().unwrap().shared = Arc::new(StdMutex::new(PreviewCameraShared::default())); } let snapshot = preview_camera_restart_snapshot(&state) .await .expect("stable frameless Live generation"); assert!( !preview_camera_restart_snapshot_is_frameless_zombie(&state, &snapshot).await, "the exact Live generation remains protected during first-frame warm-up" ); { let mut slot = state.preview_camera.lock().await; slot.live_acked_at = Some(Instant::now() - CAMERA_FIRST_FRAME_REUSE_GRACE - Duration::from_millis(1)); } assert!( preview_camera_restart_snapshot_is_frameless_zombie(&state, &snapshot).await, "the exact generation becomes recovery-eligible after the shared grace" ); let mut stale = snapshot; stale.generation = stale.generation.wrapping_add(1); assert!( !preview_camera_restart_snapshot_is_frameless_zombie(&state, &stale).await, "a retired/source-switch generation cannot authorize recovery" ); } #[tokio::test] async fn forced_recovery_registers_source_transition_before_native_completion() { let state = test_state(); let layout = test_layout(false); let video = test_video(); install_restartable_camera(&state, 41, &layout, &video).await; let expected = preview_camera_restart_snapshot(&state) .await .expect("live restart snapshot"); let recovery_epoch = 303; state.set_capture_recovery_admission_epoch(recovery_epoch); let transition_gate = Arc::clone(&state.preview_camera.lock().await.transition_gate); let held_native_transition = transition_gate.lock_owned().await; let prior_sequence = state.source_transition_fence.accepted_sequence(); let attempt = admit_force_restart_preview_camera(&state, &expected, recovery_epoch) .await .expect("exact recovery admission"); assert_eq!( state.source_transition_fence.accepted_sequence(), prior_sequence + 1, "admission must publish transition ownership before returning" ); let transition = state.source_transition_fence.observe(); assert!( tokio::time::timeout(Duration::from_millis(20), transition.wait()) .await .is_err(), "native completion is still blocked behind the physical transition gate" ); state.request_process_shutdown(); drop(held_native_transition); let _ = tokio::time::timeout( Duration::from_secs(1), complete_force_restart_preview_camera(&state, attempt), ) .await .expect("shutdown-latched recovery supervisor must retire"); tokio::time::timeout(Duration::from_secs(1), transition.wait()) .await .expect("source-transition guard must release after retirement"); } #[tokio::test] async fn frameless_live_slot_within_grace_is_not_a_zombie() { // A camera that acked Live a moment ago is still warming up; the // readiness wait owns that window, not a forced restart. let state = test_state(); { let mut slot = state.preview_camera.lock().await; slot.status.state = PreviewCameraState::Live; slot.status.frames_captured = 0; slot.status.sequence = None; slot.live_acked_at = Some(Instant::now()); } assert!(!camera_live_session_is_frameless_zombie(&state).await); } #[tokio::test] async fn frameless_live_slot_inside_the_warm_start_budget_is_not_a_zombie() { // The 0.9.51 Cam Link retry storm: a slow external device 10s into its // warm-up (past the old 4s grace) was torn down by every retry, so its // first frame could never arrive. A retry must JOIN this warm-up. let state = test_state(); { let mut slot = state.preview_camera.lock().await; slot.status.state = PreviewCameraState::Live; slot.status.camera_id = Some("camera:test".to_string()); slot.status.frames_captured = 0; slot.status.sequence = None; slot.source_key = Some(SourceKey::camera("camera:test".to_string())); slot.live_acked_at = Some(Instant::now() - Duration::from_secs(10)); } assert!(!camera_live_session_is_frameless_zombie(&state).await); } #[tokio::test] async fn live_slot_with_frame_evidence_is_never_a_zombie() { let state = test_state(); { let mut slot = state.preview_camera.lock().await; slot.status.state = PreviewCameraState::Live; slot.status.frames_captured = 42; slot.live_acked_at = Some(Instant::now() - CAMERA_FIRST_FRAME_REUSE_GRACE - Duration::from_secs(60)); } assert!(!camera_live_session_is_frameless_zombie(&state).await); } #[tokio::test] async fn non_live_slot_is_not_a_zombie() { // Starting/Failed/DeviceMissing states have their own handling; the // zombie teardown must never fire for them. let state = test_state(); { let mut slot = state.preview_camera.lock().await; slot.status.state = PreviewCameraState::Starting; slot.live_acked_at = Some(Instant::now() - CAMERA_FIRST_FRAME_REUSE_GRACE - Duration::from_secs(60)); } assert!(!camera_live_session_is_frameless_zombie(&state).await); } #[tokio::test] async fn frameless_live_slot_with_no_ack_timestamp_is_a_zombie() { // A Live status with no recorded ack time (state restored oddly, or a // pre-fix session) has no claim to the warmup grace. let state = test_state(); { let mut slot = state.preview_camera.lock().await; slot.status.state = PreviewCameraState::Live; slot.status.frames_captured = 0; slot.live_acked_at = None; } assert!(camera_live_session_is_frameless_zombie(&state).await); } }