✨(frontend) introduce performance mode with auto-detection and telemetry

CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to
 
 ## [Unreleased]
 
+### Added
+
+- ✨(frontend) introduce performance mode with auto-detection and telemetry
+
 ### Changed
 
 - 🔥(frontend) drop unused vendored ConnectionObserver

src/frontend/src/features/analytics/hardware.ts

@@ -0,0 +1,71 @@
+export interface HardwareSnapshot {
+  /** navigator.hardwareConcurrency — logical CPU cores. */
+  cpu_cores: number | null
+  /** navigator.deviceMemory — RAM in GiB, bucketed by the browser (Chromium only). */
+  device_memory_gb: number | null
+  /** performance.memory.jsHeapSizeLimit in MB (Chromium only, non-standard). */
+  js_heap_limit_mb: number | null
+  /** performance.memory.usedJSHeapSize in MB (Chromium only, non-standard). */
+  js_heap_used_mb: number | null
+  /** Battery level 0..1 via navigator.getBattery() (Chromium only). */
+  battery_level: number | null
+  /** Whether the device is plugged in, via navigator.getBattery(). */
+  battery_charging: boolean | null
+}
+
+const BATTERY_TIMEOUT_MS = 1_000
+
+const toMb = (bytes: unknown): number | null =>
+  typeof bytes === 'number' ? Math.round(bytes / (1024 * 1024)) : null
+
+export const collectHardwareSnapshot = async (): Promise<HardwareSnapshot> => {
+  const snapshot: HardwareSnapshot = {
+    cpu_cores: null,
+    device_memory_gb: null,
+    js_heap_limit_mb: null,
+    js_heap_used_mb: null,
+    battery_level: null,
+    battery_charging: null,
+  }
+
+  try {
+    snapshot.cpu_cores = navigator.hardwareConcurrency ?? null
+
+    const nav = navigator as Navigator & {
+      deviceMemory?: number
+      userAgentData?: { mobile?: boolean; platform?: string }
+      getBattery?: () => Promise<{ level: number; charging: boolean }>
+    }
+
+    snapshot.device_memory_gb = nav.deviceMemory ?? null
+
+    const memory = (
+      performance as Performance & {
+        memory?: { jsHeapSizeLimit?: number; usedJSHeapSize?: number }
+      }
+    ).memory
+    snapshot.js_heap_limit_mb = toMb(memory?.jsHeapSizeLimit)
+    snapshot.js_heap_used_mb = toMb(memory?.usedJSHeapSize)
+
+    if (typeof nav.getBattery === 'function') {
+      // getBattery can hang on some platforms — don't let it delay the event.
+      let timeoutId: ReturnType<typeof setTimeout> | undefined
+      const battery = await Promise.race([
+        nav.getBattery(),
+        new Promise<null>((resolve) => {
+          timeoutId = setTimeout(() => resolve(null), BATTERY_TIMEOUT_MS)
+        }),
+      ])
+        .catch(() => null)
+        .finally(() => clearTimeout(timeoutId))
+      if (battery) {
+        snapshot.battery_level = battery.level
+        snapshot.battery_charging = battery.charging
+      }
+    }
+  } catch {
+    // telemetry must never break the app
+  }
+
+  return snapshot
+}

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

@@ -30,6 +30,7 @@ export type LogCode =
   | 'clipboard_failure'
   | 'fullscreen_failure'
   | 'publish_sources_failure'
+  | 'performance_mode_failure'
   | 'disconnect_failure'
   | 'generic_failure'
 

src/frontend/src/features/notifications/NotificationDuration.ts

@@ -3,6 +3,7 @@ export enum ToastDuration {
   MEDIUM = 4000,
   LONG = 5000,
   EXTRA_LONG = 7000,
+  UNDO_WINDOW = 30000,
 }
 
 export const NotificationDuration = {
@@ -15,4 +16,5 @@ export const NotificationDuration = {
   REACTION_RECEIVED: ToastDuration.SHORT,
   RECORDING_REQUESTED: ToastDuration.LONG,
   ROLE_CHANGED: ToastDuration.LONG,
+  CPU_CONSTRAINED: ToastDuration.UNDO_WINDOW,
 } as const

src/frontend/src/features/notifications/NotificationType.ts

@@ -18,4 +18,5 @@ export enum NotificationType {
   RecordingSaving = 'recordingSaving',
   PermissionsRemoved = 'permissionsRemoved',
   RoleChanged = 'roleChanged',
+  CpuConstrained = 'cpuConstrained',
 }

src/frontend/src/features/notifications/components/ToastCpuConstrained.tsx

@@ -0,0 +1,69 @@
+import { useToast } from 'react-aria'
+import { useRef } from 'react'
+import { RiCloseLine } from '@remixicon/react'
+
+import { type ToastProps } from './Toast'
+import { HStack, VStack } from '@/styled-system/jsx'
+import { useTranslation } from 'react-i18next'
+import { Button, Text } from '@/primitives'
+import { css } from '@/styled-system/css'
+import { StyledToastContainer } from './StyledToastContainer'
+import { disablePerformanceMode } from '@/stores/performanceMode'
+import { captureEvent } from '@/features/analytics/telemetry'
+
+export function ToastCpuConstrained({ state, ...props }: Readonly<ToastProps>) {
+  const { t } = useTranslation('notifications', {
+    keyPrefix: 'cpuConstrained',
+  })
+  const ref = useRef(null)
+  const { toastProps, contentProps, closeButtonProps } = useToast(
+    props,
+    state,
+    ref
+  )
+  const toast = props.toast
+
+  const handleKeepQuality = () => {
+    captureEvent('cpu-constrained-degradation-cancelled')
+    disablePerformanceMode({ declinedAuto: true })
+    state.close(toast.key)
+  }
+
+  return (
+    <StyledToastContainer {...toastProps} ref={ref}>
+      <HStack alignItems="start" gap="0.5rem" padding={14}>
+        <VStack
+          justify="start"
+          alignItems="self-start"
+          {...contentProps}
+          maxWidth="370px"
+          gap="0.75rem"
+        >
+          <Text
+            margin={false}
+            className={css({
+              wordBreak: 'break-word',
+              overflowWrap: 'break-word',
+              whiteSpace: 'normal',
+            })}
+          >
+            {t('message')}
+          </Text>
+          <Button
+            size="sm"
+            variant="text"
+            className={css({
+              color: 'primary.300',
+            })}
+            onPress={() => handleKeepQuality()}
+          >
+            {t('keepQuality')}
+          </Button>
+        </VStack>
+        <Button square size="sm" invisible {...closeButtonProps}>
+          <RiCloseLine size={18} color="white" />
+        </Button>
+      </HStack>
+    </StyledToastContainer>
+  )
+}

src/frontend/src/features/notifications/components/ToastRegion.tsx

@@ -15,6 +15,7 @@ import { ToastPermissionsRemoved } from './ToastPermissionsRemoved'
 import { ToastRecordingRequest } from './ToastRecordingRequest'
 import { ToastAutoMuteLargeRoom } from './ToastAutoMuteLargeRoom'
 import { ToastRoleChanged } from '@/features/notifications/components/ToastRoleChanged'
+import { ToastCpuConstrained } from './ToastCpuConstrained'
 
 interface ToastRegionProps extends AriaToastRegionProps {
   state: ToastState<ToastData>
@@ -74,6 +75,9 @@ const renderToast = (
     case NotificationType.RoleChanged:
       return <ToastRoleChanged key={toast.key} toast={toast} state={state} />
 
+    case NotificationType.CpuConstrained:
+      return <ToastCpuConstrained key={toast.key} toast={toast} state={state} />
+
     default:
       return <Toast key={toast.key} toast={toast} state={state} />
   }

src/frontend/src/features/notifications/utils.ts

@@ -15,6 +15,15 @@ export const notifyAutoMutedOnJoin = () => {
   )
 }
 
+export const notifyCpuConstrained = () => {
+  toastQueue.add(
+    {
+      type: NotificationType.CpuConstrained,
+    },
+    { timeout: NotificationDuration.CPU_CONSTRAINED }
+  )
+}
+
 export const showLowerHandToast = (
   participant: Participant,
   onClose: () => void

src/frontend/src/features/performance/components/CpuConstrainedObserver.tsx

@@ -0,0 +1,71 @@
+import { useEffect, useRef } from 'react'
+import { useRoomContext } from '@livekit/components-react'
+import {
+  LocalTrackPublication,
+  LocalVideoTrack,
+  ParticipantEvent,
+  Track,
+} from 'livekit-client'
+
+import { captureEvent } from '@/features/analytics/telemetry'
+import { collectHardwareSnapshot } from '@/features/analytics/hardware'
+import { notifyCpuConstrained } from '@/features/notifications/utils'
+import { isFireFox } from '@/utils/livekit'
+import {
+  enablePerformanceMode,
+  performanceModeStore,
+} from '@/stores/performanceMode'
+
+export const CpuConstrainedObserver = () => {
+  const room = useRoomContext()
+  const degradedTracksRef = useRef(new WeakSet<LocalVideoTrack>())
+
+  useEffect(() => {
+    const localParticipant = room.localParticipant
+
+    const handleCpuConstrained = (
+      track: LocalVideoTrack,
+      publication: LocalTrackPublication
+    ) => {
+      const { enabled, userDeclinedAuto } = performanceModeStore
+
+      const shouldDegrade =
+        publication.source === Track.Source.Camera &&
+        !enabled &&
+        !userDeclinedAuto &&
+        !degradedTracksRef.current.has(track)
+
+      void collectHardwareSnapshot().then((hardware) => {
+        captureEvent('cpu-constrained', {
+          firefox: isFireFox(),
+          source: publication.source,
+          degraded: shouldDegrade,
+          trackOptions: publication.options,
+          performance_mode_enabled: enabled,
+          user_declined_auto: userDeclinedAuto,
+          ...hardware,
+        })
+      })
+
+      if (!shouldDegrade) return
+      degradedTracksRef.current.add(track)
+
+      enablePerformanceMode('cpu')
+      notifyCpuConstrained()
+    }
+
+    localParticipant.on(
+      ParticipantEvent.LocalTrackCpuConstrained,
+      handleCpuConstrained
+    )
+
+    return () => {
+      localParticipant.off(
+        ParticipantEvent.LocalTrackCpuConstrained,
+        handleCpuConstrained
+      )
+    }
+  }, [room])
+
+  return null
+}

src/frontend/src/features/performance/components/PerformanceModeController.tsx

@@ -0,0 +1,108 @@
+import { useEffect } from 'react'
+import { useRoomContext } from '@livekit/components-react'
+import {
+  LocalTrackPublication,
+  LocalVideoTrack,
+  ParticipantEvent,
+  Track,
+  TrackEvent,
+} from 'livekit-client'
+import { useSnapshot } from 'valtio'
+import { reportError } from '@/features/analytics/telemetry'
+import {
+  disablePerformanceMode,
+  performanceModeStore,
+} from '@/stores/performanceMode'
+import { degradeVideoTrack, restoreVideoTrack } from '../degradation'
+
+/** Delay to re-apply degradation after restart to avoid racing LiveKit's encoding recompute. */
+const REAPPLY_AFTER_RESTART_MS = 1_000
+
+/** Syncs performance mode store state to outbound camera track encoding settings. */
+export const PerformanceModeController = () => {
+  const room = useRoomContext()
+  const { enabled } = useSnapshot(performanceModeStore)
+
+  // Manage degradation application and track lifecycle events
+  useEffect(() => {
+    const localParticipant = room.localParticipant
+
+    const getCameraTrack = () => {
+      const pub = localParticipant.getTrackPublication(Track.Source.Camera)
+      return pub?.track instanceof LocalVideoTrack ? pub.track : null
+    }
+
+    const track = getCameraTrack()
+
+    // Restore track quality if performance mode is disabled
+    if (!enabled) {
+      if (track) {
+        restoreVideoTrack(track).catch((err) =>
+          reportError('performance_mode_failure', err, { action: 'restore' })
+        )
+      }
+      return
+    }
+
+    const applyDegradation = (t: LocalVideoTrack, action = 'degrade') => {
+      degradeVideoTrack(t).catch((err) =>
+        reportError('performance_mode_failure', err, { action })
+      )
+    }
+
+    // Re-apply degradation after track restarts (e.g. device/resolution changes)
+    const watchTrackRestart = (t: LocalVideoTrack) => {
+      let timeoutId: ReturnType<typeof setTimeout>
+      const onRestarted = () => {
+        clearTimeout(timeoutId)
+        timeoutId = setTimeout(() => {
+          if (performanceModeStore.enabled) applyDegradation(t, 'reapply')
+        }, REAPPLY_AFTER_RESTART_MS)
+      }
+      t.on(TrackEvent.Restarted, onRestarted)
+      return () => {
+        clearTimeout(timeoutId)
+        t.off(TrackEvent.Restarted, onRestarted)
+      }
+    }
+
+    let unwatchRestart: (() => void) | undefined
+
+    if (track) {
+      applyDegradation(track)
+      unwatchRestart = watchTrackRestart(track)
+    }
+
+    // Apply degradation to newly published camera tracks
+    const handlePublished = (pub: LocalTrackPublication) => {
+      if (
+        pub.source === Track.Source.Camera &&
+        pub.track instanceof LocalVideoTrack
+      ) {
+        unwatchRestart?.()
+        applyDegradation(pub.track)
+        unwatchRestart = watchTrackRestart(pub.track)
+      }
+    }
+    localParticipant.on(ParticipantEvent.LocalTrackPublished, handlePublished)
+
+    return () => {
+      localParticipant.off(
+        ParticipantEvent.LocalTrackPublished,
+        handlePublished
+      )
+      unwatchRestart?.()
+    }
+  }, [room, enabled])
+
+  // Reset auto (CPU-triggered) performance mode on unmount/leave room
+  useEffect(() => {
+    return () => {
+      if (performanceModeStore.trigger === 'cpu') {
+        disablePerformanceMode()
+      }
+    }
+  }, [])
+
+  return null
+}