Skip to content

fix: report why macOS system audio capture stopped - #590

Merged
devopvoid merged 1 commit into
mainfrom
fix/macos-system-audio-stop-reason
Nov 11, 2026
Merged

devopvoid merged 1 commit into
mainfrom
fix/macos-system-audio-stop-reason

Conversation

@devopvoid

Copy link
Copy Markdown
Owner

A stopped ScreenCaptureKit stream always failed with a hint to check the recording permission, even when the user ended the capture from the menu bar or the display went away. SystemAudioSource.getFailure() now names the actual cause:

  • SCStreamErrorUserStopped: "stopped by the user", without the permission hint
  • SCStreamErrorUserDeclined: asks to grant screen/audio recording permission
  • anything else: the system's error code and description

Capture timestamps are now translated from the stream's synchronizationClock, as ScreenCaptureKit documents, falling back to the host clock when the stream reports none. Both APIs are available from macOS 13, the existing minimum for system audio.

Testing

On macOS 14.5 (arm64), with the native library rebuilt:

  • SystemAudioSourceTest: 7/7 pass
  • SystemAudioSourceIntegrationTest (-Dtest.systemAudio=true, audio playing on the default output): passes, including the restart

The new stop messages need a manual stop from the menu bar and were not triggered by a test. macOS 13, macOS 15 and x86_64 were not tested.

A stopped ScreenCaptureKit stream always failed with a hint to check the
recording permission, even when the user ended the capture from the menu
bar or the display went away. The failure now names the actual cause:
stopped by the user, permission declined, or the system's error code and
description.

Capture timestamps are translated from the stream's synchronization
clock, as ScreenCaptureKit documents, falling back to the host clock when
the stream reports none.
@devopvoid
devopvoid merged commit 96e4ea1 into main Nov 11, 2026
24 checks passed
@devopvoid
devopvoid deleted the fix/macos-system-audio-stop-reason branch November 11, 2026 23:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant