How Meetily Ensures Data Integrity with Incremental Audio Saving and Checkpoints

Meetily guarantees no audio is lost during recording by writing independent MP4 checkpoints to disk every 30 seconds and stitching them losslessly on finalization, enabling full crash recovery even if the application terminates unexpectedly.

Meetily, an open-source meeting assistant from Zackriya-Solutions, implements a fault-tolerant audio pipeline that ensures data integrity through incremental on-disk persistence. Instead of buffering entire recordings in volatile memory, the application uses the IncrementalAudioSaver module to continuously serialize audio chunks, creating recoverable checkpoints that survive crashes, power failures, or abrupt process termination.

The Risk of In-Memory Recording

Traditional audio recording applications often buffer complete streams in RAM before writing to disk, risking total data loss if the process crashes before the final save. Meetily eliminates this single point of failure by treating the recording as a sequence of discrete, independently verifiable segments.

Core Architecture: The IncrementalAudioSaver

The IncrementalAudioSaver struct in frontend/src-tauri/src/audio/incremental_saver.rs orchestrates the entire incremental saving strategy. It manages internal state through a checkpoint_buffer that accumulates incoming audio samples until reaching a predefined threshold.

Chunk-Based Buffering with AudioData

Every incoming AudioChunk from the capture pipeline is wrapped in an internal AudioData struct and appended to the checkpoint_buffer. This design ensures that raw audio data is never held in transient memory structures longer than necessary.

Time-Based Checkpoint Thresholds

The saver is configured with a checkpoint interval of 30 seconds. At a sample rate of 48 kHz, this translates to exactly 1,440,000 samples per checkpoint. When the accumulated samples in checkpoint_buffer reach this threshold, the system automatically triggers a disk write operation.

Creating On-Disk Checkpoints

When the buffer threshold is met, the save_checkpoint() method executes a critical sequence:

1. Concatenation: Aggregates all buffered samples into a contiguous audio segment
2. Encoding: Calls encode_single_audio (FFmpeg-based) to produce a valid MP4 container
3. Persistence: Writes the file as audio_chunk_###.mp4 into a hidden .checkpoints directory within the meeting folder

Each checkpoint file is a complete, independently decodable MP4. This means that even if the application crashes immediately after a checkpoint completes, that 30-second segment remains fully playable and intact on disk.

// Create a saver for a new meeting (meeting_folder already exists)
let mut saver = IncrementalAudioSaver::new(meeting_folder, 48_000)?;

// Feed audio chunks as they arrive (e.g., from the pipeline)
saver.add_chunk(audio_chunk)?;   // every call may trigger a checkpoint

// When the user stops recording
let final_path = saver.finalize().await?;   // merges checkpoints → audio.mp4
println!("Saved full recording at {}", final_path.display());

Crash Recovery with recover_audio_from_checkpoints

If the application terminates abnormally before finalize() completes, the checkpoint files persist in the .checkpoints directory. The recover_audio_from_checkpoints command, exposed through frontend/src-tauri/src/audio/recording_commands.rs, enables complete reconstruction:

1. Scanning: Discovers all audio_chunk_###.mp4 files in the .checkpoints folder
2. Validation: Builds an FFmpeg concat list and verifies segment integrity
3. Reconstruction: Stitches available checkpoints into a final audio.mp4
4. Reporting: Returns an AudioRecoveryStatus struct indicating success, estimated duration, or failure messages

// Recover after a crash (called from the frontend)
let status = recover_audio_from_checkpoints(
    meeting_folder.to_string(),
    48_000,
).await?;

match status.status.as_str() {
    "success" => println!("Recovered {} s of audio", status.estimated_duration_seconds),
    "failed"  => eprintln!("Recovery failed: {}", status.message),
    _         => println!("No checkpoints to recover"),
}

Lossless Finalization and Cleanup

When recording stops normally, the finalize() method executes a safe shutdown sequence:

1. Buffer Flush: Writes any remaining samples in checkpoint_buffer to a final partial checkpoint
2. Lossless Merge: Calls merge_checkpoints() utilizing the FFmpeg concat demuxer with the -c copy flag, ensuring checkpoints are stitched together without re-encoding and preserving original audio data exactly
3. Cleanup: Executes cleanup_checkpoints to remove the temporary .checkpoints directory, maintaining a tidy meeting folder

This concatenation approach guarantees bit-perfect fidelity because it copies codec streams directly rather than decoding and re-encoding, which would introduce generational quality loss.

Integration Across the Audio Pipeline

The incremental saving system integrates with several components defined in the Tauri backend:

• frontend/src-tauri/src/audio/recording_manager.rs: Orchestrates the audio pipeline and forwards raw AudioChunk data to the IncrementalAudioSaver
• frontend/src-tauri/src/audio/ffmpeg.rs: Locates the FFmpeg binary used for encoding single checkpoints and concatenating final outputs
• frontend/src-tauri/src/audio/recording_commands.rs: Exposes Tauri command bindings for finalize, recover_audio_from_checkpoints, and cleanup_checkpoints to the frontend application
• frontend/src-tauri/src/audio/recording_state.rs: Defines the AudioChunk struct and device-type metadata consumed throughout the saver

Summary

• IncrementalAudioSaver in frontend/src-tauri/src/audio/incremental_saver.rs manages continuous audio persistence without holding entire recordings in memory.
• 30-second checkpoints (1,440,000 samples at 48 kHz) are written as independent MP4 files to a hidden .checkpoints directory.
• Crash recovery is handled by recover_audio_from_checkpoints, which scans, validates, and reconstructs audio from remaining checkpoint files.
• Lossless finalization uses FFmpeg's concat demuxer with -c copy to merge checkpoints without re-encoding, preserving original audio quality exactly.
• Automatic cleanup removes temporary checkpoint files after successful merge or recovery, ensuring the meeting folder contains only the final audio.mp4.

Frequently Asked Questions

What happens if Meetily crashes during a recording?

If Meetily crashes, all completed 30-second checkpoints remain safely stored on disk in the .checkpoints directory. Only the audio recorded since the last checkpoint (maximum 30 seconds) is lost. The recover_audio_from_checkpoints command can reconstruct the final recording from these persistent segments when the application restarts.

Why does Meetily use 30-second intervals for checkpoints?

The 30-second interval balances data safety with storage efficiency. At 48 kHz sampling rate, this creates manageable 1,440,000-sample chunks that minimize memory pressure while ensuring that a crash loses no more than half a minute of audio. This frequency also prevents excessive disk I/O that would occur with shorter intervals.

Is the final audio quality degraded by the merging process?

No. The merge_checkpoints() function uses FFmpeg's concat demuxer with the -c copy flag, which performs a lossless stream copy. This concatenates the MP4 containers without decompressing and re-encoding the audio, ensuring the final output is bit-identical to the original captured data.

How does the RecordingManager interact with the IncrementalAudioSaver?

The RecordingManager in frontend/src-tauri/src/audio/recording_manager.rs captures raw audio from the system and wraps it in AudioChunk structs defined in recording_state.rs. It passes these chunks to IncrementalAudioSaver.add_chunk(), which handles the buffering, threshold checking, and checkpoint creation automatically.

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