Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

iOS externalCallSystem: speaker preference maps to AVAudioSession mode videoChat (implicit defaultToSpeaker), so the CallKit Speaker button cannot turn the speaker off

Open
  • Is something wrong?
#1,227 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
dart, flutter, ios
Domain
audio-video-rtc, mobile-dev

Research direction

Start by reading ResolvedAudioSessionPolicy.appleConfiguration and LiveKitPlugin.applyAudioSessionConfiguration, then trace the engine re-apply path through AudioEngineDevice and LKAudioEngineObserver.applyManagedConfiguration. Verify how speaker routing behaves under externalCallSystem when changed from both the app and CallKit. Done means either control can switch between speaker and receiver, and an engine re-apply does not undo the user's route choice.

Written by the indexing model from the issue text.

Description

Describe the bug

On iOS with AudioSessionManagementMode.externalCallSystem, after the app sets AudioManager.instance.setSpeakerOutputPreferred(true), the Speaker button in the system CallKit call UI stays on and can't turn the speaker off. The app can still move audio back to the earpiece with setSpeakerOutputPreferred(false), but the user can't do it from the CallKit UI (lock screen, or the in-call screen reached from the call pill).

This looks like the same symptom as #725, which was closed as not planned on 2.3.6. It still happens on the new AudioManager/externalCallSystem path in 2.13.0.

To Reproduce
  1. Report a call to CallKit and use the documented coordination: setAudioSessionManagementMode(AudioSessionManagementMode.externalCallSystem), and setEngineAvailability gated on provider(_:didActivate:) / didDeactivate.
  2. Connect the room and publish the microphone. The call is on the earpiece (setSpeakerOutputPreferred(false)).
  3. Call AudioManager.instance.setSpeakerOutputPreferred(true). Audio moves to the speaker, and the CallKit UI shows Speaker on.
  4. In the CallKit UI, tap Speaker to turn it off.

Expected: audio moves to the receiver and the button turns off, as in the Phone app and as it does when the call started on the earpiece.

Actual: audio stays on the speaker and the button stays on.

Cause

ResolvedAudioSessionPolicy.appleConfiguration, whose automatic branch is also used for externalCallSystem, expresses the speaker preference as the session mode:

appleAudioMode: preferSpeakerOutput ? AppleAudioMode.videoChat : AppleAudioMode.voiceChat,

Apple's documentation for AVAudioSession.Mode.videoChat:

Setting this mode also causes the system to automatically apply the allowBluetoothHFP and defaultToSpeaker category options.

And for .defaultToSpeaker:

Use it to modify the category's routing behavior so audio is always routed to the speaker rather than the receiver … When using this option, the system doesn't honor user gestures.

The CallKit Speaker button is such a user gesture: it changes the output route override. With defaultToSpeaker in effect (implicitly, via videoChat), the non-speaker choice falls back to the speaker. The app's own setSpeakerOutputPreferred(false) works only because it switches the mode back to voiceChat.

There is a second, related problem. LiveKitPlugin.applyAudioSessionConfiguration calls overrideOutputAudioPort(forceSpeakerOutput ? .speaker : .none) on every re-apply for playAndRecord. Since the #1127 review fix (b70b39b) this also runs under externalCallSystem. AudioEngineDevice re-applies after AVAudioEngineConfigurationChangeNotification (ReconfigureEngine() → OnEngineWillEnable → LKAudioEngineObserver.applyManagedConfiguration). So on a voiceChat session, a speaker route the user picked in the CallKit UI can be reset to .none by the next engine reconfigure. Neither the app nor LiveKit asked for that change.

So under externalCallSystem no configuration lets both the app and the CallKit UI switch between speaker and earpiece:

  • videoChat means the CallKit UI can't leave the speaker.
  • voiceChat plus a system-UI override means the next engine re-apply can wipe the override.
  • force: true adds overrideOutputAudioPort(.speaker) but keeps videoChat.
Suggested fix

Under externalCallSystem, where the system call UI also controls the route:

  • Keep the mode at voiceChat and express the speaker preference as overrideOutputAudioPort(.speaker) / .none. That is the mechanism the CallKit button itself uses, so both stay in sync.
  • Don't reset the output override on engine-lifecycle re-applies. Only change it when the app explicitly changes the speaker preference.

Alternatively, add an opt-out from mode-based speaker routing, so apps can keep voiceChat and handle the override themselves without LiveKit clearing it.

Platform information
  • livekit_client 2.13.0, flutter_webrtc 1.6.2+hotfix.3, WebRTC-SDK 150.7871.01
  • iOS, iPhone. Seen in production on 1:1 calls reported to CallKit (flutter_callkit_incoming); CallKit activates the session, LiveKit is in externalCallSystem.
  • Also affects rooms that start with the speaker preferred, which get videoChat from the first configuration.
Dominant language
Dart
Stars
421
Forks
260
Avg merge
3d 9h
Merged PRs (30d)
11

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from livekit/client-sdk-flutter

All issues in livekit/client-sdk-flutter

Similar issues

More Dart issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.