import type * as WS from 'ws';
import type { Cartesia } from "../../../client.mjs";
import type * as TTSAPI from "../../../resources/tts.mjs";
import { TTSEmitter } from "../../../resources/tts/internal-base.mjs";
import type * as VoicesAPI from "../../../resources/voices.mjs";
/** Common WebSocket interface shared by both the `ws` package and the browser's native WebSocket. */
interface WebSocketLike {
    readyState: number;
    send(data: string): void;
    close(code?: number, reason?: string): void;
    addEventListener(type: string, listener: (event: any) => void): void;
    removeEventListener(type: string, listener: (event: any) => void): void;
}
/**
 * Request parameters for {@link TTSWSContext.generate}
 */
export type ContextGenerateRequest = Pick<TTSAPI.GenerationRequest, 'transcript'> & Partial<Omit<TTSAPI.GenerationRequest, 'context_id' | 'transcript'>>;
/**
 * Options for creating a context, including the model, voice, and output format.
 */
export interface ContextOptions {
    /**
     * A unique identifier for the context. You can use any unique identifier, like a
     * UUID or human ID.
     */
    contextId?: string | undefined;
    /**
     * The ID of the model to use for the generation. See
     * [Models](/build-with-cartesia/tts-models) for available models.
     */
    model_id: TTSAPI.TTSModel;
    output_format: TTSAPI.RawOutputFormat;
    voice: TTSAPI.VoiceSpecifier;
    /**
     * Whether to return phoneme-level timestamps. If `false` (default), no phoneme
     * timestamps will be produced. If `true`, the server will return timestamp events
     * containing phoneme-level timing information.
     */
    add_phoneme_timestamps?: boolean | null;
    /**
     * Whether to return word-level timestamps. If `false` (default), no word
     * timestamps will be produced at all. If `true`, the server will return timestamp
     * events containing word-level timing information.
     */
    add_timestamps?: boolean | null;
    /**
     * The language that the given voice should speak the transcript in. For valid
     * options, see [Models](/build-with-cartesia/tts-models).
     */
    language?: VoicesAPI.SupportedLanguage;
    /**
     * The maximum time in milliseconds to buffer text before starting generation.
     * Values between [0, 5000]ms are supported. Defaults to 3000ms.
     *
     * When set, the model will buffer incoming text chunks until it's confident it has
     * enough context to generate high-quality speech, or the buffer delay elapses,
     * whichever comes first. Without this option set, the model will kick off
     * generations immediately, ceding control of buffering to the user.
     *
     * Use this to balance responsiveness with higher quality speech generation, which
     * often benefits from having more context.
     */
    max_buffer_delay_ms?: number | null;
    /**
     * The ID of a pronunciation dictionary to use for the generation. Pronunciation
     * dictionaries are supported by `sonic-3` models and newer.
     */
    pronunciation_dict_id?: string | null;
    /**
     * Whether to use normalized timestamps (True) or original timestamps (False).
     */
    use_normalized_timestamps?: boolean | null;
    /** Receive timeout in milliseconds. If set, receive() will throw {@link WebSocketTimeoutError} after this duration of inactivity. */
    timeout?: number | undefined;
}
interface ContextQueueEntry {
    queue: TTSAPI.WebsocketResponse[];
    resolve: (() => void) | null;
}
/**
 * A context helper for managing WebSocket conversations with automatic context_id handling.
 */
export declare class TTSWSContext {
    private _ws;
    private _options;
    private _timeout;
    readonly contextId: string;
    constructor(ws: TTSWS, options: ContextOptions);
    /**
     * Send a transcript chunk with continue: true.
     * Call this multiple times to stream transcript chunks, then call done() to finish.
     * If flush is true, sends an additional flush request after the transcript.
     */
    push(options: {
        transcript: string;
        generation_config?: TTSAPI.GenerationConfig;
        flush?: boolean;
    }): Promise<void>;
    /**
     * Signal that no more transcript chunks will be sent.
     * Sends an empty transcript with continue: false.
     */
    no_more_inputs(): Promise<void>;
    /**
     * Send a generation request without waiting for responses.
     * Use this for streaming multiple transcript chunks.
     * The context_id is automatically set.
     */
    send(request: ContextGenerateRequest): Promise<void>;
    /**
     * Flush any buffered audio for this context.
     * Sends an empty transcript with flush=true and continue=true.
     * This is always sent as a separate request per the API requirement.
     */
    flush(): Promise<void>;
    /**
     * Iterate over responses for this context.
     * Completes when a "done" event is received.
     * Events for other contexts are properly routed to their queues, not dropped.
     *
     * @param options.timeout - Override the context-level timeout (ms) for this receive call.
     */
    receive(options?: {
        timeout?: number;
    }): AsyncGenerator<TTSAPI.WebsocketResponse>;
    /**
     * Send a generation request and iterate over the responses.
     * The context_id is automatically set.
     *
     * Note: this uses TTSWS.generate()'s own EventEmitter-based collection,
     * so the per-context queue is unregistered to avoid accumulating events
     * in both places.
     */
    generate(request: ContextGenerateRequest): AsyncGenerator<TTSAPI.WebsocketResponse>;
    /**
     * Cancel this context to stop generating speech.
     */
    cancel(): Promise<void>;
}
export declare class TTSWS extends TTSEmitter {
    url: URL;
    socket: WebSocketLike;
    private client;
    private _ready;
    private _wsOptions;
    private _contextQueues;
    constructor(client: Cartesia, options?: WS.ClientOptions | undefined);
    private _initSocket;
    send(event: TTSAPI.WebsocketClientEvent): Promise<void>;
    /**
     * Send a generation request and iterate over the responses.
     */
    generate(request: Omit<TTSAPI.GenerationRequest, 'context_id'> & {
        context_id?: string | null | undefined;
    }): AsyncGenerator<TTSAPI.WebsocketResponse>;
    /**
     * Cancel a context to stop generating speech for it.
     */
    cancelContext(contextId: string): Promise<void>;
    /**
     * Create a new context with the given options.
     * Registers a per-context event queue for proper multi-context routing.
     */
    context(options: ContextOptions): TTSWSContext;
    close(props?: {
        code: number;
        reason: string;
    }): void;
    /**
     * Wait for the WebSocket connection to be ready.
     */
    connect(): Promise<this>;
    /** Register a per-context queue. Called by context(). */
    _registerContext(contextId: string): void;
    /** Unregister a per-context queue. Called on context completion or cancellation. */
    _unregisterContext(contextId: string): void;
    /** Get the queue entry for a context, or undefined. */
    _getContextQueue(contextId: string): ContextQueueEntry | undefined;
    /**
     * Check if the connection is open; if closed, reconnect transparently.
     * Clears all context queues on reconnect since server-side state is lost.
     */
    private _ensureConnected;
    private authHeaders;
}
export {};
//# sourceMappingURL=ws.d.mts.map