ScreenCaptureKit for macOS Screen Recording - Encoding Approaches and Lessons
ScreenCaptureKit for macOS Screen Recording - Encoding Approaches and Lessons
ScreenCaptureKit is Apple's modern API for screen capture on macOS, and it is genuinely good. But the encoding decisions you make on top of it determine whether your recording app is usable or a resource hog.
The Basic Architecture
ScreenCaptureKit gives you a stream of CMSampleBuffer frames. What you do with those frames is entirely up to you. The two main paths are:
- AVAssetWriter - write frames directly to a video file using hardware-accelerated H.264 or HEVC encoding
- VideoToolbox - lower-level access to the encoder for custom pipelines, live streaming, or frame-by-frame control
Most screen recording apps should use AVAssetWriter. It handles the encoding pipeline, manages the output file, and uses the hardware encoder on Apple Silicon without extra configuration. Going to VideoToolbox only makes sense when you need frame-level control or a custom container format.
Encoding Trade-offs
The critical decision is your encoding preset and quality settings:
- H.264 with hardware encoding - fast, compatible, reasonable file sizes. Good default for most use cases.
- HEVC (H.265) - better compression at the same quality, but slower to encode and less compatible with older players.
- ProRes - lossless quality, massive files. Only useful for professional video editing workflows.
For a screen recording app aimed at developers recording demos, H.264 at a moderate bitrate (around 8-12 Mbps for 1080p) hits the sweet spot. File sizes stay reasonable and playback works everywhere.
Lessons from Building with It
The biggest gotcha is frame timing. ScreenCaptureKit delivers frames at the display refresh rate, but you probably want to record at 30fps, not 120fps. Dropping frames correctly without visual stuttering requires careful timestamp management.
Another common issue is handling display changes - when the user connects an external monitor or changes resolution mid-recording. ScreenCaptureKit sends a configuration change notification, and your encoder needs to handle the resolution shift gracefully.
Audio capture is straightforward - ScreenCaptureKit can capture both system audio and microphone input. Just make sure to sync audio and video timestamps or you will get drift over long recordings.
Performance on Apple Silicon
On M-series chips, the hardware encoder barely impacts system performance. You can record your screen at 60fps while running heavy development workflows without noticeable slowdown. This was not true in the older CGWindowList days.
Fazm is an open source macOS AI agent. Open source on GitHub.