Aggregate Audio Devices
Relevant source files
The following files were used as context for generating this wiki page:
Aggregate Audio Devices in the kilde project provide a mechanism to combine multiple physical or virtual audio interfaces into a single logical device. This system primarily enables loopback recording by combining the system's default output with a virtual driver like BlackHole. By setting this aggregate device as the system default, the project ensures that audio signals are simultaneously routed to physical speakers and the recording buffer.
The implementation relies on the CoreAudio HAL (Hardware Abstraction Layer) to manage device life cycles and system-wide default settings. It specifically targets "Multi-Output" configurations to support real-time monitoring while capturing system audio.
Architecture and Device Management
The system manages aggregate devices through the MonitorDevice enum and the AudioHAL utility. It creates a specific aggregate device named "kilde Monitor (spike)" with a static UID kilde-spike-monitor-001.
Component Interaction
The following diagram illustrates how the MonitorCmd interacts with CoreAudio to establish the aggregate device.
Device Configuration Keys
When creating the aggregate device, the system uses specific dictionary keys to configure the behavior:
| Key | Value / Purpose |
|---|---|
kAudioAggregateDeviceNameKey | "kilde Monitor (spike)" |
kAudioAggregateDeviceUIDKey | "kilde-spike-monitor-001" |
stacked | true (Enables simultaneous output to all sub-devices) |
kAudioAggregateDeviceSubDeviceListKey | List of UIDs (e.g., Speakers + BlackHole) |
kAudioAggregateDeviceMasterSubDeviceKey | The UID of the device providing the master clock |
Sources: Sources/Spike/AggregateDevice.swift:11-23
CoreAudio Integration (AudioHAL)
The AudioHAL enum provides a technical interface to the macOS CoreAudio hardware. It queries the kAudioObjectSystemObject to enumerate available devices and identify their capabilities based on channel counts.
Audio Device Classification
Devices are classified by their input and output stream configurations:
- Input: Devices with
inputChannels > 0. - Output: Devices with
outputChannels > 0. - BlackHole: Identified by the string "BlackHole" in the device name, used for loopback.
- Aggregate: Logic-based devices that combine multiple hardware UIDs.
Sources: Sources/Spike/AudioDevices.swift:7-21, Sources/Spike/AudioDevices.swift:80-101
Property Access Logic
The system retrieves device information using AudioObjectGetPropertyData. It targets specific selectors to extract names, UIDs, and stream configurations.
Setup and Teardown Procedures
The project includes a command-line interface via MonitorCmd to manage the lifecycle of the aggregate device.
Setup Process
- Detection: The system identifies the current
defaultOutputand searches for aBlackHoledevice. - Creation: It calls
AudioHardwareCreateAggregateDevicewith the "stacked" flag set to true. - Persistence: The original default output UID is saved to
~/.kilde_spike_monitor.json. - Activation: The new aggregate device is set as the system's default output.
Sources: Sources/Spike/MonitorCmd.swift:46-68
Teardown Process
- Recovery: The system reads the saved state file to identify the
originalDefaultOutputUID. - Restoration: It sets the system default output back to the original hardware device.
- Destruction: It calls
AudioHardwareDestroyAggregateDeviceto remove the "kilde Monitor" device. - Cleanup: The state file is deleted.
Sources: Sources/Spike/MonitorCmd.swift:72-85, Sources/Spike/AggregateDevice.swift:31-34
Validation and Diagnostics
The Doctor and RecDeviceCmd modules provide tools to verify the aggregate device state.
- Doctor: Lists all CoreAudio devices and flags the presence of BlackHole and the current default output.
- RecDeviceCmd: Allows for direct recording from a specific device UID, which is used to verify that audio is successfully looping through the BlackHole component of the aggregate device.
Sources: Sources/Spike/Doctor.swift:47-56, Sources/Spike/RecDeviceCmd.swift:15-23
Aggregate Audio Devices enable kilde to capture system audio without muting the user's speakers by creating a parallel routing path through a virtual loopback driver. This configuration is essential for seamless system-wide audio recording on macOS.