ScreenCaptureKit Native Integration
Relevant source files
The following files were used as context for generating this wiki page:
ScreenCaptureKit Native Integration enables high-performance screen and system audio recording on macOS. The system captures video frames and audio samples directly from the operating system's SCStream and processes them through AVAssetWriter for file storage.
The integration supports capturing full displays, specific windows, or system-wide audio only. It manages the complexities of sample buffer synchronization, permission handling, and real-time data encoding to ensure consistent recording quality even under system load.
Sources: README.md, Sources/Spike/SckCapture.swift
Architecture and Data Flow
The architecture centers on the SckCapture class, which wraps the native SCStream. It routes captured CMSampleBuffer data through a single serial dispatch queue to maintain temporal order.
The diagram above shows the synchronous flow of data from ScreenCaptureKit to the final media file.
Stream Management
SckCapture initializes the SCStream using specific filters and configurations. It filters incomplete frames by checking the SCFrameStatus within the sample buffer attachments.
- Initialization: Configures the stream with
SCContentFilterandSCStreamConfiguration. - Output Handling: Implements
SCStreamOutputto receive.screen(video) and.audiosamples. - Validation: Discards invalid buffers or frames marked as
.idleor.blank.
Sources: Sources/Spike/SckCapture.swift:9-55
Content Filtering and Scoping
The system uses SCContentFilter to define what portions of the screen or which audio sources are captured.
Capture Modes
| Mode | Target | Description |
|---|---|---|
| Display | SCContentFilter(display: ...) | Captures the entire desktop including all visible elements. |
| Window | SCContentFilter(desktopIndependentWindow: ...) | Captures only the specified window and its exclusive audio. |
| Audio Only | SckCapture(audio: true, observeScreen: false) | Disables video output registration to capture only system sounds. |
Sources: Sources/Spike/RecSystemCmd.swift:105-112, Sources/Spike/RecWindowCmd.swift:45-52, Sources/Spike/RecAudioOnlyCmd.swift:55-58
Window-Specific Audio Scope
When recording a specific window, the integration ensures that only audio generated by the owning application is captured. This prevents background noise or other application sounds from leaking into the recording.
Sources: Sources/Spike/RecWindowCmd.swift:65-67
Encoding and Synchronization
The MovieWriter class manages the conversion of raw buffers into an H.264 video and AAC audio container.
The sequence diagram illustrates the session initialization based on the first received sample.
Precision Timing and Anchor Points
Because ScreenCaptureKit may provide buffers with invalid durations, the integration re-calculates video timing using CMSampleTimingInfo with a 1/600s duration. The session start time (anchor) is determined by either the first video sample or the first audio sample depending on the capture mode.
- Video Timing: Overwrites invalid durations to ensure smooth playback.
- Session Start:
AVAssetWriter.startSession(atSourceTime:)is called only upon receiving the first valid sample. - Audio Alignment: Measures the PTS offset between video and audio to report synchronization accuracy.
Sources: Sources/Spike/MovieWriter.swift:58-94, Sources/Spike/MovieWriter.swift:109-130
Configuration Parameters
The SCStreamConfiguration is tuned for high-quality capture and compatibility with AVAssetWriter.
| Parameter | Value | Source/Reason |
|---|---|---|
pixelFormat | kCVPixelFormatType_32BGRA | Required for re-compression with custom bitrates. |
sampleRate | 48000 | Standard high-fidelity audio rate. |
channelCount | 2 | Stereo audio capture. |
capturesAudio | true | Enables system-wide or app-specific audio capture. |
Sources: Sources/Spike/RecSystemCmd.swift:34-36, Sources/Spike/RecSystemCmd.swift:99-103
Environment Diagnosis
Before initiating a capture, the Doctor module verifies the system environment to prevent runtime failures.
- Screen Capture Access: Validates permissions using
CGPreflightScreenCaptureAccess. - Audio Permissions: Checks
AVCaptureDevice.authorizationStatus(for: .audio). - Content Enumeration: Attempts to fetch
SCShareableContent.currentto confirm the process can see displays and windows. - CoreAudio Status: Lists available devices and identifies loopback drivers like BlackHole.
Sources: Sources/Spike/Doctor.swift:9-45
Summary
The ScreenCaptureKit Native Integration provides a robust pipeline for macOS media capture. It effectively manages the lifecycle of native capture streams, ensures data integrity through precise timing corrections, and offers flexible scoping for both system-wide and application-specific recording. By utilizing AVAssetWriter with non-compressed input formats, it maintains high quality while allowing for specific output constraints.