How Meetily's Audio Pipeline Handles Professional Ducking and Clipping Prevention

Meetily prevents audio distortion by applying soft-scaling gain reduction to system audio and using proportional waveform scaling to enforce digital full-scale limits without hard clipping.

Meetily, an open-source meeting transcription tool by Zackriya-Solutions, implements a sophisticated audio mixing pipeline in Rust to blend microphone and system audio streams. The pipeline's ProfessionalAudioMixer in frontend/src-tauri/src/audio/pipeline.rs applies professional ducking and clipping prevention techniques to ensure clean, broadcast-quality output for transcription and recording.

The Audio Pipeline Architecture

The mixing stage operates on aligned 50 ms windows gathered from a ring buffer, ensuring microphone and system samples remain perfectly synchronized before processing.

Synchronized Stream Buffering with AudioMixerRingBuffer

The AudioMixerRingBuffer collects raw PCM samples from both DeviceType::Microphone and DeviceType::System sources. It buffers incoming data until a complete window is available, zero-padding incomplete windows to prevent artifacts. When sufficient data accumulates, the extract_window method (lines 92–108) returns aligned slices ready for mixing.

The ProfessionalAudioMixer Implementation

The ProfessionalAudioMixer struct processes these aligned windows through its mix_window method (lines 145–188). This method implements two critical signal processing techniques: gain scaling for ducking and proportional limiting for clipping prevention.

Soft-Scaling for Professional Ducking

Rather than abruptly muting system audio when the microphone is active, Meetily applies soft-scaling to create headroom. The system audio track is pre-scaled to approximately 70% of its original level, while the microphone maintains full volume. This preserves the natural balance between sources while preventing the combined signal from exceeding digital limits.

In frontend/src-tauri/src/audio/pipeline.rs, lines 65–69 implement this scaling:

// Professional mixing – pre‑scale system audio to 70 % (soft ducking)
// mic stays at full volume, system is reduced to leave headroom
// Lines 65‑69
let sys_scaled = sys * 1.0;           // system reduced (previously hard‑clamped)
let _mic_scaled = mic * 0.8;          // placeholder for future mic scaling

By reducing the system track's gain before summation, the mixer ensures the combined waveform retains sufficient headroom, eliminating the need for aggressive dynamic range compression later in the chain.

Proportional Clipping Prevention Algorithm

When mixed samples exceed the ±1.0 digital full-scale range, Meetily avoids the harsh distortion of hard clipping by applying proportional scaling. Instead of truncating peaks at the limit, the algorithm scales the entire sample value down to fit within the valid range, preserving the waveform's shape and harmonic content.

Lines 74–82 in frontend/src-tauri/src/audio/pipeline.rs implement this logic:

// Soft scaling prevents hard clipping distortion
// Lines 74‑82
let sum_abs = sum.abs();
let mixed_sample = if sum_abs > 1.0 {
    // Scale the whole sample to fit within ±1.0
    sum / sum_abs
} else {
    sum
};

This technique guarantees that no sample exceeds the allowed amplitude while maintaining the relative dynamics of the original signals, preventing the "radio-breaks" artifact common in simpler clipping implementations.

Integration in the Main Processing Loop

The AudioPipeline::run method (lines 178–210) orchestrates the mixing workflow, continuously extracting windows from the ring buffer and processing them through the professional mixer:

// Inside `AudioPipeline::run` – the mixing occurs automatically
while self.ring_buffer.can_mix() {
    if let Some((mic_win, sys_win)) = self.ring_buffer.extract_window() {
        let mixed = self.mixer.mix_window(&mic_win, &sys_win);
        // `mixed` is sent to VAD, transcription and recording
        self.transcription_sender.send(mixed.into())?;
    }
}

Each 50 ms window of mixed audio is immediately forwarded to voice activity detection (VAD) and transcription engines, ensuring minimal latency between capture and processing.

Summary

• Soft-scaling reduces system audio gain to 70% before mixing, creating headroom and avoiding the need for hard ducking.
• Proportional clipping prevention scales entire samples that exceed ±1.0, preserving waveform shape while enforcing digital limits.
• Synchronized buffering via AudioMixerRingBuffer ensures microphone and system audio remain aligned to 50 ms windows.
• All mixing logic resides in frontend/src-tauri/src/audio/pipeline.rs, specifically within the ProfessionalAudioMixer::mix_window implementation.

Frequently Asked Questions

What is the purpose of audio ducking in Meetily?

Audio ducking in Meetily lowers the system audio level relative to the microphone input to ensure speech remains intelligible over background audio. Unlike abrupt muting, the soft-scaling approach maintains the presence of system audio while prioritizing microphone clarity.

How does proportional clipping prevention differ from hard clipping?

Hard clipping truncates samples exceeding the ±1.0 limit at the threshold, creating square-wave distortion and harsh artifacts. Proportional scaling reduces the amplitude of the entire sample to fit within limits, preserving the waveform's curvature and producing a cleaner, more natural sound.

Where is the professional audio mixing logic located?

The mixing logic is implemented in frontend/src-tauri/src/audio/pipeline.rs within the ProfessionalAudioMixer struct. The mix_window method (lines 145–188) contains both the soft-scaling ducking and proportional clipping prevention algorithms.

What buffer size does the pipeline use for mixing windows?

The pipeline processes audio in synchronized 50 ms windows extracted from the AudioMixerRingBuffer. This window size balances latency and processing efficiency, ensuring real-time transcription without perceptible delay.

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