feat(audio): add AudioManager session and routing APIs (livekit#1108)

## What

Adds first-class, process-wide audio session and routing control through
`AudioManager` on iOS and Android. LiveKit owns the platform audio
session by default, while apps that need exact platform behavior can
switch to manual mode and apply typed session configs.

## API and behavior

- **Automatic by default**: calls need no setup. LiveKit applies a
managed communication policy.
- **iOS automatic mode**: the native WebRTC audio-engine delegate drives
`AVAudioSession` from engine lifecycle events. Listen-only playout uses
`playback`; recording uses `playAndRecord`.
- **Android automatic mode**: LiveKit uses a communication session
through the new AudioSwitch-backed `LKAudioSwitchManager`.
- **Manual mode**: `setAudioSessionOptions(...)` and
`deactivateAudioSession()` switch `AudioManager` to manual mode.
`setAudioSessionManagementMode(AudioSessionManagementMode.automatic)`
hands lifecycle control back to LiveKit.
- **Typed options**: `AudioSessionOptions.communication()` and
`AudioSessionOptions.media()` pre-fill Apple and Android configs, with
per-platform overrides applied verbatim in manual mode.
- **Speaker routing**:
`AudioManager.instance.setSpeakerOutputPreferred(...)` owns speaker
preference and forced speaker routing. Wired and Bluetooth devices still
win unless `force: true`.

## Compatibility

- Existing calls keep working without audio-session setup.
- `Hardware` audio members and `Room.setSpeakerOn(...)` are deprecated
forwarders to `AudioManager`.
- `flutter_webrtc` native audio-session management is disabled so
LiveKit has one owner for the session.
- `bypassVoiceProcessing` now only controls WebRTC voice processing; it
no longer changes the session intent.

## Docs and tests

- Adds `docs/audio.md` and updates the README audio sections.
- Adds coverage for session options, automatic/manual mode transitions,
Apple/Android policy resolution, routing serialization, and engine-state
observation.
- Verified locally with `dart analyze`, `flutter test
test/audio/audio_session_test.dart`, and `flutter test --reporter
compact`.

Author: hiroshihorie

.changes/audio-manager-api

@@ -0,0 +1 @@
+minor type="added" "AudioManager audio session options with engine-driven native lifecycle and platform routing controls"

README.md

@@ -150,30 +150,18 @@ void main() async {
 
 #### Audio Modes
 
-By default, we use the `communication` audio mode on Android which works best for two-way voice communication.
+By default LiveKit uses the `communication` audio mode on Android, which works best for two-way voice communication.
 
-If your app is media playback oriented and does not need the use of the device's microphone, you can use the `media`
-audio mode which will provide better audio quality.
+If your app is media playback oriented and does not need the device's microphone, apply the `media` session yourself. This
+switches `AudioManager` to manual mode, where your app owns the session.
 
 ```dart
-import 'package:flutter_webrtc/flutter_webrtc.dart' as webrtc;
-
-Future<void> _initializeAndroidAudioSettings() async {
-  await webrtc.WebRTC.initialize(options: {
-    'androidAudioConfiguration': webrtc.AndroidAudioConfiguration.media.toMap()
-  });
-  webrtc.Helper.setAndroidAudioConfiguration(
-      webrtc.AndroidAudioConfiguration.media);
-}
-
-void main() async {
-  await _initializeAudioSettings();
-  runApp(const MyApp());
-}
+await AudioManager.instance.setAudioSessionOptions(
+  const AudioSessionOptions.media(),
+);
 ```
 
-Note: the audio routing will become controlled by the system and cannot be manually changed with functions like
-`Hardware.selectAudioOutput`.
+See the [audio session guide](https://github.com/livekit/client-sdk-flutter/blob/main/docs/audio.md) for more.
 
 ### Desktop support
 
@@ -322,6 +310,13 @@ Widget build(BuildContext context) {
 
 Audio tracks are played automatically as long as you are subscribed to them.
 
+LiveKit owns the platform audio session through `AudioManager`. A call is managed automatically with no setup. Speaker routing and, when you need it, manual session control go through the same object. See the [audio session guide](https://github.com/livekit/client-sdk-flutter/blob/main/docs/audio.md) for examples covering the automatic and manual modes, speaker routing, per platform overrides, and migration from the older `Hardware` APIs.
+
+```dart
+// A call is managed automatically. Route to the speaker when you want.
+await AudioManager.instance.setSpeakerOutputPreferred(true);
+```
+
 ### Handling changes
 
 LiveKit client makes it simple to build declarative UI that reacts to state changes. It notifies changes in two ways

android/build.gradle

@@ -18,6 +18,7 @@ allprojects {
     repositories {
         google()
         mavenCentral()
+        maven { url 'https://jitpack.io' }
     }
 }
 
@@ -61,6 +62,9 @@ android {
         testImplementation("org.mockito:mockito-core:5.0.0")
         implementation 'io.github.webrtc-sdk:android:144.7559.09'
         implementation 'io.livekit:noise:2.0.0'
+        // Audio device/focus/mode routing. Pinned to the same revision used by
+        // the LiveKit Android SDK (AudioSwitchHandler).
+        implementation 'com.github.davidliu:audioswitch:039a35aefab7747c557242fa216c9ea11743b604'
     }
 
     testOptions {

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

@@ -0,0 +1,322 @@
+/*
+ * 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.
+ */
+
+package io.livekit.plugin
+
+import android.content.Context
+import android.media.AudioAttributes
+import android.media.AudioManager
+import android.os.Build
+import android.os.Handler
+import android.os.HandlerThread
+import com.twilio.audioswitch.AbstractAudioSwitch
+import com.twilio.audioswitch.AudioDevice
+import com.twilio.audioswitch.AudioSwitch
+import com.twilio.audioswitch.CommDeviceAudioSwitch
+import com.twilio.audioswitch.LegacyAudioSwitch
+
+/**
+ * Manages the Android platform audio session (audio mode, audio focus, and
+ * output routing) for the LiveKit Flutter SDK, built on top of [AudioSwitch].
+ *
+ * This is LiveKit's own port of the audio-handling best practices from the
+ * LiveKit Android SDK (`AudioSwitchHandler`) and flutter_webrtc
+ * (`AudioSwitchManager`), so the Flutter SDK can own the platform audio session
+ * directly instead of delegating to flutter_webrtc's native audio management.
+ *
+ * [AudioSwitch] is not thread-safe, so every interaction with it runs on a
+ * single dedicated [HandlerThread].
+ */
+internal class LKAudioSwitchManager(private val context: Context) {
+  // AudioSwitch is not threadsafe, so confine all access to a single long-lived
+  // thread. The AudioSwitch instance is recreated per active session, while
+  // queued lifecycle work stays serialized on this thread.
+  private val thread = HandlerThread("LKAudioSwitchThread").also { it.start() }
+  private val handler = Handler(thread.looper)
+
+  private var audioSwitch: AbstractAudioSwitch? = null
+  private var isActive = false
+
+  // Configuration. Defaults mirror a communication/VoIP session and match the
+  // AudioSwitchHandler defaults in the LiveKit Android SDK.
+  private var manageAudioFocus = true
+  private var audioMode = AudioManager.MODE_IN_COMMUNICATION
+  private var focusMode = AudioManager.AUDIOFOCUS_GAIN
+  private var audioStreamType = AudioManager.STREAM_VOICE_CALL
+  private var audioAttributeUsageType = AudioAttributes.USAGE_VOICE_COMMUNICATION
+  private var audioAttributeContentType = AudioAttributes.CONTENT_TYPE_SPEECH
+  private var forceHandleAudioRouting = false
+
+  private var speakerOutputPreferred = true
+  private var speakerOutputForced = false
+
+  /**
+   * Apply an audio session configuration. Unspecified keys keep their current
+   * value. When the session is already active, changes that only take effect at
+   * activate() time trigger a deactivate and activate cycle so they apply live.
+   */
+  @Synchronized
+  fun configure(configuration: Map<String, Any?>) {
+    val previous = sessionConfigSnapshot()
+    (configuration["manageAudioFocus"] as? Boolean)?.let { manageAudioFocus = it }
+    audioModeForName(configuration["androidAudioMode"] as? String)?.let { audioMode = it }
+    focusModeForName(configuration["androidAudioFocusMode"] as? String)?.let { focusMode = it }
+    streamTypeForName(configuration["androidAudioStreamType"] as? String)?.let { audioStreamType = it }
+    usageTypeForName(configuration["androidAudioAttributesUsageType"] as? String)?.let { audioAttributeUsageType = it }
+    contentTypeForName(configuration["androidAudioAttributesContentType"] as? String)?.let { audioAttributeContentType = it }
+    (configuration["forceHandleAudioRouting"] as? Boolean)?.let { forceHandleAudioRouting = it }
+    val sessionConfig = sessionConfigSnapshot()
+    val sessionConfigChanged = sessionConfig != previous
+    val speakerRouting = speakerRoutingSnapshot()
+
+    handler.post {
+      val switch = audioSwitch ?: return@post
+      applyConfiguration(switch, sessionConfig)
+      // AudioSwitch applies the audio mode, focus, and attributes at activate()
+      // time, so a live reconfiguration (e.g. communication to media) needs a
+      // deactivate and activate cycle to take effect on an already active
+      // session. Reassert speaker routing afterward.
+      if (isActive && sessionConfigChanged) {
+        switch.deactivate()
+        switch.activate()
+        applySpeakerRouting(switch, speakerRouting)
+      }
+    }
+  }
+
+  // Snapshot of the AudioSwitch properties applied only at activate() time, used
+  // to detect when a live session needs a deactivate and activate cycle to pick
+  // up a configuration change.
+  private fun sessionConfigSnapshot() = SessionConfig(
+    manageAudioFocus = manageAudioFocus,
+    audioMode = audioMode,
+    focusMode = focusMode,
+    audioStreamType = audioStreamType,
+    audioAttributeUsageType = audioAttributeUsageType,
+    audioAttributeContentType = audioAttributeContentType,
+    forceHandleAudioRouting = forceHandleAudioRouting,
+  )
+
+  /** Create (if needed) and activate the audio session: acquire focus, set mode and routing. */
+  @Synchronized
+  fun start() {
+    val sessionConfig = sessionConfigSnapshot()
+    val speakerRouting = speakerRoutingSnapshot()
+    handler.post {
+      val switch = audioSwitch ?: createSwitch(sessionConfig, speakerRouting).also { audioSwitch = it }
+      if (!isActive) {
+        switch.activate()
+        applySpeakerRouting(switch, speakerRouting)
+        isActive = true
+      }
+    }
+  }
+
+  /** Deactivate and tear down the audio session: release focus and restore the previous mode. */
+  @Synchronized
+  fun stop() {
+    handler.post {
+      audioSwitch?.stop()
+      audioSwitch = null
+      isActive = false
+    }
+  }
+
+  /** Final cleanup when the plugin detaches. The manager must not be used after this. */
+  @Synchronized
+  fun dispose() {
+    handler.post {
+      audioSwitch?.stop()
+      audioSwitch = null
+      isActive = false
+      thread.quitSafely()
+    }
+  }
+
+  /**
+   * Prefer routing to/from the speaker, letting a connected headset keep priority
+   * unless [force] is true.
+   */
+  @Synchronized
+  fun setSpeakerphoneOn(enable: Boolean, force: Boolean) {
+    speakerOutputPreferred = enable
+    speakerOutputForced = enable && force
+    val speakerRouting = speakerRoutingSnapshot()
+    handler.post {
+      val switch = audioSwitch ?: return@post
+      applySpeakerRouting(switch, speakerRouting)
+    }
+  }
+
+  private fun createSwitch(
+    sessionConfig: SessionConfig,
+    speakerRouting: SpeakerRouting,
+  ): AbstractAudioSwitch {
+    val focusListener = AudioManager.OnAudioFocusChangeListener { }
+    // API-aware switch selection, matching the LiveKit Android SDK's
+    // AudioSwitchHandler: CommDeviceAudioSwitch uses the modern
+    // AudioManager.setCommunicationDevice routing on API 31+.
+    val switch = when {
+      Build.VERSION.SDK_INT >= Build.VERSION_CODES.S ->
+        CommDeviceAudioSwitch(context, false, focusListener, speakerRouting.preferredDeviceList)
+
+      Build.VERSION.SDK_INT >= Build.VERSION_CODES.M ->
+        AudioSwitch(context, false, focusListener, speakerRouting.preferredDeviceList)
+
+      else ->
+        LegacyAudioSwitch(context, false, focusListener, speakerRouting.preferredDeviceList)
+    }
+    applyConfiguration(switch, sessionConfig)
+    switch.start { _, _ -> }
+    return switch
+  }
+
+  private fun applyConfiguration(switch: AbstractAudioSwitch, sessionConfig: SessionConfig) {
+    switch.manageAudioFocus = sessionConfig.manageAudioFocus
+    switch.audioMode = sessionConfig.audioMode
+    switch.focusMode = sessionConfig.focusMode
+    switch.audioStreamType = sessionConfig.audioStreamType
+    switch.audioAttributeUsageType = sessionConfig.audioAttributeUsageType
+    switch.audioAttributeContentType = sessionConfig.audioAttributeContentType
+    switch.forceHandleAudioRouting = sessionConfig.forceHandleAudioRouting
+  }
+
+  private fun applySpeakerRouting(switch: AbstractAudioSwitch, speakerRouting: SpeakerRouting) {
+    switch.setPreferredDeviceList(speakerRouting.preferredDeviceList)
+    val forcedSpeaker = if (speakerRouting.speakerOutputForced) {
+      switch.availableAudioDevices.firstOrNull { it is AudioDevice.Speakerphone }
+    } else {
+      null
+    }
+    // AudioSwitch selections are sticky. Use them only for forced speaker output.
+    // Clearing the selection lets the preferred-device list handle normal routing
+    // and headset hot-plug priority.
+    switch.selectDevice(forcedSpeaker)
+  }
+
+  private fun speakerRoutingSnapshot() = SpeakerRouting(
+    speakerOutputForced = speakerOutputForced,
+    preferredDeviceList = preferredDeviceList(
+      speakerOutputPreferred = speakerOutputPreferred,
+      speakerOutputForced = speakerOutputForced,
+    ),
+  )
+
+  private fun preferredDeviceList(
+    speakerOutputPreferred: Boolean,
+    speakerOutputForced: Boolean,
+  ): List<Class<out AudioDevice>> =
+    when {
+      speakerOutputForced -> listOf(
+        AudioDevice.Speakerphone::class.java,
+        AudioDevice.BluetoothHeadset::class.java,
+        AudioDevice.WiredHeadset::class.java,
+        AudioDevice.Earpiece::class.java,
+      )
+
+      speakerOutputPreferred -> listOf(
+        AudioDevice.BluetoothHeadset::class.java,
+        AudioDevice.WiredHeadset::class.java,
+        AudioDevice.Speakerphone::class.java,
+        AudioDevice.Earpiece::class.java,
+      )
+
+      else -> listOf(
+        AudioDevice.BluetoothHeadset::class.java,
+        AudioDevice.WiredHeadset::class.java,
+        AudioDevice.Earpiece::class.java,
+        AudioDevice.Speakerphone::class.java,
+      )
+    }
+
+  private data class SessionConfig(
+    val manageAudioFocus: Boolean,
+    val audioMode: Int,
+    val focusMode: Int,
+    val audioStreamType: Int,
+    val audioAttributeUsageType: Int,
+    val audioAttributeContentType: Int,
+    val forceHandleAudioRouting: Boolean,
+  )
+
+  private data class SpeakerRouting(
+    val speakerOutputForced: Boolean,
+    val preferredDeviceList: List<Class<out AudioDevice>>,
+  )
+}
+
+// Map the Flutter-side enum names (see android_audio_session_adapter.dart) to
+// Android framework constants. Ported from flutter_webrtc's AudioUtils.
+
+private fun audioModeForName(name: String?): Int? = when (name) {
+  null -> null
+  "normal" -> AudioManager.MODE_NORMAL
+  "callScreening" -> AudioManager.MODE_CALL_SCREENING
+  "inCall" -> AudioManager.MODE_IN_CALL
+  "inCommunication" -> AudioManager.MODE_IN_COMMUNICATION
+  "ringtone" -> AudioManager.MODE_RINGTONE
+  else -> null
+}
+
+private fun focusModeForName(name: String?): Int? = when (name) {
+  null -> null
+  "gain" -> AudioManager.AUDIOFOCUS_GAIN
+  "gainTransient" -> AudioManager.AUDIOFOCUS_GAIN_TRANSIENT
+  "gainTransientExclusive" -> AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE
+  "gainTransientMayDuck" -> AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK
+  else -> null
+}
+
+private fun streamTypeForName(name: String?): Int? = when (name) {
+  null -> null
+  "accessibility" -> AudioManager.STREAM_ACCESSIBILITY
+  "alarm" -> AudioManager.STREAM_ALARM
+  "dtmf" -> AudioManager.STREAM_DTMF
+  "music" -> AudioManager.STREAM_MUSIC
+  "notification" -> AudioManager.STREAM_NOTIFICATION
+  "ring" -> AudioManager.STREAM_RING
+  "system" -> AudioManager.STREAM_SYSTEM
+  "voiceCall" -> AudioManager.STREAM_VOICE_CALL
+  else -> null
+}
+
+private fun usageTypeForName(name: String?): Int? = when (name) {
+  null -> null
+  "alarm" -> AudioAttributes.USAGE_ALARM
+  "assistanceAccessibility" -> AudioAttributes.USAGE_ASSISTANCE_ACCESSIBILITY
+  "assistanceNavigationGuidance" -> AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE
+  "assistanceSonification" -> AudioAttributes.USAGE_ASSISTANCE_SONIFICATION
+  "assistant" -> AudioAttributes.USAGE_ASSISTANT
+  "game" -> AudioAttributes.USAGE_GAME
+  "media" -> AudioAttributes.USAGE_MEDIA
+  "notification" -> AudioAttributes.USAGE_NOTIFICATION
+  "notificationEvent" -> AudioAttributes.USAGE_NOTIFICATION_EVENT
+  "notificationRingtone" -> AudioAttributes.USAGE_NOTIFICATION_RINGTONE
+  "unknown" -> AudioAttributes.USAGE_UNKNOWN
+  "voiceCommunication" -> AudioAttributes.USAGE_VOICE_COMMUNICATION
+  "voiceCommunicationSignalling" -> AudioAttributes.USAGE_VOICE_COMMUNICATION_SIGNALLING
+  else -> null
+}
+
+private fun contentTypeForName(name: String?): Int? = when (name) {
+  null -> null
+  "movie" -> AudioAttributes.CONTENT_TYPE_MOVIE
+  "music" -> AudioAttributes.CONTENT_TYPE_MUSIC
+  "sonification" -> AudioAttributes.CONTENT_TYPE_SONIFICATION
+  "speech" -> AudioAttributes.CONTENT_TYPE_SPEECH
+  "unknown" -> AudioAttributes.CONTENT_TYPE_UNKNOWN
+  else -> null
+}