@werxt/livekit-components-react 2.9.20

package/src/hooks/useTranscriptions.ts

@@ -0,0 +1,48 @@
+import * as React from 'react';
+import { useTextStream } from './useTextStream';
+import { DataTopic, ParticipantAgentAttributes } from '@livekit/components-core';
+import { Room } from 'livekit-client';
+
+/**
+ * @beta
+ */
+export interface UseTranscriptionsOptions {
+  room?: Room;
+  participantIdentities?: string[];
+  trackSids?: string[];
+}
+
+/**
+ * @beta
+ * useTranscriptions is a hook that returns the transcriptions for the given participant identities and track sids,
+ * if no options are provided, it will return all transcriptions
+ * @example
+ * ```tsx
+ * const transcriptions = useTranscriptions();
+ * return <div>{transcriptions.map((transcription) => transcription.text)}</div>;
+ * ```
+ */
+export function useTranscriptions(opts?: UseTranscriptionsOptions) {
+  const { participantIdentities, trackSids } = opts ?? {};
+  const { textStreams } = useTextStream(DataTopic.TRANSCRIPTION, { room: opts?.room });
+
+  const filteredMessages = React.useMemo(
+    () =>
+      textStreams
+        .filter((stream) =>
+          participantIdentities
+            ? participantIdentities.includes(stream.participantInfo.identity)
+            : true,
+        )
+        .filter((stream) =>
+          trackSids
+            ? trackSids.includes(
+                stream.streamInfo.attributes?.[ParticipantAgentAttributes.TranscribedTrackId] ?? '',
+              )
+            : true,
+        ),
+    [textStreams, participantIdentities, trackSids],
+  );
+
+  return filteredMessages;
+}

package/src/hooks/useVisualStableUpdate.ts

@@ -0,0 +1,63 @@
+import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
+import { log, sortTrackReferences, updatePages } from '@livekit/components-core';
+import * as React from 'react';
+
+/** @public */
+export interface UseVisualStableUpdateOptions {
+  /** Overwrites the default sort function. */
+  customSortFunction?: (
+    trackReferences: TrackReferenceOrPlaceholder[],
+  ) => TrackReferenceOrPlaceholder[];
+}
+
+/**
+ * The `useVisualStableUpdate` hook is used to prevent visually jarring jumps and shifts of elements
+ * in an array. The algorithm only starts to update when there are more items than visually fit
+ * on a page. If this is the case, it will make sure that speaking participants move to the first
+ * page and are always visible.
+ * @remarks
+ * Updating the array can occur because attendees leave or join a room, or because they mute/unmute
+ * or start speaking.
+ * The hook is used for the `GridLayout` and `CarouselLayout` components.
+ *
+ * @example
+ * ```tsx
+ * const trackRefs = useTracks();
+ * const updatedTrackRefs = useVisualStableUpdate(trackRefs, itemPerPage);
+ * ```
+ * @public
+ */
+export function useVisualStableUpdate(
+  /** `TrackReference`s to display in the grid.  */
+  trackReferences: TrackReferenceOrPlaceholder[],
+  maxItemsOnPage: number,
+  options: UseVisualStableUpdateOptions = {},
+): TrackReferenceOrPlaceholder[] {
+  const lastTrackRefs = React.useRef<TrackReferenceOrPlaceholder[]>([]);
+  const lastMaxItemsOnPage = React.useRef<number>(-1);
+  const layoutChanged = maxItemsOnPage !== lastMaxItemsOnPage.current;
+
+  const sortedTrackRefs =
+    typeof options.customSortFunction === 'function'
+      ? options.customSortFunction(trackReferences)
+      : sortTrackReferences(trackReferences);
+
+  let updatedTrackRefs: TrackReferenceOrPlaceholder[] = [...sortedTrackRefs];
+  if (layoutChanged === false) {
+    try {
+      updatedTrackRefs = updatePages(lastTrackRefs.current, sortedTrackRefs, maxItemsOnPage);
+    } catch (error) {
+      log.error('Error while running updatePages(): ', error);
+    }
+  }
+
+  // Save info for to compare against in the next update cycle.
+  if (layoutChanged) {
+    lastTrackRefs.current = sortedTrackRefs;
+  } else {
+    lastTrackRefs.current = updatedTrackRefs;
+  }
+  lastMaxItemsOnPage.current = maxItemsOnPage;
+
+  return updatedTrackRefs;
+}

package/src/hooks/useVoiceAssistant.ts

@@ -0,0 +1,109 @@
+import * as React from 'react';
+import { ConnectionState, ParticipantKind, Track } from 'livekit-client';
+import type { RemoteParticipant } from 'livekit-client';
+import {
+  ParticipantAgentAttributes,
+  type ReceivedTranscriptionSegment,
+  type TrackReference,
+} from '@livekit/components-core';
+import { useRemoteParticipants } from './useRemoteParticipants';
+import { useParticipantTracks } from './useParticipantTracks';
+import { useTrackTranscription } from './useTrackTranscription';
+import { useConnectionState } from './useConnectionStatus';
+import { useParticipantAttributes } from './useParticipantAttributes';
+import { AgentState } from './useAgent';
+
+/**
+ * @beta
+ */
+export interface VoiceAssistant {
+  /**
+   * The agent participant.
+   */
+  agent: RemoteParticipant | undefined;
+  /**
+   * The current state of the agent.
+   */
+  state: AgentState;
+  /**
+   * The microphone track published by the agent or associated avatar worker (if any).
+   */
+  audioTrack: TrackReference | undefined;
+  /**
+   * The camera track published by the agent or associated avatar worker (if any).
+   */
+  videoTrack: TrackReference | undefined;
+  /**
+   * The transcriptions of the agent's microphone track (if any).
+   */
+  agentTranscriptions: ReceivedTranscriptionSegment[];
+  /**
+   * The agent's participant attributes.
+   */
+  agentAttributes: RemoteParticipant['attributes'] | undefined;
+}
+
+const state_attribute = ParticipantAgentAttributes.AgentState;
+
+/**
+ * This hook looks for the first agent-participant in the room.
+ * @remarks This hook requires an agent running with livekit-agents \>= 0.9.0
+ * @example
+ * ```tsx
+ * const { state, audioTrack, agentTranscriptions, agentAttributes } = useVoiceAssistant();
+ * ```
+ * @beta
+ */
+export function useVoiceAssistant(): VoiceAssistant {
+  const remoteParticipants = useRemoteParticipants();
+  const agent = remoteParticipants.find(
+    (p) =>
+      p.kind === ParticipantKind.AGENT &&
+      !(ParticipantAgentAttributes.PublishOnBehalf in p.attributes),
+  );
+  const worker = remoteParticipants.find(
+    (p) =>
+      p.kind === ParticipantKind.AGENT &&
+      p.attributes[ParticipantAgentAttributes.PublishOnBehalf] === agent?.identity,
+  );
+  const agentTracks = useParticipantTracks(
+    [Track.Source.Microphone, Track.Source.Camera],
+    agent?.identity,
+  );
+  const workerTracks = useParticipantTracks(
+    [Track.Source.Microphone, Track.Source.Camera],
+    worker?.identity,
+  );
+  const audioTrack =
+    agentTracks.find((t) => t.source === Track.Source.Microphone) ??
+    workerTracks.find((t) => t.source === Track.Source.Microphone);
+  const videoTrack =
+    agentTracks.find((t) => t.source === Track.Source.Camera) ??
+    workerTracks.find((t) => t.source === Track.Source.Camera);
+  const { segments: agentTranscriptions } = useTrackTranscription(audioTrack);
+  const connectionState = useConnectionState();
+  const { attributes } = useParticipantAttributes({ participant: agent });
+
+  const state: AgentState = React.useMemo(() => {
+    if (connectionState === ConnectionState.Disconnected) {
+      return 'disconnected';
+    } else if (
+      connectionState === ConnectionState.Connecting ||
+      !agent ||
+      !attributes?.[state_attribute]
+    ) {
+      return 'connecting';
+    } else {
+      return attributes[state_attribute] as AgentState;
+    }
+  }, [attributes, agent, connectionState]);
+
+  return {
+    agent,
+    state,
+    audioTrack,
+    videoTrack,
+    agentTranscriptions,
+    agentAttributes: attributes,
+  };
+}

package/src/hooks/useWarnAboutMissingStyles.ts

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import { warnAboutMissingStyles } from '../utils';
+
+/**
+ * @internal
+ */
+export function useWarnAboutMissingStyles() {
+  React.useEffect(() => {
+    warnAboutMissingStyles();
+  }, []);
+}

package/src/index.docs.ts

@@ -0,0 +1,12 @@
+/**
+ * Used to merge the exports from the main index.ts file with the exports from the cloud/krisp/useKrispNoiseFilter.ts file for docs generation.
+ */
+
+// Regular exports
+export * from './index';
+
+// Cloud/Krisp exports
+export {
+  useKrispNoiseFilter,
+  type useKrispNoiseFilterOptions,
+} from './hooks/cloud/krisp/useKrispNoiseFilter';

package/src/index.ts

@@ -0,0 +1,32 @@
+export * from './components';
+
+export * from './hooks';
+
+export * from './prefabs';
+
+export * from './context';
+
+export * from './assets/icons';
+
+export * from './assets/images';
+
+// Re-exports from core
+export { setLogLevel, setLogExtension, isTrackReference } from '@livekit/components-core';
+export type {
+  ChatMessage,
+  ReceivedMessage,
+  ReceivedChatMessage,
+  ReceivedUserTranscriptionMessage,
+  ReceivedAgentTranscriptionMessage,
+  MessageDecoder,
+  MessageEncoder,
+  LocalUserChoices,
+  TrackReference,
+  TrackReferenceOrPlaceholder,
+  ParticipantClickEvent,
+  ParticipantIdentifier,
+  PinState,
+  WidgetState,
+  GridLayoutDefinition,
+  TextStreamData,
+} from '@livekit/components-core';

package/src/mergeProps.ts

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import clsx from 'clsx';
+
+/**
+ * Calls all functions in the order they were chained with the same arguments.
+ * @internal
+ */
+export function chain(...callbacks: any[]): (...args: any[]) => void {
+  return (...args: any[]) => {
+    for (const callback of callbacks) {
+      if (typeof callback === 'function') {
+        try {
+          callback(...args);
+        } catch (e) {
+          console.error(e);
+        }
+      }
+    }
+  };
+}
+
+interface Props {
+  [key: string]: any;
+}
+
+// taken from: https://stackoverflow.com/questions/51603250/typescript-3-parameter-list-intersection-type/51604379#51604379
+type TupleTypes<T> = { [P in keyof T]: T[P] } extends { [key: number]: infer V } ? V : never;
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void
+  ? I
+  : never;
+
+/**
+ * Merges multiple props objects together. Event handlers are chained,
+ * classNames are combined, and ids are deduplicated - different ids
+ * will trigger a side-effect and re-render components hooked up with `useId`.
+ * For all other props, the last prop object overrides all previous ones.
+ * @param args - Multiple sets of props to merge together.
+ * @internal
+ */
+export function mergeProps<T extends Props[]>(...args: T): UnionToIntersection<TupleTypes<T>> {
+  // Start with a base clone of the first argument. This is a lot faster than starting
+  // with an empty object and adding properties as we go.
+  const result: Props = { ...args[0] };
+  for (let i = 1; i < args.length; i++) {
+    const props = args[i];
+    for (const key in props) {
+      const a = result[key];
+      const b = props[key];
+
+      // Chain events
+      if (
+        typeof a === 'function' &&
+        typeof b === 'function' &&
+        // This is a lot faster than a regex.
+        key[0] === 'o' &&
+        key[1] === 'n' &&
+        key.charCodeAt(2) >= /* 'A' */ 65 &&
+        key.charCodeAt(2) <= /* 'Z' */ 90
+      ) {
+        result[key] = chain(a, b);
+
+        // Merge classnames, sometimes classNames are empty string which eval to false, so we just need to do a type check
+      } else if (
+        (key === 'className' || key === 'UNSAFE_className') &&
+        typeof a === 'string' &&
+        typeof b === 'string'
+      ) {
+        result[key] = clsx(a, b);
+      } else {
+        result[key] = b !== undefined ? b : a;
+      }
+    }
+  }
+
+  return result as UnionToIntersection<TupleTypes<T>>;
+}

package/src/prefabs/AudioConference.tsx

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import { ControlBar } from './ControlBar';
+
+import { ParticipantAudioTile } from '../components/participant/ParticipantAudioTile';
+import { LayoutContextProvider } from '../components/layout/LayoutContextProvider';
+import type { WidgetState } from '@livekit/components-core';
+import { Chat } from './Chat';
+import { TrackLoop } from '../components';
+import { useTracks } from '../hooks';
+import { useWarnAboutMissingStyles } from '../hooks/useWarnAboutMissingStyles';
+import { Track } from 'livekit-client';
+
+/** @public */
+export interface AudioConferenceProps extends React.HTMLAttributes<HTMLDivElement> {}
+
+/**
+ * This component is the default setup of a classic LiveKit audio conferencing app.
+ * It provides functionality like switching between participant grid view and focus view.
+ *
+ * @remarks
+ * The component is implemented with other LiveKit components like `FocusContextProvider`,
+ * `GridLayout`, `ControlBar`, `FocusLayoutContainer` and `FocusLayout`.
+ *
+ * @example
+ * ```tsx
+ * <LiveKitRoom>
+ *   <AudioConference />
+ * <LiveKitRoom>
+ * ```
+ * @public
+ */
+export function AudioConference({ ...props }: AudioConferenceProps) {
+  const [widgetState, setWidgetState] = React.useState<WidgetState>({
+    showChat: false,
+    unreadMessages: 0,
+  });
+
+  const audioTracks = useTracks([Track.Source.Microphone]);
+
+  useWarnAboutMissingStyles();
+
+  return (
+    <LayoutContextProvider onWidgetChange={setWidgetState}>
+      <div className="lk-audio-conference" {...props}>
+        <div className="lk-audio-conference-stage">
+          <TrackLoop tracks={audioTracks}>
+            <ParticipantAudioTile />
+          </TrackLoop>
+        </div>
+        <ControlBar
+          controls={{ microphone: true, screenShare: false, camera: false, chat: true }}
+        />
+        {widgetState.showChat && <Chat />}
+      </div>
+    </LayoutContextProvider>
+  );
+}

package/src/prefabs/Chat.tsx

@@ -0,0 +1,153 @@
+import { type ChatMessage, type ChatOptions } from '@livekit/components-core';
+import * as React from 'react';
+import { useMaybeLayoutContext } from '../context';
+import { cloneSingleChild } from '../utils';
+import type { MessageFormatter } from '../components/ChatEntry';
+import { ChatEntry } from '../components/ChatEntry';
+import { useChat } from '../hooks/useChat';
+import { ChatToggle } from '../components';
+import ChatCloseIcon from '../assets/icons/ChatCloseIcon';
+
+/** @public */
+export interface ChatProps extends React.HTMLAttributes<HTMLDivElement>, ChatOptions {
+  messageFormatter?: MessageFormatter;
+}
+
+/**
+ * The Chat component provides ready-to-use chat functionality in a LiveKit room.
+ * Messages are distributed to all participants in the room in real-time.
+ *
+ * @remarks
+ * - Only users who are in the room at the time of dispatch will receive messages
+ * - Message history is not persisted between sessions
+ * - Requires `@livekit/components-styles` to be imported for styling
+ *
+ * @example
+ * ```tsx
+ * import '@livekit/components-styles';
+ *
+ * function Room() {
+ *   return (
+ *     <LiveKitRoom data-lk-theme="default">
+ *       <Chat />
+ *     </LiveKitRoom>
+ *   );
+ * }
+ * ```
+ *
+ * For custom styling, refer to: https://docs.livekit.io/reference/components/react/concepts/style-components/
+ *
+ * @public
+ */
+export function Chat({
+  messageFormatter,
+  messageDecoder,
+  messageEncoder,
+  channelTopic,
+  ...props
+}: ChatProps) {
+  const ulRef = React.useRef<HTMLUListElement>(null);
+  const inputRef = React.useRef<HTMLInputElement>(null);
+
+  const chatOptions: ChatOptions = React.useMemo(() => {
+    return { messageDecoder, messageEncoder, channelTopic };
+  }, [messageDecoder, messageEncoder, channelTopic]);
+
+  const { chatMessages, send, isSending } = useChat(chatOptions);
+
+  const layoutContext = useMaybeLayoutContext();
+  const lastReadMsgAt = React.useRef<ChatMessage['timestamp']>(0);
+
+  async function handleSubmit(event: React.FormEvent) {
+    event.preventDefault();
+    if (inputRef.current && inputRef.current.value.trim() !== '') {
+      await send(inputRef.current.value);
+      inputRef.current.value = '';
+      inputRef.current.focus();
+    }
+  }
+
+  React.useEffect(() => {
+    if (ulRef) {
+      ulRef.current?.scrollTo({ top: ulRef.current.scrollHeight });
+    }
+  }, [ulRef, chatMessages]);
+
+  React.useEffect(() => {
+    if (!layoutContext || chatMessages.length === 0) {
+      return;
+    }
+
+    if (
+      layoutContext.widget.state?.showChat &&
+      chatMessages.length > 0 &&
+      lastReadMsgAt.current !== chatMessages[chatMessages.length - 1]?.timestamp
+    ) {
+      lastReadMsgAt.current = chatMessages[chatMessages.length - 1]?.timestamp;
+      return;
+    }
+
+    const unreadMessageCount = chatMessages.filter(
+      (msg) => !lastReadMsgAt.current || msg.timestamp > lastReadMsgAt.current,
+    ).length;
+
+    const { widget } = layoutContext;
+    if (unreadMessageCount > 0 && widget.state?.unreadMessages !== unreadMessageCount) {
+      widget.dispatch?.({ msg: 'unread_msg', count: unreadMessageCount });
+    }
+  }, [chatMessages, layoutContext?.widget]);
+
+  return (
+    <div {...props} className="lk-chat">
+      <div className="lk-chat-header">
+        Messages
+        {layoutContext && (
+          <ChatToggle className="lk-close-button">
+            <ChatCloseIcon />
+          </ChatToggle>
+        )}
+      </div>
+
+      <ul className="lk-list lk-chat-messages" ref={ulRef}>
+        {props.children
+          ? chatMessages.map((msg, idx) =>
+              cloneSingleChild(props.children, {
+                entry: msg,
+                key: msg.id ?? idx,
+                messageFormatter,
+              }),
+            )
+          : chatMessages.map((msg, idx, allMsg) => {
+              const hideName = idx >= 1 && allMsg[idx - 1].from === msg.from;
+              // If the time delta between two messages is bigger than 60s show timestamp.
+              const hideTimestamp = idx >= 1 && msg.timestamp - allMsg[idx - 1].timestamp < 60_000;
+
+              return (
+                <ChatEntry
+                  key={msg.id ?? idx}
+                  hideName={hideName}
+                  hideTimestamp={hideName === false ? false : hideTimestamp} // If we show the name always show the timestamp as well.
+                  entry={msg}
+                  messageFormatter={messageFormatter}
+                />
+              );
+            })}
+      </ul>
+      <form className="lk-chat-form" onSubmit={handleSubmit}>
+        <input
+          className="lk-form-control lk-chat-form-input"
+          disabled={isSending}
+          ref={inputRef}
+          type="text"
+          placeholder="Enter a message..."
+          onInput={(ev) => ev.stopPropagation()}
+          onKeyDown={(ev) => ev.stopPropagation()}
+          onKeyUp={(ev) => ev.stopPropagation()}
+        />
+        <button type="submit" className="lk-button lk-chat-form-button" disabled={isSending}>
+          Send
+        </button>
+      </form>
+    </div>
+  );
+}