agents/dist/voice/react.d.ts

A home for your AI agents

import {
  C as VoiceTransport,
  D as VoiceTurnSource,
  E as VoiceTurnOutcome,
  S as VoiceStatus,
  T as VoiceTurnMetrics,
  _ as VoiceErrorStage,
  b as VoiceRole,
  c as VoiceAudioFormat,
  g as VoiceErrorCode,
  h as VoiceError,
  l as VoiceAudioInput,
  o as TranscriptMessage,
  w as VoiceTransportCloseInfo,
  y as VoicePipelineMetrics
} from "../types-_Faxb570.js";
import {
  VoiceClientEvent,
  VoiceClientEventMap,
  VoiceClientOptions,
  VoiceConnectionDiagnostic,
  WebSocketVoiceTransport
} from "./client.js";

//#region src/voice/react.d.ts
/** Options accepted by useVoiceAgent. */
interface UseVoiceAgentOptions extends VoiceClientOptions {
  /**
   * Whether the hook should create and connect a VoiceClient.
   *
   * @default true
   */
  enabled?: boolean;
  /**
   * Called when the hook reconnects due to option changes (e.g., agent name
   * or instance name changed). Use this to show a toast or notification.
   */
  onReconnect?: () => void;
}
interface UseVoiceAgentReturn {
  status: VoiceStatus;
  transcript: TranscriptMessage[];
  /**
   * The current interim (partial) transcript from streaming STT.
   * Updates in real time as the user speaks. null when not available.
   */
  interimTranscript: string | null;
  metrics: VoicePipelineMetrics | null;
  /** Last stable terminal summary for a speech or text turn. */
  turnMetrics: VoiceTurnMetrics | null;
  audioLevel: number;
  isMuted: boolean;
  connected: boolean;
  error: string | null;
  outputDeviceError: string | null;
  startCall: () => Promise<void>;
  endCall: () => void;
  toggleMute: () => void;
  sendText: (text: string) => void;
  /** Send arbitrary JSON to the agent (app-level messages). */
  sendJSON: (data: Record<string, unknown>) => void;
  /** The last non-voice-protocol message received from the server. */
  lastCustomMessage: unknown;
}
/** Options accepted by useVoiceInput. */
interface UseVoiceInputOptions {
  /** Agent name (matches the server-side Durable Object class). */
  agent: string;
  /** Instance name for the agent. @default "default" */
  name?: string;
  /** Host to connect to. @default window.location.host */
  host?: string;
  /** RMS threshold below which audio is considered silence. @default 0.04 */
  silenceThreshold?: number;
  /** How long silence must last before sending end_of_speech (ms). @default 500 */
  silenceDurationMs?: number;
}
interface UseVoiceInputReturn {
  /** Accumulated final transcript text from all utterances. */
  transcript: string;
  /**
   * Current interim (partial) transcript from streaming STT.
   * Updates in real time as the user speaks. null when not available.
   */
  interimTranscript: string | null;
  /** Last stable terminal summary for a speech turn. */
  turnMetrics: VoiceTurnMetrics | null;
  /** Whether the mic is actively listening. */
  isListening: boolean;
  /** Current audio level (0–1) for visual feedback (e.g. waveform). */
  audioLevel: number;
  /** Whether the mic is muted. */
  isMuted: boolean;
  /** Any error message. */
  error: string | null;
  /** Start listening — requests mic permission and begins streaming audio. */
  start: () => Promise<void>;
  /** Stop listening — releases the mic. */
  stop: () => void;
  /** Toggle mute (mic stays open but audio is not sent). */
  toggleMute: () => void;
  /** Clear the accumulated transcript. */
  clear: () => void;
}
/**
 * React hook for voice-to-text input. Captures microphone audio, streams it
 * to a server-side VoiceAgent for STT, and returns the transcript as a string.
 *
 * Unlike `useVoiceAgent`, this hook is optimised for dictation — it accumulates
 * user transcripts into a single string and ignores assistant responses / TTS.
 *
 * @example
 * ```tsx
 * const { transcript, interimTranscript, isListening, start, stop } = useVoiceInput({
 *   agent: "voice-input-agent"
 * });
 *
 * <textarea value={transcript + (interimTranscript ? " " + interimTranscript : "")} />
 * <button onClick={isListening ? stop : start}>
 *   {isListening ? "Stop" : "Dictate"}
 * </button>
 * ```
 */
declare function useVoiceInput(
  options: UseVoiceInputOptions
): UseVoiceInputReturn;
/**
 * React hook that wraps VoiceClient, syncing its state into React state.
 * All audio infrastructure (mic capture, playback, silence/interrupt detection,
 * voice protocol) is handled by VoiceClient — this hook just bridges to React.
 *
 * When the connection identity changes (agent, name, or host), the hook
 * automatically disconnects the old client, creates a new one, and reconnects.
 * The `onReconnect` callback fires when this happens.
 */
declare function useVoiceAgent(
  options: UseVoiceAgentOptions
): UseVoiceAgentReturn;
//#endregion
export {
  type TranscriptMessage,
  UseVoiceAgentOptions,
  UseVoiceAgentReturn,
  UseVoiceInputOptions,
  UseVoiceInputReturn,
  type VoiceAudioFormat,
  type VoiceAudioInput,
  type VoiceClientEvent,
  type VoiceClientEventMap,
  type VoiceClientOptions,
  type VoiceConnectionDiagnostic,
  type VoiceError,
  type VoiceErrorCode,
  type VoiceErrorStage,
  type VoicePipelineMetrics,
  type VoiceRole,
  type VoiceStatus,
  type VoiceTransport,
  type VoiceTransportCloseInfo,
  type VoiceTurnMetrics,
  type VoiceTurnOutcome,
  type VoiceTurnSource,
  WebSocketVoiceTransport,
  useVoiceAgent,
  useVoiceInput
};
//# sourceMappingURL=react.d.ts.map