chanora/poc/audio-capture-playback-spike

Audio Capture / Playback Spike

Chanora proof-of-concept. Not product code.

Field	Value
PoC name	audio-capture-playback-spike
PoC plan	docs/architecture/proof-of-concept-plan.md §2
Purpose	Prove platform audio capture + playback behaviour
Exit criterion (plan)	"Capture/playback works on at least one desktop and one mobile target"
Authority	DEC-011 (platform-native first), audio family in SysDes / SRS

Honest status

Partial pass.

• Linux desktop: verified. cpal opens both the default input and the default output device, capture streams build (or report a typed error when no hardware-backed input is available), and playback drives a full PCM stream end-to-end through the platform audio stack (ALSA → PipeWire on this host).
• Mobile (Android / iOS): not verified. cpal supports Oboe (Android) and AVAudioEngine (iOS) but this PoC has not been built or run on either. The exit criterion's mobile half remains an open item for a follow-up spike — see "Gaps" below.

What it proves

• AudioCapture::record_to_wav(path, duration) — opens the default input device, reads frames in any supported sample format, down-mixes to mono, writes 16-bit-PCM WAV.
• AudioPlayback::play_wav(path) — opens the default output device, picks a stream config matching the file's sample rate, blocks until the file drains.
• synth_sine_wav — produces a deterministic 440 Hz sine WAV so the playback path is exercisable on hosts without a usable input device.
• A typed AudioError covering the practical failure modes (no device, config mismatch, stream-build failure, WAV I/O, unsupported format). Production code (chanora_audio) will widen this when DSP
  • Opus + jitter buffer surfaces land.
• Headless-friendly behaviour: if capture cannot build a stream, the CLI falls back to synth and the playback path is still exercised. This is the same shape production code would use for a "device test" UI.

Layout

audio-capture-playback-spike/
  src/
    lib.rs               # crate root + re-exports
    capture.rs           # AudioCapture, AudioError, sample-format adapters
    playback.rs          # AudioPlayback
    synth.rs             # synth_sine_wav (deterministic test signal)
    main.rs              # audio-capture-playback-cli
  tests/
    audio.rs             # 2 tests
  Cargo.toml

Reproduce (Linux desktop)

Requires Rust stable, ALSA dev headers (cpal builds against ALSA on Linux), and a working audio stack (PipeWire / Pulse / pure ALSA).

cargo test
cargo run --bin audio-capture-playback-cli -- roundtrip

CLI modes:

Mode	What it does
capture	Records 1 s of audio from the default input device to ${TMPDIR}/chanora_audio_spike_capture.wav.
synth	Writes a 440 Hz / 500 ms sine wave to ${TMPDIR}/chanora_audio_spike_synth.wav.
playback	Plays the synth WAV through the default output device.
roundtrip (default)	Tries capture; on any failure, falls back to synth; then playback.

PipeWire-only Linux hosts

On hosts where the only audio server is PipeWire (no pulseaudio package), cpal still uses ALSA underneath and needs a pcm.!default alias to the PipeWire PCM plugin. The package pipewire-alsa (or your distro equivalent) plus a one-line ~/.asoundrc is the standard fix:

pcm.!default { type pipewire }
ctl.!default { type pipewire }

Gaps (the mobile half of the exit criterion)

Target	What's missing	Notes
Android	Build & run cpal-oboe path on an emulator or device	Needs NDK + Gradle wiring + emulator. cpal supports it; this spike has not built it.
iOS	Build & run cpal-AVAudioEngine path on a device	Needs macOS + Xcode + a developer account.

These should be closed by a follow-up spike (or by promotion into the product chanora_audio crate scaffold) before the audio half of the PoC matrix is considered complete.

Scope boundaries

• No DSP. HPF / NS / AEC / AGC / mixing / Opus encode-decode / jitter buffer all belong to chanora_audio and are out of scope.
• No bit-exact loopback assertion. This PoC verifies that a capture stream can be opened and that a playback stream can drive a file to completion. It does not verify capture-to-playback signal integrity.
• No latency measurement.
• No device-permission flows. Mobile microphone consent UI is product-level.
• No echo-cancellation evidence. Different PoC.

Verification log

See VERIFICATION.md in this directory.