@happyvertical/speech 0.96.1 → 0.98.0

package/dist/shared/streaming-types.d.ts

@@ -0,0 +1,303 @@
+import { TranscriptResult } from './types.js';
+import { SpeechUsageCallback } from './usage.js';
+import { SpeechWebSocketConstructor, SpeechWebSocketFactory } from './websocket.js';
+/** Streaming adapter identifiers. */
+export type StreamingTranscriberType = 'openai-realtime' | 'voxtral-realtime';
+/**
+ * Raw audio sample encodings. Streaming adapters never decode containers
+ * (WebM, MP4, Ogg) or resample: callers send audio in the negotiated format.
+ *
+ * - `pcm16`: signed 16-bit little-endian PCM, interleaved when multi-channel.
+ * - `g711_ulaw` / `g711_alaw`: 8-bit G.711 companded audio.
+ */
+export type StreamingAudioEncoding = 'pcm16' | 'g711_ulaw' | 'g711_alaw';
+/** Explicit audio format for a streaming session. */
+export interface StreamingAudioFormat {
+    encoding: StreamingAudioEncoding;
+    /** Samples per second, e.g. `24000`. */
+    sampleRate: number;
+    /** Channel count. Realtime providers generally require mono (`1`). */
+    channels: number;
+}
+/**
+ * Turn detection (voice activity detection).
+ *
+ * - `server_vad`: the provider commits a turn after `silenceDurationMs` of
+ *   silence and emits a `final` per turn. The default for live sessions.
+ * - `semantic_vad`: the provider decides turn ends from content.
+ * - `manual`: nothing is committed until `session.commit()` or `end()`. The
+ *   default for the record-then-send `Transcriber` wrapper.
+ */
+export type StreamingTurnDetection = {
+    type: 'server_vad';
+    /** Activation threshold 0-1. Provider default `0.5`. */
+    threshold?: number;
+    /** Audio kept before detected speech. Provider default `300`. */
+    prefixPaddingMs?: number;
+    /** Silence that ends a turn. Provider default `500`. */
+    silenceDurationMs?: number;
+} | {
+    type: 'semantic_vad';
+    eagerness?: 'low' | 'medium' | 'high' | 'auto';
+} | {
+    type: 'manual';
+};
+/** Audio accepted by {@link StreamingSession.write}. `Buffer` is a `Uint8Array`. */
+export type StreamingAudioChunk = Uint8Array | ArrayBuffer | ArrayBufferView;
+/**
+ * A short-lived browser credential, or a function that mints one per session
+ * (for example by calling your server, which asks the provider for an
+ * ephemeral client secret scoped to the current tenant).
+ */
+export type StreamingClientSecret = string | (() => string | Promise<string>);
+/** Settings shared by adapter construction and individual sessions. */
+export interface StreamingSessionSettings {
+    /** Transcription model. */
+    model?: string;
+    /** ISO-639-1 language hint, e.g. `en`. */
+    language?: string;
+    /** Vocabulary or style prompt. */
+    prompt?: string;
+    /** Turn detection. Adapter default `server_vad`. */
+    turnDetection?: StreamingTurnDetection;
+    /** Audio format; unset fields use the adapter default. */
+    format?: Partial<StreamingAudioFormat>;
+    /**
+     * Extra headers sent on the WebSocket handshake (e.g. gateway `x-bf-vk`).
+     * Node-only: browsers cannot set WebSocket headers.
+     */
+    headers?: HeadersInit;
+    /** Short-lived credential sent as a WebSocket subprotocol (browser-safe). */
+    clientSecret?: StreamingClientSecret;
+    /** Called with aggregated usage when `end()` succeeds. */
+    onUsage?: SpeechUsageCallback;
+    /**
+     * Most audio one turn may hold, in seconds, for providers whose context is
+     * per turn. `voxtral-realtime` defaults to `270` (headroom under vLLM's
+     * `max_model_len` 4096). `openai-realtime` has no default and applies it
+     * only to `manual` sessions, where it is opt-in; server VAD ends turns
+     * there. `Infinity` removes the limit. Env
+     * `HAVE_SPEECH_STREAMING_MAX_TURN_SECONDS`.
+     */
+    maxTurnSeconds?: number;
+    /**
+     * What happens when a turn reaches `maxTurnSeconds`. Default `true`: the
+     * session commits the turn at a quiet boundary (or at the cap when none is
+     * found), emits its `final`, and continues in a new turn without losing
+     * audio. `false`: a `write()` that would push the turn past the cap rejects
+     * with the non-fatal code `SPEECH_TURN_TOO_LONG`; call `commit()` and keep
+     * writing. An object enables rollover with tuning.
+     */
+    rollover?: boolean | StreamingRolloverOptions;
+}
+/** Tuning for automatic turn rollover. */
+export interface StreamingRolloverOptions {
+    /**
+     * How long before `maxTurnSeconds` to start looking for a quiet boundary.
+     * Default `15`.
+     */
+    windowSeconds?: number;
+    /**
+     * RMS level, from 0 to 1 of full scale, below which a 20 ms frame counts as
+     * quiet. Default `0.01` (about -40 dBFS).
+     */
+    silenceThreshold?: number;
+    /** Continuous quiet audio needed to commit early. Default `300`. */
+    minSilenceMs?: number;
+}
+/** The per-turn audio limit a session enforces; see `maxTurnSeconds`. */
+export interface StreamingTurnLimit {
+    maxTurnSeconds: number;
+    /** `true` when the session rolls over, `false` when writes past the cap reject. */
+    rollover: boolean;
+    /** The cap in bytes of the session's audio format (whole sample frames). */
+    maxTurnBytes: number;
+}
+/** Options for {@link StreamingTranscriber.start}. Values override adapter defaults. */
+export interface StreamingSessionOptions extends StreamingSessionSettings {
+    /** Aborting fails the session and closes the socket. */
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+}
+/** Session lifecycle states. `closed` and `failed` are terminal. */
+export type StreamingSessionState = 'connecting' | 'open' | 'ending' | 'closed' | 'failed';
+export interface StreamingPartialEvent {
+    /** Newly recognised text. */
+    delta: string;
+    /** Text recognised so far for this turn (all deltas joined). */
+    text: string;
+    /** Provider turn/item id, when the protocol has one. */
+    itemId?: string;
+}
+export interface StreamingFinalEvent {
+    /** Final text for one committed turn. */
+    text: string;
+    itemId?: string;
+    /** Provider usage block for this turn, passed through untouched. */
+    providerUsage?: Record<string, unknown>;
+    raw?: unknown;
+}
+export interface StreamingSpeechEvent {
+    itemId?: string;
+    /** Offset into the session audio, in milliseconds. */
+    audioMs?: number;
+}
+export interface StreamingCloseEvent {
+    code: number;
+    reason: string;
+}
+/** Events emitted by a {@link StreamingSession}. */
+export interface StreamingSessionEvents {
+    /** The socket is open and the session configuration has been sent. */
+    open: {
+        sessionId?: string;
+    };
+    partial: StreamingPartialEvent;
+    final: StreamingFinalEvent;
+    speech_started: StreamingSpeechEvent;
+    speech_stopped: StreamingSpeechEvent;
+    /**
+     * A fatal session error. Emitted once; `end()` and pending `write()` calls
+     * reject with the same error.
+     */
+    error: Error;
+    /** The socket closed (normally after `end()`, or unexpectedly). */
+    close: StreamingCloseEvent;
+}
+export type StreamingSessionEventName = keyof StreamingSessionEvents;
+export type StreamingSessionListener<E extends StreamingSessionEventName> = (event: StreamingSessionEvents[E]) => void;
+/**
+ * One realtime transcription session over a WebSocket.
+ *
+ * **Backpressure.** `write()` returns a promise that resolves once the chunk
+ * has been handed to the socket and the socket's send buffer has drained to
+ * `highWaterMark` or below. Await each write to stream at the rate the network
+ * accepts. Writes are queued in order, including before the socket opens; a
+ * write that would push queued, unsent audio past `maxBufferedBytes` rejects
+ * instead of growing memory without bound.
+ *
+ * **Reconnect policy.** None. The provider holds the audio buffer and turn
+ * state, so a mid-session socket drop cannot be resumed without losing or
+ * duplicating text. An unexpected close fails the session: queued audio is
+ * discarded, pending `write()` calls and `end()` reject with a
+ * `SpeechProviderError`, and `error` then `close` are emitted. Start a new
+ * session to continue; finals already emitted remain valid.
+ */
+export interface StreamingSession {
+    readonly state: StreamingSessionState;
+    /** Provider session id, once known. */
+    readonly sessionId?: string;
+    /** Resolves when the session is open; rejects if it fails first. */
+    readonly ready: Promise<void>;
+    /** Queued audio bytes not yet handed to the socket. */
+    readonly queuedBytes: number;
+    /**
+     * Queues audio in the session's negotiated format. See backpressure above.
+     * With a turn limit and `rollover: false`, rejects with the non-fatal
+     * `SPEECH_TURN_TOO_LONG` instead of letting the current turn grow past it.
+     */
+    write(chunk: StreamingAudioChunk): Promise<void>;
+    /** Ends the current turn now (manual turn detection). Ordered after queued writes. */
+    commit(): void;
+    /**
+     * Flushes queued audio, commits any uncommitted audio, waits for every
+     * pending turn's final transcript (bounded by `timeoutMs`), closes the
+     * socket, and resolves with the joined transcript and usage. Idempotent.
+     */
+    end(): Promise<TranscriptResult>;
+    /** Fails the session immediately and closes the socket. */
+    abort(reason?: unknown): void;
+    /** Adds a listener; returns a function that removes it. */
+    on<E extends StreamingSessionEventName>(event: E, listener: StreamingSessionListener<E>): () => void;
+    off<E extends StreamingSessionEventName>(event: E, listener: StreamingSessionListener<E>): void;
+}
+/** Factory for realtime sessions against one configured provider. */
+export interface StreamingTranscriber {
+    readonly type: StreamingTranscriberType;
+    /** Default audio format for new sessions. */
+    readonly audioFormat: StreamingAudioFormat;
+    /** Opens a session. Connection happens in the background; see `session.ready`. */
+    start(options?: StreamingSessionOptions): StreamingSession;
+    /**
+     * The per-turn limit a session started with `options` would enforce, or
+     * `undefined` when its turns are unbounded. Throws like `start()` on an
+     * invalid limit. Optional for custom implementations.
+     */
+    turnLimit?(options?: StreamingSessionOptions): StreamingTurnLimit | undefined;
+}
+/** Adapter options shared by WebSocket streaming transcribers. */
+export interface StreamingTranscriberOptions extends StreamingSessionSettings {
+    /**
+     * WebSocket URL or HTTP(S) base URL. `http` becomes `ws` and `https`
+     * becomes `wss`. A server root gets `/v1/realtime`; a base ending in a
+     * version segment gets `/realtime`; a URL ending in `/realtime` is used as-is.
+     */
+    baseUrl?: string;
+    /**
+     * Long-lived API key sent as `Authorization: Bearer`. Node-only: refused in
+     * browsers. Browsers use `clientSecret`.
+     */
+    apiKey?: string;
+    /**
+     * Maximum provider inactivity while waiting for final transcripts after
+     * `end()` (every server message restarts it), and maximum wait for a
+     * congested socket to drain during `write()`. Default `30000`.
+     */
+    timeoutMs?: number;
+    /** Maximum wait for the socket to open. Default `10000`. */
+    connectTimeoutMs?: number;
+    /** Socket send-buffer size at which `write()` waits. Default 1 MiB. */
+    highWaterMark?: number;
+    /** Queued, unsent audio at which `write()` rejects. Default 16 MiB. */
+    maxBufferedBytes?: number;
+    /**
+     * WebSocket constructor. Defaults to `globalThis.WebSocket` (Node 22+,
+     * browsers, Deno, Bun). Handshake headers are passed as
+     * `new WebSocket(url, { protocols, headers })`, which Node's built-in
+     * WebSocket supports; use `createWebSocket` for other clients such as `ws`.
+     */
+    WebSocket?: SpeechWebSocketConstructor;
+    /** Full control over socket creation; wins over `WebSocket`. */
+    createWebSocket?: SpeechWebSocketFactory;
+}
+/** Options for the `openai-realtime` adapter. */
+export interface OpenAIRealtimeTranscriberOptions extends StreamingTranscriberOptions {
+    type?: 'openai-realtime';
+    /** Default `wss://api.openai.com/v1/realtime`. */
+    baseUrl?: string;
+    /** Default `gpt-4o-transcribe`. */
+    model?: string;
+    /** `audio.input.noise_reduction.type`. Omitted by default. */
+    noiseReduction?: 'near_field' | 'far_field';
+    /** Session `include` list, e.g. `['item.input_audio_transcription.logprobs']`. */
+    include?: string[];
+    /**
+     * Extra fields merged into `audio.input.transcription`, e.g.
+     * `{ delay: 'low', languages: ['en', 'fr'] }` for `gpt-live-transcribe`.
+     * The typed `model`, `language`, and `prompt` settings take precedence.
+     */
+    transcriptionOptions?: Record<string, unknown>;
+}
+/**
+ * Options for the `voxtral-realtime` adapter (vLLM's `/v1/realtime`). Audio is
+ * fixed at PCM16 16 kHz mono and turns are manual; `language` and `prompt`
+ * are not sent because vLLM's realtime session accepts only `model`.
+ */
+export interface VoxtralRealtimeTranscriberOptions extends StreamingTranscriberOptions {
+    type?: 'voxtral-realtime';
+    /**
+     * Required: the vLLM server root (`http://host:8000`), its `/v1` API root,
+     * or the full `ws(s)://…/v1/realtime` URL.
+     */
+    baseUrl?: string;
+    /**
+     * The model name vLLM serves, e.g. a `--served-model-name`. Default
+     * `mistralai/Voxtral-Mini-4B-Realtime-2602`.
+     */
+    model?: string;
+}
+/** Options accepted by `getStreamingTranscriber()`. */
+export interface GetStreamingTranscriberOptions extends Omit<OpenAIRealtimeTranscriberOptions, 'type'> {
+    type?: StreamingTranscriberType;
+}
+//# sourceMappingURL=streaming-types.d.ts.map

package/dist/shared/streaming-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-types.d.ts","sourceRoot":"","sources":["../../src/shared/streaming-types.ts"],"names":[],"mappings":"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"}

package/dist/shared/turn-limit.d.ts

@@ -0,0 +1,84 @@
+import { StreamingAudioFormat, StreamingSessionSettings, StreamingTurnLimit } from './streaming-types.js';
+/** Default per-turn audio cap for providers that need one (`voxtral-realtime`). */
+export declare const DEFAULT_MAX_TURN_SECONDS = 270;
+/** How long before the cap the rollover starts looking for silence. */
+export declare const DEFAULT_ROLLOVER_WINDOW_SECONDS = 15;
+/** RMS level (0-1 of full scale, about -40 dBFS) below which audio is quiet. */
+export declare const DEFAULT_ROLLOVER_SILENCE_THRESHOLD = 0.01;
+/** Quiet audio needed before the rollover commits. */
+export declare const DEFAULT_ROLLOVER_MIN_SILENCE_MS = 300;
+/** A resolved per-turn limit; `undefined` means turns are unbounded. */
+export interface TurnLimit {
+    maxTurnSeconds: number;
+    /** `false`: writes past the cap reject with `SPEECH_TURN_TOO_LONG`. */
+    rollover: boolean;
+    windowSeconds: number;
+    silenceThreshold: number;
+    minSilenceMs: number;
+}
+/**
+ * Resolves the turn limit from settings, highest priority first (session
+ * options, then adapter options, which already carry environment values),
+ * falling back to `defaultMaxTurnSeconds`. Returns `undefined` when no limit
+ * applies or `maxTurnSeconds` is `Infinity`.
+ */
+export declare function resolveTurnLimit(adapter: string, defaultMaxTurnSeconds: number | undefined, ...settings: Array<Pick<StreamingSessionSettings, 'maxTurnSeconds' | 'rollover'> | undefined>): TurnLimit | undefined;
+/** Bytes of one sample frame (one sample per channel). */
+export declare function blockAlign(format: StreamingAudioFormat): number;
+/** Whole sample frames in `seconds` of audio, as bytes (rounded down). */
+export declare function bytesForSeconds(seconds: number, format: StreamingAudioFormat): number;
+/** Digital silence in `format`: zero samples, encoded. */
+export declare function silence(bytes: number, format: StreamingAudioFormat): Uint8Array;
+/** Bytes of audio one turn may hold: whole sample frames, at least one. */
+export declare function turnCapBytes(limit: TurnLimit, format: StreamingAudioFormat): number;
+/** The public view of a resolved limit for a session format. */
+export declare function describeTurnLimit(limit: TurnLimit | undefined, format: StreamingAudioFormat): StreamingTurnLimit | undefined;
+/**
+ * Tracks the audio of the current turn and finds rollover points.
+ *
+ * Feed every chunk in write order to {@link split} (rollover on) or
+ * {@link add} (rollover off), and call {@link reset} whenever the turn ends
+ * for another reason (a manual commit).
+ */
+export declare class TurnSplitter {
+    /** Bytes of the current turn so far. */
+    turnBytes: number;
+    readonly capBytes: number;
+    private readonly windowStartBytes;
+    private readonly frameBytes;
+    private readonly minSilenceBytes;
+    private readonly threshold;
+    private readonly encoding;
+    private readonly sampleBytes;
+    private frameFill;
+    private frameSumSquares;
+    private frameSamples;
+    /** Trailing bytes of a sample split across chunks. */
+    private carry;
+    /** Consecutive quiet bytes ending at the last complete frame. */
+    private quietRun;
+    constructor(limit: TurnLimit, format: StreamingAudioFormat);
+    /** Ends the current turn: the next byte starts a new one. */
+    reset(): void;
+    /** Whether `bytes` more would push the current turn past the cap. */
+    wouldOverflow(bytes: number): boolean;
+    /** Counts `bytes` toward the current turn without analysing them. */
+    add(bytes: number): void;
+    /**
+     * Feeds one chunk and returns the offsets inside it where the turn should
+     * end (each in `1..chunk.byteLength`, ascending). The splitter resets at
+     * each offset, so bytes after it count toward the next turn.
+     */
+    split(chunk: Uint8Array): number[];
+    private frameIsQuiet;
+    private measure;
+    private addSample;
+    private addSampleAt;
+    private addLinear;
+    private decodeG711;
+}
+/** G.711 mu-law byte to a 16-bit linear sample (ITU-T G.711). */
+export declare function decodeMuLaw(byte: number): number;
+/** G.711 A-law byte to a 16-bit linear sample (ITU-T G.711). */
+export declare function decodeALaw(byte: number): number;
+//# sourceMappingURL=turn-limit.d.ts.map

package/dist/shared/turn-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-limit.d.ts","sourceRoot":"","sources":["../../src/shared/turn-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAEV,oBAAoB,EAEpB,wBAAwB,EACxB,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAE9B,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,uEAAuE;AACvE,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAClD,gFAAgF;AAChF,eAAO,MAAM,kCAAkC,OAAO,CAAC;AACvD,sDAAsD;AACtD,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAUnD,wEAAwE;AACxE,MAAM,WAAW,SAAS;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,qBAAqB,EAAE,MAAM,GAAG,SAAS,EACzC,GAAG,QAAQ,EAAE,KAAK,CAChB,IAAI,CAAC,wBAAwB,EAAE,gBAAgB,GAAG,UAAU,CAAC,GAAG,SAAS,CAC1E,GACA,SAAS,GAAG,SAAS,CA0DvB;AAWD,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAE/D;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,oBAAoB,GAC3B,MAAM,CAIR;AAED,0DAA0D;AAC1D,wBAAgB,OAAO,CACrB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,oBAAoB,GAC3B,UAAU,CAQZ;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,oBAAoB,GAC3B,MAAM,CAKR;AAED,gEAAgE;AAChE,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,MAAM,EAAE,oBAAoB,GAC3B,kBAAkB,GAAG,SAAS,CAQhC;AAED;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,wCAAwC;IACxC,SAAS,SAAK;IACd,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,YAAY,CAAK;IACzB,sDAAsD;IACtD,OAAO,CAAC,KAAK,CAAgB;IAC7B,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAK;gBAET,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,oBAAoB;IAoB1D,6DAA6D;IAC7D,KAAK,IAAI,IAAI;IASb,qEAAqE;IACrE,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIrC,qEAAqE;IACrE,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIxB;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE;IA+ClC,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,OAAO;IAoBf,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,UAAU;CAGnB;AAQD,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMhD;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS/C"}

package/dist/shared/types.d.ts

@@ -1,13 +1,32 @@
-export type SpeechAdapterType = 'studio-server' | 'qwen3-tts' | 'openai-compatible';
-export type TranscriberType = 'studio-server';
+import { LocalTranscriberSettings } from '../adapters/local/types.js';
+import { SpeechRetryOptions } from './retry.js';
+import { GetStreamingTranscriberOptions, StreamingTranscriberType } from './streaming-types.js';
+import { SpeechUsage, SpeechUsageCallback } from './usage.js';
+export type { SpeechRetryOptions } from './retry.js';
+export type { SpeechOperation, SpeechUsage, SpeechUsageCallback, } from './usage.js';
+export type SpeechAdapterType = 'studio-server' | 'qwen3-tts' | 'openai-compatible' | 'local' | StreamingTranscriberType;
+/**
+ * Request/response transcribers, including wrapped streaming adapters.
+ * `local` requires importing `@happyvertical/speech/local` first.
+ */
+export type TranscriberType = 'studio-server' | 'openai-compatible' | 'local' | StreamingTranscriberType;
 export type SpeechSynthesizerType = 'studio-server' | 'qwen3-tts' | 'openai-compatible';
 export interface SpeechAdapterAvailability {
     transcribers: TranscriberType[];
+    /** Adapters available through `getStreamingTranscriber()`. */
+    streamingTranscribers: StreamingTranscriberType[];
     synthesizers: SpeechSynthesizerType[];
 }
 export type AudioBytes = ArrayBuffer | Uint8Array | Blob;
+/**
+ * Raw audio accepted by transcribers. `Buffer` is a `Uint8Array` subclass.
+ * Streams are buffered (bounded by `maxBytes`) before upload.
+ */
+export type AudioSource = AudioBytes | ReadableStream<Uint8Array>;
 export interface AudioInput {
-    data: AudioBytes;
+    data: AudioSource;
+    /** MIME type, e.g. `audio/webm;codecs=opus`. Alias of `contentType`. */
+    mimeType?: string;
     contentType?: string;
     filename?: string;
     sampleRate?: number;
@@ -37,15 +56,30 @@ export interface TranscriptResult {
     provider?: string;
     model?: string;
     raw?: unknown;
+    /** Usage for billing/attribution, when the adapter reports it. */
+    usage?: SpeechUsage;
 }
+export type TranscriptionResponseFormat = 'json' | 'text' | 'verbose_json';
+export type TimestampGranularity = 'word' | 'segment';
 export interface TranscriptionRequest {
-    audio: AudioInput;
+    /** Audio wrapper, or a bare Blob/Buffer/Uint8Array/ArrayBuffer/ReadableStream. */
+    audio: AudioInput | AudioSource;
+    /** MIME type for bare audio sources; wins over `AudioInput` and Blob types. */
+    mimeType?: string;
     signal?: AbortSignal;
     language?: string;
     model?: string;
     prompt?: string;
     temperature?: number;
-    responseFormat?: 'json' | 'text' | 'verbose_json';
+    responseFormat?: TranscriptionResponseFormat;
+    /** Requested timestamp detail (OpenAI `timestamp_granularities[]`). */
+    timestampGranularities?: TimestampGranularity[];
+    /** Per-request headers, merged over adapter headers (e.g. a per-tenant `x-bf-vk`). */
+    headers?: HeadersInit;
+    /** Per-request byte limit; overrides the adapter `maxBytes`. */
+    maxBytes?: number;
+    /** Per-request usage callback, invoked after any adapter-level `onUsage`. */
+    onUsage?: SpeechUsageCallback;
     metadata?: Record<string, unknown>;
 }
 export interface SpeechVoice {
@@ -109,6 +143,28 @@ export interface StudioServerTranscriberOptions extends HttpSpeechOptions {
     type?: 'studio-server';
     transcribePath?: string;
 }
+/**
+ * Options for the OpenAI-compatible transcriber (`POST /audio/transcriptions`).
+ * Server-side only: the adapter holds the API key.
+ */
+export interface OpenAICompatibleTranscriberOptions extends HttpSpeechOptions {
+    type: 'openai-compatible';
+    /**
+     * Server root (`https://api.openai.com`), API root (`http://gateway/stt/v1`),
+     * or the full endpoint (`.../audio/transcriptions`).
+     */
+    baseUrl: string;
+    /** Default model. Default `whisper-1`. */
+    model?: string;
+    /** Default response format. Default `verbose_json` (or `json` for json-only models). */
+    responseFormat?: TranscriptionResponseFormat;
+    /** Upload limit in bytes. Default 25 MB; `Infinity` disables it. */
+    maxBytes?: number;
+    /** Retry policy for 429/5xx. Default 2 retries; `false` disables. */
+    retry?: SpeechRetryOptions | false;
+    /** Called with usage after every successful transcription. */
+    onUsage?: SpeechUsageCallback;
+}
 export interface StudioServerSpeechSynthesizerOptions extends HttpSpeechOptions {
     type: 'studio-server';
     synthesizePath?: string;
@@ -126,8 +182,30 @@ export interface OpenAICompatibleSpeechSynthesizerOptions extends HttpSpeechOpti
     defaultModel?: string;
     defaultVoice?: string;
 }
-export interface GetTranscriberOptions extends Partial<StudioServerTranscriberOptions> {
+/**
+ * Transcriber factory options. `local` settings (device, dtype, cacheDir, ...)
+ * apply only to `type: 'local'`.
+ */
+export interface GetTranscriberOptions extends Partial<HttpSpeechOptions>, Omit<LocalTranscriberSettings, 'model' | 'maxBytes' | 'onUsage'> {
     type?: TranscriberType;
+    /** Studio Server only. */
+    transcribePath?: string;
+    /** OpenAI-compatible and local. */
+    model?: string;
+    /** OpenAI-compatible only. */
+    responseFormat?: TranscriptionResponseFormat;
+    /** OpenAI-compatible and local. */
+    maxBytes?: number;
+    /** OpenAI-compatible only. */
+    retry?: SpeechRetryOptions | false;
+    /** OpenAI-compatible, local, and streaming types. */
+    onUsage?: SpeechUsageCallback;
+    /**
+     * Streaming types only (e.g. `openai-realtime`): extra adapter settings such
+     * as `turnDetection`, `WebSocket`, or `connectTimeoutMs`. Top-level fields
+     * win over these.
+     */
+    streaming?: Omit<GetStreamingTranscriberOptions, 'type'>;
 }
 export interface GetSpeechSynthesizerOptions extends Partial<HttpSpeechOptions> {
     type?: SpeechSynthesizerType;

package/dist/shared/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"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"}

package/dist/shared/usage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Usage reporting shared by speech adapters.
+ *
+ * Adapters attach a {@link SpeechUsage} record to their results and call the
+ * optional {@link SpeechUsageCallback} so callers can attribute each provider
+ * call (for example to a tenant for billing).
+ */
+export type SpeechOperation = 'transcription' | 'synthesis';
+export interface SpeechUsage {
+    /** Operation that produced this usage record. */
+    operation: SpeechOperation;
+    /** Adapter type that made the provider call, e.g. `openai-compatible`. */
+    provider: string;
+    /** Model identifier sent to (or reported by) the provider. */
+    model?: string;
+    /** Audio duration in seconds, when the provider or caller reports it. */
+    audioSeconds?: number;
+    /** Size of the audio payload in bytes (uploaded for STT, received for TTS). */
+    bytes?: number;
+    /** Provider usage block, passed through untouched (e.g. OpenAI `usage`). */
+    providerUsage?: Record<string, unknown>;
+}
+export type SpeechUsageCallback = (usage: SpeechUsage) => void | Promise<void>;
+/**
+ * Invokes every configured usage callback in order (adapter-level first, then
+ * request-level). Callback errors propagate to the caller so that billing
+ * hooks never fail silently.
+ */
+export declare function reportSpeechUsage(usage: SpeechUsage, ...callbacks: Array<SpeechUsageCallback | undefined>): Promise<void>;
+/**
+ * Extracts audio seconds from an OpenAI-style `usage` block
+ * (`{ type: 'duration', seconds }`).
+ */
+export declare function audioSecondsFromProviderUsage(providerUsage: Record<string, unknown> | undefined): number | undefined;
+//# sourceMappingURL=usage.d.ts.map

package/dist/shared/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/shared/usage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,WAAW,CAAC;AAE5D,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,SAAS,EAAE,eAAe,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/E;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,WAAW,EAClB,GAAG,SAAS,EAAE,KAAK,CAAC,mBAAmB,GAAG,SAAS,CAAC,GACnD,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACjD,MAAM,GAAG,SAAS,CASpB"}

package/dist/shared/websocket.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Minimal WebSocket surface used by streaming adapters. Browser, Node 22+
+ * (`globalThis.WebSocket`), Deno, Bun, and the `ws` package all satisfy it.
+ */
+/** `WebSocket.OPEN`. */
+export declare const WEBSOCKET_OPEN = 1;
+export interface SpeechWebSocketMessageEvent {
+    data: unknown;
+}
+export interface SpeechWebSocketCloseEvent {
+    code?: number;
+    reason?: string;
+}
+/** The subset of the WHATWG `WebSocket` interface the adapters use. */
+export interface SpeechWebSocket {
+    readonly readyState: number;
+    readonly bufferedAmount: number;
+    binaryType?: string;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'open', listener: (event: unknown) => void): void;
+    addEventListener(type: 'message', listener: (event: SpeechWebSocketMessageEvent) => void): void;
+    addEventListener(type: 'error', listener: (event: unknown) => void): void;
+    addEventListener(type: 'close', listener: (event: SpeechWebSocketCloseEvent) => void): void;
+}
+/** Handshake details passed to a {@link SpeechWebSocketFactory}. */
+export interface SpeechWebSocketInit {
+    protocols: string[];
+    /** Handshake headers; empty in browsers. */
+    headers: Record<string, string>;
+}
+export type SpeechWebSocketFactory = (url: string, init: SpeechWebSocketInit) => SpeechWebSocket;
+/**
+ * A WebSocket constructor. Standard constructors accept `protocols`; Node's
+ * built-in WebSocket also accepts `{ protocols, headers }`.
+ */
+export type SpeechWebSocketConstructor = new (url: string, protocols?: string | string[] | {
+    protocols?: string[];
+    headers?: Record<string, string>;
+}) => SpeechWebSocket;
+/** True in browsers and web workers, where API keys must never be used. */
+export declare function isBrowserRuntime(): boolean;
+/**
+ * Resolves a socket factory from explicit options, falling back to
+ * `globalThis.WebSocket`. Headers are only passed when present, so standard
+ * constructors that cannot send them are never handed an options object.
+ */
+export declare function resolveWebSocketFactory(adapter: string, options: {
+    createWebSocket?: SpeechWebSocketFactory;
+    WebSocket?: SpeechWebSocketConstructor;
+}): SpeechWebSocketFactory;
+/** Converts `http(s)://` to `ws(s)://`; leaves `ws(s)://` unchanged. */
+export declare function toWebSocketUrl(url: string, adapter: string): string;
+/** Converts a message payload to text; returns `undefined` for unsupported data. */
+export declare function messageDataToText(data: unknown): string | undefined;
+//# sourceMappingURL=websocket.d.ts.map