feat(audio): engine availability control and external call system session mode

.changes/audio-engine-availability

@@ -0,0 +1 @@
+minor type="added" "Audio engine availability and externalCallSystem mode for CallKit"

lib/src/audio/audio_engine_availability.dart

@@ -0,0 +1,61 @@
+// 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 'package:meta/meta.dart';
+
+/// Whether the WebRTC audio engine is allowed to run, per direction.
+///
+/// This is the highest-priority gate over anything that may start the engine
+/// (enabling the microphone, starting playback of remote audio). Requests
+/// made while a direction is unavailable are not lost: the engine starts as
+/// soon as availability allows.
+///
+/// Used to coordinate with platform call systems that own audio activation
+/// timing, such as CallKit on iOS: keep the engine unavailable until
+/// `provider(didActivate:)` and make it available inside the
+/// activate/deactivate window. See `AudioManager.setEngineAvailability`.
+///
+/// Experimental: this API may change in a future release.
+@experimental
+class AudioEngineAvailability {
+  /// Whether the engine may run its input (microphone / recording) side.
+  final bool isInputAvailable;
+
+  /// Whether the engine may run its output (playout / remote audio) side.
+  final bool isOutputAvailable;
+
+  const AudioEngineAvailability({
+    required this.isInputAvailable,
+    required this.isOutputAvailable,
+  });
+
+  /// Both input and output are available (the default).
+  static const defaultAvailability = AudioEngineAvailability(isInputAvailable: true, isOutputAvailable: true);
+
+  /// Neither input nor output is available. The engine will not run.
+  static const none = AudioEngineAvailability(isInputAvailable: false, isOutputAvailable: false);
+
+  @override
+  bool operator ==(Object other) =>
+      other is AudioEngineAvailability &&
+      other.isInputAvailable == isInputAvailable &&
+      other.isOutputAvailable == isOutputAvailable;
+
+  @override
+  int get hashCode => Object.hash(isInputAvailable, isOutputAvailable);
+
+  @override
+  String toString() =>
+      'AudioEngineAvailability(isInputAvailable: $isInputAvailable, isOutputAvailable: $isOutputAvailable)';
+}

lib/src/audio/audio_manager.dart

@@ -20,10 +20,13 @@ import '../logger.dart';
 import '../support/native.dart';
 import '../support/platform.dart';
 import 'android_audio_session_adapter.dart';
+import 'audio_engine_availability.dart';
 import 'audio_processing_state.dart';
 import 'audio_session.dart';
 import 'audio_session_policy.dart';
 
+export 'audio_engine_availability.dart';
+
 /// Snapshot of the WebRTC audio engine's playout/recording state.
 ///
 /// Surfaced by [AudioManager] from real audio-engine lifecycle events on the
@@ -96,7 +99,11 @@ class AudioManager {
   /// A broadcast stream of audio engine state changes (native engine lifecycle).
   Stream<AudioEngineState> get audioEngineStateStream => _audioEngineStateController.stream;
 
-  bool get _isAutomaticConfigurationEnabled => _managementMode == AudioSessionManagementMode.automatic;
+  // externalCallSystem keeps engine-driven configuration (like automatic) but
+  // the native side never activates/deactivates the session.
+  bool get _isAutomaticConfigurationEnabled => _managementMode != AudioSessionManagementMode.manual;
+
+  bool get _isSessionActivationEnabled => _managementMode != AudioSessionManagementMode.externalCallSystem;
 
   @visibleForTesting
   void resetForTest() {
@@ -141,11 +148,16 @@ class AudioManager {
   /// `LiveKitClient.initialize(initialAudioSessionOptions: ...)` uses this so the
   /// WebRTC initialization-time Android audio attributes and LiveKit's automatic
   /// runtime session policy start from the same intent. Unlike
-  /// [setAudioSessionOptions], this keeps automatic management enabled and does
+  /// [setAudioSessionOptions], this keeps the current management mode and does
   /// not apply native session changes immediately.
+  ///
+  /// Applies under [AudioSessionManagementMode.automatic] and
+  /// [AudioSessionManagementMode.externalCallSystem], both of which drive
+  /// configuration from engine lifecycle. Skipped under
+  /// [AudioSessionManagementMode.manual], where the app owns the options.
   @internal
   void setInitialAudioSessionOptions(AudioSessionOptions options) {
-    if (_managementMode != AudioSessionManagementMode.automatic) {
+    if (!_isAutomaticConfigurationEnabled) {
       return;
     }
     _options = options;
@@ -160,12 +172,46 @@ class AudioManager {
   ///
   /// The speaker preference and force flag are owned by setSpeakerOutputPreferred
   /// and are preserved across this call.
+  ///
+  /// Under [AudioSessionManagementMode.externalCallSystem] the mode is
+  /// preserved: the configuration is applied without activating the session.
   Future<void> setAudioSessionOptions(AudioSessionOptions options) async {
     await _enterManualMode();
     _options = options;
     await _applyCurrentAudioSessionPolicy();
   }
 
+  /// Sets whether the WebRTC audio engine is allowed to run.
+  ///
+  /// This is the highest-priority gate over anything that may start the
+  /// engine (enabling the microphone, remote audio playback). Requests made
+  /// while unavailable are honored as soon as availability allows, so it is
+  /// safe to connect a room and publish the microphone while the engine is
+  /// still gated off.
+  ///
+  /// This is the core of CallKit coordination on iOS: set
+  /// [AudioEngineAvailability.none] before connecting, then flip to
+  /// [AudioEngineAvailability.defaultAvailability] in CallKit's
+  /// `provider(didActivate:)` and back to `none` in `didDeactivate`. Combine
+  /// with [AudioSessionManagementMode.externalCallSystem] so LiveKit never
+  /// activates the session itself.
+  ///
+  /// iOS/macOS only. A no-op elsewhere, so it is always safe to call from
+  /// cross-platform code.
+  ///
+  /// Throws if the native side rejects the change, so callers never assume
+  /// the engine is gated when it is not.
+  ///
+  /// Experimental: this API may change in a future release.
+  @experimental
+  Future<void> setEngineAvailability(AudioEngineAvailability availability) async {
+    if (!lkPlatformIsApple()) return;
+    await Native.setEngineAvailability(
+      isInputAvailable: availability.isInputAvailable,
+      isOutputAvailable: availability.isOutputAvailable,
+    );
+  }
+
   /// Selects whether LiveKit manages the platform audio session automatically.
   ///
   /// In [AudioSessionManagementMode.manual], LiveKit does not update the audio
@@ -186,8 +232,12 @@ class AudioManager {
   }
 
   /// Switches to manual mode if not already, syncing the native side once.
+  ///
+  /// [AudioSessionManagementMode.externalCallSystem] is preserved: an explicit
+  /// configuration under an external call system applies without LiveKit
+  /// taking over the session lifecycle.
   Future<void> _enterManualMode() async {
-    if (_managementMode == AudioSessionManagementMode.manual) return;
+    if (_managementMode != AudioSessionManagementMode.automatic) return;
     _managementMode = AudioSessionManagementMode.manual;
     await _syncAppleAudioSessionManagementMode();
   }
@@ -199,6 +249,10 @@ class AudioManager {
   /// session on its own. Re-apply a configuration with [setAudioSessionOptions],
   /// or hand control back with [setAudioSessionManagementMode].
   Future<void> deactivateAudioSession() async {
+    if (_managementMode == AudioSessionManagementMode.externalCallSystem) {
+      logger.warning('deactivateAudioSession skipped: the external call system owns session activation');
+      return;
+    }
     await _enterManualMode();
     if (lkPlatformIs(PlatformType.iOS)) {
       await Native.deactivateAppleAudioSession();
@@ -265,7 +319,10 @@ class AudioManager {
 
   Future<void> _syncAppleAudioSessionManagementMode() async {
     if (lkPlatformIs(PlatformType.iOS)) {
-      await Native.setAppleAudioSessionAutomaticManagementEnabled(_isAutomaticConfigurationEnabled);
+      await Native.setAppleAudioSessionAutomaticManagementEnabled(
+        _isAutomaticConfigurationEnabled,
+        sessionActivationEnabled: _isSessionActivationEnabled,
+      );
     }
   }
 

lib/src/audio/audio_session.dart

@@ -27,6 +27,31 @@ enum AudioSessionManagementMode {
   /// The app must call AudioManager APIs when it wants to apply a session
   /// configuration.
   manual,
+
+  /// An external telephony system (iOS CallKit / Android Telecom) owns the
+  /// platform audio lifecycle.
+  ///
+  /// On iOS, LiveKit keeps configuring the session's category/mode/options
+  /// from the audio engine lifecycle like [automatic], but never activates or
+  /// deactivates the session, since CallKit owns activation timing. Combine
+  /// with `AudioManager.setEngineAvailability` so the engine only runs inside
+  /// CallKit's `didActivate`/`didDeactivate` window.
+  ///
+  /// On Android this currently behaves like [automatic] for session
+  /// configuration, so a cross-platform app can set this mode once at
+  /// startup: iOS gets the CallKit contract and Android keeps LiveKit's
+  /// normal session management. When Telecom (`androidx.core.telecom`)
+  /// integration lands, this mode will stand down LiveKit's audio-focus and
+  /// routing management, which the Telecom framework owns for registered
+  /// calls.
+  ///
+  /// `AudioManager.deactivateAudioSession` is disabled in this mode on all
+  /// platforms, since releasing platform audio belongs to the external call
+  /// system.
+  ///
+  /// Experimental: this API may change in a future release.
+  @experimental
+  externalCallSystem,
 }
 
 @immutable

lib/src/hardware/hardware.dart

@@ -85,8 +85,7 @@ class Hardware {
   // Backed by [AudioManager] so there is a single source of truth for the
   // management mode. See [AudioManager.setAudioSessionManagementMode].
   @Deprecated('Use AudioManager.instance.managementMode instead')
-  bool get isAutomaticConfigurationEnabled =>
-      AudioManager.instance.managementMode == AudioSessionManagementMode.automatic;
+  bool get isAutomaticConfigurationEnabled => AudioManager.instance.managementMode != AudioSessionManagementMode.manual;
 
   @Deprecated('Use AudioManager.instance.setAudioSessionManagementMode instead')
   void setAutomaticConfigurationEnabled({required bool enable}) {

lib/src/support/native.dart

@@ -219,18 +219,48 @@ class Native {
 
   /// Enable or disable LiveKit's automatic iOS audio-session management from
   /// native WebRTC audio-engine lifecycle callbacks.
+  ///
+  /// [sessionActivationEnabled] controls whether LiveKit may activate or
+  /// deactivate the session at all. When false, LiveKit only configures the
+  /// category/mode and an external system (CallKit) owns activation timing.
   @internal
-  static Future<void> setAppleAudioSessionAutomaticManagementEnabled(bool enabled) async {
+  static Future<void> setAppleAudioSessionAutomaticManagementEnabled(
+    bool enabled, {
+    bool sessionActivationEnabled = true,
+  }) async {
     try {
       await channel.invokeMethod<void>(
         'setAppleAudioSessionAutomaticManagementEnabled',
-        <String, dynamic>{'enabled': enabled},
+        <String, dynamic>{
+          'enabled': enabled,
+          'sessionActivationEnabled': sessionActivationEnabled,
+        },
       );
     } catch (error) {
       logger.warning('setAppleAudioSessionAutomaticManagementEnabled did throw $error');
     }
   }
 
+  /// 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.
+  @internal
+  static Future<void> setEngineAvailability({
+    required bool isInputAvailable,
+    required bool isOutputAvailable,
+  }) async {
+    await channel.invokeMethod<void>(
+      'setEngineAvailability',
+      <String, dynamic>{
+        'isInputAvailable': isInputAvailable,
+        'isOutputAvailable': isOutputAvailable,
+      },
+    );
+  }
+
   @internal
   static Future<bool> startVisualizer(
     String trackId, {

lib/src/support/platform.dart

@@ -23,6 +23,8 @@ bool lkPlatformIsMobile() => [PlatformType.iOS, PlatformType.android].contains(l
 
 bool lkPlatformIsWebMobile() => lkPlatformIsWebMobileImplementation();
 
+bool lkPlatformIsApple() => [PlatformType.iOS, PlatformType.macOS].contains(lkPlatform());
+
 bool lkPlatformIsDesktop() => [
       PlatformType.macOS,
       PlatformType.windows,

lib/src/track/audio_management.dart

@@ -31,8 +31,12 @@ class NativeAudioManagement {
   }
 
   static Future<void> stop() async {
+    // Release mirrors acquire: applyOptionsForConnect starts the Android
+    // audio session in every mode except manual, including externalCallSystem,
+    // which behaves like automatic on Android until Telecom integration owns
+    // focus and routing for registered calls.
     if (lkPlatformIs(PlatformType.android) &&
-        AudioManager.instance.managementMode == AudioSessionManagementMode.automatic) {
+        AudioManager.instance.managementMode != AudioSessionManagementMode.manual) {
       await Native.stopAndroidAudioSession();
     }
   }