Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Kilde is a macOS recording tool that captures screen content and system audio. It uses a Command Line Interface (CLI) to execute specialized recording tasks, leveraging native macOS frameworks like ScreenCaptureKit, AVFoundation, and CoreAudio. Sources: README.md:3-8, Sources/Spike/main.swift:15-22
The architecture centers on a capture-and-muxing pipeline. Specialized capture classes retrieve raw sample buffers from the system, which a central writer then serializes into media files. The system also manages audio hardware configurations to enable loopback recording via virtual devices. Sources: Sources/Spike/SckCapture.swift:6-10, Sources/Spike/MovieWriter.swift:8-12
Core System Components
The project divides functionality into capture drivers, output management, and hardware utility modules.
Component Summary Table
| Component | Responsibility | Relevant Files |
|---|---|---|
| CLI Entry Point | Initializes the NSApplication as an accessory and routes commands. | main.swift |
| SckCapture | Manages SCStream for screen and system audio acquisition. | SckCapture.swift |
| MicCapture | Captures audio from physical or virtual input devices via AVCaptureSession. | MicCapture.swift |
| MovieWriter | Muxes video and multiple audio tracks into .mov or .m4a files. | MovieWriter.swift |
| AudioHAL | Interfaces with CoreAudio to query and manipulate hardware device states. | AudioDevices.swift |
| MonitorDevice | Creates and destroys Aggregate Devices for audio loopback. | AggregateDevice.swift |
Sources: Sources/Spike/main.swift:6-13, Sources/Spike/SckCapture.swift:6-26, Sources/Spike/MovieWriter.swift:8-66, Sources/Spike/AudioDevices.swift:30-45, Sources/Spike/AggregateDevice.swift:6-26
Recording Pipeline and Data Flow
Recording sessions coordinate multiple asynchronous streams. The runRecordingSession function initializes the MovieWriter and starts simultaneous captures for screen and audio.
The diagram shows the flow of media data from system capture interfaces to the final file output. Sources: Sources/Spike/RecSystemCmd.swift:13-52
Sample Handling
- SckCapture receives
CMSampleBufferobjects fromSCStreamOutput. It filters for complete frames before passing them to the sink. Sources: Sources/Spike/SckCapture.swift:42-53 - MovieWriter uses an anchor system (
.firstVideoor.firstAudio) to establish the session start time based on the first arriving sample. Sources: Sources/Spike/MovieWriter.swift:70-105 - AVAssetWriter performs the final encoding (H.264 for video, AAC for audio). Sources: Sources/Spike/MovieWriter.swift:34-62
Audio Infrastructure
Kilde manages system audio by interacting with the CoreAudio Hardware Abstraction Layer (HAL). It supports standard ScreenCaptureKit audio capture and a "Monitor" mode using Aggregate Devices.
Audio Device Management
The AudioHAL module queries the system for device IDs, UIDs, and channel counts. It identifies "BlackHole" loopback drivers to facilitate system audio routing. Sources: Sources/Spike/AudioDevices.swift:30-50
Aggregate Device Architecture
To record system audio alongside physical speakers, Kilde creates a "stacked" Aggregate Device. This device combines the current default output with a BlackHole loopback driver.
The diagram illustrates how the Aggregate Device duplicates system audio to both physical hardware and the loopback driver. Sources: Sources/Spike/AggregateDevice.swift:10-25
Graceful Termination and Signal Handling
The system ensures file integrity by intercepting termination signals. The installStopSignalHandler function catches SIGINT (Ctrl+C) and SIGTERM. When a signal is received, the recording session stops capture inputs first and then calls writer.finish() to close the file containers correctly. Sources: Sources/Spike/Util.swift:60-72, Sources/Spike/RecSystemCmd.swift:45-52
Execution Environment
The CLI must initialize as an accessory application to avoid crashes during ScreenCaptureKit initialization. This allows the process to interact with the WindowServer without a standard GUI window. Sources: Sources/Spike/main.swift:6-9
// Sources/Spike/main.swift:7-8
let nsApp = NSApplication.shared
nsApp.setActivationPolicy(.accessory)
Summary
The Kilde architecture provides a robust framework for macOS recording by decoupling capture logic from file serialization. By leveraging ScreenCaptureKit for high-performance screen and system audio acquisition, and supplementing it with CoreAudio for advanced routing via Aggregate Devices, the system achieves complex recording tasks through a simple CLI interface. The inclusion of signal handling and non-blocking session management ensures that output files remain valid even during unexpected interruptions.