@juspay/neurolink/dist/utils/sttProcessor.d.ts

The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002

/**
 * 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 { STTCredentials, 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
     *
     * @private
     */
    private static readonly registry;
    /**
     * 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.
     *
     * Exposed publicly so module-level auto-registration code can reuse an
     * already-registered primary handler when backfilling its aliases.
     *
     * @param providerName - Provider identifier
     * @returns Handler instance or undefined if not registered
     */
    static getHandler(providerName: string): STTHandler | undefined;
    /**
     * The handler a call should use. A credentials slice for a shipped
     * provider builds a fresh handler for this call; otherwise the registered
     * one is used, and a shipped provider that was never registered (its key
     * arrived after registration, or it is the local engine on a registry that
     * was cleared) is built from the environment rather than reported as
     * unsupported. Names that are neither registered nor shipped resolve to
     * `undefined`.
     *
     * The handler classes are loaded lazily: `voice/index.ts` imports this
     * module, so a static import back would be a cycle.
     */
    static resolveHandler(provider: string, credentials?: STTCredentials): Promise<STTHandler | undefined>;
    /**
     * List the names of all registered providers.
     */
    static listProviders(): string[];
    /**
     * Removes every registered STT handler. Primarily for test isolation —
     * production code should not need to call this.
     */
    static clearHandlers(): void;
    /**
     * 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
     * @param credentials - Per-call credentials (`credentials.stt`). When it
     *   carries a slice for this provider — even an empty one — a fresh handler
     *   is built from that slice (environment as fallback) for this call alone,
     *   instead of the registry's shared instance: per-call beats instance
     *   beats environment, exactly as for text providers.
     * @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, credentials?: STTCredentials): Promise<STTResult>;
}