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

> Discover Meetily's crash-resilient incremental audio saver architecture. Learn how it uses checkpoints for automatic recovery and reconstruction, saving memory. Explore the implementation details.

- Repository: [Zackriya Solutions/meetily](https://github.com/Zackriya-Solutions/meetily)
- Tags: architecture
- Published: 2026-07-18

---

**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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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:

```rust
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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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.