@werxt/livekit-components-react 2.9.20

package/src/hooks/useSessionMessages.ts

@@ -0,0 +1,158 @@
+import * as React from 'react';
+import type TypedEventEmitter from 'typed-emitter';
+import { SendTextOptions } from 'livekit-client';
+import { EventEmitter } from 'events';
+import {
+  ReceivedMessage,
+  ReceivedChatMessage,
+  TextStreamData,
+  ReceivedUserTranscriptionMessage,
+  ReceivedAgentTranscriptionMessage,
+} from '@livekit/components-core';
+
+import { useAgent } from './useAgent';
+import { useTranscriptions } from './useTranscriptions';
+import { useChat } from './useChat';
+import { UseSessionReturn } from './useSession';
+import { useEnsureSession } from '../context';
+
+/** @beta */
+export type UseSessionMessagesReturn = {
+  messages: Array<ReceivedMessage>;
+
+  /** Is a send operation currently in progress? */
+  isSending: boolean;
+
+  send: (message: string, options?: SendTextOptions) => Promise<ReceivedChatMessage>;
+
+  internal: {
+    emitter: TypedEventEmitter<MessagesCallbacks>;
+  };
+};
+
+/** @beta */
+export enum MessagesEvent {
+  /**
+   * Emits when a new message is received from a participant
+   * args: (message: ReceivedMessage)
+   */
+  MessageReceived = 'messageReceived',
+}
+
+/** @beta */
+export type MessagesCallbacks = {
+  [MessagesEvent.MessageReceived]: (message: ReceivedMessage) => void;
+};
+
+/** @beta */
+export function useSessionMessages(session?: UseSessionReturn): UseSessionMessagesReturn {
+  const { room } = useEnsureSession(session);
+
+  const emitter = React.useMemo(
+    () => new EventEmitter() as TypedEventEmitter<MessagesCallbacks>,
+    [],
+  );
+
+  const agent = useAgent(session);
+
+  const transcriptions: Array<TextStreamData> = useTranscriptions({ room });
+  const chatOptions = React.useMemo(() => ({ room }), [room]);
+  const chat = useChat(chatOptions);
+
+  const transcriptionMessages: Array<
+    ReceivedUserTranscriptionMessage | ReceivedAgentTranscriptionMessage
+  > = React.useMemo(() => {
+    return transcriptions.map((transcription) => {
+      switch (transcription.participantInfo.identity) {
+        case room.localParticipant.identity:
+          return {
+            type: 'userTranscript',
+            message: transcription.text,
+
+            id: transcription.streamInfo.id,
+            timestamp: transcription.streamInfo.timestamp,
+            from: room.localParticipant,
+          };
+
+        case agent.internal.agentParticipant?.identity:
+        case agent.internal.workerParticipant?.identity:
+          return {
+            type: 'agentTranscript',
+            message: transcription.text,
+
+            id: transcription.streamInfo.id,
+            timestamp: transcription.streamInfo.timestamp,
+            from:
+              agent.internal.agentParticipant?.identity === transcription.participantInfo.identity
+                ? agent.internal.agentParticipant
+                : agent.internal.workerParticipant!,
+          };
+
+        default:
+          // FIXME: what should happen if an associated participant is not found?
+          //
+          // For now, just assume it is an agent transcription, since maybe it is from an agent
+          // which disconencted from the room or something like that.
+          return {
+            type: 'agentTranscript',
+            message: transcription.text,
+
+            id: transcription.streamInfo.id,
+            timestamp: transcription.streamInfo.timestamp,
+            from: Array.from(room.remoteParticipants.values()).find(
+              (p) => p.identity === transcription.participantInfo.identity,
+            ),
+          };
+      }
+    });
+  }, [transcriptions, room]);
+
+  const receivedMessages = React.useMemo(() => {
+    const merged: Array<ReceivedMessage> = [...transcriptionMessages, ...chat.chatMessages];
+    return merged;
+  }, [transcriptionMessages, chat.chatMessages]);
+
+  const messageFirstReceivedTimeMapRef = React.useRef(new Map<ReceivedMessage['id'], Date>());
+  const sortedReceivedMessages = React.useMemo(() => {
+    const now = new Date();
+    for (const message of receivedMessages) {
+      if (messageFirstReceivedTimeMapRef.current.has(message.id)) {
+        continue;
+      }
+
+      messageFirstReceivedTimeMapRef.current.set(message.id, now);
+    }
+
+    return receivedMessages.sort((a, b) => {
+      const aFirstReceivedAt = messageFirstReceivedTimeMapRef.current.get(a.id);
+      const bFirstReceivedAt = messageFirstReceivedTimeMapRef.current.get(b.id);
+      if (typeof aFirstReceivedAt === 'undefined' || typeof bFirstReceivedAt === 'undefined') {
+        return 0;
+      }
+
+      return aFirstReceivedAt.getTime() - bFirstReceivedAt.getTime();
+    });
+  }, [receivedMessages]);
+
+  const previouslyReceivedMessageIdsRef = React.useRef(new Set());
+  React.useEffect(() => {
+    for (const message of sortedReceivedMessages) {
+      if (previouslyReceivedMessageIdsRef.current.has(message.id)) {
+        continue;
+      }
+
+      previouslyReceivedMessageIdsRef.current.add(message.id);
+      emitter.emit(MessagesEvent.MessageReceived, message);
+    }
+  }, [sortedReceivedMessages]);
+
+  return React.useMemo(
+    () => ({
+      messages: sortedReceivedMessages,
+      send: chat.send,
+      isSending: chat.isSending,
+      internal: { emitter },
+    }),
+    [sortedReceivedMessages, chat.send, chat.isSending],
+  );
+}

package/src/hooks/useSettingsToggle.ts

@@ -0,0 +1,32 @@
+import { useLayoutContext } from '../context';
+import { mergeProps } from '../mergeProps';
+import * as React from 'react';
+
+/** @alpha */
+export interface UseSettingsToggleProps {
+  props: React.ButtonHTMLAttributes<HTMLButtonElement>;
+}
+
+/**
+ * The `useSettingsToggle` hook provides state and functions for toggling the settings menu.
+ * @remarks
+ * Depends on the `LayoutContext` to work properly.
+ * @see {@link SettingsMenu}
+ * @alpha
+ */
+export function useSettingsToggle({ props }: UseSettingsToggleProps) {
+  const { dispatch, state } = useLayoutContext().widget;
+  const className = 'lk-button lk-settings-toggle';
+
+  const mergedProps = React.useMemo(() => {
+    return mergeProps(props, {
+      className,
+      onClick: () => {
+        if (dispatch) dispatch({ msg: 'toggle_settings' });
+      },
+      'aria-pressed': state?.showSettings ? 'true' : 'false',
+    });
+  }, [props, className, dispatch, state]);
+
+  return { mergedProps };
+}

package/src/hooks/useSortedParticipants.ts

@@ -0,0 +1,20 @@
+import { sortParticipants } from '@livekit/components-core';
+import type { Participant } from 'livekit-client';
+import * as React from 'react';
+import { useSpeakingParticipants } from './useSpeakingParticipants';
+
+/**
+ * The `useSortedParticipants` hook returns the participants sorted by importance.
+ * @public
+ */
+export function useSortedParticipants(participants: Array<Participant>) {
+  const [sortedParticipants, setSortedParticipants] = React.useState(
+    sortParticipants(participants),
+  );
+  const activeSpeakers = useSpeakingParticipants();
+
+  React.useEffect(() => {
+    setSortedParticipants(sortParticipants(participants));
+  }, [activeSpeakers, participants]);
+  return sortedParticipants;
+}

package/src/hooks/useSpeakingParticipants.ts

@@ -0,0 +1,27 @@
+import { activeSpeakerObserver } from '@livekit/components-core';
+import * as React from 'react';
+import { useEnsureRoom } from '../context';
+import { useObservableState } from './internal';
+import { Room } from 'livekit-client';
+
+/** @public */
+export type UseSpeakingParticipantsOptions = {
+  room?: Room;
+};
+
+/**
+ * The `useSpeakingParticipants` hook returns only the active speakers of all participants.
+ *
+ * @example
+ * ```tsx
+ * const activeSpeakers = useSpeakingParticipants();
+ * ```
+ * @public
+ */
+export function useSpeakingParticipants(options?: UseSpeakingParticipantsOptions) {
+  const ensuredRoom = useEnsureRoom(options?.room);
+
+  const speakerObserver = React.useMemo(() => activeSpeakerObserver(ensuredRoom), [ensuredRoom]);
+  const activeSpeakers = useObservableState(speakerObserver, ensuredRoom.activeSpeakers);
+  return activeSpeakers;
+}

package/src/hooks/useStartAudio.ts

@@ -0,0 +1,50 @@
+import { setupStartAudio } from '@livekit/components-core';
+import type { Room } from 'livekit-client';
+import * as React from 'react';
+import { useEnsureRoom } from '../context';
+import { mergeProps } from '../mergeProps';
+import { useObservableState } from './internal';
+
+/** @alpha */
+export interface UseStartAudioProps {
+  room?: Room;
+  props: React.ButtonHTMLAttributes<HTMLButtonElement>;
+}
+
+/**
+ * In many browsers to start audio playback, the user must perform a user-initiated event such as clicking a button.
+ * The `useStatAudio` hook returns an object with a boolean `canPlayAudio` flag
+ * that indicates whether audio playback is allowed in the current context,
+ * as well as a `startAudio` function that can be called in a button `onClick` callback to start audio playback in the current context.
+ *
+ * @see Autoplay policy on MDN web docs for more info: {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Best_practices#autoplay_policy}
+ * @alpha
+ */
+export function useStartAudio({ room, props }: UseStartAudioProps) {
+  const roomEnsured = useEnsureRoom(room);
+  const { className, roomAudioPlaybackAllowedObservable, handleStartAudioPlayback } = React.useMemo(
+    () => setupStartAudio(),
+    [],
+  );
+  const observable = React.useMemo(
+    () => roomAudioPlaybackAllowedObservable(roomEnsured),
+    [roomEnsured, roomAudioPlaybackAllowedObservable],
+  );
+  const { canPlayAudio } = useObservableState(observable, {
+    canPlayAudio: roomEnsured.canPlaybackAudio,
+  });
+
+  const mergedProps = React.useMemo(
+    () =>
+      mergeProps(props, {
+        className,
+        onClick: () => {
+          handleStartAudioPlayback(roomEnsured);
+        },
+        style: { display: canPlayAudio ? 'none' : 'block' },
+      }),
+    [props, className, canPlayAudio, handleStartAudioPlayback, roomEnsured],
+  );
+
+  return { mergedProps, canPlayAudio };
+}

package/src/hooks/useStartVideo.ts

@@ -0,0 +1,49 @@
+import { setupStartVideo } from '@livekit/components-core';
+import type { Room } from 'livekit-client';
+import * as React from 'react';
+import { useEnsureRoom } from '../context';
+import { mergeProps } from '../mergeProps';
+import { useObservableState } from './internal';
+
+/** @alpha */
+export interface UseStartVideoProps {
+  room?: Room;
+  props: React.ButtonHTMLAttributes<HTMLButtonElement>;
+}
+
+/**
+ * In some browsers to start video playback in low power mode, the user must perform a user-initiated event such as clicking a button.
+ * The `useStartVideo` hook returns an object with a boolean `canPlayVideo` flag
+ * that indicates whether video playback is allowed in the current context,
+ * as well as a `startVideo` function that can be called in a button `onClick` callback to start video playback in the current context.
+ *
+ * @alpha
+ */
+export function useStartVideo({ room, props }: UseStartVideoProps) {
+  const roomEnsured = useEnsureRoom(room);
+  const { className, roomVideoPlaybackAllowedObservable, handleStartVideoPlayback } = React.useMemo(
+    () => setupStartVideo(),
+    [],
+  );
+  const observable = React.useMemo(
+    () => roomVideoPlaybackAllowedObservable(roomEnsured),
+    [roomEnsured, roomVideoPlaybackAllowedObservable],
+  );
+  const { canPlayVideo } = useObservableState(observable, {
+    canPlayVideo: roomEnsured.canPlaybackVideo,
+  });
+
+  const mergedProps = React.useMemo(
+    () =>
+      mergeProps(props, {
+        className,
+        onClick: () => {
+          handleStartVideoPlayback(roomEnsured);
+        },
+        style: { display: canPlayVideo ? 'none' : 'block' },
+      }),
+    [props, className, canPlayVideo, handleStartVideoPlayback, roomEnsured],
+  );
+
+  return { mergedProps, canPlayVideo };
+}

package/src/hooks/useSwipe.ts

@@ -0,0 +1,68 @@
+import * as React from 'react';
+
+/**
+ * @alpha
+ */
+export type UseSwipeOptions = {
+  minSwipeDistance?: number;
+  onLeftSwipe?: () => void;
+  onRightSwipe?: () => void;
+};
+
+/**
+ * Simple implementation to detect horizontal swipe actions.
+ * Accepts callbacks for on right and left swipes.
+ * @example
+ * ```tsx
+ *  <div
+      onTouchStart={onTouchStart}
+      onTouchMove={onTouchMove}
+      onTouchEnd={onTouchEnd}
+    >
+ * ```
+ * @alpha
+ */
+export function useSwipe(element: React.RefObject<HTMLElement>, options: UseSwipeOptions = {}) {
+  const touchStart = React.useRef<number | null>(null);
+  const touchEnd = React.useRef<number | null>(null);
+
+  // The required distance between touchStart and touchEnd to be detected as a swipe.
+  const minSwipeDistance = options.minSwipeDistance ?? 50;
+
+  const onTouchStart = (event: TouchEvent) => {
+    touchEnd.current = null; // Otherwise the swipe is fired even with usual touch events.
+    touchStart.current = event.targetTouches[0].clientX;
+  };
+
+  const onTouchMove = (event: TouchEvent) => {
+    touchEnd.current = event.targetTouches[0].clientX;
+  };
+
+  const onTouchEnd = React.useCallback(() => {
+    if (!touchStart.current || !touchEnd.current) {
+      return;
+    }
+    const distance = touchStart.current - touchEnd.current;
+    const isLeftSwipe = distance > minSwipeDistance;
+    const isRightSwipe = distance < -minSwipeDistance;
+
+    if (isLeftSwipe && options.onLeftSwipe) options.onLeftSwipe();
+    if (isRightSwipe && options.onRightSwipe) options.onRightSwipe();
+  }, [minSwipeDistance, options]);
+
+  React.useEffect(() => {
+    const elementCopy = element.current;
+    if (elementCopy) {
+      elementCopy.addEventListener('touchstart', onTouchStart, { passive: true });
+      elementCopy.addEventListener('touchmove', onTouchMove, { passive: true });
+      elementCopy.addEventListener('touchend', onTouchEnd, { passive: true });
+    }
+    return () => {
+      if (elementCopy) {
+        elementCopy.removeEventListener('touchstart', onTouchStart);
+        elementCopy.removeEventListener('touchmove', onTouchMove);
+        elementCopy.removeEventListener('touchend', onTouchEnd);
+      }
+    };
+  }, [element, onTouchEnd]);
+}

package/src/hooks/useTextStream.ts

@@ -0,0 +1,35 @@
+import * as React from 'react';
+import { ConnectionState, Room } from 'livekit-client';
+import { setupTextStream, type TextStreamData } from '@livekit/components-core';
+import { useEnsureRoom } from '../context';
+import { useConnectionState } from './useConnectionStatus';
+import { useObservableState } from './internal';
+
+/** @beta */
+export type UseTextStreamOptions = {
+  room?: Room;
+};
+
+/**
+ * @beta
+ * @param topic - the topic to listen to
+ * @returns an array of TextStreamData that holds the text, participantInfo, and streamInfo
+ * @example
+ * ```tsx
+ * const { textStreams } = useTextStream('my-topic');
+ * return <div>{textStreams.map((textStream) => textStream.text)}</div>;
+ * ```
+ */
+export function useTextStream(topic: string, options?: UseTextStreamOptions) {
+  const room = useEnsureRoom(options?.room);
+
+  const connectionState = useConnectionState(room);
+  const isDisconnected = connectionState === ConnectionState.Disconnected;
+
+  const textStreamData = React.useMemo(() => setupTextStream(room, topic), [room, topic]);
+  const textStreamObservable = isDisconnected ? undefined : textStreamData;
+
+  const textStreams = useObservableState<TextStreamData[]>(textStreamObservable, []);
+
+  return { textStreams };
+}

package/src/hooks/useToken.ts

@@ -0,0 +1,54 @@
+import { log } from '@livekit/components-core';
+import * as React from 'react';
+
+/** @public */
+export interface UserInfo {
+  identity?: string;
+  name?: string;
+  metadata?: string;
+}
+
+/** @public */
+export interface UseTokenOptions {
+  userInfo?: UserInfo;
+}
+
+/**
+ * The `useToken` hook fetches a token from the given token endpoint with the given user info.
+ *
+ * @example
+ * ```tsx
+ * const token = useToken(<token-endpoint>, roomName, { userInfo: { identity, name }});
+ * ```
+ * @public */
+export function useToken(
+  tokenEndpoint: string | undefined,
+  roomName: string,
+  options: UseTokenOptions = {},
+) {
+  const [token, setToken] = React.useState<string | undefined>(undefined);
+
+  React.useEffect(() => {
+    if (tokenEndpoint === undefined) {
+      throw Error('token endpoint needs to be defined');
+    }
+    if (options.userInfo?.identity === undefined) {
+      return;
+    }
+    const tokenFetcher = async () => {
+      log.debug('fetching token');
+      const params = new URLSearchParams({ ...options.userInfo, roomName });
+      const res = await fetch(`${tokenEndpoint}?${params.toString()}`);
+      if (!res.ok) {
+        log.error(
+          `Could not fetch token. Server responded with status ${res.status}: ${res.statusText}`,
+        );
+        return;
+      }
+      const { accessToken } = await res.json();
+      setToken(accessToken);
+    };
+    tokenFetcher();
+  }, [tokenEndpoint, roomName, JSON.stringify(options)]);
+  return token;
+}

package/src/hooks/useTrack.ts

@@ -0,0 +1,11 @@
+// import type { Participant, Track } from 'livekit-client';
+// import { useTrackRefBySourceOrName } from './useTrackRefBySourceOrName';
+// import { useEnsureParticipant } from '../context';
+
+/**
+ * TODO decide whether we want to expose this
+ */
+// function useTrack(source: Track.Source, participant?: Participant) {
+//   const p = useEnsureParticipant(participant);
+//   return useTrackRefBySourceOrName({ source, participant: p });
+// }

package/src/hooks/useTrackByName.ts

@@ -0,0 +1,15 @@
+import type { Participant } from 'livekit-client';
+import { useEnsureParticipant } from '../context';
+import { useTrackRefBySourceOrName } from './useTrackRefBySourceOrName';
+
+/**
+ * This function `useTrackByName` allows you to access a track by referencing its track name.
+ * Inside the function, it ensures that the a valid `participant` reference is available by checking
+ * for both a passed participant argument and, if not available, a valid participant context.
+ *
+ * @public
+ */
+export function useTrackByName(name: string, participant?: Participant) {
+  const p = useEnsureParticipant(participant);
+  return useTrackRefBySourceOrName({ name, participant: p });
+}

package/src/hooks/useTrackMutedIndicator.ts

@@ -0,0 +1,44 @@
+import {
+  type TrackReferenceOrPlaceholder,
+  setupTrackMutedIndicator,
+  getTrackReferenceId,
+} from '@livekit/components-core';
+import * as React from 'react';
+import { useEnsureTrackRef } from '../context';
+import { useObservableState } from './internal';
+
+interface TrackMutedIndicatorReturnType {
+  isMuted: boolean;
+  className: string;
+}
+
+/**
+ * The `useTrackMutedIndicator` hook is used to implement the `TrackMutedIndicator` component
+ * and returns the muted state of the given track.
+ *
+ * @example
+ * ```tsx
+ * const { isMuted } = useTrackMutedIndicator(trackRef);
+ * ```
+ * @public
+ */
+export function useTrackMutedIndicator(
+  trackRef?: TrackReferenceOrPlaceholder,
+): TrackMutedIndicatorReturnType {
+  const trackReference = useEnsureTrackRef(trackRef);
+
+  const { className, mediaMutedObserver } = React.useMemo(
+    () => setupTrackMutedIndicator(trackReference),
+    [getTrackReferenceId(trackReference)],
+  );
+
+  const isMuted = useObservableState(
+    mediaMutedObserver,
+    !!(
+      trackReference.publication?.isMuted ||
+      trackReference.participant.getTrackPublication(trackReference.source)?.isMuted
+    ),
+  );
+
+  return { isMuted, className };
+}

package/src/hooks/useTrackRefBySourceOrName.ts

@@ -0,0 +1,30 @@
+import type { TrackReferenceOrPlaceholder, TrackSource } from '@livekit/components-core';
+import { setupMediaTrack, getTrackByIdentifier } from '@livekit/components-core';
+import * as React from 'react';
+import { Track } from 'livekit-client';
+
+/**
+ * @internal
+ */
+export function useTrackRefBySourceOrName(
+  source: TrackSource<Track.Source>,
+): TrackReferenceOrPlaceholder {
+  const [publication, setPublication] = React.useState(getTrackByIdentifier(source));
+
+  const { trackObserver } = React.useMemo(() => {
+    return setupMediaTrack(source);
+  }, [source.participant.sid ?? source.participant.identity, source.source]);
+
+  React.useEffect(() => {
+    const subscription = trackObserver.subscribe((publication) => {
+      setPublication(publication);
+    });
+    return () => subscription?.unsubscribe();
+  }, [trackObserver]);
+
+  return {
+    participant: source.participant,
+    source: source.source ?? Track.Source.Unknown,
+    publication,
+  };
+}

package/src/hooks/useTrackSyncTime.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import { type TrackReferenceOrPlaceholder, trackSyncTimeObserver } from '@livekit/components-core';
+import { useObservableState } from './internal';
+
+/**
+ * @internal
+ * @deprecated this is an internal hook that's only used by deprecated APIs
+ */
+export function useTrackSyncTime(ref: TrackReferenceOrPlaceholder | undefined) {
+  const observable = React.useMemo(
+    () => (ref?.publication?.track ? trackSyncTimeObserver(ref?.publication.track) : undefined),
+    [ref?.publication?.track],
+  );
+  return useObservableState(observable, {
+    timestamp: Date.now(),
+    rtpTimestamp: ref?.publication?.track?.rtpTimestamp,
+  });
+}