element-hq / element-hq/element-call
Allow loading a custom outgoing-call ringback tone audio file on mobile clients (bundled tone is too quiet)
- Dominant language
- TypeScript
- Stars
- 996
- Forks
- 213
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 55
Description
### Problem
When placing an outgoing call and waiting for the other person to pick up, the ringback/waiting tone is too quiet to be heard on mobile phones. Users placing a call may not realize it's still ringing (and may miss the moment it's answered, declined, or times out) because the sound doesn't stand out over ambient noise or the phone being in a pocket/bag.
This is **not** the incoming-call ringtone — it's the tone played to the caller while waiting for the callee to accept, handled in [`RingingAudioRenderer.tsx`](https://github.com/element-hq/element-call/blob/main/src/room/RingingAudioRenderer.tsx). It plays a fixed, bundled asset (`src/sound/ringtone.mp3` / `.ogg`) in a loop via the Web Audio API while `pickupState` is `"ringing"`. Its perceived loudness is limited by how the sample itself was mastered, and there's no way for a user to swap it out for something louder or more attention-grabbing.
### Proposed solution
Allow the mobile client to supply a custom audio file for this waiting/ringback tone, so users can pick (or load) a sound that is loud/distinct enough to be heard reliably, instead of being stuck with the bundled sound.
This could look like:
- A setting/option in the mobile client to select a custom ringback tone audio file (e.g. from the device's local files or the OS's native sound picker).
- Passing the selected file/URI through to Element Call (e.g. via widget API parameters or a client-provided configuration) so `RingingAudioRenderer` uses it instead of (or in addition to) the bundled `ringtone.mp3`/`ringtone.ogg`.
- Falling back to the current bundled sound when no custom one is provided.
### Motivation
Not hearing the outgoing-call waiting tone clearly makes it easy to miss when a call is picked up, declined, or times out, which hurts the calling experience on mobile, where Element Call is embedded as a widget and relies on this in-app sound rather than the OS's native call volume path.
### Additional context
- Affected file: `src/room/RingingAudioRenderer.tsx` (triggered on `pickupState === "ringing"` for outgoing calls)
- Platform: Mobile (Element X / mobile clients embedding Element Call as a widget)
Contributor guide
Research direction
Start with src/room/RingingAudioRenderer.tsx and trace how pickupState === "ringing" selects and loops src/sound/ringtone.mp3/.ogg. Then inspect the mobile client embedding and the available widget API or client configuration path for an audio file or URI. Done means a mobile client can provide a custom outgoing-call waiting tone, while the bundled tone remains the fallback.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- audio-video-rtc, mobile
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100