🐛(frontend) make the device-in-use logic race-free

The device-in-use logic could race when multiple detection events
fired close together (e.g. rapid mic/cam toggles or several devices
becoming busy at once), leading to inconsistent store state.

Refactor the flow so all updates go through a serialized path,
removing the race conditions and keeping the in-use state
consistent regardless of event ordering.

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to
 ### Added
 
 - 📈(frontend) track errors when starting or stopping a recording
+- 🚸(frontend) explain camera-in-use failures on the join screen
 
 ### Changed
 
@@ -31,6 +32,9 @@ and this project adheres to
 - 🐛(frontend) stop init_virtual_background from firing on blur updates
 - 🐛(frontend) hoist mute confirmation dialog to VideoConference level
 - 🐛(frontend) fix joined notification tile no longer rendering properly
+- 🐛(frontend) handle device-in-use errors on Chrome / Windows 10
+- 🐛(frontend) handle Firefox/Windows AbortError on device start
+- 🐛(frontend) treat "Timeout starting source" AbortError as device-in-use
 
 ## [1.27.0] - 2026-08-14
 

src/frontend/src/features/analytics/telemetry.ts

@@ -137,6 +137,7 @@ export const captureMediaEvent = async (
     | 'media-device-topology'
     | 'media-device-success'
     | 'device-not-found'
+    | 'device-in-use'
     | 'permissions-denied'
     | 'screen-share-permission-denied'
     | 'silent-mic-detected'

src/frontend/src/features/rooms/components/Conference.tsx

@@ -14,6 +14,7 @@ import {
   type RoomOptions,
   VideoPresets,
 } from 'livekit-client'
+import { getMediaDeviceFailure } from '@/features/rooms/livekit/utils/mediaPermissions'
 import { keys } from '@/api/queryKeys'
 import { queryClient } from '@/api/queryClient'
 import { Screen } from '@/layout/Screen'
@@ -231,7 +232,7 @@ export const Conference = ({
             backgroundColor: 'primaryDark.50 !important',
           })}
           onError={(e) => {
-            const failure = MediaDeviceFailure.getFailure(e)
+            const failure = getMediaDeviceFailure(e)
             if (failure && failure !== MediaDeviceFailure.Other) return
 
             // connect() was aborted by a disconnect() before the join completed

src/frontend/src/features/rooms/components/Join.tsx

@@ -28,6 +28,7 @@ import {
   userChoicesStore,
 } from '@/stores/userChoices'
 import { useCannotUseDevice } from '../livekit/hooks/useCannotUseDevice'
+import { useDeviceInUse } from '../livekit/hooks/useDeviceInUse'
 import { useDeviceMissing } from '../livekit/hooks/useDeviceMissing'
 import { useJoinTracks } from '../livekit/hooks/useJoinTracks'
 import { SilentMicDetector } from './SilentMicDetector'
@@ -218,12 +219,14 @@ const switchTrackDevice =
 function getPreviewMessages({
   cameraFound,
   cameraDenied,
+  cameraInUse,
   micDenied,
   videoEnabled,
   videoStarted,
 }: {
   cameraFound: boolean
   cameraDenied: boolean
+  cameraInUse: boolean
   micDenied: boolean
   videoEnabled: boolean
   videoStarted: boolean
@@ -235,6 +238,9 @@ function getPreviewMessages({
     const key = micDenied ? 'cameraAndMicNotGranted' : 'cameraNotGranted'
     return { hint: key, permissionsButtonLabel: key }
   }
+  if (cameraInUse) {
+    return { hint: 'cameraInUse', permissionsButtonLabel: null }
+  }
   if (!videoEnabled) {
     return { hint: 'cameraDisabled', permissionsButtonLabel: null }
   }
@@ -328,18 +334,20 @@ const VideoPreview = ({
   const cameraDenied = useCannotUseDevice('videoinput')
   const micDenied = useCannotUseDevice('audioinput')
   const cameraMissing = useDeviceMissing('videoinput')
+  const cameraInUse = useDeviceInUse('videoinput')
 
   const { videoEl, videoStarted } = useAttachedVideo(videoTrack, videoEnabled)
 
   const { hint, permissionsButtonLabel } = getPreviewMessages({
     cameraFound: !cameraMissing,
     cameraDenied,
+    cameraInUse,
     micDenied,
     videoEnabled,
     videoStarted,
   })
 
-  const isError = cameraMissing || cameraDenied
+  const isError = cameraMissing || cameraDenied || cameraInUse
 
   return (
     <div className={styles.previewFrame}>

src/frontend/src/features/rooms/hooks/useWatchDeviceReleased.ts

@@ -0,0 +1,53 @@
+import { useEffect } from 'react'
+import { useSnapshot } from 'valtio'
+import {
+  clearDeviceInUseForOtherDevice,
+  deviceAvailabilityStore,
+} from '@/stores/deviceAvailability'
+import { userChoicesStore } from '@/stores/userChoices'
+import { probeDeviceReleased } from '../livekit/utils/mediaPermissions'
+import type { PermissionKind } from '@/stores/permissions'
+
+const RETRY_INTERVAL_MS = 30_000
+
+/**
+ * There is no browser event for "another app released the device", so
+ * while a device is flagged in use, re-probe it periodically. The probe
+ * targets the currently selected device (the flag is about what the app
+ * would acquire, not about any device of the kind). Only clears the flag
+ * (the toggle becomes usable again); it never re-enables the device on
+ * the user's behalf.
+ */
+export function useWatchDeviceReleased() {
+  const { cameraInUse, microphoneInUse } = useSnapshot(deviceAvailabilityStore)
+  const { audioDeviceId, videoDeviceId } = useSnapshot(userChoicesStore)
+  useWatchKind('camera', cameraInUse, videoDeviceId)
+  useWatchKind('microphone', microphoneInUse, audioDeviceId)
+}
+
+function useWatchKind(
+  kind: PermissionKind,
+  inUse: boolean,
+  selectedDeviceId?: string
+) {
+  useEffect(() => {
+    if (inUse) clearDeviceInUseForOtherDevice(kind, selectedDeviceId)
+  }, [kind, inUse, selectedDeviceId])
+
+  useEffect(() => {
+    if (!inUse) return
+    let stopped = false
+    let timer: number | undefined
+    const tick = async () => {
+      await probeDeviceReleased(kind, selectedDeviceId || undefined)
+      if (!stopped) {
+        timer = window.setTimeout(tick, RETRY_INTERVAL_MS)
+      }
+    }
+    timer = window.setTimeout(tick, RETRY_INTERVAL_MS)
+    return () => {
+      stopped = true
+      window.clearTimeout(timer)
+    }
+  }, [kind, inUse, selectedDeviceId])
+}

src/frontend/src/features/rooms/livekit/components/controls/Device/PermissionNeededButton.tsx

@@ -5,16 +5,18 @@ import { css } from '@/styled-system/css'
 import { useTranslation } from 'react-i18next'
 
 type PermissionNeededButtonProps = {
-  tooltip?: string
-  onPress?: () => void
+  tooltip?: string | null
+  onPress?: (() => void) | null
+  ariaLabel?: string
 }
 
 export const PermissionNeededButton = ({
   tooltip,
   onPress,
+  ariaLabel,
 }: PermissionNeededButtonProps) => {
   const { t } = useTranslation('rooms', { keyPrefix: 'permissionsButton' })
-  const label = tooltip ?? t('tooltip')
+  const label = tooltip === undefined ? t('tooltip') : tooltip
   return (
     <div
       className={css({
@@ -26,9 +28,13 @@ export const PermissionNeededButton = ({
       })}
     >
       <Button
-        aria-label={tooltip ? label : t('ariaLabel')}
-        tooltip={label}
-        onPress={onPress ?? (() => openPermissionsDialog())}
+        aria-label={ariaLabel ?? label ?? t('ariaLabel')}
+        tooltip={label ?? undefined}
+        onPress={
+          onPress === undefined
+            ? () => openPermissionsDialog()
+            : (onPress ?? undefined)
+        }
         variant="permission"
       >
         <div

src/frontend/src/features/rooms/livekit/components/controls/Device/ToggleDevice.tsx

@@ -20,8 +20,10 @@ import { openPermissionsDialog } from '@/stores/permissions'
 import { openSilentMicDialog, silentMicStore } from '@/stores/silentMic'
 import { useSnapshot } from 'valtio'
 import { useCannotUseDevice } from '../../../hooks/useCannotUseDevice'
+import { useDeviceInUse } from '../../../hooks/useDeviceInUse'
 import { useDeviceMissing } from '../../../hooks/useDeviceMissing'
-import { requestDevicePermission } from '../../../hooks/useJoinTracks'
+import { requestDevicePermission } from '../../../utils/mediaPermissions'
+import { userChoicesStore } from '@/stores/userChoices'
 import { useDeviceIcons } from '../../../hooks/useDeviceIcons'
 import { useDeviceShortcut } from '../../../hooks/useDeviceShortcut'
 import type {
@@ -97,38 +99,51 @@ export const ToggleDevice = <T extends ToggleSource>({
   const deviceIcons = useDeviceIcons(kind)
   const cannotUseDevice = useCannotUseDevice(kind)
   const deviceMissing = useDeviceMissing(kind)
+  const deviceInUse = useDeviceInUse(kind)
+  const explainDeviceInUse = deviceInUse && context === 'room'
   const { status: silentMicStatus } = useSnapshot(silentMicStore)
   const silentMicWarning =
     kind === 'audioinput' &&
     silentMicStatus === 'silent' &&
     !cannotUseDevice &&
-    !deviceMissing
+    !deviceMissing &&
+    !deviceInUse
   const deviceShortcut = useDeviceShortcut(kind)
   const announce = useScreenReaderAnnounce()
 
   const isRequestingPermission = useRef(false)
-  const [showDeviceNotFound, setShowDeviceNotFound] = useState(false)
+  const [alertError, setAlertError] = useState<MediaDeviceFailure | null>(null)
+
+  const mediaPath = context === 'join' ? 'join_preview' : 'room'
 
   const onPress = async () => {
     if (!enabled && deviceMissing) {
-      setShowDeviceNotFound(true)
+      setAlertError(MediaDeviceFailure.NotFound)
       return
     }
-    if (!cannotUseDevice) {
+    if (!cannotUseDevice && !deviceInUse) {
       toggle()
       return
     }
     if (isRequestingPermission.current) return
     isRequestingPermission.current = true
     try {
-      const granted = await requestDevicePermission(
+      const selectedDeviceId = cannotUseDevice
+        ? undefined
+        : kind === 'videoinput'
+          ? userChoicesStore.videoDeviceId
+          : userChoicesStore.audioDeviceId
+      const acquired = await requestDevicePermission(
         kind,
-        context === 'join' ? 'join_preview' : 'room'
+        mediaPath,
+        selectedDeviceId || undefined
       )
-      if (granted) {
+      if (acquired) {
         toggle()
-      } else {
+      } else if (cannotUseDevice) {
         openPermissionsDialog(kind)
+      } else if (explainDeviceInUse) {
+        setAlertError(MediaDeviceFailure.DeviceInUse)
       }
     } finally {
       isRequestingPermission.current = false
@@ -179,13 +194,34 @@ export const ToggleDevice = <T extends ToggleSource>({
     return <ActiveSpeakerWrapper />
   }
 
+  const getToggleTooltip = () => {
+    if (deviceMissing) return t(`deviceNotFound.${kind}`)
+    if (explainDeviceInUse) return t(`deviceInUse.${kind}`)
+    if (cannotUseDevice) return t('tooltip', { keyPrefix: 'permissionsButton' })
+    return toggleLabel
+  }
+  const toggleTooltip = getToggleTooltip()
+
   return (
     <div style={{ position: 'relative' }}>
       {(cannotUseDevice || deviceMissing) && (
         <PermissionNeededButton
           tooltip={deviceMissing ? t(`deviceNotFound.${kind}`) : undefined}
           onPress={
-            deviceMissing ? () => setShowDeviceNotFound(true) : undefined
+            deviceMissing
+              ? () => setAlertError(MediaDeviceFailure.NotFound)
+              : undefined
+          }
+        />
+      )}
+      {deviceInUse && (
+        <PermissionNeededButton
+          tooltip={explainDeviceInUse ? t(`deviceInUse.${kind}`) : null}
+          ariaLabel={t(`deviceInUse.${kind}`)}
+          onPress={
+            explainDeviceInUse
+              ? () => setAlertError(MediaDeviceFailure.DeviceInUse)
+              : null
           }
         />
       )}
@@ -204,22 +240,16 @@ export const ToggleDevice = <T extends ToggleSource>({
         shySelected
         onPress={onPress}
         aria-label={toggleLabel}
-        tooltip={
-          deviceMissing
-            ? t(`deviceNotFound.${kind}`)
-            : cannotUseDevice
-              ? t('tooltip', { keyPrefix: 'permissionsButton' })
-              : toggleLabel
-        }
+        tooltip={toggleTooltip}
         {...computedToggleButtonProps}
         {...overrideToggleButtonProps}
       >
         <Icon />
       </ToggleButton>
       <MediaDeviceErrorAlert
-        error={showDeviceNotFound ? MediaDeviceFailure.NotFound : null}
+        error={alertError}
         kind={kind}
-        onClose={() => setShowDeviceNotFound(false)}
+        onClose={() => setAlertError(null)}
       />
     </div>
   )

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

@@ -0,0 +1,21 @@
+import { useSnapshot } from 'valtio'
+import { deviceAvailabilityStore } from '@/stores/deviceAvailability'
+import { useCannotUseDevice } from './useCannotUseDevice'
+import { useDeviceMissing } from './useDeviceMissing'
+
+export const useDeviceInUse = (kind: MediaDeviceKind): boolean => {
+  const { cameraInUse, microphoneInUse } = useSnapshot(deviceAvailabilityStore)
+  const cannotUseDevice = useCannotUseDevice(kind)
+  const deviceMissing = useDeviceMissing(kind)
+
+  if (cannotUseDevice || deviceMissing) return false
+
+  switch (kind) {
+    case 'videoinput':
+      return cameraInUse
+    case 'audioinput':
+      return microphoneInUse
+    default:
+      return false
+  }
+}

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

@@ -10,16 +10,14 @@ import {
 } from 'livekit-client'
 import { BackgroundProcessorFactory } from '../components/blur'
 import {
-  classifyPermissionError,
-  isLikelySystemNotFound,
   isSystemPermissionError,
-  noteGumSuccess,
-  notePermissionDeniedFromGum,
-  noteSystemPermissionDenied,
   type PermissionKind,
 } from '@/stores/permissions'
-import { getOS } from '@/utils/os'
-import { captureMediaEvent, reportError } from '@/features/analytics/telemetry'
+import {
+  getMediaDeviceFailure,
+  noteDeviceReady,
+  onMediaPermissionError,
+} from '../utils/mediaPermissions'
 import {
   saveAudioInputDeviceId,
   saveAudioInputEnabled,
@@ -39,64 +37,6 @@ const VOICE_AUDIO_CONSTRAINTS = {
   sampleSize: 16,
 } as const
 
-const PERMISSION_KIND: Record<'audioinput' | 'videoinput', PermissionKind> = {
-  audioinput: 'microphone',
-  videoinput: 'camera',
-}
-
-type MediaPath = 'join_preview' | 'room'
-
-const onMediaPermissionError = (
-  e: Error,
-  kind?: PermissionKind,
-  path: MediaPath = 'join_preview'
-) => {
-  if (
-    MediaDeviceFailure.getFailure(e) === MediaDeviceFailure.PermissionDenied
-  ) {
-    void classifyPermissionError(e, kind).then((scope) => {
-      if (scope === 'system') {
-        noteSystemPermissionDenied(kind)
-      } else {
-        notePermissionDeniedFromGum(kind)
-      }
-      captureMediaEvent('permissions-denied', {
-        path,
-        kind,
-        denied_scope: scope,
-        os: getOS(),
-      })
-    })
-    return
-  }
-
-  if (MediaDeviceFailure.getFailure(e) === MediaDeviceFailure.NotFound) {
-    // Firefox reports OS-level blocks as NotFoundError (macOS privacy
-    // settings, missing Android app permissions).
-    void isLikelySystemNotFound(e, kind).then((system) => {
-      if (system) {
-        noteSystemPermissionDenied(kind)
-        captureMediaEvent('permissions-denied', {
-          path,
-          kind,
-          denied_scope: 'system',
-          os: getOS(),
-        })
-        return
-      }
-      captureMediaEvent('device-not-found', { path, kind })
-    })
-    return
-  }
-
-  // "Other" and "Device in use" are still reported as errors, as they are not handled on the join screen.
-  reportError(
-    path === 'room' ? 'room_media_failure' : 'join_preview_failure',
-    e,
-    { path, kind }
-  )
-}
-
 // Module-level: effect dependencies, must be referentially stable.
 const disableAudio = () => saveAudioInputEnabled(false)
 const disableVideo = () => saveVideoInputEnabled(false)
@@ -104,24 +44,6 @@ const disableVideo = () => saveVideoInputEnabled(false)
 const stopAll = (stream: MediaStream) =>
   stream.getTracks().forEach((track) => track.stop())
 
-export const requestDevicePermission = async (
-  kind: 'audioinput' | 'videoinput',
-  path: MediaPath = 'join_preview'
-): Promise<boolean> => {
-  try {
-    const track =
-      kind === 'audioinput'
-        ? await createLocalAudioTrack()
-        : await createLocalVideoTrack()
-    track.stop()
-    noteGumSuccess(PERMISSION_KIND[kind])
-    return true
-  } catch (error) {
-    onMediaPermissionError(error as Error, PERMISSION_KIND[kind], path)
-    return false
-  }
-}
-
 type WarmupState = {
   audioReady: boolean
   videoReady: boolean
@@ -158,11 +80,11 @@ function useWarmupPermissions(): WarmupState {
             video: true,
           })
         )
-        noteGumSuccess()
+        noteDeviceReady()
         bothReady()
       } catch (error) {
         if (
-          MediaDeviceFailure.getFailure(error as Error) ===
+          getMediaDeviceFailure(error as Error) ===
             MediaDeviceFailure.PermissionDenied &&
           !isSystemPermissionError(error)
         ) {
@@ -180,7 +102,7 @@ function useWarmupPermissions(): WarmupState {
           .getUserMedia({ audio: true })
           .then((stream) => {
             stopAll(stream)
-            noteGumSuccess('microphone')
+            noteDeviceReady('microphone')
           })
           .catch((e) => onMediaPermissionError(e as Error, 'microphone'))
           .finally(() =>
@@ -190,7 +112,7 @@ function useWarmupPermissions(): WarmupState {
           .getUserMedia({ video: true })
           .then((stream) => {
             stopAll(stream)
-            noteGumSuccess('camera')
+            noteDeviceReady('camera')
           })
           .catch((e) => onMediaPermissionError(e as Error, 'camera'))
           .finally(() =>
@@ -209,12 +131,14 @@ function useLocalTrack<T extends LocalAudioTrack | LocalVideoTrack>({
   enabled,
   create,
   permissionKind,
+  deviceId,
   onFailure,
 }: {
   ready: boolean
   enabled: boolean
   create: () => Promise<T>
   permissionKind: PermissionKind
+  deviceId?: string
   onFailure: () => void
 }): T | null {
   const [track, setTrack] = useState<T | null>(null)
@@ -227,21 +151,27 @@ function useLocalTrack<T extends LocalAudioTrack | LocalVideoTrack>({
     let cancelled = false
     create()
       .then((newTrack) => {
-        noteGumSuccess(permissionKind)
         if (cancelled) {
           newTrack.stop()
           return
         }
+        noteDeviceReady(permissionKind)
         setTrack(newTrack)
       })
       .catch((error) => {
-        onMediaPermissionError(error as Error, permissionKind)
+        if (cancelled) return
+        onMediaPermissionError(
+          error as Error,
+          permissionKind,
+          'join_preview',
+          deviceId
+        )
         onFailure()
       })
     return () => {
       cancelled = true
     }
-  }, [ready, enabled, track, create, permissionKind, onFailure])
+  }, [ready, enabled, track, create, permissionKind, deviceId, onFailure])
 
   // Release on toggle-off so the LED turns off.
   useEffect(() => {
@@ -315,6 +245,7 @@ export function useJoinTracks(): {
     enabled: audioEnabled,
     create: createAudio,
     permissionKind: 'microphone',
+    deviceId: audioDeviceId,
     onFailure: disableAudio,
   })
 
@@ -323,6 +254,7 @@ export function useJoinTracks(): {
     enabled: videoEnabled,
     create: createVideo,
     permissionKind: 'camera',
+    deviceId: videoDeviceId,
     onFailure: disableVideo,
   })
 

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

@@ -1,6 +1,11 @@
 import { useCallback, useEffect, useState } from 'react'
 import { useRoomContext } from '@livekit/components-react'
-import { MediaDeviceFailure, RoomEvent } from 'livekit-client'
+import {
+  type LocalTrackPublication,
+  MediaDeviceFailure,
+  RoomEvent,
+  Track,
+} from 'livekit-client'
 import {
   PERMISSION_BY_DEVICE_KIND,
   type PermissionDeniedScope,
@@ -10,8 +15,13 @@ import {
   notePermissionDeniedFromGum,
   noteSystemPermissionDenied,
 } from '@/stores/permissions'
-import { syncDeviceAvailability } from '@/stores/deviceAvailability'
+import {
+  clearDeviceInUse,
+  noteDeviceInUse,
+  syncDeviceAvailability,
+} from '@/stores/deviceAvailability'
 import { captureMediaEvent } from '@/features/analytics/telemetry'
+import { getMediaDeviceFailure } from '../utils/mediaPermissions'
 import { getOS } from '@/utils/os'
 
 type MediaDeviceAlert = {
@@ -21,6 +31,11 @@ type MediaDeviceAlert = {
 
 const NO_ALERT: MediaDeviceAlert = { error: null, kind: null }
 
+const PERMISSION_BY_SOURCE: Partial<Record<Track.Source, PermissionKind>> = {
+  [Track.Source.Camera]: 'camera',
+  [Track.Source.Microphone]: 'microphone',
+}
+
 const capturePermissionsDenied = (
   scope: PermissionDeniedScope,
   kind?: PermissionKind
@@ -49,7 +64,7 @@ export const useWatchMediaDeviceErrors = (): MediaDeviceAlert & {
 
   useEffect(() => {
     const onDeviceError = (error: Error, kind?: MediaDeviceKind) => {
-      const failure = MediaDeviceFailure.getFailure(error)
+      const failure = getMediaDeviceFailure(error)
       if (!failure) return
       if (failure != MediaDeviceFailure.Other) {
         void captureMediaEvent('media-device-error', {
@@ -63,6 +78,7 @@ export const useWatchMediaDeviceErrors = (): MediaDeviceAlert & {
       const permissionKind = PERMISSION_BY_DEVICE_KIND[kind]
       switch (failure) {
         case MediaDeviceFailure.DeviceInUse:
+          if (permissionKind) noteDeviceInUse(permissionKind)
           setAlert({ error: failure, kind })
           break
         case MediaDeviceFailure.NotFound:
@@ -92,9 +108,16 @@ export const useWatchMediaDeviceErrors = (): MediaDeviceAlert & {
           break
       }
     }
+    const onTrackPublished = (publication: LocalTrackPublication) => {
+      const permissionKind = PERMISSION_BY_SOURCE[publication.source]
+      if (permissionKind) clearDeviceInUse(permissionKind)
+    }
     room.on(RoomEvent.MediaDevicesError, onDeviceError)
+    room.on(RoomEvent.LocalTrackPublished, onTrackPublished)
     return () => {
       room.off(RoomEvent.MediaDevicesError, onDeviceError)
+      room.off(RoomEvent.LocalTrackPublished, onTrackPublished)
+      clearDeviceInUse()
     }
   }, [room])
 

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

@@ -1,5 +1,6 @@
 import { isWeb } from '@livekit/components-core'
-import { Track } from 'livekit-client'
+import { MediaDeviceFailure, Track } from 'livekit-client'
+import { getMediaDeviceFailure } from '../utils/mediaPermissions'
 import React, { useState } from 'react'
 import {
   ConnectionStateToast,
@@ -100,6 +101,11 @@ export function VideoConference({ ...props }: VideoConferenceProps) {
         return
       }
     }
+
+    if (getMediaDeviceFailure(error) !== MediaDeviceFailure.Other) {
+      return
+    }
+
     reportError('device_switch_failure', error, {
       at: 'ControlBar.onDeviceError',
       source,

src/frontend/src/features/rooms/livekit/utils/mediaPermissions.ts

@@ -0,0 +1,168 @@
+import {
+  createLocalAudioTrack,
+  createLocalVideoTrack,
+  MediaDeviceFailure,
+} from 'livekit-client'
+import {
+  classifyPermissionError,
+  isLikelySystemNotFound,
+  noteGumSuccess,
+  notePermissionDeniedFromGum,
+  noteSystemPermissionDenied,
+  type PermissionKind,
+} from '@/stores/permissions'
+import { clearDeviceInUse, noteDeviceInUse } from '@/stores/deviceAvailability'
+import { captureMediaEvent, reportError } from '@/features/analytics/telemetry'
+import { getOS } from '@/utils/os'
+
+/**
+ * Shared handling of getUserMedia() outcomes, used by both:
+ * - the join preview (`useJoinTracks`: warmup + local track acquisition)
+ * - the in-room device toggle (`ToggleDevice`, when permission is missing)
+ */
+export type MediaPath = 'join_preview' | 'room'
+
+const DEVICE_START_FAILURE =
+  /^(Starting (video|audio)input failed|Timeout starting (video|audio) source)/i
+
+/**
+ * LiveKit only maps NotReadableError/TrackStartError to DeviceInUse.
+ * Firefox reports a device held by another app as
+ * `AbortError: Starting videoinput failed` (or audioinput), which LiveKit
+ * classifies as Other. Normalise it here; every classification in the app
+ * should go through this instead of MediaDeviceFailure.getFailure.
+ */
+export const getMediaDeviceFailure = (
+  error: Error
+): MediaDeviceFailure | undefined => {
+  const failure = MediaDeviceFailure.getFailure(error)
+  if (
+    failure === MediaDeviceFailure.Other &&
+    error.name === 'AbortError' &&
+    DEVICE_START_FAILURE.test(error.message)
+  ) {
+    return MediaDeviceFailure.DeviceInUse
+  }
+  return failure
+}
+
+export const PERMISSION_KIND: Record<
+  'audioinput' | 'videoinput',
+  PermissionKind
+> = {
+  audioinput: 'microphone',
+  videoinput: 'camera',
+}
+
+export const noteDeviceReady = (kind?: PermissionKind) => {
+  noteGumSuccess(kind)
+  clearDeviceInUse(kind)
+}
+
+export const onMediaPermissionError = (
+  e: Error,
+  kind?: PermissionKind,
+  path: MediaPath = 'join_preview',
+  deviceId?: string
+) => {
+  const failure = getMediaDeviceFailure(e)
+
+  if (failure === MediaDeviceFailure.PermissionDenied) {
+    void classifyPermissionError(e, kind).then((scope) => {
+      if (scope === 'system') {
+        noteSystemPermissionDenied(kind)
+      } else {
+        notePermissionDeniedFromGum(kind)
+      }
+      captureMediaEvent('permissions-denied', {
+        path,
+        kind,
+        denied_scope: scope,
+        os: getOS(),
+      })
+    })
+    return
+  }
+
+  if (failure === MediaDeviceFailure.NotFound) {
+    // Firefox reports OS-level blocks as NotFoundError (macOS privacy
+    // settings, missing Android app permissions).
+    void isLikelySystemNotFound(e, kind).then((system) => {
+      if (system) {
+        noteSystemPermissionDenied(kind)
+        captureMediaEvent('permissions-denied', {
+          path,
+          kind,
+          denied_scope: 'system',
+          os: getOS(),
+        })
+        return
+      }
+      captureMediaEvent('device-not-found', { path, kind })
+    })
+    return
+  }
+
+  if (failure === MediaDeviceFailure.DeviceInUse) {
+    noteDeviceInUse(kind, deviceId)
+    void captureMediaEvent('device-in-use', { path, kind, os: getOS() })
+    return
+  }
+
+  // "Other" is still reported as an error.
+  reportError(
+    path === 'room' ? 'room_media_failure' : 'join_preview_failure',
+    e,
+    { path, kind }
+  )
+}
+
+/**
+ * Silent availability check for a device that was reported "in use":
+ * acquires and releases it without any error reporting, so it can be
+ * polled. Clears the in-use flag on success.
+ */
+export const probeDeviceReleased = async (
+  kind: PermissionKind,
+  deviceId?: string
+): Promise<boolean> => {
+  try {
+    const constraint = deviceId ? { deviceId: { exact: deviceId } } : true
+    const stream = await navigator.mediaDevices.getUserMedia(
+      kind === 'camera' ? { video: constraint } : { audio: constraint }
+    )
+    stream.getTracks().forEach((track) => track.stop())
+    noteDeviceReady(kind)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Triggers the browser permission prompt for one device kind by acquiring
+ * and immediately releasing a track. Resolves to whether access was granted.
+ */
+export const requestDevicePermission = async (
+  kind: 'audioinput' | 'videoinput',
+  path: MediaPath = 'join_preview',
+  deviceId?: string
+): Promise<boolean> => {
+  try {
+    const track =
+      kind === 'audioinput'
+        ? await createLocalAudioTrack({ deviceId })
+        : await createLocalVideoTrack({ deviceId })
+    track.stop()
+    noteDeviceReady(PERMISSION_KIND[kind])
+    return true
+  } catch (error) {
+    onMediaPermissionError(
+      error as Error,
+      PERMISSION_KIND[kind],
+      path,
+      deviceId
+    )
+    return false
+  }
+}

src/frontend/src/features/rooms/routes/Room.tsx

@@ -16,6 +16,7 @@ import {
 import { useConfig } from '@/api/useConfig.ts'
 import { LogLevel, setLogLevel } from 'livekit-client'
 import { useWatchDeviceAvailability } from '@/features/rooms/hooks/useWatchDeviceAvailability'
+import { useWatchDeviceReleased } from '@/features/rooms/hooks/useWatchDeviceReleased'
 import { useRoomPageTitle } from '@/features/rooms/livekit/hooks/useRoomPageTitle'
 
 const BaseRoom = ({ children }: { children: ReactNode }) => {
@@ -49,6 +50,7 @@ const Room = () => {
 
   useKeyboardShortcuts()
   useWatchDeviceAvailability()
+  useWatchDeviceReleased()
 
   const clearRouterState = () => {
     if (window?.history?.state) {

src/frontend/src/locales/de/rooms.json

@@ -16,6 +16,10 @@
       "videoinput": "Keine Kamera erkannt. Prüfe, ob sie richtig angeschlossen ist.",
       "audioinput": "Kein Mikrofon erkannt. Prüfe, ob es richtig angeschlossen ist."
     },
+    "deviceInUse": {
+      "videoinput": "Kamera nicht verfügbar: Sie wird wahrscheinlich von einer anderen App oder einem anderen Tab verwendet.",
+      "audioinput": "Mikrofon nicht verfügbar: Es wird wahrscheinlich von einer anderen App oder einem anderen Tab verwendet."
+    },
     "settings": {
       "audio": "Audioeinstellungen",
       "video": "Videoeinstellungen"
@@ -67,6 +71,7 @@
     },
     "cameraDisabled": "Kamera ist deaktiviert.",
     "cameraNotFound": "Keine Kamera erkannt. Prüfe, ob sie richtig angeschlossen ist.",
+    "cameraInUse": "Deine Kamera ist nicht verfügbar. Sie wird wahrscheinlich von einer anderen App oder einem anderen Tab verwendet.",
     "cameraStarting": "Kamera wird gestartet…",
     "cameraNotGranted": "Möchtest du, dass andere dich während des Meetings sehen können?",
     "cameraAndMicNotGranted": "Möchtest du, dass andere dich während des Meetings sehen und hören können?",

src/frontend/src/locales/en/rooms.json

@@ -16,6 +16,10 @@
       "videoinput": "No camera detected. Check that it is properly wired.",
       "audioinput": "No microphone detected. Check that it is properly wired."
     },
+    "deviceInUse": {
+      "videoinput": "Camera unavailable: it is probably in use by another application or browser tab.",
+      "audioinput": "Microphone unavailable: it is probably in use by another application or browser tab."
+    },
     "settings": {
       "audio": "Audio settings",
       "video": "Video settings"
@@ -67,6 +71,7 @@
     },
     "cameraDisabled": "Camera is disabled.",
     "cameraNotFound": "No camera detected. Check that it is properly plugged in.",
+    "cameraInUse": "Your camera is unavailable. It is probably being used by another application or browser tab.",
     "cameraStarting": "Camera is starting…",
     "cameraNotGranted": "Would you like others to be able to see you during the meeting?",
     "cameraAndMicNotGranted": "Would you like others to be able to see and hear you during the meeting?",

src/frontend/src/locales/fr/rooms.json

@@ -16,6 +16,10 @@
       "videoinput": "Aucune caméra détectée. Vérifiez qu'elle est bien branchée.",
       "audioinput": "Aucun microphone détecté. Vérifiez qu'il est bien branché."
     },
+    "deviceInUse": {
+      "videoinput": "Caméra indisponible : elle est probablement utilisée par une autre application ou un autre onglet.",
+      "audioinput": "Microphone indisponible : il est probablement utilisé par une autre application ou un autre onglet."
+    },
     "settings": {
       "audio": "Paramètres audio",
       "video": "Paramètres video"
@@ -67,6 +71,7 @@
     },
     "cameraDisabled": "La caméra est désactivée.",
     "cameraNotFound": "Aucune caméra détectée. Vérifiez qu'elle est bien branchée.",
+    "cameraInUse": "Votre caméra n'est pas disponible. Elle est probablement utilisée par une autre application ou un autre onglet.",
     "cameraStarting": "La caméra va démarrer…",
     "cameraNotGranted": "Souhaitez-vous que les autres puissent vous voir pendant la réunion ?",
     "cameraAndMicNotGranted": "Souhaitez-vous que les autres puissent vous voir et vous entendre pendant la réunion ?",

src/frontend/src/locales/nl/rooms.json

@@ -16,6 +16,10 @@
       "videoinput": "Geen camera gedetecteerd. Controleer of deze goed is aangesloten.",
       "audioinput": "Geen microfoon gedetecteerd. Controleer of deze goed is aangesloten."
     },
+    "deviceInUse": {
+      "videoinput": "Camera niet beschikbaar: deze wordt waarschijnlijk gebruikt door een andere toepassing of een ander tabblad.",
+      "audioinput": "Microfoon niet beschikbaar: deze wordt waarschijnlijk gebruikt door een andere toepassing of een ander tabblad."
+    },
     "settings": {
       "audio": "Audio-instellingen",
       "video": "Video-instellingen"
@@ -67,6 +71,7 @@
     },
     "cameraDisabled": "Camera is uitgeschakeld.",
     "cameraNotFound": "Geen camera gedetecteerd. Controleer of deze goed is aangesloten.",
+    "cameraInUse": "Je camera is niet beschikbaar. Deze wordt waarschijnlijk gebruikt door een andere toepassing of een ander tabblad.",
     "cameraStarting": "Camera wordt ingeschakeld…",
     "cameraNotGranted": "Wilt u dat anderen u tijdens de vergadering kunnen zien?",
     "cameraAndMicNotGranted": "Wilt u dat anderen u tijdens de vergadering kunnen zien en horen?",

src/frontend/src/stores/deviceAvailability.ts

@@ -1,14 +1,68 @@
 import { proxy } from 'valtio'
 import { captureMediaEvent, reportError } from '@/features/analytics/telemetry'
+import type { PermissionKind } from './permissions'
 
-// Device presence (not permission): enumerateDevices() exposes kinds
-// before any grant. Optimistic defaults until the first sync.
-export const deviceAvailabilityStore = proxy({
+// Device availability (not permission):
+// - presence: enumerateDevices() exposes kinds before any grant.
+//   Optimistic defaults until the first sync.
+// - in use: the device exists and is allowed, but getUserMedia() failed
+//   because another application or tab is holding it. The id of the
+//   affected device is kept (when known) so that a selection change can
+//   invalidate a flag that no longer concerns the selected device.
+export const deviceAvailabilityStore = proxy<{
+  hasCamera: boolean
+  hasMicrophone: boolean
+  cameraInUse: boolean
+  microphoneInUse: boolean
+  cameraInUseDeviceId?: string
+  microphoneInUseDeviceId?: string
+  synced: boolean
+}>({
   hasCamera: true,
   hasMicrophone: true,
+  cameraInUse: false,
+  microphoneInUse: false,
   synced: false,
 })
 
+const IN_USE_KEY: Record<PermissionKind, 'cameraInUse' | 'microphoneInUse'> = {
+  camera: 'cameraInUse',
+  microphone: 'microphoneInUse',
+}
+
+const IN_USE_DEVICE_KEY: Record<
+  PermissionKind,
+  'cameraInUseDeviceId' | 'microphoneInUseDeviceId'
+> = {
+  camera: 'cameraInUseDeviceId',
+  microphone: 'microphoneInUseDeviceId',
+}
+
+const ALL_KINDS: PermissionKind[] = ['camera', 'microphone']
+
+export const noteDeviceInUse = (kind?: PermissionKind, deviceId?: string) => {
+  for (const k of kind ? [kind] : ALL_KINDS) {
+    deviceAvailabilityStore[IN_USE_KEY[k]] = true
+    deviceAvailabilityStore[IN_USE_DEVICE_KEY[k]] = deviceId
+  }
+}
+
+export const clearDeviceInUse = (kind?: PermissionKind) => {
+  for (const k of kind ? [kind] : ALL_KINDS) {
+    deviceAvailabilityStore[IN_USE_KEY[k]] = false
+    deviceAvailabilityStore[IN_USE_DEVICE_KEY[k]] = undefined
+  }
+}
+
+export const clearDeviceInUseForOtherDevice = (
+  kind: PermissionKind,
+  selectedDeviceId?: string
+) => {
+  const affected = deviceAvailabilityStore[IN_USE_DEVICE_KEY[kind]]
+  if (!affected || !selectedDeviceId || affected === selectedDeviceId) return
+  clearDeviceInUse(kind)
+}
+
 export const syncDeviceAvailability = async (): Promise<void> => {
   try {
     const devices = await navigator.mediaDevices.enumerateDevices()