@juspay/neurolink 9.61.2 → 9.62.0

package/dist/lib/types/tts.d.ts

@@ -6,9 +6,13 @@
  * @module types/ttsTypes
  */
 /**
- * Supported audio formats for TTS output
+ * Supported audio formats for TTS output, STT input, and Realtime PCM streams.
+ *
+ * `pcm16` is included for the OpenAI Realtime PCM16 output stream — the chunk
+ * is raw PCM, not a RIFF/WAV-headered file. Consumers must not pass `pcm16`
+ * bytes to a WAV duration parser.
  */
-export type AudioFormat = "mp3" | "wav" | "ogg" | "opus";
+export type TTSAudioFormat = "mp3" | "wav" | "ogg" | "opus" | "m4a" | "flac" | "webm" | "mp4" | "mpeg" | "mpga" | "pcm16";
 /**
  * TTS quality settings
  */
@@ -51,7 +55,7 @@ export type TTSOptions = {
     /** Voice identifier (e.g., "en-US-Neural2-C") */
     voice?: string;
     /** Audio format (default: mp3) */
-    format?: AudioFormat;
+    format?: TTSAudioFormat;
     /** Speaking rate 0.25-4.0 (default: 1.0) */
     speed?: number;
     /** Voice pitch adjustment -20.0 to 20.0 semitones (default: 0.0) */
@@ -64,6 +68,8 @@ export type TTSOptions = {
     output?: string;
     /** Auto-play audio after generation (default: false) */
     play?: boolean;
+    /** Override TTS provider (e.g., "elevenlabs", "openai-tts", "azure-tts") */
+    provider?: string;
 };
 /**
  * TTS audio result returned from generation
@@ -72,7 +78,7 @@ export type TTSResult = {
     /** Audio data as Buffer */
     buffer: Buffer;
     /** Audio format */
-    format: AudioFormat;
+    format: TTSAudioFormat;
     /** Audio file size in bytes */
     size: number;
     /** Duration in seconds (if available) */
@@ -105,9 +111,15 @@ export type AudioSaveResult = {
     error?: string;
 };
 /** Allowed TTS voice types */
-export type VoiceType = "standard" | "wavenet" | "neural" | "chirp" | "unknown";
+export type TTSVoiceType = "standard" | "wavenet" | "neural" | "chirp" | "unknown";
 /** Allowed genders for TTS voices */
-export type Gender = "male" | "female" | "neutral";
+export type TTSGender = "male" | "female" | "neutral";
+/** @deprecated Use `TTSAudioFormat` instead. */
+export type AudioFormat = TTSAudioFormat;
+/** @deprecated Use `TTSVoiceType` instead. */
+export type VoiceType = TTSVoiceType;
+/** @deprecated Use `TTSGender` instead. */
+export type Gender = TTSGender;
 /**
  * TTS voice information
  */
@@ -120,17 +132,17 @@ export type TTSVoice = {
     languageCode: string;
     /** All supported language codes */
     languageCodes: string[];
-    /** Gender */
-    gender: Gender;
+    /** TTSGender */
+    gender: TTSGender;
     /** Voice type */
-    type?: VoiceType;
+    type?: TTSVoiceType;
     /** Voice description (optional) */
     description?: string;
     /** Natural sample rate in Hz (optional) */
     naturalSampleRateHertz?: number;
 };
 /** Valid audio formats as an array for runtime validation */
-export declare const VALID_AUDIO_FORMATS: readonly AudioFormat[];
+export declare const VALID_AUDIO_FORMATS: readonly TTSAudioFormat[];
 /** Valid TTS quality levels as an array for runtime validation */
 export declare const VALID_TTS_QUALITIES: readonly TTSQuality[];
 /** Valid Google TTS audio formats */
@@ -153,7 +165,7 @@ export type TTSChunk = {
     /** Audio data chunk as Buffer */
     data: Buffer;
     /** Audio format of this chunk */
-    format: AudioFormat;
+    format: TTSAudioFormat;
     /** Chunk sequence number (0-indexed) */
     index: number;
     /** Whether this is the final audio chunk */

package/dist/lib/types/tts.js

@@ -11,6 +11,13 @@ export const VALID_AUDIO_FORMATS = [
     "wav",
     "ogg",
     "opus",
+    "m4a",
+    "flac",
+    "webm",
+    "mp4",
+    "mpeg",
+    "mpga",
+    "pcm16",
 ];
 /** Valid TTS quality levels as an array for runtime validation */
 export const VALID_TTS_QUALITIES = ["standard", "hd"];

package/dist/lib/types/voice.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Voice and Speech Type Definitions for NeuroLink
+ *
+ * Core voice types: capabilities, provider config, audio utilities,
+ * events, and provider abstractions.
+ *
+ * STT types are in ./stt.ts
+ * Realtime types are in ./realtime.ts
+ * TTS types are in ./tts.ts
+ *
+ * @module types/voice
+ */
+export * from "./tts.js";
+export * from "./stt.js";
+export * from "./realtime.js";
+import type { TTSAudioFormat, TTSOptions, TTSResult, TTSVoice } from "./tts.js";
+import type { TTSHandler } from "./common.js";
+import type { STTResult, STTHandler } from "./stt.js";
+import type { RealtimeHandler } from "./realtime.js";
+/**
+ * Voice capability types supported by providers
+ */
+export type VoiceCapability = "tts" | "stt" | "realtime" | "streaming";
+/**
+ * Voice provider types
+ */
+export type VoiceProviderType = "tts" | "stt" | "realtime";
+/**
+ * Voice provider name union type
+ */
+export type VoiceProviderName = "google-tts" | "elevenlabs" | "openai-tts" | "azure-tts" | "sarvam" | "murf" | "playai" | "speechify" | "cartesia" | "deepgram" | "gladia" | "whisper" | "assemblyai" | "google-stt" | "azure-stt" | "openai-realtime" | "gemini-live";
+/**
+ * Base voice provider configuration
+ */
+export type VoiceProviderConfig = {
+    /** Provider identifier */
+    name: string;
+    /** API key or credentials */
+    apiKey?: string;
+    /** Custom endpoint URL */
+    baseUrl?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Maximum retries for failed requests */
+    maxRetries?: number;
+    /** Provider-specific options */
+    options?: Record<string, unknown>;
+};
+/**
+ * Audio format details
+ */
+export type AudioFormatDetails = {
+    /** Format name */
+    format: TTSAudioFormat;
+    /** MIME type */
+    mimeType: string;
+    /** File extension */
+    extension: string;
+    /** Whether format supports streaming */
+    supportsStreaming: boolean;
+    /** Typical sample rates */
+    sampleRates: number[];
+    /** Bit depths */
+    bitDepths: number[];
+};
+/**
+ * Audio conversion options
+ */
+export type AudioConversionOptions = {
+    /** Target format */
+    targetFormat: TTSAudioFormat;
+    /** Target sample rate */
+    sampleRate?: number;
+    /** Target bit depth */
+    bitDepth?: number;
+    /** Number of channels */
+    channels?: number;
+    /** Normalize audio level */
+    normalize?: boolean;
+};
+/**
+ * Audio stream chunk for streaming operations
+ */
+export type AudioStreamChunk = {
+    /** Audio data */
+    data: Buffer;
+    /** Chunk index */
+    index: number;
+    /** Whether this is the final chunk */
+    isFinal: boolean;
+    /** Audio format */
+    format: TTSAudioFormat;
+    /** Sample rate */
+    sampleRate: number;
+    /** Timestamp offset in milliseconds */
+    timestampMs: number;
+    /** Duration of this chunk in milliseconds */
+    durationMs: number;
+};
+/**
+ * Voice event types for event-driven architectures
+ */
+export type VoiceEventType = "synthesis.started" | "synthesis.progress" | "synthesis.completed" | "synthesis.error" | "transcription.started" | "transcription.partial" | "transcription.completed" | "transcription.error" | "realtime.connected" | "realtime.audio.received" | "realtime.text.received" | "realtime.disconnected" | "realtime.error";
+/**
+ * Voice event for event-driven operations
+ */
+export type VoiceEvent<T = unknown> = {
+    type: VoiceEventType;
+    timestamp: Date;
+    provider: VoiceProviderName;
+    data: T;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Voice operation result union
+ */
+export type VoiceResult = TTSResult | STTResult;
+/**
+ * Voice conversation turn
+ */
+export type VoiceTurn = {
+    role: "user" | "assistant";
+    text: string;
+    audio?: Buffer;
+    timestamp: Date;
+    metadata?: {
+        duration?: number;
+        confidence?: number;
+        language?: string;
+        provider?: string;
+        voice?: string;
+        [key: string]: unknown;
+    };
+};
+/**
+ * TTS-capable voice provider type
+ */
+export type TTSProvider = {
+    /**
+     * Synthesize text to speech
+     */
+    synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
+    /**
+     * Stream synthesized audio chunks
+     */
+    synthesizeStream?(text: string, options: TTSOptions): AsyncIterable<TTSStreamChunk>;
+    /**
+     * Get available voices
+     */
+    getVoices(languageCode?: string): Promise<TTSVoice[]>;
+    /**
+     * Maximum text length supported
+     */
+    readonly maxTextLength: number;
+};
+/**
+ * TTS stream chunk for streaming synthesis
+ */
+export type TTSStreamChunk = {
+    /** Audio data chunk */
+    data: Buffer;
+    /** Chunk sequence number */
+    index: number;
+    /** Whether this is the final chunk */
+    isFinal: boolean;
+    /** Audio format */
+    format: string;
+    /** Sample rate */
+    sampleRate?: number;
+    /** Timestamp offset in audio (milliseconds) */
+    timestampMs?: number;
+};
+/**
+ * Voice error codes (general)
+ */
+export declare const VOICE_ERROR_CODES: {
+    readonly PROVIDER_NOT_FOUND: "VOICE_PROVIDER_NOT_FOUND";
+    readonly INVALID_CONFIGURATION: "VOICE_INVALID_CONFIGURATION";
+    readonly INITIALIZATION_FAILED: "VOICE_INITIALIZATION_FAILED";
+    readonly OPERATION_CANCELLED: "VOICE_OPERATION_CANCELLED";
+    readonly PROVIDER_NOT_CONFIGURED: "VOICE_PROVIDER_NOT_CONFIGURED";
+    readonly PROVIDER_NOT_SUPPORTED: "VOICE_PROVIDER_NOT_SUPPORTED";
+    readonly FEATURE_NOT_SUPPORTED: "VOICE_FEATURE_NOT_SUPPORTED";
+    readonly TTS_EMPTY_TEXT: "VOICE_TTS_EMPTY_TEXT";
+    readonly TTS_TEXT_TOO_LONG: "VOICE_TTS_TEXT_TOO_LONG";
+    readonly TTS_SYNTHESIS_FAILED: "VOICE_TTS_SYNTHESIS_FAILED";
+    readonly STT_EMPTY_AUDIO: "VOICE_STT_EMPTY_AUDIO";
+    readonly STT_INVALID_FORMAT: "VOICE_STT_INVALID_FORMAT";
+    readonly STT_TRANSCRIPTION_FAILED: "VOICE_STT_TRANSCRIPTION_FAILED";
+    readonly REALTIME_CONNECTION_FAILED: "VOICE_REALTIME_CONNECTION_FAILED";
+    readonly REALTIME_SESSION_ERROR: "VOICE_REALTIME_SESSION_ERROR";
+    readonly NETWORK_ERROR: "VOICE_NETWORK_ERROR";
+    readonly TIMEOUT: "VOICE_TIMEOUT";
+};
+/**
+ * Supported audio formats with details
+ */
+export declare const AUDIO_FORMAT_DETAILS: Partial<Record<TTSAudioFormat, AudioFormatDetails>>;
+import type { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
+export type VoiceErrorOptions = {
+    code: string;
+    message: string;
+    category?: ErrorCategory;
+    severity?: ErrorSeverity;
+    retriable?: boolean;
+    context?: Record<string, unknown>;
+    originalError?: Error;
+    provider?: string;
+};
+export type AudioMetadata = {
+    format: TTSAudioFormat;
+    duration: number;
+    sampleRate: number;
+    channels: number;
+    bitDepth: number;
+    samples: number;
+    size: number;
+};
+export type StreamHandlerConfig = {
+    chunkDurationMs?: number;
+    sampleRate?: number;
+    bytesPerSample?: number;
+    format?: TTSAudioFormat;
+    highWaterMark?: number;
+    bufferTimeoutMs?: number;
+};
+export type StreamEvents = {
+    chunk: (chunk: AudioStreamChunk) => void;
+    end: () => void;
+    error: (error: Error) => void;
+    drain: () => void;
+    pause: () => void;
+    resume: () => void;
+};
+export type VoiceHandler = TTSHandler | STTHandler | RealtimeHandler;
+export type AzureTTSOptions = TTSOptions & {
+    useSSML?: boolean;
+    ssmlTemplate?: string;
+    outputFormat?: string;
+    wordBoundary?: boolean;
+    /**
+     * Pass `text` through as raw SSML when it begins with `<speak`.
+     *
+     * **Security:** raw SSML can change voice, embed external content, or
+     * inject markup. Only enable when `text` originates from a TRUSTED source
+     * (your own server-built template, not end-user input). When this flag
+     * is false (default), all input — including text starting with `<speak`
+     * — is XML-escaped, preventing SSML injection.
+     *
+     * @default false
+     */
+    allowRawSSML?: boolean;
+};
+export type ElevenLabsModel = "eleven_multilingual_v2" | "eleven_turbo_v2_5" | "eleven_turbo_v2" | "eleven_monolingual_v1";
+export type ElevenLabsTTSOptions = TTSOptions & {
+    model?: ElevenLabsModel;
+    stability?: number;
+    similarityBoost?: number;
+    style?: number;
+    useSpeakerBoost?: boolean;
+};
+export type GoogleVoiceType = "Standard" | "WaveNet" | "Neural2" | "Studio" | "Polyglot";
+export type GoogleTTSOptions = TTSOptions & {
+    voiceType?: GoogleVoiceType;
+    sampleRateHertz?: number;
+    effectsProfileId?: string[];
+};
+export type OpenAIVoice = "alloy" | "echo" | "fable" | "onyx" | "nova" | "shimmer";
+export type OpenAITTSModel = "tts-1" | "tts-1-hd";
+export type OpenAITTSOptions = TTSOptions & {
+    model?: OpenAITTSModel;
+};

package/dist/lib/types/voice.js

@@ -0,0 +1,137 @@
+/**
+ * Voice and Speech Type Definitions for NeuroLink
+ *
+ * Core voice types: capabilities, provider config, audio utilities,
+ * events, and provider abstractions.
+ *
+ * STT types are in ./stt.ts
+ * Realtime types are in ./realtime.ts
+ * TTS types are in ./tts.ts
+ *
+ * @module types/voice
+ */
+// Re-export all TTS types
+export * from "./tts.js";
+// Re-export all STT types
+export * from "./stt.js";
+// Re-export all Realtime types
+export * from "./realtime.js";
+// ============================================================================
+// ERROR CODES
+// ============================================================================
+/**
+ * Voice error codes (general)
+ */
+export const VOICE_ERROR_CODES = {
+    PROVIDER_NOT_FOUND: "VOICE_PROVIDER_NOT_FOUND",
+    INVALID_CONFIGURATION: "VOICE_INVALID_CONFIGURATION",
+    INITIALIZATION_FAILED: "VOICE_INITIALIZATION_FAILED",
+    OPERATION_CANCELLED: "VOICE_OPERATION_CANCELLED",
+    // General
+    PROVIDER_NOT_CONFIGURED: "VOICE_PROVIDER_NOT_CONFIGURED",
+    PROVIDER_NOT_SUPPORTED: "VOICE_PROVIDER_NOT_SUPPORTED",
+    FEATURE_NOT_SUPPORTED: "VOICE_FEATURE_NOT_SUPPORTED",
+    // TTS specific
+    TTS_EMPTY_TEXT: "VOICE_TTS_EMPTY_TEXT",
+    TTS_TEXT_TOO_LONG: "VOICE_TTS_TEXT_TOO_LONG",
+    TTS_SYNTHESIS_FAILED: "VOICE_TTS_SYNTHESIS_FAILED",
+    // STT specific
+    STT_EMPTY_AUDIO: "VOICE_STT_EMPTY_AUDIO",
+    STT_INVALID_FORMAT: "VOICE_STT_INVALID_FORMAT",
+    STT_TRANSCRIPTION_FAILED: "VOICE_STT_TRANSCRIPTION_FAILED",
+    // Realtime specific
+    REALTIME_CONNECTION_FAILED: "VOICE_REALTIME_CONNECTION_FAILED",
+    REALTIME_SESSION_ERROR: "VOICE_REALTIME_SESSION_ERROR",
+    // Network
+    NETWORK_ERROR: "VOICE_NETWORK_ERROR",
+    TIMEOUT: "VOICE_TIMEOUT",
+};
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+/**
+ * Supported audio formats with details
+ */
+export const AUDIO_FORMAT_DETAILS = {
+    mp3: {
+        format: "mp3",
+        mimeType: "audio/mpeg",
+        extension: ".mp3",
+        supportsStreaming: true,
+        sampleRates: [8000, 16000, 22050, 24000, 44100, 48000],
+        bitDepths: [16],
+    },
+    wav: {
+        format: "wav",
+        mimeType: "audio/wav",
+        extension: ".wav",
+        supportsStreaming: false,
+        sampleRates: [8000, 16000, 22050, 24000, 44100, 48000],
+        bitDepths: [8, 16, 24, 32],
+    },
+    ogg: {
+        format: "ogg",
+        mimeType: "audio/ogg",
+        extension: ".ogg",
+        supportsStreaming: true,
+        sampleRates: [8000, 16000, 22050, 24000, 44100, 48000],
+        bitDepths: [16],
+    },
+    opus: {
+        format: "opus",
+        mimeType: "audio/opus",
+        extension: ".opus",
+        supportsStreaming: true,
+        sampleRates: [8000, 12000, 16000, 24000, 48000],
+        bitDepths: [16],
+    },
+    m4a: {
+        format: "m4a",
+        mimeType: "audio/mp4",
+        extension: ".m4a",
+        supportsStreaming: false,
+        sampleRates: [44100, 48000],
+        bitDepths: [16],
+    },
+    flac: {
+        format: "flac",
+        mimeType: "audio/flac",
+        extension: ".flac",
+        supportsStreaming: false,
+        sampleRates: [44100, 48000, 96000],
+        bitDepths: [16, 24],
+    },
+    webm: {
+        format: "webm",
+        mimeType: "audio/webm",
+        extension: ".webm",
+        supportsStreaming: true,
+        sampleRates: [44100, 48000],
+        bitDepths: [16],
+    },
+    mp4: {
+        format: "mp4",
+        mimeType: "audio/mp4",
+        extension: ".mp4",
+        supportsStreaming: false,
+        sampleRates: [44100, 48000],
+        bitDepths: [16],
+    },
+    mpeg: {
+        format: "mpeg",
+        mimeType: "audio/mpeg",
+        extension: ".mpeg",
+        supportsStreaming: true,
+        sampleRates: [8000, 16000, 22050, 24000, 44100, 48000],
+        bitDepths: [16],
+    },
+    mpga: {
+        format: "mpga",
+        mimeType: "audio/mpeg",
+        extension: ".mpga",
+        supportsStreaming: true,
+        sampleRates: [8000, 16000, 22050, 24000, 44100, 48000],
+        bitDepths: [16],
+    },
+};
+//# sourceMappingURL=voice.js.map

package/dist/lib/utils/audioFormatDetector.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared utility: infer a `TTSAudioFormat` from a file path.
+ *
+ * Used by the CLI generate/stream handlers (m2) to set `stt.format` so
+ * `STTProcessor.transcribe()` can fail fast on incompatible provider/format
+ * combinations (e.g. MP3 to azure-stt). Pulled into a single helper to
+ * avoid duplicating the 11-element format list across two CLI handlers.
+ */
+import type { TTSAudioFormat } from "../types/index.js";
+/**
+ * Returns the `TTSAudioFormat` that matches the file extension of `path`,
+ * or `undefined` when the path is missing or its extension isn't a known
+ * audio format. The check is case-insensitive.
+ */
+export declare function inferAudioFormatFromPath(path: string | undefined): TTSAudioFormat | undefined;

package/dist/lib/utils/audioFormatDetector.js

@@ -0,0 +1,34 @@
+/**
+ * Shared utility: infer a `TTSAudioFormat` from a file path.
+ *
+ * Used by the CLI generate/stream handlers (m2) to set `stt.format` so
+ * `STTProcessor.transcribe()` can fail fast on incompatible provider/format
+ * combinations (e.g. MP3 to azure-stt). Pulled into a single helper to
+ * avoid duplicating the 11-element format list across two CLI handlers.
+ */
+const VALID_FORMATS = [
+    "mp3",
+    "wav",
+    "ogg",
+    "opus",
+    "m4a",
+    "flac",
+    "webm",
+    "mp4",
+    "mpeg",
+    "mpga",
+    "pcm16",
+];
+/**
+ * Returns the `TTSAudioFormat` that matches the file extension of `path`,
+ * or `undefined` when the path is missing or its extension isn't a known
+ * audio format. The check is case-insensitive.
+ */
+export function inferAudioFormatFromPath(path) {
+    if (!path) {
+        return undefined;
+    }
+    const ext = path.toLowerCase().split(".").pop();
+    return ext && VALID_FORMATS.includes(ext) ? ext : undefined;
+}
+//# sourceMappingURL=audioFormatDetector.js.map

package/dist/lib/utils/sttProcessor.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Speech-to-Text (STT) Processing Utility
+ *
+ * Central orchestrator for all STT operations across providers.
+ * Manages provider-specific STT handlers and audio transcription.
+ *
+ * @module utils/sttProcessor
+ */
+import type { STTOptions, STTResult, STTHandler } from "../types/index.js";
+/**
+ * STT processor class for orchestrating speech-to-text operations
+ *
+ * Follows the same pattern as TTSProcessor, CSVProcessor, ImageProcessor, and PDFProcessor.
+ * Provides a unified interface for STT transcription across multiple providers.
+ *
+ * @example
+ * ```typescript
+ * // Register a handler
+ * STTProcessor.registerHandler('whisper', whisperHandler);
+ *
+ * // Check if provider is supported
+ * if (STTProcessor.supports('whisper')) {
+ *   // Provider is registered
+ * }
+ * ```
+ */
+export declare class STTProcessor {
+    /**
+     * Handler registry mapping provider names to STT handlers
+     * Uses Map for O(1) lookups and better type safety
+     *
+     * @private
+     */
+    private static readonly handlers;
+    /**
+     * Default maximum audio duration for STT transcription (in seconds)
+     *
+     * Providers can override this value by specifying the `maxAudioDuration` property
+     * in their respective `STTHandler` implementation. If not specified, this default
+     * value will be used (5 minutes).
+     *
+     * @private
+     */
+    private static readonly DEFAULT_MAX_AUDIO_DURATION;
+    /**
+     * Register an STT handler for a specific provider
+     *
+     * Allows providers to register their STT implementation at runtime.
+     *
+     * @param providerName - Provider identifier (e.g., 'whisper', 'deepgram')
+     * @param handler - STT handler implementation
+     *
+     * @example
+     * ```typescript
+     * const whisperHandler: STTHandler = {
+     *   transcribe: async (audio, options) => { ... },
+     *   getSupportedFormats: () => ["mp3", "wav"],
+     *   isConfigured: () => true
+     * };
+     *
+     * STTProcessor.registerHandler('whisper', whisperHandler);
+     * ```
+     */
+    static registerHandler(providerName: string, handler: STTHandler): void;
+    /**
+     * Get a registered STT handler by provider name
+     *
+     * @private
+     * @param providerName - Provider identifier
+     * @returns Handler instance or undefined if not registered
+     */
+    private static getHandler;
+    /**
+     * Check if a provider is supported (has a registered STT handler)
+     *
+     * @param providerName - Provider identifier
+     * @returns True if handler is registered
+     *
+     * @example
+     * ```typescript
+     * if (STTProcessor.supports('whisper')) {
+     *   console.log('Whisper STT is supported');
+     * }
+     * ```
+     */
+    static supports(providerName: string): boolean;
+    /**
+     * Transcribe audio to text using a registered STT provider
+     *
+     * Orchestrates the speech-to-text transcription process:
+     * 1. Validates audio input (non-empty)
+     * 2. Looks up the provider handler
+     * 3. Verifies provider configuration
+     * 4. Delegates transcription to the provider
+     * 5. Enriches result with provider metadata
+     *
+     * @param audio - Audio data as Buffer or ArrayBuffer
+     * @param provider - Provider identifier
+     * @param options - STT configuration options
+     * @returns Transcription result with text and metadata
+     * @throws STTError if validation fails or provider not supported/configured
+     *
+     * @example
+     * ```typescript
+     * const result = await STTProcessor.transcribe(audioBuffer, "whisper", {
+     *   language: "en-US",
+     *   punctuation: true,
+     * });
+     *
+     * console.log(`Transcription: ${result.text}`);
+     * console.log(`Confidence: ${result.confidence}`);
+     * ```
+     */
+    static transcribe(audio: Buffer | ArrayBuffer, provider: string, options: STTOptions): Promise<STTResult>;
+}