# How to Debug Audio Capture Issues Using the Meetily Diagnostics Module

> Debug audio capture issues with Meetily’s diagnostics module. Analyze buffer health, device capabilities, and performance to fix glitches and latency.

- Repository: [Zackriya Solutions/meetily](https://github.com/Zackriya-Solutions/meetily)
- Tags: how-to-guide
- Published: 2026-07-31

---

**Meetily’s diagnostics module provides platform-aware logging and runtime instrumentation that exposes buffer health, device capabilities, and performance metrics to diagnose missing audio, latency spikes, and device-specific glitches.**

The Meetily open-source meeting assistant relies on a robust audio pipeline to capture microphone and system audio for Whisper transcription. When capture fails silently or produces degraded output, the **diagnostics module** in [`frontend/src-tauri/src/audio/diagnostics.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/frontend/src-tauri/src/audio/diagnostics.rs) offers deep visibility into the Rust audio subsystem, revealing exactly how the pipeline handles device detection, buffer sizing, and stream mixing.

## How the Diagnostics Pipeline Fits into Meetily’s Architecture

Meetily’s audio stack uses a modular design where diagnostics integrate at three critical stages: device discovery, stream configuration, and runtime monitoring.

### Device Detection and Adaptive Configuration

Before recording begins, [`device_detection.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/device_detection.rs) identifies the **InputDeviceKind** (Bluetooth, USB, or built-in) and calculates an **adaptive buffer timeout** based on device characteristics. This module passes the detected device and `cpal::SupportedStreamConfig` to the diagnostics layer for structured reporting.

### Structured Capability Reporting

The `log_device_capabilities` function in [`diagnostics.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/diagnostics.rs) emits a comprehensive report containing:

- Platform name, device name, and input type
- Sample rate, channel count, buffer size, and sample format
- Calculated buffer latency and adaptive timeout range
- Platform-specific details (CoreAudio transport on macOS, WASAPI naming on Windows, PulseAudio/BlueZ on Linux)
- Warnings for suspicious configurations like Bluetooth low latency or non-standard sample rates

### Runtime Health Monitoring

Throughout the recording session, the pipeline invokes helper functions to log real-time metrics:

1. `log_detection_summary`: Concise device overview at session start
2. `log_buffer_health`: Ring-buffer utilization and dropped frames
3. `log_mixer_status`: Mic and system audio mixing statistics from [`ffmpeg_mixer.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/ffmpeg_mixer.rs)
4. `log_performance_summary`: Aggregate metrics including buffer overflows and device reconnects

## Interpreting Diagnostic Output

When running with `RUST_LOG=debug`, the diagnostics module prints structured logs that correlate technical metrics with specific remediation steps.

**Buffer Latency** readings indicate how long a single buffer sits before processing. Values exceeding 50 ms typically signal misconfigured wired devices, while values below 20 ms suggest potential Bluetooth underruns.

**⚠️ POTENTIAL ISSUE: Bluetooth device has unusually low buffer latency** warns that aggressive buffering on wireless devices risks dropouts. This indicates the adaptive timeout calculated in `InputDeviceKind::buffer_timeout()` is too aggressive for the current signal conditions.

**⚠️ HIGH BUFFER UTILIZATION** flags when the ring buffer exceeds 80 % capacity, pointing to CPU back-pressure or insufficient timeout values. The log appears when `log_buffer_health` detects `current_buffer.len()` approaching `max_buffer.len()`.

Platform-specific sections reveal low-level audio stack details—such as CoreAudio transport types or WASAPI driver names—that verify whether virtual devices like macOS “BlackHole” are active.

## Instrumenting Your Code with Diagnostics

To add diagnostic coverage to custom audio workflows, import the detection and logging functions from [`audio/mod.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/audio/mod.rs) and instrument your pipeline at key transition points.

```rust
use crate::audio::{
    device_detection::{detect_input_device, InputDeviceKind},
    diagnostics::{
        log_device_capabilities, log_detection_summary,
        log_buffer_health, log_mixer_status, log_performance_summary,
    },
};

// 1. Detect device and determine its classification
let (device, config) = detect_input_device()?;
let kind = InputDeviceKind::from_device(&device);

// 2. Log full hardware capabilities once per session
log_device_capabilities(&device, &config, kind);

// 3. Emit concise summary when recording starts
log_detection_summary(
    &device.name, 
    kind, 
    config.buffer_size().max(), 
    config.sample_rate().0
);

// 4. Monitor buffer health inside the capture loop
log_buffer_health(
    &device.name,
    kind,
    current_buffer.len(),
    max_buffer.len(),
    dropped_frames,
);

// 5. Report mixer status after combining mic and system audio
log_mixer_status(mic_buffered, system_buffered, gaps_detected, silence_inserted_ms);

// 6. Generate final report when session ends
log_performance_summary(
    total_chunks_processed,
    average_latency_ms,
    buffer_overflows,
    device_reconnects,
);

```

## Enabling Verbose Logging

Diagnostic output requires the `debug` log level for the `app_lib::audio` crate. Launch Meetily with the appropriate environment variable for your platform:

```bash

# macOS and Linux

RUST_LOG=debug,app_lib::audio=debug ./clean_run.sh

# Windows PowerShell

$env:RUST_LOG="debug,app_lib::audio=debug"; ./clean_run_windows.bat

```

These logs appear in the Rust console and are simultaneously emitted as **Tauri events**, enabling the frontend diagnostics view to display real-time audio subsystem status.

## Key Source Files

The following files in the `Zackriya-Solutions/meetily` repository contain the referenced implementations:

- **[`frontend/src-tauri/src/audio/diagnostics.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/frontend/src-tauri/src/audio/diagnostics.rs)**: Central implementation of `log_device_capabilities`, `log_buffer_health`, and performance reporting.
- **[`frontend/src-tauri/src/audio/device_detection.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/frontend/src-tauri/src/audio/device_detection.rs)**: `InputDeviceKind` enum and adaptive timeout calculations.
- **[`frontend/src-tauri/src/audio/pipeline.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/frontend/src-tauri/src/audio/pipeline.rs)**: Audio buffer processing that invokes diagnostic hooks during recording.
- **[`frontend/src-tauri/src/audio/ffmpeg_mixer.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/frontend/src-tauri/src/audio/ffmpeg_mixer.rs)**: Adaptive mixing logic that reports mixer status via `log_mixer_status`.

## Summary

- Import the diagnostics module from [`audio/diagnostics.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/audio/diagnostics.rs) to instrument device detection, buffer health, and performance summaries.
- Run Meetily with `RUST_LOG=debug,app_lib::audio=debug` to expose buffer latency, utilization warnings, and platform-specific device details.
- Interpret **buffer latency** values to distinguish between wired configuration errors (> 50 ms) and Bluetooth underruns (< 20 ms).
- Use `log_device_capabilities` to verify sample rates, channel counts, and driver selection (CoreAudio, WASAPI, PulseAudio) before recording begins.
- Correlate `⚠️ HIGH BUFFER UTILIZATION` warnings with CPU load or inadequate timeout values calculated by `InputDeviceKind::buffer_timeout()`.

## Frequently Asked Questions

### How do I enable debug logging for audio capture in Meetily?

Set the `RUST_LOG` environment variable to `debug,app_lib::audio=debug` when launching the application. On macOS and Linux, run `RUST_LOG=debug,app_lib::audio=debug ./clean_run.sh`. On Windows, use `$env:RUST_LOG="debug,app_lib::audio=debug"` in PowerShell before executing the run script. This exposes the structured diagnostics output from [`diagnostics.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/diagnostics.rs) in the console and forwards it to the frontend via Tauri events.

### What does the warning "Bluetooth device has unusually low buffer latency" mean?

This warning appears in `log_device_capabilities` when the adaptive timeout calculated in [`device_detection.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/device_detection.rs) falls below safe thresholds for wireless audio. Bluetooth devices require higher latency buffers to accommodate radio interference and packet loss; values below 20 ms risk audio dropouts. Remediation involves increasing the physical proximity between the device and computer, reducing wireless interference, or switching to a wired input device.

### Where can I find the source code for the diagnostics module?

The primary implementation resides in [`frontend/src-tauri/src/audio/diagnostics.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/frontend/src-tauri/src/audio/diagnostics.rs) within the `Zackriya-Solutions/meetily` repository. This file contains the `log_device_capabilities`, `log_buffer_health`, `log_mixer_status`, and `log_performance_summary` functions. Related device detection logic is located in [`frontend/src-tauri/src/audio/device_detection.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/frontend/src-tauri/src/audio/device_detection.rs), while the pipeline integration occurs in [`frontend/src-tauri/src/audio/pipeline.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/frontend/src-tauri/src/audio/pipeline.rs).

### How does Meetily calculate adaptive buffer timeouts?

The `InputDeviceKind` enum in [`device_detection.rs`](https://github.com/Zackriya-Solutions/meetily/blob/main/device_detection.rs) categorizes detected hardware as Bluetooth, USB, or built-in, then calculates timeout values based on device-specific latency characteristics and historical reliability. The resulting timeout range appears in diagnostic reports as the **adaptive buffer timeout**, which the pipeline uses to configure `cpal::SupportedStreamConfig` parameters and detect mismatches between expected and actual buffer behavior.