Command: Diagnostic Doctor
Relevant source files
The following files were used as context for generating this wiki page:
The doctor command serves as the primary environmental and diagnostic tool for the kilde project. It evaluates the host system's readiness for screen and audio recording by checking necessary macOS permissions, listing available hardware, and identifying software dependencies like BlackHole.
This command is typically the first step for users to ensure their environment is correctly configured before attempting complex recording tasks like rec-system or rec-window. It reports on the status of ScreenCaptureKit (SCK) access, microphone authorization, and CoreAudio device availability.
Diagnostic Flow and Components
The doctor command executes a series of checks sequentially to validate the recording pipeline. It interacts with several macOS frameworks including CoreGraphics, AVFoundation, and ScreenCaptureKit.
The diagram shows the sequential execution of diagnostic checks within the Doctor.swift struct.
Sources: Sources/Spike/Doctor.swift:8-61, Sources/Spike/main.swift:14
System and Permission Verification
The tool first identifies the macOS version and checks for Screen Capture access via CGPreflightScreenCaptureAccess(). If access is missing, it triggers a system request using CGRequestScreenCaptureAccess().
Sources: Sources/Spike/Doctor.swift:10-20
For audio, the command checks AVCaptureDevice.authorizationStatus(for: .audio). It handles four states: authorized, denied, restricted, and notDetermined. If the status is notDetermined, it initiates a permission request.
Sources: Sources/Spike/Doctor.swift:23-33, Sources/Spike/MicCapture.swift:45-62
Hardware and Resource Enumeration
The doctor command retrieves and displays counts for the following resources to verify that the ScreenCaptureKit and CoreAudio subsystems are operational:
| Category | Source Framework | Information Displayed |
|---|---|---|
| Screen Content | ScreenCaptureKit | Number of displays, windows, and applications. |
| Displays | ScreenCaptureKit | Width, height, and displayID for each display. |
| CoreAudio | CoreAudio (HAL) | Total device count, default input/output names. |
| Loopback | CoreAudio (HAL) | Presence of "BlackHole" devices, including channel counts. |
| AVCapture | AVFoundation | UniqueIDs and localized names of audio devices. |
Sources: Sources/Spike/Doctor.swift:36-61, Sources/Spike/AudioDevices.swift:27-58
Integration and Usage
The doctor command is integrated into the main spike CLI utility. It is also used as a prerequisite in automated integration tests to ensure the test environment has the required permissions before running recording scenarios.
This sequence illustrates the interaction between the doctor command and the underlying hardware abstraction layers.
Sources: Sources/Spike/main.swift:14, Sources/Spike/Doctor.swift:36-50, Sources/Spike/AudioDevices.swift:27-31
Key Logic for Audio Diagnosis
The doctor command utilizes the AudioHAL helper to inspect the system's audio state. It specifically looks for "BlackHole" devices, which are essential for system audio loopback in certain recording modes.
// Example of BlackHole detection logic used by doctor
let bh = devices.filter { $0.isBlackHole }
if bh.isEmpty {
print("[coreaudio] BlackHole: 未検出 (brew install --cask blackhole-2ch)")
} else {
for d in bh {
print(" blackhole: \"\(d.name)\" in=\(d.inputChannels) out=\(d.outputChannels)")
}
}
Sources: Sources/Spike/Doctor.swift:53-59, Sources/Spike/AudioDevices.swift:13-15
Summary
The Command: Diagnostic Doctor is a critical utility for verifying the complex permission and hardware requirements of the kilde project. By aggregating checks for ScreenCaptureKit, CoreAudio, and AVFoundation in one location, it allows developers and users to quickly identify why recording features might fail due to system-level restrictions or missing drivers.