Files

T

EdisonJwa d5b53996bc feat(poc/audio): add audio capture/playback spike (partial — desktop only)

Proof-of-concept addressing the audio exit criterion from
docs/architecture/proof-of-concept-plan.md §2:
  "Capture/playback works on at least one desktop and one mobile
   target."

PARTIAL PASS. The desktop half is verified on Linux; the mobile
half is NOT verified by this PoC and remains a documented open gap.

Implements via cpal (matching DEC-011 'platform-native first'):
  - AudioCapture::record_to_wav opens the default input device,
    handles f32/i16/u16 sample formats, down-mixes to mono, writes
    16-bit PCM WAV via hound.
  - AudioPlayback::play_wav opens the default output device, picks
    a stream config matching the WAV, blocks until drained.
  - synth_sine_wav produces a deterministic 440 Hz test signal for
    headless verification of the playback path when no microphone
    is available.
  - Typed AudioError DTO with NoInputDevice, NoOutputDevice,
    DefaultConfig, BuildStream, PlayStream, Wav, Io,
    UnsupportedFormat arms.

Verified on 2026-05-13 (Linux + cpal + PipeWire). Capture stream
opened against the system default input; build failed against the
auto_null source (typed AudioError::BuildStream returned cleanly,
demonstrating the production error path); fallback to synth fired;
playback drove 24,000 frames to completion through
Rust → cpal → ALSA → pcm_pipewire → PipeWire → auto_null.
Both audio.rs tests pass.

Mobile gap (explicit, NOT closed):
  - Android Oboe path not built or run.
  - iOS AVAudioEngine path not built or run.

Surfaced finding for the decision register: DEC-011 does not pin an
audio crate. The PoC uses cpal; production code needs an owner
ruling, ideally after the mobile spike closes the gap.

Out of scope: DSP (HPF/NS/AEC/AGC), Opus encode/decode, jitter
buffer, mixer, latency measurement, bit-exact loopback, device
permission flows. These belong to chanora_audio.

Authority: PoC plan §2, DEC-011, SysDes audio subsystem.
Not product code; not promoted into chanora_audio.

2026-05-14 12:27:04 +08:00

4.6 KiB

Raw Blame History

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.

4.6 KiB Raw Blame History