livekit/platform_audio/
processing.rs

1// Copyright 2026 LiveKit, Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Audio processing configuration types (AEC, AGC, NS).
16
17/// The type of audio processing being used.
18#[derive(Debug, Clone, Copy, PartialEq, Eq)]
19pub enum AudioProcessingType {
20    /// Hardware audio processing (iOS VPIO, Android hardware effects).
21    Hardware,
22    /// Software audio processing (WebRTC's built-in APM).
23    Software,
24    /// Audio processing is not available or disabled.
25    None,
26}
27
28impl Default for AudioProcessingType {
29    fn default() -> Self {
30        Self::Software
31    }
32}
33
34/// Configuration options for audio processing (AEC, AGC, NS).
35///
36/// # Platform Behavior
37///
38/// - **iOS**: Hardware processing via VPIO is always used and provides excellent
39///   AEC/AGC/NS. The `prefer_hardware_processing` default is `true` on iOS.
40///
41/// - **Android**: Hardware AEC quality varies significantly across manufacturers
42///   and device models. Many devices have broken or poorly-tuned hardware AEC.
43///   The default is `false` to use WebRTC's reliable software processing.
44///   See: <https://github.com/react-native-webrtc/react-native-webrtc/issues/713>
45///
46/// - **Desktop** (macOS, Windows, Linux): Hardware processing is not available.
47///   WebRTC's software Audio Processing Module (APM) is always used.
48///   The `prefer_hardware_processing` setting is ignored.
49///
50/// # Example
51///
52/// ```rust,ignore
53/// use livekit::AudioProcessingOptions;
54///
55/// // Use platform-appropriate defaults
56/// let opts = AudioProcessingOptions::default();
57///
58/// // Disable echo cancellation
59/// let opts = AudioProcessingOptions {
60///     echo_cancellation: false,
61///     ..Default::default()
62/// };
63///
64/// // Force software processing on iOS (not recommended)
65/// let opts = AudioProcessingOptions {
66///     prefer_hardware_processing: false,
67///     ..Default::default()
68/// };
69/// ```
70#[derive(Debug, Clone, Copy, PartialEq, Eq)]
71pub struct AudioProcessingOptions {
72    /// Enable echo cancellation.
73    ///
74    /// Echo cancellation removes acoustic echo from the microphone signal,
75    /// which occurs when the speaker output is picked up by the microphone.
76    ///
77    /// Default: `true`
78    pub echo_cancellation: bool,
79
80    /// Enable noise suppression.
81    ///
82    /// Noise suppression reduces background noise in the microphone signal.
83    ///
84    /// Default: `true`
85    pub noise_suppression: bool,
86
87    /// Enable automatic gain control.
88    ///
89    /// AGC automatically adjusts the microphone volume to maintain
90    /// consistent audio levels.
91    ///
92    /// Default: `true`
93    pub auto_gain_control: bool,
94
95    /// Prefer hardware audio processing when available.
96    ///
97    /// # Platform Defaults
98    ///
99    /// - **iOS**: `true` - VPIO hardware processing is excellent and always used.
100    ///   Apple's Voice Processing IO unit provides reliable, low-latency AEC/AGC/NS
101    ///   that is tightly integrated with the audio hardware.
102    ///
103    /// - **Android**: `false` - Hardware AEC is unreliable on many devices.
104    ///   Quality varies significantly across manufacturers (Samsung, Xiaomi, etc.)
105    ///   and even across models from the same manufacturer. WebRTC's software AEC
106    ///   provides consistent behavior across all Android devices.
107    ///   Reference: Meta found hardware AEC "broken on many combinations of HW + OS"
108    ///   when supporting billions of users across thousands of device models.
109    ///
110    /// - **Desktop**: `false` - Hardware processing is not available.
111    ///   This setting is ignored; WebRTC software APM is always used.
112    pub prefer_hardware_processing: bool,
113}
114
115impl Default for AudioProcessingOptions {
116    fn default() -> Self {
117        Self {
118            echo_cancellation: true,
119            noise_suppression: true,
120            auto_gain_control: true,
121            // iOS: VPIO hardware processing is excellent and tightly integrated.
122            // Android: Hardware AEC is unreliable across the fragmented device ecosystem.
123            // Desktop: Hardware processing not available, setting is ignored.
124            #[cfg(target_os = "ios")]
125            prefer_hardware_processing: true,
126            #[cfg(not(target_os = "ios"))]
127            prefer_hardware_processing: false,
128        }
129    }
130}
livekit/platform_audio/processing.rs

livekit/platform_audio/
processing.rs
