feat(audio): engine-wide audio processing state read-back

Surfaces the WebRTC-SDK v2 audio processing state on AudioManager:
the audio processing module is owned by the native peer connection
factory and shared engine-wide, so the snapshot reflects what is
actually applied across the engine rather than any single track.

Dart models follow the v2 contract per component: requested (caller
intent, null when nothing was ever applied) -> software/platform
resolved -> active, with effective as the merged verdict. The iOS and
Android plugins read factory.audioProcessingState and serialize it
over the method channel; Android reaches the factory through the
flutter_webrtc getPeerConnectionFactory accessor.

Author: hiroshihorie

android/src/main/kotlin/io/livekit/plugin/LiveKitPlugin.kt

@@ -30,9 +30,12 @@ import com.cloudwebrtc.webrtc.audio.LocalAudioTrack
 import io.flutter.plugin.common.BinaryMessenger
 import org.webrtc.AudioTrack
 import org.webrtc.audio.AudioProcessingComponentOptions
+import org.webrtc.audio.AudioProcessingComponentState
+import org.webrtc.audio.AudioProcessingImplementation
 import org.webrtc.audio.AudioProcessingMode
 import org.webrtc.audio.AudioProcessingOptions
 import org.webrtc.audio.AudioProcessingOptionsResult
+import org.webrtc.audio.AudioProcessingState
 
 /** LiveKitPlugin */
 class LiveKitPlugin : FlutterPlugin, MethodCallHandler {
@@ -271,6 +274,56 @@ class LiveKitPlugin : FlutterPlugin, MethodCallHandler {
     AudioProcessingOptionsResult.Code.APPLY_FAILED -> "applyFailed"
   }
 
+  private fun handleGetAudioProcessingState(result: Result) {
+    val factory = flutterWebRTCPlugin.getPeerConnectionFactory()
+    if (factory == null) {
+      result.success(null)
+      return
+    }
+    result.success(audioProcessingStateToMap(factory.audioProcessingState))
+  }
+
+  private fun audioProcessingModeString(mode: AudioProcessingMode): String = when (mode) {
+    AudioProcessingMode.PLATFORM -> "platform"
+    AudioProcessingMode.SOFTWARE -> "software"
+    AudioProcessingMode.AUTOMATIC -> "auto"
+  }
+
+  private fun audioProcessingImplementationString(implementation: AudioProcessingImplementation): String =
+    when (implementation) {
+      AudioProcessingImplementation.UNKNOWN -> "unknown"
+      AudioProcessingImplementation.DISABLED -> "disabled"
+      AudioProcessingImplementation.SOFTWARE -> "software"
+      AudioProcessingImplementation.PLATFORM -> "platform"
+      AudioProcessingImplementation.SOFTWARE_AND_PLATFORM -> "softwareAndPlatform"
+    }
+
+  private fun requestedToMap(requested: AudioProcessingComponentOptions?): Map<String, Any?>? =
+    requested?.let {
+      mapOf(
+        "enabled" to it.isEnabled,
+        "mode" to audioProcessingModeString(it.mode),
+      )
+    }
+
+  private fun componentToMap(state: AudioProcessingComponentState): Map<String, Any?> = mapOf(
+    "requested" to requestedToMap(state.requested),
+    "isSoftwareResolved" to state.isSoftwareResolved,
+    "isSoftwareActive" to state.isSoftwareActive,
+    "isPlatformAvailable" to state.isPlatformAvailable,
+    "isPlatformResolved" to state.isPlatformResolved,
+    "isPlatformActive" to state.isPlatformActive,
+    "effective" to audioProcessingImplementationString(state.effective),
+  )
+
+  private fun audioProcessingStateToMap(state: AudioProcessingState): Map<String, Any?> = mapOf(
+    "hasAudioProcessingModule" to state.hasAudioProcessingModule,
+    "echoCancellation" to componentToMap(state.echoCancellation),
+    "noiseSuppression" to componentToMap(state.noiseSuppression),
+    "autoGainControl" to componentToMap(state.autoGainControl),
+    "highPassFilter" to componentToMap(state.highPassFilter),
+  )
+
   override fun onMethodCall(@NonNull call: MethodCall, @NonNull result: Result) {
     when (call.method) {
       "startVisualizer" -> {
@@ -293,6 +346,10 @@ class LiveKitPlugin : FlutterPlugin, MethodCallHandler {
         handleSetAudioProcessingOptions(call, result)
       }
 
+      "getAudioProcessingState" -> {
+        handleGetAudioProcessingState(result)
+      }
+
       else -> {
         result.notImplemented()
       }

lib/livekit_client.dart

@@ -41,12 +41,14 @@ export 'src/agent/room_agent.dart';
 export 'src/participant/local.dart';
 export 'src/participant/participant.dart';
 export 'src/participant/remote.dart' hide ParticipantCreationResult;
+export 'src/audio/audio_manager.dart';
 export 'src/audio/audio_frame_capture.dart' show AudioFormat, AudioFrame, AudioFrameCallback, AudioRendererOptions;
 export 'src/preconnect/pre_connect_audio_buffer.dart';
 export 'src/publication/local.dart';
 export 'src/publication/remote.dart';
 export 'src/publication/track_publication.dart';
 export 'src/support/platform.dart';
+export 'src/audio/audio_processing_state.dart';
 export 'src/track/audio_visualizer.dart';
 export 'src/track/local/audio.dart';
 export 'src/track/local/local.dart';

lib/src/audio/audio_manager.dart

@@ -0,0 +1,40 @@
+// Copyright 2024 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import '../support/native.dart';
+import 'audio_processing_state.dart';
+
+/// Controls LiveKit's process-wide platform audio behavior.
+///
+/// The platform audio engine and its audio processing module are global to the
+/// app process, so engine-scoped audio state lives here rather than on a `Room`
+/// or an individual track.
+class AudioManager {
+  AudioManager._();
+
+  static final AudioManager instance = AudioManager._();
+
+  /// Diagnostic snapshot of the resolved audio processing state.
+  ///
+  /// The audio processing module is owned by the native peer connection factory
+  /// and shared engine-wide, so this reflects what is actually applied across
+  /// the engine rather than any single track — use it to verify what a
+  /// `LocalAudioTrack.setAudioProcessingOptions` request resolved to. Returns
+  /// `null` when the native side cannot provide it.
+  Future<AudioProcessingState?> getAudioProcessingState() async {
+    final response = await Native.getAudioProcessingState();
+    if (response == null) return null;
+    return AudioProcessingState.fromMap(response);
+  }
+}

lib/src/audio/audio_processing_state.dart

@@ -0,0 +1,145 @@
+// Copyright 2026 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import '../track/options.dart';
+
+/// The implementation in effect for an audio processing component.
+enum AudioProcessingImplementation {
+  unknown('unknown'),
+  disabled('disabled'),
+  software('software'),
+  platform('platform'),
+  softwareAndPlatform('softwareAndPlatform');
+
+  const AudioProcessingImplementation(this.value);
+
+  final String value;
+
+  static AudioProcessingImplementation fromValue(String? value) => AudioProcessingImplementation.values.firstWhere(
+        (e) => e.value == value,
+        orElse: () => AudioProcessingImplementation.unknown,
+      );
+}
+
+AudioProcessingMode _modeFromValue(String? value) {
+  for (final mode in AudioProcessingMode.values) {
+    if (mode.constraintValue == value) return mode;
+  }
+  return AudioProcessingMode.automatic;
+}
+
+/// The caller's request for one audio processing component: enabled flag plus
+/// implementation mode.
+class AudioProcessingComponentRequest {
+  const AudioProcessingComponentRequest({
+    required this.enabled,
+    required this.mode,
+  });
+
+  factory AudioProcessingComponentRequest.fromMap(Map<dynamic, dynamic> map) => AudioProcessingComponentRequest(
+        enabled: (map['enabled'] as bool?) ?? false,
+        mode: _modeFromValue(map['mode'] as String?),
+      );
+
+  final bool enabled;
+  final AudioProcessingMode mode;
+}
+
+/// Diagnostic state of one audio processing component (echo cancellation,
+/// noise suppression, auto gain control or high-pass filter), observed at
+/// three stages of one pipeline: requested (caller intent) -> resolved (the
+/// engine's per-path decision) -> active (live truth), with [effective] as
+/// the merged verdict.
+class AudioProcessingComponentState {
+  const AudioProcessingComponentState({
+    this.requested,
+    required this.isSoftwareResolved,
+    required this.isSoftwareActive,
+    required this.isPlatformAvailable,
+    required this.isPlatformResolved,
+    required this.isPlatformActive,
+    required this.effective,
+  });
+
+  factory AudioProcessingComponentState.fromMap(Map<dynamic, dynamic> map) => AudioProcessingComponentState(
+        requested: map['requested'] is Map
+            ? AudioProcessingComponentRequest.fromMap(Map<dynamic, dynamic>.from(map['requested'] as Map))
+            : null,
+        isSoftwareResolved: (map['isSoftwareResolved'] as bool?) ?? false,
+        isSoftwareActive: (map['isSoftwareActive'] as bool?) ?? false,
+        isPlatformAvailable: (map['isPlatformAvailable'] as bool?) ?? false,
+        isPlatformResolved: (map['isPlatformResolved'] as bool?) ?? false,
+        isPlatformActive: (map['isPlatformActive'] as bool?) ?? false,
+        effective: AudioProcessingImplementation.fromValue(map['effective'] as String?),
+      );
+
+  /// What the caller most recently requested for this component. Null when no
+  /// audio processing options have ever been applied — "nobody asked".
+  final AudioProcessingComponentRequest? requested;
+
+  /// Whether the resolver decided the WebRTC software (APM) implementation
+  /// should run, after weighing the requested mode against platform
+  /// availability, coupling, and policy.
+  final bool isSoftwareResolved;
+
+  /// Whether APM's live configuration currently has this component enabled.
+  final bool isSoftwareActive;
+
+  /// Whether this device/OS offers a built-in implementation at all.
+  final bool isPlatformAvailable;
+
+  /// Whether the engine asked the OS to run the platform implementation. The
+  /// OS owns the outcome: it can decline, defer, or couple components.
+  final bool isPlatformResolved;
+
+  /// Whether the device reports the platform implementation actually running.
+  final bool isPlatformActive;
+
+  /// The verdict: which implementation is in effect right now.
+  final AudioProcessingImplementation effective;
+}
+
+/// Diagnostic snapshot of the resolved audio processing state for the shared
+/// audio processing module.
+///
+/// The module is owned by the native peer connection factory and shared
+/// engine-wide, so this reflects what is actually applied (per-component
+/// [AudioProcessingComponentState.effective]) versus what was requested — for
+/// the whole engine, not a single track.
+class AudioProcessingState {
+  const AudioProcessingState({
+    required this.hasAudioProcessingModule,
+    required this.echoCancellation,
+    required this.noiseSuppression,
+    required this.autoGainControl,
+    required this.highPassFilter,
+  });
+
+  factory AudioProcessingState.fromMap(Map<dynamic, dynamic> map) => AudioProcessingState(
+        hasAudioProcessingModule: (map['hasAudioProcessingModule'] as bool?) ?? false,
+        echoCancellation:
+            AudioProcessingComponentState.fromMap(Map<dynamic, dynamic>.from(map['echoCancellation'] as Map)),
+        noiseSuppression:
+            AudioProcessingComponentState.fromMap(Map<dynamic, dynamic>.from(map['noiseSuppression'] as Map)),
+        autoGainControl:
+            AudioProcessingComponentState.fromMap(Map<dynamic, dynamic>.from(map['autoGainControl'] as Map)),
+        highPassFilter: AudioProcessingComponentState.fromMap(Map<dynamic, dynamic>.from(map['highPassFilter'] as Map)),
+      );
+
+  final bool hasAudioProcessingModule;
+  final AudioProcessingComponentState echoCancellation;
+  final AudioProcessingComponentState noiseSuppression;
+  final AudioProcessingComponentState autoGainControl;
+  final AudioProcessingComponentState highPassFilter;
+}

lib/src/support/native.dart

@@ -74,6 +74,25 @@ class Native {
     return <String, dynamic>{};
   }
 
+  /// Reads the engine-wide audio processing state from the native peer
+  /// connection factory. Returns `null` when unavailable (e.g. the factory
+  /// does not exist yet, or the platform cannot provide it).
+  @internal
+  static Future<Map<String, dynamic>?> getAudioProcessingState() async {
+    try {
+      final response = await channel.invokeMethod<dynamic>(
+        'getAudioProcessingState',
+        <String, dynamic>{},
+      );
+      if (response is Map) {
+        return response.map((key, value) => MapEntry(key.toString(), value));
+      }
+    } catch (error) {
+      logger.warning('getAudioProcessingState did throw $error');
+    }
+    return null;
+  }
+
   @internal
   static Future<bool> startVisualizer(
     String trackId, {

lib/src/track/local/audio.dart

@@ -176,6 +176,16 @@ class LocalAudioTrack extends LocalTrack with AudioTrack, LocalAudioManagementMi
       await track.setProcessor(options.processor);
     }
 
+    // Per-component processing modes are not part of standard capture
+    // constraints; apply them through the native audio processing path.
+    final processing = options.processing;
+    if (processing.echoCancellationMode != track_options.AudioProcessingMode.automatic ||
+        processing.noiseSuppressionMode != track_options.AudioProcessingMode.automatic ||
+        processing.autoGainControlMode != track_options.AudioProcessingMode.automatic ||
+        processing.highPassFilterMode != track_options.AudioProcessingMode.automatic) {
+      await track.setAudioProcessingOptions(processing);
+    }
+
     return track;
   }
 }

lib/src/track/options.dart

@@ -421,10 +421,6 @@ class AudioCaptureOptions extends LocalTrackOptions implements AudioProcessingOp
         <String, dynamic>{'autoGainControl': false},
         <String, dynamic>{'voiceIsolation': false},
         <String, dynamic>{'googDAEchoCancellation': false},
-        if (!kIsWeb) <String, dynamic>{'echoCancellationMode': echoCancellationMode.constraintValue},
-        if (!kIsWeb) <String, dynamic>{'noiseSuppressionMode': noiseSuppressionMode.constraintValue},
-        if (!kIsWeb) <String, dynamic>{'autoGainControlMode': autoGainControlMode.constraintValue},
-        if (!kIsWeb) <String, dynamic>{'highPassFilterMode': highPassFilterMode.constraintValue},
       ];
     } else {
       /// in we platform it's not possible to provide optional and mandatory parameters.
@@ -443,10 +439,6 @@ class AudioCaptureOptions extends LocalTrackOptions implements AudioProcessingOp
           <String, dynamic>{'googAutoGainControl': autoGainControl},
           <String, dynamic>{'googHighpassFilter': highPassFilter},
           <String, dynamic>{'googTypingNoiseDetection': typingNoiseDetection},
-          if (!kIsWeb) <String, dynamic>{'echoCancellationMode': echoCancellationMode.constraintValue},
-          if (!kIsWeb) <String, dynamic>{'noiseSuppressionMode': noiseSuppressionMode.constraintValue},
-          if (!kIsWeb) <String, dynamic>{'autoGainControlMode': autoGainControlMode.constraintValue},
-          if (!kIsWeb) <String, dynamic>{'highPassFilterMode': highPassFilterMode.constraintValue},
         ];
       }
     }