/**
 * Text-to-Speech (TTS) Processing Utility
 *
 * Central orchestrator for all TTS operations across providers.
 * Manages provider-specific TTS handlers and audio generation.
 *
 * @module utils/ttsProcessor
 */
import type { TTSOptions, TTSResult, TTSVoice } from "../types/ttsTypes.js";
import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
import { NeuroLinkError } from "./errorHandling.js";
/**
 * TTS-specific error codes
 */
export declare const TTS_ERROR_CODES: {
    readonly EMPTY_TEXT: "TTS_EMPTY_TEXT";
    readonly TEXT_TOO_LONG: "TTS_TEXT_TOO_LONG";
    readonly PROVIDER_NOT_SUPPORTED: "TTS_PROVIDER_NOT_SUPPORTED";
    readonly PROVIDER_NOT_CONFIGURED: "TTS_PROVIDER_NOT_CONFIGURED";
    readonly SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED";
    readonly INVALID_INPUT: "TTS_INVALID_INPUT";
};
/**
 * TTS Error class for text-to-speech specific errors
 */
export declare class TTSError extends NeuroLinkError {
    constructor(options: {
        code: string;
        message: string;
        category?: ErrorCategory;
        severity?: ErrorSeverity;
        retriable?: boolean;
        context?: Record<string, unknown>;
        originalError?: Error;
    });
}
/**
 * TTS Handler interface for provider-specific implementations
 *
 * Each provider (Google AI, OpenAI, etc.) implements this interface
 * to provide TTS generation capabilities using their respective APIs.
 *
 * **Timeout Handling:**
 * Implementations MUST handle their own timeouts for the `synthesize()` method.
 * Recommended timeout: 30 seconds. Implementations should use `withTimeout()` utility
 * or provider-specific timeout mechanisms (e.g., Google Cloud client timeout).
 *
 * **Error Handling:**
 * Implementations should throw TTSError for all failures, including timeouts.
 * Use appropriate error codes from TTS_ERROR_CODES.
 *
 * @example
 * ```typescript
 * class MyTTSHandler implements TTSHandler {
 *   async synthesize(text: string, options: TTSOptions): Promise<TTSResult> {
 *     // REQUIRED: Implement timeout handling
 *     return await withTimeout(
 *       this.actualSynthesis(text, options),
 *       30000, // 30 second timeout
 *       'TTS synthesis timed out'
 *     );
 *   }
 *
 *   isConfigured(): boolean {
 *     return !!process.env.MY_TTS_API_KEY;
 *   }
 * }
 * ```
 */
export type TTSHandler = {
    /**
     * Generate audio from text using provider-specific TTS API
     *
     * **IMPORTANT: Timeout Responsibility**
     * Implementations MUST enforce their own timeouts (recommended: 30 seconds).
     * Use the `withTimeout()` utility or provider-specific timeout mechanisms.
     *
     * @param text - Text to convert to speech (pre-validated, non-empty, within length limits)
     * @param options - TTS configuration options (voice, format, speed, etc.)
     * @returns Audio buffer with metadata
     * @throws {TTSError} On synthesis failure, timeout, or configuration issues
     */
    synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
    /**
     * Get available voices for the provider
     *
     * @param languageCode - Optional language filter (e.g., "en-US")
     * @returns List of available voices
     */
    getVoices?(languageCode?: string): Promise<TTSVoice[]>;
    /**
     * Validate that the provider is properly configured
     *
     * @returns True if provider can generate TTS
     */
    isConfigured(): boolean;
    /**
     * Maximum text length supported by this provider (in bytes)
     * Different providers have different limits
     *
     * @default 3000 if not specified
     */
    maxTextLength?: number;
};
/**
 * TTS processor class for orchestrating text-to-speech operations
 *
 * Follows the same pattern as CSVProcessor, ImageProcessor, and PDFProcessor.
 * Provides a unified interface for TTS generation across multiple providers.
 *
 * @example
 * ```typescript
 * // Register a handler
 * TTSProcessor.registerHandler('google-ai', googleAIHandler);
 *
 * // Check if provider is supported
 * if (TTSProcessor.supports('google-ai')) {
 *   // Provider is registered
 * }
 * ```
 */
export declare class TTSProcessor {
    /**
     * Handler registry mapping provider names to TTS handlers
     * Uses Map for O(1) lookups and better type safety
     *
     * @private
     */
    private static readonly handlers;
    /**
     * Default maximum text length for TTS synthesis (in bytes)
     *
     * Providers can override this value by specifying the `maxTextLength` property
     * in their respective `TTSHandler` implementation. If not specified, this default
     * value will be used.
     *
     * @private
     */
    private static readonly DEFAULT_MAX_TEXT_LENGTH;
    /**
     * Register a TTS handler for a specific provider
     *
     * Allows providers to register their TTS implementation at runtime.
     *
     * @param providerName - Provider identifier (e.g., 'google-ai', 'openai')
     * @param handler - TTS handler implementation
     *
     * @example
     * ```typescript
     * const googleHandler: TTSHandler = {
     *   synthesize: async (text, options) => { ... },
     *   getVoices: async (languageCode) => { ... },
     *   isConfigured: () => true
     * };
     *
     * TTSProcessor.registerHandler('google-ai', googleHandler);
     * ```
     */
    static registerHandler(providerName: string, handler: TTSHandler): void;
    /**
     * Get a registered TTS 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 TTS handler)
     *
     * @param providerName - Provider identifier
     * @returns True if handler is registered
     *
     * @example
     * ```typescript
     * if (TTSProcessor.supports('google-ai')) {
     *   console.log('Google AI TTS is supported');
     * }
     * ```
     */
    static supports(providerName: string): boolean;
    /**
     * Synthesize speech from text using a registered TTS provider
     *
     * Orchestrates the text-to-speech generation process:
     * 1. Validates input text (not empty, within length limits)
     * 2. Looks up the provider handler
     * 3. Verifies provider configuration
     * 4. Delegates synthesis to the provider (timeout handled by provider)
     * 5. Enriches result with metadata
     *
     * **Timeout Handling:**
     * Timeouts are enforced by individual provider implementations (see TTSHandler interface).
     * Providers typically use 30-second timeouts via `withTimeout()` utility or
     * provider-specific timeout mechanisms (e.g., Google Cloud client timeout).
     *
     * @param text - Text to convert to speech
     * @param provider - Provider identifier
     * @param options - TTS configuration options
     * @returns Audio result with buffer and metadata
     * @throws TTSError if validation fails or provider not supported/configured
     *
     * @example
     * ```typescript
     * const result = await TTSProcessor.synthesize("Hello, world!", "google-ai", {
     *   voice: "en-US-Neural2-C",
     *   format: "mp3",
     *   speed: 1.0
     * });
     *
     * console.log(`Generated ${result.size} bytes of ${result.format} audio`);
     * // Save to file or play the audio buffer
     * ```
     */
    static synthesize(text: string, provider: string, options: TTSOptions): Promise<TTSResult>;
}
