element-hq / element-hq/element-call

[iOS] Incoming call audio routed to handset speaker / no sound in headphones until toggling Speaker (Element X 26.04.0, iOS 26.4.1)

Open
#3,865 2 comments 0 reactions 0 assignees View on GitHub
T-Defect
Dominant language
TypeScript
Stars
996
Forks
213
Avg merge
1d 6h
Merged PRs (30d)
54

Description

### Steps to reproduce

Short description:
When Element X is backgrounded and an incoming call arrives via APNs, accepting the call often results in audio being routed to the handset speaker / earpiece while connected headphones remain silent. Manually switching to Speaker and back (or toggling audio output) restores audio to the headphones. This happens even though the call is accepted and WebRTC tracks are published.

Steps to reproduce:

Install Element X 26.04.0 on iPhone 11 (iOS 26.4.1).
Leave Element X backgrounded (not foreground). Connect headphones (wired or Bluetooth).
From another client, start a call to the Element X user.
Accept the call from the push notification.
Observe that audio plays via handset speaker/earpiece and headphones are silent until manually toggling speaker/device audio output.
Expected behavior:
When headphones are connected, accepted calls should route audio to headphones immediately (no manual switching).

Steps to reproduce:

Install Element X 26.04.0 on iPhone 16 (iOS 26.4.1).
Leave Element X backgrounded (not foreground). Connect headphones (wired or Bluetooth).
From another client, start a call to the Element X user.
Accept the call from the push notification.
Observe that audio plays via handset speaker/earpiece and headphones are silent until manually toggling speaker/device audio output.

Problem occurs when app is backgrounded and woken by a standard APNs notification (not VoIP / PushKit). iOS takes time to wake the app and initialize AVAudioSession; during that sequence the audio route appears to default to handset speaker/earpiece instead of honoring connected headphones.
Server-side delivery and WebRTC negotiation appear to work correctly (push delivered, LiveKit shows audio tracks). This strongly indicates the issue is in client-side AVAudioSession / audio route handling on wake-from-background.
LiveKit client in our setup uses JS SDK (logs show sdk: "JS", version: "2.16.0" inside LiveKit telemetry) within a WKWebView.
Suggestions for maintainers:

When app is launched from background due to an incoming push, ensure AVAudioSession is activated and the audio route is refreshed/overridden to prefer connected headphones (PlayAndRecord mode, setPreferredInput, overrideOutputAudioPort as appropriate) before initializing WebRTC audio.
Consider explicitly querying available routes and forcing correct output after activation.
If possible, add a short delay to confirm route selection before binding WebRTC audio (or trigger re-evaluation of route immediately after session activation).

### Outcome

#### What did you expect?
When headphones are connected, accepted calls should route audio to headphones immediately (no manual switching).
#### What happened instead?
Audio initially goes to handset speaker/earpiece; headphones produce no sound until user toggles speaker/earpiece or re-plugs/re-connects headphones.

### Your phone model

iPhone 16

### Operating system version

iOS26.4.1

### Application version

26.04.0

### Homeserver

_No response_

### Will you send logs?

No

Contributor guide

Open the contributing guide

Research direction

Start by tracing the background APNs wake path through AVAudioSession activation and WebRTC audio initialization in the iOS client and its LiveKit JS SDK running in a WKWebView. Reproduce with wired or Bluetooth headphones, inspect available routes and session state before and after accepting the call, and compare the result after toggling Speaker. Done means an accepted background call immediately plays through connected headphones without manual output switching.

Written by the indexing model from the issue text.

Assessment

Tech stack
ios, javascript, typescript
Domain
audio-video-rtc, mobile-dev
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.