How Professional Audio Mixing in Meetily Prevents Clipping During Simultaneous Recording

Meetily implements a two-stage limiter architecture that scales audio peaks to approximately 0.95 and applies soft-clipping filters, preventing hard distortion when mixing microphone and system audio streams.

Meetily, an open-source meeting transcription tool developed by Zackriya-Solutions, captures both microphone and system audio concurrently during recording sessions. When these simultaneous high-volume streams overlap, their combined amplitudes can exceed digital maximums and create harsh "radio breaks" distortion. To prevent this, the professional audio mixing pipeline in frontend/src-tauri/src/audio/pipeline.rs and frontend/src-tauri/src/audio/ffmpeg_mixer.rs implements explicit clipping prevention logic that safeguards recording quality.

Two-Stage Clipping Prevention Architecture

Meetily's audio processing layer employs a dual-defense strategy against digital clipping. When simultaneous recording occurs, audio samples from both sources can sum beyond the normalized amplitude of 1.0. The system prevents this through sequential limiting stages implemented in the Rust-based Tauri frontend.

Pre-Mix Peak Limiting in pipeline.rs

The initial mixing stage occurs in frontend/src-tauri/src/audio/pipeline.rs, where the combine_audio routine—documented at line 146—performs the blending of microphone and system audio buffers. This function sums the incoming streams and applies a basic limiter that scales any sample exceeding the safe peak range. According to the source comments at line 176, this logic specifically "avoids hard clipping distortion that sounds like radio breaks" by ensuring the mixed output never reaches the digital maximum threshold during the combination process.

FFmpeg Soft-Limiting in ffmpeg_mixer.rs

The second safeguard resides in frontend/src-tauri/src/audio/ffmpeg_mixer.rs, where the lower-level FFmpeg integration incorporates explicit clipping protection. Source comments at lines 306 and 313 mark the specific blocks where "Prevent clipping" logic is applied within the audio-processing pipeline. This stage applies final soft-clipping filters and resampling safeguards to the mixed audio before recording_saver.rs writes the final file, ensuring the output remains distortion-free even when input levels are aggressive.

Validation Through Unit Testing

To verify clipping prevention under extreme conditions, Meetily includes the test_audio_mixer_clipping_prevention unit test in ffmpeg_mixer.rs (lines 499-502). This test deliberately injects overdriven sample values of 1.5—significantly exceeding the normalized maximum of 1.0—and asserts that the mixer's output stays strictly within the allowable amplitude range. This automated validation confirms that the algorithm successfully limits peaks regardless of input volume, providing consistent protection against distortion.

Implementation Examples

The following Rust code demonstrates the professional mixing and clipping prevention mechanisms:

// ---- professional mixing (pipeline.rs) ----
/// Combines mic + system audio with basic clipping prevention
fn mix(mic: &[f32], system: &[f32]) -> Vec<f32> {
    // Simple RMS-based ducking …
    let mixed = mic.iter().zip(system).map(|(m, s)| m + s).collect::<Vec<_>>();
    // This avoids hard clipping distortion that sounds like "radio breaks"
    limit_peaks(&mixed, 0.95)
}

// ---- FFmpeg-based mixer (ffmpeg_mixer.rs) ----
// Prevent clipping
let cmd = Command::new("ffmpeg")
    .args(&["-i", input, "-af", "volume=0.9, aresample=resampler=soxr, limiter"])
    .output()?;

// Test that extreme values are limited
#[test]
fn test_audio_mixer_clipping_prevention() {
    let extreme = vec![1.5_f32; 48000]; // deliberately overdriven
    let result = mix_with_ffmpeg(&extreme);
    assert!(result.iter().all(|&s| s.abs() <= 1.0));
}

Summary

• Meetily combines microphone and system audio using a two-stage limiter architecture to prevent hard clipping during simultaneous recording.
• The combine_audio routine in frontend/src-tauri/src/audio/pipeline.rs applies preliminary peak scaling to approximately 0.95 before mixing streams.
• FFmpeg integration in frontend/src-tauri/src/audio/ffmpeg_mixer.rs provides secondary soft-clipping protection at lines 306 and 313.
• The test_audio_mixer_clipping_prevention unit test at lines 499-502 validates that extreme input values (1.5) are constrained within safe output ranges (≤1.0).
• Supporting utilities in audio_processing.rs and file writing in recording_saver.rs complete the distortion-free pipeline.

Frequently Asked Questions

What causes audio clipping during simultaneous recording?

When multiple audio streams are mixed digitally, their amplitudes sum mathematically. If the combined waveform exceeds the maximum representable value of 1.0 in normalized floating-point audio, the peaks flatten against the digital ceiling, creating harsh distortion artifacts described in the Meetily codebase as "radio breaks."

How does Meetily specifically prevent clipping?

Meetily implements a two-stage approach: first, the combine_audio function in pipeline.rs scales mixed samples to a target peak of 0.95, providing 5% headroom. Second, the FFmpeg mixer in ffmpeg_mixer.rs applies soft-clipping filters and resampling safeguards marked by "Prevent clipping" comments at lines 306 and 313.

What is the test coverage for clipping prevention?

The repository includes the test_audio_mixer_clipping_prevention unit test in ffmpeg_mixer.rs (lines 499-502) that deliberately injects extreme sample values of 1.5 and verifies that all output samples remain within the absolute bounds of 1.0, ensuring the limiter functions correctly under worst-case scenarios.

Which files handle the audio mixing pipeline?

The primary mixing logic resides in frontend/src-tauri/src/audio/pipeline.rs, with FFmpeg-based post-processing in frontend/src-tauri/src/audio/ffmpeg_mixer.rs. Utility functions for peak limiting are located in frontend/src-tauri/src/audio/audio_processing.rs, while frontend/src-tauri/src/audio/recording_saver.rs handles the final distortion-free file writing.

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