Microphone Capture Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Microphone Capture Engine provides the capability to capture audio data from a built-in microphone or external input devices. It operates as a component of the Kilde "spike" verification tool to support multi-track recording scenarios where system audio and physical microphone input must be separated. Sources: Sources/Spike/MicCapture.swift, Sources/Spike/RecSystemCmd.swift:23-28
The engine utilizes the AVFoundation framework to interface with hardware devices. It processes raw audio frames into CMSampleBuffer objects, which are then dispatched to a data sink for recording or analysis. Sources: Sources/Spike/MicCapture.swift:6-12
Architecture and Components
The capture engine centers around the MicCapture class, which manages an AVCaptureSession. This session coordinates the flow of data from an input device to a specific output delegate.
Core Components
- AVCaptureSession: Manages the real-time data flow from the hardware input to the output. Sources: Sources/Spike/MicCapture.swift:8
- AVCaptureDeviceInput: Represents the physical hardware device (e.g., microphone) selected for capture. Sources: Sources/Spike/MicCapture.swift:23
- AVCaptureAudioDataOutput: Captures the audio data and provides it to a delegate on a private serial queue. Sources: Sources/Spike/MicCapture.swift:9-10
- Data Sink: A closure that receives
CMSampleBufferobjects for processing by other modules likeMovieWriter. Sources: Sources/Spike/MicCapture.swift:12
Capture Data Flow
The following diagram illustrates how audio data moves from the hardware device to the file writer.
The engine uses a dedicated serial dispatch queue named spike.mic to ensure thread-safe delivery of audio samples. Sources: Sources/Spike/MicCapture.swift:10
Permission Management
Before capturing audio, the engine verifies system-level permissions. The ensureMicPermission() function checks the AVAuthorizationStatus. Sources: Sources/Spike/MicCapture.swift:44-61
| Status | Engine Action |
|---|---|
authorized | Proceeds with session initialization. |
notDetermined | Requests access via a system dialog and waits for a user response. |
denied / restricted | Fails with an error message. |
Sources: Sources/Spike/MicCapture.swift:45-60, Sources/Spike/RecSystemCmd.swift:93-95
Device Discovery and Selection
The engine can target specific devices using their Unique Identifiers (UIDs) or default to the system's primary audio input. Sources: Sources/Spike/MicCapture.swift:14-22
- Automatic Selection: If no UID is provided, the engine uses
AVCaptureDevice.default(for: .audio). Sources: Sources/Spike/MicCapture.swift:20 - Manual Selection: Users can specify a UID via CLI flags like
--device. Sources: Sources/Spike/RecDeviceCmd.swift:15-22 - Discovery: The engine lists available devices using
AVCaptureDevice.DiscoverySession, filtering for.builtInMicrophoneand.externaltypes. Sources: Sources/Spike/DevicesCmd.swift:34-40, Sources/Spike/Doctor.swift:57-62
Implementation Details
Session Lifecycle
The MicCapture class manages the session lifecycle through start() and stop() methods. Because startRunning() is a blocking call, it is executed on a dedicated startQueue. Sources: Sources/Spike/MicCapture.swift:11, 31-37
// Sources/Spike/MicCapture.swift:31-37
func start() {
startQueue.sync { session.startRunning() }
}
func stop() {
startQueue.sync { session.stopRunning() }
}
Integration with Recording Sessions
When the --mic flag is used in recording commands, the system initializes a MicCapture instance alongside the SckCapture (Screen Capture Kit) engine. The MovieWriter is configured with multiple audio labels to maintain separate tracks. Sources: Sources/Spike/RecSystemCmd.swift:47-52, Sources/Spike/MovieWriter.swift:49-60
The "mic" track is processed independently of the "system" track, allowing for multi-channel M4A or MOV files. Sources: Sources/Spike/MovieWriter.swift:125-135
Technical Specifications
| Property | Value |
|---|---|
| Framework | AVFoundation |
| Data Format | CMSampleBuffer |
| Sample Rate | 48,000 Hz (Transcoded by MovieWriter) |
| Channels | 2 (Transcoded by MovieWriter) |
| Dispatch Queue | spike.mic (Serial) |
Sources: Sources/Spike/MicCapture.swift:10, Sources/Spike/MovieWriter.swift:51-54
The Microphone Capture Engine ensures that physical audio input is captured reliably even if the system audio capture (via ScreenCaptureKit) encounters issues. It provides the necessary infrastructure for validating audio-visual synchronization and multi-track integrity in the project. Sources: Sources/Spike/RecSystemCmd.swift:47-52, Sources/Spike/MovieWriter.swift:125-130