Meetily Audio Level Monitor: Implementing RMS-Based Ducking and Clipping Prevention

Meetily's audio level monitor automatically reduces system audio gain by approximately 4 dB when RMS-detected speech exceeds a 0.01 threshold, while employing both hard clamping and proportional scaling techniques to prevent digital clipping distortion.

Meetily, an open-source meeting transcription assistant, implements sophisticated audio level monitoring to balance microphone and system audio streams in real-time. The application uses a dual-mixer architecture that combines FFmpeg-style adaptive mixing with pipeline-level professional processing to ensure clear speech capture without audible distortion. This implementation relies on Root Mean Square (RMS) calculations to drive intelligent ducking and multi-layered clipping prevention strategies.

The Dual-Mixer Architecture

Meetily processes audio mixing in two distinct locations, each optimized for different stages of the audio pipeline.

FFmpeg-Style Adaptive Mixer

The primary mixing occurs in frontend/src-tauri/src/audio/ffmpeg_mixer.rs, where the AudioMixer struct handles real-time combination of microphone and system audio streams. This mixer implements RMS-based ducking logic and hard-clipping protection for immediate output to the transcription pipeline.

Professional Pipeline Mixer

The secondary mixing layer resides in frontend/src-tauri/src/audio/pipeline.rs, specifically within the ProfessionalAudioMixer::mix_window method (lines 61-84). This component provides soft-scaling clipping prevention for VAD-driven processing, ensuring that audio windows sent to speech recognition remain within valid amplitude ranges while preserving relative dynamics.

RMS-Based Ducking Implementation

The ducking system continuously monitors microphone activity to intelligently attenuate background audio only when necessary.

RMS Calculation and Speech Detection

The calculate_rms function in ffmpeg_mixer.rs (lines 48-56) computes the root-mean-square value of microphone samples for each 50ms mixing window. When the calculated RMS exceeds the SPEECH_THRESHOLD constant of 0.01, the system identifies active speech.

In the mix function (lines 88-96), this detection triggers the ducking logic:

// RMS calculation determines if mic is "talking"
let rms = calculate_rms(mic_samples);
let is_speech = rms > SPEECH_THRESHOLD; // 0.01 threshold

Adaptive Gain Reduction Logic

When speech is detected, the mixer applies an adaptive gain reduction to the system audio stream. The default system_ducking value of 0.60 (approximately -4 dB) reduces background audio volume while the microphone is active, restoring full system volume during silence.

This implementation in ffmpeg_mixer.rs (lines 88-96) ensures that ducking occurs only during actual speech activity, preventing unnecessary attenuation of system audio during quiet periods.

Clipping Prevention Strategies

Meetily employs two distinct approaches to prevent digital clipping, depending on which mixer component is processing the audio.

Hard Clamping in the FFmpeg Mixer

The mix function in ffmpeg_mixer.rs (lines 103-108) applies hard clamping to every summed sample. After combining the microphone and system audio streams with their respective gain values, the result is clamped to the range -1.0 to +1.0:

// Prevent hard clipping by clamping to valid range
let sum = mic_sample * mic_gain + system_sample * system_gain;
let clamped = sum.clamp(-1.0, 1.0);

This technique eliminates "radio-break" distortion by ensuring the final waveform never exceeds the digital range accepted by most audio codecs.

Proportional Scaling in the Pipeline Mixer

The ProfessionalAudioMixer::mix_window method in pipeline.rs (lines 61-84) implements a more sophisticated soft-scaling approach. When the summed value exceeds ±1.0, the entire window is proportionally scaled using the formula sum / sum_abs rather than hard-clipping individual samples.

This preserves the relative dynamics of the audio content while maintaining the waveform within valid bounds, making it particularly suitable for VAD-driven processing where amplitude consistency affects transcription accuracy.

Code Implementation Examples

To implement the FFmpeg-style mixer with RMS-based ducking in your own Meetily integration:

use crate::audio::ffmpeg_mixer::AudioMixer;

// Initialize mixer with adaptive ducking enabled
let mut mixer = AudioMixer::new(true);
let mixed = mixer.mix(&mic_samples, &system_samples);
// mixed is already ducked (if speech detected) and clamped to [-1.0, 1.0]

For pipeline-level processing with soft-scaling clipping prevention:

use crate::audio::pipeline::ProfessionalAudioMixer;

let mut pro_mixer = ProfessionalAudioMixer::new(48000); // 48kHz sample rate
let mixed = pro_mixer.mix_window(&mic_window, &system_window);
// mixed is proportionally scaled only when sum exceeds ±1.0

Both methods return Vec<f32> buffers ready for direct consumption by the Whisper transcription pipeline or WAV file serialization.

Summary

• RMS-based detection: The calculate_rms function in ffmpeg_mixer.rs computes perceived loudness every 50ms to detect speech activity above the 0.01 threshold.
• Adaptive ducking: System audio gain reduces to 0.60 (-4 dB) automatically when microphone speech is detected, preventing background audio from drowning out speakers.
• Hard-clipping protection: The FFmpeg mixer clamps summed samples to [-1.0, 1.0] in mix (lines 103-108), eliminating digital distortion.
• Soft-scaling fallback: The pipeline mixer in pipeline.rs (lines 61-84) applies proportional scaling when windows exceed amplitude limits, preserving dynamic range.
• Dual architecture: Separate mixers handle real-time streaming (ffmpeg_mixer.rs) and VAD-driven processing (pipeline.rs) with complementary clipping strategies.

Frequently Asked Questions

What is the threshold for triggering RMS-based ducking in Meetily?

Meetily uses a SPEECH_THRESHOLD constant of 0.01 defined in ffmpeg_mixer.rs. When the RMS calculation for a 50ms microphone window exceeds this value, the system considers speech active and applies the 0.60 gain reduction to system audio.

How does Meetily prevent audio clipping when mixing two loud sources?

The application implements two mechanisms: hard clamping in ffmpeg_mixer.rs that forces samples into the [-1.0, 1.0] range, and proportional scaling in pipeline.rs that reduces the entire window's amplitude by a calculated factor when the sum exceeds ±1.0, preserving relative dynamics while preventing distortion.

Why does Meetily use RMS instead of peak amplitude for speech detection?

RMS (Root Mean Square) provides a more accurate estimation of perceived loudness over time compared to instantaneous peak values. By calculating RMS for each 50ms window in calculate_rms, Meetily reliably distinguishes between actual speech and transient noise spikes, ensuring ducking only occurs during meaningful vocal activity.

Can the ducking amount be adjusted in Meetily's audio configuration?

Yes, the system_ducking parameter in the AudioMixer struct controls the gain reduction applied to system audio during speech detection. The default value of 0.60 represents approximately -4 dB of attenuation, but this can be modified when initializing the mixer via AudioMixer::new(enable_ducking) and adjusting the internal ducking gain constants.

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