Request microphone permission before starting audio capture (#1085)

webrtc-sdk/webrtc#265 removed the blocking mic permission request from
the `AudioEngineDevice` pre-enable path. The ADM now does a passive
authorization check and returns
`kAudioEngineErrorInsufficientDevicePermission` (-9000) instead of
prompting, so requesting permission is the SDK's job.

That change shipped in `144.7559.12`, and main is now on
**`150.7871.01`** (#1103, merged into this branch). So this is not
precautionary: without it, microphone publishing fails on every fresh
install, because `.notDetermined` is the state of a newly installed app
and nothing prompts.

Supersedes #1047. Credit to @silviudeac for the original foreground-gate
helper there.

## Where the check goes

`LocalAudioTrack.startCapture()` is the one async choke point every
microphone track path reaches, and it is what actually opens ADM input
via `AudioManager.startLocalRecording`. Publishing arrives through
`Track.start()`, pre-connect recording through
`LocalAudioTrackRecorder.start()`.

```swift
override func startCapture() async throws {
    let needsMicrophonePermission = await RTC.run {
        !AudioManager.shared.isManualRenderingMode && AudioManager.shared.engineAvailability.isInputAvailable
    }
    if needsMicrophonePermission {
        try await LiveKitSDK.ensureMicrophoneAccessForRecording()
    }
    ...
}
```

Manual rendering mode never opens the microphone, and disabled input
availability (the CallKit flow) defers opening it entirely, so neither
needs permission. Both flags are read on the `@RTC` executor (#1101)
since they wait on WebRTC's worker thread.

It is the only gated entry point. Everything else either cannot prompt
or should not.

## Call path coverage

| Entry point | Gated | Behavior when not authorized |
| --- | --- | --- |
| `LocalParticipant.setMicrophone(enabled: true)` | Yes, via `_publish`
and `Track.start()` | Prompts if active, else throws
`.deviceAccessDenied` |
| `LocalParticipant.set(source: .microphone, enabled: true)` | Yes, same
path | Prompts if active, else throws `.deviceAccessDenied` |
| `LocalParticipant.publish(audioTrack:)` with an app-created track |
Yes, via `Track.start()` | Prompts if active, else throws
`.deviceAccessDenied` |
| `Track.start()` called directly on a `LocalAudioTrack` | Yes | Prompts
if active, else throws `.deviceAccessDenied` |
| `Room.withPreConnectAudio { }` | Yes, via `PreConnectAudioBuffer` and
`LocalAudioTrackRecorder.start()` | Prompts if active, else throws
`.deviceAccessDenied` |
| `PreConnectAudioBuffer.startRecording()` | Yes, same path | Prompts if
active, else throws `.deviceAccessDenied` |
| `LocalAudioTrackRecorder.start()` standalone | Yes | Prompts if
active, else throws `.deviceAccessDenied` |
| Manual rendering mode (`setManualRenderingMode(true)` then
`setMicrophone(enabled: true)`) | No, never touches the mic | Publishes
app audio with no permission needed |
| `AudioManager.setRecordingAlwaysPreparedMode(true)` | No, prewarming
is not user-initiated | Fails fast, ADM returns -9000 mapped to
`.deviceAccessDenied` |
| `AudioManager.startLocalRecording(_:)` | No, synchronous so it cannot
prompt | Fails fast, -9000 mapped |
| Publish while `setEngineAvailability(.none)` (CallKit, #815) | Exempt,
input never opens | Publishes with input deferred; permission applies
when availability is restored |
| `AudioManager.setEngineAvailability(_:)` restoring input | No,
synchronous so it cannot prompt | Fails fast, -9000 mapped |
| `LocalAudioTrack.mute()` and `unmute()` | Not applicable | `_unmute`
only restarts video tracks, so mic capture is never reopened |
| WebRTC's implicit `InitRecording` on sender attach | Already gated |
`_publish` calls `Track.start()` before `addTransceiver` |
| `AudioMixRecorder` | Not applicable | No ADM input path |

The ungated `AudioManager` calls already surface -9000 as
`.deviceAccessDenied` through `checkAdmResult`, and their doc comments
now point at `LiveKitSDK.ensureDeviceAccess(for:)` for callers driving
the ADM directly.

## Reading the application state

The SDK only prompts while the app can actually present the alert.
`UIApplication.shared` cannot be referenced here: it does not compile
under `APPLICATION_EXTENSION_API_ONLY=YES`, which CI exercises, and
consumers build this module into broadcast upload extensions via
`LKSampleHandler`. Annotating the reader with
`@available(iOSApplicationExtension, unavailable)` compiles, but
availability propagates to callers and `startCapture` has to stay
extension-available, so it cannot be reached from there.

So the state is read through the Objective-C runtime, behind an
app-extension check. This is the same shape Google's GoogleUtilities
uses in `GULAppDelegateSwizzler.sharedApplication`, which underpins
Firebase: extension guard first, then `respondsToSelector:` before a
dynamically resolved `sharedApplication`. That precedent ships in a
large share of App Store apps, so the dynamic lookup is not an App
Review concern.

The gate is `== .active`. An inactive app (locked screen, call banner,
app switcher, or launch before the scene activates) has the alert
deferred rather than presented, and `requestAccess` has no
cancellation-aware continuation, so waiting there would suspend the
caller for as long as the app stays inactive. Since `startCapture` runs
inside `Participant._publishSerialRunner`, that suspension would also
block camera and screen share publishing. Failing fast avoids it, and
the next attempt prompts normally.

The gate applies only to iOS-family devices: Mac Catalyst is excluded
(like native macOS, the system presents the mic dialog regardless of
frontmost state), matching the `targetEnvironment` exclusion
`CameraCapturer` uses.

## Review fixes

From @pblazej's review:

- Manual rendering mode is no longer gated. `Docs/audio.md` documents it
as publishing app audio without touching the microphone, so it must not
require permission. This restores a condition the pre-#793
implementation had.
- The gate narrowed from `!= .background` to `== .active`, per above. A
timeout was considered and rejected, since it would still hold the
publish serial runner for the length of the timeout before failing.
- `setRecordingAlwaysPreparedMode` is no longer gated.
`LocalMedia.observeDevices()` calls it from `init`, so gating it raised
a permission dialog on view-model construction and silently lost the
prewarm when it failed.
- The `republishAllTracks()` concern is resolved by merging main: #1008
rewrote it with a per-track `do/catch` that records the first error and
rethrows only after the loop, so camera and screen share are republished
even when audio fails.

Round 2, from a deeper review pass:

- The gate also exempts disabled input availability, restoring the
CallKit `setEngineAvailability(.none)` flow where the ADM skips its
permission check and defers input (verified against `m150_release`).
Both flag reads moved onto the `@RTC` executor per #1101.
- Mac Catalyst is excluded from the foreground gate, per above.
- Doc corrections: `withPreConnectAudio` no longer recommends calling at
app launch (the scene is typically still inactive there), and
`setRecordingAlwaysPreparedMode`'s throw is conditioned on the ADM
reporting the missing permission (its passive check is skipped in some
mute modes).

A follow-up branch makes the permission wait cancellation-aware so an
unanswered prompt cannot wedge `stop`/`unpublish`/`disconnect`; it will
be a separate PR on top of this one.

## Verification

- `swift build` and `swift build -Xswiftc -application-extension` pass
- `xcodebuild -destination 'generic/platform=iOS Simulator'
APPLICATION_EXTENSION_API_ONLY=YES` exits 0, mirroring the CI matrix leg
- `AudioManagerAdmResultTests` passes, `swiftlint` clean on the touched
files

Two caveats for reviewers:

- **No new test coverage.** The gate depends on process and application
state that is not reachable from a unit test without a seam. Happy to
add one if wanted.
- **Residual suspension.** If the app is active, the alert is presented,
and the user then backgrounds without answering, the request stays
suspended until they return and answer. That self-heals, unlike the
inactive case this PR removes.

## Follow-up

`Docs/audio.md` should mention that microphone permission is now
requested by the SDK at capture start, and that apps wanting the prompt
earlier should call `LiveKitSDK.ensureDeviceAccess(for:)`.

Refs #815, CLT-3243

Author: hiroshihorie

.changes/mic-permission-foreground

@@ -0,0 +1 @@
+patch type="fixed" "Request microphone permission while foregrounded before enabling recording"

Sources/LiveKit/Audio/Manager/AudioManager.swift

@@ -430,9 +430,12 @@ public class AudioManager: Loggable {
     /// - Parameter enabled: Pass `true` to enable always-prepared recording, or `false` to disable it.
     /// - Parameter audioProcessingOptions: Optional voice-processing options used when prewarming mic input.
     /// - Note: If `audioSession.isAutomaticConfigurationEnabled` is `true`, the session category is configured to `.playAndRecord`.
-    /// - Note: Microphone permission is required. iOS may prompt if not already granted.
+    /// - Note: Microphone permission is required to enable, but is not requested here: prewarming is not a
+    ///   user-initiated capture, so prompting from it would surprise the user. Request it up front with
+    ///   ``LiveKitSDK/ensureDeviceAccess(for:)``, otherwise this throws ``LiveKitError`` of type
+    ///   ``LiveKitErrorType/deviceAccessDenied`` when the audio device module reports the missing permission.
     /// - Note: This persists across ``Room`` lifecycles and connections until disabled.
-    /// - Throws: An error if the underlying audio device module fails to apply the setting.
+    /// - Throws: An error if microphone permission is not granted, or if the underlying audio device module fails to apply the setting.
     public func setRecordingAlwaysPreparedMode(
         _ enabled: Bool,
         audioProcessingOptions: AudioProcessingOptions? = nil,
@@ -449,6 +452,9 @@ public class AudioManager: Loggable {
 
     /// Starts mic input to the SDK even without any ``Room`` or a connection.
     /// Audio buffers will flow into ``LocalAudioTrack/add(audioRenderer:)`` and ``capturePostProcessingDelegate``.
+    ///
+    /// - Note: Being synchronous, this cannot request microphone permission. Ensure permission is granted first (for example via
+    ///   ``LiveKitSDK/ensureDeviceAccess(for:)``), otherwise it throws ``LiveKitError`` of type ``LiveKitErrorType/deviceAccessDenied``.
     public func startLocalRecording(audioProcessingOptions: AudioProcessingOptions? = nil) throws {
         updateExpectedPlatformVoiceProcessing(for: audioProcessingOptions)
         // Always unmute APM if muted by last session.
@@ -481,6 +487,11 @@ public class AudioManager: Loggable {
     /// This is useful when you need to set up connections without touching the audio
     /// device yet (e.g., CallKit flows), or to guarantee the engine remains off
     /// regardless of subscription/publication requests.
+    ///
+    /// - Note: Microphone permission is not requested here. If recording was requested while input
+    ///   was unavailable, ensure permission is granted (for example via
+    ///   ``LiveKitSDK/ensureDeviceAccess(for:)``) before restoring input availability, otherwise
+    ///   this throws ``LiveKitError`` of type ``LiveKitErrorType/deviceAccessDenied``.
     public func setEngineAvailability(_ availability: AudioEngineAvailability) throws {
         let result = RTC.audioDeviceModule.setEngineAvailability(availability.toRTCType())
         try checkAdmResult(code: result)

Sources/LiveKit/Core/Room+PreConnect.swift

@@ -43,7 +43,7 @@ public extension Room {
     /// ```
     ///
     /// - See: ``PreConnectAudioBuffer``
-    /// - Important: Call ``AudioManager/setRecordingAlwaysPreparedMode(_:)`` during app launch sequence to request microphone permissions early.
+    /// - Important: Requires microphone permission. It is requested automatically while the app is active, so call this once the app has become active and the system prompt can appear. At app launch the scene may not be active yet, so when calling this early, request permission first with ``LiveKitSDK/ensureDeviceAccess(for:)``. Otherwise it throws ``LiveKitError`` of type ``LiveKitErrorType/deviceAccessDenied``.
     ///
     func withPreConnectAudio<T>(timeout: TimeInterval = PreConnectAudioBuffer.Constants.timeout,
                                 _ operation: @Sendable @escaping () async throws -> T,

Sources/LiveKit/LiveKit+DeviceHelpers.swift

@@ -16,6 +16,35 @@
 
 import AVFoundation
 
+#if canImport(UIKit) && (os(iOS) || os(visionOS) || os(tvOS)) && !targetEnvironment(macCatalyst)
+import UIKit
+#endif
+
+// Whether this process is an app extension, which cannot present a permission dialog. The broadcast
+// upload extension the SDK supports (see `LKSampleHandler`) is headless, so no prompt can appear.
+// The `.appex` bundle suffix is Apple's documented way to detect an extension process.
+private let kIsAppExtension = Bundle.main.bundleURL.pathExtension == "appex"
+
+#if canImport(UIKit) && (os(iOS) || os(visionOS) || os(tvOS)) && !targetEnvironment(macCatalyst)
+// Resolves `UIApplication.shared` through the Objective-C runtime because referencing it directly
+// does not compile with APPLICATION_EXTENSION_API_ONLY=YES, and consumers build this module into
+// broadcast upload extensions. An extension process is prohibited from calling `sharedApplication`,
+// so callers must be guarded by `kIsAppExtension`. The selector itself would resolve there too.
+@MainActor
+private func isApplicationForegrounded() -> Bool {
+    let selector = NSSelectorFromString("sharedApplication")
+    guard UIApplication.responds(to: selector),
+          let shared = UIApplication.perform(selector),
+          let application = shared.takeUnretainedValue() as? UIApplication
+    else { return false }
+    // Only .active can actually present the alert. While .inactive (locked screen, call banner, app
+    // switcher, or launch before the scene activates) the system defers it, and requestAccess has no
+    // cancellation-aware continuation, so waiting there would suspend the caller for as long as the
+    // app stays inactive. Failing fast instead lets the next attempt prompt normally.
+    return application.applicationState == .active
+}
+#endif
+
 public extension LiveKitSDK {
     /// Helper method to ensure authorization for video(camera) / audio(microphone) permissions in a single call.
     static func ensureDeviceAccess(for types: Set<AVMediaType>) async -> Bool {
@@ -27,7 +56,12 @@ public extension LiveKitSDK {
             let status = AVCaptureDevice.authorizationStatus(for: type)
             switch status {
             case .notDetermined:
-                if await !(AVCaptureDevice.requestAccess(for: type)) {
+                // Explicit continuation instead of the synthesized async overload, which hits a
+                // mixed Swift 5/6 thunk-coalescing crash before Swift 6.3 (swiftlang/swift#81846).
+                let granted = await withCheckedContinuation { continuation in
+                    AVCaptureDevice.requestAccess(for: type) { continuation.resume(returning: $0) }
+                }
+                if !granted {
                     return false
                 }
             case .restricted, .denied: return false
@@ -82,3 +116,55 @@ public extension LiveKitSDK {
         return granted
     }
 }
+
+extension LiveKitSDK {
+    /// Requests authorization for the given media types, but only while the app can present the
+    /// system permission dialog.
+    ///
+    /// An app extension always returns `false` without prompting, since it cannot present the dialog.
+    ///
+    /// On iOS-family platforms this also returns `false` without prompting unless the app is active, so
+    /// a caller woken in the background (for example by CallKit) does not wait on an alert that cannot
+    /// appear. An inactive app is treated the same way, since the system defers the alert there and
+    /// waiting would suspend the caller. On macOS and Mac Catalyst the prompt can be presented
+    /// regardless, so this otherwise behaves like ``ensureDeviceAccess(for:)``.
+    static func ensureDeviceAccessIfForegrounded(for types: Set<AVMediaType>) async -> Bool {
+        if kIsAppExtension { return false }
+        #if canImport(UIKit) && (os(iOS) || os(visionOS) || os(tvOS)) && !targetEnvironment(macCatalyst)
+        guard await isApplicationForegrounded() else { return false }
+        #endif
+        return await ensureDeviceAccess(for: types)
+    }
+
+    /// Ensures microphone access is granted before enabling recording.
+    ///
+    /// The WebRTC audio device no longer requests microphone permission implicitly, so the SDK
+    /// requests it here while the app is foregrounded. When permission is undetermined and the app
+    /// cannot present the prompt (backgrounded or app extension), this fails fast instead of blocking.
+    ///
+    /// - Throws: ``LiveKitError`` of type ``LiveKitErrorType/deviceAccessDenied`` when microphone
+    ///   access is denied or restricted, or when permission is undetermined and cannot be requested.
+    static func ensureMicrophoneAccessForRecording() async throws {
+        switch AVCaptureDevice.authorizationStatus(for: .audio) {
+        case .authorized:
+            return
+        case .notDetermined:
+            guard await ensureDeviceAccessIfForegrounded(for: [.audio]) else {
+                // Distinguish "could not present the prompt" from "the user denied it".
+                if AVCaptureDevice.authorizationStatus(for: .audio) == .notDetermined {
+                    if kIsAppExtension {
+                        throw LiveKitError(.deviceAccessDenied,
+                                           message: "Microphone permission cannot be requested from an app extension. Request it in the host app before enabling recording.")
+                    }
+                    throw LiveKitError(.deviceAccessDenied,
+                                       message: "Microphone permission could not be requested. Request it while the app is in the foreground before enabling recording.")
+                }
+                throw LiveKitError(.deviceAccessDenied, message: "Microphone permission was denied.")
+            }
+        case .denied, .restricted:
+            throw LiveKitError(.deviceAccessDenied, message: "Microphone permission is not granted.")
+        @unknown default:
+            throw LiveKitError(.deviceAccessDenied, message: "Microphone permission is not granted.")
+        }
+    }
+}

Sources/LiveKit/Track/Local/LocalAudioTrack.swift

@@ -142,6 +142,17 @@ public class LocalAudioTrack: Track, LocalTrackProtocol, AudioTrackProtocol, @un
     // MARK: - Internal
 
     override func startCapture() async throws {
+        // The WebRTC audio device no longer prompts for mic permission (see webrtc-sdk#265),
+        // so request it here while foregrounded before starting recording. Manual rendering mode
+        // publishes app audio without ever opening the microphone, and disabled input availability
+        // (CallKit flows, see setEngineAvailability) defers opening it entirely, so neither needs
+        // permission. Reading these flags waits on WebRTC's worker thread, hence the RTC hop.
+        let needsMicrophonePermission = await RTC.run {
+            !AudioManager.shared.isManualRenderingMode && AudioManager.shared.engineAvailability.isInputAvailable
+        }
+        if needsMicrophonePermission {
+            try await LiveKitSDK.ensureMicrophoneAccessForRecording()
+        }
         // AudioDeviceModule's InitRecording() and StartRecording() automatically get called by WebRTC, but
         // explicitly init & start it early to detect audio engine failures (mic not accessible for some reason, etc.).
         let audioProcessingOptions = captureOptions.audioProcessing