Request microphone permission before audio capture starts (#1183)

Flutter counterpart of client-sdk-swift #1085, matching its final merged
behavior. Builds on #1182.

## Why

webrtc-sdk/webrtc#265 (first shipped in `m144.7559.12`) removed the
blocking mic permission request from the AudioEngine device. The
pre-enable check is now passive: it returns
`kAudioEngineErrorInsufficientDevicePermission` (-9000) instead of
prompting, so requesting permission is the SDK's job.

flutter-webrtc still pins `144.7559.10`, so this is not load-bearing
yet. It is harmless there, since `getUserMedia` in flutter-webrtc
already prompts and the status is resolved before the device's blocking
path runs. Once flutter-webrtc bumps past `.12` and the pin here
follows, this is what keeps the current behavior.

## What Flutter already had

flutter-webrtc's `getUserMedia` calls `AVCaptureDevice
requestAccessForMediaType:` and waits for the answer, so every
livekit_client mic path (publish, `restartTrack` on unmute, pre-connect
audio) already prompted before the audio device saw the track. That part
of #1085 needs no port. #1182 already maps -9000 to
`TrackCreateException` for the direct ADM entry points
(`setEngineAvailability`, `startLocalRecording`).

## What this adds

The one behavior from #1085 that was missing: only prompt while the app
can show the alert.

- Native `ensureMicrophoneAccess` in `LiveKitPlugin.swift`: `authorized`
passes, `denied`/`restricted` fail, `notDetermined` requests access. On
iOS the request is only made while
`UIApplication.shared.applicationState == .active`. An inactive or
backgrounded app (locked screen, CallKit wake, app switcher) has the
alert deferred by the system, and awaiting it would suspend
`getUserMedia` and the `_publishRunner` behind it, blocking camera and
screen share publishes for as long as the app stays there. Failing fast
lets the next foreground attempt prompt normally. macOS can present the
prompt regardless, so it always requests. No app extension concern here,
the plugin is app-only.
- The gate is skipped while engine input availability is disabled
(`setEngineAvailability`, the CallKit flow), mirroring the same late fix
in #1085: the audio device module defers opening input entirely and runs
no permission check there, so gating would turn a working background
connect into a `deviceAccessDenied` failure. The check reads the
plugin's tracked availability value, so it also covers gating done
natively before the Flutter engine exists.
- `LocalTrack.createStream` calls it for `AudioCaptureOptions` on Apple
platforms before `getUserMedia`. That is the Flutter choke point:
`LocalAudioTrack.create()`, `restartTrack()` and
`PreConnectAudioBuffer.startRecording()` all reach it. Since the prompt
in Flutter happens at `getUserMedia` rather than at capture start, the
gate sits in front of that instead of in `startCapture` as in Swift.
- Failures surface as `TrackCreateException` through the
`deviceAccessDenied` code introduced in #1182.
- Docs for `withPreConnectAudio` and
`PreConnectAudioBuffer.startRecording` now say permission is requested
at recording start but only while the app is active, so callers running
at app launch should request it up front (matching the final #1085
wording). `Native.setEngineAvailability` documents that permission is
not requested there and must be granted before input availability is
restored.

## Testing

- `flutter analyze`, `flutter test`, `dart format
--set-exit-if-changed`, `import_sorter --exit-if-changed` clean.
- Unit tests cover `Native.ensureMicrophoneAccess` (no-op when
unimplemented, propagates `deviceAccessDenied`). The `createStream` gate
is behind `lkPlatformIsApple()` and not reachable from unit tests.
- The example app builds for iOS (device SDK) and macOS with the change,
re-verified after the rebase onto `main`. On-device run against a fresh
install (first-launch prompt) and a CallKit background wake still to do.

Refs CLT-3243, client-sdk-swift#1085

Author: hiroshihorie

.changes/mic-permission-before-capture

@@ -0,0 +1 @@
+patch type="fixed" "iOS/macOS: request microphone permission before audio capture starts, failing fast with TrackCreateException while the app is not in the foreground"

.changes/preconnect-buffer-cleanup

@@ -0,0 +1 @@
+patch type="fixed" "Pre-connect audio buffer returns to a reusable state when recording fails to start, instead of ignoring retries and leaking the agent timeout"

lib/src/core/room_preconnect.dart

@@ -41,8 +41,12 @@ extension RoomPreConnect on Room {
   /// );
   /// ```
   ///
-  /// - Note: Ensure microphone permissions are granted early in your app
-  ///   lifecycle so pre-connect can start without additional prompts.
+  /// - Note: Requires microphone permission. On iOS/macOS the SDK requests it
+  ///   when recording starts, but only while the app is active, so call this
+  ///   once the app has become active and the system prompt can appear. At app
+  ///   launch the app may not be active yet, so when calling this early,
+  ///   request permission up front (for example with the permission_handler
+  ///   package). Otherwise it throws a [TrackCreateException].
   /// - SeeAlso: [PreConnectAudioBuffer]
   Future<T> withPreConnectAudio<T>(
     Future<T> Function() operation, {

lib/src/preconnect/pre_connect_audio_buffer.dart

@@ -105,8 +105,9 @@ class PreConnectAudioBuffer {
   /// [agentReadyFuture] completes with an error and callers should [reset] the
   /// buffer.
   ///
-  /// Ensure microphone permissions are granted before calling this.
-  /// Audio capture may fail without permissions.
+  /// Requires microphone permission. On iOS/macOS it is requested here while
+  /// the app is in the foreground. Throws a [TrackCreateException] when it is
+  /// denied or cannot be requested (app not in the foreground).
   Future<void> startRecording({
     Duration timeout = const Duration(seconds: 20),
   }) async {
@@ -119,7 +120,14 @@ class PreConnectAudioBuffer {
     // Set up timeout for agent readiness
     _agentReadyManager.setTimer(timeout, timeoutReason: 'Agent did not become ready within timeout');
 
-    _localTrack = await LocalAudioTrack.create();
+    try {
+      _localTrack = await LocalAudioTrack.create();
+    } catch (error) {
+      logger.severe('[Preconnect audio] failed to create local track: $error');
+      _notifyError(error);
+      await stopRecording(withError: error);
+      rethrow;
+    }
     logger.fine('[Preconnect audio] created local track ${_localTrack!.mediaStreamTrack.id}');
 
     final rendererId = Uuid().v4();
@@ -137,7 +145,7 @@ class PreConnectAudioBuffer {
     if (!result) {
       final error = StateError('Failed to start audio renderer ($result)');
       logger.severe('[Preconnect audio] $error');
-      _onError?.call(error);
+      _notifyError(error);
       await stopRecording(withError: error);
       await _localTrack?.stop();
       _localTrack = null;
@@ -149,7 +157,7 @@ class PreConnectAudioBuffer {
       _nativeRecordingStarted = lkPlatformSupportsExplicitAudioRecordingStart();
     } catch (error) {
       logger.severe('[Preconnect audio] failed to start local recording: $error');
-      _onError?.call(error);
+      _notifyError(error);
       await stopRecording(withError: error);
       await _localTrack?.stop();
       _localTrack = null;
@@ -183,7 +191,7 @@ class PreConnectAudioBuffer {
           _agentReadyManager.complete();
         } catch (error) {
           _agentReadyManager.completeError(error);
-          _onError?.call(error);
+          _notifyError(error);
         }
       },
     );
@@ -345,4 +353,15 @@ class PreConnectAudioBuffer {
   void setErrorHandler(PreConnectOnError? onError) {
     _onError = onError;
   }
+
+  /// Invokes the app-provided error callback without letting a throwing
+  /// callback derail the failure path it is called from: cleanup must still
+  /// run and the original error must stay the one callers see.
+  void _notifyError(Object error) {
+    try {
+      _onError?.call(error);
+    } catch (callbackError) {
+      logger.warning('[Preconnect audio] onError callback threw: $callbackError');
+    }
+  }
 }

lib/src/support/native.dart

@@ -266,12 +266,39 @@ class Native {
     }
   }
 
+  /// Requests microphone permission before audio capture starts (iOS/macOS).
+  ///
+  /// The WebRTC audio device only checks the permission and fails when it is
+  /// missing, so the SDK requests it here. On iOS the prompt is only shown while
+  /// the app is active. Throws a [PlatformException] with code
+  /// `deviceAccessDenied` when permission is denied, restricted, or could not be
+  /// requested. A no-op where the platform does not implement it, or while the
+  /// engine's input availability is disabled via [setEngineAvailability] (the
+  /// audio device defers opening input there, so no permission is needed yet).
+  @internal
+  static Future<void> ensureMicrophoneAccess() async {
+    try {
+      await channel.invokeMethod<void>('ensureMicrophoneAccess', <String, dynamic>{});
+    } on PlatformException catch (error) {
+      if (error.code == 'Unimplemented') return;
+      rethrow;
+    } on MissingPluginException {
+      return;
+    }
+  }
+
   /// Sets whether the WebRTC audio engine is allowed to run (iOS/macOS).
   ///
   /// Unlike most methods in this class this deliberately does not swallow
   /// platform errors: a failed availability change means the engine may run
   /// outside the window the caller intended (e.g. CallKit's
   /// didActivate/didDeactivate), so the error must reach the caller.
+  ///
+  /// Microphone permission is not requested here. A recording requested while
+  /// input was unavailable is honored on re-enable, but the audio device only
+  /// passively checks permission at that point, so it must be granted before
+  /// input availability is restored. Otherwise this throws a
+  /// [PlatformException] with code `deviceAccessDenied`.
   @internal
   static Future<void> setEngineAvailability({
     required bool isInputAvailable,

lib/src/support/reusable_completer.dart

@@ -72,6 +72,14 @@ class ReusableCompleter<T> {
       return false;
     }
 
+    if (!_hasPendingListener) {
+      // No one can observe this error: [future] creates a fresh completer once
+      // completed, so delivering it would only surface an unhandled async
+      // error. Mark completed silently, like reset() and dispose() do.
+      _markCompletedWithoutNotify();
+      return true;
+    }
+
     _completeCurrent((completer) => completer.completeError(error, stackTrace));
     return true;
   }

lib/src/track/local/local.dart

@@ -16,17 +16,20 @@ import 'dart:async';
 
 import 'package:flutter/foundation.dart' show kIsWeb;
 import 'package:flutter/material.dart';
+import 'package:flutter/services.dart' show PlatformException;
 
 import 'package:flutter_webrtc/flutter_webrtc.dart' as rtc;
 import 'package:meta/meta.dart';
 
+import '../../audio/audio_engine_error.dart';
 import '../../audio/audio_frame_capture.dart';
 import '../../events.dart';
 import '../../exceptions.dart';
 import '../../extensions.dart';
 import '../../internal/events.dart';
 import '../../logger.dart';
 import '../../participant/remote.dart';
+import '../../support/native.dart';
 import '../../support/platform.dart';
 import '../../types/other.dart';
 import '../options.dart';
@@ -254,6 +257,20 @@ abstract class LocalTrack extends Track {
       'video': options is VideoCaptureOptions ? options.toMediaConstraintsMap() : false,
     };
 
+    if (options is AudioCaptureOptions && lkPlatformIsApple()) {
+      // The WebRTC audio device only checks microphone permission and fails
+      // when it is missing, so the SDK requests it before opening the mic. On
+      // iOS this fails fast while the app is not in the foreground instead of
+      // suspending getUserMedia (and the publish queue behind it) on a prompt
+      // the system cannot show yet.
+      try {
+        await Native.ensureMicrophoneAccess();
+      } on PlatformException catch (error) {
+        throw audioEngineExceptionFrom(error) ??
+            TrackCreateException(error.message ?? 'Microphone permission is not granted');
+      }
+    }
+
     final rtc.MediaStream stream;
     if (options is ScreenShareCaptureOptions) {
       if (kIsWeb) {

shared_swift/LiveKitPlugin.swift

@@ -542,6 +542,63 @@ public class LiveKitPlugin: NSObject, FlutterPlugin {
         }
     }
 
+    // MARK: - Microphone permission
+
+    /// Ensures microphone access is granted before audio capture starts.
+    ///
+    /// The WebRTC audio device does not request microphone permission itself. It
+    /// only checks it and fails with kAudioEngineErrorInsufficientDevicePermission,
+    /// so requesting is the SDK's job. On iOS the request is only made while the
+    /// app is active: while inactive or in the background the system defers the
+    /// alert, and waiting on it would suspend the caller, and the publish queue
+    /// behind it, for as long as the app stays there. Failing fast lets the next
+    /// attempt prompt normally. macOS can present the prompt regardless.
+    ///
+    /// Method channel handlers run on the main thread, which UIApplication needs.
+    public func handleEnsureMicrophoneAccess(result: @escaping FlutterResult) {
+        // With engine input availability disabled (the CallKit flow, see
+        // setEngineAvailability) the audio device module defers opening input
+        // entirely and runs no permission check, so gating here would turn a
+        // working background connect into a deviceAccessDenied failure. The
+        // last-set value is tracked by both the channel and native static
+        // paths, so it covers gating done before the Flutter engine exists.
+        LiveKitPlugin.engineAvailabilityLock.lock()
+        let pendingAvailability = LiveKitPlugin.pendingEngineAvailability
+        LiveKitPlugin.engineAvailabilityLock.unlock()
+        if let pendingAvailability, !pendingAvailability.isInputAvailable.boolValue {
+            result(nil)
+            return
+        }
+
+        let denied = { (message: String) in
+            result(FlutterError(code: LiveKitPlugin.deviceAccessDeniedErrorCode, message: message, details: nil))
+        }
+        switch AVCaptureDevice.authorizationStatus(for: .audio) {
+        case .authorized:
+            result(nil)
+        case .notDetermined:
+            #if !os(macOS)
+            guard UIApplication.shared.applicationState == .active else {
+                denied("Microphone permission could not be requested because the app is not in the foreground. Request it while the app is active before enabling recording.")
+                return
+            }
+            #endif
+            AVCaptureDevice.requestAccess(for: .audio) { granted in
+                DispatchQueue.main.async {
+                    if granted {
+                        result(nil)
+                    } else {
+                        denied("Microphone permission was denied.")
+                    }
+                }
+            }
+        case .denied, .restricted:
+            denied("Microphone permission is not granted.")
+        @unknown default:
+            denied("Microphone permission is not granted.")
+        }
+    }
+
     // MARK: - Microphone mute mode
 
     static func muteModeString(_ mode: RTCAudioEngineMuteMode) -> String {
@@ -768,6 +825,8 @@ public class LiveKitPlugin: NSObject, FlutterPlugin {
             handleStopLocalRecording(result: result)
         case "setEngineAvailability":
             handleSetEngineAvailability(args: args, result: result)
+        case "ensureMicrophoneAccess":
+            handleEnsureMicrophoneAccess(result: result)
         case "setAudioProcessingOptions":
             handleSetAudioProcessingOptions(args: args, result: result)
         case "getAudioProcessingState":
@@ -800,14 +859,18 @@ extension LiveKitPlugin {
     static let kAudioEngineErrorInsufficientDevicePermission = -9000
     static let kAudioEngineErrorAudioSessionInvalidCategory = -9001
 
+    /// FlutterError code for missing microphone permission. Dart maps it to
+    /// TrackCreateException (see audio_engine_error.dart).
+    static let deviceAccessDeniedErrorCode = "deviceAccessDenied"
+
     /// Maps a non-zero audio device module result to a `FlutterError` whose code
     /// the Dart side can act on. Codes with a known cause get their own error
     /// code, mirroring client-sdk-swift's `checkAdmResult`. Anything else falls
     /// back to `fallbackCode` with the raw value in the message.
     static func flutterError(forAudioEngineResult result: Int, fallbackCode: String) -> FlutterError {
         switch result {
         case kAudioEngineErrorInsufficientDevicePermission:
-            return FlutterError(code: "deviceAccessDenied",
+            return FlutterError(code: deviceAccessDeniedErrorCode,
                                 message: "Microphone permission is not granted (audio engine error \(result))",
                                 details: result)
         case kAudioEngineErrorAudioSessionInvalidCategory:

test/audio/audio_session_test.dart

@@ -876,6 +876,37 @@ void main() {
     });
   });
 
+  group('Native.ensureMicrophoneAccess', () {
+    test('is a no-op when the platform does not implement it', () async {
+      TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger.setMockMethodCallHandler(
+        Native.channel,
+        (call) async => throw PlatformException(code: 'Unimplemented'),
+      );
+      await expectLater(Native.ensureMicrophoneAccess(), completes);
+
+      TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger.setMockMethodCallHandler(
+        Native.channel,
+        null,
+      );
+      await expectLater(Native.ensureMicrophoneAccess(), completes);
+    });
+
+    test('propagates a denied permission so callers can map it', () async {
+      TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger.setMockMethodCallHandler(
+        Native.channel,
+        (call) async {
+          expect(call.method, 'ensureMicrophoneAccess');
+          throw PlatformException(code: audioEngineErrorCodeDeviceAccessDenied, message: 'denied');
+        },
+      );
+
+      await expectLater(
+        Native.ensureMicrophoneAccess(),
+        throwsA(isA<PlatformException>().having((error) => error.code, 'code', audioEngineErrorCodeDeviceAccessDenied)),
+      );
+    });
+  });
+
   group('audioEngineExceptionFrom', () {
     test('maps missing microphone permission to TrackCreateException', () {
       final error = audioEngineExceptionFrom(