@happyvertical/speech 0.97.0 → 0.99.0

package/dist/adapters/local/transcriber.d.ts

@@ -0,0 +1,40 @@
+import { Transcriber, TranscriptionRequest, TranscriptResult } from '../../shared/types.js';
+import { AsrOutput } from './runtime.js';
+import { LocalTranscriberOptions } from './types.js';
+/** Small multilingual Whisper (~80 MB at the default q8 quantisation). */
+export declare const DEFAULT_LOCAL_MODEL = "onnx-community/whisper-base";
+/**
+ * On-device speech-to-text with transformers.js (Whisper or Moonshine ONNX).
+ * Runs on WebGPU/WASM in browsers and onnxruntime-node in Node; no audio
+ * leaves the device and no API key is involved.
+ */
+export declare class LocalTranscriber implements Transcriber {
+    readonly type: "local";
+    private readonly options;
+    private readonly model;
+    private readonly maxBytes;
+    private readonly onUsage?;
+    private runtime?;
+    private readonly pipelines;
+    /** Serialises inference: ONNX sessions (especially WebGPU) run one call at a time. */
+    private queue;
+    constructor(options?: LocalTranscriberOptions);
+    /**
+     * Downloads (first time) and initialises the model so the first
+     * `transcribe()` is fast. Progress goes to `onProgress`.
+     */
+    preload(model?: string, signal?: AbortSignal): Promise<void>;
+    transcribe(request: TranscriptionRequest): Promise<TranscriptResult>;
+    /** Waits for in-flight inference, then releases every loaded model session. */
+    dispose(): Promise<void>;
+    private run;
+    private enqueue;
+    private loadRuntime;
+    private loadPipeline;
+}
+/**
+ * Maps transformers.js chunks onto `words` (when word timestamps were
+ * requested) or `segments`.
+ */
+export declare function mapAsrOutput(output: AsrOutput, wordLevel: boolean): Pick<TranscriptResult, 'text' | 'segments' | 'words'>;
+//# sourceMappingURL=transcriber.d.ts.map

package/dist/adapters/local/transcriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcriber.d.ts","sourceRoot":"","sources":["../../../src/adapters/local/transcriber.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAGV,WAAW,EACX,oBAAoB,EACpB,gBAAgB,EAGjB,MAAM,uBAAuB,CAAC;AAQ/B,OAAO,EACL,KAAK,SAAS,EAKf,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,gCAAgC,CAAC;AAWjE;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,WAAW;IAClD,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;IAEjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAsB;IAC/C,OAAO,CAAC,OAAO,CAAC,CAA8B;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8C;IACxE,sFAAsF;IACtF,OAAO,CAAC,KAAK,CAAuC;gBAExC,OAAO,GAAE,uBAA4B;IAOjD;;;OAGG;IACG,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAwD1E,+EAA+E;IACzE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAYhB,GAAG;IAgEjB,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,WAAW;IAoBnB,OAAO,CAAC,YAAY;CA+BrB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,OAAO,GACjB,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,CA6BvD"}

package/dist/adapters/local/transformers-shim.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Type stub for the optional `@huggingface/transformers` peer, mapped through
+ * `paths` in tsconfig.json. The adapter uses its own structural types
+ * (`runtime.ts`) so the package typechecks without compiling the peer's
+ * declarations, which fail under this repo's `skipLibCheck: false` (4.3.0).
+ */
+export {};
+//# sourceMappingURL=transformers-shim.d.ts.map

package/dist/adapters/local/transformers-shim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformers-shim.d.ts","sourceRoot":"","sources":["../../../src/adapters/local/transformers-shim.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC"}

package/dist/adapters/local/types.d.ts

@@ -0,0 +1,92 @@
+import { SpeechUsageCallback } from '../../shared/usage.js';
+/**
+ * Inference device. `auto` picks WebGPU when the browser exposes a usable
+ * adapter (falling back to WASM if WebGPU fails to initialise) and `cpu` in
+ * Node. Other values are passed to transformers.js unchanged (Node also
+ * supports `cuda`, `dml`, `coreml`, and `webgpu` where onnxruntime-node does).
+ */
+export type LocalTranscriberDevice = 'auto' | 'webgpu' | 'wasm' | 'cpu' | 'gpu' | 'cuda' | 'dml' | 'coreml' | (string & {});
+/**
+ * Quantisation (`dtype`) forwarded to transformers.js: a single value such as
+ * `q8`, `q4`, `fp16`, `fp32`, or a per-file map such as
+ * `{ encoder_model: 'fp32', decoder_model_merged: 'q4' }`.
+ */
+export type LocalTranscriberDtype = string | Record<string, string>;
+/** Model loading progress, as reported by transformers.js. */
+export interface LocalTranscriberProgress {
+    status: string;
+    name?: string;
+    file?: string;
+    progress?: number;
+    loaded?: number;
+    total?: number;
+    [key: string]: unknown;
+}
+export type LocalTranscriberProgressCallback = (progress: LocalTranscriberProgress) => void;
+/** Decoded audio returned by a {@link LocalAudioDecoder}. */
+export interface DecodedAudio {
+    /** Mono samples, or one array per channel (downmixed by averaging). */
+    samples: Float32Array | Float32Array[];
+    sampleRate: number;
+}
+/**
+ * Caller-supplied decoder for formats the adapter cannot decode itself, e.g.
+ * WebM/Opus, MP4/AAC, MP3, or FLAC in Node (where there is no `AudioContext`).
+ * Return any sample rate; the adapter resamples to 16 kHz mono.
+ */
+export type LocalAudioDecoder = (audio: {
+    bytes: Uint8Array;
+    mimeType: string;
+    signal?: AbortSignal;
+}) => Promise<DecodedAudio>;
+/** Loader for the transformers.js module, or the module itself. */
+export type LocalTransformersRuntime = Record<string, unknown> | (() => Promise<Record<string, unknown>>);
+/** Settings shared by the `local` transcriber and `getTranscriber()`. */
+export interface LocalTranscriberSettings {
+    /** Hugging Face model id. Default `onnx-community/whisper-base`. */
+    model?: string;
+    /** Inference device. Default `auto`. */
+    device?: LocalTranscriberDevice;
+    /** Quantisation. Default: transformers.js chooses per device. */
+    dtype?: LocalTranscriberDtype;
+    /** Model revision (branch, tag, or commit). Default `main`. */
+    revision?: string;
+    /**
+     * Node model cache directory. Browsers always use Cache Storage, so this is
+     * ignored there.
+     */
+    cacheDir?: string;
+    /**
+     * Custom model host for self-hosted weights, e.g. `https://models.example.com/`.
+     * Sets the process-wide transformers.js `env.remoteHost`.
+     */
+    modelHost?: string;
+    /** Called with download and load progress (first load only). */
+    onProgress?: LocalTranscriberProgressCallback;
+    /** Decoder for formats without a built-in decoder. See {@link LocalAudioDecoder}. */
+    decodeAudio?: LocalAudioDecoder;
+    /**
+     * Whisper chunk length in seconds for audio longer than one 30 s window.
+     * Default 30; `0` disables chunking.
+     */
+    chunkLengthSeconds?: number;
+    /** Input byte limit. Default 25 MB; `Infinity` disables it. */
+    maxBytes?: number;
+    /** Called with usage after every successful transcription. */
+    onUsage?: SpeechUsageCallback;
+    /**
+     * Inject the transformers.js module (or a loader for it), e.g. a CDN build.
+     * Default: `import('@huggingface/transformers')`.
+     */
+    transformers?: LocalTransformersRuntime;
+    /**
+     * Escape hatch to adjust the process-wide transformers.js `env` (for example
+     * `localModelPath`, `allowRemoteModels`, or `backends.onnx.wasm`) before the
+     * first model load.
+     */
+    configureEnv?: (env: Record<string, unknown>) => void;
+}
+export interface LocalTranscriberOptions extends LocalTranscriberSettings {
+    type?: 'local';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/adapters/local/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/adapters/local/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAC9B,MAAM,GACN,QAAQ,GACR,MAAM,GACN,KAAK,GACL,KAAK,GACL,MAAM,GACN,KAAK,GACL,QAAQ,GACR,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEpE,8DAA8D;AAC9D,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,gCAAgC,GAAG,CAC7C,QAAQ,EAAE,wBAAwB,KAC/B,IAAI,CAAC;AAEV,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,OAAO,EAAE,YAAY,GAAG,YAAY,EAAE,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE;IACtC,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAE5B,mEAAmE;AACnE,MAAM,MAAM,wBAAwB,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvB,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;AAE7C,yEAAyE;AACzE,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,iEAAiE;IACjE,KAAK,CAAC,EAAE,qBAAqB,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,UAAU,CAAC,EAAE,gCAAgC,CAAC;IAC9C,qFAAqF;IACrF,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,wBAAwB,CAAC;IACxC;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CACvD;AAED,MAAM,WAAW,uBAAwB,SAAQ,wBAAwB;IACvE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB"}

package/dist/adapters/local/worker.d.ts

@@ -0,0 +1,118 @@
+import { TimestampGranularity, Transcriber, TranscriptionRequest, TranscriptResult } from '../../shared/types.js';
+import { SpeechUsageCallback } from '../../shared/usage.js';
+import { LocalAudioDecoder, LocalTranscriberOptions, LocalTranscriberProgress, LocalTranscriberProgressCallback } from './types.js';
+/** Minimal `postMessage` endpoint: a `Worker`, `DedicatedWorkerGlobalScope`, or `MessagePort`. */
+export interface LocalWorkerEndpoint {
+    postMessage(message: unknown, transfer?: Transferable[]): void;
+    addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+}
+/** Audio sent to the worker. Its buffers are transferred, not copied. */
+export type LocalWorkerAudio = {
+    /** WAV or raw PCM bytes (or any format the worker's `decodeAudio` handles). */
+    kind: 'encoded';
+    bytes: Uint8Array;
+    mimeType: string;
+    sampleRate?: number;
+    channels?: number;
+} | {
+    /** Channels decoded on the main thread; the worker downmixes and resamples. */
+    kind: 'decoded';
+    samples: Float32Array[];
+    sampleRate: number;
+};
+/** Messages from the client to the worker. */
+export type LocalWorkerRequest = {
+    kind: 'transcribe';
+    id: number;
+    audio: LocalWorkerAudio;
+    model?: string;
+    language?: string;
+    timestampGranularities?: TimestampGranularity[];
+} | {
+    kind: 'preload';
+    id: number;
+    model?: string;
+} | {
+    kind: 'abort';
+    id: number;
+};
+/** Messages from the worker to the client. */
+export type LocalWorkerResponse = {
+    kind: 'result';
+    id: number;
+    result?: TranscriptResult;
+} | {
+    kind: 'error';
+    id: number;
+    error: {
+        name: string;
+        message: string;
+        code?: string;
+    };
+} | {
+    kind: 'progress';
+    progress: LocalTranscriberProgress;
+};
+/**
+ * Runs a {@link LocalTranscriber} inside a worker and answers client
+ * requests. Call it from your worker module:
+ *
+ * ```ts
+ * // transcriber.worker.ts
+ * import { serveLocalTranscriber } from '@happyvertical/speech/local';
+ * serveLocalTranscriber({ model: 'onnx-community/whisper-base' });
+ * ```
+ *
+ * Returns a function that stops listening and disposes the model.
+ */
+export declare function serveLocalTranscriber(options?: LocalTranscriberOptions, endpoint?: LocalWorkerEndpoint): () => Promise<void>;
+export interface LocalTranscriberWorkerClientOptions {
+    /** Encoded input byte limit, checked on the main thread. Default 25 MB. */
+    maxBytes?: number;
+    /**
+     * Main-thread decoder for formats other than WAV and raw PCM. Formats with
+     * neither this hook nor `AudioContext` go to the worker's own `decodeAudio`.
+     */
+    decodeAudio?: LocalAudioDecoder;
+    /** Model download/load progress forwarded from the worker. */
+    onProgress?: LocalTranscriberProgressCallback;
+    /** Called with usage after every successful transcription. */
+    onUsage?: SpeechUsageCallback;
+}
+/**
+ * Main-thread {@link Transcriber} that delegates inference to a worker running
+ * {@link serveLocalTranscriber}.
+ *
+ * ```ts
+ * const worker = new Worker(new URL('./transcriber.worker.ts', import.meta.url), { type: 'module' });
+ * const transcriber = new LocalTranscriberWorkerClient(worker, { onProgress });
+ * const { text } = await transcriber.transcribe({ audio: recordingBlob });
+ * ```
+ */
+export declare class LocalTranscriberWorkerClient implements Transcriber {
+    readonly type: "local";
+    private readonly endpoint;
+    private readonly options;
+    private readonly calls;
+    private nextId;
+    private closed;
+    /** Aborted by `close()` to reject calls still buffering or decoding. */
+    private readonly closing;
+    private readonly listener;
+    constructor(endpoint: LocalWorkerEndpoint, options?: LocalTranscriberWorkerClientOptions);
+    /** Loads the model in the worker ahead of the first transcription. */
+    preload(model?: string, signal?: AbortSignal): Promise<void>;
+    transcribe(request: TranscriptionRequest): Promise<TranscriptResult>;
+    /**
+     * Stops listening, rejects in-flight and later calls, and asks the worker to
+     * abort posted work. Does not terminate the worker.
+     */
+    close(): void;
+    /** Buffers the input and, only when the worker cannot, decodes it here. */
+    private prepare;
+    private assertOpen;
+    private call;
+    private onMessage;
+}
+//# sourceMappingURL=worker.d.ts.map

package/dist/adapters/local/worker.d.ts.map

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

package/dist/adapters/openai-compatible.d.ts

@@ -2,7 +2,8 @@ import { HttpSpeechAdapter } from '../shared/http.js';
 import { OpenAICompatibleSpeechSynthesizerOptions, SpeechSynthesizer, SynthesisRequest, SynthesizedSpeech } from '../shared/types.js';
 export declare class OpenAICompatibleSpeechSynthesizer extends HttpSpeechAdapter implements SpeechSynthesizer {
     readonly type: "openai-compatible";
-    private readonly speechPath;
+    /** Explicit override, resolved relative to `baseUrl` (or absolute). */
+    private readonly speechPath?;
     private readonly defaultModel;
     private readonly defaultVoice;
     constructor(options: OpenAICompatibleSpeechSynthesizerOptions);

package/dist/adapters/openai-compatible.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai-compatible.d.ts","sourceRoot":"","sources":["../../src/adapters/openai-compatible.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,iBAAiB,EAGlB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,wCAAwC,EACxC,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAE5B,qBAAa,iCACX,SAAQ,iBACR,YAAW,iBAAiB;IAE5B,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAU;IAE7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,OAAO,EAAE,wCAAwC;IAOvD,UAAU,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA8BxE"}
+{"version":3,"file":"openai-compatible.d.ts","sourceRoot":"","sources":["../../src/adapters/openai-compatible.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,iBAAiB,EAIlB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,wCAAwC,EACxC,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAE5B,qBAAa,iCACX,SAAQ,iBACR,YAAW,iBAAiB;IAE5B,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAU;IAE7C,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,OAAO,EAAE,wCAAwC;IAOvD,UAAU,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAsCxE"}

package/dist/adapters/openai-realtime.d.ts

@@ -0,0 +1,48 @@
+import { RealtimeProtocol, RealtimeProtocolEvent, RealtimeSessionConfig } from '../shared/realtime-session.js';
+import { OpenAIRealtimeTranscriberOptions, StreamingAudioFormat, StreamingSession, StreamingSessionOptions, StreamingTranscriber, StreamingTurnLimit } from '../shared/streaming-types.js';
+export declare const OPENAI_REALTIME_DEFAULT_URL = "wss://api.openai.com/v1/realtime";
+export declare const OPENAI_REALTIME_DEFAULT_MODEL = "gpt-4o-transcribe";
+/** The OpenAI Realtime transcription wire protocol. */
+export declare const openAIRealtimeProtocol: (extras?: Pick<OpenAIRealtimeTranscriberOptions, "noiseReduction" | "include" | "transcriptionOptions">) => RealtimeProtocol;
+/**
+ * The GA transcription session object (`session.type: "transcription"`),
+ * shared by `session.update` and the client-secret mint request.
+ */
+export declare function openAIRealtimeTranscriptionSession(config: RealtimeSessionConfig, extras?: Pick<OpenAIRealtimeTranscriberOptions, 'noiseReduction' | 'include' | 'transcriptionOptions'>): Record<string, unknown>;
+/** Maps one OpenAI Realtime server event to normalised session events. */
+export declare function parseOpenAIRealtimeEvent(message: unknown): RealtimeProtocolEvent[];
+/**
+ * Realtime transcriber for OpenAI and OpenAI-Realtime-compatible servers.
+ *
+ * Auth: `apiKey` is sent as `Authorization: Bearer` (Node only). In browsers,
+ * pass `clientSecret` (an ephemeral client secret minted by your server); it
+ * is sent as the `openai-insecure-api-key.<secret>` subprotocol. Supplying
+ * `apiKey` or `headers` in a browser throws.
+ */
+export declare class OpenAIRealtimeTranscriber implements StreamingTranscriber {
+    readonly type = "openai-realtime";
+    readonly audioFormat: StreamingAudioFormat;
+    private readonly options;
+    private readonly url;
+    private readonly createWebSocket;
+    private readonly protocol;
+    constructor(options?: OpenAIRealtimeTranscriberOptions);
+    /**
+     * A turn limit applies only to `manual` sessions with `maxTurnSeconds` set;
+     * under server or semantic VAD the provider ends turns itself.
+     */
+    turnLimit(options?: StreamingSessionOptions): StreamingTurnLimit | undefined;
+    private sessionFormat;
+    private resolveTurnLimit;
+    private turnDetection;
+    start(options?: StreamingSessionOptions): StreamingSession;
+}
+/**
+ * Resolves a realtime WebSocket URL: `http(s)` becomes `ws(s)`, a server root
+ * gets `/v1/realtime`, a versioned API root gets `/realtime`, and
+ * `intent=transcription` is added unless an `intent` is already present. No
+ * `model` query parameter is added: the model travels in `session.update`.
+ */
+export declare function resolveRealtimeUrl(baseUrl: string): string;
+export declare function resolveOpenAIRealtimeFormat(format: Partial<StreamingAudioFormat> | undefined): StreamingAudioFormat;
+//# sourceMappingURL=openai-realtime.d.ts.map

package/dist/adapters/openai-realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-realtime.d.ts","sourceRoot":"","sources":["../../src/adapters/openai-realtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,OAAO,EAML,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAE3B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,gCAAgC,EAChC,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EAEpB,kBAAkB,EACnB,MAAM,8BAA8B,CAAC;AAatC,eAAO,MAAM,2BAA2B,qCAAqC,CAAC;AAC9E,eAAO,MAAM,6BAA6B,sBAAsB,CAAC;AAYjE,uDAAuD;AACvD,eAAO,MAAM,sBAAsB,GACjC,SAAQ,IAAI,CACV,gCAAgC,EAChC,gBAAgB,GAAG,SAAS,GAAG,sBAAsB,CACjD,KACL,gBAuBD,CAAC;AAEH;;;GAGG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,qBAAqB,EAC7B,MAAM,GAAE,IAAI,CACV,gCAAgC,EAChC,gBAAgB,GAAG,SAAS,GAAG,sBAAsB,CACjD,GACL,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BzB;AAED,0EAA0E;AAC1E,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,GACf,qBAAqB,EAAE,CAoFzB;AAED;;;;;;;GAOG;AACH,qBAAa,yBAA0B,YAAW,oBAAoB;IACpE,QAAQ,CAAC,IAAI,qBAAW;IACxB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAE3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;gBAEhC,OAAO,GAAE,gCAAqC;IAa1D;;;OAGG;IACH,SAAS,CACP,OAAO,GAAE,uBAA4B,GACpC,kBAAkB,GAAG,SAAS;IAOjC,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,aAAa;IASrB,KAAK,CAAC,OAAO,GAAE,uBAA4B,GAAG,gBAAgB;CAwC/D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ1D;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,SAAS,GAChD,oBAAoB,CAsBtB"}

package/dist/adapters/voxtral-realtime.d.ts

@@ -0,0 +1,44 @@
+import { RealtimeProtocol, RealtimeProtocolEvent } from '../shared/realtime-session.js';
+import { StreamingAudioFormat, StreamingSession, StreamingSessionOptions, StreamingTranscriber, StreamingTurnLimit, VoxtralRealtimeTranscriberOptions } from '../shared/streaming-types.js';
+/** vLLM's default served model name for Voxtral Mini Realtime. */
+export declare const VOXTRAL_REALTIME_DEFAULT_MODEL = "mistralai/Voxtral-Mini-4B-Realtime-2602";
+/** The only input format vLLM's realtime endpoint accepts. */
+export declare const VOXTRAL_REALTIME_AUDIO_FORMAT: Readonly<StreamingAudioFormat>;
+/** The vLLM realtime wire protocol. */
+export declare const voxtralRealtimeProtocol: () => RealtimeProtocol;
+/** Maps one vLLM realtime server event to normalised session events. */
+export declare function parseVoxtralRealtimeEvent(message: unknown): RealtimeProtocolEvent[];
+/**
+ * Realtime transcriber for Voxtral Realtime served by vLLM.
+ *
+ * - Audio: PCM16, 16 kHz, mono only; write whole samples (even byte counts).
+ * - Turns: manual only. vLLM has no VAD; it streams partials continuously and
+ *   produces one final per `commit()` / `end()`, plus one per automatic
+ *   rollover when a turn reaches `maxTurnSeconds` (default 270).
+ * - `language` and `prompt` are not sent: vLLM's realtime session accepts
+ *   only `model`.
+ * - Auth: `apiKey` → `Authorization: Bearer` (Node only). vLLM has no
+ *   ephemeral tokens, so browsers must connect through the consumer's own
+ *   proxy or token gateway, passing that gateway's short-lived `clientSecret`
+ *   (sent as the `openai-insecure-api-key.<secret>` subprotocol next to
+ *   `realtime`; the gateway must echo `realtime`).
+ */
+export declare class VoxtralRealtimeTranscriber implements StreamingTranscriber {
+    readonly type = "voxtral-realtime";
+    readonly audioFormat: StreamingAudioFormat;
+    private readonly options;
+    private readonly url;
+    private readonly createWebSocket;
+    private readonly protocol;
+    constructor(options?: VoxtralRealtimeTranscriberOptions);
+    turnLimit(options?: StreamingSessionOptions): StreamingTurnLimit | undefined;
+    private resolveTurnLimit;
+    start(options?: StreamingSessionOptions): StreamingSession;
+}
+/**
+ * Resolves vLLM's realtime WebSocket URL: `http(s)` becomes `ws(s)`, a server
+ * root gets `/v1/realtime`, a versioned API root (e.g. a gateway's
+ * `/stt/v1`) gets `/realtime`, and a URL ending in `/realtime` is kept.
+ */
+export declare function resolveVoxtralRealtimeUrl(baseUrl: string): string;
+//# sourceMappingURL=voxtral-realtime.d.ts.map

package/dist/adapters/voxtral-realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voxtral-realtime.d.ts","sourceRoot":"","sources":["../../src/adapters/voxtral-realtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAUH,OAAO,EAKL,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAE3B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EAEpB,kBAAkB,EAClB,iCAAiC,EAClC,MAAM,8BAA8B,CAAC;AAetC,kEAAkE;AAClE,eAAO,MAAM,8BAA8B,4CACA,CAAC;AAE5C,8DAA8D;AAC9D,eAAO,MAAM,6BAA6B,EAAE,QAAQ,CAAC,oBAAoB,CACF,CAAC;AAExE,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,QAAO,gBAuBzC,CAAC;AAEH,wEAAwE;AACxE,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,GACf,qBAAqB,EAAE,CAqDzB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,0BAA2B,YAAW,oBAAoB;IACrE,QAAQ,CAAC,IAAI,sBAAW;IACxB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAExC;IAEF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;gBAE1C,OAAO,GAAE,iCAAsC;IAiB3D,SAAS,CACP,OAAO,GAAE,uBAA4B,GACpC,kBAAkB,GAAG,SAAS;IAQjC,OAAO,CAAC,gBAAgB;IAWxB,KAAK,CAAC,OAAO,GAAE,uBAA4B,GAAG,gBAAgB;CA2C/D;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKjE"}

package/dist/chunks/errors-CQBX3OPS.js

@@ -0,0 +1,41 @@
+//#region src/shared/errors.ts
+var SpeechError = class extends Error {
+	code;
+	adapter;
+	constructor(message, code, adapter) {
+		super(message);
+		this.code = code;
+		this.adapter = adapter;
+		this.name = "SpeechError";
+	}
+};
+var SpeechConfigurationError = class extends SpeechError {
+	constructor(message, adapter) {
+		super(message, "SPEECH_CONFIGURATION_ERROR", adapter);
+		this.name = "SpeechConfigurationError";
+	}
+};
+var InvalidSpeechAdapterError = class extends SpeechError {
+	constructor(type, kind) {
+		super(`Invalid ${kind} speech adapter type: ${type}`, "INVALID_ADAPTER");
+		this.name = "InvalidSpeechAdapterError";
+	}
+};
+var SpeechProviderError = class extends SpeechError {
+	status;
+	responseBody;
+	/** Parsed `Retry-After` delay in milliseconds, when the provider sent one. */
+	retryAfterMs;
+	constructor(adapter, message, options = {}) {
+		super(message, "SPEECH_PROVIDER_ERROR", adapter);
+		this.name = "SpeechProviderError";
+		this.status = options.status;
+		this.responseBody = options.responseBody;
+		this.retryAfterMs = options.retryAfterMs;
+		if (options.cause !== void 0) this.cause = options.cause;
+	}
+};
+//#endregion
+export { SpeechProviderError as i, SpeechConfigurationError as n, SpeechError as r, InvalidSpeechAdapterError as t };
+
+//# sourceMappingURL=errors-CQBX3OPS.js.map

package/dist/chunks/errors-CQBX3OPS.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-CQBX3OPS.js","names":[],"sources":["../../src/shared/errors.ts"],"sourcesContent":["export class SpeechError extends Error {\n  constructor(\n    message: string,\n    public code: string,\n    public adapter?: string,\n  ) {\n    super(message);\n    this.name = 'SpeechError';\n  }\n}\n\nexport class SpeechConfigurationError extends SpeechError {\n  constructor(message: string, adapter?: string) {\n    super(message, 'SPEECH_CONFIGURATION_ERROR', adapter);\n    this.name = 'SpeechConfigurationError';\n  }\n}\n\nexport class InvalidSpeechAdapterError extends SpeechError {\n  constructor(type: string, kind: string) {\n    super(`Invalid ${kind} speech adapter type: ${type}`, 'INVALID_ADAPTER');\n    this.name = 'InvalidSpeechAdapterError';\n  }\n}\n\nexport class SpeechProviderError extends SpeechError {\n  readonly status?: number;\n  readonly responseBody?: string;\n  /** Parsed `Retry-After` delay in milliseconds, when the provider sent one. */\n  readonly retryAfterMs?: number;\n\n  constructor(\n    adapter: string,\n    message: string,\n    options: {\n      status?: number;\n      responseBody?: string;\n      retryAfterMs?: number;\n      cause?: unknown;\n    } = {},\n  ) {\n    super(message, 'SPEECH_PROVIDER_ERROR', adapter);\n    this.name = 'SpeechProviderError';\n    this.status = options.status;\n    this.responseBody = options.responseBody;\n    this.retryAfterMs = options.retryAfterMs;\n    if (options.cause !== undefined) {\n      this.cause = options.cause;\n    }\n  }\n}\n"],"mappings":";AAAA,IAAa,cAAb,cAAiC,MAAM;CAG5B;CACA;CAHT,YACE,SACA,MACA,SACA;EACA,MAAM,OAAO;EAHN,KAAA,OAAA;EACA,KAAA,UAAA;EAGP,KAAK,OAAO;CACd;AACF;AAEA,IAAa,2BAAb,cAA8C,YAAY;CACxD,YAAY,SAAiB,SAAkB;EAC7C,MAAM,SAAS,8BAA8B,OAAO;EACpD,KAAK,OAAO;CACd;AACF;AAEA,IAAa,4BAAb,cAA+C,YAAY;CACzD,YAAY,MAAc,MAAc;EACtC,MAAM,WAAW,KAAK,wBAAwB,QAAQ,iBAAiB;EACvE,KAAK,OAAO;CACd;AACF;AAEA,IAAa,sBAAb,cAAyC,YAAY;CACnD;CACA;;CAEA;CAEA,YACE,SACA,SACA,UAKI,CAAC,GACL;EACA,MAAM,SAAS,yBAAyB,OAAO;EAC/C,KAAK,OAAO;EACZ,KAAK,SAAS,QAAQ;EACtB,KAAK,eAAe,QAAQ;EAC5B,KAAK,eAAe,QAAQ;EAC5B,IAAI,QAAQ,UAAU,KAAA,GACpB,KAAK,QAAQ,QAAQ;CAEzB;AACF"}