Skip to content

Commit faa5b0b

Browse files
Add Android initial audio session options (#1117)
## Summary - Add `LiveKitClient.initialize(initialAudioSessionOptions: ...)` for Android WebRTC audio-device initialization. - Seed Android automatic audio-session policy from the same initial options so playback-first apps do not need to immediately call `AudioManager.setAudioSessionOptions(...)` with the same preset. - Rename the playback preset to `AudioSessionOptions.mediaPlayback()` for clearer intent. - Avoid sticky Android speaker routing when updating speaker preference. - Update audio session docs and change entry. ## Runtime behavior Android uses `AudioSessionOptions` in two places with different timing: | API | Timing | What changes | | --- | --- | --- | | `LiveKitClient.initialize(initialAudioSessionOptions: ...)` | Before WebRTC initializes. | Passes Android audio configuration into flutter_webrtc/WebRTC ADM creation. This is where WebRTC playout `AudioAttributes` such as `usageType` and `contentType` are set. It also seeds LiveKit's automatic Android session policy. | | `AudioManager.instance.setAudioSessionOptions(...)` | Runtime. | Replaces LiveKit's stored session policy, switches to manual management, and applies LiveKit's platform session behavior: Android audio mode, audio focus mode, stream type, focus ownership, routing handler policy, and iOS category/options/mode. | The important Android limitation is that WebRTC playout `AudioAttributes` are still initialization-time configuration. Calling `AudioManager.setAudioSessionOptions(...)` at runtime applies LiveKit's platform session policy, but it does not mutate the `AudioAttributes` on an already-created WebRTC audio device module. For playback-first Android apps that need media volume/routing from WebRTC playout, pass `AudioSessionOptions.mediaPlayback()` to `LiveKitClient.initialize(...)` before connecting. ## Validation - `flutter test --no-pub test/audio/audio_session_test.dart` - `flutter analyze --no-pub --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
1 parent d1fe342 commit faa5b0b

9 files changed

Lines changed: 216 additions & 52 deletions

File tree

‎.changes/android-media-routing‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
patch type="fixed" "Apply Android media audio attributes during WebRTC initialization"
2+
patch type="fixed" "Use initialization audio options as the default Android session policy"
3+
patch type="fixed" "Avoid sticky Android speaker routing when updating route preference"

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

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -195,20 +195,14 @@ internal class LKAudioSwitchManager(private val context: Context) {
195195
}
196196

197197
private fun applySpeakerRouting(switch: AbstractAudioSwitch, speakerRouting: SpeakerRouting) {
198+
// AudioSwitch treats selectDevice(null) as "select no device"; it does not
199+
// recompute the best route from the preferred-device list. Keep routing
200+
// automatic here so normal preference and forced-speaker priority both
201+
// follow device hot-plug changes without leaving a sticky selected device.
198202
switch.setPreferredDeviceList(speakerRouting.preferredDeviceList)
199-
val forcedSpeaker = if (speakerRouting.speakerOutputForced) {
200-
switch.availableAudioDevices.firstOrNull { it is AudioDevice.Speakerphone }
201-
} else {
202-
null
203-
}
204-
// AudioSwitch selections are sticky. Use them only for forced speaker output.
205-
// Clearing the selection lets the preferred-device list handle normal routing
206-
// and headset hot-plug priority.
207-
switch.selectDevice(forcedSpeaker)
208203
}
209204

210205
private fun speakerRoutingSnapshot() = SpeakerRouting(
211-
speakerOutputForced = speakerOutputForced,
212206
preferredDeviceList = preferredDeviceList(
213207
speakerOutputPreferred = speakerOutputPreferred,
214208
speakerOutputForced = speakerOutputForced,
@@ -253,7 +247,6 @@ internal class LKAudioSwitchManager(private val context: Context) {
253247
)
254248

255249
private data class SpeakerRouting(
256-
val speakerOutputForced: Boolean,
257250
val preferredDeviceList: List<Class<out AudioDevice>>,
258251
)
259252
}

‎docs/audio.md‎

Lines changed: 33 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ LiveKit disables flutter_webrtc's own native audio management automatically when
1212

1313
Speaker output is preferred by default, but a wired or Bluetooth headset still wins over the speaker. Forced speaker output is off, so the speaker is never forced over a connected headset unless you ask for it.
1414

15+
The media playback preset (`AudioSessionOptions.mediaPlayback()`) is for playback-first experiences such as viewer-only live streams. On Android, pass it to `LiveKitClient.initialize` before WebRTC initializes when you need the WebRTC audio device module to use media mode and media volume. This also seeds LiveKit's automatic runtime session policy until you explicitly replace it with `AudioManager.instance.setAudioSessionOptions(...)`. Runtime session updates apply LiveKit's platform session policy, but WebRTC playout `AudioAttributes` are currently initialized when the audio device module is created.
16+
1517
The default audio capture options apply standard voice processing, so echo cancellation, noise suppression, and auto gain control are on and the high pass filter is off. You can change this per track with `AudioProcessingOptions`.
1618

1719
On macOS the audio engine state is reported but no `AVAudioSession` is configured. On web, Windows, and Linux the session APIs do not configure native audio. Speaker switching is available only on iOS and Android, where `AudioManager.instance.canSwitchSpeakerphone` is true.
@@ -27,24 +29,45 @@ import 'package:livekit_client/livekit_client.dart';
2729
2830
// Take manual control and apply a media playback session.
2931
await AudioManager.instance.setAudioSessionOptions(
30-
const AudioSessionOptions.media(),
32+
const AudioSessionOptions.mediaPlayback(),
33+
);
34+
```
35+
36+
On Android, media output type has one WebRTC initialization-time piece and one LiveKit runtime-session piece. For playback-first apps, initialize WebRTC with the media intent before connecting:
37+
38+
```dart
39+
await LiveKitClient.initialize(
40+
initialAudioSessionOptions: const AudioSessionOptions.mediaPlayback(),
3141
);
3242
```
3343

34-
See the next section for the full rule. Apply options before connecting when you can.
44+
This seeds both WebRTC's initialization-time playout attributes and LiveKit's automatic runtime session policy. See the next section for the full rule. Apply options before connecting when you can.
45+
46+
## Configuration timing
47+
48+
`AudioSessionOptions` are used in two places on Android:
49+
50+
| API | Timing | What it can update |
51+
| --- | --- | --- |
52+
| `LiveKitClient.initialize(initialAudioSessionOptions: ...)` | Before WebRTC initializes. | WebRTC audio device module playout `AudioAttributes`, and LiveKit's initial automatic runtime session policy. Today WebRTC uses the Android `usageType` and `contentType` fields, for example `USAGE_MEDIA` and `CONTENT_TYPE_UNKNOWN` from `AudioSessionOptions.mediaPlayback()`. |
53+
| `AudioManager.instance.setAudioSessionOptions(...)` | Runtime. | Explicitly replaces the stored session options, switches to manual management, and applies LiveKit's platform session policy: Android audio mode, audio focus mode, stream type, focus ownership, routing handler policy, and iOS category/options/mode. |
54+
55+
Most fields in `AudioSessionOptions` are runtime session policy and can be applied again with `AudioManager.instance.setAudioSessionOptions(...)`. The exception is Android WebRTC playout attributes: changing `AndroidAudioSessionConfiguration.usageType` or `contentType` at runtime updates LiveKit's session/focus handler, but it does not change the `AudioAttributes` of an already-created WebRTC audio device module. Pass those options to `LiveKitClient.initialize(...)` before WebRTC initializes when they must affect playout volume/routing. You do not need to call `setAudioSessionOptions(...)` with the same options just to make LiveKit use them during automatic session management.
56+
57+
We plan to make Android WebRTC playout attributes runtime-updatable in a future SDK/WebRTC integration if the native layer can safely update the stored attributes and recreate playout with acceptable behavior. Until then, treat WebRTC playout `AudioAttributes` as initialization-time configuration.
3558

3659
## Automatic vs manual mode
3760

3861
The two modes differ in who owns the session lifecycle.
3962

40-
In automatic mode (the default) LiveKit manages the session from room, connect, and engine lifecycle and chooses the configuration for you. It does not take session options in this mode.
63+
In automatic mode (the default) LiveKit manages the session from room, connect, and engine lifecycle. On iOS it derives the active category/mode from the current audio engine state. On Android it uses the current session intent, defaulting to communication and optionally seeded by `LiveKitClient.initialize(initialAudioSessionOptions: ...)`.
4164

4265
In manual mode LiveKit does not touch the session on its own, and your app owns it. Enter manual mode when you need to apply a fixed platform configuration or deactivate the session yourself.
4366

4467
```dart
4568
// Apply a fixed config. This enters manual mode.
4669
await AudioManager.instance.setAudioSessionOptions(
47-
const AudioSessionOptions.media(),
70+
const AudioSessionOptions.mediaPlayback(),
4871
);
4972
5073
// Later, hand control back to LiveKit.
@@ -84,7 +107,9 @@ await AudioManager.instance.setSpeakerOutputPreferred(true, force: true);
84107
await AudioManager.instance.setSpeakerOutputPreferred(false);
85108
```
86109

87-
Speaker routing is independent of the management mode and does not switch it. On Android and in iOS automatic mode, LiveKit applies the preference through its managed route policy. In iOS manual mode, the fixed Apple config you apply owns non-forced receiver vs speaker behavior. `force: true` still uses Apple's speaker override when the active category is `playAndRecord`. Read the current preference through `AudioManager.instance.isSpeakerOutputPreferred` and `AudioManager.instance.isSpeakerOutputForced`. `AudioManager.instance.canSwitchSpeakerphone` is true on iOS and Android.
110+
Speaker routing is independent of the management mode and does not switch it. In Android communication/call sessions and in iOS automatic mode, LiveKit applies the preference through its managed route policy. In iOS manual mode, the fixed Apple config you apply owns non-forced receiver vs speaker behavior. `force: true` still uses Apple's speaker override when the active category is `playAndRecord`. Read the current preference through `AudioManager.instance.isSpeakerOutputPreferred` and `AudioManager.instance.isSpeakerOutputForced`. `AudioManager.instance.canSwitchSpeakerphone` is true on iOS and Android.
111+
112+
On Android, LiveKit speaker routing is a communication/call routing policy. Media sessions use Android's normal media routing. Pass `AudioSessionOptions.mediaPlayback()` to `LiveKitClient.initialize` before WebRTC initializes when the WebRTC audio device module should use media attributes.
88113

89114
`Room.setSpeakerOn(...)` is deprecated and forwards to `AudioManager.instance.setSpeakerOutputPreferred`. You can also set an initial preference through `RoomOptions` (`defaultAudioOutputOptions.speakerOn`) before connecting, which LiveKit applies when the session starts.
90115

@@ -148,7 +173,7 @@ print('echo cancellation in effect: ${state?.echoCancellation.effective}');
148173

149174
## Per platform overrides
150175

151-
When the preset constructors are not enough you can pin exact platform values. Supplying options through `setAudioSessionOptions` switches to manual mode, so these configs are a manual-mode tool. `AudioSessionOptions.communication()` and `AudioSessionOptions.media()` pre-fill Apple and Android configs. Passing `apple` or `android` replaces that platform config rather than merging with the preset.
176+
When the preset constructors are not enough you can pin exact platform values. Supplying options through `setAudioSessionOptions` switches to manual mode, so these configs are a manual-mode tool. `AudioSessionOptions.communication()` and `AudioSessionOptions.mediaPlayback()` pre-fill Apple and Android configs. Passing `apple` or `android` replaces that platform config rather than merging with the preset.
152177

153178
```dart
154179
await AudioManager.instance.setAudioSessionOptions(
@@ -188,15 +213,15 @@ final clearedMode = updated.copyWith(
188213
);
189214
```
190215

191-
Create a new `AudioSessionOptions.communication()` or `AudioSessionOptions.media()` when you want to start from a different preset config.
216+
Create a new `AudioSessionOptions.communication()` or `AudioSessionOptions.mediaPlayback()` when you want to start from a different preset config.
192217

193218
## Platform support
194219

195220
| Platform | Audio session | Speaker routing | Engine state |
196221
| --- | --- | --- | --- |
197222
| iOS | Automatic mode follows live engine state. Manual mode applies your Apple config verbatim. | Yes. Normal preference respects wired and Bluetooth devices. Forced speaker uses Apple's speaker override while the active category is `playAndRecord`. | Yes, from native WebRTC engine events. |
198223
| macOS | Not configured. There is no `AVAudioSession`. | No. `canSwitchSpeakerphone` is false. | Yes, the same engine events are reported. |
199-
| Android | Automatic mode uses the communication session (in-communication mode, voice call stream). A media session is available in manual mode. Managed through LiveKit's AudioSwitch handler. | Yes. Normal preference orders headsets before the speaker. Forced speaker selects the speaker device. | Not reported, the Dart state stays idle. |
224+
| Android | Automatic mode uses the current session intent, seeded by `LiveKitClient.initialize(initialAudioSessionOptions: ...)` and defaulting to communication. Pass media options before WebRTC initializes when the WebRTC audio device module should use media mode/volume. | Yes for communication/call routing. Media playback follows Android media routing. | Not reported, the Dart state stays idle. |
200225
| Web, Windows, Linux | Not configured. | No. `canSwitchSpeakerphone` is false. | Not reported. |
201226

202227
On iOS automatic mode, listen only playout uses `playback`. When recording starts, LiveKit reapplies the session as `playAndRecord`. In manual mode, non-forced receiver vs speaker behavior comes from the Apple config you applied.

‎lib/src/audio/audio_manager.dart‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,21 @@ class AudioManager {
136136
_audioEngineStateController.add(nextState);
137137
}
138138

139+
/// Seeds the initial session intent without taking over the session lifecycle.
140+
///
141+
/// `LiveKitClient.initialize(initialAudioSessionOptions: ...)` uses this so the
142+
/// WebRTC initialization-time Android audio attributes and LiveKit's automatic
143+
/// runtime session policy start from the same intent. Unlike
144+
/// [setAudioSessionOptions], this keeps automatic management enabled and does
145+
/// not apply native session changes immediately.
146+
@internal
147+
void setInitialAudioSessionOptions(AudioSessionOptions options) {
148+
if (_managementMode != AudioSessionManagementMode.automatic) {
149+
return;
150+
}
151+
_options = options;
152+
}
153+
139154
/// Applies an explicit audio session configuration and switches to manual mode.
140155
///
141156
/// Calling this puts [AudioManager] in [AudioSessionManagementMode.manual]:

‎lib/src/audio/audio_session.dart‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -55,11 +55,12 @@ class AudioSessionOptions {
5555

5656
/// One-way media playback preset.
5757
///
58-
/// This pre-fills playback-oriented platform policies. Apple playback policy
59-
/// leaves routing to the platform, while Android speaker routing remains a
60-
/// runtime preference. Override [apple] or [android] for exact platform
61-
/// behavior.
62-
const AudioSessionOptions.media({
58+
/// This pre-fills playback-oriented platform policies. Apple and Android
59+
/// media routing are platform-owned. On Android, pass this to
60+
/// `LiveKitClient.initialize` before WebRTC initializes when WebRTC playout
61+
/// should use media `AudioAttributes`; the same value seeds LiveKit's initial
62+
/// automatic runtime media session policy.
63+
const AudioSessionOptions.mediaPlayback({
6364
AppleAudioSessionConfiguration apple = AppleAudioSessionConfiguration.media,
6465
AndroidAudioSessionConfiguration android = AndroidAudioSessionConfiguration.media,
6566
}) : this._(apple: apple, android: android);

‎lib/src/audio/audio_session_policy.dart‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,9 +53,10 @@ class ResolvedAudioSessionPolicy {
5353
}
5454

5555
AndroidAudioSessionConfiguration get androidConfiguration {
56-
if (automatic) {
57-
return AndroidAudioSessionConfiguration.communication;
58-
}
56+
// In automatic mode LiveKit still owns activation timing, focus/routing
57+
// lifecycle, and speaker preference. The Android session intent itself is
58+
// the current AudioSessionOptions value, seeded by LiveKitClient.initialize
59+
// or replaced explicitly by AudioManager.setAudioSessionOptions.
5960
return options.android;
6061
}
6162
}

‎lib/src/livekit.dart‎

Lines changed: 31 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,10 @@
1515
import 'package:flutter_webrtc/flutter_webrtc.dart' as rtc;
1616

1717
import 'audio/audio_manager.dart';
18+
import 'audio/audio_session.dart';
1819
import 'support/native.dart';
19-
import 'support/platform.dart' show lkPlatformIsMobile;
20+
import 'support/platform.dart' show PlatformType, lkPlatformIs, lkPlatformIsMobile;
21+
import 'support/webrtc_initialize_options.dart';
2022

2123
/// Main entry point to connect to a room.
2224
/// {@category Room}
@@ -26,25 +28,45 @@ class LiveKitClient {
2628
/// Initialize the WebRTC plugin.
2729
///
2830
/// Optional: call once at startup to enable [bypassVoiceProcessing] before
29-
/// connecting. Otherwise WebRTC initializes lazily with defaults.
31+
/// connecting, or to apply Android [initialAudioSessionOptions] before WebRTC
32+
/// creates its audio device module. Otherwise WebRTC initializes lazily with
33+
/// defaults.
3034
///
3135
/// LiveKit owns the platform audio session, and flutter_webrtc's own native
3236
/// audio management is disabled automatically when the LiveKit plugin loads
3337
/// (done natively at registration), so that does not depend on this call.
3438
///
35-
/// Configure audio-session behavior through [AudioManager] before connecting,
36-
/// e.g. `await AudioManager.instance.setAudioSessionManagementMode(...)` and
39+
/// Configure explicit runtime audio-session behavior through [AudioManager]
40+
/// before connecting, e.g.
41+
/// `await AudioManager.instance.setAudioSessionManagementMode(...)` and
3742
/// `await AudioManager.instance.setAudioSessionOptions(...)`.
43+
///
44+
/// [initialAudioSessionOptions] currently affects Android's WebRTC
45+
/// initialization-time playout attributes, such as media vs voice
46+
/// communication usage. It also seeds [AudioManager]'s initial automatic
47+
/// runtime session policy until the app explicitly replaces it with
48+
/// [AudioManager.setAudioSessionOptions]. A future SDK/WebRTC integration may
49+
/// make those Android playout attributes runtime-updatable; for now, pass them
50+
/// here before WebRTC initializes.
3851
static Future<void> initialize({
3952
bool bypassVoiceProcessing = false,
53+
AudioSessionOptions? initialAudioSessionOptions,
4054
}) async {
4155
if (lkPlatformIsMobile()) {
42-
// bypassVoiceProcessing controls only WebRTC voice processing, not the
43-
// session intent. The audio session is owned by AudioManager.
56+
// bypassVoiceProcessing controls only WebRTC voice processing. Android
57+
// playout attributes are passed here because WebRTC reads them when it
58+
// creates the audio device module.
4459
Native.bypassVoiceProcessing = bypassVoiceProcessing;
45-
await rtc.WebRTC.initialize(options: {
46-
if (bypassVoiceProcessing) 'bypassVoiceProcessing': bypassVoiceProcessing,
47-
});
60+
await rtc.WebRTC.initialize(
61+
options: liveKitWebRTCInitializeOptions(
62+
bypassVoiceProcessing: bypassVoiceProcessing,
63+
initialAudioSessionOptions: initialAudioSessionOptions,
64+
includeAndroidAudioConfiguration: lkPlatformIs(PlatformType.android),
65+
),
66+
);
67+
if (lkPlatformIs(PlatformType.android) && initialAudioSessionOptions != null) {
68+
AudioManager.instance.setInitialAudioSessionOptions(initialAudioSessionOptions);
69+
}
4870
}
4971
}
5072
}
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// Copyright 2026 LiveKit, Inc.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
import 'package:meta/meta.dart';
16+
17+
import '../audio/android_audio_session_adapter.dart';
18+
import '../audio/audio_session.dart';
19+
20+
@internal
21+
Map<String, dynamic> liveKitWebRTCInitializeOptions({
22+
required bool bypassVoiceProcessing,
23+
required AudioSessionOptions? initialAudioSessionOptions,
24+
required bool includeAndroidAudioConfiguration,
25+
}) =>
26+
{
27+
if (bypassVoiceProcessing) 'bypassVoiceProcessing': bypassVoiceProcessing,
28+
if (includeAndroidAudioConfiguration && initialAudioSessionOptions != null)
29+
'androidAudioConfiguration': androidAudioSessionConfigurationToMap(initialAudioSessionOptions.android),
30+
};

0 commit comments

Comments
 (0)