@lumea-labs/chat-web-speech 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# @lumea-labs/chat-web-speech
+
+Tier 2 voice adapter for Web Speech API — wraps webkitSpeechRecognition behind the VoiceTranscriptionAdapter contract.
+
+## Install
+
+```bash
+npm install @lumea-labs/chat-web-speech
+```
+
+## Usage
+
+```tsx
+import { /* … */ } from "@lumea-labs/chat-web-speech";
+```
+
+See the [Lumea Agents repo](https://github.com/Lumea-Technologies/lumea-agents/tree/main/packages/chat-web-speech) for the full source and a playground example.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { UseBrowserVoiceAdapterOptions, useBrowserVoiceAdapter } from './use-browser-voice-adapter.js';
+import '@lumea-labs/chat';

package/dist/index.js

@@ -0,0 +1,6 @@
+import {
+  useBrowserVoiceAdapter
+} from "./use-browser-voice-adapter";
+export {
+  useBrowserVoiceAdapter
+};

package/dist/use-browser-voice-adapter.d.ts

@@ -0,0 +1,39 @@
+import { VoiceTranscriptionAdapter } from '@lumea-labs/chat';
+
+interface UseBrowserVoiceAdapterOptions {
+    /** BCP-47 language tag — e.g. `"en-US"`, `"it-IT"`. Default: browser default. */
+    language?: string;
+    /** Keep transcribing across multiple utterances. Default `false` —
+     *  one utterance per `start()`. */
+    continuous?: boolean;
+    /** Emit interim (in-progress) transcripts. Default `true`. */
+    interim?: boolean;
+    /** Fired when the recognition session ends — covers BOTH cases:
+     *    - the user clicked the mic button to stop (manual)
+     *    - the browser auto-ended after detecting silence (auto)
+     *  The Promise returned by `stop()` only resolves on the manual
+     *  path; subscribe via this callback to also catch auto-ends.
+     *  Receives the final transcript (may be empty). */
+    onResult?: (text: string) => void;
+    /** Trailing silence (ms) before the adapter auto-stops on its own.
+     *  When > 0, the adapter forces `continuous: true` and tracks
+     *  silence via an internal timer instead of letting the browser
+     *  auto-end on its short ~1-3s default. Useful for "wait a few
+     *  seconds before committing the transcript" UX — set e.g. 5000
+     *  to give the user breathing room between sentences.
+     *  Default `0` (use the browser's default silence behavior). */
+    silenceTimeoutMs?: number;
+    /** Hard cap (ms) on a single recording session. The adapter stops
+     *  itself after this many ms regardless of speech activity, so the
+     *  user can never accidentally leave the mic open forever. Same
+     *  emit path as a silence-timeout stop (`onResult` fires with the
+     *  accumulated transcript). Default `0` (no cap). */
+    maxDurationMs?: number;
+}
+/**
+ * Hook returning a `VoiceTranscriptionAdapter` backed by the browser
+ * Web Speech API. Drop the result into `<ChatMicButton adapter={…}>`.
+ */
+declare function useBrowserVoiceAdapter(opts?: UseBrowserVoiceAdapterOptions): VoiceTranscriptionAdapter;
+
+export { type UseBrowserVoiceAdapterOptions, useBrowserVoiceAdapter };

package/dist/use-browser-voice-adapter.js

@@ -0,0 +1,216 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+function getSpeechRecognition() {
+  if (typeof window === "undefined") return null;
+  const w = window;
+  return w.SpeechRecognition ?? w.webkitSpeechRecognition ?? null;
+}
+function useBrowserVoiceAdapter(opts = {}) {
+  const {
+    language,
+    continuous = false,
+    interim = true,
+    silenceTimeoutMs = 0,
+    maxDurationMs = 0
+  } = opts;
+  const onResultRef = useRef(opts.onResult);
+  onResultRef.current = opts.onResult;
+  const [status, setStatus] = useState("idle");
+  const [error, setError] = useState(null);
+  const [elapsedMs, setElapsedMs] = useState(0);
+  const [interimTranscript, setInterimTranscript] = useState("");
+  const [finalTranscript, setFinalTranscript] = useState("");
+  const recRef = useRef(null);
+  const finalTextRef = useRef("");
+  const startTimeRef = useRef(0);
+  const tickRef = useRef(null);
+  const stopResolverRef = useRef(null);
+  const cancelledRef = useRef(false);
+  const silenceTickRef = useRef(null);
+  const lastSpeechAtRef = useRef(0);
+  const maxDurationTimerRef = useRef(null);
+  const isSupported = typeof window !== "undefined" && !!getSpeechRecognition();
+  const startTicker = useCallback(() => {
+    if (tickRef.current !== null) return;
+    startTimeRef.current = Date.now();
+    setElapsedMs(0);
+    tickRef.current = window.setInterval(() => {
+      setElapsedMs(Date.now() - startTimeRef.current);
+    }, 100);
+  }, []);
+  const stopTicker = useCallback(() => {
+    if (tickRef.current !== null) {
+      window.clearInterval(tickRef.current);
+      tickRef.current = null;
+    }
+  }, []);
+  const stopSilenceTick = useCallback(() => {
+    if (silenceTickRef.current !== null) {
+      window.clearInterval(silenceTickRef.current);
+      silenceTickRef.current = null;
+    }
+  }, []);
+  const stopMaxDurationTimer = useCallback(() => {
+    if (maxDurationTimerRef.current !== null) {
+      window.clearTimeout(maxDurationTimerRef.current);
+      maxDurationTimerRef.current = null;
+    }
+  }, []);
+  useEffect(() => {
+    return () => {
+      stopTicker();
+      stopSilenceTick();
+      stopMaxDurationTimer();
+      try {
+        recRef.current?.abort();
+      } catch {
+      }
+    };
+  }, [stopTicker, stopSilenceTick, stopMaxDurationTimer]);
+  const start = useCallback(async () => {
+    const Ctor = getSpeechRecognition();
+    if (!Ctor) {
+      const err = new Error("Web Speech API not supported in this browser");
+      setError(err);
+      setStatus("error");
+      throw err;
+    }
+    if (status === "recording" || status === "starting") return;
+    setError(null);
+    setInterimTranscript("");
+    setFinalTranscript("");
+    finalTextRef.current = "";
+    cancelledRef.current = false;
+    setStatus("starting");
+    const rec = new Ctor();
+    if (language) rec.lang = language;
+    rec.continuous = silenceTimeoutMs > 0 ? true : continuous;
+    rec.interimResults = interim;
+    rec.onstart = () => {
+      setStatus("recording");
+      startTicker();
+      lastSpeechAtRef.current = Date.now();
+      if (silenceTimeoutMs > 0) {
+        silenceTickRef.current = window.setInterval(() => {
+          const idle = Date.now() - lastSpeechAtRef.current;
+          if (idle >= silenceTimeoutMs) {
+            stopSilenceTick();
+            try {
+              rec.stop();
+            } catch {
+            }
+          }
+        }, 400);
+      }
+      if (maxDurationMs > 0) {
+        maxDurationTimerRef.current = window.setTimeout(() => {
+          maxDurationTimerRef.current = null;
+          try {
+            rec.stop();
+          } catch {
+          }
+        }, maxDurationMs);
+      }
+    };
+    rec.onresult = (event) => {
+      let interimAcc = "";
+      let appendedFinal = false;
+      for (let i = event.resultIndex; i < event.results.length; i++) {
+        const result = event.results[i];
+        const transcript = result[0]?.transcript ?? "";
+        if (result.isFinal) {
+          finalTextRef.current = (finalTextRef.current + " " + transcript).trim();
+          appendedFinal = true;
+        } else {
+          interimAcc += transcript;
+        }
+      }
+      setInterimTranscript(interimAcc);
+      if (appendedFinal) setFinalTranscript(finalTextRef.current);
+      lastSpeechAtRef.current = Date.now();
+    };
+    rec.onerror = (e) => {
+      const err = new Error(e.error || "Speech recognition error");
+      setError(err);
+      setStatus("error");
+      stopTicker();
+      stopSilenceTick();
+      stopMaxDurationTimer();
+      stopResolverRef.current?.("");
+      stopResolverRef.current = null;
+    };
+    rec.onend = () => {
+      stopTicker();
+      stopSilenceTick();
+      stopMaxDurationTimer();
+      const final = cancelledRef.current ? "" : finalTextRef.current;
+      setInterimTranscript("");
+      setStatus("idle");
+      if (stopResolverRef.current) {
+        stopResolverRef.current(final);
+        stopResolverRef.current = null;
+      } else if (final) {
+        onResultRef.current?.(final);
+      }
+    };
+    recRef.current = rec;
+    try {
+      rec.start();
+    } catch (e) {
+      const err = e instanceof Error ? e : new Error("Failed to start mic");
+      setError(err);
+      setStatus("error");
+      stopTicker();
+      throw err;
+    }
+  }, [
+    continuous,
+    interim,
+    language,
+    silenceTimeoutMs,
+    maxDurationMs,
+    startTicker,
+    stopTicker,
+    stopSilenceTick,
+    stopMaxDurationTimer,
+    status
+  ]);
+  const stop = useCallback(async () => {
+    const rec = recRef.current;
+    if (!rec) return "";
+    setStatus("processing");
+    return new Promise((resolve) => {
+      stopResolverRef.current = resolve;
+      try {
+        rec.stop();
+      } catch {
+        resolve(finalTextRef.current);
+        stopResolverRef.current = null;
+      }
+    });
+  }, []);
+  const cancel = useCallback(() => {
+    cancelledRef.current = true;
+    finalTextRef.current = "";
+    setInterimTranscript("");
+    setFinalTranscript("");
+    try {
+      recRef.current?.abort();
+    } catch {
+    }
+  }, []);
+  return {
+    status,
+    error,
+    elapsedMs,
+    interimTranscript,
+    finalTranscript,
+    isSupported,
+    start,
+    stop,
+    cancel
+  };
+}
+export {
+  useBrowserVoiceAdapter
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@lumea-labs/chat-web-speech",
+  "version": "0.1.0",
+  "description": "Tier 2 voice adapter for Web Speech API — wraps webkitSpeechRecognition behind the VoiceTranscriptionAdapter contract.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=19",
+    "lucide-react": "*",
+    "@lumea-labs/chat": "*"
+  },
+  "license": "Apache-2.0",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "clean": "rm -rf dist"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Lumea-Technologies/lumea-agents.git",
+    "directory": "packages/chat-web-speech"
+  },
+  "homepage": "https://github.com/Lumea-Technologies/lumea-agents/tree/main/packages/chat-web-speech"
+}