Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
kilde (specifically the spike tool) records macOS screen content and system audio natively using ScreenCaptureKit. This guide provides instructions for setting up the environment, discovering devices, and executing recording commands to verify audio and video capture functionality.
Environment Preparation
You must grant necessary permissions before recording. The spike doctor command diagnoses the environment and requests access for screen recording and microphone usage.
- Build the project using
swift build. - Run
.build/debug/spike doctorto check status. - Follow system prompts to allow "Screen Recording" and "Microphone" access if requested.
Sources: README.md:14-17, Sources/Spike/Doctor.swift:8-30, scripts/integration-test.sh:84-93
The diagram shows the prerequisite flow to ensure the macOS environment allows kilde to capture screen and audio data.
Device Discovery
Before recording, identify the available displays, windows, and audio devices. The devices command lists all shareable content and CoreAudio interfaces.
- Displays: Listed with
displayID. - Windows: Listed with
windowID, application name, and title. - Audio Devices: Shows IDs, UIDs, and channel counts (input/output).
Sources: Sources/Spike/main.swift:18, Sources/Spike/DevicesCmd.swift:7-40
| Command | Output Type | Key Information |
|---|---|---|
spike devices | Displays | Resolution, displayID |
spike devices | Windows | windowID, BundleID, Title, Frame Size |
spike devices | Audio | Device ID, UID, Input/Output channels, BlackHole status |
Recording Commands
kilde provides specific commands for different recording scenarios. Each command supports duration and output path customization.
Basic Screen and System Audio
The rec-system command captures a physical display and the system audio stream.
# Record display 0 for 10 seconds with system audio
spike rec-system --display 0 --duration 10s --output demo.mov
# Record display 0 and include a separate track for the microphone
spike rec-system --mic --output session_with_mic.mov
Sources: Sources/Spike/main.swift:20-25, Sources/Spike/RecSystemCmd.swift:86-118
Window-Specific Recording
The rec-window command limits capture to a specific application window. It uses a --match flag to filter by window title or bundle identifier.
# Record a window matching "Safari"
spike rec-window --match Safari --duration 5s
Sources: Sources/Spike/RecWindowCmd.swift:14-55
Audio-Only Recording
The rec-audio-only command captures system audio into an M4A container without video tracks.
Sources: Sources/Spike/main.swift:26-28, Sources/Spike/RecAudioOnlyCmd.swift:12-65
Result Verification
After recording, verify the integrity of the output file. The inspect command analyzes the file structure and measures audio levels (RMS and Peak) to confirm audio was successfully captured.
spike inspect demo.mov
The output confirms:
- Video: Presence, resolution, and duration.
- Audio Tracks: Duration, Root Mean Square (RMS) level, and Peak level.
Sources: Sources/Spike/InspectCmd.swift:12-45, Sources/Spike/Util.swift:101-140
The sequence diagram illustrates the lifecycle of a recording session from initiation to post-capture verification.
Summary of Options
Common flags available across recording commands:
| Flag | Description | Default |
|---|---|---|
--duration <N> | Duration of recording (s, m, h) | 6s |
--output <path> | Destination file path | Timestamped filename |
--mic | Enables microphone capture (rec-system only) | Disabled |
--match <text> | Filter window by title/bundleID | N/A |
Sources: Sources/Spike/Util.swift:42-53, Sources/Spike/main.swift:20-33