Audio Device Management
Relevant source files
The following files were used as context for generating this wiki page:
Audio Device Management in the kilde project provides the infrastructure for discovering, configuring, and monitoring audio hardware on macOS. It enables the system to interact with CoreAudio HAL (Hardware Abstraction Layer) to list physical and virtual devices, manage default system outputs, and create aggregate devices for loopback recording.
This system is essential for capturing system audio alongside microphone input by leveraging virtual drivers like BlackHole. It ensures that recording sessions can access the correct audio streams while maintaining the user's ability to hear system sounds through their primary output device.
CoreAudio Hardware Abstraction Layer (HAL)
The AudioHAL enumeration serves as the primary interface for interacting with the macOS CoreAudio system object. It retrieves hardware information using AudioObjectPropertyAddress selectors to query system-wide audio properties.
Device Discovery Logic
The system queries the kAudioObjectSystemObject to obtain a list of AudioObjectID values. For each ID, it fetches metadata including the device name, UID, and the number of input/output channels.
Audio Device Data Structures
The system represents devices using the AudioDeviceInfo struct, which categorizes hardware based on channel configurations and naming conventions.
| Field | Type | Description |
|---|---|---|
id | AudioObjectID | The internal CoreAudio identifier. |
name | String | Human-readable name (e.g., "BlackHole 2ch"). |
uid | String | Unique persistent identifier for the device. |
inputChannels | Int | Number of available input channels. |
outputChannels | Int | Number of available output channels. |
Sources: Sources/Spike/AudioDevices.swift:7-21
Aggregate and Monitor Devices
The MonitorDevice module manages the creation and destruction of virtual aggregate devices. This allows kilde to route system audio to both a physical output (so the user can hear it) and a virtual loopback device (for recording) simultaneously.
Aggregate Device Creation
The system uses the AudioHardwareCreateAggregateDevice function with a specific configuration dictionary. A critical implementation detail is the use of the "stacked" flag, which enables simultaneous output to all member sub-devices, mirroring the "Multi-Output Device" behavior in Audio MIDI Setup.
State Persistence
When a monitor device is set up, the MonitorCmd saves the original default output UID to a local JSON file (~/.kilde_spike_monitor.json). This allows the teardown command to restore the user's original audio settings even after the application restarts.
Sources: Sources/Spike/MonitorCmd.swift:11-23, Sources/Spike/MonitorCmd.swift:70-83
Audio Capture and Permissions
Capturing audio involves two distinct paths: system audio via ScreenCaptureKit (handled in recording commands) and input device audio via AVCaptureSession.
Input Device Capture
The MicCapture class manages audio input from microphones or virtual devices like BlackHole. It uses AVCaptureAudioDataOutput to deliver CMSampleBuffer data to a provided sink function.
- Initialization: Configures
AVCaptureDeviceInputbased on a specificuniqueIDor the system default. - Threading: Uses a dedicated
DispatchQueue("spike.mic") for sample buffer handling to avoid blocking the main thread.
Sources: Sources/Spike/MicCapture.swift:8-35
Permission Management
The system verifies and requests necessary permissions for audio capture.
- Check Status: Queries
AVCaptureDevice.authorizationStatus(for: .audio). - Request Access: If status is
.notDetermined, it callsrequestAccess(for: .audio)and uses aDispatchSemaphoreto wait for the user's response synchronously.
Sources: Sources/Spike/MicCapture.swift:45-62, Sources/Spike/Doctor.swift:23-32
Diagnostic and Inspection Tools
Kilde includes commands to inspect the state of audio devices and verify recording integrity.
- Doctor Command: Diagnoses the environment by listing macOS version, SCK access status, microphone permissions, and detected CoreAudio/AVCapture devices.
- Devices Command: Lists all displays and audio devices, marking the current default output and detected BlackHole instances.
- Inspect Command: Analyzes recording files to verify track composition, duration, and audio levels (RMS/Peak).
| Command | File | Purpose |
|---|---|---|
spike doctor | Doctor.swift | Validates permissions and hardware availability. |
spike devices | DevicesCmd.swift | Enumerates all available audio and video sources. |
spike monitor | MonitorCmd.swift | Manages the life cycle of the aggregate monitor device. |
spike inspect | InspectCmd.swift | Performs post-recording analysis of audio tracks. |
Sources: Sources/Spike/Doctor.swift:6-60, Sources/Spike/DevicesCmd.swift:7-43, Sources/Spike/InspectCmd.swift:12-42
Audio Device Management ensures seamless integration between macOS hardware and the kilde recording engine. By automating the creation of aggregate devices and managing permissions, it provides a "zero-setup" experience for capturing system audio.