ScreenCaptureKit Audio: System Audio and Mic Capture Guide

Where this comes from: the API facts are checked against Apple's documentation, WWDC sessions and release notes, linked throughout and listed at the end. The practical tips come from building the native ScreenCaptureKit recorder in the ZoomCap CLI; we say so wherever a tip is ours rather than Apple's.

TL;DR

• System audio: capturesAudio, sampleRate (8/16/24/48 kHz), channelCount (1 or 2) and excludesCurrentProcessAudio, all macOS 13+.
• Microphone: captureMicrophone and microphoneCaptureDeviceID, macOS 15+, delivered as a separate .microphone output.
• Audio filtering is per app, never per window. Excluding one window of an app removes all of that app's sound.
• SCRecordingOutput (macOS 15+) writes an MP4 for you. It mixes mic and system audio into one track unless you're on macOS 27 and turn that off.
• Two permissions: Screen & System Audio Recording, plus Microphone. From a CLI, both belong to the terminal app.
• Sync on presentation timestamps. The microphone runs on its own clock, and a dropped audio buffer becomes drift unless you fill the gap.

Who this is for

Developers building a Mac screen recorder, a meeting recorder, a streaming tool or anything else that needs the Mac's sound. If you just want to record your screen with audio, you don't need any of this. Read does Cmd+Shift+5 record audio? instead, since macOS 27 finally added system audio to the built-in toolbar.

The audio APIs, by macOS version

Everything audio-related in ScreenCaptureKit, with the macOS version Apple's documentation lists for each. (Apple's docs now also list iOS 27 and other platforms for much of the framework. This article is about macOS.)

If you only need audio and no pixels, ScreenCaptureKit isn't your only option. Core Audio taps (AudioHardwareCreateProcessTap, macOS 14.2+) capture the output of specific processes. They need an NSAudioCaptureUsageDescription string and ask for the narrower audio-only recording permission.

How system audio capture works

Set capturesAudio on the stream configuration and add either a stream output for .audio or an SCRecordingOutput. ScreenCaptureKit then delivers system audio as CMSampleBuffers. Each buffer wraps an AudioBufferList whose format comes from your sampleRate and channelCount. The framework delivers up to 48 kHz stereo.

Audio is filtered by app, not by window

This is the rule that surprises people. In Apple's WWDC22 session, the framework's audio policy "always works at the app level". Capture one Safari window with a single-window filter and the audio includes every Safari tab that's playing. Exclude one Safari window from a display filter and all of Safari's audio disappears. Build your UI around apps, not windows, when audio is on.

Leave your own sounds out

excludesCurrentProcessAudio drops audio from your own process. Turn it on if your recorder plays a countdown beep or a start chime. Leave it off if your app is the thing being demoed.

Capturing the microphone (macOS 15+)

Set captureMicrophone = true, optionally choose a device with microphoneCaptureDeviceID, and add an output for .microphone. Apple's WWDC24 example sets the device to AVCaptureDevice.default(for: .audio)?.uniqueID. Leaving it unset records the system default input, which surprises users who picked a different mic in your app. Pass their choice explicitly.

The microphone is not just another audio stream. An Apple DTS engineer on the developer forums put it this way: with the mic on, app audio and mic audio "arrive with different CMFormatDescriptions", the mic "may arrive at a different rate depending on the input device", and the two are "on independent clocks". Writing both into one AVAssetWriterInput corrupts the file. Give each its own input.

On macOS 13 and 14 there is no captureMicrophone. You capture the mic separately with AVCaptureSession or AVAudioEngine and line it up by timestamp yourself.

SCRecordingOutput or your own AVAssetWriter?

Use SCRecordingOutput unless you need to touch frames or audio samples. It turns a stream into a finished movie file with a configuration object and three delegate callbacks. The default container is MPEG-4 with H.264, and you can choose HEVC or .mov.

One tip from our recorder if you use SCRecordingOutput and never read pixels. Capture in kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange rather than BGRA. BGRA is 32 bits per pixel against 12, and it adds a colour conversion before encoding. On a large Retina display at 60 fps, that is the difference between smooth scrolling and dropped frames.

A minimal recorder (illustrative sketch)

This is a sketch to show the shape of the API, not production code. It records the main display with system audio and, if permitted, the microphone, to an MP4. It needs macOS 15 or later.

import AVFoundation
import ScreenCaptureKit

@available(macOS 15.0, *)
final class AudioScreenRecorder: NSObject,
    SCStreamDelegate, SCRecordingOutputDelegate {
    private var stream: SCStream?

    func start(to url: URL, wantsMic: Bool) async throws {
        // Requires Screen Recording permission.
        let content = try await SCShareableContent.excludingDesktopWindows(
            false, onScreenWindowsOnly: true)
        guard let display = content.displays.first else { return }

        // Audio is filtered per app, so this includes every app's sound.
        let filter = SCContentFilter(display: display, excludingWindows: [])

        let config = SCStreamConfiguration()
        config.width = display.width * 2    // assumes a 2x display
        config.height = display.height * 2
        config.minimumFrameInterval = CMTime(value: 1, timescale: 60)

        config.capturesAudio = true               // system audio, macOS 13+
        config.sampleRate = 48_000                // 8k, 16k, 24k or 48k
        config.channelCount = 2                   // 1 or 2
        config.excludesCurrentProcessAudio = true // skip our own sounds

        // The mic has its own permission: record without it, don't fail.
        var useMic = wantsMic
        let micStatus = AVCaptureDevice.authorizationStatus(for: .audio)
        if useMic && micStatus != .authorized {
            useMic = await AVCaptureDevice.requestAccess(for: .audio)
        }
        config.captureMicrophone = useMic         // macOS 15+
        // Optional: config.microphoneCaptureDeviceID = device.uniqueID

        let stream = SCStream(filter: filter, configuration: config,
                              delegate: self)

        let recordingConfig = SCRecordingOutputConfiguration()
        recordingConfig.outputURL = url           // defaults: MPEG-4, H.264
        let recording = SCRecordingOutput(configuration: recordingConfig,
                                          delegate: self)
        try stream.addRecordingOutput(recording)

        try await stream.startCapture()           // also starts recording
        self.stream = stream
    }

    func stop() async throws {
        try await stream?.stopCapture()
        // Not done yet: wait for recordingOutputDidFinishRecording.
    }

    func recordingOutputDidStartRecording(_ output: SCRecordingOutput) {
        // output.recordedDuration = video already written.
    }

    func recordingOutput(_ output: SCRecordingOutput,
                         didFailWithError error: Error) {
        // Surface this. Assume the file is unusable.
    }

    func recordingOutputDidFinishRecording(_ output: SCRecordingOutput) {
        // Now it is safe to open, move or upload the file.
    }

    func stream(_ stream: SCStream, didStopWithError error: Error) {
        // Also fires when the user stops sharing from the system UI
        // (SCStreamError.userStopped). Treat that as a normal stop.
    }
}

If you write the file yourself, the part that matters for audio is the routing. Register each type with addStreamOutput(_:type:sampleHandlerQueue:) and give audio its own queue, so slow video work can't starve it:

// Inside your SCStreamOutput (macOS 15+ because of .microphone).
func stream(_ stream: SCStream,
            didOutputSampleBuffer sampleBuffer: CMSampleBuffer,
            of type: SCStreamOutputType) {
    guard sampleBuffer.isValid else { return }
    switch type {
    case .screen:
        // .idle means the display didn't change; only .complete is new.
        guard isCompleteFrame(sampleBuffer) else { return }
        startSessionIfNeeded(at: sampleBuffer.presentationTimeStamp)
        append(sampleBuffer, to: videoInput)
    case .audio:
        append(sampleBuffer, to: systemAudioInput)
    case .microphone:
        append(sampleBuffer, to: micInput)  // never the .audio input
    @unknown default:
        break
    }
}

func isCompleteFrame(_ sampleBuffer: CMSampleBuffer) -> Bool {
    let attachments = CMSampleBufferGetSampleAttachmentsArray(
        sampleBuffer, createIfNecessary: false)
    guard let info = (attachments as? [[SCStreamFrameInfo: Any]])?.first,
          let raw = info[.status] as? Int,
          let status = SCFrameStatus(rawValue: raw) else { return false }
    return status == .complete
}

Set expectsMediaDataInRealTime = true on each input. The macOS 27 SDK deprecates it in favour of the new input receiver's appendImmediately, but it still works on everything you're likely to support. When an input isn't ready for more data, count the drop. Don't silently discard it (see sync).

Permissions, and the Sequoia prompts

ScreenCaptureKit needs the Screen & System Audio Recording permission, and microphone capture also needs the Microphone permission. They are separate grants in System Settings > Privacy & Security. Apple's user guide notes that people can allow an app to record "both your screen and audio, or just your audio".

• Screen recording: add an NSScreenCaptureUsageDescription string. Apple's own sample warns that after granting, the app must be restarted before capture works. Tell your users that.
• Microphone: add NSMicrophoneUsageDescription and the com.apple.security.device.audio-input entitlement. Check AVCaptureDevice.authorizationStatus(for: .audio) before you configure the stream.
• Prefer the system picker. Apple recommends SCContentSharingPicker (macOS 14+) over building your own selection UI.

The recurring prompt in macOS Sequoia

macOS 15 added a recurring alert for apps that capture the screen directly. It reads "[App] is requesting to bypass the system private window picker and directly access your screen and audio", with an Allow For One Month button. It was weekly in the betas and monthly at release. The macOS 15.1 notes add that people "will see fewer dialogs if they regularly use apps in which they have already acknowledged and accepted the risks."

Apple's macOS 15 notes tie these alerts to deprecated APIs such as CGDisplayStream and CGWindowListCreateImage, and tell developers to move to ScreenCaptureKit and SCContentSharingPicker. Press coverage at the time reported ScreenCaptureKit apps seeing it too. Managed Macs can suppress the alert with the MDM key forceBypassScreenCaptureAlert (macOS 15.1), and VNC-style apps can apply for the Persistent Content Capture entitlement. We couldn't verify from Apple how often the prompt appears on macOS 26 or 27, so design for it. When capture fails to start, point users to the right settings pane instead of showing a raw error.

Capturing from a CLI: the terminal owns the permission

If your recorder is a command-line binary, macOS attributes capture to the app that launched it. That app is the "responsible process": Terminal, iTerm2, or your IDE's terminal. That's where the Screen Recording and Microphone grants go, and it's the entry users need to toggle.

We lean on this on purpose. The ZoomCap CLI ships its recorder as a plain universal binary rather than a .app bundle, because a bundle gets its own privacy identity and needs its own separate grant. A plain binary inherits the terminal's. Two things we learned along the way:

• Don't gate on CGPreflightScreenCaptureAccess(). For a plain binary it can report the wrong answer for the identity that actually records. We call CGRequestScreenCaptureAccess() as a nudge, then treat startCapture's error as the source of truth.
• Put a timeout on permission probes. On some macOS builds, getShareableContent hangs rather than failing when the grant is missing. Our check gives up after five seconds, and it runs from the same binary that records, because the answer depends on who asks.

Developers have also reported on Apple's forums that, since macOS Tahoe 26.1, plain executables no longer show up in the Screen Recording list. Point users at their terminal app, not at your binary.

Keeping audio and video in sync

Use each buffer's presentation timestamp, never the time it arrived. Screen, system audio and microphone buffers come in on different queues at different rates, so arrival order tells you nothing. Everything below follows from that.

1. Start the writer session at the first complete frame. Apple's docs for startSession(atSourceTime:) say samples earlier than the start time are written but don't play, and an input whose first sample is later gets an empty edit "to preserve synchronization between tracks".
2. Treat the mic as its own clock. Apple DTS's advice is to offset mic and app audio relative to your recording start. If the mic's first timestamp is far from the video's, its audio lands before time zero or after the end, and plays as silence. Log the first timestamp of each output type while you develop.
3. Never drop audio silently. If you discard a buffer because isReadyForMoreMediaData is false, every later sample plays early by that amount. Audio drifts ahead of the picture. Deliver audio on its own queue, and fill any gap between one buffer's end and the next buffer's start with silence.
4. Expect idle frames. On a static screen, many frames don't carry a .complete status. Your audio keeps going while your video track may end early. Repeat the last frame at the end if the track lengths must match.

With SCRecordingOutput, the system handles audio and video interleaving. You still need a clock of your own if you record anything alongside, such as input events or a webcam. We anchor "video time zero" in recordingOutputDidStartRecording: we take the current host time and subtract recordedDuration, rather than trusting when the callback happened to run. We stamp events with NSEvent.timestamp (the same boot-time clock as CACurrentMediaTime()), not the time our handler ran. Under encoding load, handlers run late, and that lateness shows up as drift.

What the ZoomCap recorder does, end to end

For a concrete reference, here is how our CLI's native recorder puts the pieces together:

1. Native on macOS 15+. npx zoomcap record checks the OS version first. Older macOS falls back to an ffmpeg recorder that captures video only, because captureMicrophone and SCRecordingOutput don't exist there.
2. One stream, one file. A display filter with no exclusions, capturesAudio for system audio, excludesCurrentProcessAudio, and captureMicrophone when allowed, all written by SCRecordingOutput to an MP4.
3. The mic never blocks a take. If Microphone isn't granted, we request it for next time, warn, and record screen and system audio without it.
4. Every stop is a stop. If the stream ends for a reason we didn't start, we finalize at once. That covers the system Stop control, a revoked permission or an unplugged display. Otherwise the file never closes and the privacy indicator stays lit. A 120-second backstop covers a finalize that truly hangs. Flushing a long, high-res recording can legitimately take tens of seconds, so the backstop can't be shorter.
5. Duration comes from the recording. We report recordedDuration at finish, not wall-clock time, because teardown time isn't video.

Common pitfalls

• No audio output registered. capturesAudio alone does nothing for a custom pipeline. You also need addStreamOutput(_:type: .audio, ...), and the same goes for .microphone.
• Silence because the app is excluded. Excluding any window of an app removes all of its audio.
• Silence from your own app. excludesCurrentProcessAudio is on, but the sound you wanted came from your process.
• Sample-rate assumptions. Asking for 44.1 kHz gives you 48 kHz. The mic may not match system audio. Read the format description of each buffer.
• A non-exhaustive switch. Apple's own sample handles .screen and .audio. Once you turn the mic on, handle .microphone and add @unknown default.
• Exiting before the file is finished. Wait for recordingOutputDidFinishRecording (or finishWriting) before you quit, move or upload.
• Granting the wrong app. From a CLI, the terminal needs the grant, and it may need a restart after.
• Queue depth over 8. Apple says not to exceed eight frames. We use eight on large Retina displays so a slow encoder doesn't drop frames.

When ScreenCaptureKit is the wrong tool

• Audio only, from specific apps: use Core Audio taps. There are no pixels to pay for, and the permission is narrower.
• You just need a recording, not a product: on macOS 15 or later, npx zoomcap record captures screen, system audio and mic in one command; on macOS 27, Cmd+Shift+5 records system audio too, and OBS is the free option on older systems. Our guide to recording a Mac screen with audio covers the rest.
• A still bug report: a screenshot and three lines of text beat a video nobody wants to scrub through.

Our recommendation

Target macOS 15 or later if you can. You get the mic in the same stream and SCRecordingOutput for the file, which removes most of the sync code you'd otherwise write. Drop to SCStreamOutput and AVAssetWriter only when you need samples or separate tracks before macOS 27. Design your permission flow for a terminal as carefully as for an app, because that's where CLI users get stuck.

If you'd rather not build a recorder at all, ours is one command. npx zoomcap record captures the screen, system audio and your mic on macOS 15+, and the browser editor adds zooms where you clicked. It's part of the paid plans, $29 once or $12.49 a month. The recording is edited and exported on your machine with nothing uploaded; the security page shows the data flow. It records the whole display with no per-app audio choice, and on Linux it records video only. The docs list every flag. If you need scenes, streaming or per-app audio, OBS is free and does them; we compared the two in OBS vs ZoomCap.

Frequently asked questions

Sources: Apple's ScreenCaptureKit documentation, the Capturing screen content in macOS sample, WWDC22 sessions 10156 and 10155, WWDC24 10088, and the macOS 15 and 15.1 release notes. All were checked in September 2026.

Skip the build and record today. Try ZoomCap free in the browser recorder, or get the ScreenCaptureKit CLI with system audio, mic and automatic zoom for $29 once on the pricing page.