# Audio Loopback Test Tool Design

**Date:** 2026-06-11
**Status:** Design proposal
**TODO:** TODO-046
**Requirements:** SysRS-073, SRS-083
**Effort:** L
**Dependencies:** TODO-054 (audio loopback harness)

## Purpose

End-to-end audio quality verification. Sends a known test signal through the full encode→decode→playback→capture loop and measures signal quality metrics to verify the entire audio pipeline works correctly on a given platform.

## Inputs

- Known test signal (sine sweep, white noise, or chirp)
- Loopback device configuration (virtual audio device or hardware loopback)
- Test duration and sample rate

## Outputs

- Signal quality metrics: SNR (dB), latency (ms), jitter (ms), THD+N (%)
- Pass/fail against acceptance thresholds
- Captured loopback audio WAV for manual inspection

## Architecture

```text
┌──────────┐     ┌───────────┐     ┌───────────┐     ┌───────────┐
│ Test     │────>│ Opus      │────>│ Loopback  │────>│ Opus      │
│ Signal   │     │ Encode    │     │ Device    │     │ Decode    │
│ Generator│     │           │     │ (virtual) │     │           │
└──────────┘     └───────────┘     └───────────┘     └─────┬─────┘
                                                           │
┌──────────┐     ┌───────────┐     ┌───────────┐     ┌────v─────┐
│ Report   │<────│ Metrics   │<────│ Compare   │<────│ Capture  │
│ (SNR,    │     │ Extract   │     │ (original │     │ (loopback│
│  latency)│     │           │     │  vs recv) │     │  audio)  │
└──────────┘     └───────────┘     └───────────┘     └──────────┘
```

1. **Generate:** Create known test signal (e.g., 1kHz sine, sweep)
2. **Encode:** Pass through Opus encoder (matching voice pipeline config)
3. **Loopback:** Send encoded audio through virtual audio device
4. **Decode:** Capture loopback audio and decode through Opus decoder
5. **Compare:** Cross-correlate original and received signals
6. **Measure:** Extract SNR, latency (peak correlation offset), jitter, THD+N

## Implementation Plan

- New Rust binary crate: `tools/audio-loopback-test/`
- Reuse `chanora_audio` Opus encoder/decoder wrappers
- Virtual audio device: BlackHole (macOS), VB-Audio (Windows), snd-aloop (Linux)
- Cross-correlation for latency measurement
- CLI interface: `audio-loopback-test [--duration 5] [--signal sine|sweep|noise] [--device <name>]`
- Requires TODO-054 (loopback harness) for CI virtual device setup

## Dependencies

- `chanora_audio` (Opus encode/decode, audio config)
- `opus` crate (encoder/decoder)
- `hound` (WAV I/O)
- Virtual audio device (platform-specific, from TODO-054)

## Verification

- Unit test: encode→decode roundtrip without loopback, verify signal preserved
- Integration test: full loopback on macOS with BlackHole, verify SNR > threshold
- Platform test: run on each target OS with configured virtual device
- Demo: run tool on developer machine, show metrics report