| name | macos-audio-capture |
| description | Capture system audio, microphone audio, and screenshots on macOS. ScreenCaptureKit, Core Audio Taps, AVAudioEngine, SCStream, SCStreamConfiguration, loopback audio, echo cancellation, noise suppression, voice processing, SCScreenshotManager, Electron desktopCapturer, AudioTee, aggregate device, CATapDescription, silence detection, screen lock persistence, CMSampleBuffer, AVAssetWriter, PCM audio streaming. Use when building meeting recorders, transcription apps, screen recording tools, or any app capturing system/mic audio on macOS. |
macOS Audio & Screenshot Capture
Capture system audio output, microphone input, and screenshots on macOS without touching system volume levels or requiring third-party audio drivers.
When to Read Reference Files
Decision: Which Audio Capture API
Three viable APIs exist. Choose based on your constraints:
ScreenCaptureKit (macOS 13+) — Apple's primary recommendation. Captures system audio + mic in a single SCStream. Also captures video frames if needed. Requires "Screen & System Audio Recording" permission. Best when you also need screen capture, or want a single unified stream of system + mic audio.
Core Audio Taps (macOS 14.2+) — Lower-level. Taps audio pre-mixer (volume-independent). Only requires "System Audio Recording" permission (no screen recording). Best for audio-only apps (transcription, meeting recorders) where you don't want misleading screen-recording indicators. Can target specific processes.
AVAudioEngine with Voice Processing (macOS 10.15+) — Mic-only with built-in AEC/noise suppression. Does not capture system audio. Use for mic input when echo cancellation matters (VoIP, meeting recording where you also capture system audio separately).
| Concern | ScreenCaptureKit | Core Audio Taps | AVAudioEngine |
|---|
| System audio | Yes | Yes | No |
| Mic audio | Yes (macOS 14+) | No (mic separate) | Yes |
| Echo cancellation | No | No | Yes (voice processing mode) |
| Permission type | Screen & System Audio | System Audio Only | Microphone |
| Volume-independent | Yes | Yes (pre-mixer) | N/A |
| Process filtering | Via SCContentFilter | Via CATapDescription | N/A |
| Min macOS | 13.0 | 14.2 | 10.15 |
Typical meeting-recorder architecture: Core Audio Taps (system audio) + AVAudioEngine with voice processing (mic with AEC) → two separate PCM streams merged or kept as separate tracks.
Entitlements & Permissions
All audio capture requires the app to be signed and have appropriate Info.plist keys:
NSAudioCaptureUsageDescription — Required for Core Audio Taps and ScreenCaptureKit audio. Customizable prompt text.NSMicrophoneUsageDescription — Required for mic access (AVAudioEngine, or SCStream with captureMicrophone).NSScreenCaptureUsageDescription — Required for ScreenCaptureKit (even audio-only, since it goes through the screen recording permission path).
Sandbox entitlements (if sandboxed):
com.apple.security.device.audio-input — Miccom.apple.security.device.screen-capture — ScreenCaptureKit
For Electron apps, the parent process (terminal, IDE, or the .app bundle itself) must contain the relevant Info.plist keys.
Audio Format Defaults
For speech/meeting recording, prefer:
- Sample rate: 48kHz capture → downsample to 16kHz for ASR services
- Channels: Mono (sufficient for speech; halves bandwidth)
- Bit depth: 16-bit signed integer (after any sample rate conversion)
- Format: Raw PCM for streaming; AAC/OPUS for file storage
ScreenCaptureKit defaults: 48kHz stereo Float32. Core Audio Taps: matches output device (typically 44.1kHz or 48kHz, 32-bit float).
