feat: automatically equalize participant audio levels

src/frontend/src/features/rooms/livekit/hooks/useAudioLevelEqualization.ts

@@ -0,0 +1,93 @@
+import { useEffect, useRef } from 'react'
+import { useRemoteParticipants, useRoomContext } from '@livekit/components-react'
+import { RemoteParticipant, RemoteTrackPublication, Track } from 'livekit-client'
+import { useSnapshot } from 'valtio'
+import { userChoicesStore } from '@/stores/userChoices'
+
+const TARGET_LEVEL = 0.12
+const ADAPTATION_RATE = 0.05
+const MIN_GAIN = 0.2
+const MAX_GAIN = 3.0
+const TICK_INTERVAL_MS = 500
+
+interface ParticipantGainState {
+  currentGain: number
+  smoothedLevel: number
+}
+
+/**
+ * Adaptive per-participant audio level normalization (issue #1345).
+ *
+ * Every TICK_INTERVAL_MS, samples each remote participant's audioLevel,
+ * smooths it via EMA, and gradually adjusts their audio element volume
+ * toward TARGET_LEVEL. Gain is clamped to [MIN_GAIN, MAX_GAIN].
+ * Resets all volumes to 1.0 when disabled.
+ */
+export const useAudioLevelEqualization = () => {
+  const room = useRoomContext()
+  const remoteParticipants = useRemoteParticipants()
+  const { audioLevelEqualizationEnabled } = useSnapshot(userChoicesStore)
+  const gainStateRef = useRef<Map<string, ParticipantGainState>>(new Map())
+
+  useEffect(() => {
+    if (!audioLevelEqualizationEnabled) {
+      for (const participant of room.remoteParticipants.values()) {
+        const audioElement = getAudioElement(participant)
+        if (audioElement) audioElement.volume = 1.0
+      }
+      gainStateRef.current.clear()
+      return
+    }
+
+    const tick = () => {
+      for (const participant of room.remoteParticipants.values()) {
+        const sid = participant.sid
+        const audioLevel = participant.audioLevel ?? 0
+
+        if (!gainStateRef.current.has(sid)) {
+          gainStateRef.current.set(sid, { currentGain: 1.0, smoothedLevel: audioLevel })
+        }
+
+        const state = gainStateRef.current.get(sid)!
+
+        // EMA to avoid reacting to transient spikes
+        state.smoothedLevel =
+          state.smoothedLevel * (1 - ADAPTATION_RATE) + audioLevel * ADAPTATION_RATE
+
+        // Only adjust gain when participant is speaking, not on silence/noise floor
+        if (state.smoothedLevel > 0.01) {
+          const ratio = TARGET_LEVEL / state.smoothedLevel
+          state.currentGain =
+            state.currentGain * (1 - ADAPTATION_RATE) + ratio * ADAPTATION_RATE
+        }
+
+        state.currentGain = Math.min(MAX_GAIN, Math.max(MIN_GAIN, state.currentGain))
+
+        const audioElement = getAudioElement(participant)
+        if (audioElement) audioElement.volume = state.currentGain
+      }
+
+      // Clean up state for departed participants
+      for (const sid of gainStateRef.current.keys()) {
+        if (!room.remoteParticipants.has(sid)) {
+          gainStateRef.current.delete(sid)
+        }
+      }
+    }
+
+    const intervalId = setInterval(tick, TICK_INTERVAL_MS)
+    return () => clearInterval(intervalId)
+  }, [audioLevelEqualizationEnabled, room, remoteParticipants])
+}
+
+function getAudioElement(participant: RemoteParticipant): HTMLAudioElement | null {
+  const micPub = participant.getTrackPublication(
+    Track.Source.Microphone
+  ) as RemoteTrackPublication | undefined
+
+  if (!micPub?.trackSid) return null
+
+  return document.querySelector<HTMLAudioElement>(
+    `audio[data-lk-sid="${micPub.trackSid}"]`
+  )
+}

src/frontend/src/features/rooms/livekit/prefabs/VideoConference.tsx

@@ -18,6 +18,7 @@ import { isFireFox } from '@/utils/livekit'
 import { MediaStateObserver } from '../components/MediaStateObserver'
 import { RoomMetadataSynchronizer } from '../components/RoomMetadataSynchronizer'
 import { useNoiseReduction } from '../hooks/useNoiseReduction'
+import { useAudioLevelEqualization } from '../hooks/useAudioLevelEqualization'
 import { VideoResolutionSubscription } from '../components/VideoResolutionSubscription'
 import { SettingsDialogProvider } from '@/features/settings/components/SettingsDialogProvider'
 import { MuteAlertDialogProvider } from '@/features/rooms/livekit/components/MuteAlertDialogProvider'
@@ -75,6 +76,7 @@ const getScreenSharePermissionDeniedScope = (
  */
 export function VideoConference({ ...props }: VideoConferenceProps) {
   useNoiseReduction()
+  useAudioLevelEqualization()
 
   const { isOpen: isPictureInPictureOpen } = usePictureInPicture()
 

src/frontend/src/features/settings/components/tabs/AudioTab.tsx

@@ -17,6 +17,7 @@ import {
   saveAudioInputDeviceId,
   saveAudioOutputDeviceId,
   saveNoiseReductionEnabled,
+  saveAudioLevelEqualizationEnabled,
   userChoicesStore,
 } from '@/stores/userChoices'
 import { captureEvent } from '@/features/analytics/telemetry'
@@ -30,7 +31,7 @@ export const AudioTab = ({ id }: AudioTabProps) => {
   const { t } = useTranslation('settings')
   const { localParticipant } = useRoomContext()
 
-  const { noiseReductionEnabled, audioDeviceId, audioOutputDeviceId } =
+  const { noiseReductionEnabled, audioDeviceId, audioOutputDeviceId, audioLevelEqualizationEnabled } =
     useSnapshot(userChoicesStore)
 
   const isSpeaking = useIsSpeaking(localParticipant)
@@ -136,6 +137,22 @@ export const AudioTab = ({ id }: AudioTabProps) => {
           <div />
         </RowWrapper>
       )}
+      {/* Audio level equalization — issue #1345 */}
+      <RowWrapper heading={t('audio.audioLevelEqualization.heading')} beta>
+        <Switch
+          aria-label={t(
+            `audio.audioLevelEqualization.ariaLabel.${audioLevelEqualizationEnabled ? 'disable' : 'enable'}`
+          )}
+          isSelected={audioLevelEqualizationEnabled}
+          onChange={(v) => {
+            saveAudioLevelEqualizationEnabled(v)
+            if (v) captureEvent('audio-level-equalization-init')
+          }}
+        >
+          {t('audio.audioLevelEqualization.label')}
+        </Switch>
+        <div />
+      </RowWrapper>
     </TabPanel>
   )
 }

src/frontend/src/locales/de/settings.json

@@ -32,6 +32,15 @@
         "disable": "Geräuschunterdrückung deaktivieren"
       }
     },
+    "audioLevelEqualization": {
+      "label": "Lautstärke der Teilnehmer automatisch angleichen",
+      "heading": "Audio-Pegelanpassung",
+      "description": "Passt die Lautstärke jedes Teilnehmers kontinuierlich an, damit alle gleich laut zu hören sind.",
+      "ariaLabel": {
+        "enable": "Audio-Pegelanpassung aktivieren",
+        "disable": "Audio-Pegelanpassung deaktivieren"
+      }
+    },
     "speakers": {
       "heading": "Lautsprecher",
       "label": "Audioausgabe wählen",

src/frontend/src/locales/en/settings.json

@@ -32,6 +32,15 @@
         "disable": "Disable noise reduction"
       }
     },
+    "audioLevelEqualization": {
+      "label": "Automatically balance participant audio levels",
+      "heading": "Audio level equalization",
+      "description": "Continuously adjusts each participant's volume so everyone sounds equally loud.",
+      "ariaLabel": {
+        "enable": "Enable audio level equalization",
+        "disable": "Disable audio level equalization"
+      }
+    },
     "speakers": {
       "heading": "Speakers",
       "label": "Select your audio output",

src/frontend/src/locales/fr/settings.json

@@ -32,6 +32,15 @@
         "disable": "Désactiver la réduction du bruit"
       }
     },
+    "audioLevelEqualization": {
+      "label": "Équilibrer automatiquement les niveaux audio des participants",
+      "heading": "Égalisation du niveau audio",
+      "description": "Ajuste continuellement le volume de chaque participant pour que tout le monde soit entendu à égalité.",
+      "ariaLabel": {
+        "enable": "Activer l'égalisation du niveau audio",
+        "disable": "Désactiver l'égalisation du niveau audio"
+      }
+    },
     "speakers": {
       "heading": "Haut-parleurs",
       "label": "Sélectionner votre sortie audio",

src/frontend/src/locales/nl/settings.json

@@ -32,6 +32,15 @@
         "disable": "Ruisonderdrukking uitschakelen"
       }
     },
+    "audioLevelEqualization": {
+      "label": "Audioniveaus van deelnemers automatisch balanceren",
+      "heading": "Audioniveauegalisatie",
+      "description": "Past het volume van elke deelnemer continu aan zodat iedereen even goed te horen is.",
+      "ariaLabel": {
+        "enable": "Audioniveauegalisatie inschakelen",
+        "disable": "Audioniveauegalisatie uitschakelen"
+      }
+    },
     "speakers": {
       "heading": "Luidsprekers",
       "label": "Selecteer uw audio-uitvoer",

src/frontend/src/stores/userChoices.ts

@@ -20,6 +20,7 @@ const isVideoResolution = (value: unknown): value is VideoResolution =>
 export type LocalUserChoices = Omit<LocalUserChoicesLK, 'username'> & {
   processorConfig?: ProcessorConfig
   noiseReductionEnabled?: boolean
+  audioLevelEqualizationEnabled?: boolean
   audioOutputDeviceId?: string
   videoPublishResolution?: VideoResolution
   videoSubscribeQuality?: VideoQuality
@@ -28,6 +29,8 @@ export type LocalUserChoices = Omit<LocalUserChoicesLK, 'username'> & {
 function getUserChoicesState(): LocalUserChoices {
   const stored: LocalUserChoices = {
     noiseReductionEnabled: false,
+    // Audio level equalization defaults off — opt-in before it becomes the default
+    audioLevelEqualizationEnabled: false,
     audioOutputDeviceId: 'default', // Use 'default' to match LiveKit's standard device selection behavior
     videoPublishResolution: 'h720',
     videoSubscribeQuality: VideoQuality.HIGH,
@@ -109,6 +112,10 @@ export const saveNoiseReductionEnabled = (enabled: boolean) => {
   userChoicesStore.noiseReductionEnabled = enabled
 }
 
+export const saveAudioLevelEqualizationEnabled = (enabled: boolean) => {
+  userChoicesStore.audioLevelEqualizationEnabled = enabled
+}
+
 export const saveProcessorConfig = (
   processorConfig: ProcessorConfig | undefined
 ) => {