sys-voice

Cross-platform native voice I/O with OS-level Acoustic Echo Cancellation (AEC).

Current Status

Each platform has been roughly tested but this library is likely to have bugs. Contributions welcome.

Platform Support

Quick Start

use sys_voice::{AecConfig, CaptureHandle, Channels};

let config = AecConfig {
    sample_rate: 48000,
    channels: Channels::Mono,
};

let handle = CaptureHandle::new(config)?;

// Receive samples (async, blocking, or non-blocking)
while let Some(result) = handle.recv_blocking() {
    match result {
        Ok(samples) => { /* Process AEC-enabled audio samples */ }
        Err(e) => { /* Handle audio error */ }
    }
}

// Handle automatically stops capture on drop

Testing AEC

Run the included test tool to verify AEC is working on your system:

cargo run --example aec_test

The test tool:

1. Plays a 440Hz tone through your speakers
2. Records from the microphone with AEC enabled for 10 seconds
3. Saves the recording to aec_recording.wav

Expected result: The recording should contain your voice but NOT the 440Hz tone. If you hear the tone clearly in the recording, AEC may not be active on your system.

Platform-Specific Notes

macOS

• Requires microphone permission (System Preferences → Security & Privacy → Microphone)
• Uses VoiceProcessingIO audio unit which automatically monitors system output for echo reference
• macOS pauses/ducks other audio (Spotify, Apple Music, etc.) when VoiceProcessingIO is active. This is a system-level behavior that cannot be disabled.

iOS

• Requires NSMicrophoneUsageDescription in Info.plist
• Uses AVAudioSession voiceChat mode which enables hardware AEC
• Permission must be granted before stream creation

Windows

• Requires audio device with AEC support
• Uses WASAPI with IAcousticEchoCancellationControl
• Automatically links capture to render device for echo reference

Linux

• Requires PulseAudio daemon running
• For AEC, load module-echo-cancel: pactl load-module module-echo-cancel
• The Simple API cannot pass media.role hints; AEC depends on system configuration

Android

• Requires RECORD_AUDIO permission in AndroidManifest.xml
• Uses Oboe with VoiceCommunication usage which triggers hardware AEC
• Permission must be granted at runtime before stream creation

iOS Testing

See docs/ios-testing.md for detailed instructions on building and testing on iOS devices and simulators.

Limitations

• Linux: The PulseAudio Simple API cannot pass media.role hints. AEC depends on whether module-echo-cancel is loaded in the system configuration.
• Hardware AEC availability: Some devices may not support hardware AEC. The library will still capture audio, but without echo cancellation.

API Reference

Channels

#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum Channels {
    #[default]
    Mono,
    Stereo,
}

AecConfig

pub struct AecConfig {
    pub sample_rate: u32,   // Target sample rate (48000 recommended)
    pub channels: Channels, // Mono or Stereo (stereo = duplicated mono)
}

CaptureHandle

impl CaptureHandle {
    pub fn new(config: AecConfig) -> Result<Self, AecError>;
    
    // Async receive (requires async runtime)
    pub async fn recv(&self) -> Option<Result<Vec<f32>, AecError>>;
    
    // Blocking receive
    pub fn recv_blocking(&self) -> Option<Result<Vec<f32>, AecError>>;
    
    // Non-blocking receive
    pub fn try_recv(&self) -> Option<Result<Vec<f32>, AecError>>;
    
    // Get the native sample rate
    pub fn native_sample_rate(&self) -> u32;
}
// Capture stops automatically on drop

AecError

pub enum AecError {
    DeviceUnavailable,        // No capture device found
    PermissionDenied,         // Microphone access denied
    AecNotSupported,          // Platform doesn't support AEC
    InvalidConfig(String),    // Invalid configuration
    BackendError(String),     // Platform-specific error
}

License

MIT