Edison Jwa
72ded4e011
Design documents for event replay, audio processing test, audio loopback test, and protocol probe tools. iOS audio session test plan with 28 scenarios and 3-phase automation approach.
71 lines
3.4 KiB
Markdown
71 lines
3.4 KiB
Markdown
# 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
|