🩹(frontend) add participant audio leveling

[SyedIshmumAhnaf]

Purpose

Adds an optional participant audio leveling setting for calls, addressing #1345.

Proposal

Automatically equalize participant audio levels

Changes

• Add a persisted audio setting for participant audio leveling.
• Add an Audio settings switch with localized label and description.
• Add a LiveKit hook that gradually attenuates loud remote microphone tracks.
• Reset touched remote audio tracks to volume 1 when disabled or unmounted.

Safety

This MVP is attenuation-only. MAX_GAIN is capped at 1, so the hook never sets HTMLMediaElement.volume above the safe browser limit.

[cameledev]

Hi. Thank you for your PR. This would be nice feature. I did not try this out yet.

I have a few comments/questions:

• Do you have a reference for property audioLevel being used ? I have trouble finding a definitive answer on whether this is a smoothed value already. I guess yes, since values are btw 0 and 1, but it would be nice to confirm what it actually corresponds to.

• Do you have insight for the proposed constants ? How did you choose these values ?

• SMOOTHING_FACTOR / UPDATE_INTERVAL_MS with current values means corrections can be long (5 seconds from 0.02 to 0.3, with target 0.35). While this is okay for volume increase, it seems like a long wait if sound is too loud. Perhaps, volume decrease can be sped up.

• Additional comment: We should be careful that this integrates properly with participant muting to come

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[SyedIshmumAhnaf]

@cameledev Thanks for the review.

On audioLevel: I traced the value through LiveKit rather than assuming from the range alone. In livekit-client, participant.audioLevel is assigned from SpeakerInfo.level during active-speaker / speaker-update handling. The LiveKit protocol defines SpeakerInfo.level as an audio level from 0 to 1.0, where 1 is loudest.

I have not found a definitive reference confirming whether that value is already smoothed server-side, or whether it represents RMS/peak/VAD-derived level. So I treated it as a LiveKit-provided relative activity/loudness signal rather than a calibrated loudness value.

On the constants: they are conservative MVP values rather than calibrated audio-normalization constants.

• MAX_GAIN = 1 is deliberate because this first version is attenuation-only. Since the current room setup does not enable a WebAudio amplification path, RemoteAudioTrack.setVolume() may map to HTMLMediaElement.volume, where values above 1 are unsafe.
• MIN_GAIN = 0.6 avoids making loud participants too quiet.
• MIN_AUDIO_LEVEL = 0.02 avoids reacting to silence/background noise.
• TARGET_AUDIO_LEVEL = 0.35 is a conservative target within LiveKit’s 0..1 level range.

Your point about correction speed makes sense. I updated the smoothing to be asymmetric: attenuation is faster when a participant is too loud, while recovery is slower to avoid audible pumping. That should make loud-participant correction more responsive without making the volume jump around.

On participant muting: the current implementation only touches remote microphone track playback volume and resets touched RemoteAudioTracks to 1 when disabled/unmounted. It does not change publication mute state or subscription state. That said, I agree this should be kept compatible with participant muting if/when local per-participant mute/volume controls are introduced; if that feature adds its own per-participant playback state, this hook should compose with it rather than overwrite it.