@ai-matrx/media 0.13.0 → 0.15.0

package/dist/speech.d.cts

@@ -0,0 +1,565 @@
+import { ProviderSessionFailure, ProviderSessionFailureVerdict } from '@ai-matrx/agents/matrx';
+import { b as SpeechPronunciation, V as VoicePurpose } from './tts-config-JbF86KIt.cjs';
+import { GenerationConfig } from '@cartesia/cartesia-js/resources/tts';
+import { SupportedLanguage } from '@cartesia/cartesia-js/resources/voices';
+
+/**
+ * Unified audio playback — shared types.
+ *
+ * One queue, one output, app-wide. Every "speak this" request becomes a
+ * `PlaybackItem` on the single `playbackQueue`. If audio is already playing, the
+ * new request is QUEUED (never overlapped — the playback twin of the capture
+ * lock's start-always-wins). Providers plug in via `PlaybackAdapter`s so the
+ * queue stays engine-agnostic (Cartesia WebSocket, Groq WAV blob, …).
+ */
+/**
+ * Which synthesis engine renders an item. Declared with its capabilities in the
+ * AV engine registry (`features/audio/service/engines.ts`) — this union and
+ * `SpeakEngineId` are the same set by construction (see the type assertion
+ * there). Consumers call `speak()`, never these keys directly.
+ */
+type PlaybackProvider = "cartesia" | "catalog" | (string & {});
+type PlaybackItemStatus = "queued" | "loading" | "playing" | "paused" | "done" | "error";
+/** What a consumer asks the queue to speak. */
+interface PlaybackRequest {
+    provider: PlaybackProvider;
+    /** Raw text; the adapter applies markdown stripping per `processMarkdown`. */
+    text: string;
+    processMarkdown?: boolean | undefined;
+    /** Short human label for the queue UI (e.g. "Assistant reply", "Note"). */
+    label?: string | undefined;
+    /** Opt this utterance into Custom Dictionary pronunciation (Cartesia). */
+    dictionarySurfaceKey?: string | undefined;
+    /**
+     * Cartesia voice params — EXPLICIT overrides only. Anything absent is
+     * resolved by the adapter AT START TIME from the tiered listening config
+     * (`resolveListeningSettings`), so queued items and history replays honor the
+     * settings current when audio actually plays, not when it was enqueued.
+     * `purpose` picks the default-voice slot when no voice is set anywhere.
+     */
+    cartesia?: {
+        voiceId?: string | undefined;
+        language?: string | undefined;
+        speed?: number | undefined;
+        purpose?: "reading" | "assistant" | undefined;
+    };
+    /** Catalog speech voice params — resolved by `speak()`; server picks the vendor. */
+    catalog?: {
+        voice?: string | undefined;
+        model?: string | undefined;
+        /**
+         * Play a model's sample of one voice instead of synthesizing `text`: the
+         * vendor's own sample when it publishes one (ElevenLabs), otherwise one
+         * short line the server renders once and caches per (model, voice).
+         */
+        sample?: {
+            model: string;
+            voice: string;
+            offeringId?: string | undefined;
+        } | undefined;
+    };
+}
+interface PlaybackItem extends PlaybackRequest {
+    id: string;
+    status: PlaybackItemStatus;
+    error?: string | undefined;
+    enqueuedAtMs: number;
+}
+/** Serializable snapshot the queue pushes to subscribers (→ Redux mirror). */
+interface PlaybackSnapshot {
+    items: PlaybackItem[];
+    /** Id of the item currently loading/playing/paused, or null when idle. */
+    currentId: string | null;
+    /** Global playback rate (applies live to rate-capable providers, e.g. Groq). */
+    rate: number;
+}
+/** Callbacks an adapter fires back into the queue as playback progresses. */
+interface PlaybackAdapterCallbacks {
+    onLoading: () => void;
+    onPlaying: () => void;
+    /** Natural end — the queue advances to the next item. */
+    onEnded: () => void;
+    onError: (message: string) => void;
+}
+/** Handle for controlling the one active playback an adapter started. */
+interface ActivePlayback {
+    pause: () => void | Promise<void>;
+    resume: () => void | Promise<void>;
+    /** Stop + release all resources. Must be idempotent. */
+    stop: () => void | Promise<void>;
+    /** Live playback-rate change (rate-capable providers only). */
+    setRate?: (rate: number) => void;
+}
+interface PlaybackAdapter {
+    provider: PlaybackProvider;
+    /**
+     * Begin playing `item`. Resolves with a control handle as soon as playback is
+     * underway (NOT when it finishes). Fire `cb.onPlaying` once audio starts and
+     * `cb.onEnded` when it finishes naturally.
+     */
+    start: (item: PlaybackItem, cb: PlaybackAdapterCallbacks, rate: number) => Promise<ActivePlayback>;
+}
+
+/** Voice parameters for one Cartesia utterance, resolved at START time. */
+interface SpeechVoiceSettings {
+    /** The person's saved Cartesia voice id (null → the purpose default). */
+    voice: string | null;
+    language: string;
+    speed: number;
+    emotion?: string | null;
+}
+interface SpeechPorts {
+    /** A short-lived Cartesia access token. `forceRefresh` after the provider rejected the last one. */
+    getCartesiaToken: (opts?: {
+        forceRefresh?: boolean;
+    }) => Promise<string>;
+    /** Drop a token the provider rejected so the next read mints a fresh one. */
+    invalidateCartesiaToken?: (token: string) => void;
+    /** The person's voice / language / speed right now (tiered settings on the web). */
+    resolveVoiceSettings: () => Promise<SpeechVoiceSettings>;
+    /** Custom pronunciations for one utterance (best-effort; failures speak without them). */
+    resolvePronunciations?: (item: PlaybackItem) => Promise<SpeechPronunciation[]>;
+    /**
+     * Report a browser-held provider session failure to the server; the verdict carries the
+     * person's sentence and whether retrying can help.
+     */
+    reportProviderFailure?: (failure: ProviderSessionFailure) => Promise<ProviderSessionFailureVerdict | null>;
+    /** Tell the person speech stopped (a toast on the web). Without it the error is only on the item. */
+    notifyError?: (title: string, description: string) => void;
+    /**
+     * Runs before an item starts (e.g. "speaking happens in an organization" — hold until one is set).
+     * Throwing marks the item failed with `describeStartRefusal(err)` (or the error's message).
+     */
+    beforeStart?: (item: PlaybackItem) => Promise<void>;
+    describeStartRefusal?: (error: unknown) => string | null;
+    /** First engagement of the engine (the web mounts its lazy audio UI here). */
+    onEngage?: () => void;
+    /** Extra engines (the web's server catalog lane). Cartesia is built in. */
+    adapters?: Partial<Record<PlaybackProvider, () => Promise<PlaybackAdapter>>>;
+    /** Engine used when a `speak` call names none. Default "cartesia". */
+    defaultEngine?: PlaybackProvider;
+    /** Fill engine-specific params a `speak` call left out (the web's catalog voice preference). */
+    completeRequest?: (request: PlaybackRequest) => PlaybackRequest;
+}
+declare function configureSpeech(next: Partial<SpeechPorts>): void;
+/** Test seam: forget every port. */
+declare function resetSpeechPortsForTests(): void;
+
+/**
+ * speak() — THE entry point for turning text into audio, in every app.
+ *
+ * One call, any engine. The caller says WHAT to say (and optionally which engine); the queue owns
+ * one-at-a-time playback, the app-wide playback lock and lazy-loading of the engine. Cartesia's
+ * voice / language / speed resolve at START time through the host's `resolveVoiceSettings` port,
+ * so queued items and replays honor the settings current when audio plays. Framework-free;
+ * React surfaces use `useSpeech()` (`@ai-matrx/media/react`) on top of the same call.
+ */
+
+interface SpeakRequest {
+    text: string;
+    /** Engine to synthesize with. Omit for the host's default (Cartesia unless configured). */
+    engine?: PlaybackProvider | undefined;
+    /** Which voice slot to resolve for engines with per-purpose voices (Cartesia). */
+    purpose?: VoicePurpose | undefined;
+    /** Strip markdown before speaking (default true). */
+    processMarkdown?: boolean | undefined;
+    /** Short human label for a queue / Media panel row. */
+    label?: string | undefined;
+    /** Opt this utterance into Custom Dictionary pronunciation (host-resolved). */
+    dictionarySurfaceKey?: string | undefined;
+    /** Explicit voice id — overrides the saved voice for this utterance. */
+    voice?: string | undefined;
+    /** Explicit language — overrides the saved language. */
+    language?: string | undefined;
+    /** Explicit speed — overrides the saved speed. */
+    speed?: number | undefined;
+    /** Hear a catalog model's sample of one voice instead of speaking `text` (catalog engine). */
+    sample?: {
+        model: string;
+        voice: string;
+        offeringId?: string | undefined;
+    } | undefined;
+}
+interface SpeakResult {
+    /** Queue item id — feed it to the queue's pause/resume/remove verbs. */
+    id: string;
+    /** The engine that actually ran (after defaulting). */
+    engine: PlaybackProvider;
+}
+/** The engine for a request: explicit wins, otherwise the host default, otherwise Cartesia. */
+declare function resolveSpeakEngine(requested?: PlaybackProvider): PlaybackProvider;
+/** Speak text through the single playback queue. */
+declare function speak(request: SpeakRequest): SpeakResult;
+
+/**
+ * playbackQueue — the single, app-wide audio playback queue.
+ *
+ * Framework-free singleton (the playback twin of `captureLock`). Every "speak
+ * this" request becomes an item; audio plays ONE at a time. New requests while
+ * something is playing are appended (queued, never overlapped). Finished items
+ * stay in history (status `done`) until cleared so the UI can offer replay.
+ *
+ * Providers plug in via `PlaybackAdapter`s, so the queue never knows about
+ * Cartesia WebSockets or Groq blobs.
+ *
+ * Moved from matrx-frontend (features/audio/playback/playbackQueue.ts) into @ai-matrx/media so
+ * every app plays through ONE queue. A host may mirror snapshots (the web mirrors into Redux for
+ * its Media panel); React reads it through `useSpeech` / `usePlaybackSnapshot`.
+ */
+
+type Listener = (snapshot: PlaybackSnapshot) => void;
+interface EnqueueResult {
+    id: string;
+}
+/** Add a request to the queue. Plays immediately if nothing is active. */
+declare function enqueuePlayback(request: PlaybackRequest): EnqueueResult;
+declare function pausePlayback(): Promise<void>;
+declare function resumePlayback(): Promise<void>;
+/** Stop the active item (marks it done) and advance to the next queued item. */
+declare function skipPlayback(): Promise<void>;
+/** Play (or replay) a specific item now, taking over anything active. */
+declare function playPlaybackItem(id: string): Promise<void>;
+/** Remove an item. If it's the active one, advance. */
+declare function removePlaybackItem(id: string): Promise<void>;
+/** Stop everything and clear the queue + history. */
+declare function clearPlayback(): Promise<void>;
+declare function setPlaybackRate(value: number): void;
+declare function getPlaybackSnapshot(): PlaybackSnapshot;
+/** Test seam: drop every item and forget loaded engines. */
+declare function resetPlaybackForTests(): void;
+declare function subscribePlayback(listener: Listener): () => void;
+
+/**
+ * Playback Lock — app-wide single-OUTPUT arbitration.
+ *
+ * The output twin of `captureLock`. Just as only one mic capture may be live at
+ * a time, **only one thing may be producing audible playback at any instant,
+ * anywhere in the app.** Multiple playback paths exist (the unified
+ * `playbackQueue` for Speaker buttons, the streaming auto-voice
+ * `useCartesiaStreamingSpeaker`, xAI realtime, podcast PCM) and each one used to
+ * play independently — so a War Room read-aloud could stream over a queued
+ * utterance, two voices in your ear at once. This arbiter makes that
+ * structurally impossible.
+ *
+ * Claiming is **start-always-wins**: a new claim instantly stops the current
+ * holder (its `stop` runs synchronously) and takes ownership. Framework-free,
+ * allocates nothing until first use, holds no audio itself — it only tracks who
+ * currently owns playback and how to stop them.
+ *
+ * Contract for holders (mirror of captureLock):
+ *  - Stable id per path (constant for a singleton owner, `useId()` per instance).
+ *  - `claimPlayback({ id, stop })` right before producing audio.
+ *  - `releasePlayback(id)` when playback ends (finished, stopped, errored,
+ *    unmounted). Release is id-guarded — a stale release is a safe no-op.
+ *  - `stop` MUST be synchronous-effective (stop audio now).
+ *
+ * Subscribers get a `PlaybackTakeover` describing the holder change, which the
+ * AudioPlaybackHost uses to surface the Audio panel whenever playback gets
+ * "complex" (a cross-path takeover).
+ */
+interface PlaybackHolder {
+    /** Stable identifier for the claiming playback path / instance. */
+    id: string;
+    /** Optional human label for diagnostics / the panel indicator. */
+    label?: string;
+    /** Stop audio immediately. Called when another path takes over. */
+    stop: () => void;
+}
+interface PlaybackTakeover {
+    /** The holder that now owns playback, or null when playback went idle. */
+    current: PlaybackHolder | null;
+    /** The holder that was stopped to grant ownership, if this was a takeover. */
+    preempted: PlaybackHolder | null;
+}
+/**
+ * Claim exclusive playback (start-always-wins). If a different holder currently
+ * owns playback, its `stop()` runs first (synchronously) so two outputs can
+ * never overlap. Re-claiming with the SAME id just refreshes the registration.
+ */
+declare function claimPlayback(holder: PlaybackHolder): void;
+/**
+ * Release playback for `id`. Id-guarded: if `id` is not the current owner (it
+ * was already taken over), this is a no-op.
+ */
+declare function releasePlayback(id: string): void;
+/** The id of the path currently holding playback, or null if idle. */
+declare function getActivePlaybackHolderId(): string | null;
+/** True while any path holds playback. */
+declare function isPlaybackHeld(): boolean;
+/** Subscribe to playback ownership changes. Returns an unsubscribe fn. */
+declare function subscribePlaybackLock(cb: (event: PlaybackTakeover) => void): () => void;
+
+/**
+ * unlock.ts — THE iOS/WebKit audio-output unlock primitive.
+ *
+ * WHY THIS EXISTS (mobile-silence class, 2026-08-30)
+ * --------------------------------------------------
+ * On iOS every browser is WebKit (Chrome and Firefox on iPhone included), and
+ * WebKit enforces two rules desktop browsers don't:
+ *
+ *   1. An `AudioContext` created (or resumed) OUTSIDE a user gesture starts
+ *      `suspended` and stays silent. Our TTS starts audio from websocket
+ *      callbacks seconds after the tap, so every utterance scheduled into a
+ *      fresh per-utterance context played into a suspended context — total
+ *      silence on iPhone while desktop worked fine.
+ *   2. Web Audio output is muted by the ringer/silent switch unless the page
+ *      declares a playback audio session (`navigator.audioSession.type =
+ *      "playback"`, iOS 16.4+).
+ *
+ * THE FIX: capture a real user gesture ONCE, and inside it (synchronously)
+ *   - declare the playback audio session,
+ *   - create ONE shared `AudioContext`, resume it, and play a one-frame
+ *     silent buffer through it (the classic unlock), and
+ *   - prime ONE shared `HTMLAudioElement` with a muted play() so element
+ *     playback (the catalog engine) is also user-activated.
+ *
+ * Consumers then REUSE the shared unlocked context/element instead of minting
+ * fresh ones outside a gesture:
+ *   - `SinkAwarePlayer` schedules through `getUnlockedAudioContext()` when it
+ *     exists (per-utterance GainNode; the context is never closed).
+ *   - `catalogAdapter` plays through `getPrimedMediaElement()` when it exists.
+ *
+ * Two entry points, both idempotent and framework-free:
+ *   - `installAudioUnlockListeners()` — capture-phase pointerdown/keydown
+ *     listeners that unlock on the user's FIRST interaction anywhere. Mounted
+ *     once at app root (AudioPlaybackHost), so by the time any audio plays,
+ *     the page is almost always already unlocked.
+ *   - `primeAudioOutput()` — explicit call at the top of every audio-starting
+ *     gesture handler (speak(), the Listen actions, transport buttons) as the
+ *     belt-and-suspenders for taps the global listener could miss.
+ *
+ * Everything feature-detects: on desktop this is a no-op-cost shared context
+ * that behaves identically to before.
+ *
+ * THE CATEGORY IS SEQUENCED, NOT SHARED (2026-09-17)
+ * -------------------------------------------------
+ * `"playback"` is the OUTPUT category, and WebKit refuses every
+ * `getUserMedia({audio})` under it ("AudioSession category is not compatible
+ * with audio capture" — the /chat voice-input failure on iPhone). Capture needs
+ * `"play-and-record"`. This file never touches capture: the package's mic
+ * manager (`@ai-matrx/browser-audio` ≥ 0.4.0) switches the category right
+ * before its own capture and restores whatever this file declared once the
+ * microphone stops. Never make this file "smarter" about capture, and never
+ * declare the category from a recording surface — one owner per direction.
+ */
+/**
+ * The ONE shared output context, unlocked by a user gesture. Null until the
+ * first `primeAudioOutput()` (or global-listener) gesture ran.
+ */
+declare function getUnlockedAudioContext(): AudioContext | null;
+/**
+ * The ONE shared media element, user-activated by a muted play(). Null until
+ * primed. Reused by element-based playback so `.play()` outside a gesture is
+ * allowed on WebKit (activation is per-element).
+ */
+declare function getPrimedMediaElement(): HTMLAudioElement | null;
+/**
+ * Unlock audio output. MUST be called synchronously inside a user-gesture
+ * call stack to have its full effect; safe (and cheap) to call any time.
+ */
+declare function primeAudioOutput(): void;
+/**
+ * Install capture-phase first-interaction listeners that unlock audio on ANY
+ * tap/keypress. Idempotent; the listeners stay installed (re-priming after
+ * the OS suspends the page costs nothing and heals `interrupted` contexts).
+ */
+declare function installAudioUnlockListeners(): void;
+
+type SinkListener = (deviceId: string) => void;
+/** True when `HTMLMediaElement.setSinkId` exists (Chrome/Firefox, not Safari). */
+declare function mediaElementSinkSupported(): boolean;
+/** True when `AudioContext.setSinkId` exists (Chromium only). */
+declare function audioContextSinkSupported(): boolean;
+/**
+ * True when the browser can route output at all (either API). When false, the
+ * speaker picker is disabled and the user is told to choose output in OS
+ * settings.
+ */
+declare function outputSelectionSupported(): boolean;
+/** Read the current preferred output deviceId ("" = system default). */
+declare function getPreferredOutputDeviceId(): string;
+/**
+ * Set the preferred output device. Notifies subscribers (InlineMediaRef
+ * re-applies to its live media elements; SinkAwarePlayer re-routes any live
+ * playback context mid-utterance). Idempotent — a no-op when unchanged.
+ */
+declare function setPreferredOutputDeviceId(deviceId: string): void;
+/** Subscribe to preferred-output changes. Returns an unsubscribe fn. */
+declare function subscribeOutputDevice(listener: SinkListener): () => void;
+/**
+ * Apply the current preferred sink to one `HTMLMediaElement`. Feature-detected;
+ * on Safari (no `setSinkId`) or "" (system default) it's a clean no-op. A real
+ * failure (e.g. the device vanished) is reported loudly, never swallowed — the
+ * element keeps playing on the default device.
+ */
+declare function applySinkToMediaElement(el: HTMLMediaElement | null | undefined): Promise<void>;
+
+/**
+ * The slice of the Cartesia `Source` contract the player actually consumes.
+ * Structural — `@cartesia/cartesia-js`'s `Source` satisfies it — so the
+ * player has no hard SDK type dependency and is unit-testable with a stub.
+ */
+interface PlayableSource {
+    readonly sampleRate: number;
+    /** Read up to `dst.length` samples; resolves with the count actually read.
+     *  A short read (< dst.length) signals the end of the source. */
+    read(dst: Float32Array): Promise<number>;
+    /** Number of samples covering `durationSecs` at this source's sample rate. */
+    durationToSampleCount(durationSecs: number): number;
+}
+/** Minimal AudioContext surface the player uses — injectable for tests. */
+interface SinkAwareAudioContext {
+    readonly currentTime: number;
+    readonly state: AudioContextState;
+    readonly destination: AudioNode;
+    createBufferSource(): AudioBufferSourceNode;
+    createBuffer(channels: number, length: number, sampleRate: number): AudioBuffer;
+    suspend(): Promise<void>;
+    resume(): Promise<void>;
+    close(): Promise<void>;
+    /** Chromium-only; absent on Firefox/Safari. */
+    setSinkId?: (deviceId: string) => Promise<void>;
+}
+interface SinkAwarePlayerOptions {
+    /** Seconds of audio to buffer per scheduling chunk (same as the SDK). */
+    bufferDuration: number;
+    /**
+     * Test seam: build the per-utterance context. Defaults to
+     * `new AudioContext({ sampleRate })`.
+     */
+    createContext?: (sampleRate: number) => SinkAwareAudioContext;
+}
+declare class SinkAwarePlayer {
+    #private;
+    constructor({ bufferDuration, createContext }: SinkAwarePlayerOptions);
+    /**
+     * Play audio from a source. Resolves when the audio has finished playing.
+     *
+     * Prefers the app's shared gesture-unlocked context (required for sound on
+     * iOS/WebKit); otherwise builds a fresh AudioContext per call (matching the
+     * SDK). Either way the output is routed to the user's preferred device and
+     * re-routed live on device change. Web Audio resamples per-buffer, so the
+     * shared context's hardware rate plays 44.1k sources correctly.
+     */
+    play(source: PlayableSource): Promise<void>;
+    /** Suspend playback. Throws before the first play (contract parity). */
+    pause(): Promise<void>;
+    /** Resume suspended playback. Throws before the first play. */
+    resume(): Promise<void>;
+    /** Pause when running, resume otherwise. Throws before the first play. */
+    toggle(): Promise<void>;
+    /**
+     * Stop playback. Throws before the first play (contract parity); a repeat
+     * stop is a silent no-op.
+     *
+     * Owned-context mode closes the context (the SDK contract). Shared mode
+     * NEVER closes the app-wide unlocked context — it stops this utterance's
+     * scheduled sources and tears down its GainNode, and resumes the context
+     * if this utterance had paused it (a suspended shared context would mute
+     * the NEXT utterance too).
+     */
+    stop(): Promise<void>;
+}
+
+/**
+ * THE single way to open a Cartesia TTS websocket from a browser (moved from matrx-frontend
+ * lib/cartesia/connection.ts; token, failure report and toast arrive through configureSpeech).
+ *
+ * Cartesia v4 exposes a snake_case, event based websocket. The rest of the
+ * app intentionally keeps one small, stable streaming contract, so SDK
+ * upgrades stay contained here instead of leaking through every TTS hook.
+ */
+
+/**
+ * A provider session failure carrying the server's verdict: `message` is the sentence to show
+ * (the provider's raw text when the report failed), and `retryable` says whether reconnecting helps.
+ */
+declare class ProviderSessionError extends Error {
+    readonly name = "ProviderSessionError";
+    readonly provider: ProviderSessionFailure["provider"];
+    readonly retryable: boolean;
+    readonly errorType: string | null;
+    readonly reported: boolean;
+    constructor(failure: ProviderSessionFailure, verdict: ProviderSessionFailureVerdict | null, fallbackMessage: string, options?: {
+        cause?: unknown;
+    });
+}
+/** True when the provider rejected the token (refresh once and retry). */
+declare function isCartesiaAuthError(error: unknown): boolean;
+interface CartesiaTtsSocketOptions {
+    container?: string;
+    encoding?: string;
+    sampleRate?: number;
+}
+type CartesiaTtsVoice = {
+    mode: "id";
+    id: string;
+};
+interface CartesiaTtsRequest {
+    modelId: string;
+    transcript: string;
+    voice: CartesiaTtsVoice;
+    language?: SupportedLanguage;
+    contextId?: string;
+    continue?: boolean;
+    addTimestamps?: boolean;
+    addPhonemeTimestamps?: boolean;
+    maxBufferDelayMs?: number;
+    generationConfig?: GenerationConfig;
+}
+type MessageListener = (message: string) => void;
+/** The structural source consumed by SinkAwarePlayer. */
+declare class CartesiaAudioSource {
+    #private;
+    readonly sampleRate: number;
+    constructor(sampleRate: number);
+    durationToSampleCount(durationSecs: number): number;
+    push(bytes: Uint8Array): void;
+    finish(): void;
+    read(destination: Float32Array): Promise<number>;
+}
+interface CartesiaTtsResponse {
+    source: CartesiaAudioSource;
+    on(event: "message", listener: MessageListener): void;
+}
+interface CartesiaConnectionCtx {
+    on(event: "close", listener: () => void): void;
+}
+interface CartesiaTtsSocket {
+    send(request: CartesiaTtsRequest): Promise<CartesiaTtsResponse>;
+    continue(request: CartesiaTtsRequest): Promise<CartesiaTtsResponse>;
+    disconnect(): void;
+}
+/** Open a connected socket, refreshing a rejected broker token once. */
+declare function connectCartesiaTts(options?: CartesiaTtsSocketOptions): Promise<{
+    ws: CartesiaTtsSocket;
+    ctx: CartesiaConnectionCtx;
+}>;
+
+/**
+ * Cartesia playback adapter.
+ *
+ * Imperative twin of `useCartesiaSpeaker.speak()`: token → WebSocket → send →
+ * SinkAwarePlayer. Lives outside React so the singleton `playbackQueue` can
+ * drive it. Output device routing is owned by the player itself — it applies
+ * the preferred speaker at context creation and re-routes mid-utterance on
+ * device change (see features/audio/sinkAwarePlayer.ts).
+ *
+ * Note: Cartesia "speed" is a synthesis-time parameter, so live rate changes are
+ * not supported (no `setRate`). The queue's global rate is captured into the
+ * synthesis `speed` at enqueue time by the consumer instead.
+ */
+
+/** Cartesia generation config from the person's speed / emotion. */
+declare function buildGenerationConfig(opts?: {
+    speed?: number | null;
+    volume?: number | null;
+    emotion?: string | null;
+}): {
+    speed: number;
+    volume: number;
+    emotion?: string;
+};
+declare const cartesiaAdapter: PlaybackAdapter;
+
+export { type ActivePlayback, CartesiaAudioSource, type CartesiaConnectionCtx, type CartesiaTtsRequest, type CartesiaTtsResponse, type CartesiaTtsSocket, type CartesiaTtsSocketOptions, type CartesiaTtsVoice, type EnqueueResult, type PlayableSource, type PlaybackAdapter, type PlaybackAdapterCallbacks, type PlaybackHolder, type PlaybackItem, type PlaybackItemStatus, type PlaybackProvider, type PlaybackRequest, type PlaybackSnapshot, type PlaybackTakeover, ProviderSessionError, type SinkAwareAudioContext, SinkAwarePlayer, type SinkAwarePlayerOptions, type SpeakRequest, type SpeakResult, type SpeechPorts, type SpeechVoiceSettings, applySinkToMediaElement, audioContextSinkSupported, buildGenerationConfig, cartesiaAdapter, claimPlayback, clearPlayback, configureSpeech, connectCartesiaTts, enqueuePlayback, getActivePlaybackHolderId, getPlaybackSnapshot, getPreferredOutputDeviceId, getPrimedMediaElement, getUnlockedAudioContext, installAudioUnlockListeners, isCartesiaAuthError, isPlaybackHeld, mediaElementSinkSupported, outputSelectionSupported, pausePlayback, playPlaybackItem, primeAudioOutput, releasePlayback, removePlaybackItem, resetPlaybackForTests, resetSpeechPortsForTests, resolveSpeakEngine, resumePlayback, setPlaybackRate, setPreferredOutputDeviceId, skipPlayback, speak, subscribeOutputDevice, subscribePlayback, subscribePlaybackLock };