element-hq / element-hq/element-call

Allow loading a custom outgoing-call ringback tone audio file on mobile clients (bundled tone is too quiet)

Open
#4,252 0 comments 5 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.