@happyvertical/speech 0.96.1 → 0.98.0

package/dist/shared/realtime-session.d.ts

@@ -0,0 +1,240 @@
+import { StreamingAudioChunk, StreamingAudioFormat, StreamingSession, StreamingSessionEventName, StreamingSessionListener, StreamingSessionState, StreamingTurnDetection } from './streaming-types.js';
+import { TurnLimit } from './turn-limit.js';
+import { TranscriptResult } from './types.js';
+import { SpeechUsageCallback } from './usage.js';
+import { SpeechWebSocketFactory } from './websocket.js';
+export declare const DEFAULT_STREAMING_TIMEOUT_MS = 30000;
+export declare const DEFAULT_STREAMING_CONNECT_TIMEOUT_MS = 10000;
+export declare const DEFAULT_STREAMING_HIGH_WATER_MARK: number;
+export declare const DEFAULT_STREAMING_MAX_BUFFERED_BYTES: number;
+/** Normalised events a protocol parser returns for one server message. */
+export type RealtimeProtocolEvent = {
+    type: 'session';
+    sessionId?: string;
+}
+/** The provider committed a turn (from a client commit or server VAD). */
+ | {
+    type: 'committed';
+    itemId?: string;
+}
+/** The provider rejected a commit because its buffer was empty. Not fatal. */
+ | {
+    type: 'commit_empty';
+} | {
+    type: 'partial';
+    itemId?: string;
+    delta: string;
+} | {
+    type: 'final';
+    itemId?: string;
+    text: string;
+    providerUsage?: Record<string, unknown>;
+    raw?: unknown;
+    /**
+     * `false` when the provider reports that the turn consumed no audio
+     * (vLLM: `usage.prompt_tokens <= 1`). A turn that was sent audio but
+     * consumed none means the provider's turn state is out of sync, and the
+     * session fails instead of silently dropping that audio.
+     */
+    audioConsumed?: boolean;
+} | {
+    type: 'speech_started';
+    itemId?: string;
+    audioMs?: number;
+} | {
+    type: 'speech_stopped';
+    itemId?: string;
+    audioMs?: number;
+}
+/** A fatal provider error. */
+ | {
+    type: 'error';
+    message: string;
+    code?: string;
+    raw?: unknown;
+};
+/** Resolved per-session settings handed to the protocol. */
+export interface RealtimeSessionConfig {
+    model: string;
+    format: StreamingAudioFormat;
+    turnDetection: StreamingTurnDetection;
+    language?: string;
+    prompt?: string;
+}
+/** Wire format of one realtime provider. */
+export interface RealtimeProtocol {
+    /** Adapter name used for errors and usage, e.g. `openai-realtime`. */
+    readonly provider: string;
+    /**
+     * How a client commit is acknowledged: by a `committed` event (OpenAI), or
+     * only by the turn's `final` event (servers without a commit ack).
+     */
+    readonly commitAck: 'committed' | 'final';
+    /**
+     * Whether `end()` commits only when uncommitted audio remains
+     * (`if-audio`), or always sends a final commit (`always`, for servers that
+     * need an explicit end-of-stream marker).
+     */
+    readonly endCommit: 'if-audio' | 'always';
+    /**
+     * Default per-turn audio cap in seconds, for providers whose model context
+     * covers one turn (vLLM resets it after each final commit). Adapters pass
+     * it to `resolveTurnLimit()`; a session with a turn limit rolls over to a
+     * new turn before the cap, or rejects writes past it. Unset: no default.
+     */
+    readonly maxTurnSeconds?: number;
+    /**
+     * Shortest audio, in seconds, the provider accepts in one commit (OpenAI:
+     * 100 ms; shorter commits are rejected as empty). A session with a turn
+     * limit pads a shorter, non-empty turn with silence before committing it,
+     * so the tail left after a rollover is transcribed instead of dropped.
+     */
+    readonly minCommitSeconds?: number;
+    /** Messages sent once the socket opens (session configuration). */
+    sessionMessages(config: RealtimeSessionConfig): unknown[];
+    /** One audio chunk, already base64-encoded. */
+    appendMessage(base64Audio: string): unknown;
+    /** Ends the current turn. `final` is true for the commit sent by `end()`. */
+    commitMessage(options: {
+        final: boolean;
+    }): unknown;
+    /**
+     * Opens a turn before its first audio, for servers that only start
+     * generating after an explicit start signal (vLLM's non-final
+     * `input_audio_buffer.commit`). When set, the session sends it before the
+     * first append of every turn, and holds audio written after a commit until
+     * every outstanding turn has been acknowledged, so a server that resets its
+     * buffer between turns never drops audio.
+     */
+    turnStartMessage?(): unknown;
+    /** Maps one parsed JSON server message to zero or more events. */
+    parse(message: unknown): RealtimeProtocolEvent[];
+}
+/** Where and how to open the socket; resolved per session. */
+export interface RealtimeConnection {
+    url: string;
+    protocols: string[];
+    headers: Record<string, string>;
+    /** Credentials to redact from surfaced provider text. */
+    secrets: string[];
+}
+export interface RealtimeSessionInit {
+    protocol: RealtimeProtocol;
+    config: RealtimeSessionConfig;
+    /** Resolves the connection (may mint a short-lived token). */
+    connect: () => Promise<RealtimeConnection>;
+    createWebSocket: SpeechWebSocketFactory;
+    timeoutMs: number;
+    connectTimeoutMs: number;
+    highWaterMark: number;
+    maxBufferedBytes: number;
+    signal?: AbortSignal;
+    /** Called in order with the aggregated usage when `end()` succeeds. */
+    onUsage: Array<SpeechUsageCallback | undefined>;
+    /** Per-turn audio limit; unset means turns are unbounded. */
+    turnLimit?: TurnLimit;
+}
+export declare class RealtimeTranscriptionSession implements StreamingSession {
+    state: StreamingSessionState;
+    sessionId?: string;
+    readonly ready: Promise<void>;
+    private readonly init;
+    private readonly provider;
+    private resolveReady;
+    private rejectReady;
+    private socket?;
+    private opened;
+    private secrets;
+    private queue;
+    private queued;
+    private pumping;
+    private totalBytes;
+    private uncommittedBytes;
+    private outstandingCommits;
+    /** Per outstanding commit, in order: whether it carried audio. */
+    private readonly commitHadAudio;
+    private turnOpen;
+    /** `Date.now()` of the last server message; bounds inactivity waits. */
+    private lastServerMessageAt;
+    private readonly itemOrder;
+    private readonly pendingItems;
+    private readonly vadStoppedItems;
+    private readonly partials;
+    private readonly finals;
+    private readonly listeners;
+    private error?;
+    private endPromise?;
+    private endWaiter?;
+    private connectTimer?;
+    private endTimer?;
+    private closeEmitted;
+    /** Measures the current turn in write order when a turn limit applies. */
+    private readonly splitter?;
+    private readonly onAbort;
+    constructor(init: RealtimeSessionInit);
+    get queuedBytes(): number;
+    write(chunk: StreamingAudioChunk): Promise<void>;
+    commit(): void;
+    end(): Promise<TranscriptResult>;
+    /**
+     * (Re)starts the end timeout. It measures provider inactivity: every server
+     * message restarts it, so a long recording that is still being transcribed
+     * is not cut off, while a silent provider still fails after `timeoutMs`.
+     */
+    private armEndTimer;
+    abort(reason?: unknown): void;
+    on<E extends StreamingSessionEventName>(event: E, listener: StreamingSessionListener<E>): () => void;
+    off<E extends StreamingSessionEventName>(event: E, listener: StreamingSessionListener<E>): void;
+    private enqueueAudio;
+    private connect;
+    private onOpen;
+    private onMessage;
+    private handle;
+    /** Acknowledges the oldest outstanding commit; returns whether it carried audio. */
+    private ackCommit;
+    private pump;
+    private sendCommit;
+    /**
+     * In a session with a turn limit, tops up a non-empty turn shorter than the
+     * protocol's `minCommitSeconds` with silence (not counted as streamed
+     * audio). Rollover can leave such a tail, which the provider would
+     * otherwise reject as empty and drop. Returns false when the send failed.
+     */
+    private padShortTurn;
+    /**
+     * For protocols with an explicit turn start: before the next audio, waits
+     * for every outstanding turn to be acknowledged, then opens a new turn. Like
+     * the end timeout, the wait is bounded by provider inactivity: it fails only
+     * after `timeoutMs` without any server message. Returns false when the
+     * session has failed.
+     */
+    private openTurnIfNeeded;
+    /**
+     * Waits until the socket's send buffer is at or below `highWaterMark`. A
+     * socket that stays congested for `timeoutMs` fails the session, so a
+     * stalled connection can never leave `write()` pending forever.
+     */
+    private waitForDrain;
+    private send;
+    private checkEnded;
+    private finish;
+    private rank;
+    private onClose;
+    private fail;
+    private cleanup;
+    private closeSocket;
+    private emit;
+    private isTerminal;
+    private redact;
+}
+/**
+ * Throws when a turn cap is below the provider's minimum commit length:
+ * padding a short turn up to that minimum would then exceed the cap.
+ */
+export declare function assertTurnLimitFitsProtocol(protocol: Pick<RealtimeProtocol, 'provider' | 'minCommitSeconds'>, limit: Pick<TurnLimit, 'maxTurnSeconds'> | undefined): void;
+/**
+ * Sums numeric fields of per-turn provider usage blocks (recursively), keeping
+ * the first value of non-numeric fields such as `type`.
+ */
+export declare function sumUsage(blocks: Array<Record<string, unknown> | undefined>): Record<string, unknown> | undefined;
+//# sourceMappingURL=realtime-session.d.ts.map

package/dist/shared/realtime-session.d.ts.map

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

package/dist/shared/registry.d.ts

@@ -0,0 +1,9 @@
+import { SpeechFactoryContext } from './factory.js';
+import { GetTranscriberOptions, Transcriber, TranscriberType } from './types.js';
+export type OptionalTranscriberFactory = (options: GetTranscriberOptions, context: SpeechFactoryContext) => Transcriber | Promise<Transcriber>;
+export declare function registerOptionalTranscriber(type: TranscriberType, factory: OptionalTranscriberFactory): void;
+export declare function getOptionalTranscriberFactory(type: string): OptionalTranscriberFactory | undefined;
+/** Subpath that registers `type`, when it is an opt-in adapter. */
+export declare function optionalTranscriberEntry(type: string): string | undefined;
+export declare function registeredOptionalTranscribers(): TranscriberType[];
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/shared/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EACV,qBAAqB,EACrB,WAAW,EACX,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,0BAA0B,GAAG,CACvC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,oBAAoB,KAC1B,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;AASxC,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,0BAA0B,GAClC,IAAI,CAEN;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,GACX,0BAA0B,GAAG,SAAS,CAExC;AAED,mEAAmE;AACnE,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEzE;AAED,wBAAgB,8BAA8B,IAAI,eAAe,EAAE,CAElE"}

package/dist/shared/retry.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Retry with exponential backoff for speech provider calls. Retries only
+ * rate-limit (429) and server (5xx) responses, honours `Retry-After`, and
+ * stops immediately when the caller aborts.
+ */
+export interface SpeechRetryOptions {
+    /** Retries after the first attempt. Default `2`. `0` disables retries. */
+    maxRetries?: number;
+    /** First backoff delay in milliseconds. Default `500`. */
+    initialDelayMs?: number;
+    /**
+     * Upper bound for any single wait in milliseconds. Default `30000`. A
+     * `Retry-After` longer than this ends retrying rather than retrying early.
+     */
+    maxDelayMs?: number;
+}
+export declare const DEFAULT_SPEECH_RETRY: Required<SpeechRetryOptions>;
+export declare function resolveRetryOptions(retry: SpeechRetryOptions | false | undefined, defaults?: Required<SpeechRetryOptions> | false): Required<SpeechRetryOptions> | false;
+export declare function isRetryableStatus(status: number | undefined): boolean;
+/**
+ * Parses a `Retry-After` header (delta-seconds or HTTP-date) into
+ * milliseconds. Returns `undefined` when absent or unparseable.
+ */
+export declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
+/**
+ * Runs `attempt` until it succeeds, throws a non-retryable error, or the
+ * retry budget is exhausted. Retryable errors are {@link SpeechProviderError}
+ * instances whose `status` is 429 or 5xx.
+ */
+export declare function withSpeechRetry<T>(attempt: (attemptNumber: number) => Promise<T>, retry: Required<SpeechRetryOptions> | false, signal?: AbortSignal): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/shared/retry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,kBAAkB,CAI7D,CAAC;AAEF,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,GAAG,KAAK,GAAG,SAAS,EAC7C,QAAQ,GAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,KAA4B,GACpE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,KAAK,CAyBtC;AAwBD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAErE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,GAAG,GAAE,MAAmB,GACvB,MAAM,GAAG,SAAS,CAYpB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,OAAO,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9C,KAAK,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,KAAK,EAC3C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,CAAC,CA6BZ"}

package/dist/shared/streaming-client-secret.d.ts

@@ -0,0 +1,90 @@
+import { SpeechEnv } from './env.js';
+import { OpenAIRealtimeTranscriberOptions, StreamingAudioFormat, StreamingTranscriberType, StreamingTurnDetection } from './streaming-types.js';
+import { SpeechFetch } from './types.js';
+/** Default client-secret lifetime: long enough to connect, short if leaked. */
+export declare const DEFAULT_CLIENT_SECRET_TTL_SECONDS = 60;
+/** OpenAI's accepted `expires_after.seconds` range. */
+export declare const CLIENT_SECRET_TTL_RANGE: {
+    readonly min: 10;
+    readonly max: 7200;
+};
+export interface CreateStreamingClientSecretOptions {
+    /** Streaming adapter. Default `HAVE_SPEECH_STREAMING_TYPE`, then `openai-realtime`. */
+    type?: StreamingTranscriberType;
+    /** Long-lived server key. Default `HAVE_SPEECH_STREAMING_API_KEY`. */
+    apiKey?: string;
+    /**
+     * API base. Accepts the same values as the streaming adapter
+     * (`https://api.openai.com`, `…/v1`, or `wss://…/v1/realtime`). Default
+     * `HAVE_SPEECH_STREAMING_BASE_URL`, then `https://api.openai.com/v1`.
+     */
+    baseUrl?: string;
+    /** Secret lifetime in seconds, 10–7200. Default 60. */
+    ttlSeconds?: number;
+    /**
+     * Tenant the secret is minted for. Echoed in the result for your usage
+     * ledger; OpenAI's transcription client secrets carry no attribution field.
+     */
+    tenantId?: string;
+    /** Your session id (e.g. the dictation session), echoed in the result. */
+    sessionId?: string;
+    /** Extra attribution echoed in the result. Never sent to the provider. */
+    metadata?: Record<string, unknown>;
+    /** Transcription model the secret is bound to. Default `HAVE_SPEECH_STREAMING_MODEL`, then `gpt-4o-transcribe`. */
+    model?: string;
+    language?: string;
+    prompt?: string;
+    /** Default `HAVE_SPEECH_STREAMING_TURN_DETECTION`, then `server_vad`. */
+    turnDetection?: StreamingTurnDetection;
+    /** Default PCM16 24 kHz mono. */
+    format?: Partial<StreamingAudioFormat>;
+    noiseReduction?: OpenAIRealtimeTranscriberOptions['noiseReduction'];
+    include?: string[];
+    /**
+     * Extra `transcription` fields. The typed `model`, `language`, and `prompt`
+     * take precedence, so the secret is bound to the model the result reports.
+     */
+    transcriptionOptions?: Record<string, unknown>;
+    /**
+     * Headers for the mint request, e.g. a per-tenant gateway virtual key
+     * (`x-bf-vk`) for provider-side attribution. Merged over
+     * `HAVE_SPEECH_STREAMING_HEADERS`.
+     */
+    headers?: HeadersInit;
+    fetch?: SpeechFetch;
+    signal?: AbortSignal;
+    /** Request timeout. Default `HAVE_SPEECH_STREAMING_TIMEOUT[_MS]`, then 10000. */
+    timeoutMs?: number;
+}
+/** A minted browser credential plus the attribution it was minted for. */
+export interface StreamingClientSecretResult {
+    type: StreamingTranscriberType;
+    /** The short-lived secret. Send it to the browser as `clientSecret`. */
+    value: string;
+    /** Expiry as epoch milliseconds. */
+    expiresAt: number;
+    ttlSeconds: number;
+    model: string;
+    tenantId?: string;
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+    /** The provider's echoed session config. */
+    session?: Record<string, unknown>;
+}
+export interface StreamingClientSecretContext {
+    env?: SpeechEnv;
+}
+/**
+ * Mints a short-lived, session-scoped client secret for browser streaming.
+ * Server-side only: throws in a browser runtime, and for adapters without an
+ * ephemeral-token mechanism (`voxtral-realtime`).
+ */
+export declare function createStreamingClientSecret(options?: CreateStreamingClientSecretOptions, context?: StreamingClientSecretContext): Promise<StreamingClientSecretResult>;
+/**
+ * Resolves the client-secret endpoint from any accepted realtime base:
+ * `ws(s)` becomes `http(s)`, a trailing `/realtime` and query are dropped,
+ * then `/v1/realtime/client_secrets` (or `/realtime/client_secrets` under a
+ * versioned root) is appended.
+ */
+export declare function resolveClientSecretUrl(baseUrl: string): string;
+//# sourceMappingURL=streaming-client-secret.d.ts.map

package/dist/shared/streaming-client-secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-client-secret.d.ts","sourceRoot":"","sources":["../../src/shared/streaming-client-secret.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAQH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,UAAU,CAAC;AAiBlB,OAAO,KAAK,EACV,gCAAgC,EAChC,oBAAoB,EACpB,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,+EAA+E;AAC/E,eAAO,MAAM,iCAAiC,KAAK,CAAC;AACpD,uDAAuD;AACvD,eAAO,MAAM,uBAAuB;;;CAAkC,CAAC;AAEvE,MAAM,WAAW,kCAAkC;IACjD,uFAAuF;IACvF,IAAI,CAAC,EAAE,wBAAwB,CAAC;IAChC,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,mHAAmH;IACnH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,iCAAiC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACvC,cAAc,CAAC,EAAE,gCAAgC,CAAC,gBAAgB,CAAC,CAAC;IACpE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/C;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,0EAA0E;AAC1E,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,wBAAwB,CAAC;IAC/B,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,4BAA4B;IAC3C,GAAG,CAAC,EAAE,SAAS,CAAC;CACjB;AAID;;;;GAIG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,GAAE,kCAAuC,EAChD,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,2BAA2B,CAAC,CAuHtC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAc9D"}

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

@@ -0,0 +1,65 @@
+import { SpeechEnv } from './env.js';
+import { GetStreamingTranscriberOptions, StreamingTranscriber, StreamingTranscriberType, StreamingTurnDetection } from './streaming-types.js';
+import { Transcriber } from './types.js';
+/** Streaming adapters `getStreamingTranscriber()` can build. */
+export declare const STREAMING_TRANSCRIBER_TYPES: readonly StreamingTranscriberType[];
+/** Environment variable names read for each streaming setting, in priority order. */
+export declare const STREAMING_TRANSCRIBER_ENV_KEYS: {
+    readonly type: readonly ["HAVE_SPEECH_STREAMING_TYPE"];
+    readonly baseUrl: readonly ["HAVE_SPEECH_STREAMING_BASE_URL"];
+    readonly model: readonly ["HAVE_SPEECH_STREAMING_MODEL"];
+    readonly apiKey: readonly ["HAVE_SPEECH_STREAMING_API_KEY"];
+    readonly language: readonly ["HAVE_SPEECH_STREAMING_LANGUAGE"];
+    readonly turnDetection: readonly ["HAVE_SPEECH_STREAMING_TURN_DETECTION"];
+    readonly timeoutMs: readonly ["HAVE_SPEECH_STREAMING_TIMEOUT", "HAVE_SPEECH_STREAMING_TIMEOUT_MS"];
+    readonly connectTimeoutMs: readonly ["HAVE_SPEECH_STREAMING_CONNECT_TIMEOUT_MS"];
+    readonly headers: readonly ["HAVE_SPEECH_STREAMING_HEADERS"];
+    readonly maxTurnSeconds: readonly ["HAVE_SPEECH_STREAMING_MAX_TURN_SECONDS"];
+};
+export interface StreamingFactoryContext {
+    env?: SpeechEnv;
+    /** Headers merged under explicit `headers` (env → context → options). */
+    headers?: HeadersInit;
+}
+export declare function isStreamingTranscriberType(type: string | undefined): type is StreamingTranscriberType;
+/**
+ * Creates a realtime streaming transcriber. Explicit options win over
+ * `HAVE_SPEECH_STREAMING_*` environment variables. The type defaults to
+ * `openai-realtime`.
+ */
+export declare function getStreamingTranscriber(options?: GetStreamingTranscriberOptions, context?: StreamingFactoryContext): StreamingTranscriber;
+export declare function parseTurnDetection(value: string | undefined): StreamingTurnDetection | undefined;
+/**
+ * Parses `HAVE_SPEECH_STREAMING_MAX_TURN_SECONDS`: a positive number of
+ * seconds, or `Infinity` for no limit.
+ */
+export declare function parseMaxTurnSeconds(value: string | undefined): number | undefined;
+export interface StreamingTranscriberWrapperOptions {
+    /** Bytes per `write()`. Default 64 KiB. */
+    chunkBytes?: number;
+    /** Upload limit in bytes. Default 25 MB; `Infinity` disables it. */
+    maxBytes?: number;
+    /**
+     * Turn detection for wrapped sessions. Default `manual`: the whole clip is
+     * one turn, committed by `end()`.
+     */
+    turnDetection?: StreamingTurnDetection;
+}
+/**
+ * Adapts a streaming transcriber to the request/response `Transcriber`
+ * interface for record-then-send callers. Each `transcribe()` opens one
+ * session, streams the recording, and returns `session.end()`.
+ *
+ * Input must be raw audio: a PCM16/G.711 WAV file, `audio/pcm` or
+ * `audio/L16` (optionally with `rate`/`channels` parameters), `audio/pcmu`,
+ * `audio/pcma`, or untyped bytes in the adapter's default format. WAV headers
+ * and MIME parameters set the session format; compressed recordings are
+ * rejected, so use an HTTP transcriber for WebM/MP4/Ogg.
+ *
+ * A clip longer than the adapter's per-turn limit (`maxTurnSeconds`) is
+ * never sent as one turn: with rollover (the default) the session splits it
+ * into several turns at quiet boundaries, and with `rollover: false` the clip
+ * is rejected with `SPEECH_TURN_TOO_LONG` before connecting.
+ */
+export declare function wrapStreamingTranscriber(streaming: StreamingTranscriber, options?: StreamingTranscriberWrapperOptions): Transcriber;
+//# sourceMappingURL=streaming-factory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-factory.d.ts","sourceRoot":"","sources":["../../src/shared/streaming-factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,UAAU,CAAC;AAOlB,OAAO,KAAK,EACV,8BAA8B,EAE9B,oBAAoB,EACpB,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,WAAW,EAGZ,MAAM,YAAY,CAAC;AAEpB,gEAAgE;AAChE,eAAO,MAAM,2BAA2B,EAAE,SAAS,wBAAwB,EAClC,CAAC;AAE1C,qFAAqF;AACrF,eAAO,MAAM,8BAA8B;;;;;;;;;;;CAcjC,CAAC;AAEX,MAAM,WAAW,uBAAuB;IACtC,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,yEAAyE;IACzE,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,IAAI,IAAI,wBAAwB,CAKlC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,8BAAmC,EAC5C,OAAO,GAAE,uBAA4B,GACpC,oBAAoB,CA4CtB;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,sBAAsB,GAAG,SAAS,CAcpC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,MAAM,GAAG,SAAS,CAWpB;AAED,MAAM,WAAW,kCAAkC;IACjD,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACxC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,oBAAoB,EAC/B,OAAO,GAAE,kCAAuC,GAC/C,WAAW,CA6Eb"}