Meetily's Incremental Audio Saver and Checkpoint System: Architecture and Implementation

Meetily implements a crash-resilient incremental audio saver that persists PCM chunks to temporary checkpoint files in a hidden .checkpoints/ directory, enabling automatic recovery and reconstruction of the final recording without consuming memory for the entire audio stream.

The open-source meeting assistant Zackriya-Solutions/meetily uses a Rust-based audio pipeline in its Tauri frontend to handle real-time recording. The incremental audio saver and checkpoint system ensures that even if the application crashes mid-recording, no audio data is lost by periodically flushing buffers to disk as recoverable segments.

Core Architecture Components

IncrementalAudioSaver Struct

Located in frontend/src-tauri/src/audio/incremental_saver.rs, this struct manages the stateful writing process. It encapsulates the meeting folder path, sample rate (typically 48,000 Hz), and the current file handle for the working audio stream. The struct provides the primary interface for chunk ingestion and checkpoint generation.

Checkpoint Directory Structure

The system creates a .checkpoints/ subdirectory inside the active meeting folder. This directory stores partial audio fragments (e.g., segment_001.wav) that serve as atomic save points during the recording session. Each checkpoint represents a complete, valid audio segment that can be independently decoded.

Recovery and Cleanup Functions

Exposed in frontend/src-tauri/src/lib.rs (lines 620–622), the functions recover_audio_from_checkpoints and cleanup_checkpoints handle post-crash restoration and disk cleanup. The has_audio_checkpoints utility detects whether an interrupted session exists before attempting recovery.

RecordingSaver Integration

The RecordingSaver struct in frontend/src-tauri/src/audio/recording_saver.rs wraps the saver in an Arc<AsyncMutex<IncrementalAudioSaver>>, providing thread-safe access across the async audio capture pipeline. This wrapper manages the saver lifecycle from initialization through finalization.

How the Checkpoint System Works

1. Initialization – When a meeting starts, IncrementalAudioSaver::new creates the meeting folder and the .checkpoints/ directory, preparing the PCM stream parameters.

2. Chunk Processing – Incoming audio frames pass through save_chunk, which appends data to a temporary buffer. After a configurable interval or frame count, the buffer flushes to a new numbered segment file in .checkpoints/.

3. Crash Recovery – On application restart, recover_audio_from_checkpoints scans the checkpoint directory, concatenates segments chronologically, and reconstructs the final audio.wav file.

4. Finalization – Upon graceful stop, finalize writes any remaining buffered data, and cleanup_checkpoints deletes the temporary segment files to reclaim disk space.

Implementation Details and Code Examples

The following Rust code demonstrates the three-phase lifecycle of the incremental saver:

use std::path::PathBuf;
use std::sync::Arc;
use tauri::async_runtime::Mutex as AsyncMutex;

// Phase 1: Initialization
fn start_meeting_recording(meeting_folder: PathBuf) -> Result<Arc<AsyncMutex<IncrementalAudioSaver>>, Box<dyn std::error::Error>> {
    let sample_rate = 48_000;
    let saver = IncrementalAudioSaver::new(meeting_folder, sample_rate)?;
    Ok(Arc::new(AsyncMutex::new(saver)))
}

// Phase 2: Real-time chunk handling
async fn process_audio_chunk(
    chunk: Vec<u8>, 
    saver: Arc<AsyncMutex<IncrementalAudioSaver>>
) -> Result<(), Box<dyn std::error::Error>> {
    let mut guard = saver.lock().await;
    guard.save_chunk(&chunk)?; // Writes to current buffer, creates checkpoints periodically
    Ok(())
}

// Phase 3: Finalization and cleanup
async fn stop_and_finalize(
    saver: Arc<AsyncMutex<IncrementalAudioSaver>>
) -> Result<(), Box<dyn std::error::Error>> {
    let mut guard = saver.lock().await;
    guard.finalize()?;          // Flush remaining bytes to final file
    guard.cleanup_checkpoints()?; // Remove .checkpoints/ directory
    Ok(())
}

Key method signatures in incremental_saver.rs:

• pub fn new(meeting_folder: PathBuf, sample_rate: u32) -> Result<Self>
• pub fn save_chunk(&mut self, data: &[u8]) -> Result<()>
• pub fn finalize(&mut self) -> Result<()>
• pub fn cleanup_checkpoints(&self) -> Result<()>

Summary

• The IncrementalAudioSaver struct in incremental_saver.rs provides the core checkpoint persistence logic for Meetily's audio pipeline.
• Audio data streams to disk in atomic segments within a .checkpoints/ directory, ensuring crash resilience without memory bloat.
• Recovery functions in lib.rs enable automatic reconstruction of interrupted recordings by concatenating checkpoint segments.
• The RecordingSaver wrapper manages thread-safe access and lifecycle transitions across the async recording boundary.

Frequently Asked Questions

How does Meetily recover audio after an application crash?

On restart, Meetily calls recover_audio_from_checkpoints from frontend/src-tauri/src/lib.rs. This function scans the .checkpoints/ directory inside the meeting folder, reads all segment files in chronological order, and concatenates them into a single valid WAV file before resuming normal operations.

What is the storage overhead of the checkpoint system?

The checkpoint system maintains temporary segment files equal to the total recording size until finalization. During active recording, disk usage roughly doubles because data exists in both the checkpoint fragments and the working buffer. After cleanup_checkpoints runs, only the final merged audio file remains.

Why does Meetily use IncrementalAudioSaver instead of writing directly to the final file?

Writing directly to the final file risks corruption if the process terminates mid-write. By using IncrementalAudioSaver to create periodic atomic checkpoints, Meetily ensures that completed segments are already persisted to disk. This allows recover_audio_from_checkpoints to reconstruct the recording up to the last successful checkpoint rather than losing the entire session.

Where is the checkpoint interval configured?

The checkpoint interval logic resides in frontend/src-tauri/src/audio/incremental_saver.rs. While the implementation flushes buffers based on internal thresholds within the save_chunk method, the specific frame count or time interval is hardcoded to balance disk I/O overhead against data safety margins.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}