chanora/crates/chanora_audio/README.md

chanora_audio

Real-time audio subsystem: capture, Opus encoding/decoding, voice rendering, PTT gating, and audio processing. Promoted from poc/audio-capture-playback-spike.

Architecture

Engine

• AudioEngine — the primary type. Starts a platform audio backend (capture + playback), wires an AudioTransmitGate for PTT gating, and feeds encoded Opus frames to the protocol layer via voice_out. Inbound voice packets are decoded and mixed by tsclientlib::audio::AudioHandler and pulled by the platform output callback at 48 kHz stereo.

Platform backends (cfg-gated)

Target	Backend	Notes
Android	Oboe (via android_voice_unit)	Requires ndk_context before start
iOS/macOS	Apple VoiceProcessingIO (ios_voice_unit)	Platform AEC/AGC/NS, route-change handling
Linux	SDL (sdl_output)	PulseAudio/ALSA via SDL
Other desktop	cpal	Fallback

Key modules

• audio_processing — P1 audio processing config, stats, route policy, effect ownership (Platform/Sonora/WebRTC APM)
• opus_voice — 20 ms / 48 kHz mono Opus encode/decode via audiopus
• transmit_mode — TransmitMode enum: Ptt, Continuous, VoiceActivity
• transmit_selector — TransmitModeSelector combining mode, hard-mute, PTT gate, permission gate, and in-channel state
• ptt — AudioTransmitGate (atomic bool), PttCapabilityLevel, PttBackendDescriptor
• ptt_backends — platform PTT backends: DesktopPttBackend (Linux portal), FocusedPttBackend (in-app fallback)
• release_tail — ReleaseTailTimer for configurable PTT release delay (default 200 ms, max 500 ms)
• vad — Voice-activity detection: Silero ONNX (desktop), WebRTC fallback, energy debug
• voice_render — mixes per-client decoded f32 PCM into the output buffer
• debug_wav — optional WAV file dump for diagnostics (DIAG_002/003)
• mobile_voice_backend — shared mobile voice-unit lifecycle abstraction
• frame — frame-aligned buffer utilities

Public API Summary

Types

Type	Role
AudioEngine	Start/stop audio, set gain/mute/volume, read stats
AudioEngineConfig	Capture/playback device selection, PTT initial state, processing config
AudioDeviceInfo / AudioDeviceList	Device enumeration
AudioTransmitGate	Atomic PTT gate
TransmitMode / TransmitModeSelector	Mode selection with hard-mute clamp
ReleaseTailTimer	Configurable release delay (SDD-096)
PttBinding / PttInputClass	PTT key binding types
PttBackendDescriptor / PttCapabilityLevel	Capability query
AudioProcessingConfig / AudioProcessingStats	P1 processing control and telemetry
AudioRoute	Speaker/Earpiece/Wired/Bluetooth enum
AudioEffects	Effect toggles (AEC/AGC/NS/HPF), all enabled by default (DEC-007..010)
AudioError	Typed error catalogue

Key functions

• AudioEngine::start_with_gate(cfg, voice_out, voice_in, gate) — construct and start
• AudioEngine::stop() — tear down
• list_audio_devices() — enumerate available input/output devices
• select_ptt_backend() — choose the best PTT backend for the current platform

Platform notes

• Android requires initChanoraContext (NDK context) before engine start.
• iOS/macOS uses VoiceProcessingIO for platform AEC/AGC/NS in the default route.
• Desktop can use Silero ONNX VAD when the model file is available.
• bench_seam is exposed (#[doc(hidden)]) for criterion benchmarks on non-mobile targets.