Meeting Recording & Echo Mitigation
Relevant source files
The following files were used as context for generating this wiki page:
Meeting Recording in MacParakeet is a specialized capture mode designed to record both local microphone input and system audio (remote participants) concurrently. The system utilizes macOS-specific APIs, such as ScreenCaptureKit for system audio, to provide a dual-stream recording that separates speakers based on their audio source. This architecture is governed by ADR-014 and allows for local-first transcription without requiring cloud-based meeting bots.
Echo Mitigation is a critical component of the meeting pipeline, addressing the issue where remote speaker audio from system output leaks acoustically into the local microphone. MacParakeet employs multiple layers of mitigation, including a software-based Acoustic Echo Cancellation (AEC) (NLMS), joined mic/system processing, and a dominant-system live suppression guard. These measures ensure that transcriptions accurately attribute speech to "Me" or "Others" without phantom fragments caused by acoustic bleed.
Sources: spec/adr/014-meeting-recording.md, plans/completed/2026-04-meeting-mic-aec.md:16-24, spec/README.md:144-150
Audio Capture Architecture
The meeting pipeline captures two independent streams to maintain source separation for transcription and artifacts. This dual-source approach preserves the integrity of the original audio for high-quality post-meeting processing.
Dual-Stream Capture Components
- MicrophoneCapture: Taps
AVAudioEngine.inputNodefor raw local voice. It avoids Voice Processing I/O (VPIO) by default to prevent AGC/NS from degrading user voice quality, instead relying on software echo suppression. - SystemAudioTap: Utilizes Core Audio Taps or ScreenCaptureKit on the default output device to provide a clean copy of remote participants' audio.
- MeetingAudioPairJoiner: Aligns microphone and system sample batches, emitting diagnostics if sync-lag or overflows occur.
Sources: plans/completed/2026-04-meeting-mic-aec.md:17-38, plans/completed/2026-05-meeting-neural-echo-suppression.md:104-118
Meeting Recording Data Flow
The following diagram illustrates the path from raw audio capture to the final dual-source meeting artifact.
The diagram shows the alignment of mic and system streams followed by layered echo mitigation before final storage.
Sources: plans/completed/2026-04-meeting-mic-aec.md:16-24, plans/completed/2026-05-meeting-neural-echo-suppression.md:104-118
Echo Mitigation Strategies
Echo mitigation is implemented in a non-destructive manner, preserving raw audio while filtering transcription input. This prevents "phantom" fragments where remote speech is incorrectly attributed to the local user.
Software AEC and Neural Suppression
The project shipped a v0.6 hardening implementation that moved away from VPIO-centric planning in favor of MeetingSoftwareAEC using Normalized Least Mean Squares (NLMS). This software-based approach allows MacParakeet to cancel system output from the microphone stream without affecting the global hardware input gain that other apps might inherit.
Sources: plans/completed/2026-04-meeting-mic-aec.md:16-24, plans/completed/2026-05-meeting-neural-echo-suppression.md:16-30
Dominant-System Suppression Guard
As a defense-in-depth measure, a live suppression guard is applied to mic chunks. This deterministic guard checks the Root Mean Square (RMS) energy ratio between concurrent system and mic streams.
| Parameter | Value / Default | Description |
|---|---|---|
recentSystemRms | EMA of system RMS | Tracks ongoing remote participant energy levels. |
recentMicRms | EMA of mic RMS | Tracks local microphone energy levels. |
systemDominanceRatio | 4.0 | Mic chunks are suppressed if system energy ≥ 4× mic energy. |
systemActiveFloor | 0.02 | Minimum system energy required to trigger the gate. |
Sources: plans/completed/2026-04-meeting-mic-aec.md:103-125
Neural Echo Suppressor Logic
The StreamingMeetingEchoSuppressor handles frame-based processing by buffering partial frames and applying a reference delay to align system audio with the microphone signal.
Sequence showing the framing and alignment required for streaming echo suppression.
Sources: plans/completed/2026-05-meeting-neural-echo-suppression.md:12-24, plans/completed/2026-05-meeting-neural-echo-suppression.md:120-134
Meeting Artifacts and Reliability
Final artifacts preserve source separation to allow for flexible post-meeting review and re-transcription. Reliability is maintained through fragmented writing and watchdog monitoring.
Dual-Source Artifacts
When both mic and system tracks exist, the final artifact is preserved as a stereo file where L=microphone and R=system. This enables the diarization and transcription engines to process clean isolated tracks.
Sources: plans/completed/2026-04-meeting-mic-aec.md:16-24, plans/completed/2026-05-meeting-neural-echo-suppression.md:154-162
Capture Reliability Watchdog
AppFeatures.meetingCaptureReliabilityEnabled gates a mic-health telemetry watchdog. This system monitors for capture failure or extended silence that might indicate a hardware issue or permission loss during a session.
Sources: spec/README.md:160-165, plans/README.md:27-28
Crash Resilience (ADR-019)
The meeting recorder uses a fragmented MP4 writer that flushes 1-second fragments to disk. This ensures that in the event of an app crash or power loss, audio is playable up to the last fragment boundary. Session lock files (recording.lock) are used to detect orphans and offer recovery upon next launch.
Sources: spec/README.md:220-225, plans/completed/2026-04-crash-resilient-meeting-recording.md:12-40
Implementation Summary
Meeting Recording and Echo Mitigation in MacParakeet prioritize local-first privacy and technical accuracy. By utilizing a dual-stream architecture with layered software-based AEC, the system effectively separates local and remote participants without the need for destructive hardware processing or cloud intervention. Reliability is further enhanced by fragmented storage and sync-lag diagnostics, ensuring durable meeting artifacts.
Sources: spec/adr/014-meeting-recording.md, plans/completed/2026-04-meeting-mic-aec.md:16-24, plans/completed/2026-05-meeting-neural-echo-suppression.md:210-225