@voice-kit/core 0.1.1 → 0.1.3

package/dist/stt.d.ts

@@ -1,308 +0,0 @@
-import { S as STTProvider, g as STTConfig, h as STTResult } from './index-CkTG6DOa.js';
-import { EventEmitter } from 'node:events';
-import 'ai';
-
-/**
- * @voice-kit/core — AssemblyAI STT Provider
- *
- * Async long-form transcription using AssemblyAI SDK.
- * Best for post-call recordings, meeting notes, long interviews.
- * Does not support realtime streaming — use Deepgram for live calls.
- */
-
-/**
- * AssemblyAI async transcription provider.
- * @internal — obtained via createSTT('assemblyai', config)
- */
-declare class AssemblyAISTTProvider implements STTProvider {
-    readonly name = "assemblyai";
-    readonly supportsStreaming = false;
-    readonly supportedLanguages: string[];
-    private readonly client;
-    private readonly config;
-    constructor(config: STTConfig);
-    /**
-     * Batch-transcribes collected audio. AssemblyAI has no realtime streaming.
-     * Collects all audio from the iterable, uploads, then polls for result.
-     *
-     * @param audio  Async iterable of PCM buffers
-     */
-    transcribeStream(audio: AsyncIterable<Buffer>): AsyncIterable<STTResult>;
-    /**
-     * Upload audio to AssemblyAI and wait for async transcription.
-     * Suitable for call recordings. Average latency: 15–45s per minute of audio.
-     *
-     * @param audio  Raw WAV/PCM/MP3 buffer
-     *
-     * @example
-     * ```ts
-     * const stt = createSTT('assemblyai', { wordTimestamps: true })
-     * const result = await stt.transcribeBatch(recordingBuffer)
-     * console.log(result.words) // Word-level timestamps
-     * ```
-     */
-    transcribeBatch(audio: Buffer): Promise<STTResult>;
-}
-
-/**
- * @voice-kit/core — Deepgram Nova-3 STT Provider
- *
- * Streaming STT using Deepgram Nova-3. Handles WebSocket reconnect with
- * exponential backoff, interim + final results, language detection.
- * Never instantiate directly — use createSTT('deepgram', config).
- *
- * SDK: @deepgram/sdk v5 (beta) — https://github.com/deepgram/deepgram-js-sdk
- */
-
-/**
- * Deepgram Nova-3 streaming STT provider.
- * @internal — obtained via createSTT('deepgram', config)
- */
-declare class DeepgramSTTProvider implements STTProvider {
-    readonly name = "deepgram";
-    readonly supportsStreaming = true;
-    readonly supportedLanguages: string[];
-    private readonly client;
-    private readonly config;
-    constructor(config: STTConfig);
-    /**
-     * Stream audio to Deepgram and receive interim + final transcription results.
-     * Handles reconnection transparently with exponential backoff.
-     *
-     * @param audio  Async iterable of 16kHz PCM buffers from AudioPipeline
-     *
-     * @example
-     * ```ts
-     * const stt = createSTT('deepgram', { language: 'hi-IN' })
-     * for await (const result of stt.transcribeStream(audioIterable)) {
-     *   if (result.isFinal) console.log('User said:', result.transcript)
-     * }
-     * ```
-     */
-    transcribeStream(audio: AsyncIterable<Buffer>): AsyncIterable<STTResult>;
-    /**
-     * Transcribe a complete audio buffer (non-streaming).
-     * Uses Deepgram pre-recorded API.
-     *
-     * @param audio  Raw PCM or WAV buffer
-     */
-    transcribeBatch(audio: Buffer): Promise<STTResult>;
-    /**
-     * Create and open a live WebSocket connection to Deepgram.
-     *
-     * v5 connection lifecycle (3 explicit steps):
-     *   1. await listen.v1.connect(options)  — constructs the connection object
-     *   2. connection.connect()              — initiates the WebSocket handshake
-     *   3. await connection.waitForOpen()    — resolves once the socket is ready
-     *
-     * @internal
-     */
-    private connectWithRetry;
-}
-
-/**
- * @voice-kit/core — Sarvam AI Indic STT Provider
- *
- * Sarvam AI provides state-of-the-art STT for Indian languages:
- * hi-IN, kn-IN, ta-IN, te-IN, mr-IN, bn-IN, gu-IN, pa-IN, or-IN
- *
- * Uses axios for HTTP calls. No official JS SDK — we use the REST API directly.
- */
-
-/**
- * Sarvam AI Indic STT provider.
- * @internal — obtained via createSTT('sarvam', config)
- */
-declare class SarvamSTTProvider implements STTProvider {
-    readonly name = "sarvam";
-    readonly supportsStreaming = false;
-    readonly supportedLanguages: string[];
-    private readonly http;
-    private readonly config;
-    constructor(config: STTConfig);
-    /**
-     * Collects audio and transcribes via Sarvam batch API.
-     * Sarvam doesn't support realtime streaming.
-     *
-     * @param audio  Async iterable of 16kHz PCM buffers
-     */
-    transcribeStream(audio: AsyncIterable<Buffer>): AsyncIterable<STTResult>;
-    /**
-     * Transcribe a WAV/PCM audio buffer in an Indic language.
-     *
-     * @param audio  16kHz PCM or WAV buffer
-     *
-     * @example
-     * ```ts
-     * const stt = createSTT('sarvam', { language: 'ta-IN' })
-     * const result = await stt.transcribeBatch(tamilAudioBuffer)
-     * console.log(result.transcript) // Tamil text
-     * ```
-     */
-    transcribeBatch(audio: Buffer): Promise<STTResult>;
-}
-
-/**
- * @voice-kit/core — Hinglish language switch detector
- *
- * Detects mid-sentence Hindi↔English (Hinglish) code-switching in realtime STT output.
- * Pure algorithmic detection — no external API calls, no latency overhead.
- *
- * Detection signals:
- *   1. Devanagari Unicode range (U+0900–U+097F) for Hindi
- *   2. Latin character runs for English
- *   3. Common Hinglish transition patterns (e.g. "main think karta hun")
- *   4. Script boundary crossing mid-sentence
- */
-
-type LanguageCode = 'hi-IN' | 'en-IN' | 'unknown';
-interface LanguageSwitchEvent {
-    /** Language switched from. */
-    from: LanguageCode;
-    /** Language switched to. */
-    to: LanguageCode;
-    /** Position in transcript where switch occurred (word index). */
-    position: number;
-    /** Confidence of the detection 0–1. */
-    confidence: number;
-    /** Full transcript at time of detection. */
-    transcript: string;
-    /** Timestamp of detection. */
-    detectedAt: Date;
-}
-type LanguageDetectorEventMap = {
-    'language.switched': [LanguageSwitchEvent];
-};
-/**
- * Hinglish language switch detector.
- *
- * Analyzes STT transcripts word-by-word in realtime.
- * Emits 'language.switched' events when a significant script change is detected.
- *
- * @example
- * ```ts
- * const detector = new LanguageSwitchDetector('en-IN')
- * detector.on('language.switched', ({ from, to, transcript }) => {
- *   console.log(`Language switched: ${from} → ${to} in: "${transcript}"`)
- * })
- *
- * // Call on every STT final result
- * detector.analyze('main yeh kaam kal karonga I promise')
- * ```
- */
-declare class LanguageSwitchDetector extends EventEmitter<LanguageDetectorEventMap> {
-    private currentLanguage;
-    private readonly primaryLanguage;
-    /** Rolling window of recent language classifications for smoothing. */
-    private recentClassifications;
-    private readonly windowSize;
-    constructor(primaryLanguage?: LanguageCode);
-    /**
-     * Analyze a transcript for language switches.
-     * Should be called on every STT final result.
-     *
-     * @param transcript  The transcribed text to analyze
-     * @returns           Detected language of the transcript
-     */
-    analyze(transcript: string): LanguageCode;
-    /**
-     * Analyze a transcript and return per-word language classification.
-     * Useful for word-level Hinglish mixing visualization.
-     *
-     * @param transcript  Text to analyze
-     * @returns           Array of { word, language } pairs
-     */
-    analyzeWords(transcript: string): Array<{
-        word: string;
-        language: LanguageCode;
-    }>;
-    /** Reset to primary language (e.g., on new call). */
-    reset(): void;
-    /** Current detected language. */
-    get language(): LanguageCode;
-    private tokenize;
-    private classifyWord;
-    private classifySegment;
-    private computeConfidence;
-    private smoothedLanguage;
-}
-/**
- * Detect whether a transcript contains mixed Hindi+English (Hinglish).
- * Stateless convenience function for one-shot analysis.
- *
- * @param transcript  Text to analyze
- * @returns           True if both Devanagari and Latin characters are present
- *
- * @example
- * ```ts
- * isHinglish('main kal office jaaunga') // true
- * isHinglish('I will go to the office')  // false
- * isHinglish('मैं कल ऑफिस जाऊंगा')       // false (pure Hindi)
- * ```
- */
-declare function isInglish(transcript: string): boolean;
-
-/**
- * @voice-kit/core — STT factory
- *
- * createSTT() is the ONLY public API for speech-to-text.
- * Never instantiate provider classes directly.
- */
-
-/**
- * Create an STT provider instance. This is the ONLY public API for STT.
- *
- * Provider selection guide:
- * - 'deepgram'   → Default. Realtime streaming, best latency, supports en-IN + Indic
- * - 'sarvam'     → Best accuracy for pure Indic languages (hi-IN, ta-IN, kn-IN, te-IN, mr-IN)
- * - 'assemblyai' → Best for long-form recordings (post-call analysis)
- * - 'whisper'    → Fallback batch transcription, broad language support
- *
- * @example
- * ```ts
- * // Realtime English (India) — default
- * const stt = createSTT('deepgram', { language: 'en-IN' })
- *
- * // Realtime Hindi
- * const stt = createSTT('deepgram', { language: 'hi-IN' })
- *
- * // Best Indic accuracy
- * const stt = createSTT('sarvam', { language: 'ta-IN' })
- *
- * // Post-call recording
- * const stt = createSTT('assemblyai', { wordTimestamps: true })
- * ```
- */
-declare function createSTT(provider: 'deepgram' | 'whisper' | 'assemblyai' | 'sarvam', config?: STTConfig): STTProvider;
-
-/**
- * @voice-kit/core — OpenAI Whisper STT Provider (batch fallback)
- *
- * Uses @ai-sdk/openai for batch transcription. Does not support streaming.
- * Use as fallback for long-form audio or when Deepgram is unavailable.
- */
-
-/**
- * OpenAI Whisper STT provider. Batch-only — does not support streaming.
- * @internal — obtained via createSTT('whisper', config)
- */
-declare class WhisperSTTProvider implements STTProvider {
-    readonly name = "whisper";
-    readonly supportsStreaming = false;
-    readonly supportedLanguages: string[];
-    private readonly config;
-    constructor(config: STTConfig);
-    /**
-     * Streaming not supported by Whisper. Collects all audio then transcribes.
-     * For realtime use, use createSTT('deepgram') instead.
-     */
-    transcribeStream(audio: AsyncIterable<Buffer>): AsyncIterable<STTResult>;
-    /**
-     * Transcribe a complete audio buffer via Whisper.
-     *
-     * @param audio  WAV or PCM buffer
-     */
-    transcribeBatch(audio: Buffer): Promise<STTResult>;
-}
-
-export { AssemblyAISTTProvider, DeepgramSTTProvider, type LanguageCode, LanguageSwitchDetector, type LanguageSwitchEvent, SarvamSTTProvider, WhisperSTTProvider, createSTT, isInglish };