Skip to content

YC (S26) | Open Computer History | Continuously record your company computer work, map your workflows, help you find work worth automating, and power your agents' context

[codex] release macOS audio streams while locked (#5288)

Louis Beaumonta6689be2a96e
diff --git a/crates/screenpipe-audio/src/audio_manager/device_monitor.rs b/crates/screenpipe-audio/src/audio_manager/device_monitor.rs
index 77d26fc63..f8468d91b 100644
--- a/crates/screenpipe-audio/src/audio_manager/device_monitor.rs
+++ b/crates/screenpipe-audio/src/audio_manager/device_monitor.rs
@@ -90,6 +90,46 @@ fn is_session_type_streaming(
use super::{AudioManager, AudioManagerStatus};
+#[cfg(any(target_os = "macos", test))]
+#[derive(Debug, Default, PartialEq, Eq)]
+struct ScreenLockAudioGate {
+ suspended: bool,
+}
+
+#[cfg(any(target_os = "macos", test))]
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum ScreenLockAudioAction {
+ None,
+ Suspend,
+ EnforceSuspended,
+ Resume,
+}
+
+#[cfg(any(target_os = "macos", test))]
+impl ScreenLockAudioAction {
+ fn enforces_stream_shutdown(self) -> bool {
+ matches!(self, Self::Suspend | Self::EnforceSuspended)
+ }
+}
+
+#[cfg(any(target_os = "macos", test))]
+impl ScreenLockAudioGate {
+ fn update(&mut self, should_suspend: bool) -> ScreenLockAudioAction {
+ match (self.suspended, should_suspend) {
+ (false, true) => {
+ self.suspended = true;
+ ScreenLockAudioAction::Suspend
+ }
+ (true, false) => {
+ self.suspended = false;
+ ScreenLockAudioAction::Resume
+ }
+ (true, true) => ScreenLockAudioAction::EnforceSuspended,
+ (false, false) => ScreenLockAudioAction::None,
+ }
+ }
+}
+
/// Exponential backoff for device recovery.
///
/// Transient errors (e.g., ScreenCaptureKit not yet initialized) use a short
@@ -585,6 +625,15 @@ pub async fn start_device_monitor(
// the stable path on any gap. Pure decider in `meeting_piggyback.rs`.
let mut piggyback_state = super::meeting_piggyback::PiggybackState::default();
+ // macOS CoreAudio keeps a PreventUserIdleSystemSleep assertion for as
+ // long as an input/output stream remains open. Merely skipping samples
+ // while the display is locked leaves that assertion alive and prevents
+ // the machine from completing idle sleep. Track the lock edge so every
+ // stream is torn down exactly once, then enrolled for normal reconnect
+ // after unlock.
+ #[cfg(target_os = "macos")]
+ let mut screen_lock_audio_gate = ScreenLockAudioGate::default();
+
// Initialize tracker with current defaults
let _ = default_tracker.check_input_changed();
let _ = default_tracker.check_output_changed().await;
@@ -605,6 +654,115 @@ pub async fn start_device_monitor(
loop {
if audio_manager.status().await == AudioManagerStatus::Running {
+ #[cfg(target_os = "macos")]
+ {
+ let should_suspend = screenpipe_config::should_pause_audio_for_lock();
+ let lock_action = screen_lock_audio_gate.update(should_suspend);
+ match lock_action {
+ ScreenLockAudioAction::Suspend => {
+ // Piggyback may have suspended the stable mic/output
+ // while session streams were active. Lift those
+ // guards without restarting yet; the screen-lock
+ // gate below keeps every start path closed.
+ for device_name in audio_manager.suspended_devices() {
+ audio_manager.unsuspend_device(&device_name);
+ }
+ piggyback_state = super::meeting_piggyback::PiggybackState::default();
+ }
+ ScreenLockAudioAction::EnforceSuspended => {}
+ ScreenLockAudioAction::Resume => {
+ let enabled_devices = audio_manager.enabled_devices().await;
+ for device_name in enabled_devices {
+ disconnected_devices.insert(device_name.clone());
+ disconnected_device_backoffs.remove(&device_name);
+ }
+ info!("screen unlocked: scheduling audio stream recovery");
+ }
+ ScreenLockAudioAction::None => {}
+ }
+
+ if lock_action.enforces_stream_shutdown() {
+ // Enforce the invariant on every locked tick, not only
+ // on the edge. This closes two races: a stream whose
+ // start was already in flight when the lock flag
+ // changed, and a transient CoreAudio stop failure.
+ let session_devices = audio_manager.session_devices();
+ let mut observed_device_names = session_devices.clone();
+ for device_name in &session_devices {
+ match parse_audio_device(device_name) {
+ Ok(device) => {
+ if let Err(e) =
+ audio_manager.stop_session_device(&device).await
+ {
+ warn!(
+ "failed to stop meeting-session audio device {} for screen lock: {}",
+ device, e
+ );
+ }
+ }
+ Err(e) => warn!(
+ "failed to parse meeting-session audio device '{}' during screen-lock cleanup: {}",
+ device_name, e
+ ),
+ }
+ }
+
+ // Snapshot again after session teardown so a session
+ // stream is not normally stopped twice. If its first
+ // stop failed, it remains here and gets an immediate
+ // retry through the generic path.
+ let current_devices = audio_manager.current_devices();
+ observed_device_names
+ .extend(current_devices.iter().map(std::string::ToString::to_string));
+ for device in &current_devices {
+ if let Err(e) = audio_manager.stop_device_recording(device).await {
+ warn!(
+ "failed to stop audio device {} for screen lock: {}",
+ device, e
+ );
+ }
+ }
+
+ let mut remaining_device_names = audio_manager.session_devices();
+ remaining_device_names.extend(
+ audio_manager
+ .current_devices()
+ .iter()
+ .map(std::string::ToString::to_string),
+ );
+ let released_streams = observed_device_names
+ .len()
+ .saturating_sub(remaining_device_names.len());
+ if lock_action == ScreenLockAudioAction::Suspend {
+ if remaining_device_names.is_empty() {
+ info!(
+ "screen locked: released {} audio stream(s) so macOS can idle sleep",
+ released_streams
+ );
+ } else {
+ warn!(
+ "screen locked: released {} of {} audio stream(s); {} remain and will be retried",
+ released_streams,
+ observed_device_names.len(),
+ remaining_device_names.len()
+ );
+ }
+ } else if !observed_device_names.is_empty() {
+ debug!(
+ "screen-lock cleanup found {} late or retrying audio stream(s); {} remain",
+ observed_device_names.len(),
+ remaining_device_names.len()
+ );
+ }
+
+ tokio::select! {
+ _ = sleep(Duration::from_secs(1)) => {}
+ _ = super::piggyback_listeners::sweep_wake_notified() => {}
+ }
+ continue;
+ }
+ }
+
// Check if sleep/wake or display reconfiguration requested
// audio stream invalidation. Force-cycle all running devices
// to recover from silent CoreAudio stream failures.
@@ -2168,6 +2326,66 @@ impl RestartCooldown {
mod tests {
use super::*;
+ #[test]
+ fn screen_lock_audio_gate_tears_down_and_resumes_once_per_edge() {
+ let mut gate = ScreenLockAudioGate::default();
+
+ assert_eq!(gate.update(false), ScreenLockAudioAction::None);
+ assert_eq!(gate.update(true), ScreenLockAudioAction::Suspend);
+ assert_eq!(gate.update(true), ScreenLockAudioAction::EnforceSuspended);
+ assert_eq!(gate.update(false), ScreenLockAudioAction::Resume);
+ assert_eq!(gate.update(false), ScreenLockAudioAction::None);
+ }
+
+ #[test]
+ fn screen_lock_audio_gate_enforces_shutdown_for_every_locked_tick() {
+ let mut gate = ScreenLockAudioGate::default();
+
+ for expected in [
+ ScreenLockAudioAction::Suspend,
+ ScreenLockAudioAction::EnforceSuspended,
+ ScreenLockAudioAction::EnforceSuspended,
+ ] {
+ let action = gate.update(true);
+ assert_eq!(action, expected);
+ assert!(action.enforces_stream_shutdown());
+ }
+
+ assert_eq!(gate.update(false), ScreenLockAudioAction::Resume);
+ assert!(!ScreenLockAudioAction::Resume.enforces_stream_shutdown());
+ assert!(!ScreenLockAudioAction::None.enforces_stream_shutdown());
+ }
+
+ #[test]
+ fn screen_lock_audio_gate_matches_all_short_lock_sequences() {
+ // Exhaust every lock/unlock sequence up to eight monitor ticks. This
+ // covers rapid flapping, repeated locks, and preference toggles while
+ // the display remains locked (the input is the effective pause flag).
+ for mask in 0u16..=u8::MAX as u16 {
+ let mut gate = ScreenLockAudioGate::default();
+ let mut previously_locked = false;
+
+ for tick in 0..8 {
+ let locked = mask & (1 << tick) != 0;
+ let expected = match (previously_locked, locked) {
+ (false, false) => ScreenLockAudioAction::None,
+ (false, true) => ScreenLockAudioAction::Suspend,
+ (true, true) => ScreenLockAudioAction::EnforceSuspended,
+ (true, false) => ScreenLockAudioAction::Resume,
+ };
+ let action = gate.update(locked);
+
+ assert_eq!(action, expected, "mask={mask:08b}, tick={tick}");
+ assert_eq!(
+ action.enforces_stream_shutdown(),
+ locked,
+ "mask={mask:08b}, tick={tick}"
+ );
+ previously_locked = locked;
+ }
+ }
+ }
+
lazy_static::lazy_static! {
/// Default for builders that don't exercise the fail-over-to-any-available
/// path (most fallback tests only care about the system-default target).
diff --git a/crates/screenpipe-audio/src/audio_manager/manager.rs b/crates/screenpipe-audio/src/audio_manager/manager.rs
index b51eeb1e7..473585675 100644
--- a/crates/screenpipe-audio/src/audio_manager/manager.rs
+++ b/crates/screenpipe-audio/src/audio_manager/manager.rs
@@ -779,6 +779,15 @@ impl AudioManager {
return Ok(());
}
+ #[cfg(target_os = "macos")]
+ if screenpipe_config::should_pause_audio_for_lock() {
+ debug!(
+ "skipping start of audio device while screen is locked: {}",
+ device
+ );
+ return Ok(());
+ }
+
// Don't restart devices that are paused due to DRM content detection.
// The monitor watcher will call start_output_devices() when DRM clears.
if self
@@ -840,6 +849,19 @@ impl AudioManager {
}
}
+ // The lock flag can change while CoreAudio is opening the stream. The
+ // pre-start guard above cannot close that race, and the device monitor
+ // cannot see this stream until its recording handle is registered.
+ #[cfg(target_os = "macos")]
+ if screenpipe_config::should_pause_audio_for_lock() {
+ self.stop_device_recording(device).await?;
+ debug!(
+ "stopped newly-opened audio device after screen locked during startup: {}",
+ device
+ );
+ return Ok(());
+ }
+
if !self.recording_handles.contains_key(device) {
if let Some(is_running) = self.device_manager.is_running_mut(device) {
is_running.store(true, Ordering::Relaxed);
@@ -872,6 +894,14 @@ impl AudioManager {
if self.options.read().await.is_disabled {
return Ok(());
}
+ #[cfg(target_os = "macos")]
+ if screenpipe_config::should_pause_audio_for_lock() {
+ debug!(
+ "skipping start of meeting-session audio device while screen is locked: {}",
+ device
+ );
+ return Ok(());
+ }
// Insert BEFORE starting: the audio-receiver drop-gate bypass must see
// this device from the very first chunk. Rolled back on failure below.
self.session_devices
@@ -896,6 +926,23 @@ impl AudioManager {
return Err(e);
}
}
+
+ // As above, close a stream that finished opening after the screen-lock
+ // gate was checked. Remove session bookkeeping before the generic stop.
+ #[cfg(target_os = "macos")]
+ if screenpipe_config::should_pause_audio_for_lock() {
+ self.session_devices
+ .write()
+ .unwrap()
+ .remove(&device.to_string());
+ self.stop_device_recording(device).await?;
+ debug!(
+ "stopped newly-opened meeting-session audio device after screen locked during startup: {}",
+ device
+ );
+ return Ok(());
+ }
+
if !self.recording_handles.contains_key(device) {
if let Some(is_running) = self.device_manager.is_running_mut(device) {
is_running.store(true, Ordering::Relaxed);
diff --git a/crates/screenpipe-config/src/screen_lock.rs b/crates/screenpipe-config/src/screen_lock.rs
index b9c2a14db..79f71efc1 100644
--- a/crates/screenpipe-config/src/screen_lock.rs
+++ b/crates/screenpipe-config/src/screen_lock.rs
@@ -45,3 +45,41 @@ pub fn set_record_while_locked(enabled: bool) {
pub fn should_pause_audio_for_lock() -> bool {
screen_is_locked() && !record_while_locked()
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::sync::Mutex;
+
+ static SCREEN_LOCK_TEST: Mutex<()> = Mutex::new(());
+
+ struct ResetScreenLockState;
+
+ impl Drop for ResetScreenLockState {
+ fn drop(&mut self) {
+ set_screen_locked(false);
+ set_record_while_locked(false);
+ }
+ }
+
+ #[test]
+ fn pause_policy_covers_lock_and_record_while_locked_combinations() {
+ let _guard = SCREEN_LOCK_TEST.lock().unwrap();
+ let _reset = ResetScreenLockState;
+
+ for (locked, record_locked, expected_pause) in [
+ (false, false, false),
+ (false, true, false),
+ (true, false, true),
+ (true, true, false),
+ ] {
+ set_screen_locked(locked);
+ set_record_while_locked(record_locked);
+ assert_eq!(
+ should_pause_audio_for_lock(),
+ expected_pause,
+ "locked={locked}, record_while_locked={record_locked}"
+ );
+ }
+ }
+}
diff --git a/crates/screenpipe-engine/src/routes/health.rs b/crates/screenpipe-engine/src/routes/health.rs
index 73df3e2a7..3c484bc78 100644
--- a/crates/screenpipe-engine/src/routes/health.rs
+++ b/crates/screenpipe-engine/src/routes/health.rs
@@ -128,6 +128,7 @@ const STREAM_TIMEOUT_RECENCY_SECS: u64 = 90;
#[allow(clippy::too_many_arguments)]
fn classify_audio_status(
audio_disabled: bool,
+ audio_paused_for_screen_lock: bool,
audio_never_captured: bool,
has_input_device: bool,
stream_timeout_recent: bool,
@@ -138,6 +139,12 @@ fn classify_audio_status(
) -> &'static str {
if audio_disabled {
"disabled"
+ } else if audio_paused_for_screen_lock {
+ // The audio manager deliberately owns no streams in this state so
+ // CoreAudio cannot keep macOS awake. Treat it like vision's existing
+ // screen-lock exemption, not as a stalled recorder. Keep the stable
+ // top-level status contract; capture_status carries the specific state.
+ "ok"
} else if audio_never_captured && !has_input_device {
// Audio is on but there is no microphone to capture from — expected
// idle, not a failure. Distinct from "not_started" so /health stays 200
@@ -161,8 +168,10 @@ fn classify_audio_status(
}
}
+#[allow(clippy::too_many_arguments)]
fn capture_status(
audio_disabled: bool,
+ audio_paused_for_screen_lock: bool,
audio_status: &str,
active_audio_devices: usize,
active_input_devices: usize,
@@ -182,6 +191,12 @@ fn capture_status(
"warning",
"audio capture is disabled for this recorder",
)
+ } else if audio_paused_for_screen_lock {
+ (
+ "screen_locked",
+ "waiting",
+ "audio capture is paused while the screen is locked",
+ )
} else if paused_input_devices > 0 && active_input_devices == 0 {
(
"mic_paused",
@@ -982,8 +997,15 @@ async fn health_check_inner(state: &Arc<AppState>) -> HealthCheckResponse {
let stream_timeout_recent = audio_snap.last_stream_timeout_at > 0
&& now_ts.saturating_sub(audio_snap.last_stream_timeout_at) < STREAM_TIMEOUT_RECENCY_SECS;
+ // Only report the intentional pause after the manager has actually
+ // released every stream. During the short teardown transition (or if a
+ // stop unexpectedly fails), health must not claim capture is suspended.
+ let audio_paused_for_screen_lock =
+ screenpipe_config::should_pause_audio_for_lock() && audio_devices.is_empty();
+
let audio_status = classify_audio_status(
state.audio_disabled,
+ audio_paused_for_screen_lock,
audio_never_captured,
has_input_device,
stream_timeout_recent,
@@ -1014,6 +1036,7 @@ async fn health_check_inner(state: &Arc<AppState>) -> HealthCheckResponse {
.count();
let capture_status = capture_status(
state.audio_disabled,
+ audio_paused_for_screen_lock,
&audio_status,
active_audio_devices,
active_input_devices,
@@ -1608,6 +1631,7 @@ mod tests {
#[test]
fn capture_status_does_not_show_stalled_for_recovered_active_no_data() {
let state = capture_status(
+ false,
false,
"active_no_data",
1,
@@ -1629,6 +1653,7 @@ mod tests {
#[test]
fn capture_status_still_warns_for_active_no_data_without_fresh_audio() {
let state = capture_status(
+ false,
false,
"active_no_data",
1,
@@ -1647,6 +1672,20 @@ mod tests {
assert_eq!(state.severity, "warning");
}
+ #[test]
+ fn capture_status_reports_intentional_screen_lock_pause() {
+ let state = capture_status(
+ false, true, "ok", 0, 0, 0, 0, false, None, 0.0, 0, 0, 10_000,
+ );
+
+ assert_eq!(state.status, "screen_locked");
+ assert_eq!(state.severity, "waiting");
+ assert_eq!(
+ state.reason,
+ "audio capture is paused while the screen is locked"
+ );
+ }
+
#[tokio::test]
async fn health_cache_fresh_then_stale() {
let now = std::time::SystemTime::now()
@@ -1834,6 +1873,7 @@ mod tests {
fn audio_status_for(stream_timeout_recent: bool, global_audio_active: bool) -> &'static str {
classify_audio_status(
false, // audio_disabled
+ false, // audio_paused_for_screen_lock
false, // audio_never_captured
true, // has_input_device
stream_timeout_recent,
@@ -1891,27 +1931,32 @@ mod tests {
fn audio_status_non_timeout_branches_unchanged() {
// Guard the unrelated branches against accidental regressions.
assert_eq!(
- classify_audio_status(true, false, true, true, true, 1000, 1010, 60),
+ classify_audio_status(true, true, false, true, true, true, 1000, 1010, 60),
"disabled"
);
+ // intentional lock pause wins over stale/not-started signals
+ assert_eq!(
+ classify_audio_status(false, true, true, true, false, false, 0, 1010, 60),
+ "ok"
+ );
// never captured + no mic -> benign no_input_device (stays 200)
assert_eq!(
- classify_audio_status(false, true, false, false, false, 0, 1010, 60),
+ classify_audio_status(false, false, true, false, false, false, 0, 1010, 60),
"no_input_device"
);
// never captured but a mic exists -> not_started
assert_eq!(
- classify_audio_status(false, true, true, false, false, 0, 1010, 60),
+ classify_audio_status(false, false, true, true, false, false, 0, 1010, 60),
"not_started"
);
// not active, last audio within threshold -> ok
assert_eq!(
- classify_audio_status(false, false, true, false, false, 1000, 1030, 60),
+ classify_audio_status(false, false, false, true, false, false, 1000, 1030, 60),
"ok"
);
// not active, last audio stale -> stale
assert_eq!(
- classify_audio_status(false, false, true, false, false, 1000, 2000, 60),
+ classify_audio_status(false, false, false, true, false, false, 1000, 2000, 60),
"stale"
);
}