even-toolkit 1.1.0 → 1.1.2

package/stt/react/useSTT.ts

@@ -0,0 +1,113 @@
+import { useState, useRef, useEffect, useCallback } from 'react';
+import type { UseSTTConfig, UseSTTReturn, STTState, STTError } from '../types';
+import { STTEngine } from '../engine';
+
+export function useSTT(config: UseSTTConfig = {}): UseSTTReturn {
+  const [transcript, setTranscript] = useState('');
+  const [interimTranscript, setInterimTranscript] = useState('');
+  const [isListening, setIsListening] = useState(false);
+  const [isLoading, setIsLoading] = useState(false);
+  const [loadProgress] = useState(0);
+  const [error, setError] = useState<STTError | null>(null);
+  const [state, setState] = useState<STTState>('idle');
+
+  const engineRef = useRef<STTEngine | null>(null);
+  const configRef = useRef(config);
+  configRef.current = config;
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      engineRef.current?.dispose();
+      engineRef.current = null;
+    };
+  }, []);
+
+  const start = useCallback(async () => {
+    // Dispose previous engine
+    engineRef.current?.dispose();
+
+    const cfg = configRef.current;
+    const engine = new STTEngine({
+      provider: cfg.provider ?? 'web-speech',
+      source: cfg.source,
+      language: cfg.language,
+      mode: cfg.mode,
+      apiKey: cfg.apiKey,
+      modelId: cfg.modelId,
+      continuous: cfg.continuous,
+      vad: cfg.vad,
+      fallback: cfg.fallback,
+    });
+
+    engineRef.current = engine;
+
+    // Subscribe to events
+    engine.onTranscript((t) => {
+      if (t.isFinal) {
+        setTranscript((prev) => (prev ? prev + ' ' + t.text : t.text));
+        setInterimTranscript('');
+      } else {
+        setInterimTranscript(t.text);
+      }
+      cfg.onTranscript?.(t.text, t.isFinal);
+    });
+
+    engine.onStateChange((s) => {
+      setState(s);
+      setIsListening(s === 'listening');
+      setIsLoading(s === 'loading');
+      if (s === 'idle') {
+        setInterimTranscript('');
+      }
+    });
+
+    engine.onError((e) => {
+      setError(e);
+    });
+
+    setError(null);
+    await engine.start();
+  }, []);
+
+  const stop = useCallback(() => {
+    engineRef.current?.stop();
+  }, []);
+
+  const abort = useCallback(() => {
+    engineRef.current?.abort();
+  }, []);
+
+  const reset = useCallback(() => {
+    engineRef.current?.abort();
+    setTranscript('');
+    setInterimTranscript('');
+    setError(null);
+    setState('idle');
+    setIsListening(false);
+    setIsLoading(false);
+  }, []);
+
+  // Auto-start if configured
+  useEffect(() => {
+    if (config.autoStart) {
+      start();
+    }
+    // Only run on mount
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return {
+    transcript,
+    interimTranscript,
+    isListening,
+    isLoading,
+    loadProgress,
+    error,
+    state,
+    start,
+    stop,
+    abort,
+    reset,
+  };
+}

package/stt/registry.ts

@@ -0,0 +1,24 @@
+import type { STTProvider } from './types';
+
+export async function createProvider(type: string): Promise<STTProvider> {
+  switch (type) {
+    case 'web-speech': {
+      const { WebSpeechProvider } = await import('./providers/web-speech');
+      return new WebSpeechProvider();
+    }
+    case 'whisper-local': {
+      const { WhisperLocalProvider } = await import('./providers/whisper-local/provider');
+      return new WhisperLocalProvider();
+    }
+    case 'whisper-api': {
+      const { WhisperApiProvider } = await import('./providers/whisper-api');
+      return new WhisperApiProvider();
+    }
+    case 'deepgram': {
+      const { DeepgramProvider } = await import('./providers/deepgram');
+      return new DeepgramProvider();
+    }
+    default:
+      throw new Error(`Unknown STT provider: ${type}`);
+  }
+}

package/stt/sources/glass-bridge.ts

@@ -0,0 +1,67 @@
+import type { AudioSource } from '../types';
+import { uint8ToPcm16, pcm16ToFloat32 } from '../audio/pcm-utils';
+
+const GLASS_SAMPLE_RATE = 16000;
+
+export interface GlassBridgeSourceConfig {
+  /** The EvenHub bridge instance that fires audio events */
+  bridge: {
+    onEvent(handler: (event: GlassAudioEvent) => void): void;
+  };
+}
+
+export interface GlassAudioEvent {
+  audioEvent?: {
+    audioPcm?: Uint8Array;
+  };
+}
+
+/**
+ * AudioSource for G2 smart glasses.
+ * Listens for audio PCM events from the EvenHub SDK bridge
+ * and converts 16-bit PCM to Float32.
+ */
+export class GlassBridgeSource implements AudioSource {
+  private config: GlassBridgeSourceConfig;
+  private listeners: Array<(pcm: Float32Array, sampleRate: number) => void> = [];
+  private listening = false;
+
+  constructor(config: GlassBridgeSourceConfig) {
+    this.config = config;
+  }
+
+  async start(): Promise<void> {
+    if (this.listening) return;
+    this.listening = true;
+
+    this.config.bridge.onEvent((event: GlassAudioEvent) => {
+      if (!this.listening) return;
+      const audioPcm = event.audioEvent?.audioPcm;
+      if (!audioPcm || audioPcm.length === 0) return;
+
+      const pcm16 = uint8ToPcm16(audioPcm);
+      const float32 = pcm16ToFloat32(pcm16);
+
+      for (const cb of this.listeners) {
+        cb(float32, GLASS_SAMPLE_RATE);
+      }
+    });
+  }
+
+  stop(): void {
+    this.listening = false;
+  }
+
+  onAudioData(cb: (pcm: Float32Array, sampleRate: number) => void): () => void {
+    this.listeners.push(cb);
+    return () => {
+      const idx = this.listeners.indexOf(cb);
+      if (idx >= 0) this.listeners.splice(idx, 1);
+    };
+  }
+
+  dispose(): void {
+    this.stop();
+    this.listeners.length = 0;
+  }
+}

package/stt/sources/microphone.ts

@@ -0,0 +1,75 @@
+import type { AudioSource } from '../types';
+
+const CHUNK_SIZE = 4096;
+const DEFAULT_SAMPLE_RATE = 16000;
+
+/**
+ * AudioSource that captures PCM audio from the device microphone
+ * using getUserMedia and ScriptProcessorNode.
+ */
+export class MicrophoneSource implements AudioSource {
+  private stream: MediaStream | null = null;
+  private audioContext: AudioContext | null = null;
+  private scriptNode: ScriptProcessorNode | null = null;
+  private sourceNode: MediaStreamAudioSourceNode | null = null;
+  private listeners: Array<(pcm: Float32Array, sampleRate: number) => void> = [];
+
+  async start(): Promise<void> {
+    this.stream = await navigator.mediaDevices.getUserMedia({
+      audio: { sampleRate: DEFAULT_SAMPLE_RATE, channelCount: 1 },
+    });
+
+    this.audioContext = new AudioContext({ sampleRate: DEFAULT_SAMPLE_RATE });
+    this.sourceNode = this.audioContext.createMediaStreamSource(this.stream);
+    this.scriptNode = this.audioContext.createScriptProcessor(CHUNK_SIZE, 1, 1);
+
+    this.scriptNode.onaudioprocess = (event) => {
+      const input = event.inputBuffer.getChannelData(0);
+      // Copy the buffer — it's reused by the browser
+      const chunk = new Float32Array(input.length);
+      chunk.set(input);
+      const rate = this.audioContext?.sampleRate ?? DEFAULT_SAMPLE_RATE;
+      for (const cb of this.listeners) {
+        cb(chunk, rate);
+      }
+    };
+
+    this.sourceNode.connect(this.scriptNode);
+    this.scriptNode.connect(this.audioContext.destination);
+  }
+
+  stop(): void {
+    if (this.scriptNode) {
+      this.scriptNode.onaudioprocess = null;
+      this.scriptNode.disconnect();
+      this.scriptNode = null;
+    }
+    if (this.sourceNode) {
+      this.sourceNode.disconnect();
+      this.sourceNode = null;
+    }
+    if (this.stream) {
+      for (const track of this.stream.getTracks()) {
+        track.stop();
+      }
+      this.stream = null;
+    }
+    if (this.audioContext) {
+      this.audioContext.close().catch(() => {});
+      this.audioContext = null;
+    }
+  }
+
+  onAudioData(cb: (pcm: Float32Array, sampleRate: number) => void): () => void {
+    this.listeners.push(cb);
+    return () => {
+      const idx = this.listeners.indexOf(cb);
+      if (idx >= 0) this.listeners.splice(idx, 1);
+    };
+  }
+
+  dispose(): void {
+    this.stop();
+    this.listeners.length = 0;
+  }
+}

package/stt/types.ts

@@ -0,0 +1,104 @@
+// ── STT Provider Types ──
+
+export type STTProviderType = 'web-speech' | 'whisper-local' | 'whisper-api' | 'deepgram' | string;
+export type STTMode = 'streaming' | 'batch';
+export type STTState = 'idle' | 'loading' | 'listening' | 'processing' | 'error';
+
+export interface STTTranscript {
+  text: string;
+  isFinal: boolean;
+  confidence: number;
+  language?: string;
+  timestamp: number;
+}
+
+export interface STTProviderConfig {
+  language?: string;          // BCP 47 tag, default 'en-US'
+  mode?: STTMode;
+  apiKey?: string;
+  modelId?: string;
+  continuous?: boolean;
+  vadEnabled?: boolean;
+  vadSilenceMs?: number;      // default 1500
+  sampleRate?: number;        // default 16000
+  maxDurationMs?: number;
+}
+
+export interface STTError {
+  code: 'not-allowed' | 'no-speech' | 'network' | 'model-load' | 'aborted' | 'unsupported' | 'unknown';
+  message: string;
+  provider: STTProviderType;
+}
+
+export interface STTProvider {
+  readonly type: STTProviderType;
+  readonly supportedModes: STTMode[];
+  readonly state: STTState;
+
+  init(config: STTProviderConfig): Promise<void>;
+  start(): void;
+  stop(): void;
+  abort(): void;
+  dispose(): void;
+
+  onTranscript(cb: (t: STTTranscript) => void): () => void;
+  onStateChange(cb: (s: STTState) => void): () => void;
+  onError(cb: (e: STTError) => void): () => void;
+
+  /** Batch mode: feed raw audio for transcription */
+  transcribe?(audio: Float32Array, sampleRate: number): Promise<STTTranscript>;
+}
+
+// ── Audio Source Types ──
+
+export interface AudioSource {
+  start(): Promise<void>;
+  stop(): void;
+  onAudioData(cb: (pcm: Float32Array, sampleRate: number) => void): () => void;
+  dispose(): void;
+}
+
+// ── Engine Config ──
+
+export interface STTEngineConfig {
+  provider: STTProviderType;
+  source?: 'microphone' | 'glass-bridge' | AudioSource;
+  language?: string;
+  mode?: STTMode;
+  apiKey?: string;
+  modelId?: string;
+  continuous?: boolean;
+  vad?: boolean | { silenceMs?: number; thresholdDb?: number };
+  sampleRate?: number;
+  fallback?: STTProviderType;
+}
+
+// ── React Hook Types ──
+
+export interface UseSTTConfig {
+  provider?: STTProviderType;
+  source?: 'microphone' | 'glass-bridge';
+  language?: string;
+  mode?: STTMode;
+  apiKey?: string;
+  modelId?: string;
+  continuous?: boolean;
+  vad?: boolean;
+  autoStart?: boolean;
+  fallback?: STTProviderType;
+  onTranscript?: (text: string, isFinal: boolean) => void;
+}
+
+export interface UseSTTReturn {
+  transcript: string;
+  interimTranscript: string;
+  isListening: boolean;
+  isLoading: boolean;
+  loadProgress: number;
+  error: STTError | null;
+  state: STTState;
+  start: () => Promise<void>;
+  stop: () => void;
+  abort: () => void;
+  reset: () => void;
+}