Command: Record System
Relevant source files
The following files were used as context for generating this wiki page:
The rec-system command captures a macOS display along with system audio. It allows you to record the screen and internal sounds simultaneously, with an optional flag to include microphone input as a separate audio track. This command serves as the primary verification tool for synchronized screen and audio capture using the ScreenCaptureKit (SCK) and AVFoundation frameworks.
Sources: Sources/Spike/RecSystemCmd.swift:7, Sources/Spike/main.swift:23-27
Architecture and Data Flow
The recording system coordinates multiple capture sources and pipes them into a centralized file writer. It utilizes SCStream for screen and system audio, and AVCaptureSession for microphone input. All captured buffers are processed through a single serial queue to maintain order before being appended to the final media file.
The diagram above illustrates the flow of sample buffers from capture components to the MovieWriter.
Sources: Sources/Spike/RecSystemCmd.swift:14-49, Sources/Spike/SckCapture.swift:9-12
Component Roles
SckCapture
SckCapture wraps the SCStream API. It configures the stream to capture both screen content and system audio. It requests non-compressed 32BGRA pixel formats to allow custom re-compression during the writing phase.
Sources: Sources/Spike/SckCapture.swift:7-14, Sources/Spike/RecSystemCmd.swift:34-37
MicCapture
When the --mic flag is present, MicCapture initializes an AVCaptureSession using the default audio input device. It provides audio sample buffers to the writer, enabling multi-track audio recording.
Sources: Sources/Spike/MicCapture.swift:8-14, Sources/Spike/RecSystemCmd.swift:45-49
MovieWriter
MovieWriter manages the AVAssetWriter lifecycle. It synchronizes the start of the recording session based on the Presentation Time Stamp (PTS) of the first received video or audio sample.
Sources: Sources/Spike/MovieWriter.swift:8-15, Sources/Spike/MovieWriter.swift:105-110
Execution Logic
The command follows a strict sequence to ensure permissions are met and resources are properly initialized before starting the capture.
- Permission Check: Validates screen recording and microphone permissions using
CGPreflightScreenCaptureAccessandensureMicPermission. - Display Selection: Retrieves shareable content and selects the target display.
- Configuration: Sets up
SCStreamConfigurationwith specific sample rates (48kHz) and channel counts. - Session Start: Initializes
SckCaptureandMicCapture. - Signal Handling: Installs handlers for
SIGINT(Ctrl+C) to ensure a safe shutdown and file finalization. - Finalization: Stops all streams and calls
finishWritingon theAVAssetWriter.
Sources: Sources/Spike/RecSystemCmd.swift:84-110, Sources/Spike/Util.swift:66-77
Recording Sequence
Command Options
| Option | Type | Default | Description |
|---|---|---|---|
--duration | String | 6s | The length of the recording (e.g., 10s, 1m). |
--output | Path | spike-rec-system-TIMESTAMP.mov | The destination path for the recorded file. |
--mic | Flag | false | If set, includes the microphone as a second audio track. |
--display | Integer | 0 | The index of the display to record. |
Sources: Sources/Spike/RecSystemCmd.swift:77-80, Sources/Spike/Util.swift:51-57
Technical Implementation Details
Timing and Synchronization
To prevent timing issues in the resulting file, MovieWriter ensures that video buffers have valid durations. If a buffer has an invalid duration, the system assigns a default value of 1/600s.
Sources: Sources/Spike/MovieWriter.swift:125-145
Signal Handling for Safety
The system uses DispatchSourceSignal to catch termination signals. When you press Ctrl+C, the handler triggers a semaphore that initiates the teardown process, ensuring the AVAssetWriter closes the file correctly rather than leaving it corrupted.
Sources: Sources/Spike/Util.swift:66-77, Sources/Spike/RecSystemCmd.swift:57-61
Conclusion
The rec-system command provides a robust implementation for capturing high-quality screen recordings with internal and external audio. By leveraging non-compressed buffers and manual signal handling, it ensures data integrity and precise control over the recording output.