Utility Functions
Relevant source files
The following files were used as context for generating this wiki page:
Utility functions in the kilde project provide essential cross-cutting concerns including command-line argument parsing, asynchronous synchronization, audio analysis, and system signal handling. These functions support the spike tool, which validates screen and audio recording capabilities before they are integrated into the main Kilde application.
The utilities facilitate complex operations such as bridging Swift's concurrency model with synchronous execution, extracting audio metrics (RMS and Peak) from recorded files, and managing Unix signals for safe file finalization.
Core Execution Utilities
The project uses specialized structures and functions to manage CLI input and synchronize asynchronous tasks.
Synchronous Execution Wrapper
The awaitSync function executes an asynchronous block and waits for its completion using a DispatchSemaphore. This allows the CLI to call async functions within a synchronous context.
The diagram shows how awaitSync bridges asynchronous tasks to synchronous calls.
Sources: Sources/Spike/Util.swift:21-36
Argument Parsing
The Args struct parses command-line inputs. It identifies flags, retrieves option values, and filters bare arguments.
| Method | Description |
|---|---|
flag(_ name: String) | Returns true if the argument list contains the specified string. |
option(_ name: String) | Returns the string immediately following the specified option key. |
bare | Returns all arguments that do not start with a hyphen -. |
Sources: Sources/Spike/Util.swift:38-47
Audio Analysis Utilities
The system provides functions to analyze the content of recorded audio files to verify capture success.
Metric Calculation
The analyzeAudioTrack function decodes an AVAssetTrack into Linear PCM format to calculate Root Mean Square (RMS) and Peak amplitude levels. This verification ensures that recording sessions actually captured sound rather than silence.
| Statistic | Description | Calculation Logic |
|---|---|---|
| RMS | Average power of the audio signal. | sqrt(sum(v^2) / count) |
| Peak | Maximum absolute amplitude. | max(peak, abs(d)) |
| Duration | Length of the track in seconds. | Derived from AVAsset.load(.duration) |
Sources: Sources/Spike/Util.swift:81-119, Sources/Spike/InspectCmd.swift:30-51
Data Flow for Audio Inspection
The following sequence describes how the inspect command utilizes analysis utilities.
System and Media Utilities
Signal Handling
The installStopSignalHandler function intercepts SIGINT (Ctrl+C) and SIGTERM. It uses DispatchSourceSignal to trigger a cleanup handler, ensuring MovieWriter can finalize files before the process exits.
Sources: Sources/Spike/Util.swift:65-77
Time and Duration Parsing
The parseDuration function converts user-supplied strings (e.g., "10s", "5m", "1h") into TimeInterval values. If the string ends with "m", it multiplies the value by 60; if "h", by 3600. The default duration is 6 seconds.
Sources: Sources/Spike/Util.swift:49-56
Media Timing Correction
The MovieWriter.withValidVideoTiming function ensures CMSampleBuffer objects from ScreenCaptureKit (SCK) have valid durations. If a buffer lacks numeric duration, the utility creates a new buffer with a fixed timing of 1/600s.
Sources: Sources/Spike/MovieWriter.swift:125-146
Audio Hardware Inspection
The AudioHAL utility provides a high-level interface to the CoreAudio Hardware Abstraction Layer.
| Property | File | Description |
|---|---|---|
devices | AudioDevices.swift | Lists all AudioDeviceInfo objects via kAudioHardwarePropertyDevices. |
defaultOutput | AudioDevices.swift | Retrieves the current system default output device. |
streamChannels | AudioDevices.swift | Calculates channel counts by inspecting AudioBufferList buffers. |
Sources: Sources/Spike/AudioDevices.swift:32-90
Conclusion
The utility functions in Kilde form a robust foundation for media capture validation. By abstracting CoreAudio, AVFoundation, and Unix signal complexities into reusable helpers like awaitSync, analyzeAudioTrack, and installStopSignalHandler, the project ensures that recording sessions are reliably started, monitored, and finalized.