docs: add test tool designs and iOS test plan (TODO-020,043,044,046,047)

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.
2026-06-11 21:04:45 +09:00
parent c04aaf4a51
commit 72ded4e011
5 changed files with 423 additions and 0 deletions
@@ -0,0 +1,70 @@
+# 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