Introduction to Kilde
Relevant source files
The following files were used as context for generating this wiki page:
Kilde is an open-source screen and audio recording tool for macOS. It records system audio alongside screen content without complex setup, a feature not natively supported by standard QuickTime Player recordings. The project currently exists in a design and spike phase, providing a CLI-first tool named spike to validate core recording capabilities using ScreenCaptureKit and CoreAudio.
Sources: README.md:1-12, Package.swift:7-11
Core Architecture
Kilde's prototype, spike, utilizes a modular CLI structure to handle different recording scenarios. It leverages macOS native frameworks like ScreenCaptureKit for video and system audio, and CoreAudio for managing hardware devices and aggregate loopbacks.
Recording Flow
The recording process involves initializing a capture session, routing buffers to a writer, and handling process signals to ensure file integrity.
The diagram shows how a CLI command triggers the initialization of the application and capture stream, routing data through a writer until a stop signal triggers finalization.
Sources: Sources/Spike/main.swift:7-8, Sources/Spike/RecSystemCmd.swift:20-56, Sources/Spike/Util.swift:65-75
Key Components
Media Capture Systems
Kilde provides specialized classes to wrap macOS media frameworks:
- SckCapture: Wraps
SCStreamfrom ScreenCaptureKit. It manages the output of screen frames and system audio samples through a unified serial queue. - MicCapture: Uses
AVCaptureSessionto capture audio from microphones or other external input devices. - MonitorDevice: Manages CoreAudio aggregate devices. It creates a "stacked" aggregate device combining the default output and BlackHole for audio loopback.
Sources: Sources/Spike/SckCapture.swift:7-40, Sources/Spike/MicCapture.swift:9-30, Sources/Spike/AggregateDevice.swift:6-24
File Writing and Finalization
The MovieWriter class manages the AVAssetWriter lifecycle. It synchronizes video and audio tracks based on their Presentation Time Stamps (PTS).
| Property | Description |
|---|---|
anchor | Determines if the session starts at the first video or first audio sample. |
videoInput | AVAssetWriterInput for H.264 video. |
audioInputs | A dictionary of inputs for multiple audio tracks (e.g., system, mic). |
sessionStarted | Boolean flag indicating if startSession(at:) has been called. |
Sources: Sources/Spike/MovieWriter.swift:10-55
Command Reference
The spike utility supports several commands for diagnostic and recording tasks.
| Command | Functionality |
|---|---|
doctor | Diagnoses permissions for screen recording and microphone access. |
devices | Lists available displays, windows, and audio devices. |
rec-system | Records the display and system audio (optional --mic support). |
rec-window | Records a specific window based on title or bundle ID matching. |
monitor | Manages aggregate audio devices (status, setup, teardown). |
Sources: Sources/Spike/main.swift:18-40, Sources/Spike/Doctor.swift:8-30
Audio Management
Kilde addresses the limitation of system audio capture by creating aggregate devices. The monitor setup command creates a "kilde Monitor" device that mirrors audio to both the physical output and a loopback driver like BlackHole.
This diagram illustrates the audio routing where system sound is split between physical speakers and the BlackHole driver for capture.
Sources: Sources/Spike/MonitorCmd.swift:44-55, Sources/Spike/AggregateDevice.swift:11-20
Diagnostic Tools
The doctor command validates the environment by checking macOS versions and framework permissions. It specifically verifies CGPreflightScreenCaptureAccess for ScreenCaptureKit and authorization status for AVCaptureDevice audio.
// Example of permission checking in Doctor.swift
let pre = CGPreflightScreenCaptureAccess()
print("[screen] preflight: \(pre)")
if !pre {
let req = CGRequestScreenCaptureAccess()
}
Sources: Sources/Spike/Doctor.swift:12-20
Kilde currently serves as a validation platform for high-performance macOS recording, ensuring safe file finalization even when interrupted via CLI signals. The project plans to evolve from these CLI primitives into a full menu bar application.