Command: Record Audio Only
Relevant source files
The following files were used as context for generating this wiki page:
The rec-audio-only command captures system or application-specific audio using the ScreenCaptureKit (SCK) framework without recording video. It serves as a verification tool to ensure audio buffers are correctly received when video output registration is bypassed or scoped to specific windows.
This command generates an .m4a file containing the captured audio stream. It supports capturing the entire system audio or filtering audio to a specific application window using the --match flag.
Sources: Sources/Spike/RecAudioOnlyCmd.swift:7-10, Sources/Spike/main.swift:34-37
Architecture and Data Flow
The audio capture process involves configuring an SCStream to specifically target audio data. The command utilizes a shared session runner that manages the lifecycle of the recording, including initialization, signal handling for safe termination, and file finalization.
Execution Flow
- Permission Check: The command verifies screen capture access using
CGPreflightScreenCaptureAccess(). - Filter Configuration: It creates an
SCContentFiltertargeting either the main display or a specific window. - Stream Setup: An
SCStreamConfigurationis initialized withcapturesAudio = trueand specific audio parameters (48kHz, 2 channels). - Capture and Write: The
SckCaptureclass receivesCMSampleBufferobjects of type.audioand passes them toMovieWriter. - Finalization: Upon duration expiry or receiving a stop signal (SIGINT/SIGTERM), the writer closes the file.
Key Components
RecAudioOnlyCmd
The primary entry point for the audio recording logic. It parses command-line arguments, determines the capture scope, and invokes the recording session.
Sources: Sources/Spike/RecAudioOnlyCmd.swift:7-9
MovieWriter
Handles the actual file writing using AVAssetWriter. For audio-only mode, it sets the session anchor to .firstAudio and uses the .m4a file type. It encodes audio into kAudioFormatMPEG4AAC at 48,000Hz.
Sources: Sources/Spike/MovieWriter.swift:12-68
SckCapture
Wraps SCStream to handle sample buffer delivery. In audio-only mode, the observeScreen parameter is typically set to false, which prevents the registration of a .screen output, verifying that SCK can function with audio output alone.
Sources: Sources/Spike/SckCapture.swift:10-32
Configuration and Options
The command accepts several flags to modify capture behavior.
| Option | Type | Description | Default |
|---|---|---|---|
--duration | String | Duration of recording (e.g., "10s", "1m"). | 6s |
--output | Path | Custom file path for the resulting .m4a. | spike-rec-audio-only-[timestamp].m4a |
--match | String | Partial match for window title or bundle ID to scope audio. | N/A (System-wide) |
--with-screen-output | Flag | Registers screen output to compare performance/behavior. | false |
Sources: Sources/Spike/RecAudioOnlyCmd.swift:14-17, Sources/Spike/Util.swift:42-47, Sources/Spike/main.swift:34-37
Audio Scope and Filtering
When the --match option is provided, the system filters the SCShareableContent to find a specific window. This allows the command to capture only the audio produced by that specific application process, effectively ignoring other system sounds.
Technical Implementation Details
The audio recording relies on specific parameters to ensure compatibility with standard media players:
- Format: MPEG4 AAC (
kAudioFormatMPEG4AAC). - Sample Rate: 48,000 Hz.
- Channels: 2 (Stereo).
- Session Anchoring: For audio-only files, the
MovieWriterstarts theAVAssetWritersession using the presentation timestamp (PTS) of the first received audio sample.
Sources: Sources/Spike/MovieWriter.swift:60-66, Sources/Spike/MovieWriter.swift:107-113, Sources/Spike/RecSystemCmd.swift:85-88
Summary
The rec-audio-only command provides a specialized path for capturing system and application audio without the overhead of video processing. By utilizing SCContentFilter and SCStreamConfiguration, it validates the project's ability to scope audio to specific applications and verifies that ScreenCaptureKit functions correctly when only audio outputs are registered. Finalized files are saved as standard .m4a documents with AAC encoding.