speech-to-speech 0.1.2 → 0.1.4

package/README.md

@@ -6,6 +6,7 @@ TypeScript utilities for speech-to-text (STT) and text-to-speech (TTS) in the br
 
 - 🎤 **STT**: Browser-native speech recognition with session management
 - 🔊 **TTS**: Piper neural TTS with automatic model downloading
+- ⚡ **WASM Caching**: Automatic browser caching eliminates repeated downloads
 - 🎵 **Shared Audio Queue**: Auto-play audio queue for seamless playback
 - ✅ **Zero Config**: No manual ONNX setup required - everything is handled automatically
 - 📦 **Small**: ~135KB package size
@@ -37,7 +38,7 @@ stt.start();
 
 // Text-to-Speech with auto-play queue
 const tts = new TTSLogic({ voiceId: "en_US-hfc_female-medium" });
-await tts.initialize();
+await tts.initialize(); // WASM files cached automatically
 
 const result = await tts.synthesize("Hello world!");
 sharedAudioPlayer.addAudioIntoQueue(result.audio, result.sampleRate);
@@ -255,24 +256,41 @@ export default function SpeechComponent() {
 ## Exports
 
 ```typescript
-// Main bundle (STT + TTS)
+// Main bundle (STT + TTS + Service wrapper)
 import {
+  // Service wrapper (new in 0.1.4)
+  createSpeechService,
+  // STT
   STTLogic,
+  getCompatibilityInfo,
+  // TTS
   TTSLogic,
+  prefetchTTSModel,
+  cleanTextForTTS,
   AudioPlayer,
   createAudioPlayer,
   sharedAudioPlayer,
 } from "speech-to-speech";
 
 // STT only
-import { STTLogic, ResetSTTLogic, VADController } from "speech-to-speech/stt";
+import {
+  STTLogic,
+  ResetSTTLogic,
+  VADController,
+  getCompatibilityInfo,      // new in 0.1.4
+} from "speech-to-speech/stt";
 
 // TTS only
 import {
   TTSLogic,
+  prefetchTTSModel,          // new in 0.1.4
+  cleanTextForTTS,           // new in 0.1.4
   AudioPlayer,
   createAudioPlayer,
   sharedAudioPlayer,
+  ensureWasmCached,
+  isWasmCached,
+  clearWasmCache,
 } from "speech-to-speech/tts";
 ```
 
@@ -323,7 +341,8 @@ Piper TTS synthesizer. Voice models download automatically on first use.
 ```typescript
 const tts = new TTSLogic({
   voiceId: "en_US-hfc_female-medium", // Piper voice ID
-  warmUp: true, // Pre-warm the model (default: true)
+  warmUp: true,                        // Pre-warm the model (default: true)
+  enableWasmCache: true,               // Cache WASM assets (default: true)
 });
 await tts.initialize();
 
@@ -341,6 +360,51 @@ await tts.synthesizeAndAddToQueue("Hello world!");
 await tts.dispose();
 ```
 
+#### WASM Caching (New in 0.1.3)
+
+The library automatically caches `piper_phonemize.data` (~9MB) and `piper_phonemize.wasm` in the browser Cache API. This eliminates repeated network downloads on every synthesis call.
+
+**Zero-config (recommended):**
+```typescript
+const tts = new TTSLogic({ voiceId: "en_US-hfc_female-medium" });
+await tts.initialize();
+// WASM files cached automatically after first download
+```
+
+**Self-hosted WASM files:**
+```typescript
+const tts = new TTSLogic({
+  voiceId: "en_US-hfc_female-medium",
+  wasmPaths: {
+    piperData: "/piper-wasm/piper_phonemize.data",
+    piperWasm: "/piper-wasm/piper_phonemize.wasm",
+    onnxWasm: "/ort/ort-wasm-simd.wasm", // optional
+  },
+});
+```
+
+**Disable caching:**
+```typescript
+const tts = new TTSLogic({
+  voiceId: "en_US-hfc_female-medium",
+  enableWasmCache: false, // Uses CDN URLs directly
+});
+```
+
+**Utility functions:**
+```typescript
+import { ensureWasmCached, isWasmCached, clearWasmCache } from "speech-to-speech/tts";
+
+// Prefetch WASM assets before initialization
+await ensureWasmCached(); // Returns { piperData: blob:..., piperWasm: blob:... }
+
+// Check if cached
+const cached = await isWasmCached(); // true/false
+
+// Clear cache
+await clearWasmCache();
+```
+
 ### Audio Playback
 
 #### `sharedAudioPlayer` (Recommended)
@@ -569,9 +633,137 @@ function stop() {
 }
 ```
 
+## Unified Speech Service
+
+`createSpeechService()` wires STT and TTS together so you need fewer imports and no manual callback plumbing.
+
+```ts
+import { createSpeechService } from "speech-to-speech";
+
+const service = createSpeechService();
+
+// 1. Set up STT
+service.initializeSTT({
+  onTranscript: (text) => console.log("Final:", text),
+  onInterimTranscript: (text) => setLiveCaption(text), // real-time display
+  onWordsUpdate: (words) => console.log("Words so far:", words),
+  onStatusChange: (type, data) => {
+    if (type === "speaking") setUserSpeaking(data as boolean);
+  },
+});
+
+// 2. Set up TTS (awaitable)
+await service.initializeTTS({ voiceId: "en_US-hfc_female-medium" });
+
+// 3. Start session
+service.startListening();
+await service.speak("Hello, how can I help you?");
+
+// 4. End session
+const transcript = service.stopListening();
+service.stopSpeaking();
+```
+
+---
+
+## Interim Transcript Streaming
+
+Get real-time partial results while the user is still speaking. Pass `onInterimTranscript` directly to `initializeSTT()`:
+
+```ts
+import { createSpeechService } from "speech-to-speech";
+
+const service = createSpeechService();
+
+service.initializeSTT({
+  onTranscript: (finalText) => console.log("Final:", finalText),
+  onInterimTranscript: (partialText) => {
+    // Called on every interim result — great for live captions
+    liveCaption.textContent = partialText;
+  },
+});
+
+await service.initializeTTS({ voiceId: "en_US-hfc_female-medium" });
+service.startListening();
+```
+
+---
+
+## TTS Warmup
+
+Call `prefetchTTSModel()` early in your app boot (e.g. after page load) so the first `speak()` call has no cold-start delay:
+
+```ts
+import { prefetchTTSModel } from "speech-to-speech";
+
+// Fire-and-forget — safe to call before the user interacts
+prefetchTTSModel("en_US-hfc_female-medium");
+
+// Later, when the user actually triggers speech:
+const tts = new TTSLogic({ voiceId: "en_US-hfc_female-medium" });
+await tts.initialize(); // instant — model already cached
+```
+
+---
+
+## Browser Compatibility Check
+
+Gate your UI before attempting to start STT or TTS:
+
+```ts
+import { getCompatibilityInfo } from "speech-to-speech";
+
+const { stt, tts, browser } = getCompatibilityInfo();
+
+if (!stt) {
+  showBanner(`Speech input is not supported in ${browser}. Please use Chrome or Edge.`);
+}
+if (!tts) {
+  showBanner("Text-to-speech is not supported in this browser.");
+}
+```
+
+---
+
+## Text Cleanup for TTS
+
+Strip HTML, Markdown, and emoji from LLM responses before passing them to synthesis:
+
+```ts
+import { cleanTextForTTS } from "speech-to-speech";
+
+const raw = "**Hello** <b>world</b>! Here's a [link](https://example.com) 🎉";
+const spoken = cleanTextForTTS(raw);
+// → "Hello world Here's a link"
+
+// Or opt-out of individual steps:
+const spoken2 = cleanTextForTTS(raw, { removeEmojis: false });
+// → "Hello world Here's a link 🎉"
+```
+
+---
+
+## Audio Player Status Callbacks
+
+React to playback state changes without polling:
+
+```ts
+import { sharedAudioPlayer } from "speech-to-speech";
+
+sharedAudioPlayer.setStatusCallback((status) => {
+  console.log("[TTS]", status); // e.g. "Playing audio chunk 1"
+});
+
+sharedAudioPlayer.setPlayingChangeCallback((isPlaying) => {
+  setTTSIndicator(isPlaying); // show/hide a speaking indicator in UI
+});
+```
+
+---
+
 ## Available Piper Voices
 
-Voice models are downloaded automatically from CDN on first use (~20-80MB per voice).
+Voice models are downloaded automatically from CDN on first use (~20-80MB per voice). WASM files (~9MB) are cached automatically and reused across all voices.
 
 | Voice ID                  | Language     | Description                    |
 | ------------------------- | ------------ | ------------------------------ |
@@ -602,7 +794,8 @@ See [Piper Voices](https://rhasspy.github.io/piper-samples/) for the complete li
 | Issue                | Solution                                                                                |
 | -------------------- | --------------------------------------------------------------------------------------- |
 | "Voice not found"    | Check voice ID spelling. Use `en_US-hfc_female-medium` for testing.                     |
-| Slow first synthesis | Normal - voice model (~20MB) downloads on first use. Subsequent calls use cached model. |
+| Slow first synthesis | Normal - voice model (~20MB) and WASM files (~9MB) download on first use. Subsequent calls use cached assets. |
+| Repeated WASM downloads | Ensure `enableWasmCache: true` (default). Check browser Cache API support. |
 | No audio output      | Ensure browser supports Web Audio API. Check volume and audio permissions.              |
 | CORS errors          | Ensure Vite config has proper COOP/COEP headers (see above).                            |
 
@@ -647,6 +840,25 @@ npm run clean   # Remove dist/
 - **[Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API)** - Browser speech recognition
 - **[Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)** - Audio processing
 
+## Changelog
+
+### v0.1.4
+
+- **`createSpeechService()`** — Unified service wrapper that wires STT + TTS together with a single ergonomic API. Supports `initializeSTT`, `initializeTTS`, `startListening`, `stopListening`, `speak`, `stopSpeaking`, and `getCompatibilityInfo`.
+- **`onInterimTranscript`** — New option in `STTLogic` (and `createSpeechService().initializeSTT()`) to receive real-time partial transcript updates while the user is still speaking.
+- **`prefetchTTSModel(voiceId)`** — Pre-warm a Piper voice early in app boot to eliminate cold-start latency on the first `speak()` call.
+- **`getCompatibilityInfo()`** — Returns `{ stt, tts, browser }` for browser feature detection and UI gating.
+- **`cleanTextForTTS(text, options?)`** — Strips HTML, Markdown, and emoji from text before synthesis. Options: `stripHtml`, `stripMarkdown`, `removeEmojis` (all default `true`).
+
+### v0.1.3
+
+- Automatic WASM caching via the browser Cache API — `piper_phonemize.data` (~9MB) and `piper_phonemize.wasm` are fetched once and reused across sessions.
+- `ensureWasmCached`, `isWasmCached`, `clearWasmCache` utility functions.
+- `enableWasmCache` and `wasmPaths` options on `TTSLogic` for self-hosted WASM.
+- Speech-aware audio player — queue automatically pauses while the user is speaking.
+
+---
+
 ## License
 
 MIT

package/dist/index-D3jSI59z.d.cts

@@ -0,0 +1,266 @@
+import { F as FillerManager } from './filler-manager-hZwzWKVC.cjs';
+
+/**
+ * stt-tts-lib - Speech-to-Text and Text-to-Speech Library
+ * Copyright (C) 2026 Navgurukul
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+type ResetReason = "silence" | "utterance-complete" | "manual";
+interface ResetStats {
+    utteranceStartedAt: number;
+    lastActivityAt: number;
+    partialTranscript: string;
+}
+interface ResetSTTOptions$1 {
+    /** Maximum silence (ms) allowed before forcing a reset. */
+    maxSilenceMs?: number;
+    /** Maximum utterance length (ms) before rotating to a fresh buffer. */
+    maxUtteranceMs?: number;
+    /** Optional reset hook for logging/analytics. */
+    onReset?: (reason: ResetReason, stats: ResetStats) => void;
+    /**
+     * Supply a clock for deterministic tests; defaults to Date.now.
+     * Using a function keeps the class platform-neutral.
+     */
+    now?: () => number;
+}
+/**
+ * Tracks speech activity and decides when to reset an STT pipeline so tokens and streams do not grow unbounded.
+ */
+declare class ResetSTTLogic$1 {
+    private readonly maxSilenceMs;
+    private readonly maxUtteranceMs;
+    private readonly onReset?;
+    private readonly now;
+    private utteranceStartedAt;
+    private lastActivityAt;
+    private partialTranscript;
+    constructor(options?: ResetSTTOptions$1);
+    recordSpeechActivity(timestamp?: number): void;
+    updatePartialTranscript(partial: string, timestamp?: number): void;
+    shouldReset(timestamp?: number): ResetReason | null;
+    maybeReset(timestamp?: number): ResetReason | null;
+    forceReset(reason?: ResetReason, timestamp?: number): void;
+    private reset;
+}
+
+/**
+ * stt-tts-lib - Speech-to-Text and Text-to-Speech Library
+ * Copyright (C) 2026 Navgurukul
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+type VADControllerOptions = {
+    bufferSize?: number;
+    minSpeechMs?: number;
+    minSilenceMs?: number;
+    energyThreshold?: number;
+    dynamicThresholdFactor?: number;
+    noiseFloorSmoothing?: number;
+    noiseFloorDecay?: number;
+    maxAmplitude?: number;
+};
+declare class VADController {
+    private vad;
+    private voiceStartListeners;
+    private voiceStopListeners;
+    private running;
+    private options?;
+    constructor(options?: VADControllerOptions);
+    start(): Promise<void>;
+    stop(): void;
+    destroy(): void;
+    isActive(): boolean;
+    onVoiceStart(listener: () => void): () => void;
+    onVoiceStop(listener: () => void): () => void;
+    private emitVoiceStart;
+    private emitVoiceStop;
+}
+
+/**
+ * stt-tts-lib - Speech-to-Text and Text-to-Speech Library
+ * Copyright (C) 2026 Navgurukul
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+type WordUpdateCallback = (words: string[]) => void;
+type MicTimeUpdateCallback = (ms: number) => void;
+type RestartMetricsCallback = (count: number, lastDuration: number | null) => void;
+type VadCallbacks = {
+    onSpeechStart?: () => void;
+    onSpeechEnd?: () => void;
+};
+type LogCallback = (message: string, type?: "info" | "error" | "warning") => void;
+type TranscriptCallback = (transcript: string) => void;
+interface ResetSTTOptions {
+    sessionDurationMs?: number;
+    interimSaveIntervalMs?: number;
+    preserveTranscriptOnStart?: boolean;
+    /** Enable short filler (default: false) */
+    enableShortFiller?: boolean;
+    /** Enable long filler (default: false) */
+    enableLongFiller?: boolean;
+    /** Delay before short filler in ms (default: 5000) */
+    shortFillerDelayMs?: number;
+    /** Delay before long filler in ms (default: 10000) */
+    longFillerDelayMs?: number;
+    /** Fallback short filler if LLM fails */
+    shortFillerFallback?: string;
+    /** Fallback long filler if LLM fails */
+    longFillerFallback?: string;
+    /** Callback when filler is generated */
+    onFillerGenerated?: (type: "short" | "long", text: string) => void;
+    /** LLM API URL (required for dynamic filler generation) */
+    llmApiUrl?: string;
+    /** LLM API Key */
+    llmApiKey?: string;
+    /** LLM Model name (default: "deepseek-chat") */
+    llmModel?: string;
+    /** LLM request timeout in ms (default: 3000) */
+    llmTimeoutMs?: number;
+    /** Language hint for LLM (e.g., "English", "Hindi") */
+    languageHint?: string;
+    /**
+     * Called on every interim (non-final) recognition result with the current
+     * partial transcript text. Useful for real‑time UI updates.
+     * Does not affect the final transcript or setWordsUpdateCallback.
+     */
+    onInterimTranscript?: (text: string) => void;
+}
+type STTLogicOptions = ResetSTTOptions;
+declare class ResetSTTLogic {
+    private recognition;
+    private isListening;
+    private fullTranscript;
+    private heardWords;
+    private onLog;
+    private onTranscript;
+    private onWordsUpdate;
+    private onMicTimeUpdate;
+    private onRestartMetrics;
+    private options;
+    private micOnTime;
+    private sessionDuration;
+    private lastTickTime;
+    private micTimeInterval;
+    private restartCount;
+    private isRestarting;
+    private isRecognitionRunning;
+    private lastInterimTranscript;
+    private onInterimTranscriptCallback?;
+    private lastInterimSaveTime;
+    private interimSaveInterval;
+    private lastInterimResultTime;
+    private lastSavedLength;
+    private transcriptBeforeRestart;
+    private sessionStartTranscript;
+    private resultHandler?;
+    private errorHandler?;
+    private endHandler?;
+    private startHandler?;
+    private sessionId;
+    private awaitingRestartFirstResultId;
+    private lastWasFinal;
+    private restartMetrics;
+    private isAutoRestarting;
+    private onUserSpeechStart?;
+    private onUserSpeechEnd?;
+    private fillerManager;
+    constructor(onLog: LogCallback, onTranscript: TranscriptCallback, options?: ResetSTTOptions);
+    setWordsUpdateCallback(callback: WordUpdateCallback): void;
+    setMicTimeUpdateCallback(callback: MicTimeUpdateCallback): void;
+    setRestartMetricsCallback(callback: RestartMetricsCallback): void;
+    setVadCallbacks(onSpeechStart?: () => void, onSpeechEnd?: () => void): void;
+    getSessionDurationMs(): number;
+    isInAutoRestart(): boolean;
+    getFullTranscript(): string;
+    clearTranscript(): void;
+    private setupRecognition;
+    private waitForEventOnce;
+    private startMicTimer;
+    private stopMicTimer;
+    private saveInterimToFinal;
+    private getSuffixToAppend;
+    private collapseRepeats;
+    private performRestart;
+    start(): void;
+    stop(): void;
+    destroy(): void;
+    /**
+     * Get the filler manager instance (if enabled)
+     */
+    getFillerManager(): FillerManager | null;
+    /**
+     * Set a custom synthesizer for filler audio generation.
+     * Optional - internal TTS is used by default.
+     */
+    setFillerSynthesizer(synthesize: (text: string) => Promise<{
+        audio: Float32Array;
+        sampleRate: number;
+    }>): void;
+    /**
+     * Get the generated short filler text (null if not generated yet)
+     */
+    getShortFiller(): string | null;
+    /**
+     * Get the generated long filler text (null if not generated yet)
+     */
+    getLongFiller(): string | null;
+}
+interface CompatibilityInfo {
+    /** Whether the Web Speech Recognition API is available in this browser */
+    stt: boolean;
+    /** Whether Piper TTS is supported (Web Audio API present) */
+    tts: boolean;
+    /** Detected browser label */
+    browser: "Chrome" | "Edge" | "Firefox" | "Safari" | "unknown";
+}
+/**
+ * Returns a snapshot of browser feature support relevant to this library.
+ * Useful for gating UI elements or showing user-friendly warnings before
+ * attempting to start STT or TTS.
+ *
+ * @example
+ * const { stt, browser } = getCompatibilityInfo();
+ * if (!stt) alert(`Speech input is not supported in ${browser}.`);
+ */
+declare function getCompatibilityInfo(): CompatibilityInfo;
+declare class STTLogic extends ResetSTTLogic {
+}
+
+export { type CompatibilityInfo as C, type MicTimeUpdateCallback as M, type ResetSTTOptions as R, STTLogic as S, VADController as V, type WordUpdateCallback as W, ResetSTTLogic$1 as a, type ResetReason as b, type ResetSTTOptions$1 as c, type ResetStats as d, type VADControllerOptions as e, type STTLogicOptions as f, type RestartMetricsCallback as g, type VadCallbacks as h, getCompatibilityInfo as i };