Command: Record Window
Relevant source files
The following files were used as context for generating this wiki page:
The rec-window command provides functionality to record a specific application window and its associated audio. It leverages Apple's ScreenCaptureKit (SCK) to perform high-performance window-level capture while maintaining audio scope isolation, ensuring that only audio from the targeted application is recorded.
Sources: Sources/Spike/RecWindowCmd.swift:9-11, README.md:9-12
Architecture and Execution Flow
The command execution follows a structured pipeline that includes permission validation, window discovery, stream configuration, and a managed recording session.
Execution Sequence
The following diagram illustrates the lifecycle of a rec-window execution:
The sequence shows how the command transitions from user input to the finalization of the media file.
Sources: Sources/Spike/main.swift:20, Sources/Spike/RecWindowCmd.swift:15-68, Sources/Spike/RecSystemCmd.swift:14-61
Logic Components
Window Selection Logic
RecWindowCmd retrieves all on-screen windows that belong to an application. It filters this list based on the --match argument provided by the user. The matching logic performs a case-insensitive search against both the window title and the application's bundle identifier.
Sources: Sources/Spike/RecWindowCmd.swift:26-52
Configuration Parameters
The command defines specific technical requirements for the SCStreamConfiguration and the resulting media file:
| Parameter | Value / Implementation | Source |
|---|---|---|
| Video Resolution | Matched to window frame width/height | RecWindowCmd.swift:55-56 |
| Pixel Format | 32BGRA (Non-compressed for AVAssetWriter) | RecSystemCmd.swift:34 |
| Audio Sample Rate | 48000 Hz | RecWindowCmd.swift:58 |
| Audio Channels | 2 (Stereo) | RecWindowCmd.swift:59 |
| Capture Filter | SCContentFilter(desktopIndependentWindow: win) | RecWindowCmd.swift:60 |
| Audio Scope | Application-specific (Isolated) | RecWindowCmd.swift:80-81 |
Stream and Output Management
The command utilizes SckCapture to manage the SCStream and route buffers to MovieWriter.
- SckCapture: Attaches to the
SCStreamand receivesCMSampleBufferobjects. It filters out incomplete or invalid frames (e.g.,.blankor.idlestatuses) before passing them to the sink. - MovieWriter: Handles the
AVAssetWritersession. It uses the first received video frame's Presentation Time Stamp (PTS) as the session anchor to ensure synchronization. - Graceful Shutdown: The system installs signal handlers for
SIGINTandSIGTERM. When a signal is received, the session stops the capture stream and callsfinish()on theAVAssetWriterto ensure the resulting.movfile is valid and playable.
Sources: Sources/Spike/SckCapture.swift:11-54, Sources/Spike/MovieWriter.swift:85-132, Sources/Spike/Util.swift:62-75
Implementation Details
Window Filtering Code
let content = try awaitSync { try await SCShareableContent.current }
let wins = content.windows.filter { $0.isOnScreen && $0.owningApplication != nil }
guard let win = wins.first(where: {
($0.title ?? "").localizedCaseInsensitiveContains(match) ||
($0.owningApplication?.bundleIdentifier ?? "").localizedCaseInsensitiveContains(match)
}) else {
fail("\"\(match)\" にマッチするウィンドウがありません")
}
Sources: Sources/Spike/RecWindowCmd.swift:30-48
Capture Loop Flow
The flowchart visualizes the data flow from the initial permission check through the sample buffer processing loop.
Sources: Sources/Spike/RecWindowCmd.swift:15-68, Sources/Spike/RecSystemCmd.swift:14-61
Conclusion
The rec-window command serves as a critical verification tool for the kilde project, specifically for testing window-level capture and application-scoped audio isolation. By integrating ScreenCaptureKit for capture and AVFoundation for writing, it ensures high-quality recordings with precise synchronization.
Sources: Sources/Spike/RecWindowCmd.swift:9-13, Sources/Spike/main.swift:42-43