MovieWriter Component
Relevant source files
The following files were used as context for generating this wiki page:
The MovieWriter component manages the recording and persistence of audiovisual data to the local file system. It acts as a wrapper for AVAssetWriter, handling the synchronization of video frames and multiple audio tracks (such as system audio and microphone input) into a single container format like .mov or .m4a.
Sources: Sources/Spike/MovieWriter.swift:8-14, Sources/Spike/RecSystemCmd.swift:14-25
Component Architecture
MovieWriter utilizes AVAssetWriterInput instances to process real-time media data. It supports separate inputs for video and multiple labeled audio streams. The component ensures that session timing is anchored to either the first video sample or the first audio sample, depending on the recording mode.
Class Structure and State
The class maintains internal counters and timestamps to track recording progress and health, such as appended and dropped frame counts.
The diagram shows the internal structure of MovieWriter, emphasizing its reliance on AVAssetWriter and its management of multiple inputs.
Sources: Sources/Spike/MovieWriter.swift:10-38
Data Flow and Processing
The component receives CMSampleBuffer objects from capture sources like SckCapture (for screen and system audio) and MicCapture (for microphone audio).
Recording Sequence
When the first valid sample arrives, MovieWriter initiates the writing session. It validates timing information for video frames, correcting invalid durations that often occur in ScreenCaptureKit buffers.
This sequence illustrates the session initialization and the flow of sample buffers from capture sources to the final writer.
Sources: Sources/Spike/MovieWriter.swift:65-115, Sources/Spike/RecSystemCmd.swift:34-48
Media Configuration
The component configures output settings for both video and audio to ensure high-quality, standardized files.
| Media Type | Setting | Value |
|---|---|---|
| Video | Codec | H.264 |
| Bitrate | 12,000,000 bps | |
| Profile | High Auto Level | |
| Audio | Format | MPEG4 AAC |
| Channels | 2 | |
| Sample Rate | 48,000 Hz | |
| Quality | High |
Sources: Sources/Spike/MovieWriter.swift:42-61
Key Implementation Details
Video Timing Correction
MovieWriter includes a static method withValidVideoTiming to handle ScreenCaptureKit (SCK) buffers. If a buffer has an invalid duration, the component re-assigns a default duration of 1/600s to ensure the resulting movie file is playable and has correct timing.
Sources: Sources/Spike/MovieWriter.swift:118-138
Synchronization and Thread Safety
A NSLock instance protects shared state, including sessionStarted, videoAppended, and audioAppended dictionaries. This prevents race conditions when multiple capture queues (e.g., system audio and microphone) attempt to update statistics or check session status simultaneously.
Sources: Sources/Spike/MovieWriter.swift:20-30, Sources/Spike/SckCapture.swift:9-12
Session Finalization
The finish() method marks all inputs as finished and asynchronously waits for AVAssetWriter to complete writing. If the session never started (e.g., no samples were received), it cancels the writer instead of finishing.
Sources: Sources/Spike/MovieWriter.swift:142-157
Diagnostics and Reporting
The component generates structured reports via reportLines(). These reports detail the performance of each track, including:
- Total appended and dropped samples.
- Presentation Time Stamp (PTS) of the first and last samples.
- Offset differences between audio tracks and the video track to diagnose synchronization issues.
Sources: Sources/Spike/MovieWriter.swift:165-184, Sources/Spike/InspectCmd.swift:33-47
Conclusion
The MovieWriter component provides a robust interface for recording synchronized media. By abstracting AVAssetWriter complexities and handling specific macOS media capture quirks—such as SCK timing issues and multi-track synchronization—it ensures reliable file output for the Kilde project.