@werxt/livekit-components-react 2.9.20

package/src/hooks/useLiveKitRoom.ts

@@ -0,0 +1,186 @@
+import { log, setupLiveKitRoom } from '@livekit/components-core';
+import type { DisconnectReason } from 'livekit-client';
+import { Room, MediaDeviceFailure, RoomEvent } from 'livekit-client';
+import * as React from 'react';
+import type { HTMLAttributes } from 'react';
+
+import type { LiveKitRoomProps } from '../components';
+import { mergeProps } from '../mergeProps';
+import { roomOptionsStringifyReplacer } from '../utils';
+
+const defaultRoomProps: Partial<LiveKitRoomProps> = {
+  connect: true,
+  audio: false,
+  video: false,
+};
+
+/**
+ * The `useLiveKitRoom` hook is used to implement the `LiveKitRoom` or your custom implementation of it.
+ * It returns a `Room` instance and HTML props that should be applied to the root element of the component.
+ *
+ * @example
+ * ```tsx
+ * const { room, htmlProps } = useLiveKitRoom();
+ * return <div {...htmlProps}>...</div>;
+ * ```
+ * @public
+ */
+export function useLiveKitRoom<T extends HTMLElement>(
+  props: LiveKitRoomProps,
+): {
+  room: Room | undefined;
+  htmlProps: HTMLAttributes<T>;
+} {
+  const {
+    token,
+    serverUrl,
+    options,
+    room: passedRoom,
+    connectOptions,
+    connect,
+    audio,
+    video,
+    screen,
+    onConnected,
+    onDisconnected,
+    onError,
+    onMediaDeviceFailure,
+    onEncryptionError,
+    simulateParticipants,
+    ...rest
+  } = { ...defaultRoomProps, ...props };
+  if (options && passedRoom) {
+    log.warn(
+      'when using a manually created room, the options object will be ignored. set the desired options directly when creating the room instead.',
+    );
+  }
+
+  const [room, setRoom] = React.useState<Room | undefined>();
+
+  const shouldConnect = React.useRef(connect);
+
+  React.useEffect(() => {
+    setRoom(passedRoom ?? new Room(options));
+  }, [passedRoom, JSON.stringify(options, roomOptionsStringifyReplacer)]);
+
+  const htmlProps = React.useMemo(() => {
+    const { className } = setupLiveKitRoom();
+    return mergeProps(rest, { className }) as HTMLAttributes<T>;
+  }, [rest]);
+
+  React.useEffect(() => {
+    if (!room) return;
+    const onSignalConnected = () => {
+      const localP = room.localParticipant;
+
+      log.debug('trying to publish local tracks');
+      Promise.all([
+        localP.setMicrophoneEnabled(!!audio, typeof audio !== 'boolean' ? audio : undefined),
+        localP.setCameraEnabled(!!video, typeof video !== 'boolean' ? video : undefined),
+        localP.setScreenShareEnabled(!!screen, typeof screen !== 'boolean' ? screen : undefined),
+      ]).catch((e) => {
+        log.warn(e);
+        onError?.(e as Error);
+      });
+    };
+
+    const handleMediaDeviceError = (e: Error, kind?: MediaDeviceKind) => {
+      const mediaDeviceFailure = MediaDeviceFailure.getFailure(e);
+      onMediaDeviceFailure?.(mediaDeviceFailure, kind);
+    };
+    const handleEncryptionError = (e: Error) => {
+      onEncryptionError?.(e);
+    };
+    const handleDisconnected = (reason?: DisconnectReason) => {
+      onDisconnected?.(reason);
+    };
+    const handleConnected = () => {
+      onConnected?.();
+    };
+
+    room
+      .on(RoomEvent.SignalConnected, onSignalConnected)
+      .on(RoomEvent.MediaDevicesError, handleMediaDeviceError)
+      .on(RoomEvent.EncryptionError, handleEncryptionError)
+      .on(RoomEvent.Disconnected, handleDisconnected)
+      .on(RoomEvent.Connected, handleConnected);
+
+    return () => {
+      room
+        .off(RoomEvent.SignalConnected, onSignalConnected)
+        .off(RoomEvent.MediaDevicesError, handleMediaDeviceError)
+        .off(RoomEvent.EncryptionError, handleEncryptionError)
+        .off(RoomEvent.Disconnected, handleDisconnected)
+        .off(RoomEvent.Connected, handleConnected);
+    };
+  }, [
+    room,
+    audio,
+    video,
+    screen,
+    onError,
+    onEncryptionError,
+    onMediaDeviceFailure,
+    onConnected,
+    onDisconnected,
+  ]);
+
+  React.useEffect(() => {
+    if (!room) return;
+
+    if (simulateParticipants) {
+      room.simulateParticipants({
+        participants: {
+          count: simulateParticipants,
+        },
+        publish: {
+          audio: true,
+          useRealTracks: true,
+        },
+      });
+      return;
+    }
+
+    if (connect) {
+      shouldConnect.current = true;
+      log.debug('connecting');
+      if (!token) {
+        log.debug('no token yet');
+        return;
+      }
+      if (!serverUrl) {
+        log.warn('no livekit url provided');
+        onError?.(Error('no livekit url provided'));
+        return;
+      }
+      room.connect(serverUrl, token, connectOptions).catch((e) => {
+        log.warn(e);
+        if (shouldConnect.current === true) {
+          onError?.(e as Error);
+        }
+      });
+    } else {
+      log.debug('disconnecting because connect is false');
+      shouldConnect.current = false;
+      room.disconnect();
+    }
+  }, [
+    connect,
+    token,
+    JSON.stringify(connectOptions),
+    room,
+    onError,
+    serverUrl,
+    simulateParticipants,
+  ]);
+
+  React.useEffect(() => {
+    if (!room) return;
+    return () => {
+      log.info('disconnecting on onmount');
+      room.disconnect();
+    };
+  }, [room]);
+
+  return { room, htmlProps };
+}

package/src/hooks/useLocalParticipant.ts

@@ -0,0 +1,73 @@
+import type { ParticipantMedia } from '@livekit/components-core';
+import { observeParticipantMedia } from '@livekit/components-core';
+import type { TrackPublication, LocalParticipant, Room } from 'livekit-client';
+import * as React from 'react';
+import { useEnsureRoom } from '../context';
+
+/** @public */
+export interface UseLocalParticipantOptions {
+  /**
+   * The room to use. If not provided, the hook will use the room from the context.
+   */
+  room?: Room;
+}
+
+/**
+ * The `useLocalParticipant` hook returns the local participant and the associated state
+ * around the participant.
+ *
+ * @example
+ * ```tsx
+ * const { localParticipant } = useLocalParticipant();
+ * ```
+ * @public
+ */
+export function useLocalParticipant(options: UseLocalParticipantOptions = {}) {
+  const room = useEnsureRoom(options.room);
+  const [localParticipant, setLocalParticipant] = React.useState(room.localParticipant);
+
+  const [isMicrophoneEnabled, setIsMicrophoneEnabled] = React.useState(
+    localParticipant.isMicrophoneEnabled,
+  );
+  const [isCameraEnabled, setIsCameraEnabled] = React.useState(localParticipant.isCameraEnabled);
+  const [isScreenShareEnabled, setIsScreenShareEnabled] = React.useState(
+    localParticipant.isScreenShareEnabled,
+  );
+
+  const [lastMicrophoneError, setLastMicrophoneError] = React.useState(
+    localParticipant.lastMicrophoneError,
+  );
+  const [lastCameraError, setLastCameraError] = React.useState(localParticipant.lastCameraError);
+
+  const [microphoneTrack, setMicrophoneTrack] = React.useState<TrackPublication | undefined>(
+    undefined,
+  );
+  const [cameraTrack, setCameraTrack] = React.useState<TrackPublication | undefined>(undefined);
+
+  const handleUpdate = (media: ParticipantMedia<LocalParticipant>) => {
+    setIsCameraEnabled(media.isCameraEnabled);
+    setIsMicrophoneEnabled(media.isMicrophoneEnabled);
+    setIsScreenShareEnabled(media.isScreenShareEnabled);
+    setCameraTrack(media.cameraTrack);
+    setMicrophoneTrack(media.microphoneTrack);
+    setLastMicrophoneError(media.participant.lastMicrophoneError);
+    setLastCameraError(media.participant.lastCameraError);
+    setLocalParticipant(media.participant);
+  };
+  React.useEffect(() => {
+    const listener = observeParticipantMedia(room.localParticipant).subscribe(handleUpdate);
+    // TODO also listen to permission and metadata etc. events
+    return () => listener.unsubscribe();
+  }, [room]);
+
+  return {
+    isMicrophoneEnabled,
+    isScreenShareEnabled,
+    isCameraEnabled,
+    microphoneTrack,
+    cameraTrack,
+    lastMicrophoneError,
+    lastCameraError,
+    localParticipant,
+  };
+}

package/src/hooks/useLocalParticipantPermissions.ts

@@ -0,0 +1,24 @@
+import { participantPermissionObserver } from '@livekit/components-core';
+import type { ParticipantPermission } from '@livekit/protocol';
+import * as React from 'react';
+import { useRoomContext } from '../context';
+import { useObservableState } from './internal';
+
+/**
+ * The `useLocalParticipantPermissions` hook returns the local participant's permissions.
+ *
+ * @example
+ * ```tsx
+ * const { canPublish, canPublishData } = useLocalParticipantPermissions();
+ * ```
+ * @public
+ */
+export function useLocalParticipantPermissions(): ParticipantPermission | undefined {
+  const room = useRoomContext();
+  const permissionObserver = React.useMemo(
+    () => participantPermissionObserver(room.localParticipant),
+    [room],
+  );
+  const permissions = useObservableState(permissionObserver, room.localParticipant.permissions);
+  return permissions;
+}

package/src/hooks/useMediaDeviceSelect.ts

@@ -0,0 +1,81 @@
+import { createMediaDeviceObserver, setupDeviceSelector, log } from '@livekit/components-core';
+import { Room, type LocalAudioTrack, type LocalVideoTrack } from 'livekit-client';
+import * as React from 'react';
+import { useMaybeRoomContext } from '../context';
+import { useObservableState } from './internal';
+
+/** @public */
+export interface UseMediaDeviceSelectProps {
+  kind: MediaDeviceKind;
+  room?: Room;
+  track?: LocalAudioTrack | LocalVideoTrack;
+  /**
+   * this will call getUserMedia if the permissions are not yet given to enumerate the devices with device labels.
+   * in some browsers multiple calls to getUserMedia result in multiple permission prompts.
+   * It's generally advised only flip this to true, once a (preview) track has been acquired successfully with the
+   * appropriate permissions.
+   *
+   * @see {@link MediaDeviceMenu}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices | MDN enumerateDevices}
+   */
+  requestPermissions?: boolean;
+  /**
+   * this callback gets called if an error is thrown when failing to select a device and also if a user
+   * denied permissions, eventhough the `requestPermissions` option is set to `true`.
+   * Most commonly this will emit a MediaDeviceError
+   */
+  onError?: (e: Error) => void;
+}
+
+/**
+ * The `useMediaDeviceSelect` hook is used to implement the `MediaDeviceSelect` component and
+ * returns o.a. the list of devices of a given kind (audioinput or videoinput), the currently active device
+ * and a function to set the the active device.
+ *
+ * @example
+ * ```tsx
+ * const { devices, activeDeviceId, setActiveMediaDevice } = useMediaDeviceSelect({kind: 'audioinput'});
+ * ```
+ * @public
+ */
+export function useMediaDeviceSelect({
+  kind,
+  room,
+  track,
+  requestPermissions,
+  onError,
+}: UseMediaDeviceSelectProps) {
+  const roomContext = useMaybeRoomContext();
+
+  const roomFallback = React.useMemo(() => room ?? roomContext ?? new Room(), [room, roomContext]);
+
+  // List of all devices.
+  const deviceObserver = React.useMemo(
+    () => createMediaDeviceObserver(kind, onError, requestPermissions),
+    [kind, requestPermissions, onError],
+  );
+  const devices = useObservableState(deviceObserver, [] as MediaDeviceInfo[]);
+  // Active device management.
+  const [currentDeviceId, setCurrentDeviceId] = React.useState<string>(
+    roomFallback?.getActiveDevice(kind) ?? 'default',
+  );
+  const { className, activeDeviceObservable, setActiveMediaDevice } = React.useMemo(
+    () => setupDeviceSelector(kind, roomFallback),
+    [kind, roomFallback, track],
+  );
+
+  React.useEffect(() => {
+    const listener = activeDeviceObservable.subscribe((deviceId) => {
+      if (!deviceId) {
+        return;
+      }
+      log.info('setCurrentDeviceId', deviceId);
+      setCurrentDeviceId(deviceId);
+    });
+    return () => {
+      listener?.unsubscribe();
+    };
+  }, [activeDeviceObservable]);
+
+  return { devices, className, activeDeviceId: currentDeviceId, setActiveMediaDevice };
+}

package/src/hooks/useMediaDevices.ts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+import { useObservableState } from './internal';
+import { createMediaDeviceObserver } from '@livekit/components-core';
+
+/**
+ * The `useMediaDevices` hook returns the list of media devices of a given kind.
+ *
+ * @example
+ * ```tsx
+ * const videoDevices = useMediaDevices({ kind: 'videoinput' });
+ * const audioDevices = useMediaDevices({ kind: 'audioinput' });
+ * ```
+ * @public
+ */
+export function useMediaDevices({
+  kind,
+  onError,
+}: {
+  kind: MediaDeviceKind;
+  onError?: (e: Error) => void;
+}) {
+  const deviceObserver = React.useMemo(
+    () => createMediaDeviceObserver(kind, onError),
+    [kind, onError],
+  );
+  const devices = useObservableState(deviceObserver, [] as MediaDeviceInfo[]);
+  return devices;
+}

package/src/hooks/useMediaTrackBySourceOrName.ts

@@ -0,0 +1,97 @@
+import type { TrackIdentifier } from '@livekit/components-core';
+import {
+  getTrackByIdentifier,
+  isTrackReference,
+  log,
+  setupMediaTrack,
+} from '@livekit/components-core';
+import * as React from 'react';
+import { mergeProps } from '../utils';
+
+/** @public */
+export interface UseMediaTrackOptions {
+  element?: React.RefObject<HTMLMediaElement> | null;
+  props?: React.HTMLAttributes<HTMLVideoElement | HTMLAudioElement>;
+}
+
+/**
+ * @internal
+ */
+export function useMediaTrackBySourceOrName(
+  observerOptions: TrackIdentifier,
+  options: UseMediaTrackOptions = {},
+) {
+  const [publication, setPublication] = React.useState(getTrackByIdentifier(observerOptions));
+
+  const [isMuted, setMuted] = React.useState(publication?.isMuted);
+  const [isSubscribed, setSubscribed] = React.useState(publication?.isSubscribed);
+
+  const [track, setTrack] = React.useState(publication?.track);
+  const [orientation, setOrientation] = React.useState<'landscape' | 'portrait'>('landscape');
+  const previousElement = React.useRef<HTMLMediaElement | undefined | null>();
+
+  const { className, trackObserver } = React.useMemo(() => {
+    return setupMediaTrack(observerOptions);
+  }, [
+    observerOptions.participant.sid ?? observerOptions.participant.identity,
+    observerOptions.source,
+    isTrackReference(observerOptions) && observerOptions.publication.trackSid,
+  ]);
+
+  React.useEffect(() => {
+    const subscription = trackObserver.subscribe((publication) => {
+      log.debug('update track', publication);
+      setPublication(publication);
+      setMuted(publication?.isMuted);
+      setSubscribed(publication?.isSubscribed);
+      setTrack(publication?.track);
+    });
+    return () => subscription?.unsubscribe();
+  }, [trackObserver]);
+
+  React.useEffect(() => {
+    if (track) {
+      if (previousElement.current) {
+        track.detach(previousElement.current);
+      }
+      if (
+        options.element?.current &&
+        !(observerOptions.participant.isLocal && track?.kind === 'audio')
+      ) {
+        track.attach(options.element.current);
+      }
+    }
+    previousElement.current = options.element?.current;
+    return () => {
+      if (previousElement.current) {
+        track?.detach(previousElement.current);
+      }
+    };
+  }, [track, options.element]);
+
+  React.useEffect(() => {
+    // Set the orientation of the video track.
+    // TODO: This does not handle changes in orientation after a track got published (e.g when rotating a phone camera from portrait to landscape).
+    if (
+      typeof publication?.dimensions?.width === 'number' &&
+      typeof publication?.dimensions?.height === 'number'
+    ) {
+      const orientation_ =
+        publication.dimensions.width > publication.dimensions.height ? 'landscape' : 'portrait';
+      setOrientation(orientation_);
+    }
+  }, [publication]);
+
+  return {
+    publication,
+    isMuted,
+    isSubscribed,
+    track,
+    elementProps: mergeProps(options.props, {
+      className,
+      'data-lk-local-participant': observerOptions.participant.isLocal,
+      'data-lk-source': publication?.source,
+      ...(publication?.kind === 'video' && { 'data-lk-orientation': orientation }),
+    }),
+  };
+}

package/src/hooks/usePagination.test.ts

@@ -0,0 +1,77 @@
+import { describe, test, expect } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import usePagination from './usePagination';
+import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
+
+describe('Test hook', () => {
+  test('Test basic assumptions of the usePagination hook return values.', () => {
+    const itemPerPage = 4;
+    const totalTrackRefs = new Array(12) as TrackReferenceOrPlaceholder[];
+    const { result } = renderHook(() => usePagination(itemPerPage, totalTrackRefs));
+
+    expect(result.current.currentPage).toBe(1);
+    expect(result.current.totalPageCount).toBe(3);
+    expect(result.current.firstItemIndex).toBe(0);
+    expect(result.current.lastItemIndex).toBe(4);
+    expect(result.current.prevPage).toBeTypeOf('function');
+    expect(result.current.nextPage).toBeTypeOf('function');
+  });
+  test('Test moving to pages works as expected.', () => {
+    const itemPerPage = 4;
+    const totalTrackRefs = new Array(12) as TrackReferenceOrPlaceholder[];
+    const { result, rerender } = renderHook(() => usePagination(itemPerPage, totalTrackRefs));
+
+    expect(result.current.currentPage).toBe(1);
+
+    result.current.nextPage();
+    rerender();
+    expect(result.current.currentPage).toBe(2);
+
+    result.current.nextPage();
+    rerender();
+    expect(result.current.currentPage).toBe(3);
+
+    // Check top limit is working.
+    result.current.nextPage();
+    rerender();
+    expect(result.current.currentPage).toBe(3);
+
+    result.current.prevPage();
+    rerender();
+    expect(result.current.currentPage).toBe(2);
+
+    result.current.prevPage();
+    rerender();
+    expect(result.current.currentPage).toBe(1);
+
+    // Test bottom limit is working.
+    result.current.prevPage();
+    rerender();
+    expect(result.current.currentPage).toBe(1);
+  });
+
+  test('Test jumping to pages works as expected.', () => {
+    const itemPerPage = 4;
+    const totalTrackRefs = new Array(12) as TrackReferenceOrPlaceholder[];
+    const { result, rerender } = renderHook(() => usePagination(itemPerPage, totalTrackRefs));
+    expect(result.current.currentPage).toBe(1);
+
+    result.current.setPage(3);
+    rerender();
+    expect(result.current.currentPage).toBe(3);
+
+    result.current.setPage(2);
+    rerender();
+    expect(result.current.currentPage).toBe(2);
+
+    // Jumping to a index that is lower than 1 jumps to page 1.
+    result.current.setPage(0);
+    rerender();
+    expect(result.current.currentPage).toBe(1);
+
+    // Jumping to a index that is higher than the last page jumps to last page.
+    result.current.setPage(999999);
+    rerender();
+    expect(result.current.currentPage).toBe(3);
+  });
+});

package/src/hooks/usePagination.ts

@@ -0,0 +1,67 @@
+import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
+import * as React from 'react';
+import { useVisualStableUpdate } from './useVisualStableUpdate';
+
+/**
+ * The `usePagination` hook implements simple pagination logic for use with arrays.
+ * @example
+ * ```tsx
+ * const tracks = useTracks();
+ * const pagination = usePagination(4, tracks);
+ *
+ * <TrackLoop tracks={pagination.tracks} />
+ * ```
+ * @alpha
+ */
+export function usePagination(itemPerPage: number, trackReferences: TrackReferenceOrPlaceholder[]) {
+  const [currentPage, setCurrentPage] = React.useState(1);
+  const totalPageCount = Math.max(Math.ceil(trackReferences.length / itemPerPage), 1);
+  if (currentPage > totalPageCount) {
+    setCurrentPage(totalPageCount);
+  }
+  const lastItemIndex = currentPage * itemPerPage;
+  const firstItemIndex = lastItemIndex - itemPerPage;
+
+  const changePage = (direction: 'next' | 'previous') => {
+    setCurrentPage((state) => {
+      if (direction === 'next') {
+        if (state === totalPageCount) {
+          return state;
+        }
+        return state + 1;
+      } else {
+        if (state === 1) {
+          return state;
+        }
+        return state - 1;
+      }
+    });
+  };
+
+  const goToPage = (num: number) => {
+    if (num > totalPageCount) {
+      setCurrentPage(totalPageCount);
+    } else if (num < 1) {
+      setCurrentPage(1);
+    } else {
+      setCurrentPage(num);
+    }
+  };
+
+  const updatedTrackReferences = useVisualStableUpdate(trackReferences, itemPerPage);
+
+  const tracksOnPage = updatedTrackReferences.slice(firstItemIndex, lastItemIndex);
+
+  return {
+    totalPageCount,
+    nextPage: () => changePage('next'),
+    prevPage: () => changePage('previous'),
+    setPage: goToPage,
+    firstItemIndex,
+    lastItemIndex,
+    tracks: tracksOnPage,
+    currentPage,
+  };
+}
+
+export default usePagination;