use-voice-control 0.1.37 → 0.1.39

package/speech/react/useReadAloud.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview React binding for `ReadAloudController`.
+ *
+ * Keeps one controller alive for the lifetime of the component, mirrors its state
+ * into React state, and stops playback on unmount so navigating away never leaves
+ * audio running.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import {
+  ReadAloudController,
+  type ReadAloudChunk,
+  type ReadAloudOptions,
+  type ReadAloudState,
+} from "../client/read-aloud";
+
+export interface UseReadAloudOptions
+  extends Omit<ReadAloudOptions, "onStateChange" | "onChunk"> {
+  /** Called as each chunk starts playing (e.g. to highlight it in the document). */
+  onChunk?: (chunk: ReadAloudChunk) => void;
+}
+
+export interface UseReadAloudReturn {
+  state: ReadAloudState;
+  /** True while loading, speaking, or paused. */
+  isActive: boolean;
+  isSpeaking: boolean;
+  isPaused: boolean;
+  /** The chunk currently being spoken, or `null` between utterances. */
+  currentChunk: ReadAloudChunk | null;
+  error: Error | null;
+  speak: (text: string) => Promise<void>;
+  pause: () => void;
+  resume: () => void;
+  stop: () => void;
+  /** Speak `text`, or stop if something is already playing. */
+  toggle: (text: string) => void;
+}
+
+export function useReadAloud(options: UseReadAloudOptions = {}): UseReadAloudReturn {
+  const [state, setState] = useState<ReadAloudState>("idle");
+  const [currentChunk, setCurrentChunk] = useState<ReadAloudChunk | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Callers routinely pass inline callbacks; hold them in a ref so the controller
+  // is never rebuilt mid-playback.
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  const controller = useMemo(
+    () =>
+      new ReadAloudController({
+        onStateChange: setState,
+        onChunk: (chunk) => {
+          setCurrentChunk(chunk);
+          optionsRef.current.onChunk?.(chunk);
+        },
+        onEnd: (reason) => {
+          setCurrentChunk(null);
+          optionsRef.current.onEnd?.(reason);
+        },
+        onError: (err) => {
+          setError(err);
+          optionsRef.current.onError?.(err);
+        },
+      }),
+    []
+  );
+
+  // Re-apply the caller's settings (voice, endpoint, …) whenever they change,
+  // preserving the callback wiring above.
+  useEffect(() => {
+    const { onChunk, onEnd, onError, ...rest } = options;
+    controller.setOptions({
+      ...rest,
+      onStateChange: setState,
+      onChunk: (chunk) => {
+        setCurrentChunk(chunk);
+        optionsRef.current.onChunk?.(chunk);
+      },
+      onEnd: (reason) => {
+        setCurrentChunk(null);
+        optionsRef.current.onEnd?.(reason);
+      },
+      onError: (err) => {
+        setError(err);
+        optionsRef.current.onError?.(err);
+      },
+    });
+  }, [
+    controller,
+    options.provider,
+    options.voice,
+    options.endpoint,
+    options.maxChunkLength,
+    options.synthesize,
+  ]);
+
+  useEffect(() => () => controller.stop(), [controller]);
+
+  const speak = useCallback(
+    async (text: string) => {
+      setError(null);
+      await controller.speak(text);
+    },
+    [controller]
+  );
+
+  const stop = useCallback(() => controller.stop(), [controller]);
+  const pause = useCallback(() => controller.pause(), [controller]);
+  const resume = useCallback(() => controller.resume(), [controller]);
+
+  const toggle = useCallback(
+    (text: string) => {
+      if (controller.isActive()) {
+        controller.stop();
+      } else {
+        void speak(text);
+      }
+    },
+    [controller, speak]
+  );
+
+  return {
+    state,
+    isActive: state !== "idle",
+    isSpeaking: state === "speaking",
+    isPaused: state === "paused",
+    currentChunk,
+    error,
+    speak,
+    pause,
+    resume,
+    stop,
+    toggle,
+  };
+}

package/speech/ui/AudioPlayer.js

@@ -1,3 +1,9 @@
+/**
+ * @fileoverview `AudioPlayer` class that queues raw Float32 audio chunks and plays them back sequentially through the Web Audio API.
+ *
+ * Supports queueing additional chunks while playback is in progress, stopping playback and
+ * clearing the queue, and closing the underlying `AudioContext`.
+ */
 const SAMPLE_RATE = 24000;
 
 export class AudioPlayer {

package/speech/ui/ui.js

@@ -1,3 +1,10 @@
+/**
+ * @fileoverview Legacy demo UI glue: renders the conversation transcript, drives the tab navigation, and wires the recording toggle button to a `Conversation` instance.
+ *
+ * Provides `displayConversation` (renders chat history into the DOM) and a
+ * `DOMContentLoaded` handler that sets up tab switching, the voice selector, the
+ * record/stop button (with a live timer), and an F8 "continue" keyboard shortcut.
+ */
 import { Conversation } from './conversation.js';
 import { initVoiceSelector } from './voice-selector.js';
 

package/speech/ui/voice-selector.js

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview `initVoiceSelector` populates the legacy demo's voice `<select>` element, grouping voices by gender and sorting each group by quality grade.
+ */
 import { VOICES } from './voices.js';
 
 export function initVoiceSelector() {

package/speech/ui/voices.js

@@ -1,3 +1,10 @@
+/**
+ * @fileoverview Kokoro voice catalog and per-voice style-vector loading/caching used by the legacy TTS demo.
+ *
+ * Exports the `VOICES` metadata map (name, language, gender, quality grade) plus
+ * `getVoiceData`, which fetches each voice's style-vector `.bin` file from the Hugging Face
+ * Hub (via the Cache API and an in-memory `VOICE_CACHE`) and returns it as a `Float32Array`.
+ */
 export const VOICES = Object.freeze({
   af_heart: {
     name: "Heart",

package/speech/utils/audio-utils.js

@@ -1,3 +1,10 @@
+/**
+ * @fileoverview Audio-buffer utility functions for resampling, gain adjustment, and WAV encoding, used by the legacy STT/TTS pipeline.
+ *
+ * Exports `resampleAudio` (via `OfflineAudioContext`), `applyAudioGain` (volume boost with
+ * clamping, used to retry failed transcriptions), and `convertAudioBufferToWav` (manual RIFF/WAV
+ * header + PCM encoding) plus its internal `writeString` helper.
+ */
 //see also: https://github.com/colmeye/js-mediarecorder-to-wav/blob/main/wave-worker.js
 
 // 16000

package/speech/utils/phonemize.js

@@ -1,3 +1,10 @@
+/**
+ * @fileoverview `phonemize` converts input text into phonemes for the Kokoro TTS pipeline, using the `phonemizer` (espeak-ng) library loaded from a CDN.
+ *
+ * Normalizes text first (quotes/punctuation, abbreviations, numbers, currency,
+ * possessives, hyphenation) via `normalize_text`, splits on punctuation to preserve it, runs
+ * each section through espeak-ng, then applies Kokoro-specific phoneme post-processing.
+ */
 import { phonemize as espeakng } from "https://cdn.jsdelivr.net/npm/phonemizer@1.2.1/dist/phonemizer.min.js";
 //import { phonemize as espeakng } from "phonemizer";
 

package/speech/utils/semantic-split.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Type declarations for the JavaScript chunker in `semantic-split.js`,
+ * so TypeScript callers under `speech/client` can import it directly.
+ */
+
+/** Split text into TTS-sized chunks along paragraph, sentence, comma, and word boundaries. */
+export function splitTextSmart(text: string, maxChunkLength?: number): string[];
+
+/** Break a single oversized sentence down along commas, then words. */
+export function splitLongSentence(sentence: string, maxLen: number): string[];

package/speech/utils/semantic-split.js

@@ -1,3 +1,10 @@
+/**
+ * @fileoverview Splits long text into TTS-sized chunks along paragraph, sentence, comma, and word boundaries so speech synthesis can process it incrementally.
+ *
+ * Exports `splitTextSmart` (primary chunker, falling back to `splitLongSentence` for
+ * oversized sentences) and `splitLongSentence`. Also retains an older, unused
+ * `splitTextSmartOld` variant that lacks the long-sentence fallback.
+ */
 export function splitTextSmart(text, maxChunkLength = 500) {
   const paragraphChunks = text.split(/\n\s*\n/);
   const finalChunks = [];

package/speech/utils/sentence-detector.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Type declarations for the JavaScript helpers in `sentence-detector.js`,
+ * so TypeScript callers under `speech/client` can import it directly.
+ */
+
+/** True when the text reads as a finished sentence (or is long enough to speak anyway). */
+export function isCompleteSentence(text: string): boolean;
+
+/** Split an accumulator + new chunk into speakable sentences plus the leftover remainder. */
+export function processStreamingText(
+  accumulator: string,
+  newContent: string
+): { sentences: string[]; remainder: string };

package/speech/utils/sentence-detector.js

@@ -1,6 +1,10 @@
 
 /**
- * Utility functions for detecting sentence boundaries in streaming text
+ * @fileoverview Utility functions for detecting sentence boundaries in streaming text so speech can be synthesized incrementally as an LLM response streams in.
+ *
+ * Exports `isCompleteSentence` (checks basic/dialog/list-item/paragraph endings plus a
+ * length-based fallback) and `processStreamingText`, which splits an accumulator + new
+ * chunk into ready-to-speak sentences and a leftover remainder.
  */
 
 // These are common sentence ending patterns