@werxt/livekit-components-react 2.9.20

package/src/context/room-context.ts

@@ -0,0 +1,42 @@
+import type { Room } from 'livekit-client';
+import * as React from 'react';
+
+/** @public */
+export const RoomContext = React.createContext<Room | undefined>(undefined);
+
+/**
+ * Ensures that a room is provided via context.
+ * If no room is provided, an error is thrown.
+ * @public
+ */
+export function useRoomContext() {
+  const ctx = React.useContext(RoomContext);
+  if (!ctx) {
+    throw Error('tried to access room context outside of livekit room component');
+  }
+  return ctx;
+}
+
+/**
+ * Returns the room context if it exists, otherwise undefined.
+ * @public
+ */
+export function useMaybeRoomContext() {
+  return React.useContext(RoomContext);
+}
+
+/**
+ * Ensures that a room is provided, either via context or explicitly as a parameter.
+ * If no room is provided, an error is thrown.
+ * @public
+ */
+export function useEnsureRoom(room?: Room) {
+  const context = useMaybeRoomContext();
+  const r = room ?? context;
+  if (!r) {
+    throw new Error(
+      'No room provided, make sure you are inside a Room context or pass the room explicitly',
+    );
+  }
+  return r;
+}

package/src/context/session-context.ts

@@ -0,0 +1,43 @@
+import * as React from 'react';
+
+import { UseSessionReturn } from '../hooks/useSession';
+
+/** @internal */
+export const SessionContext = React.createContext<UseSessionReturn | undefined>(undefined);
+
+/**
+ * Ensures that a session is provided via context.
+ * If no session is provided, an error is thrown.
+ * @beta
+ */
+export function useSessionContext() {
+  const ctx = React.useContext(SessionContext);
+  if (!ctx) {
+    throw Error('tried to access session context outside of SessionProvider component');
+  }
+  return ctx;
+}
+
+/**
+ * Returns the session context if it exists, otherwise undefined.
+ * @beta
+ */
+export function useMaybeSessionContext() {
+  return React.useContext(SessionContext);
+}
+
+/**
+ * Ensures that a session is provided, either via context or explicitly as a parameter.
+ * If no session is provided, an error is thrown.
+ * @beta
+ */
+export function useEnsureSession(session?: UseSessionReturn) {
+  const context = useMaybeSessionContext();
+  const r = session ?? context;
+  if (!r) {
+    throw new Error(
+      'No session provided, make sure you are inside a Session context or pass the session explicitly',
+    );
+  }
+  return r;
+}

package/src/context/track-reference-context.ts

@@ -0,0 +1,47 @@
+import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
+import * as React from 'react';
+
+/**
+ * This context provides a `TrackReferenceOrPlaceholder` to all child components.
+ * @public
+ */
+export const TrackRefContext = React.createContext<TrackReferenceOrPlaceholder | undefined>(
+  undefined,
+);
+
+/**
+ * Ensures that a track reference is provided via context.
+ * If not inside a `TrackRefContext`, an error is thrown.
+ * @public
+ */
+export function useTrackRefContext() {
+  const trackReference = React.useContext(TrackRefContext);
+  if (!trackReference) {
+    throw Error('tried to access track context outside of track context provider');
+  }
+  return trackReference;
+}
+
+/**
+ * Returns a track reference from the `TrackRefContext` if it exists, otherwise `undefined`.
+ * @public
+ */
+export function useMaybeTrackRefContext() {
+  return React.useContext(TrackRefContext);
+}
+
+/**
+ * Ensures that a track reference is provided, either via context or explicitly as a parameter.
+ * If not inside a `TrackRefContext` and no track reference is provided, an error is thrown.
+ * @public
+ */
+export function useEnsureTrackRef(trackRef?: TrackReferenceOrPlaceholder) {
+  const context = useMaybeTrackRefContext();
+  const ref = trackRef ?? context;
+  if (!ref) {
+    throw new Error(
+      'No TrackRef, make sure you are inside a TrackRefContext or pass the TrackRef explicitly',
+    );
+  }
+  return ref;
+}

package/src/hooks/cloud/krisp/useKrispNoiseFilter.ts

@@ -0,0 +1,110 @@
+import * as React from 'react';
+import { LocalAudioTrack } from 'livekit-client';
+import { log } from '@livekit/components-core';
+import type { KrispNoiseFilterProcessor, NoiseFilterOptions } from '@livekit/krisp-noise-filter';
+import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
+import { useLocalParticipant } from '../../..';
+
+/**
+ * @beta
+ */
+export interface useKrispNoiseFilterOptions {
+  /**
+   * The track reference to use for the noise filter (defaults: local microphone track)
+   */
+  trackRef?: TrackReferenceOrPlaceholder;
+  /**
+   * @internal
+   */
+  filterOptions?: NoiseFilterOptions;
+}
+
+/**
+ * Enable the Krisp enhanced noise cancellation feature for local audio tracks.
+ *
+ * Defaults to the localParticipant's microphone track publication, but you can override this behavior by passing in a different track reference.
+ *
+ * @package \@livekit/components-react/krisp
+ * @remarks This filter requires that you install the `@livekit/krisp-noise-filter` package and is supported only on {@link https://cloud.livekit.io | LiveKit Cloud}.
+ * @beta
+ * @example
+ * ```tsx
+ * const krisp = useKrispNoiseFilter();
+ * return <input
+ *   type="checkbox"
+ *   onChange={(ev) => krisp.setNoiseFilterEnabled(ev.target.checked)}
+ *   checked={krisp.isNoiseFilterEnabled}
+ *   disabled={krisp.isNoiseFilterPending}
+ * />
+ * ```
+ * @returns Use `setIsNoiseFilterEnabled` to enable/disable the noise filter.
+ */
+export function useKrispNoiseFilter(options: useKrispNoiseFilterOptions = {}) {
+  const [shouldEnable, setShouldEnable] = React.useState(false);
+  const [isNoiseFilterPending, setIsNoiseFilterPending] = React.useState(false);
+  const [isNoiseFilterEnabled, setIsNoiseFilterEnabled] = React.useState(false);
+  let micPublication = useLocalParticipant().microphoneTrack;
+  const [krispProcessor, setKrispProcessor] = React.useState<
+    KrispNoiseFilterProcessor | undefined
+  >();
+  if (options.trackRef) {
+    micPublication = options.trackRef.publication;
+  }
+
+  const setNoiseFilterEnabled = React.useCallback(async (enable: boolean) => {
+    if (enable) {
+      const { KrispNoiseFilter, isKrispNoiseFilterSupported } = await import(
+        '@livekit/krisp-noise-filter'
+      );
+
+      if (!isKrispNoiseFilterSupported()) {
+        log.warn('LiveKit-Krisp noise filter is not supported in this browser');
+        return;
+      }
+      if (!krispProcessor) {
+        setKrispProcessor(KrispNoiseFilter(options.filterOptions));
+      }
+    }
+    setShouldEnable((prev) => {
+      if (prev !== enable) {
+        setIsNoiseFilterPending(true);
+      }
+      return enable;
+    });
+  }, []);
+
+  React.useEffect(() => {
+    if (micPublication && micPublication.track instanceof LocalAudioTrack && krispProcessor) {
+      const currentProcessor = micPublication.track.getProcessor();
+      if (currentProcessor && currentProcessor.name === 'livekit-noise-filter') {
+        setIsNoiseFilterPending(true);
+        (currentProcessor as KrispNoiseFilterProcessor).setEnabled(shouldEnable).finally(() => {
+          setIsNoiseFilterPending(false);
+          setIsNoiseFilterEnabled(shouldEnable);
+        });
+      } else if (!currentProcessor && shouldEnable) {
+        setIsNoiseFilterPending(true);
+        micPublication?.track
+          ?.setProcessor(krispProcessor)
+          .then(() => krispProcessor.setEnabled(shouldEnable))
+          .then(() => {
+            setIsNoiseFilterEnabled(true);
+          })
+          .catch((e: any) => {
+            setIsNoiseFilterEnabled(false);
+            log.error('Krisp hook: error enabling filter', e);
+          })
+          .finally(() => {
+            setIsNoiseFilterPending(false);
+          });
+      }
+    }
+  }, [shouldEnable, micPublication, krispProcessor]);
+
+  return {
+    setNoiseFilterEnabled,
+    isNoiseFilterEnabled,
+    isNoiseFilterPending,
+    processor: krispProcessor,
+  };
+}

package/src/hooks/index.ts

@@ -0,0 +1,72 @@
+export { useAudioPlayback } from './useAudioPlayback';
+export { useClearPinButton } from './useClearPinButton';
+export {
+  type ConnectionQualityIndicatorOptions,
+  useConnectionQualityIndicator,
+} from './useConnectionQualityIndicator';
+export { useConnectionState } from './useConnectionStatus';
+export { useDataChannel } from './useDataChannel';
+export { useDisconnectButton } from './useDisconnectButton';
+export { useFacingMode } from './useFacingMode';
+export { type UseFocusToggleProps, useFocusToggle } from './useFocusToggle';
+export { useGridLayout } from './useGridLayout';
+export { type UseIsMutedOptions, useIsMuted } from './useIsMuted';
+export { useIsSpeaking } from './useIsSpeaking';
+export { useLiveKitRoom } from './useLiveKitRoom';
+export { type UseLocalParticipantOptions, useLocalParticipant } from './useLocalParticipant';
+export { useLocalParticipantPermissions } from './useLocalParticipantPermissions';
+export { type UseMediaDeviceSelectProps, useMediaDeviceSelect } from './useMediaDeviceSelect';
+export { useMediaDevices } from './useMediaDevices';
+export { usePagination } from './usePagination';
+export { type UseParticipantInfoOptions, useParticipantInfo } from './useParticipantInfo';
+export {
+  type UseParticipantPermissionsOptions,
+  useParticipantPermissions,
+} from './useParticipantPermissions';
+export { type UseParticipantTileProps, useParticipantTile } from './useParticipantTile';
+export { type UseParticipantsOptions, useParticipants } from './useParticipants';
+export { usePinnedTracks } from './usePinnedTracks';
+export { type UseRemoteParticipantOptions, useRemoteParticipant } from './useRemoteParticipant';
+export { type UseRemoteParticipantsOptions, useRemoteParticipants } from './useRemoteParticipants';
+export { type UseRoomInfoOptions, useRoomInfo } from './useRoomInfo';
+export { useSortedParticipants } from './useSortedParticipants';
+export {
+  useSpeakingParticipants,
+  type UseSpeakingParticipantsOptions,
+} from './useSpeakingParticipants';
+export { type UseStartAudioProps, useStartAudio } from './useStartAudio';
+export { type UseStartVideoProps, useStartVideo } from './useStartVideo';
+export { type UseSwipeOptions, useSwipe } from './useSwipe';
+export { type UseChatToggleProps, useChatToggle } from './useChatToggle';
+export { type UseTokenOptions, type UserInfo, useToken } from './useToken';
+export { useTrackMutedIndicator } from './useTrackMutedIndicator';
+export { type UseTrackToggleProps, useTrackToggle } from './useTrackToggle';
+export { type UseTracksHookReturnType, type UseTracksOptions, useTracks } from './useTracks';
+export { type UseVisualStableUpdateOptions, useVisualStableUpdate } from './useVisualStableUpdate';
+// export { UseTrackOptions, useTrack } from './useTrack';
+export { useTrackByName } from './useTrackByName';
+export { useChat } from './useChat';
+export {
+  usePersistentUserChoices,
+  type UsePersistentUserChoicesOptions,
+} from './usePersistentUserChoices';
+export { type UseIsEncryptedOptions, useIsEncrypted } from './useIsEncrypted';
+export * from './useTrackVolume';
+export * from './useParticipantTracks';
+export * from './useTrackTranscription';
+export * from './useVoiceAssistant';
+export * from './useParticipantAttributes';
+export * from './useIsRecording';
+export * from './useTextStream';
+export * from './useTranscriptions';
+export * from './useSequentialRoomConnectDisconnect';
+export * from './useSession';
+export {
+  type AgentState,
+  AgentEvent,
+  type AgentCallbacks,
+  type UseAgentReturn,
+  useAgent,
+} from './useAgent';
+export * from './useEvents';
+export * from './useSessionMessages';

package/src/hooks/internal/index.ts

@@ -0,0 +1,10 @@
+/**
+ * A collection of internal hooks that are not part of the public API
+ * and therefore can be modified or removed at any time.
+ *
+ * @internal
+ */
+
+export * from './useResizeObserver';
+export * from './useObservableState';
+export * from './useMediaQuery';

package/src/hooks/internal/useMediaQuery.ts

@@ -0,0 +1,46 @@
+import * as React from 'react';
+/**
+ * Implementation used from https://github.com/juliencrn/usehooks-ts
+ *
+ * @internal
+ */
+export function useMediaQuery(query: string): boolean {
+  const getMatches = (query: string): boolean => {
+    // Prevents SSR issues
+    if (typeof window !== 'undefined') {
+      return window.matchMedia(query).matches;
+    }
+    return false;
+  };
+
+  const [matches, setMatches] = React.useState<boolean>(getMatches(query));
+
+  function handleChange() {
+    setMatches(getMatches(query));
+  }
+
+  React.useEffect(() => {
+    const matchMedia = window.matchMedia(query);
+
+    // Triggered at the first client-side load and if query changes
+    handleChange();
+
+    // Listen matchMedia
+    if (matchMedia.addListener) {
+      matchMedia.addListener(handleChange);
+    } else {
+      matchMedia.addEventListener('change', handleChange);
+    }
+
+    return () => {
+      if (matchMedia.removeListener) {
+        matchMedia.removeListener(handleChange);
+      } else {
+        matchMedia.removeEventListener('change', handleChange);
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [query]);
+
+  return matches;
+}

package/src/hooks/internal/useObservableState.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+// @ts-ignore
+import type { Observable } from 'rxjs';
+
+/**
+ * @internal
+ */
+export function useObservableState<T>(
+  observable: Observable<T> | undefined,
+  startWith: T,
+  resetWhenObservableChanges = true,
+) {
+  const [state, setState] = React.useState<T>(startWith);
+  React.useEffect(() => {
+    if (resetWhenObservableChanges) {
+      setState(startWith);
+    }
+    // observable state doesn't run in SSR
+    if (typeof window === 'undefined' || !observable) return;
+    const subscription = observable.subscribe(setState);
+    return () => subscription.unsubscribe();
+  }, [observable, resetWhenObservableChanges]);
+  return state;
+}

package/src/hooks/internal/useResizeObserver.ts

@@ -0,0 +1,124 @@
+/* eslint-disable no-return-assign */
+/* eslint-disable no-underscore-dangle */
+import * as React from 'react';
+
+const useLatest = <T>(current: T) => {
+  const storedValue = React.useRef(current);
+  React.useEffect(() => {
+    storedValue.current = current;
+  });
+  return storedValue;
+};
+
+/**
+ * A React hook that fires a callback whenever ResizeObserver detects a change to its size
+ * code extracted from https://github.com/jaredLunde/react-hook/blob/master/packages/resize-observer/src/index.tsx in order to not include the polyfill for resize-observer
+ *
+ * @internal
+ */
+export function useResizeObserver<T extends HTMLElement>(
+  target: React.RefObject<T>,
+  callback: UseResizeObserverCallback,
+) {
+  const resizeObserver = getResizeObserver();
+  const storedCallback = useLatest(callback);
+
+  React.useLayoutEffect(() => {
+    let didUnsubscribe = false;
+
+    const targetEl = target.current;
+    if (!targetEl) return;
+
+    function cb(entry: ResizeObserverEntry, observer: ResizeObserver) {
+      if (didUnsubscribe) return;
+      storedCallback.current(entry, observer);
+    }
+
+    resizeObserver?.subscribe(targetEl as HTMLElement, cb);
+
+    return () => {
+      didUnsubscribe = true;
+      resizeObserver?.unsubscribe(targetEl as HTMLElement, cb);
+    };
+  }, [target.current, resizeObserver, storedCallback]);
+
+  return resizeObserver?.observer;
+}
+
+function createResizeObserver() {
+  let ticking = false;
+  let allEntries: ResizeObserverEntry[] = [];
+
+  const callbacks: Map<unknown, Array<UseResizeObserverCallback>> = new Map();
+
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  const observer = new ResizeObserver((entries: ResizeObserverEntry[], obs: ResizeObserver) => {
+    allEntries = allEntries.concat(entries);
+    if (!ticking) {
+      window.requestAnimationFrame(() => {
+        const triggered = new Set<Element>();
+        for (let i = 0; i < allEntries.length; i++) {
+          if (triggered.has(allEntries[i].target)) continue;
+          triggered.add(allEntries[i].target);
+          const cbs = callbacks.get(allEntries[i].target);
+          cbs?.forEach((cb) => cb(allEntries[i], obs));
+        }
+        allEntries = [];
+        ticking = false;
+      });
+    }
+    ticking = true;
+  });
+
+  return {
+    observer,
+    subscribe(target: HTMLElement, callback: UseResizeObserverCallback) {
+      observer.observe(target);
+      const cbs = callbacks.get(target) ?? [];
+      cbs.push(callback);
+      callbacks.set(target, cbs);
+    },
+    unsubscribe(target: HTMLElement, callback: UseResizeObserverCallback) {
+      const cbs = callbacks.get(target) ?? [];
+      if (cbs.length === 1) {
+        observer.unobserve(target);
+        callbacks.delete(target);
+        return;
+      }
+      const cbIndex = cbs.indexOf(callback);
+      if (cbIndex !== -1) cbs.splice(cbIndex, 1);
+      callbacks.set(target, cbs);
+    },
+  };
+}
+
+let _resizeObserver: ReturnType<typeof createResizeObserver>;
+
+const getResizeObserver = () =>
+  !_resizeObserver ? (_resizeObserver = createResizeObserver()) : _resizeObserver;
+
+export type UseResizeObserverCallback = (
+  entry: ResizeObserverEntry,
+  observer: ResizeObserver,
+) => unknown;
+
+export const useSize = (target: React.RefObject<HTMLDivElement>) => {
+  const [size, setSize] = React.useState({ width: 0, height: 0 });
+  React.useLayoutEffect(() => {
+    if (target.current) {
+      const { width, height } = target.current.getBoundingClientRect();
+      setSize({ width, height });
+    }
+  }, [target.current]);
+
+  const resizeCallback = React.useCallback(
+    (entry: ResizeObserverEntry) => setSize(entry.contentRect),
+    [],
+  );
+  // Where the magic happens
+  useResizeObserver(target, resizeCallback);
+  return size;
+};