@djangocfg/ui-tools 2.1.381 → 2.1.383

package/src/tools/SpeechRecognition/core/engine/websocket.ts

@@ -0,0 +1,211 @@
+/**
+ * WebSocket engine — pushes recorded audio frames over a persistent socket
+ * and parses server responses through a host-supplied `parseMessage`
+ * callback. Works with Deepgram / AssemblyAI realtime endpoints or any
+ * custom gateway that speaks JSON or binary frames.
+ *
+ * Reconnect: simple exponential backoff capped at 5 s; the engine emits
+ * `state: 'connecting'` between attempts so UIs can show "reconnecting…".
+ */
+
+import { newSegmentId } from '../ids';
+import { sttLogger } from '../logger';
+import { createEngineBus } from './index';
+import { startMicCapture, type MicCaptureHandle } from './mediarecorder';
+import type {
+  EngineStartOptions,
+  RecognitionEngine,
+  RecognitionError,
+  Unsub,
+} from '../../types';
+
+export type WsParsedEvent =
+  | { kind: 'partial'; text: string; segmentId?: string; confidence?: number }
+  | { kind: 'final'; text: string; segmentId?: string; confidence?: number }
+  | { kind: 'error'; error: RecognitionError }
+  | { kind: 'ignore' };
+
+export interface WebSocketEngineOptions {
+  url: string | ((language: string) => Promise<string> | string);
+  protocols?: string[];
+  /** Chunk emission interval, ms. Default 250 for realtime feel. */
+  chunkMs?: number;
+  mime?: string;
+  /** Parse one frame (string or binary) into our normalised event shape. */
+  parseMessage: (data: string | ArrayBuffer) => WsParsedEvent;
+  /** Stable engine id for telemetry / UI badge. Default 'websocket'. */
+  id?: string;
+  /** Max reconnect attempts before giving up. Default 5. */
+  maxReconnect?: number;
+}
+
+const MIN_BACKOFF = 250;
+const MAX_BACKOFF = 5000;
+
+export function createWebSocketEngine(
+  opts: WebSocketEngineOptions,
+): RecognitionEngine {
+  const bus = createEngineBus();
+  let socket: WebSocket | null = null;
+  let capture: MicCaptureHandle | null = null;
+  let currentSegmentId: string | null = null;
+  let stopping = false;
+  let attempts = 0;
+
+  function emitParsed(parsed: WsParsedEvent): void {
+    switch (parsed.kind) {
+      case 'partial': {
+        const id = parsed.segmentId ?? currentSegmentId ?? newSegmentId();
+        currentSegmentId = id;
+        bus.emit('partial', parsed.text, id);
+        return;
+      }
+      case 'final': {
+        const id = parsed.segmentId ?? currentSegmentId ?? newSegmentId();
+        bus.emit('final', parsed.text, id, parsed.confidence);
+        currentSegmentId = null;
+        return;
+      }
+      case 'error':
+        bus.emit('error', parsed.error);
+        return;
+      case 'ignore':
+      default:
+        return;
+    }
+  }
+
+  async function openSocket(language: string): Promise<WebSocket> {
+    const url =
+      typeof opts.url === 'function' ? await opts.url(language) : opts.url;
+    const ws = new WebSocket(url, opts.protocols);
+    ws.binaryType = 'arraybuffer';
+    return ws;
+  }
+
+  async function connect(start: EngineStartOptions): Promise<void> {
+    if (stopping) return;
+    bus.emit('state', 'connecting');
+    let ws: WebSocket;
+    try {
+      ws = await openSocket(start.language);
+    } catch (cause) {
+      bus.emit('error', {
+        code: 'network',
+        message: 'Failed to open STT socket.',
+        cause,
+      });
+      return;
+    }
+    socket = ws;
+
+    ws.onopen = () => {
+      attempts = 0;
+      bus.emit('state', 'listening');
+    };
+    ws.onmessage = (e) => {
+      try {
+        const parsed = opts.parseMessage(e.data as string | ArrayBuffer);
+        emitParsed(parsed);
+      } catch (cause) {
+        sttLogger.warn('[ws] parseMessage threw', cause);
+      }
+    };
+    ws.onerror = () => {
+      bus.emit('error', { code: 'network', message: 'STT socket error.' });
+    };
+    ws.onclose = () => {
+      socket = null;
+      if (stopping) {
+        bus.emit('state', 'closed');
+        return;
+      }
+      attempts += 1;
+      const max = opts.maxReconnect ?? 5;
+      if (attempts > max) {
+        bus.emit('error', {
+          code: 'network',
+          message: `STT socket closed; gave up after ${max} attempts.`,
+        });
+        bus.emit('state', 'closed');
+        return;
+      }
+      const delay = Math.min(MIN_BACKOFF * 2 ** (attempts - 1), MAX_BACKOFF);
+      setTimeout(() => {
+        void connect(start);
+      }, delay);
+    };
+  }
+
+  return {
+    id: opts.id ?? 'websocket',
+    isSupported:
+      typeof WebSocket !== 'undefined' &&
+      typeof navigator !== 'undefined' &&
+      !!navigator.mediaDevices?.getUserMedia &&
+      typeof MediaRecorder !== 'undefined',
+    on(event, cb): Unsub {
+      return bus.on(event, cb);
+    },
+    async start(start: EngineStartOptions): Promise<void> {
+      if (capture) return;
+      stopping = false;
+      attempts = 0;
+      try {
+        capture = await startMicCapture({
+          deviceId: start.deviceId,
+          mime: opts.mime,
+          chunkMs: opts.chunkMs ?? 250,
+          onChunk: (chunk) => {
+            if (socket?.readyState === WebSocket.OPEN) {
+              chunk
+                .arrayBuffer()
+                .then((buf) => socket?.send(buf))
+                .catch((cause) => sttLogger.warn('[ws] send failed', cause));
+            }
+          },
+          onError: (err) => bus.emit('error', err),
+        });
+      } catch (cause) {
+        const err = cause as RecognitionError;
+        bus.emit('error', err);
+        bus.emit('state', 'error');
+        throw err;
+      }
+      await connect(start);
+      start.signal?.addEventListener('abort', () => {
+        void this.stop();
+      });
+    },
+    async stop(): Promise<void> {
+      stopping = true;
+      bus.emit('state', 'closing');
+      try {
+        socket?.close(1000, 'client-stop');
+      } catch {
+        // ignore
+      }
+      socket = null;
+      await capture?.stop();
+      capture = null;
+      currentSegmentId = null;
+      bus.emit('state', 'closed');
+    },
+    abort(): void {
+      stopping = true;
+      try {
+        socket?.close(4000, 'client-abort');
+      } catch {
+        // ignore
+      }
+      socket = null;
+      capture?.stop().catch(() => undefined);
+      capture = null;
+      currentSegmentId = null;
+      bus.emit('state', 'closed');
+    },
+    getStream(): MediaStream | null {
+      return capture?.stream ?? null;
+    },
+  };
+}

package/src/tools/SpeechRecognition/core/engine/webspeech.ts

@@ -0,0 +1,188 @@
+/**
+ * Default engine — wraps the browser's `SpeechRecognition` API.
+ *
+ * Lives behind the same `RecognitionEngine` contract every other engine
+ * implements. When the browser doesn't expose `SpeechRecognition`
+ * (Firefox, some mobile WebViews) `isSupported` is `false` and `start()`
+ * throws an `unsupported` error.
+ */
+
+import { newSegmentId } from '../ids';
+import { sttLogger } from '../logger';
+import { createEngineBus } from './index';
+import type {
+  EngineStartOptions,
+  RecognitionEngine,
+  RecognitionError,
+  RecognitionErrorCode,
+  Unsub,
+} from '../../types';
+
+// Minimal subset of the Web Speech API we actually rely on. Browsers
+// expose either `SpeechRecognition` (Edge / Safari new) or the older
+// `webkitSpeechRecognition` (Chrome). Both share the same shape.
+interface BrowserSpeechRecognition extends EventTarget {
+  lang: string;
+  interimResults: boolean;
+  continuous: boolean;
+  maxAlternatives: number;
+  start(): void;
+  stop(): void;
+  abort(): void;
+  onresult: ((e: BrowserSpeechRecognitionEvent) => void) | null;
+  onerror: ((e: BrowserSpeechRecognitionError) => void) | null;
+  onstart: (() => void) | null;
+  onend: (() => void) | null;
+}
+
+interface BrowserSpeechRecognitionResult {
+  isFinal: boolean;
+  0: { transcript: string; confidence: number };
+}
+
+interface BrowserSpeechRecognitionEvent extends Event {
+  resultIndex: number;
+  results: ArrayLike<BrowserSpeechRecognitionResult>;
+}
+
+interface BrowserSpeechRecognitionError extends Event {
+  error: string;
+  message?: string;
+}
+
+type Ctor = new () => BrowserSpeechRecognition;
+
+function resolveCtor(): Ctor | null {
+  if (typeof window === 'undefined') return null;
+  const w = window as unknown as {
+    SpeechRecognition?: Ctor;
+    webkitSpeechRecognition?: Ctor;
+  };
+  return w.SpeechRecognition ?? w.webkitSpeechRecognition ?? null;
+}
+
+const ERROR_MAP: Record<string, RecognitionErrorCode> = {
+  'no-speech': 'no-speech',
+  aborted: 'aborted',
+  'audio-capture': 'no-microphone',
+  network: 'network',
+  'not-allowed': 'permission-denied',
+  'service-not-allowed': 'permission-denied',
+  'bad-grammar': 'engine',
+  'language-not-supported': 'language',
+};
+
+export interface WebSpeechEngineOptions {
+  /** Whether the underlying recognition should be continuous. Default true. */
+  continuous?: boolean;
+  /** Max alternatives the engine should request. Default 1. */
+  maxAlternatives?: number;
+}
+
+export function createWebSpeechEngine(
+  opts: WebSpeechEngineOptions = {},
+): RecognitionEngine {
+  const Ctor = resolveCtor();
+  const bus = createEngineBus();
+  let instance: BrowserSpeechRecognition | null = null;
+  let currentSegmentId: string | null = null;
+
+  function teardown(): void {
+    if (!instance) return;
+    instance.onresult = null;
+    instance.onerror = null;
+    instance.onstart = null;
+    instance.onend = null;
+    instance = null;
+    currentSegmentId = null;
+  }
+
+  return {
+    id: 'webspeech',
+    isSupported: Ctor !== null,
+    on(event, cb): Unsub {
+      return bus.on(event, cb);
+    },
+    async start(start: EngineStartOptions): Promise<void> {
+      if (!Ctor) {
+        const err: RecognitionError = {
+          code: 'unsupported',
+          message: 'Web Speech API is not available in this browser.',
+        };
+        bus.emit('error', err);
+        throw err;
+      }
+      if (instance) {
+        sttLogger.debug('[webspeech] start() called while running — ignoring');
+        return;
+      }
+
+      bus.emit('state', 'connecting');
+
+      const rec = new Ctor();
+      rec.lang = start.language;
+      rec.interimResults = start.interim;
+      rec.continuous = opts.continuous ?? true;
+      rec.maxAlternatives = opts.maxAlternatives ?? 1;
+
+      rec.onstart = () => {
+        bus.emit('state', 'listening');
+      };
+      rec.onend = () => {
+        bus.emit('state', 'closed');
+        teardown();
+      };
+      rec.onerror = (e) => {
+        const code = ERROR_MAP[e.error] ?? 'engine';
+        const err: RecognitionError = {
+          code,
+          message: e.message || `Web Speech error: ${e.error}`,
+        };
+        bus.emit('error', err);
+      };
+      rec.onresult = (e) => {
+        for (let i = e.resultIndex; i < e.results.length; i += 1) {
+          const res = e.results[i];
+          const alt = res[0];
+          const text = alt.transcript;
+          if (!currentSegmentId) currentSegmentId = newSegmentId();
+          if (res.isFinal) {
+            bus.emit('final', text, currentSegmentId, alt.confidence);
+            currentSegmentId = null;
+          } else {
+            bus.emit('partial', text, currentSegmentId);
+          }
+        }
+      };
+
+      if (start.signal) {
+        start.signal.addEventListener('abort', () => {
+          rec.abort();
+        });
+      }
+
+      instance = rec;
+      try {
+        rec.start();
+      } catch (cause) {
+        const err: RecognitionError = {
+          code: 'engine',
+          message: 'Failed to start Web Speech recognition.',
+          cause,
+        };
+        bus.emit('error', err);
+        teardown();
+        throw err;
+      }
+    },
+    async stop(): Promise<void> {
+      if (!instance) return;
+      bus.emit('state', 'closing');
+      instance.stop();
+    },
+    abort(): void {
+      if (!instance) return;
+      instance.abort();
+    },
+  };
+}

package/src/tools/SpeechRecognition/core/ids.ts

@@ -0,0 +1,11 @@
+let counter = 0;
+
+/**
+ * Cheap monotonic id — collisions are fine across sessions, we just need
+ * uniqueness within one component lifecycle. Avoids pulling in nanoid for
+ * a tool that already keeps the lazy chunk small.
+ */
+export function newSegmentId(): string {
+  counter = (counter + 1) % Number.MAX_SAFE_INTEGER;
+  return `seg_${Date.now().toString(36)}_${counter.toString(36)}`;
+}

package/src/tools/SpeechRecognition/core/index.ts

@@ -0,0 +1,14 @@
+export { newSegmentId } from './ids';
+export { sttLogger } from './logger';
+export {
+  EMPTY_TRANSCRIPT,
+  buildTranscript,
+  joinFinal,
+  normaliseFinal,
+} from './transcript';
+export {
+  INITIAL_STATE,
+  reducer,
+  type RecognitionAction,
+  type RecognitionState,
+} from './reducer';

package/src/tools/SpeechRecognition/core/language.ts

@@ -0,0 +1,78 @@
+/**
+ * Maps 2-letter ISO 639-1 codes (`en`, `ru`, `ko` — what
+ * `@djangocfg/i18n` exposes via `useLocale()`) to BCP-47 tags
+ * (`en-US`, `ru-RU`, `ko-KR`) that the Web Speech API and most cloud
+ * STT services expect.
+ *
+ * We keep a small built-in table for the locales we ship translations
+ * for; everything else falls through to `<code>-<UPPER(code)>`, which
+ * works for the majority of regions. The mapping is also re-exported
+ * so consumers can extend it.
+ */
+
+const ISO_TO_BCP47: Record<string, string> = {
+  en: 'en-US',
+  ru: 'ru-RU',
+  ko: 'ko-KR',
+  ja: 'ja-JP',
+  zh: 'zh-CN',
+  de: 'de-DE',
+  fr: 'fr-FR',
+  it: 'it-IT',
+  es: 'es-ES',
+  nl: 'nl-NL',
+  ar: 'ar-SA',
+  tr: 'tr-TR',
+  pl: 'pl-PL',
+  sv: 'sv-SE',
+  no: 'nb-NO',
+  da: 'da-DK',
+  pt: 'pt-BR',
+};
+
+export const DEFAULT_ISO_TO_BCP47 = ISO_TO_BCP47;
+
+/**
+ * Normalise any of:
+ *   - BCP-47 ("en-US", "ru-RU") — passed through.
+ *   - ISO 639-1 ("en", "ru")    — mapped via the table above, or
+ *                                 falls back to `<code>-<UPPER(code)>`.
+ *   - `null`/`undefined`/empty  — returns `undefined`.
+ */
+export function toBCP47(
+  code: string | null | undefined,
+  table: Record<string, string> = ISO_TO_BCP47,
+): string | undefined {
+  if (!code) return undefined;
+  const trimmed = code.trim();
+  if (!trimmed) return undefined;
+  if (trimmed.includes('-')) return trimmed; // already BCP-47
+  const lower = trimmed.toLowerCase();
+  return table[lower] ?? `${lower}-${lower.toUpperCase()}`;
+}
+
+/**
+ * Resolve the language tag for a speech session in priority order:
+ *   1. `explicit` prop (always wins) — host-supplied override.
+ *   2. `prefs`    — value stored in `useSpeechPrefs` (user picked it
+ *                   via `<LanguagePicker>` or programmatically).
+ *   3. `i18n`     — current i18n locale (2-letter ISO).
+ *   4. `navigator.language` — browser default.
+ *   5. `'en-US'`  — last-resort safety net.
+ *
+ * All inputs may be ISO-2 or BCP-47; the function normalises before
+ * returning.
+ */
+export function resolveSpeechLanguage(opts: {
+  explicit?: string;
+  prefs?: string | null;
+  i18n?: string | null;
+}): string {
+  return (
+    toBCP47(opts.explicit) ??
+    toBCP47(opts.prefs) ??
+    toBCP47(opts.i18n) ??
+    toBCP47(typeof navigator !== 'undefined' ? navigator.language : null) ??
+    'en-US'
+  );
+}