feat(macos): record system audio from a Core Audio tap with Apple's picker

A take picked in Apple's system picker holds no Screen Recording grant,
and ScreenCaptureKit hands such a capture its system audio as silence
(measured on macOS 26.5). So #737 dropped system audio unless Screen
Recording was granted, which brought back the grant the picker removes.

Picked takes now record system audio from a Core Audio process tap
instead, under its own, narrower 'System Audio Recording Only' grant.
Measured alongside a picker stream on 26.5: real audio, in the same
process, with no relaunch and no Screen Recording grant.

- SystemAudioTap: a global stereo process tap in a private aggregate
  device. Its IO cycles become CMSampleBuffers stamped on the host clock
  (makeAudioSampleBuffer, in OpenScreenCaptureCore with tests), so they
  take the recorder's existing pause/retime path into AudioTrackMixer.
- The tap starts off the take's start path, since the first start blocks
  on macOS' prompt, and stops accepting audio before the writer is
  finalised. Takes from the app's own picker keep ScreenCaptureKit audio.
- `--request-system-audio` raises the prompt on its own. The HUD's
  system-audio toggle calls it the first time it is turned on, so the
  prompt never lands on a take that is already counting down.
- The permissions window gets a real 'System audio' row there. Its
  answer has no public read, so after asking it reads 'requested' and
  offers the matching System Settings pane (Privacy_AudioCapture), with
  the section named as macOS names it in each of the 15 locales.

Author: EtienneLescot

electron/ipc/handlers.ts

@@ -2220,6 +2220,13 @@ export function registerIpcHandlers(
 				selectedSource = null;
 				broadcastSelectedSource(null);
 			}
+			// Turning system audio on is when its grant becomes wanted: ask now, so the prompt
+			// never lands on a take that is already counting down.
+			if (!previous.systemAudioEnabled && next.systemAudioEnabled && macPickerOwnsSources()) {
+				void getMacPermissions()
+					.askForSystemAudioOnce()
+					.catch((error) => console.warn("[permissions] system audio request failed:", error));
+			}
 		},
 	);
 
@@ -2996,18 +3003,12 @@ export function registerIpcHandlers(
 					// The helper reports the final ScreenCaptureKit permission status.
 				}
 			}
-			// System audio is the one thing a pick does not cover: without the Screen Recording
-			// grant ScreenCaptureKit delivers it as silence (measured). Recording silence and
-			// calling it system audio would be worse than saying so, so the take goes ahead
-			// without it and the permissions window explains what would bring it back.
-			let systemAudioUnavailable = false;
+			// A picked take records system audio from a Core Audio tap, under its own "System
+			// Audio Recording Only" grant (see SystemAudioTap.swift). The helper raises that
+			// prompt itself if it was never answered, so note it: the permissions window then
+			// offers System Settings rather than a prompt macOS will not show again.
 			if (pickerSession && request.audio?.system?.enabled) {
-				const permissions = await getMacPermissions().read();
-				if (permissions.screen !== "granted") {
-					systemAudioUnavailable = true;
-					request = { ...request, audio: { ...request.audio, system: { enabled: false } } };
-					showPermissionsWindow();
-				}
+				getMacPermissions().noteRequested("systemAudio");
 			}
 			if (request.audio?.microphone?.enabled) {
 				const micStatus = systemPreferences.getMediaAccessStatus("microphone");
@@ -3136,7 +3137,6 @@ export function registerIpcHandlers(
 				path: outputPath,
 				helperPath,
 				microphoneDefaulted,
-				systemAudioUnavailable,
 			};
 		} catch (error) {
 			console.error("Failed to start native macOS recording:", error);

electron/native/screencapturekit/Sources/OpenScreenCaptureCore/AudioBufferListSampleBuffer.swift

@@ -0,0 +1,66 @@
+import AudioToolbox
+import CoreMedia
+import Foundation
+
+/// Wraps one Core Audio IO cycle as the `CMSampleBuffer` the mixer already reads.
+///
+/// The system-audio tap delivers an `AudioBufferList` and the host time it was captured at.
+/// ScreenCaptureKit's audio output delivered `CMSampleBuffer`s stamped on the host clock.
+/// Stamping the tap's audio on that same clock is what lets it go through the recorder's
+/// existing pause and retime path, and land in `AudioTrackMixer` at the offset it belongs
+/// at, exactly as ScreenCaptureKit's did.
+///
+/// The data is copied: the IO proc's buffers are only valid for the duration of the callback.
+public func makeAudioSampleBuffer(
+	copying bufferList: UnsafePointer<AudioBufferList>,
+	format: CMAudioFormatDescription,
+	hostTime: UInt64
+) -> CMSampleBuffer? {
+	guard let asbd = CMAudioFormatDescriptionGetStreamBasicDescription(format)?.pointee,
+		asbd.mBytesPerFrame > 0,
+		asbd.mSampleRate > 0
+	else {
+		return nil
+	}
+	let buffers = UnsafeMutableAudioBufferListPointer(UnsafeMutablePointer(mutating: bufferList))
+	guard let first = buffers.first, first.mDataByteSize > 0 else {
+		return nil
+	}
+	// Per buffer: one channel for non-interleaved audio, every channel for interleaved.
+	let frameCount = Int(first.mDataByteSize / asbd.mBytesPerFrame)
+	guard frameCount > 0 else {
+		return nil
+	}
+
+	var timing = CMSampleTimingInfo(
+		duration: CMTime(value: 1, timescale: CMTimeScale(asbd.mSampleRate)),
+		presentationTimeStamp: CMClockMakeHostTimeFromSystemUnits(hostTime),
+		decodeTimeStamp: .invalid
+	)
+	var sampleBuffer: CMSampleBuffer?
+	var status = CMSampleBufferCreate(
+		allocator: kCFAllocatorDefault,
+		dataBuffer: nil,
+		dataReady: false,
+		makeDataReadyCallback: nil,
+		refcon: nil,
+		formatDescription: format,
+		sampleCount: frameCount,
+		sampleTimingEntryCount: 1,
+		sampleTimingArray: &timing,
+		sampleSizeEntryCount: 0,
+		sampleSizeArray: nil,
+		sampleBufferOut: &sampleBuffer
+	)
+	guard status == noErr, let sampleBuffer else {
+		return nil
+	}
+	status = CMSampleBufferSetDataBufferFromAudioBufferList(
+		sampleBuffer,
+		blockBufferAllocator: kCFAllocatorDefault,
+		blockBufferMemoryAllocator: kCFAllocatorDefault,
+		flags: 0,
+		bufferList: bufferList
+	)
+	return status == noErr ? sampleBuffer : nil
+}

electron/native/screencapturekit/Sources/OpenScreenScreenCaptureKitHelper/ScreenCaptureRecorder.swift

@@ -159,6 +159,12 @@ final class ScreenCaptureRecorder: NSObject, SCStreamOutput, SCStreamDelegate {
 	private let microphoneOutputTypeRawValue = 2
 	private let hostClock = CMClockGetHostTimeClock()
 	private let picked: PickedSource?
+	/// A `SystemAudioTap` (macOS 14.2+), held untyped so this class keeps its macOS 13 floor.
+	private var systemAudioTap: AnyObject?
+	/// Sample queue only. Cleared before the writer is finalised: a tap stops on its own
+	/// queue, and a buffer it had in flight must not reach a finished writer input.
+	private var acceptsTappedAudio = true
+	private let tapControlQueue = DispatchQueue(label: "app.openscreen.sck-helper.system-audio-control")
 
 	/// `picked` is a choice already made in Apple's system picker (`PickerSession`). The take
 	/// then records exactly that filter: no source lookup, and no Screen Recording check,
@@ -169,6 +175,21 @@ final class ScreenCaptureRecorder: NSObject, SCStreamOutput, SCStreamDelegate {
 		self.picked = picked
 	}
 
+	/// Whether this take's system audio comes from a Core Audio tap instead of ScreenCaptureKit.
+	///
+	/// Only for a source from Apple's picker: that capture holds no Screen Recording grant,
+	/// and ScreenCaptureKit hands a grantless capture its system audio as silence. Every other
+	/// source keeps ScreenCaptureKit's audio, which its grant already covers.
+	private var tapsSystemAudio: Bool {
+		guard picked != nil, request.audio.system.enabled else {
+			return false
+		}
+		if #available(macOS 14.2, *) {
+			return true
+		}
+		return false
+	}
+
 	func start() async throws {
 		try ensureRequestedPermissions(screen: picked == nil)
 
@@ -189,7 +210,7 @@ final class ScreenCaptureRecorder: NSObject, SCStreamOutput, SCStreamDelegate {
 		let stream = SCStream(filter: target.filter, configuration: configuration, delegate: self)
 
 		try stream.addStreamOutput(self, type: .screen, sampleHandlerQueue: sampleQueue)
-		if request.audio.system.enabled {
+		if request.audio.system.enabled && !tapsSystemAudio {
 			try stream.addStreamOutput(self, type: .audio, sampleHandlerQueue: sampleQueue)
 		}
 		if nativeMicrophoneEnabled {
@@ -201,6 +222,7 @@ final class ScreenCaptureRecorder: NSObject, SCStreamOutput, SCStreamDelegate {
 			try stream.addStreamOutput(self, type: microphoneOutputType, sampleHandlerQueue: sampleQueue)
 		}
 		try setupWriter()
+		startSystemAudioTapIfNeeded()
 
 		self.stream = stream
 		emit([
@@ -238,10 +260,75 @@ final class ScreenCaptureRecorder: NSObject, SCStreamOutput, SCStreamDelegate {
 				"message": "\(error)",
 			])
 		}
+		stopSystemAudioTap()
 
 		await finishWriter()
 	}
 
+	private func startSystemAudioTapIfNeeded() {
+		guard tapsSystemAudio, #available(macOS 14.2, *) else {
+			return
+		}
+		let tap = SystemAudioTap { [weak self] sampleBuffer in
+			guard let self else {
+				return
+			}
+			self.sampleQueue.async {
+				self.ingestTappedSystemAudio(sampleBuffer)
+			}
+		}
+		systemAudioTap = tap
+		// Off the start path: the first time, starting a tap blocks until the user answers
+		// macOS' prompt, and the app gives a take only seconds to report it has started.
+		// Audio that arrives late lands where it belongs, with silence in front of it.
+		tapControlQueue.async {
+			do {
+				try tap.start()
+			} catch {
+				emit([
+					"event": "warning",
+					"code": "system-audio-unavailable",
+					"message": "System audio could not be captured: \(error)",
+				])
+			}
+		}
+	}
+
+	/// Queued behind the start rather than run beside it: a tap stopped while its start is
+	/// still inside AudioDeviceStart is torn down under its own feet. Not awaited, so a
+	/// prompt left unanswered cannot hold the recording's stop hostage; what the tap still
+	/// delivers is dropped by `acceptsTappedAudio`.
+	private func stopSystemAudioTap() {
+		sampleQueue.sync {
+			acceptsTappedAudio = false
+		}
+		guard let tap = systemAudioTap else {
+			return
+		}
+		systemAudioTap = nil
+		tapControlQueue.async {
+			if #available(macOS 14.2, *), let tap = tap as? SystemAudioTap {
+				tap.stop()
+			}
+		}
+	}
+
+	/// Sample queue. The tap's audio takes the same pause and retime path ScreenCaptureKit's
+	/// system audio took in `stream(_:didOutputSampleBuffer:of:)`.
+	private func ingestTappedSystemAudio(_ sampleBuffer: CMSampleBuffer) {
+		guard acceptsTappedAudio else {
+			return
+		}
+		let pauseState = currentPauseState()
+		if pauseState.paused {
+			return
+		}
+		guard let sampleBuffer = retimedSampleBuffer(sampleBuffer, subtracting: pauseState.offset) else {
+			return
+		}
+		audioMixer?.ingest(sampleBuffer, from: .system)
+	}
+
 	func pause() {
 		let didPause = stateQueue.sync {
 			if shutdownTask != nil || isPaused {
@@ -618,7 +705,7 @@ final class ScreenCaptureRecorder: NSObject, SCStreamOutput, SCStreamDelegate {
 		configuration.sampleRate = 48_000
 		configuration.channelCount = 2
 		configuration.excludesCurrentProcessAudio = true
-		configuration.capturesAudio = request.audio.system.enabled
+		configuration.capturesAudio = request.audio.system.enabled && !tapsSystemAudio
 
 		if request.audio.microphone.enabled {
 			guard supportsNativeMicrophoneCapture(streamConfig: configuration) else {
@@ -1054,6 +1141,10 @@ struct OpenScreenScreenCaptureKitHelper {
 	/// picker. See `PickerSession`.
 	private static let pickerSessionFlag = "--picker-session"
 
+	/// The flag that raises macOS' "record system audio" prompt and exits once it is
+	/// answered. See `SystemAudioTap.requestAccess`.
+	private static let requestSystemAudioFlag = "--request-system-audio"
+
 	static func main() async {
 		do {
 			initializeCoreGraphicsWindowServerConnection()
@@ -1079,6 +1170,24 @@ struct OpenScreenScreenCaptureKitHelper {
 				exit(0)
 			}
 
+			if CommandLine.arguments.count == 2, CommandLine.arguments[1] == requestSystemAudioFlag {
+				guard #available(macOS 14.2, *) else {
+					emitError(
+						code: "system-audio-unsupported",
+						message: "Core Audio process taps need macOS 14.2 or later."
+					)
+					exit(2)
+				}
+				do {
+					try SystemAudioTap.requestAccess()
+					emit(["event": "system-audio-access-requested"])
+					exit(0)
+				} catch {
+					emitError(code: "system-audio-request-failed", message: "\(error)")
+					exit(1)
+				}
+			}
+
 			if CommandLine.arguments.count == 2, CommandLine.arguments[1] == pickerSessionFlag {
 				guard #available(macOS 15.2, *) else {
 					emitError(