hooks.ts

Overview

The hooks.ts file provides a set of custom React hooks designed to manage key functionalities related to chat message feedback, message deletion, and speech synthesis playback within the application. These hooks encapsulate asynchronous interactions with backend services and handle UI state management, enabling components to easily integrate feedback submission, message removal, and speech playback features with clear and reusable APIs.

Specifically, it exports three hooks:

• useSendFeedback: Manages user feedback submission for a specific chat message, including modal visibility controls and loading state.

• useRemoveMessage: Handles deletion of a chat message by its ID and optionally updates the local message state.

• useSpeech: Provides speech synthesis playback capabilities using streaming responses, managing an audio player instance and playback state.

These hooks abstract complex logic such as API calls, state management, and audio streaming into simplified interfaces for React components.

Detailed Explanations

1. useSendFeedback

useSendFeedback(messageId: string): {
  loading: boolean;
  onFeedbackOk: (params: IFeedbackRequestBody) => Promise<void>;
  visible: boolean;
  hideModal: () => void;
  showModal: () => void;
}

Purpose

Facilitates submitting user feedback on a chat message identified by messageId. It manages the feedback modal's visibility and loading state while performing the asynchronous feedback submission.

Parameters

• messageId (string): The unique identifier of the message for which the feedback is sent.

Returns

An object containing:

• loading (boolean): Indicates whether the feedback submission is in progress.

• onFeedbackOk (async function): Function to submit feedback with additional parameters.

• visible (boolean): Indicates if the feedback modal is currently visible.

• hideModal (function): Function to hide the feedback modal.

• showModal (function): Function to show the feedback modal.

Usage Example

const { loading, onFeedbackOk, visible, hideModal, showModal } = useSendFeedback("msg123");

// To show the feedback modal
showModal();

// To submit feedback
await onFeedbackOk({ rating: 5, comment: "Great response!" });

// To hide the modal after submission or cancellation
hideModal();

Implementation Details

• Utilizes useSetModalState hook to manage modal visibility.

• Calls useFeedback hook to send feedback asynchronously.

• The onFeedbackOk function merges messageId with passed feedback parameters and awaits a response.

• Closes the modal if feedback submission returns a success code (0).

2. useRemoveMessage

useRemoveMessage(
  messageId: string,
  removeMessageById?: (id: string) => void
): {
  onRemoveMessage: () => Promise<void>;
  loading: boolean;
}

Purpose

Handles the deletion of a chat message by its ID and optionally allows removing the message from local state via a callback.

Parameters

• messageId (string): The ID of the message to delete.

• removeMessageById (optional function): Callback function to update local state by removing the message from UI after successful deletion.

Returns

An object containing:

• onRemoveMessage (async function): Function to trigger message deletion.

• loading (boolean): Indicates if the deletion operation is in progress.

Usage Example

const { onRemoveMessage, loading } = useRemoveMessage("msg123", (id) => {
  setMessages((prev) => prev.filter(msg => msg.id !== id));
});

// Trigger deletion
await onRemoveMessage();

Implementation Details

• Uses the useDeleteMessage hook to perform the asynchronous delete request.

• Upon success (return code 0), calls the optional removeMessageById callback to update local message state.

• Ensures onRemoveMessage is memoized with useCallback for performance.

3. useSpeech

useSpeech(content: string, audioBinary?: string): {
  ref: React.RefObject<HTMLAudioElement>;
  handleRead: () => Promise<void>;
  isPlaying: boolean;
}

Purpose

Provides speech synthesis playback functionality using OpenAI's streaming speech data. It manages an audio player instance, playback state, and supports feeding raw audio data.

Parameters

• content (string): The text content to be converted to speech and played.

• audioBinary (optional string): Hexadecimal string representation of pre-encoded audio data to feed to the player directly.

Returns

An object containing:

• ref (RefObject<HTMLAudioElement>): Reference to an audio element to attach the speech player.

• handleRead (async function): Controls playback toggling (play/pause) for the speech audio.

• isPlaying (boolean): Current playback state indicator.

Usage Example

const { ref, handleRead, isPlaying } = useSpeech("Hello world!");

// Render audio element
<audio ref={ref} />

// Toggle playback on button click
<button onClick={handleRead}>
  {isPlaying ? "Pause" : "Play"}
</button>

Implementation Details

• Initializes a SpeechPlayer instance on mount with appropriate MIME type detection for audio compatibility.

• Uses the useSpeechWithSse hook to read streaming speech data based on the input text.

• The handleRead function toggles playback state, either pausing the player or initiating speech synthesis streaming.

• When audioBinary is provided, converts the hex string to a Uint8Array and feeds it directly to the player.

• Uses React hooks (useState, useEffect, useRef, useCallback) to manage state and lifecycle.

Important Implementation Details and Algorithms

• Speech MIME Type Detection: The hook dynamically selects between 'audio/mpeg' and 'audio/mp4; codecs="mp4a.40.2"' depending on browser support via MediaSource.isTypeSupported. This ensures compatibility across browsers like Chrome and Firefox.

• Streaming Audio: The speech content is streamed using Server-Sent Events through the useSpeechWithSse hook and fed incrementally to the SpeechPlayer, enabling near real-time audio playback.

• Hex String to Uint8Array Conversion: The utility hexStringToUint8Array converts hex-encoded audio data strings into binary formats suitable for the audio player.

• Modal State Management: Feedback modal visibility is managed through a custom hook useSetModalState, simplifying UI state toggling.

Interaction with Other Parts of the System

• Hooks from Other Modules:

  • useDeleteMessage and useFeedback from chat-hooks: Provide asynchronous API calls for deleting messages and submitting feedback.

  • useSetModalState from common-hooks: Manages modal dialog states application-wide.

  • useSpeechWithSse from logic-hooks: Handles streaming speech synthesis.

• Interfaces:

  • IFeedbackRequestBody from interfaces defines the structure of feedback request payloads.

  • IRemoveMessageById interface defines the signature expected for message removal callbacks.

• Utilities:

  • hexStringToUint8Array from common-util: Used to convert audio data from string to binary.

• External Library:

  • SpeechPlayer from openai-speech-stream-player: Core audio player handling streaming data feeding and playback events.

These hooks are designed to be integrated into React components responsible for chat UI, feedback modals, and speech playback controls.

Mermaid Diagram

flowchart TD
    A[useSendFeedback] --> B[useSetModalState]
    A --> C[useFeedback]

    D[useRemoveMessage] --> E[useDeleteMessage]
    D --> F[removeMessageById?]

    G[useSpeech] --> H[useSpeechWithSse]
    G --> I[SpeechPlayer]
    G --> J[hexStringToUint8Array]

    subgraph "Hooks.ts"
        A
        D
        G
    end

Summary

The hooks.ts file streamlines complex UI behaviors related to chat message feedback, removal, and speech synthesis playback by providing well-encapsulated React hooks. They abstract API communication, audio streaming, and UI state management, making it easier for developers to integrate these capabilities consistently throughout the application. The hooks leverage a combination of internal utilities, interfaces, and external libraries to deliver responsive and user-friendly chat interactions.