feat(audio): add AudioManager microphone mute mode API (#1124)

## Description

Adds `AudioManager.setMicrophoneMuteMode` / `getMicrophoneMuteMode` with
a LiveKit-owned `MicrophoneMuteMode` enum (`voiceProcessing`, `restart`,
`inputMixer`), mirroring the Swift SDK's
`AudioManager.microphoneMuteMode`.

## Background

On iOS/macOS the AVAudioEngine-based ADM defaults to `voiceProcessing`
muting, which plays the platform's mute/unmute sound effect (see
flutter-webrtc/flutter-webrtc#2098). Apps can select `inputMixer` or
`restart` to mute silently.

```dart
await AudioManager.instance.setMicrophoneMuteMode(MicrophoneMuteMode.inputMixer);
```

The mode applies to LiveKit's own mute path: disabling a published local
audio track drives the engine-level microphone mute in webrtc
(`WebRtcVoiceSendChannel::MuteStream` -> `adm->SetMicrophoneMute`). For
the fastest silent mute toggling, combine `inputMixer` with
`AudioCaptureOptions(stopAudioCaptureOnMute: false)` (documented on the
API).

## Implementation notes

- Self-contained: implemented on LiveKit's own plugin and method
channel. `LiveKitPlugin.swift` calls the ADM's `muteMode`/`setMuteMode:`
directly (public API in the WebRTC-SDK pod already linked), so this does
not depend on any flutter_webrtc change or release. The companion
flutter-webrtc PR (flutter-webrtc/flutter-webrtc#2105) exposes the same
control to plain flutter-webrtc users independently.
- No flutter_webrtc types on the public surface: the enum is
LiveKit-owned and named to match the Swift SDK (`restart`, not
`restartEngine`).
- No-op on non-Apple platforms, including for `unknown`, so `set(await
get())` round-trips safely in cross-platform code.
- The setter runs off the platform thread natively, since a mode change
while muted can rebuild the audio engine. Setter errors propagate to the
caller (mirrors the Swift SDK's throwing API), the getter falls back to
`unknown`.
- Engine-wide state, recommended to set once before connecting.

## Testing

- `dart analyze lib test` clean, all 315 tests pass.
- iOS example builds against the released flutter_webrtc 1.5.2 pin, no
dependency override needed.

Author: hiroshihorie

.changes/microphone-mute-mode

@@ -0,0 +1 @@
+minor type="added" "Microphone mute mode control on iOS/macOS"

lib/src/audio/audio_manager.dart

@@ -24,8 +24,10 @@ import 'audio_engine_availability.dart';
 import 'audio_processing_state.dart';
 import 'audio_session.dart';
 import 'audio_session_policy.dart';
+import 'microphone_mute_mode.dart';
 
 export 'audio_engine_availability.dart';
+export 'microphone_mute_mode.dart';
 
 /// Snapshot of the WebRTC audio engine's playout/recording state.
 ///
@@ -359,6 +361,50 @@ class AudioManager {
         automatic: _isAutomaticConfigurationEnabled,
       );
 
+  /// How microphone input is muted on iOS/macOS.
+  ///
+  /// Returns [MicrophoneMuteMode.unknown] on other platforms.
+  Future<MicrophoneMuteMode> getMicrophoneMuteMode() async {
+    if (!lkPlatformIsApple()) return MicrophoneMuteMode.unknown;
+    final mode = await Native.getMicrophoneMuteMode();
+    return MicrophoneMuteMode.values.firstWhere(
+      (value) => value.name == mode,
+      orElse: () => MicrophoneMuteMode.unknown,
+    );
+  }
+
+  /// Sets how microphone input is muted on iOS/macOS. No-op elsewhere,
+  /// including for [MicrophoneMuteMode.unknown], so
+  /// `setMicrophoneMuteMode(await getMicrophoneMuteMode())` round-trips
+  /// safely on every platform.
+  ///
+  /// The default, [MicrophoneMuteMode.voiceProcessing], plays the platform's
+  /// mute/unmute sound effect and keeps the microphone observable for
+  /// muted-talker detection. Use [MicrophoneMuteMode.inputMixer] or
+  /// [MicrophoneMuteMode.restart] to mute silently.
+  ///
+  /// The mode applies whenever the engine mutes microphone input, which
+  /// includes LiveKit's own mute path: muting a published local audio track
+  /// (e.g. `LocalParticipant.setMicrophoneEnabled(false)`) disables the
+  /// track, and WebRTC mutes the engine input using this mode. With the
+  /// default `AudioCaptureOptions.stopAudioCaptureOnMute` (true) the capture
+  /// is additionally stopped after muting. For the fastest silent mute
+  /// toggling combine [MicrophoneMuteMode.inputMixer] with
+  /// `stopAudioCaptureOnMute: false`. Note that [MicrophoneMuteMode.restart]
+  /// restarts the audio engine on every mute toggle, which also
+  /// reconfigures the audio session (audible route changes on e.g.
+  /// Bluetooth headsets).
+  ///
+  /// Throws if the native side rejects the change, so callers never assume
+  /// a muting behavior that is not actually in effect.
+  ///
+  /// This is engine-wide state. Prefer setting it once before connecting.
+  Future<void> setMicrophoneMuteMode(MicrophoneMuteMode mode) async {
+    if (mode == MicrophoneMuteMode.unknown) return;
+    if (!lkPlatformIsApple()) return;
+    await Native.setMicrophoneMuteMode(mode.name);
+  }
+
   /// Diagnostic snapshot of the resolved audio processing state.
   ///
   /// The audio processing module is owned by the native peer connection factory

lib/src/audio/microphone_mute_mode.dart

@@ -0,0 +1,38 @@
+// 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.
+
+/// Strategy used to mute microphone input on iOS/macOS.
+///
+/// Applies to the AVAudioEngine-based audio device module, which is engine-wide
+/// (process-global) state. Set via `AudioManager.setMicrophoneMuteMode`.
+enum MicrophoneMuteMode {
+  /// Mute using Voice Processing I/O's input mute.
+  ///
+  /// Fast, and the OS keeps observing the input so muted-talker detection
+  /// remains possible, but the platform plays its mute/unmute sound effect.
+  voiceProcessing,
+
+  /// Mute by restarting the audio engine without microphone input.
+  ///
+  /// Slower, but silent and stops microphone input entirely while muted.
+  restart,
+
+  /// Mute by muting the engine's input mixer node.
+  ///
+  /// Fast and silent; the engine and audio session keep running.
+  inputMixer,
+
+  /// The mode could not be determined (e.g. unsupported platform).
+  unknown,
+}

lib/src/support/native.dart

@@ -241,6 +241,31 @@ class Native {
     }
   }
 
+  /// Sets how the audio device module mutes microphone input (iOS/macOS).
+  ///
+  /// Unlike most methods in this class this deliberately does not swallow
+  /// platform errors: a failed change means muting behaves differently from
+  /// what the caller selected, so the error must reach the caller.
+  @internal
+  static Future<void> setMicrophoneMuteMode(String mode) async {
+    await channel.invokeMethod<void>(
+      'setMicrophoneMuteMode',
+      <String, dynamic>{'mode': mode},
+    );
+  }
+
+  /// Reads the audio device module's microphone mute mode (iOS/macOS).
+  /// Returns null when the native side cannot provide it.
+  @internal
+  static Future<String?> getMicrophoneMuteMode() async {
+    try {
+      return await channel.invokeMethod<String>('getMicrophoneMuteMode', <String, dynamic>{});
+    } catch (error) {
+      logger.warning('getMicrophoneMuteMode did throw $error');
+      return null;
+    }
+  }
+
   /// Sets whether the WebRTC audio engine is allowed to run (iOS/macOS).
   ///
   /// Unlike most methods in this class this deliberately does not swallow

shared_swift/LiveKitPlugin.swift

@@ -534,6 +534,65 @@ public class LiveKitPlugin: NSObject, FlutterPlugin {
         }
     }
 
+    // MARK: - Microphone mute mode
+
+    static func muteModeString(_ mode: RTCAudioEngineMuteMode) -> String {
+        switch mode {
+        case .voiceProcessing: return "voiceProcessing"
+        case .restartEngine: return "restart"
+        case .inputMixer: return "inputMixer"
+        default: return "unknown"
+        }
+    }
+
+    static func muteMode(from string: String) -> RTCAudioEngineMuteMode {
+        switch string {
+        case "voiceProcessing": return .voiceProcessing
+        case "restart": return .restartEngine
+        case "inputMixer": return .inputMixer
+        default: return .unknown
+        }
+    }
+
+    public func handleSetMicrophoneMuteMode(args: [String: Any?], result: @escaping FlutterResult) {
+        let modeString = args["mode"] as? String ?? ""
+        let mode = LiveKitPlugin.muteMode(from: modeString)
+        if mode == .unknown {
+            result(FlutterError(code: "setMicrophoneMuteMode", message: "invalid mute mode: \(modeString)", details: nil))
+            return
+        }
+
+        guard let adm = FlutterWebRTCPlugin.sharedSingleton()?.peerConnectionFactory?.audioDeviceModule else {
+            result(FlutterError(code: "setMicrophoneMuteMode", message: "audio device module is unavailable", details: nil))
+            return
+        }
+
+        // Changing the mode while muted can rebuild the audio engine, so keep
+        // that work off the platform thread.
+        DispatchQueue.global(qos: .userInitiated).async {
+            let admResult = adm.setMuteMode(mode)
+            DispatchQueue.main.async {
+                if admResult == 0 {
+                    result(nil)
+                } else {
+                    result(FlutterError(
+                        code: "setMicrophoneMuteMode",
+                        message: "Audio engine returned error code: \(admResult)",
+                        details: nil
+                    ))
+                }
+            }
+        }
+    }
+
+    public func handleGetMicrophoneMuteMode(result: @escaping FlutterResult) {
+        guard let adm = FlutterWebRTCPlugin.sharedSingleton()?.peerConnectionFactory?.audioDeviceModule else {
+            result(FlutterError(code: "getMicrophoneMuteMode", message: "audio device module is unavailable", details: nil))
+            return
+        }
+        result(LiveKitPlugin.muteModeString(adm.muteMode))
+    }
+
     public func handleStartLocalRecording(args: [String: Any?], result: @escaping FlutterResult) {
         guard let adm = FlutterWebRTCPlugin.sharedSingleton()?.peerConnectionFactory?.audioDeviceModule else {
             result(FlutterError(code: "rejectedPlatformUnavailable", message: "audio device module is unavailable", details: nil))
@@ -696,6 +755,10 @@ public class LiveKitPlugin: NSObject, FlutterPlugin {
             handleStartAudioRenderer(args: args, result: result)
         case "stopAudioRenderer":
             handleStopAudioRenderer(args: args, result: result)
+        case "setMicrophoneMuteMode":
+            handleSetMicrophoneMuteMode(args: args, result: result)
+        case "getMicrophoneMuteMode":
+            handleGetMicrophoneMuteMode(result: result)
         case "startLocalRecording":
             handleStartLocalRecording(args: args, result: result)
         case "stopLocalRecording":

test/audio/audio_session_test.dart

@@ -591,6 +591,13 @@ void main() {
       expect(calls.single.arguments, {'enable': true, 'force': true});
     });
 
+    test('passes microphone mute mode to platform method', () async {
+      await Native.setMicrophoneMuteMode('inputMixer');
+
+      expect(calls.single.method, 'setMicrophoneMuteMode');
+      expect(calls.single.arguments, {'mode': 'inputMixer'});
+    });
+
     test('passes session activation ownership to Apple management method', () async {
       await Native.setAppleAudioSessionAutomaticManagementEnabled(true, sessionActivationEnabled: false);