@pipedog/core 0.0.0 → 0.1.0

package/dist/services/tts_service.d.ts

@@ -0,0 +1,909 @@
+/**
+ * Base classes for Text-to-speech services.
+ *
+ * Porting notes: the deprecated `aggregateSentences`, `pauseWatchdogTimeoutS`
+ * and `skipAggregatorTypes` constructor options, the deprecated
+ * `aggregationType` argument of `addTextTransformer()` /
+ * `removeTextTransformer()`, `setModel()` / `setVoice()`, the legacy
+ * `TTSUpdateSettingsFrame(settings={...})` path and the deprecated
+ * `WordTTSService`, `WebsocketWordTTSService`, `InterruptibleWordTTSService`,
+ * `AudioContextTTSService` and `AudioContextWordTTSService` classes are not
+ * ported.
+ */
+import { type Task } from "@pipedog/asyncio";
+import type { BaseAudioResampler } from "../audio/resamplers/base_audio_resampler.ts";
+import { AggregatedTextFrame, type CancelFrame, EndFrame, ErrorFrame, Frame, InterruptionFrame, LLMFullResponseEndFrame, LLMFullResponseStartFrame, LLMTextFrame, type StartFrame, TextFrame, TextType, TTSSpeakFrame, TTSStoppedFrame, TTSUpdateSettingsFrame } from "../frames/frames.ts";
+import { FrameDirection, type FrameProcessorSetup } from "../processors/frame_processor.ts";
+import { type Language } from "../transcriptions/language.ts";
+import { AggregatedFrameSequencer } from "../utils/context/aggregated_frame_sequencer.ts";
+import { AudioContextManager } from "../utils/context/audio_context_manager.ts";
+import { WordTimestamp, WordTimestampTracker } from "../utils/context/word_timestamp_tracker.ts";
+import type { Aggregation } from "../utils/text/base_text_aggregator.ts";
+import type { BaseTextFilter } from "../utils/text/base_text_filter.ts";
+import { SimpleTextAggregator } from "../utils/text/simple_text_aggregator.ts";
+import { PronunciationTransform } from "../utils/text/transforms/pronunciations.ts";
+import { AIService, type AIServiceOptions } from "./ai_service.ts";
+import { TTSSettings } from "./settings.ts";
+import { WebsocketService, type WebsocketServiceOptions } from "./websocket_service.ts";
+/**
+ * Controls how incoming text is aggregated before TTS synthesis.
+ *
+ * - SENTENCE: Buffer text until sentence boundaries are detected before
+ *   synthesis. Produces more natural speech but adds latency (~200-300ms per
+ *   sentence).
+ * - TOKEN: Stream text tokens directly to TTS as they arrive. Reduces latency
+ *   but may affect speech quality depending on the TTS provider.
+ */
+export declare const TextAggregationMode: {
+    readonly SENTENCE: "sentence";
+    readonly TOKEN: "token";
+};
+export type TextAggregationMode = (typeof TextAggregationMode)[keyof typeof TextAggregationMode];
+/**
+ * A text transform: takes the aggregated text and its type, and returns the
+ * transformed text.
+ */
+export type TextTransformFunction = (text: string, textType: TextType | string) => Promise<string>;
+export interface TTSContextOptions {
+    /**
+     * Whether this TTS output should be appended to the conversation context
+     * after it is spoken.
+     */
+    appendToContext?: boolean;
+    /**
+     * Whether to push an `LLMAssistantPushAggregationFrame` after the TTS has
+     * finished speaking, forcing the assistant aggregator to commit its current
+     * text buffer to the conversation context.
+     */
+    pushAssistantAggregation?: boolean;
+    /** Whether an interruption may discard this synthesis. */
+    interruptible?: boolean;
+}
+/**
+ * Context information for a TTS request.
+ *
+ * - `appendToContext`: Whether this TTS output should be appended to the
+ *   conversation context after it is spoken.
+ * - `pushAssistantAggregation`: Whether to push an
+ *   `LLMAssistantPushAggregationFrame` after the TTS has finished speaking,
+ *   forcing the assistant aggregator to commit its current text buffer to the
+ *   conversation context.
+ * - `interruptible`: Whether an interruption may discard this synthesis.
+ */
+export declare class TTSContext {
+    appendToContext: boolean;
+    pushAssistantAggregation: boolean;
+    interruptible: boolean;
+    constructor(options?: TTSContextOptions);
+}
+/** Internal: what has happened so far while an audio context plays. */
+export declare class _AudioContextPlayback {
+    receivedAudio: boolean;
+    stopFrameDue: boolean;
+}
+/** An item queued in an audio context. */
+export type AudioContextItem = Frame | WordTimestamp;
+export interface TTSServiceOptions extends AIServiceOptions {
+    /**
+     * How to aggregate incoming text before synthesis.
+     * `TextAggregationMode.SENTENCE` (default) buffers until sentence
+     * boundaries, `TextAggregationMode.TOKEN` streams tokens directly for lower
+     * latency.
+     */
+    textAggregationMode?: TextAggregationMode | null;
+    /** Whether to push TextFrames and LLMFullResponseEndFrames. */
+    pushTextFrames?: boolean;
+    /** Whether to automatically push TTSStoppedFrames. */
+    pushStopFrames?: boolean;
+    /**
+     * Whether to automatically create audio contexts and push TTSStartedFrames.
+     * When true, the base class handles `createAudioContext` and yields
+     * `TTSStartedFrame` before each synthesis call, so `runTts`
+     * implementations do not need to.
+     */
+    pushStartFrame?: boolean;
+    /** Idle time before pushing TTSStoppedFrame when pushStopFrames is true. */
+    stopFrameTimeoutS?: number;
+    /** Whether to push silence audio after TTSStoppedFrame. */
+    pushSilenceAfterStop?: boolean;
+    /** Duration of silence to push when pushSilenceAfterStop is true. */
+    silenceTimeS?: number;
+    /**
+     * Whether to hold incoming frames after a turn until its audio contexts
+     * end. Needed by services whose audio doesn't carry its request's context
+     * ID.
+     */
+    pauseFrameProcessing?: boolean;
+    /**
+     * How many consecutive TTS contexts may complete without producing any
+     * audio before the service is reported unable to do its job. Catches a
+     * provider that accepts requests and stays silent — an unknown voice ID,
+     * say — which no error ever surfaces. Every silent context reports an error
+     * the service can carry on from, whatever the limit is; on reaching the
+     * limit the service reports a permanent error instead, stops being given
+     * work, and the pipeline worker applies its `ProcessorUnusablePolicy`. Set
+     * to 0 to report silent contexts without ever writing the service off.
+     */
+    maxConsecutiveZeroAudioContexts?: number;
+    /**
+     * Whether to append a trailing space to text before sending to TTS. This
+     * helps prevent some TTS services from vocalizing trailing punctuation
+     * (e.g., "dot"). Only applied in sentence aggregation mode; when streaming
+     * tokens, the incoming text's own whitespace is preserved.
+     */
+    appendTrailingSpace?: boolean;
+    /** Output sample rate for generated audio. */
+    sampleRate?: number | null;
+    /** List of text types that should not be spoken. */
+    skipTextTypes?: string[] | null;
+    /**
+     * A list of callables to transform text just before sending it to TTS.
+     * Each callable takes the aggregated text and its type, and returns the
+     * transformed text. To register, provide a list of tuples of
+     * `[textType | "*", transformFunction]`.
+     */
+    textTransforms?: [TextType | string, TextTransformFunction][] | null;
+    /** Sequence of text filters to apply after aggregation. */
+    textFilters?: readonly BaseTextFilter[] | null;
+    /** Destination for generated audio frames. */
+    transportDestination?: string | null;
+    /** The runtime-updatable settings for the TTS service. */
+    settings?: TTSSettings | null;
+    /** Whether the service should reuse context IDs within the same turn. */
+    reuseContextIdWithinTurn?: boolean;
+}
+/**
+ * Base class for text-to-speech services.
+ *
+ * Provides common functionality for TTS services including text aggregation,
+ * filtering, audio generation, and frame management. Supports configurable
+ * sentence aggregation, silence insertion, and frame processing control.
+ *
+ * Event handlers:
+ *
+ * - on_connected: Called when connected to the TTS service.
+ * - on_disconnected: Called when disconnected from the TTS service.
+ * - on_connection_error: Called when a connection to the TTS service error occurs.
+ * - on_tts_request: Called before a TTS request is made, with the context ID and text.
+ *
+ * @example
+ * tts.eventHandler("on_connected", async (tts: TTSService) => {
+ *   logger.debug("TTS connected");
+ * });
+ * tts.eventHandler("on_disconnected", async (tts: TTSService) => {
+ *   logger.debug("TTS disconnected");
+ * });
+ * tts.eventHandler("on_connection_error", async (tts: TTSService, error: string) => {
+ *   logger.error(`TTS connection error: ${error}`);
+ * });
+ * tts.eventHandler("on_tts_request", async (tts: TTSService, contextId: string, text: string) => {
+ *   logger.debug(`TTS request: ${contextId} - ${text}`);
+ * });
+ */
+export declare abstract class TTSService extends AIService {
+    protected _settings: TTSSettings;
+    protected _textAggregationMode: TextAggregationMode;
+    protected _pushTextFrames: boolean;
+    protected _pushStopFrames: boolean;
+    protected _pushStartFrame: boolean;
+    protected _stopFrameTimeoutS: number;
+    protected _pushSilenceAfterStop: boolean;
+    protected _silenceTimeS: number;
+    protected _pauseFrameProcessing: boolean;
+    protected _maxConsecutiveZeroAudioContexts: number;
+    protected _consecutiveZeroAudioContexts: number;
+    protected _appendTrailingSpace: boolean;
+    protected _initSampleRate: number | null;
+    protected _sampleRate: number;
+    protected _textAggregator: SimpleTextAggregator;
+    protected _skippedTextAggregator: SimpleTextAggregator;
+    protected _skipTextTypes: string[];
+    protected _textTransforms: [TextType | string, TextTransformFunction][];
+    protected _skippingPronunciations: boolean;
+    protected _textFilters: readonly BaseTextFilter[];
+    protected _transportDestination: string | null;
+    protected _aggregatedFrameSequencer: AggregatedFrameSequencer;
+    protected _resampler: BaseAudioResampler;
+    protected _ttsContexts: Map<string, TTSContext>;
+    protected _streamedText: string;
+    protected _sentNonWhitespaceInContext: boolean;
+    protected _textAggregationMetricsStarted: boolean;
+    protected _wordTimestampTracker: WordTimestampTracker;
+    protected _reuseContextIdWithinTurn: boolean;
+    protected _turnContextId: string | null;
+    protected _audioContextManager: AudioContextManager;
+    protected _audioContextTask: Task<unknown> | null;
+    protected _isYieldingFramesSynchronously: boolean;
+    /**
+     * Initialize the TTS service.
+     *
+     * @param options See `TTSServiceOptions`. Other options are passed to the
+     *   parent AIService.
+     */
+    constructor(options?: TTSServiceOptions);
+    /** The current sample rate for audio output, in Hz. */
+    get sampleRate(): number;
+    /**
+     * The recommended chunk size for audio streaming, in bytes.
+     *
+     * This property indicates how much audio we download (from TTS services
+     * that require chunking) before we start pushing the first audio frame.
+     * This will make sure we download the rest of the audio while audio is
+     * being played without causing audio glitches (specially at the
+     * beginning). Of course, this will also depend on how fast the TTS service
+     * generates bytes.
+     */
+    get chunkSize(): number;
+    /** Current sentence tokenizer language, derived from TTS settings. */
+    get textAggregationLanguage(): string;
+    /**
+     * Whether this service has a meaningful processing-time metric.
+     *
+     * Processing time is measured around `runTts()`, so it only means something
+     * when synthesis finishes before `runTts` returns. Services that hand the
+     * text off and receive audio elsewhere — anything holding a persistent
+     * connection with its own receive task — return false, since the
+     * measurement would cover the send and nothing else. TTFB and TTFA carry
+     * the latency for those.
+     */
+    get supportsProcessingMetrics(): boolean;
+    /**
+     * Record TTS usage metrics.
+     *
+     * When streaming tokens, usage metrics are aggregated and reported at flush
+     * time instead of per token, so individual calls are skipped.
+     *
+     * @param text The text being processed by TTS.
+     */
+    startTtsUsageMetrics(text: string): Promise<void>;
+    /**
+     * Start text aggregation metrics if not already started.
+     *
+     * Only starts the metric once per LLM response. Skipped when streaming
+     * tokens since per-token aggregation time is not meaningful.
+     */
+    startTextAggregationMetrics(): Promise<void>;
+    /** Stop text aggregation metrics and reset the started flag. */
+    stopTextAggregationMetrics(): Promise<void>;
+    /**
+     * Set up the service.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    setup(setup: FrameProcessorSetup): Promise<void>;
+    /**
+     * Start the TTS service.
+     *
+     * @param frame The start frame containing initialization parameters.
+     */
+    start(frame: StartFrame): Promise<void>;
+    /**
+     * Stop the TTS service.
+     *
+     * @param frame The end frame.
+     */
+    stop(frame: EndFrame): Promise<void>;
+    /**
+     * Cancel the TTS service.
+     *
+     * @param frame The cancel frame.
+     */
+    cancel(frame: CancelFrame): Promise<void>;
+    /** Release TTS resources at teardown. */
+    cleanup(): Promise<void>;
+    /**
+     * Set whether this service can be given work.
+     *
+     * @param isUsable Whether the service can be given work.
+     */
+    setUsable(isUsable: boolean): Promise<void>;
+    /**
+     * Transform text of a specific type.
+     *
+     * @param transformFunction The function to apply for transformation. This
+     *   function should take the text and its type as input and return the
+     *   transformed text, e.g.
+     *   `async function myTransform(text: string, textType: string): Promise<string>`.
+     * @param textType The type of text to transform. This value defaults to
+     *   "*" indicating the function should handle all text before sending to
+     *   TTS.
+     */
+    addTextTransformer(transformFunction: TextTransformFunction, textType?: TextType | string): void;
+    /**
+     * Remove a text transformer for a specific text type.
+     *
+     * @param transformFunction The function to remove.
+     * @param textType The type of text to remove the transformer for.
+     */
+    removeTextTransformer(transformFunction: TextTransformFunction, textType?: TextType | string): void;
+    /**
+     * Render a word's pronunciation in this service's markup.
+     *
+     * Services that support pronunciation hints override this. The base
+     * implementation supports none.
+     *
+     * @param word The word as it appears in the text.
+     * @param ipa How to pronounce it, in IPA.
+     * @returns The text to send in place of `word`, or null when this service
+     *   cannot use the pronunciation.
+     */
+    static formatPronunciation(_word: string, _ipa: string): string | null;
+    /**
+     * Whether this service reads pronunciation markup with its current settings.
+     *
+     * Pronunciation transforms are skipped while this is false, so their words
+     * are spoken as written. Services whose markup depends on the model or on a
+     * setting override this; it is checked for every text sent, so it follows
+     * settings updates.
+     *
+     * @returns true in the base implementation.
+     */
+    get supportsPronunciations(): boolean;
+    /**
+     * Create a text transform that makes this service say words as IPA describes.
+     *
+     * Each word is replaced with `formatPronunciation()` output, so the same
+     * IPA works with any service that supports it. Words the service cannot use
+     * are reported once and spoken as written. While the service cannot read
+     * pronunciation markup at all (see `supportsPronunciations`), the transform
+     * is skipped.
+     *
+     * Register this transform last in `textTransforms`. Transforms run in
+     * order, and one that runs after it (stripping markdown or symbols,
+     * replacing text) can rewrite the markup it inserts, such as Cartesia's
+     * `<<…>>` blocks or an SSML `<phoneme>` tag, and break the hint.
+     *
+     * @param pronunciations Word to IPA, e.g. `{ Metformin: "mɛtˈfɔɹmɪn" }`.
+     * @returns A transform to register with `textTransforms`.
+     *
+     * @example
+     * const pronounce = CartesiaTTSService.pronunciationTransformIpa({ Metformin: "mɛtˈfɔɹmɪn" });
+     * const tts = new CartesiaTTSService({
+     *   textTransforms: [
+     *     ["*", stripMarkdown],
+     *     ["*", expandCurrency],
+     *     ["*", pronounce], // last, so nothing rewrites its markup
+     *   ],
+     * });
+     */
+    static pronunciationTransformIpa(pronunciations: Readonly<Record<string, string>>): PronunciationTransform;
+    /**
+     * Run text-to-speech synthesis on the provided text.
+     *
+     * This method must be implemented by subclasses to provide actual TTS
+     * functionality. The base class logs the synthesized text before invoking
+     * this method, so implementations should not log it again.
+     *
+     * @param text The text to synthesize into speech.
+     * @param contextId Unique identifier for this TTS context.
+     * @returns Audio frames containing the synthesized speech.
+     */
+    abstract runTts(text: string, contextId: string): AsyncGenerator<Frame | null, void>;
+    /**
+     * Convert a language to the service-specific language format.
+     *
+     * @param language The language to convert.
+     * @returns The service-specific language identifier. Return null to
+     *   indicate an unsupported language. This optional return is an extension
+     *   hook for future or third-party subclasses; as of 2026-04-28,
+     *   first-party services return a string.
+     */
+    languageToServiceLanguage(language: Language): string | null;
+    /**
+     * Generate or reuse a context ID based on concurrent TTS support.
+     *
+     * @returns A context ID string for the TTS request.
+     */
+    createContextId(): string;
+    /**
+     * Flush any buffered audio data.
+     *
+     * @param contextId The specific context to flush. If null, falls back to
+     *   the currently active context (for non-concurrent services).
+     */
+    flushAudio(_contextId?: string | null): Promise<void>;
+    /**
+     * Process frames from an async generator, routing them through the audio context.
+     *
+     * All non-null frames yielded by the generator are appended to the audio
+     * context identified by contextId. The audio context must be created by
+     * runTts (via createAudioContext) before the first frame is yielded.
+     *
+     * WebSocket services yield null to signal that audio will arrive via a
+     * separate receive loop; those services manage context lifetime themselves
+     * (via removeAudioContext in the receive loop on "done"). HTTP services
+     * never yield null and do NOT call removeAudioContext in runTts —
+     * onTurnContextCompleted closes the context once the turn's remaining
+     * frames (e.g. TTSTextFrame) are queued.
+     *
+     * @param contextId The audio context to route frames to.
+     * @param generator An async generator yielding Frame objects or null.
+     */
+    ttsProcessGenerator(contextId: string, generator: AsyncIterable<Frame | null | undefined>): Promise<void>;
+    /**
+     * Called when a new turn context ID has been created.
+     *
+     * Override to perform provider-specific setup (e.g., eagerly opening a
+     * server-side context) before text starts flowing. This is called from
+     * `processFrame` when an `LLMFullResponseStartFrame` or `TTSSpeakFrame`
+     * arrives.
+     *
+     * @param contextId The newly created turn context ID.
+     */
+    onTurnContextCreated(_contextId: string): Promise<void>;
+    /** Handle the completion of a turn. */
+    onTurnContextCompleted(): Promise<void>;
+    /**
+     * Called when an audio context is cancelled due to an interruption.
+     *
+     * Override this in a subclass to perform provider-specific cleanup (e.g.
+     * sending a cancel/close message over the WebSocket) when the bot is
+     * interrupted mid-speech. The context is still registered when this hook
+     * runs. Uninterruptible contexts continue playing and do not call this
+     * hook.
+     *
+     * @param contextId The ID of the audio context that was interrupted.
+     */
+    onAudioContextInterrupted(_contextId: string): Promise<void>;
+    /**
+     * Called after an audio context has finished playing all of its audio.
+     *
+     * Override this in a subclass to perform provider-specific cleanup (e.g.
+     * sending a close-context message to free server-side resources) once an
+     * audio context has been fully processed. The context entry has already
+     * been removed from the internal context map, and the active context has
+     * **not** yet been reset when this is called.
+     *
+     * @param contextId The ID of the audio context that finished processing.
+     */
+    onAudioContextCompleted(_contextId: string): Promise<void>;
+    /** Start tracking word timestamps from the current time. */
+    startWordTimestamps(): Promise<void>;
+    /** Reset word timestamp tracking. */
+    resetWordTimestamps(): Promise<void>;
+    /**
+     * Add word timestamps for processing.
+     *
+     * When an audio context exists for this contextId, timestamps are routed
+     * into the per-context audio queue alongside audio frames so they are
+     * processed in strict playback order by _handleAudioContext. Otherwise they
+     * are processed immediately via _addWordTimestamps.
+     *
+     * @param wordTimes List of [word, timestamp] tuples where timestamp is in
+     *   seconds.
+     * @param contextId Unique identifier for the TTS context.
+     * @param options.includesInterFrameSpaces When true, each emitted
+     *   TTSTextFrame carries `includesInterFrameSpaces=true` so downstream
+     *   consumers do not inject extra spaces between consecutive frames (e.g.
+     *   ElevenLabs for CJK languages where word tokens already self-contain
+     *   their spacing). null leaves the frame's own default unchanged.
+     * @param options.preMergeTokens When true, punctuation and space-only
+     *   tokens are merged into the preceding word via `mergePunctTokens` before
+     *   queuing (e.g. Inworld TTS, which emits spaces and punctuation as
+     *   separate tokens). After merging the resulting tokens are clean word
+     *   strings, so `includesInterFrameSpaces` should be left false (its
+     *   default).
+     */
+    addWordTimestamps(wordTimes: (readonly [string, number])[], contextId?: string | null, options?: {
+        includesInterFrameSpaces?: boolean | null;
+        preMergeTokens?: boolean;
+    }): Promise<void>;
+    /**
+     * Create a new audio context for grouping related audio.
+     *
+     * @param contextId Unique identifier for the audio context.
+     */
+    createAudioContext(contextId: string): Promise<void>;
+    /**
+     * Append a frame or word-timestamp entry to an existing audio context queue.
+     *
+     * Passing a `frame` of null signals end-of-context (used by
+     * removeAudioContext to mark the queue for deletion). If the context no
+     * longer exists but the contextId matches the active turn, the context is
+     * transparently recreated before appending.
+     *
+     * @param contextId The context to append to. null is accepted as a no-op
+     *   (with a debug log) so callers can pass through values from
+     *   `getActiveAudioContextId()` without an explicit guard.
+     * @param frame The frame, word-timestamp entry, or null (end-of-context
+     *   sentinel) to append.
+     */
+    appendToAudioContext(contextId: string | null, frame: AudioContextItem | null): Promise<void>;
+    /**
+     * Remove an existing audio context.
+     *
+     * @param contextId The context to remove. null is accepted as a no-op
+     *   (logged) so callers can pass through values from
+     *   `getActiveAudioContextId()` without an explicit guard.
+     */
+    removeAudioContext(contextId: string | null): Promise<void>;
+    /**
+     * Check whether the given audio context is registered.
+     *
+     * @param contextId The context ID to check.
+     * @returns true if the context exists and is available.
+     */
+    audioContextAvailable(contextId: string): boolean;
+    /** Get a list of all available audio contexts. */
+    getAudioContexts(): string[];
+    /**
+     * Check if there is an active audio context.
+     *
+     * @returns true if an active audio context exists, false otherwise.
+     */
+    hasActiveAudioContext(): boolean;
+    /**
+     * Get the active audio context ID.
+     *
+     * Returns the playback cursor when set (during active playback), falling
+     * back to the current turn's synthesis contextId. The fallback covers the
+     * gap between contexts and the start of a turn before the playback task has
+     * dequeued the just-created context — important for services whose wire
+     * protocol does not echo contextId back on incoming audio.
+     *
+     * @returns The active context ID, or null if neither cursor is set.
+     */
+    getActiveAudioContextId(): string | null;
+    /** Remove the active audio context. */
+    removeActiveAudioContext(): Promise<void>;
+    /** Reset the active audio context. */
+    resetActiveAudioContext(): void;
+    /**
+     * Process frames for text-to-speech conversion.
+     *
+     * Handles TextFrames for synthesis, interruption frames, settings updates,
+     * and various control frames.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of frame processing.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+    /**
+     * Push a frame downstream with TTS-specific handling.
+     *
+     * @param frame The frame to push.
+     * @param direction The direction to push the frame.
+     */
+    pushFrame(frame: Frame, direction?: FrameDirection): Promise<void>;
+    /**
+     * Apply a TTS settings delta.
+     *
+     * Translates language to service-specific value before applying.
+     *
+     * @param delta A TTS settings delta.
+     * @returns Record mapping changed field names to their previous values.
+     */
+    protected _updateSettings(delta: TTSSettings): Promise<Record<string, unknown>>;
+    /** Convert a language to the service's format, passing unknown codes as they are. */
+    protected _serviceLanguage(language: string): string;
+    /** Start a turn whose sentences share one context ID. */
+    protected _handleLlmResponseStart(frame: LLMFullResponseStartFrame): Promise<void>;
+    /** Speak the turn's remaining text and complete the turn. */
+    protected _handleLlmResponseEnd(frame: LLMFullResponseEndFrame | EndFrame, direction: FrameDirection): Promise<void>;
+    /** Queue each sentence of LLM text that isn't spoken. */
+    protected _handleSkippedLlmText(frame: LLMTextFrame): Promise<void>;
+    /** Queue the rest of a reply that isn't spoken, then the end of the reply. */
+    protected _handleSkippedLlmResponseEnd(frame: LLMFullResponseEndFrame): Promise<void>;
+    /** Queue a sentence of LLM text that isn't spoken, as the bot's output. */
+    protected _queueSkippedLlmText(aggregation: Aggregation): Promise<void>;
+    /** Speak a TTSSpeakFrame as a turn of its own, even in the middle of an LLM turn. */
+    protected _handleTtsSpeak(frame: TTSSpeakFrame): Promise<void>;
+    /** Apply a settings update meant for this service, or pass it on. */
+    protected _handleUpdateSettings(frame: TTSUpdateSettingsFrame, direction: FrameDirection): Promise<void>;
+    /** Reset the turn and drop interruptible audio contexts. */
+    protected _handleInterruption(_frame: InterruptionFrame, _direction: FrameDirection): Promise<void>;
+    /** Discard interruptible contexts while preserving ongoing synthesis and playback. */
+    protected _interruptAudioContexts(): Promise<void>;
+    /**
+     * Hold incoming frames while an audio context is open.
+     *
+     * Services whose audio doesn't carry its request's context ID label
+     * incoming audio with the context still open, so the next request waits for
+     * every open context to end. Contexts play in order, so audio from
+     * different requests never overlaps.
+     */
+    protected _holdFramesWhileAudioContextsOpen(): Promise<void>;
+    /** Let held frames through once no audio context is open. */
+    protected _releaseFramesIfAudioContextsEnded(): Promise<void>;
+    /** Make a frame of an uninterruptible context uninterruptible too. */
+    protected _applyContextInterruptible(frame: Frame): void;
+    /** Forget a stopped context and push the assistant aggregation it asked for. */
+    protected _finishTtsContext(frame: TTSStoppedFrame): Promise<void>;
+    /** Push the silence configured to follow a TTSStoppedFrame. */
+    protected _pushStopSilence(frame: TTSStoppedFrame): Promise<void>;
+    /** Send a segment's willBeSpoken frame through the transport's clock queue. */
+    protected _stampSegmentAnnouncement(frame: AggregatedTextFrame): void;
+    /** Whether the service is streaming tokens directly without sentence aggregation. */
+    protected get _isStreamingTokens(): boolean;
+    /** Aggregate LLM text and speak each aggregation. */
+    protected _handleText(frame: TextFrame): Promise<void>;
+    /** Build the frame for an aggregation, keeping a pattern's delimiters in its raw text. */
+    protected _aggregatedTextFrame(aggregation: Aggregation): AggregatedTextFrame;
+    /** Speak aggregated text in `contextId` or a new context, or push it on if skipped. */
+    protected _handleAggregatedText(srcFrame: AggregatedTextFrame, contextId?: string | null): Promise<void>;
+    /** Push text that isn't spoken, in order with the spoken text around it. */
+    protected _pushSkippedText(frame: AggregatedTextFrame, contextId: string): Promise<void>;
+    /** Filter, transform and synthesize text, timing it as processing. */
+    protected _speakText(srcFrame: AggregatedTextFrame, text: string, contextId: string): Promise<void>;
+    /** Trim leading whitespace from text to synthesize, or null if nothing is left to say. */
+    protected _trimText(text: string): string | null;
+    /**
+     * Run the text filters on text about to be synthesized.
+     *
+     * @returns The filtered text, or null if nothing is left to say.
+     */
+    protected _filterText(text: string): Promise<string | null>;
+    /**
+     * Turn filtered text into the text sent to the TTS.
+     *
+     * Transforms only affect the text sent to the TTS for TTS-specific purposes
+     * (e.g. inserting tags for spelling or emotion, or replacing an @ with
+     * "at"). For services with word timestamps they can affect the context,
+     * since TTSTextFrames are built from the TTS output.
+     *
+     * @returns The text to synthesize, or null if a transform failed.
+     */
+    protected _transformText(text: string, textType: string): Promise<string | null>;
+    /** Whether pronunciation transforms apply, warning once when they stop applying. */
+    protected _canApplyPronunciations(): boolean;
+    /**
+     * Prepare text for TTS by applying any transformations required by the TTS service.
+     *
+     * @param text The text to prepare.
+     * @returns The prepared text with transformations applied.
+     */
+    protected _prepareTextForTts(text: string): string;
+    /** Mark text as about to be spoken and push it ahead of its audio. */
+    protected _announceText(srcFrame: AggregatedTextFrame, contextId: string): Promise<void>;
+    /** Open an audio context with a TTSStartedFrame, for services that leave it to the base. */
+    protected _startAudioContext(contextId: string): Promise<void>;
+    /** Give the text a slot in the sequencer, which orders it with skipped text. */
+    protected _registerSpokenText(srcFrame: AggregatedTextFrame, text: string, contextId: string): Promise<void>;
+    /**
+     * Emit frames returned by the aggregated-frame sequencer in audio order.
+     *
+     * In streaming (TOKEN) mode these frames — a promoted sentence anchor and
+     * any replayed word/progress frames — describe an audio context whose audio
+     * and word frames are emitted by the dedicated audio-context task. Routing
+     * them through that context's queue keeps a single consumer emitting
+     * everything in order; pushing directly here would let them race the
+     * audio-context task. When the context is gone (or the sequencer is
+     * non-streaming), push directly.
+     *
+     * @param frames Frames returned by registerSpoken/registerSkipped/finalize.
+     * @param contextId The context these frames belong to.
+     */
+    protected _pushSequencerFrames(frames: Frame[], contextId: string | null): Promise<void>;
+    /** Run the service's runTts for text, unless the service is no longer usable. */
+    protected _synthesizeText(text: string, contextId: string): Promise<void>;
+    /** Queue the spoken text behind its audio, for services without word timestamps. */
+    protected _pushSpokenText(srcFrame: AggregatedTextFrame, text: string, contextId: string, appendToContext: boolean): Promise<void>;
+    /**
+     * Stream audio frames from an async byte iterator with optional resampling.
+     *
+     * For WAV data, use `stripWavHeader: true` to strip the header and
+     * auto-detect the source sample rate. For raw PCM data, pass `inSampleRate`
+     * directly. Audio is resampled to `this.sampleRate` when the source rate
+     * differs.
+     *
+     * @param iterator Async iterator yielding audio bytes.
+     * @param options.stripWavHeader Strip WAV header and parse source sample
+     *   rate from it.
+     * @param options.inSampleRate Source sample rate for raw PCM data.
+     *   Overrides WAV-detected rate if both are provided.
+     * @param options.contextId Unique identifier for this TTS context.
+     */
+    protected _streamAudioFramesFromIterator(iterator: AsyncIterable<Uint8Array>, options?: {
+        stripWavHeader?: boolean;
+        inSampleRate?: number | null;
+        contextId?: string | null;
+    }): AsyncGenerator<Frame, void>;
+    /**
+     * Process word timestamps directly, building and pushing TTSTextFrames inline.
+     *
+     * Used both from _handleAudioContext (via WordTimestamp items) and from
+     * services that do not use audio contexts. Each entry emits a TTSTextFrame
+     * with a PTS relative to when startWordTimestamps() was called. Entries that
+     * come before that are cached and timed once it is called (i.e. when the
+     * first audio chunk is received).
+     */
+    protected _addWordTimestamps(wordTimes: readonly (readonly [string, number])[], contextId?: string | null, options?: {
+        includesInterFrameSpaces?: boolean;
+    }): Promise<void>;
+    /** Push frames built by the sequencer, noting the PTS of the last word. */
+    protected _pushWordFrames(frames: Frame[]): Promise<void>;
+    /**
+     * Force-complete a context's spoken slots and push any unblocked skipped frames.
+     *
+     * Called at end-of-context to handle TTS providers that silently drop
+     * word-timestamp events. Emits a TTSTextFrame for any remaining unspoken
+     * text in this context, then flushes skipped frames that were blocked by
+     * those incomplete slots. Slots for other contexts still in flight are left
+     * untouched.
+     *
+     * @param contextId The audio context that has ended.
+     */
+    protected _applyForceComplete(contextId: string): Promise<void>;
+    /** Signal that the audio context is still in use, resetting the timeout. */
+    protected _refreshAudioContext(contextId: string): void;
+    /** Create the task that plays audio contexts. */
+    protected _createAudioContextTask(): void;
+    /** Cancel the task that plays audio contexts. */
+    protected _stopAudioContextTask(): Promise<void>;
+    /**
+     * Play audio contexts and the frames between them in order.
+     *
+     * Each audio context plays until all its audio has been pushed downstream,
+     * then onAudioContextCompleted() is called. A frame between contexts (e.g.
+     * an AggregatedTextFrame preceding its audio, or a frame that arrived
+     * between two speak frames) is pushed at its position.
+     */
+    protected _audioContextTaskHandler(): Promise<void>;
+    /** Send a reply's end frame after its words, or behind its start frame if it timed none. */
+    protected _stampLlmResponseFrame(frame: Frame): void;
+    /** Push an audio context's items in order until it ends or goes quiet. */
+    protected _handleAudioContext(contextId: string): Promise<void>;
+    /** Wait for the context's next item, or null once it ends or goes quiet. */
+    protected _nextAudioContextItem(contextId: string): Promise<AudioContextItem | null>;
+    /** Push one item of the playing audio context. */
+    protected _pushAudioContextItem(contextId: string, item: AudioContextItem, playback: _AudioContextPlayback): Promise<void>;
+    /** Finish the playing audio context once it ends or goes quiet. */
+    protected _endAudioContext(contextId: string, playback: _AudioContextPlayback): Promise<void>;
+    /**
+     * Track whether contexts are producing audio, and act when they stop.
+     *
+     * A provider can accept every request and return no audio at all — an
+     * unknown voice ID, say — without ever reporting an error. Every context
+     * that completes in silence is reported as an error, so application code
+     * hears about a turn that produced no speech as it happens. Enough of them
+     * in a row means the service isn't going to speak again, so it is reported
+     * unable to do its job: it stops being given work, a `ServiceSwitcher` can
+     * fail over to another provider, and the pipeline worker applies its
+     * `ProcessorUnusablePolicy`.
+     *
+     * Only contexts that complete are counted; an interrupted context is
+     * cancelled before it gets here.
+     *
+     * @param contextId The audio context that just completed.
+     * @param receivedAudio Whether any audio arrived for that context.
+     */
+    protected _recordContextAudioOutcome(contextId: string, receivedAudio: boolean): Promise<void>;
+}
+export interface WebsocketTTSServiceOptions extends TTSServiceOptions, WebsocketServiceOptions {
+}
+declare const WebsocketTTSService_base: typeof TTSService & (abstract new (...args: any[]) => WebsocketService);
+/**
+ * Base class for websocket-based TTS services.
+ *
+ * Combines TTS functionality with websocket connectivity, providing automatic
+ * error handling and reconnection capabilities.
+ *
+ * Includes an optional keepalive for providers that close an idle
+ * connection. A subclass enables it by overriding `_sendKeepalive()` to send
+ * its provider's keepalive message, and calling
+ * `_createKeepaliveTask(interval)` / `_cancelKeepaliveTask()` from its
+ * `_connect()` / `_disconnect()`.
+ *
+ * Event handlers:
+ *
+ * - on_connection_error: Called when a websocket connection error occurs.
+ *
+ * @example
+ * tts.eventHandler("on_connection_error", async (tts: TTSService, error: string) => {
+ *   logger.error(`TTS connection error: ${error}`);
+ * });
+ */
+export declare abstract class WebsocketTTSService extends WebsocketTTSService_base {
+    protected _keepaliveTask: Task<unknown> | null;
+    /**
+     * Initialize the Websocket TTS service.
+     *
+     * @param options.reconnectOnError Whether to automatically reconnect on
+     *   websocket errors. Other options are passed to parent classes.
+     */
+    constructor(options?: WebsocketTTSServiceOptions);
+    /**
+     * Whether this service has a meaningful processing-time metric.
+     *
+     * false: `runTts` sends the text and returns, and audio arrives later on
+     * the receive task, so there is no synthesis inside the measured window. A
+     * subclass that instead waits for the server to signal the end of synthesis
+     * before returning can override this back to true.
+     */
+    get supportsProcessingMetrics(): boolean;
+    /**
+     * Stop the websocket TTS service on a graceful end.
+     *
+     * @param frame The end frame.
+     */
+    stop(frame: EndFrame): Promise<void>;
+    /**
+     * Cancel the websocket TTS service immediately.
+     *
+     * Disconnecting here is the prompt teardown: the websocket receive loop
+     * runs independently of the audio-context task, so it keeps reading from
+     * the provider until the socket is closed. Stopping only the audio-context
+     * task (in `TTSService.cancel()`) halts output but not reception.
+     *
+     * @param frame The cancel frame.
+     */
+    cancel(frame: CancelFrame): Promise<void>;
+    /** Release websocket TTS resources at teardown. */
+    cleanup(): Promise<void>;
+    /**
+     * End the audio contexts of a connection that is being replaced.
+     *
+     * Providers keep context state per connection and don't resume it on a new
+     * one, so audio still due on the old connection never arrives. Every open
+     * context is closed (audio already received still plays), and a turn in
+     * progress moves to a new context ID so its remaining sentences open a
+     * fresh provider context. Reopening a connection that was already closed,
+     * to send the text at hand, doesn't come through here, so the context it
+     * sends to stays open.
+     */
+    protected _closeConnectionContexts(): Promise<void>;
+    _disconnect(): Promise<void>;
+    _reconnectWebsocket(attemptNumber: number): Promise<boolean>;
+    protected _reportError(error: ErrorFrame, options?: {
+        forceTreatAsPermanent?: boolean;
+    }): Promise<void>;
+    /**
+     * Start the keepalive task if it isn't running.
+     *
+     * @param interval Seconds between keepalive messages.
+     */
+    protected _createKeepaliveTask(interval: number): void;
+    /** Stop the keepalive task if running. */
+    protected _cancelKeepaliveTask(): Promise<void>;
+    /**
+     * Send a keepalive every `interval` seconds while connected.
+     *
+     * A failed send is logged and the loop keeps going: the receive loop
+     * handles a lost connection, and the next keepalive goes out on the
+     * reconnected socket.
+     */
+    protected _keepaliveTaskHandler(interval: number): Promise<void>;
+    /**
+     * Check if the service is ready to send a keepalive.
+     *
+     * @returns true if the websocket is open.
+     */
+    protected _isKeepaliveReady(): boolean;
+    /**
+     * Send a keepalive message over the websocket.
+     *
+     * Subclasses that enable keepalive must override this to send their
+     * provider's keepalive message.
+     */
+    protected _sendKeepalive(): Promise<void>;
+}
+export interface InterruptibleTTSServiceOptions extends WebsocketTTSServiceOptions {
+}
+/**
+ * Websocket-based TTS service that handles interruptions without word timestamps.
+ *
+ * Designed for TTS services that don't support word timestamps. Handles
+ * interruptions by reconnecting the websocket when the bot is speaking and
+ * gets interrupted.
+ */
+export declare abstract class InterruptibleTTSService extends WebsocketTTSService {
+    protected _botSpeaking: boolean;
+    protected _ttsStarted: boolean;
+    protected _handleInterruption(frame: InterruptionFrame, direction: FrameDirection): Promise<void>;
+    /**
+     * Push a frame downstream with TTS-specific handling.
+     *
+     * @param frame The frame to push.
+     * @param direction The direction to push the frame.
+     */
+    pushFrame(frame: Frame, direction?: FrameDirection): Promise<void>;
+    /**
+     * Process frames, tracking whether an interruption needs a reconnect.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of frame processing.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+}
+export {};
+//# sourceMappingURL=tts_service.d.ts.map