even-toolkit 1.1.0 → 1.1.2

package/stt/providers/web-speech.ts

@@ -0,0 +1,221 @@
+import type {
+  STTProvider,
+  STTProviderConfig,
+  STTMode,
+  STTState,
+  STTTranscript,
+  STTError,
+} from '../types';
+
+// ── Inline SpeechRecognition types (not in standard TS lib) ──
+
+interface SpeechRecognitionEvent extends Event {
+  readonly results: SpeechRecognitionResultList;
+  readonly resultIndex: number;
+}
+
+interface SpeechRecognitionErrorEvent extends Event {
+  readonly error: string;
+  readonly message: string;
+}
+
+interface SpeechRecognitionResultList {
+  readonly length: number;
+  item(index: number): SpeechRecognitionResult;
+  [index: number]: SpeechRecognitionResult;
+}
+
+interface SpeechRecognitionResult {
+  readonly length: number;
+  readonly isFinal: boolean;
+  item(index: number): SpeechRecognitionAlternative;
+  [index: number]: SpeechRecognitionAlternative;
+}
+
+interface SpeechRecognitionAlternative {
+  readonly transcript: string;
+  readonly confidence: number;
+}
+
+interface SpeechRecognitionInstance {
+  continuous: boolean;
+  interimResults: boolean;
+  lang: string;
+  onresult: ((event: SpeechRecognitionEvent) => void) | null;
+  onerror: ((event: SpeechRecognitionErrorEvent) => void) | null;
+  onstart: (() => void) | null;
+  onend: (() => void) | null;
+  start(): void;
+  stop(): void;
+  abort(): void;
+}
+
+type SpeechRecognitionConstructor = new () => SpeechRecognitionInstance;
+
+function getSpeechRecognitionCtor(): SpeechRecognitionConstructor | null {
+  if (typeof window === 'undefined') return null;
+  const w = window as unknown as Record<string, unknown>;
+  return (w.SpeechRecognition ?? w.webkitSpeechRecognition) as SpeechRecognitionConstructor | null;
+}
+
+// ── Provider ──
+
+export class WebSpeechProvider implements STTProvider {
+  readonly type = 'web-speech' as const;
+  readonly supportedModes: STTMode[] = ['streaming'];
+
+  private _state: STTState = 'idle';
+  private recognition: SpeechRecognitionInstance | null = null;
+  private config: STTProviderConfig = {};
+  private stopping = false;
+
+  private transcriptCbs: Array<(t: STTTranscript) => void> = [];
+  private stateCbs: Array<(s: STTState) => void> = [];
+  private errorCbs: Array<(e: STTError) => void> = [];
+
+  get state(): STTState {
+    return this._state;
+  }
+
+  async init(config: STTProviderConfig): Promise<void> {
+    const Ctor = getSpeechRecognitionCtor();
+    if (!Ctor) {
+      this.emitError({ code: 'unsupported', message: 'SpeechRecognition not available in this browser', provider: this.type });
+      throw new Error('SpeechRecognition not supported');
+    }
+    this.config = config;
+  }
+
+  start(): void {
+    const Ctor = getSpeechRecognitionCtor();
+    if (!Ctor) {
+      this.emitError({ code: 'unsupported', message: 'SpeechRecognition not available', provider: this.type });
+      return;
+    }
+
+    // Tear down previous instance if any
+    if (this.recognition) {
+      try { this.recognition.abort(); } catch { /* ignore */ }
+    }
+
+    this.stopping = false;
+    const recognition = new Ctor();
+    recognition.continuous = this.config.continuous ?? true;
+    recognition.interimResults = true;
+    recognition.lang = this.config.language ?? 'en-US';
+
+    recognition.onstart = () => {
+      this.setState('listening');
+    };
+
+    recognition.onresult = (event: SpeechRecognitionEvent) => {
+      for (let i = event.resultIndex; i < event.results.length; i++) {
+        const result = event.results[i];
+        if (!result?.[0]) continue;
+
+        const transcript: STTTranscript = {
+          text: result[0].transcript,
+          isFinal: result.isFinal,
+          confidence: result[0].confidence ?? 0,
+          timestamp: Date.now(),
+        };
+        this.emitTranscript(transcript);
+      }
+    };
+
+    recognition.onerror = (event: SpeechRecognitionErrorEvent) => {
+      // Suppress no-speech and aborted-while-stopping
+      if (event.error === 'no-speech') return;
+      if (event.error === 'aborted' && this.stopping) return;
+
+      const code = mapErrorCode(event.error);
+      this.emitError({ code, message: event.message || event.error, provider: this.type });
+
+      if (code !== 'no-speech') {
+        this.setState('error');
+      }
+    };
+
+    recognition.onend = () => {
+      this.recognition = null;
+      this.setState('idle');
+    };
+
+    this.recognition = recognition;
+    recognition.start();
+  }
+
+  stop(): void {
+    this.stopping = true;
+    if (this.recognition) {
+      this.recognition.stop();
+    }
+  }
+
+  abort(): void {
+    this.stopping = true;
+    if (this.recognition) {
+      this.recognition.abort();
+    }
+  }
+
+  dispose(): void {
+    this.abort();
+    this.transcriptCbs = [];
+    this.stateCbs = [];
+    this.errorCbs = [];
+  }
+
+  onTranscript(cb: (t: STTTranscript) => void): () => void {
+    this.transcriptCbs.push(cb);
+    return () => {
+      this.transcriptCbs = this.transcriptCbs.filter((c) => c !== cb);
+    };
+  }
+
+  onStateChange(cb: (s: STTState) => void): () => void {
+    this.stateCbs.push(cb);
+    return () => {
+      this.stateCbs = this.stateCbs.filter((c) => c !== cb);
+    };
+  }
+
+  onError(cb: (e: STTError) => void): () => void {
+    this.errorCbs.push(cb);
+    return () => {
+      this.errorCbs = this.errorCbs.filter((c) => c !== cb);
+    };
+  }
+
+  // ── Private helpers ──
+
+  private setState(s: STTState): void {
+    if (this._state === s) return;
+    this._state = s;
+    for (const cb of this.stateCbs) cb(s);
+  }
+
+  private emitTranscript(t: STTTranscript): void {
+    for (const cb of this.transcriptCbs) cb(t);
+  }
+
+  private emitError(e: STTError): void {
+    for (const cb of this.errorCbs) cb(e);
+  }
+}
+
+function mapErrorCode(error: string): STTError['code'] {
+  switch (error) {
+    case 'not-allowed':
+    case 'service-not-allowed':
+      return 'not-allowed';
+    case 'no-speech':
+      return 'no-speech';
+    case 'network':
+      return 'network';
+    case 'aborted':
+      return 'aborted';
+    default:
+      return 'unknown';
+  }
+}

package/stt/providers/whisper-api.ts

@@ -0,0 +1,146 @@
+import type {
+  STTProvider,
+  STTProviderConfig,
+  STTMode,
+  STTState,
+  STTTranscript,
+  STTError,
+} from '../types';
+import { float32ToWav } from '../audio/pcm-utils';
+
+const WHISPER_API_URL = 'https://api.openai.com/v1/audio/transcriptions';
+
+export class WhisperApiProvider implements STTProvider {
+  readonly type = 'whisper-api' as const;
+  readonly supportedModes: STTMode[] = ['batch'];
+
+  private _state: STTState = 'idle';
+  private apiKey = '';
+  private language = 'en';
+  private modelId = 'whisper-1';
+
+  private transcriptCbs: Array<(t: STTTranscript) => void> = [];
+  private stateCbs: Array<(s: STTState) => void> = [];
+  private errorCbs: Array<(e: STTError) => void> = [];
+
+  get state(): STTState {
+    return this._state;
+  }
+
+  async init(config: STTProviderConfig): Promise<void> {
+    this.apiKey = config.apiKey ?? '';
+    this.language = config.language ?? 'en';
+    this.modelId = config.modelId ?? 'whisper-1';
+
+    if (!this.apiKey) {
+      const err: STTError = { code: 'not-allowed', message: 'API key is required', provider: this.type };
+      this.emitError(err);
+      throw new Error(err.message);
+    }
+  }
+
+  start(): void {
+    // Batch mode — no-op; audio is fed via transcribe()
+  }
+
+  stop(): void {
+    this.setState('idle');
+  }
+
+  abort(): void {
+    this.setState('idle');
+  }
+
+  dispose(): void {
+    this.transcriptCbs = [];
+    this.stateCbs = [];
+    this.errorCbs = [];
+    this.setState('idle');
+  }
+
+  async transcribe(audio: Float32Array, sampleRate: number): Promise<STTTranscript> {
+    this.setState('processing');
+
+    try {
+      const wavBlob = float32ToWav(audio, sampleRate);
+
+      const formData = new FormData();
+      formData.append('file', wavBlob, 'audio.wav');
+      formData.append('model', this.modelId);
+      formData.append('language', this.language);
+
+      const response = await fetch(WHISPER_API_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+        body: formData,
+      });
+
+      if (!response.ok) {
+        const code: STTError['code'] = response.status === 401 ? 'not-allowed' : 'network';
+        const message = `Whisper API error: ${response.status} ${response.statusText}`;
+        const err: STTError = { code, message, provider: this.type };
+        this.emitError(err);
+        this.setState('error');
+        throw new Error(message);
+      }
+
+      const json = (await response.json()) as { text: string };
+
+      const transcript: STTTranscript = {
+        text: json.text,
+        isFinal: true,
+        confidence: 1,
+        timestamp: Date.now(),
+      };
+
+      this.emitTranscript(transcript);
+      this.setState('idle');
+      return transcript;
+    } catch (err: any) {
+      // If already handled (HTTP error), just rethrow
+      if (this._state === 'error') throw err;
+
+      const sttError: STTError = {
+        code: 'network',
+        message: err?.message ?? 'Network error',
+        provider: this.type,
+      };
+      this.emitError(sttError);
+      this.setState('error');
+      throw err;
+    }
+  }
+
+  onTranscript(cb: (t: STTTranscript) => void): () => void {
+    this.transcriptCbs.push(cb);
+    return () => { this.transcriptCbs = this.transcriptCbs.filter((c) => c !== cb); };
+  }
+
+  onStateChange(cb: (s: STTState) => void): () => void {
+    this.stateCbs.push(cb);
+    return () => { this.stateCbs = this.stateCbs.filter((c) => c !== cb); };
+  }
+
+  onError(cb: (e: STTError) => void): () => void {
+    this.errorCbs.push(cb);
+    return () => { this.errorCbs = this.errorCbs.filter((c) => c !== cb); };
+  }
+
+  // ── Private ──
+
+  private setState(s: STTState): void {
+    if (this._state === s) return;
+    this._state = s;
+    for (const cb of this.stateCbs) cb(s);
+  }
+
+  private emitTranscript(t: STTTranscript): void {
+    for (const cb of this.transcriptCbs) cb(t);
+  }
+
+  private emitError(e: STTError): void {
+    for (const cb of this.errorCbs) cb(e);
+  }
+}

package/stt/providers/whisper-local/provider.ts

@@ -0,0 +1,226 @@
+import type {
+  STTProvider,
+  STTProviderConfig,
+  STTMode,
+  STTState,
+  STTTranscript,
+  STTError,
+} from '../../types';
+
+interface WorkerMessage {
+  type: 'init' | 'transcribe';
+  modelId?: string;
+  language?: string;
+  audio?: Float32Array;
+}
+
+interface WorkerResponse {
+  type: 'ready' | 'progress' | 'result' | 'error';
+  loaded?: number;
+  total?: number;
+  text?: string;
+  confidence?: number;
+  message?: string;
+}
+
+export class WhisperLocalProvider implements STTProvider {
+  readonly type = 'whisper-local' as const;
+  readonly supportedModes: STTMode[] = ['batch'];
+
+  private _state: STTState = 'idle';
+  private worker: Worker | null = null;
+  private config: STTProviderConfig = {};
+  private ready = false;
+
+  private transcriptCbs: Array<(t: STTTranscript) => void> = [];
+  private stateCbs: Array<(s: STTState) => void> = [];
+  private errorCbs: Array<(e: STTError) => void> = [];
+
+  private pendingResolve: ((t: STTTranscript) => void) | null = null;
+  private pendingReject: ((e: Error) => void) | null = null;
+  private initResolve: (() => void) | null = null;
+  private initReject: ((e: Error) => void) | null = null;
+
+  get state(): STTState {
+    return this._state;
+  }
+
+  async init(config: STTProviderConfig): Promise<void> {
+    this.config = config;
+    this.setState('loading');
+
+    return new Promise<void>((resolve, reject) => {
+      this.initResolve = resolve;
+      this.initReject = reject;
+
+      this.worker = new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });
+
+      this.worker.onmessage = (e: MessageEvent<WorkerResponse>) => {
+        this.handleWorkerMessage(e.data);
+      };
+
+      this.worker.onerror = (err) => {
+        const sttError: STTError = {
+          code: 'model-load',
+          message: err.message || 'Worker error',
+          provider: this.type,
+        };
+        this.emitError(sttError);
+        this.setState('error');
+        if (this.initReject) {
+          this.initReject(new Error(sttError.message));
+          this.initResolve = null;
+          this.initReject = null;
+        }
+      };
+
+      const msg: WorkerMessage = {
+        type: 'init',
+        modelId: config.modelId,
+        language: config.language,
+      };
+      this.worker.postMessage(msg);
+    });
+  }
+
+  start(): void {
+    // Batch mode: start is a no-op; audio is fed via transcribe()
+    if (this.ready) {
+      this.setState('listening');
+    }
+  }
+
+  stop(): void {
+    if (this._state === 'listening' || this._state === 'processing') {
+      this.setState('idle');
+    }
+  }
+
+  abort(): void {
+    if (this.pendingReject) {
+      this.pendingReject(new Error('Aborted'));
+      this.pendingResolve = null;
+      this.pendingReject = null;
+    }
+    this.setState('idle');
+  }
+
+  dispose(): void {
+    this.abort();
+    if (this.worker) {
+      this.worker.terminate();
+      this.worker = null;
+    }
+    this.ready = false;
+    this.transcriptCbs = [];
+    this.stateCbs = [];
+    this.errorCbs = [];
+  }
+
+  async transcribe(audio: Float32Array, sampleRate: number): Promise<STTTranscript> {
+    if (!this.worker || !this.ready) {
+      throw new Error('Provider not initialized');
+    }
+
+    this.setState('processing');
+
+    return new Promise<STTTranscript>((resolve, reject) => {
+      this.pendingResolve = resolve;
+      this.pendingReject = reject;
+
+      this.worker!.postMessage(
+        { type: 'transcribe', audio, language: this.config.language ?? 'en', sampleRate },
+        [audio.buffer],
+      );
+    });
+  }
+
+  onTranscript(cb: (t: STTTranscript) => void): () => void {
+    this.transcriptCbs.push(cb);
+    return () => { this.transcriptCbs = this.transcriptCbs.filter((c) => c !== cb); };
+  }
+
+  onStateChange(cb: (s: STTState) => void): () => void {
+    this.stateCbs.push(cb);
+    return () => { this.stateCbs = this.stateCbs.filter((c) => c !== cb); };
+  }
+
+  onError(cb: (e: STTError) => void): () => void {
+    this.errorCbs.push(cb);
+    return () => { this.errorCbs = this.errorCbs.filter((c) => c !== cb); };
+  }
+
+  // ── Private ──
+
+  private handleWorkerMessage(data: WorkerResponse): void {
+    switch (data.type) {
+      case 'ready':
+        this.ready = true;
+        this.setState('idle');
+        if (this.initResolve) {
+          this.initResolve();
+          this.initResolve = null;
+          this.initReject = null;
+        }
+        break;
+
+      case 'progress':
+        // Model download progress — stay in loading state
+        break;
+
+      case 'result': {
+        const transcript: STTTranscript = {
+          text: data.text ?? '',
+          isFinal: true,
+          confidence: data.confidence ?? 0.95,
+          timestamp: Date.now(),
+        };
+        this.emitTranscript(transcript);
+        this.setState('listening');
+
+        if (this.pendingResolve) {
+          this.pendingResolve(transcript);
+          this.pendingResolve = null;
+          this.pendingReject = null;
+        }
+        break;
+      }
+
+      case 'error': {
+        const sttError: STTError = {
+          code: 'model-load',
+          message: data.message ?? 'Worker error',
+          provider: this.type,
+        };
+        this.emitError(sttError);
+        this.setState('error');
+
+        if (this.pendingReject) {
+          this.pendingReject(new Error(sttError.message));
+          this.pendingResolve = null;
+          this.pendingReject = null;
+        }
+        if (this.initReject) {
+          this.initReject(new Error(sttError.message));
+          this.initResolve = null;
+          this.initReject = null;
+        }
+        break;
+      }
+    }
+  }
+
+  private setState(s: STTState): void {
+    if (this._state === s) return;
+    this._state = s;
+    for (const cb of this.stateCbs) cb(s);
+  }
+
+  private emitTranscript(t: STTTranscript): void {
+    for (const cb of this.transcriptCbs) cb(t);
+  }
+
+  private emitError(e: STTError): void {
+    for (const cb of this.errorCbs) cb(e);
+  }
+}

package/stt/providers/whisper-local/worker.ts

@@ -0,0 +1,40 @@
+// WebWorker for Whisper local inference via @huggingface/transformers
+
+let pipe: any = null;
+
+self.onmessage = async (e: MessageEvent) => {
+  const { type } = e.data;
+
+  if (type === 'init') {
+    try {
+      const { pipeline } = await import('@huggingface/transformers');
+      pipe = await pipeline(
+        'automatic-speech-recognition',
+        e.data.modelId ?? 'onnx-community/whisper-tiny',
+        {
+          progress_callback: (p: any) => self.postMessage({ type: 'progress', ...p }),
+        },
+      );
+      self.postMessage({ type: 'ready' });
+    } catch (err: any) {
+      self.postMessage({ type: 'error', message: err?.message ?? 'Failed to load model' });
+    }
+  }
+
+  if (type === 'transcribe') {
+    if (!pipe) {
+      self.postMessage({ type: 'error', message: 'Model not loaded' });
+      return;
+    }
+
+    try {
+      const result = await pipe(e.data.audio, {
+        language: e.data.language ?? 'en',
+        return_timestamps: false,
+      });
+      self.postMessage({ type: 'result', text: result.text, confidence: 0.95 });
+    } catch (err: any) {
+      self.postMessage({ type: 'error', message: err?.message ?? 'Transcription failed' });
+    }
+  }
+};