Command: Inspect Targets
Relevant source files
The following files were used as context for generating this wiki page:
InspectCmd analyzes recording files to verify track composition, video dimensions, and audio levels. It serves as a diagnostic and validation tool, providing machine-readable output for integration tests to confirm that captured media contains valid data.
The command operates by loading media assets via AVFoundation, extracting metadata from video tracks, and decoding audio tracks to calculate Root Mean Square (RMS) and peak volume levels.
Sources: Sources/Spike/InspectCmd.swift:10-15, Sources/Spike/main.swift:23, scripts/integration-test.sh:35-37
Command Execution Flow
When you run spike inspect <file>, the system performs a sequential analysis of the target file. It first validates the file's existence on the disk before initiating an asynchronous inspection process.
The diagram shows the logical progression from user input to the final calculation of audio metrics.
Sources: Sources/Spike/InspectCmd.swift:18-32, Sources/Spike/Util.swift:96-105
Audio Analysis Logic
The analyzeAudioTrack function performs the core technical evaluation of audio quality. It uses an AVAssetReader to convert compressed audio tracks into Linear PCM format (32-bit float). The system then iterates through every sample to determine signal strength.
Metrics Calculation
- RMS (Root Mean Square): Represents the average power of the audio signal. Calculated as
sqrt(sum(sample^2) / count). - Peak: Represents the highest absolute value found in the sample buffer.
The sequence diagram illustrates the buffer-by-buffer processing of audio data required to generate volume statistics.
Sources: Sources/Spike/Util.swift:96-126
Integration and Usage
The inspect command provides specific outputs used by the integration-test.sh script to automate quality assurance. The script parses the output strings to ensure that recordings are not silent and have the correct duration.
Output Format Specification
| Field | Description | Example |
|---|---|---|
video | Presence and resolution of video track | present 2560x1440 |
duration | Total length of the track in seconds | duration=8.08s |
rms | Root Mean Square value of the audio | rms=0.0873 |
peak | Maximum absolute amplitude detected | peak=0.6100 |
Sources: Sources/Spike/InspectCmd.swift:10-13, scripts/integration-test.sh:39-55
Validation in Tests
The integration test suite uses the following logic to determine a "Pass" state:
- Extracts the
rmsvalue usinggrepandawk. - Compares the value against a threshold (typically
0.005). - Verifies the
videostatus ispresentfor video-enabled commands. - Ensures track counts (e.g.,
audio[0],audio[1]) match expected configurations.
Sources: scripts/integration-test.sh:43-52, Sources/Spike/RecSystemCmd.swift:65-75
Core Utility Integration
InspectCmd relies on shared utilities within the spike toolset to handle synchronous execution and file attribute retrieval.
- awaitSync: Wraps Swift Concurrency
asynccalls into synchronous blocks for CLI compatibility. - fileSizeString: Formats the raw byte count of the target file into a human-readable string (e.g., KB, MB).
- SpikeError: Provides a standardized error reporting mechanism when inspection fails.
Sources: Sources/Spike/Util.swift:20-35, Sources/Spike/Util.swift:61-64
The inspect command is essential for confirming that the SCK (ScreenCaptureKit) and AVFoundation pipelines successfully wrote data to the disk, especially when verifying complex setups like multi-track recording or window-scoped audio capture.
Sources: Sources/Spike/InspectCmd.swift:42-50, scripts/integration-test.sh:105-112