@happyvertical/speech 0.102.0 → 0.102.2

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

@@ -1,4 +1,14 @@
-import { DecodedAudio, LocalAudioDecoder } from './types.js';
+/**
+ * Audio decoding for on-device inference: turns encoded bytes into 16 kHz
+ * mono Float32 PCM, the input Whisper and Moonshine expect.
+ *
+ * - WAV (PCM 8/16/24/32-bit, IEEE float 32/64, WAVE_FORMAT_EXTENSIBLE) and raw
+ *   `audio/pcm` are decoded in-process in every runtime, including workers.
+ * - Anything else goes to the caller's `decodeAudio` hook, or, in browsers,
+ *   to `OfflineAudioContext.decodeAudioData` (MediaRecorder WebM/Opus, Safari
+ *   `audio/mp4`, MP3, ...).
+ */
+import type { DecodedAudio, LocalAudioDecoder } from './types.js';
 /** Sample rate expected by Whisper and Moonshine feature extractors. */
 export declare const LOCAL_SAMPLE_RATE = 16000;
 export interface DecodeToPcmOptions {

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

@@ -1,5 +1,9 @@
-import { SpeechFactoryContext } from '../../shared/factory.js';
-import { LocalTranscriberOptions } from './types.js';
+/**
+ * Environment configuration for the `local` transcriber. Explicit options win,
+ * then the factory context, then `HAVE_SPEECH_TRANSCRIBER_*` variables (Node).
+ */
+import type { SpeechFactoryContext } from '../../shared/factory.js';
+import type { LocalTranscriberOptions } from './types.js';
 /** Local-only environment variables, in priority order. */
 export declare const LOCAL_TRANSCRIBER_ENV_KEYS: {
     readonly device: readonly ["HAVE_SPEECH_TRANSCRIBER_DEVICE"];

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

@@ -1,4 +1,11 @@
-import { LocalTranscriberDevice, LocalTranscriberDtype, LocalTranscriberProgressCallback, LocalTransformersRuntime } from './types.js';
+/**
+ * Loads the optional `@huggingface/transformers` peer dependency and builds
+ * `automatic-speech-recognition` pipelines from it.
+ *
+ * This is the only module that names the peer. It is reachable only from the
+ * `@happyvertical/speech/local` entry, never from the core entry.
+ */
+import type { LocalTranscriberDevice, LocalTranscriberDtype, LocalTranscriberProgressCallback, LocalTransformersRuntime } from './types.js';
 export declare const TRANSFORMERS_PACKAGE = "@huggingface/transformers";
 export declare const TRANSFORMERS_INSTALL_HINT: string;
 /** One ASR result as returned by transformers.js. */

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

@@ -1,6 +1,6 @@
-import { Transcriber, TranscriptionRequest, TranscriptResult } from '../../shared/types.js';
-import { AsrOutput } from './runtime.js';
-import { LocalTranscriberOptions } from './types.js';
+import type { Transcriber, TranscriptionRequest, TranscriptResult } from '../../shared/types.js';
+import { type AsrOutput } from './runtime.js';
+import type { LocalTranscriberOptions } from './types.js';
 /** Small multilingual Whisper (~80 MB at the default q8 quantisation). */
 export declare const DEFAULT_LOCAL_MODEL = "onnx-community/whisper-base";
 /**

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

@@ -1,4 +1,10 @@
-import { SpeechUsageCallback } from '../../shared/usage.js';
+/**
+ * Public option types for the on-device (`local`) transcriber.
+ *
+ * Kept free of `@huggingface/transformers` types so the core entry can
+ * reference them without depending on the optional peer.
+ */
+import type { 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

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

@@ -1,6 +1,16 @@
-import { TimestampGranularity, Transcriber, TranscriptionRequest, TranscriptResult } from '../../shared/types.js';
-import { SpeechUsageCallback } from '../../shared/usage.js';
-import { LocalAudioDecoder, LocalTranscriberOptions, LocalTranscriberProgress, LocalTranscriberProgressCallback } from './types.js';
+/**
+ * Web Worker support for the `local` transcriber.
+ *
+ * Inference runs in a worker (`serveLocalTranscriber`) so long recordings never
+ * block the UI thread. The main-thread client (`LocalTranscriberWorkerClient`)
+ * transfers WAV and raw PCM bytes to the worker, which parses, downmixes, and
+ * resamples them there. Only formats that need `AudioContext` (which workers
+ * lack) or the client's `decodeAudio` hook are decoded on the main thread;
+ * their Float32 channels are then transferred and resampled in the worker.
+ */
+import type { TimestampGranularity, Transcriber, TranscriptionRequest, TranscriptResult } from '../../shared/types.js';
+import { type SpeechUsageCallback } from '../../shared/usage.js';
+import type { LocalAudioDecoder, LocalTranscriberOptions, LocalTranscriberProgress, LocalTranscriberProgressCallback } from './types.js';
 /** Minimal `postMessage` endpoint: a `Worker`, `DedicatedWorkerGlobalScope`, or `MessagePort`. */
 export interface LocalWorkerEndpoint {
     postMessage(message: unknown, transfer?: Transferable[]): void;

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

@@ -1,5 +1,5 @@
 import { HttpSpeechAdapter } from '../shared/http.js';
-import { OpenAICompatibleTranscriberOptions, Transcriber, TranscriptionRequest, TranscriptResult } from '../shared/types.js';
+import type { OpenAICompatibleTranscriberOptions, Transcriber, TranscriptionRequest, TranscriptResult } from '../shared/types.js';
 export declare function isJsonOnlyTranscriptionModel(model: string): boolean;
 /**
  * OpenAI-compatible speech-to-text adapter (`POST <base>/audio/transcriptions`).

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

@@ -1,5 +1,5 @@
 import { HttpSpeechAdapter } from '../shared/http.js';
-import { OpenAICompatibleSpeechSynthesizerOptions, SpeechSynthesizer, SynthesisRequest, SynthesizedSpeech } from '../shared/types.js';
+import type { OpenAICompatibleSpeechSynthesizerOptions, SpeechSynthesizer, SynthesisRequest, SynthesizedSpeech } from '../shared/types.js';
 export declare class OpenAICompatibleSpeechSynthesizer extends HttpSpeechAdapter implements SpeechSynthesizer {
     readonly type: "openai-compatible";
     /** Explicit override, resolved relative to `baseUrl` (or absolute). */

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

@@ -1,5 +1,16 @@
-import { RealtimeProtocol, RealtimeProtocolEvent, RealtimeSessionConfig } from '../shared/realtime-session.js';
-import { OpenAIRealtimeTranscriberOptions, StreamingAudioFormat, StreamingSession, StreamingSessionOptions, StreamingTranscriber, StreamingTurnLimit } from '../shared/streaming-types.js';
+/**
+ * OpenAI Realtime transcription adapter (`openai-realtime`).
+ *
+ * Targets the GA Realtime API transcription session (no `OpenAI-Beta`
+ * header): connect to `wss://api.openai.com/v1/realtime?intent=transcription`,
+ * send `session.update` with `session.type: "transcription"`, stream
+ * `input_audio_buffer.append`, and read
+ * `conversation.item.input_audio_transcription.delta` / `.completed`.
+ * Reference: https://developers.openai.com/api/docs/guides/realtime-transcription
+ * and https://developers.openai.com/api/reference/resources/realtime/client-events
+ */
+import { type RealtimeProtocol, type RealtimeProtocolEvent, type RealtimeSessionConfig } from '../shared/realtime-session.js';
+import type { 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. */

package/dist/adapters/qwen3.d.ts

@@ -1,5 +1,5 @@
 import { HttpSpeechAdapter } from '../shared/http.js';
-import { Qwen3SpeechSynthesizerOptions, SpeechSynthesizer, SynthesisRequest, SynthesizedSpeech } from '../shared/types.js';
+import type { Qwen3SpeechSynthesizerOptions, SpeechSynthesizer, SynthesisRequest, SynthesizedSpeech } from '../shared/types.js';
 export declare class Qwen3SpeechSynthesizer extends HttpSpeechAdapter implements SpeechSynthesizer {
     readonly type: "qwen3-tts";
     private readonly speechPath;

package/dist/adapters/studio-server.d.ts

@@ -1,5 +1,5 @@
 import { HttpSpeechAdapter } from '../shared/http.js';
-import { SpeechSynthesizer, StudioServerSpeechSynthesizerOptions, StudioServerTranscriberOptions, SynthesisRequest, SynthesizedSpeech, Transcriber, TranscriptionRequest, TranscriptResult } from '../shared/types.js';
+import type { SpeechSynthesizer, StudioServerSpeechSynthesizerOptions, StudioServerTranscriberOptions, SynthesisRequest, SynthesizedSpeech, Transcriber, TranscriptionRequest, TranscriptResult } from '../shared/types.js';
 export declare class StudioServerTranscriber extends HttpSpeechAdapter implements Transcriber {
     readonly type: "studio-server";
     private readonly transcribePath;

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

@@ -1,5 +1,39 @@
-import { RealtimeProtocol, RealtimeProtocolEvent } from '../shared/realtime-session.js';
-import { StreamingAudioFormat, StreamingSession, StreamingSessionOptions, StreamingTranscriber, StreamingTurnLimit, VoxtralRealtimeTranscriberOptions } from '../shared/streaming-types.js';
+/**
+ * vLLM realtime transcription adapter (`voxtral-realtime`), for Mistral's
+ * Voxtral Realtime models (e.g. `mistralai/Voxtral-Mini-4B-Realtime-2602`)
+ * served by vLLM at `/v1/realtime`.
+ *
+ * vLLM's protocol borrows OpenAI event names but is not OpenAI-compatible.
+ * Verified against vLLM's `entrypoints/speech_to_text/realtime` source and a
+ * live server:
+ *
+ * 1. The server sends `session.created` (`{ id, created }`) on connect.
+ * 2. The client sends `session.update` with a top-level `model` (no nested
+ *    `session` object, no acknowledgement; an unknown model yields an
+ *    `error` with code `model_not_found`).
+ * 3. A non-final `input_audio_buffer.commit` starts generation for a turn.
+ * 4. `input_audio_buffer.append` carries base64 PCM16 at 16 kHz mono. Audio
+ *    appended before the start commit is kept.
+ * 5. The server streams `transcription.delta` (`{ delta }`, often empty) while
+ *    audio arrives, at roughly real-time speed.
+ * 6. `input_audio_buffer.commit` with `final: true` ends the turn; the server
+ *    replies `transcription.done` (`{ text, usage }`, token usage only) and
+ *    clears its buffer. A further start commit opens the next turn on the same
+ *    socket.
+ * 7. Errors arrive as `{ type: 'error', error: string, code }` and leave the
+ *    socket open; this adapter treats every error as fatal.
+ * 8. A turn whose audio and tokens exceed `max_model_len` (~12.5 tokens per
+ *    audio second plus a 39-token prompt) ends in `error` `processing_error`
+ *    and can take the engine down. The limit is per turn: after a final
+ *    commit vLLM clears the turn's context. The session therefore rolls over
+ *    to a new turn before `maxTurnSeconds` (default 270) of audio.
+ * 9. A stray final commit leaves a stale end marker: the next turn ends at once
+ *    with `prompt_tokens: 1` (any audio costs 39) and its audio is dropped.
+ *    The session fails closed on that, and on any `done` for a turn it did
+ *    not commit, rather than losing audio silently.
+ */
+import { type RealtimeProtocol, type RealtimeProtocolEvent } from '../shared/realtime-session.js';
+import type { 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. */

package/dist/conversation/openai-webrtc.d.ts

@@ -1,4 +1,4 @@
-import { OpenAIWebRTCVoiceOptions, VoiceSession } from './types.js';
+import type { OpenAIWebRTCVoiceOptions, VoiceSession } from './types.js';
 /** Browser WebRTC transport. No credentials, Node dependencies or globals are read at import. */
 export declare function createOpenAIWebRTCVoiceSession(options: OpenAIWebRTCVoiceOptions): VoiceSession;
 //# sourceMappingURL=openai-webrtc.d.ts.map

package/dist/conversation-server.d.ts

@@ -1,6 +1,7 @@
+/** Server-only OpenAI conversational call lifecycle. Hosts own authorization and admission policy. */
 import { SpeechProviderError } from './shared/errors.js';
-import { StreamingTurnDetection } from './shared/streaming-types.js';
-import { SpeechFetch } from './shared/types.js';
+import type { StreamingTurnDetection } from './shared/streaming-types.js';
+import type { SpeechFetch } from './shared/types.js';
 export interface OpenAIVoiceCallOptions {
     apiKey: string;
     /** Fixed by the host, never copied from untrusted browser JSON. */

package/dist/local.d.ts

@@ -1,6 +1,24 @@
+/**
+ * @happyvertical/speech/local
+ *
+ * On-device speech-to-text with transformers.js (`@huggingface/transformers`,
+ * an optional peer dependency loaded on first use). Importing this entry
+ * registers `type: 'local'` with `getTranscriber()` and `getSpeech()`.
+ *
+ * @example
+ * ```typescript
+ * import { getTranscriber } from '@happyvertical/speech';
+ * import '@happyvertical/speech/local';
+ *
+ * const transcriber = await getTranscriber({ type: 'local' });
+ * const { text } = await transcriber.transcribe({ audio: wavBytes, mimeType: 'audio/wav' });
+ * ```
+ *
+ * @packageDocumentation
+ */
 import { LocalTranscriber } from './adapters/local/transcriber.js';
-import { LocalTranscriberOptions } from './adapters/local/types.js';
-import { SpeechFactoryContext } from './shared/factory.js';
+import type { LocalTranscriberOptions } from './adapters/local/types.js';
+import type { SpeechFactoryContext } from './shared/factory.js';
 export { decodeToPcm16k, LOCAL_SAMPLE_RATE, } from './adapters/local/audio.js';
 export { LOCAL_TRANSCRIBER_ENV_KEYS } from './adapters/local/env.js';
 export { TRANSFORMERS_INSTALL_HINT, TRANSFORMERS_PACKAGE, } from './adapters/local/runtime.js';

package/dist/shared/audio.d.ts

@@ -1,4 +1,10 @@
-import { AudioInput, AudioSource } from './types.js';
+/**
+ * Audio input normalisation shared by speech adapters: accepts the input
+ * shapes callers actually have (Blob, Buffer, Uint8Array, ArrayBuffer,
+ * ReadableStream), enforces byte limits while buffering, and derives a
+ * multipart filename whose extension matches the MIME type.
+ */
+import type { AudioInput, AudioSource } from './types.js';
 /** OpenAI caps `/audio/transcriptions` uploads at 25 MB. */
 export declare const DEFAULT_MAX_AUDIO_BYTES: number;
 /**

package/dist/shared/env.d.ts

@@ -1,4 +1,11 @@
-import { SpeechFetch } from './types.js';
+/**
+ * Environment configuration for speech adapters.
+ *
+ * Transcriber settings resolve in this order (first wins):
+ * explicit options → factory context → `HAVE_SPEECH_TRANSCRIBER_*` →
+ * legacy `HAVE_SPEECH_STT_*` → gateway `STT_*` aliases.
+ */
+import type { SpeechFetch } from './types.js';
 export interface SpeechEnv {
     [key: string]: string | undefined;
 }

package/dist/shared/factory.d.ts

@@ -1,5 +1,5 @@
-import { SpeechEnv } from './env.js';
-import { GetSpeechOptions, GetSpeechSynthesizerOptions, GetTranscriberOptions, Speech, SpeechAdapterAvailability, SpeechFetch, SpeechSynthesizer, Transcriber } from './types.js';
+import { type SpeechEnv } from './env.js';
+import type { GetSpeechOptions, GetSpeechSynthesizerOptions, GetTranscriberOptions, Speech, SpeechAdapterAvailability, SpeechFetch, SpeechSynthesizer, Transcriber } from './types.js';
 export interface SpeechFactoryContext {
     env?: SpeechEnv;
     fetch?: SpeechFetch;

package/dist/shared/http.d.ts

@@ -1,5 +1,5 @@
-import { SpeechRetryOptions } from './retry.js';
-import { HttpSpeechOptions, SpeechFetch, SynthesisRequest, SynthesizedSpeech, TranscriptResult, TranscriptSegment, WordTiming } from './types.js';
+import { type SpeechRetryOptions } from './retry.js';
+import type { HttpSpeechOptions, SpeechFetch, SynthesisRequest, SynthesizedSpeech, TranscriptResult, TranscriptSegment, WordTiming } from './types.js';
 /**
  * Returns `baseUrl` with a trailing `/` on its path so relative paths resolve
  * beneath it. The query string is preserved and any fragment is dropped.

package/dist/shared/input-format.d.ts

@@ -1,4 +1,4 @@
-import { TranscriberType } from './types.js';
+import type { TranscriberType } from './types.js';
 /** What audio a transcriber type accepts from a caller. */
 export type TranscriberInputFormat = {
     kind: 'compressed';

package/dist/shared/pcm.d.ts

@@ -1,4 +1,9 @@
-import { StreamingAudioChunk, StreamingAudioFormat } from './streaming-types.js';
+/**
+ * Raw-audio helpers for streaming adapters: byte views, base64 encoding,
+ * duration from byte counts, and WAV/`audio/L16` unwrapping for the
+ * record-then-send wrapper. Nothing here decodes compressed audio or resamples.
+ */
+import type { StreamingAudioChunk, StreamingAudioFormat } from './streaming-types.js';
 /** Returns a byte view over a chunk without copying. */
 export declare function chunkToBytes(chunk: StreamingAudioChunk, adapter?: string): Uint8Array;
 export declare function encodeBase64(bytes: Uint8Array): string;

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

@@ -1,5 +1,13 @@
-import { RealtimeConnection } from './realtime-session.js';
-import { StreamingClientSecret } from './streaming-types.js';
+/**
+ * Credential handling shared by realtime (WebSocket) adapters.
+ *
+ * Node callers authenticate with a long-lived `apiKey` in the
+ * `Authorization` header. Browsers cannot set WebSocket headers and must never
+ * hold a long-lived key, so they pass a short-lived `clientSecret`, which is
+ * sent as a WebSocket subprotocol.
+ */
+import type { RealtimeConnection } from './realtime-session.js';
+import type { StreamingClientSecret } from './streaming-types.js';
 /** Subprotocol prefix that carries a client secret (OpenAI's convention). */
 export declare const CLIENT_SECRET_SUBPROTOCOL_PREFIX = "openai-insecure-api-key.";
 /** Throws when an adapter is given a long-lived `apiKey` in a browser. */

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

@@ -1,8 +1,17 @@
-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';
+/**
+ * Protocol-agnostic realtime transcription session over a WebSocket.
+ *
+ * The session owns the socket lifecycle, write queue and backpressure,
+ * timeouts, turn bookkeeping, events, and the final `TranscriptResult`. A
+ * {@link RealtimeProtocol} supplies the wire format, so a sibling adapter
+ * (for example a vLLM-served Voxtral realtime endpoint) only has to map its
+ * own messages.
+ */
+import type { StreamingAudioChunk, StreamingAudioFormat, StreamingSession, StreamingSessionEventName, StreamingSessionListener, StreamingSessionState, StreamingTurnDetection } from './streaming-types.js';
+import { type TurnLimit } from './turn-limit.js';
+import type { TranscriptResult } from './types.js';
+import { type SpeechUsageCallback } from './usage.js';
+import { type 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;

package/dist/shared/registry.d.ts

@@ -1,5 +1,13 @@
-import { SpeechFactoryContext } from './factory.js';
-import { GetTranscriberOptions, Transcriber, TranscriberType } from './types.js';
+/**
+ * Registry for opt-in transcriber adapters that live behind subpath exports
+ * (e.g. `@happyvertical/speech/local`).
+ *
+ * The core entry never imports those adapters, so their heavy optional peer
+ * dependencies are never resolved by bundlers or loaded at runtime unless the
+ * caller imports the subpath, which registers its factory here.
+ */
+import type { SpeechFactoryContext } from './factory.js';
+import type { 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;

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

@@ -1,6 +1,24 @@
-import { SpeechEnv } from './env.js';
-import { OpenAIRealtimeTranscriberOptions, StreamingAudioFormat, StreamingTranscriberType, StreamingTurnDetection } from './streaming-types.js';
-import { SpeechFetch } from './types.js';
+/**
+ * Server-side minting of short-lived browser credentials for realtime
+ * transcription.
+ *
+ * A browser must never hold the long-lived provider key. Your server calls
+ * {@link createStreamingClientSecret} once per tenant session (after its own
+ * auth check), records the returned tenant/session attribution, and hands the
+ * browser only `value` and `expiresAt`. The browser passes `value` as the
+ * streaming adapter's `clientSecret`.
+ *
+ * - `openai-realtime`: `POST /v1/realtime/client_secrets` with
+ *   `expires_after: { anchor: 'created_at', seconds }` and a
+ *   `session.type: "transcription"` config, returning an `ek_…` secret
+ *   (https://developers.openai.com/api/reference/resources/realtime/subresources/client_secrets/methods/create).
+ * - `voxtral-realtime`: vLLM has no ephemeral-token mechanism, so this throws
+ *   `SpeechConfigurationError`. Browser Voxtral needs your own proxy or token
+ *   gateway in front of vLLM.
+ */
+import { type SpeechEnv } from './env.js';
+import type { OpenAIRealtimeTranscriberOptions, StreamingAudioFormat, StreamingTranscriberType, StreamingTurnDetection } from './streaming-types.js';
+import type { 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. */

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

@@ -1,6 +1,10 @@
-import { SpeechEnv } from './env.js';
-import { GetStreamingTranscriberOptions, StreamingTranscriber, StreamingTranscriberType, StreamingTurnDetection } from './streaming-types.js';
-import { Transcriber } from './types.js';
+/**
+ * Streaming transcriber factory, environment configuration, and the
+ * record-then-send `Transcriber` wrapper.
+ */
+import { type SpeechEnv } from './env.js';
+import type { GetStreamingTranscriberOptions, StreamingTranscriber, StreamingTranscriberType, StreamingTurnDetection } from './streaming-types.js';
+import type { 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. */

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

@@ -1,6 +1,13 @@
-import { TranscriptResult } from './types.js';
-import { SpeechUsageCallback } from './usage.js';
-import { SpeechWebSocketConstructor, SpeechWebSocketFactory } from './websocket.js';
+/**
+ * Streaming (realtime) speech-to-text contract.
+ *
+ * A {@link StreamingTranscriber} opens one {@link StreamingSession} per
+ * utterance or conversation. Callers push raw audio with `write()`, listen for
+ * `partial` and `final` events, and call `end()` for the whole transcript.
+ */
+import type { TranscriptResult } from './types.js';
+import type { SpeechUsageCallback } from './usage.js';
+import type { SpeechWebSocketConstructor, SpeechWebSocketFactory } from './websocket.js';
 /** Streaming adapter identifiers. */
 export type StreamingTranscriberType = 'openai-realtime' | 'voxtral-realtime';
 /**

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

@@ -1,4 +1,16 @@
-import { StreamingAudioFormat, StreamingSessionSettings, StreamingTurnLimit } from './streaming-types.js';
+/**
+ * Per-turn audio limits for realtime sessions.
+ *
+ * Some providers cap the audio of one turn rather than of a session: vLLM's
+ * realtime endpoint keeps a turn's audio and generated tokens in one model
+ * context (`max_model_len`) and clears it after each final commit. A
+ * {@link TurnSplitter} measures the audio of the current turn from byte counts
+ * and the negotiated format, and picks where to roll over to a new turn: at
+ * the first quiet stretch inside a window before the limit, or at the limit
+ * itself when no quiet stretch turns up. The silence check is a plain RMS
+ * energy test, not a voice-activity model.
+ */
+import type { 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. */

package/dist/shared/types.d.ts

@@ -1,7 +1,7 @@
-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';
+import type { LocalTranscriberSettings } from '../adapters/local/types.js';
+import type { SpeechRetryOptions } from './retry.js';
+import type { GetStreamingTranscriberOptions, StreamingTranscriberType } from './streaming-types.js';
+import type { 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/speech",
-  "version": "0.102.0",
+  "version": "0.102.2",
   "description": "Speech provider abstraction for STT and TTS backends",
   "type": "module",
   "main": "./dist/index.js",