@happyvertical/speech 0.101.3 → 0.102.1

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/local.js

@@ -1,5 +1,5 @@
-import { i as SpeechProviderError, n as SpeechConfigurationError, r as SpeechError } from "./chunks/errors-CQBX3OPS.js";
-import { f as readEnv, h as reportSpeechUsage, o as defaultEnv, p as resolveTranscriberConfig, r as registerOptionalTranscriber, v as normalizeAudioInput, y as normalizeMimeType } from "./chunks/registry-C_5BakmM.js";
+import { a as SpeechProviderError, i as SpeechError, r as SpeechConfigurationError } from "./chunks/errors-Cs0vX-mV.js";
+import { f as readEnv, h as reportSpeechUsage, o as defaultEnv, p as resolveTranscriberConfig, r as registerOptionalTranscriber, v as normalizeAudioInput, y as normalizeMimeType } from "./chunks/registry-DFSF3WoM.js";
 //#region src/adapters/local/env.ts
 /**
 * Environment configuration for the `local` transcriber. Explicit options win,

package/dist/pcm.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@happyvertical/speech/pcm`: pure PCM and WAV utilities for the realtime
+ * transcribers. No Node APIs, no DOM; safe in browsers, workers and Node.
+ */
+export { WavFormatError, type WavFormatErrorReason } from './shared/errors.js';
+export { MAX_RESAMPLE_OUTPUT_SAMPLES, resampleMono, } from './shared/resample.js';
+export { encodeWavPcm16, float32ToPcm16, type ParsedWavPcm16, parseWavPcm16, pcm16ToFloat32, type WavExpectation, } from './shared/wav.js';
+//# sourceMappingURL=pcm.d.ts.map

package/dist/pcm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pcm.d.ts","sourceRoot":"","sources":["../src/pcm.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,EACL,2BAA2B,EAC3B,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,EACd,cAAc,EACd,KAAK,cAAc,EACnB,aAAa,EACb,cAAc,EACd,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC"}

package/dist/pcm.js

@@ -0,0 +1,3 @@
+import { o as WavFormatError } from "./chunks/errors-Cs0vX-mV.js";
+import { a as MAX_RESAMPLE_OUTPUT_SAMPLES, i as pcm16ToFloat32, n as float32ToPcm16, o as resampleMono, r as parseWavPcm16, t as encodeWavPcm16 } from "./chunks/wav-B0Djpj2r.js";
+export { MAX_RESAMPLE_OUTPUT_SAMPLES, WavFormatError, encodeWavPcm16, float32ToPcm16, parseWavPcm16, pcm16ToFloat32, resampleMono };

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/errors.d.ts

@@ -21,4 +21,22 @@ export declare class SpeechProviderError extends SpeechError {
         cause?: unknown;
     });
 }
+/** Why a WAV buffer was rejected by `parseWavPcm16`, or an encode input refused. */
+export type WavFormatErrorReason = 'not_riff' | 'truncated' | 'malformed_chunk' | 'missing_fmt' | 'duplicate_fmt' | 'data_before_fmt' | 'missing_data' | 'empty_data' | 'unsupported_format' | 'unsupported_bits' | 'inconsistent_header' | 'misaligned_data' | 'rate_mismatch' | 'channel_mismatch' | 'invalid_argument';
+/**
+ * Thrown by the PCM/WAV utilities (`@happyvertical/speech/pcm`) for input that
+ * is not exactly the 16-bit PCM WAV that was asked for, and for invalid
+ * arguments (sample rate, sizes). `reason` is stable and machine-readable.
+ */
+export declare class WavFormatError extends SpeechError {
+    readonly reason: WavFormatErrorReason;
+    constructor(reason: WavFormatErrorReason, message: string);
+}
+/** Why a browser PCM capture could not start or produce audio. */
+export type PcmCaptureErrorReason = 'unsupported' | 'setup_failed' | 'cancelled';
+/** Thrown by `createPcmCapture` (`@happyvertical/speech/browser`). */
+export declare class PcmCaptureError extends SpeechError {
+    readonly reason: PcmCaptureErrorReason;
+    constructor(reason: PcmCaptureErrorReason, message: string, cause?: unknown);
+}
 //# sourceMappingURL=errors.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,WAAY,SAAQ,KAAK;IAG3B,IAAI,EAAE,MAAM;IACZ,OAAO,CAAC,EAAE,MAAM;gBAFvB,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,YAAA;CAK1B;AAED,qBAAa,wBAAyB,SAAQ,WAAW;gBAC3C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAI9C;AAED,qBAAa,yBAA0B,SAAQ,WAAW;gBAC5C,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAIvC;AAED,qBAAa,mBAAoB,SAAQ,WAAW;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;gBAG7B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,OAAO,CAAC;KACZ;CAWT"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,WAAY,SAAQ,KAAK;IAG3B,IAAI,EAAE,MAAM;IACZ,OAAO,CAAC,EAAE,MAAM;gBAFvB,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,YAAA;CAK1B;AAED,qBAAa,wBAAyB,SAAQ,WAAW;gBAC3C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAI9C;AAED,qBAAa,yBAA0B,SAAQ,WAAW;gBAC5C,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAIvC;AAED,qBAAa,mBAAoB,SAAQ,WAAW;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;gBAG7B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,OAAO,CAAC;KACZ;CAWT;AAED,oFAAoF;AACpF,MAAM,MAAM,oBAAoB,GAC5B,UAAU,GACV,WAAW,GACX,iBAAiB,GACjB,aAAa,GACb,eAAe,GACf,iBAAiB,GACjB,cAAc,GACd,YAAY,GACZ,oBAAoB,GACpB,kBAAkB,GAClB,qBAAqB,GACrB,iBAAiB,GACjB,eAAe,GACf,kBAAkB,GAClB,kBAAkB,CAAC;AAEvB;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,WAAW;IAC7C,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;gBAE1B,MAAM,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM;CAK1D;AAED,kEAAkE;AAClE,MAAM,MAAM,qBAAqB,GAC7B,aAAa,GACb,cAAc,GACd,WAAW,CAAC;AAEhB,sEAAsE;AACtE,qBAAa,eAAgB,SAAQ,WAAW;IAC9C,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;gBAE3B,MAAM,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAQ5E"}

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

@@ -0,0 +1,20 @@
+import type { TranscriberType } from './types.js';
+/** What audio a transcriber type accepts from a caller. */
+export type TranscriberInputFormat = {
+    kind: 'compressed';
+} | {
+    kind: 'pcm16';
+    sampleRate: number;
+    channels: 1;
+};
+/**
+ * Says what to record for a transcriber type. `pcm16` types reject compressed
+ * containers (webm, ogg, mp3) and need 16-bit little-endian mono PCM, raw or in
+ * a WAV, at exactly `sampleRate`; use `@happyvertical/speech/browser` or
+ * `/pcm` to produce it. `compressed` types decode containers themselves
+ * (HTTP APIs, and the on-device transcriber, which decodes with the platform).
+ * For `openai-realtime` this is the default format; G.711 is an explicit
+ * adapter option and not a capture format.
+ */
+export declare function transcriberInputFormat(type: TranscriberType): TranscriberInputFormat;
+//# sourceMappingURL=input-format.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"input-format.d.ts","sourceRoot":"","sources":["../../src/shared/input-format.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,2DAA2D;AAC3D,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,CAAA;CAAE,CAAC;AAKvD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,eAAe,GACpB,sBAAsB,CAuBxB"}

package/dist/shared/pcm-capture.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Browser PCM capture: `MediaStream` -> mono Float32 at a requested rate and a
+ * ready 16-bit PCM WAV, via `AudioContext` + `AudioWorklet`. The worklet code
+ * is inlined and loaded from a Blob URL, so no bundler configuration is
+ * needed. Nothing here touches Node APIs; the Web Audio globals are read when
+ * `createPcmCapture` is called, so importing this module is SSR-safe.
+ */
+export interface PcmCaptureOptions {
+    /** Rate of the returned samples and WAV, in Hz (e.g. 16000 for Voxtral). */
+    sampleRate: number;
+    /** Audio beyond this duration is dropped, not stored. */
+    maxDurationMs: number;
+    /** Called once, when the cap is reached; the capture keeps running until stopped. */
+    onLimit?: () => void;
+}
+export interface PcmCaptureResult {
+    /** Mono samples at `sampleRate`, -1..1. */
+    samples: Float32Array;
+    /** The same audio as a 16-bit PCM mono WAV. */
+    wav: Uint8Array;
+    /** True when audio past `maxDurationMs` was dropped. */
+    truncated: boolean;
+}
+export interface PcmCapture {
+    /** Ends capture, tears everything down, and resolves with the audio. Idempotent. */
+    stop(): Promise<PcmCaptureResult>;
+    /** Discards the audio and tears everything down. Idempotent; a pending `stop()` rejects. */
+    cancel(): void;
+}
+/** Whether this runtime has the Web Audio pieces `createPcmCapture` needs. */
+export declare function pcmCaptureSupported(): boolean;
+/**
+ * Starts capturing `stream`. Throws `PcmCaptureError` (`unsupported`) when Web
+ * Audio is unavailable. The caller keeps ownership of the stream and its
+ * tracks: stop them yourself after `stop()` or `cancel()`.
+ */
+export declare function createPcmCapture(stream: MediaStream, options: PcmCaptureOptions): PcmCapture;
+//# sourceMappingURL=pcm-capture.d.ts.map

package/dist/shared/pcm-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pcm-capture.d.ts","sourceRoot":"","sources":["../../src/shared/pcm-capture.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgCH,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,OAAO,EAAE,YAAY,CAAC;IACtB,+CAA+C;IAC/C,GAAG,EAAE,UAAU,CAAC;IAChB,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,oFAAoF;IACpF,IAAI,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAClC,4FAA4F;IAC5F,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,IAAI,OAAO,CAQ7C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,iBAAiB,GACzB,UAAU,CA6IZ"}

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/resample.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Mono resampler: windowed-sinc (Hann, 16 zero crossings per side)
+ * interpolation. When downsampling, the kernel's cutoff is scaled to 95% of
+ * the target Nyquist frequency so content above it is attenuated before it can
+ * alias; when upsampling it is a plain band-limited interpolator. Edges treat
+ * missing samples as absent and renormalise the kernel, so DC gain stays 1.
+ * Quality is suited to speech recognition (passband flat to roughly 90% of
+ * Nyquist, stopband well below -40 dB), not mastering. Cost is
+ * O(output length x taps), taps ~ 32 x max(1, fromRate / toRate).
+ */
+/** Largest output a single call may produce (samples). */
+export declare const MAX_RESAMPLE_OUTPUT_SAMPLES: number;
+/** Resamples mono float samples from `fromRate` to `toRate` (Hz). */
+export declare function resampleMono(samples: Float32Array, fromRate: number, toRate: number): Float32Array;
+//# sourceMappingURL=resample.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resample.d.ts","sourceRoot":"","sources":["../../src/shared/resample.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,0DAA0D;AAC1D,eAAO,MAAM,2BAA2B,QAAU,CAAC;AAWnD,qEAAqE;AACrE,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,YAAY,CA2Cd"}

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/dist/shared/wav.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure, dependency-free 16-bit PCM WAV helpers. No Node APIs and no DOM: they
+ * run in the browser, in Node and in workers. Exposed as
+ * `@happyvertical/speech/pcm`.
+ *
+ * `parseWavPcm16` is strict because it reads untrusted bytes: every declared
+ * size is checked against the buffer before it is trusted, nothing is
+ * allocated from a declared (rather than present) size, and work is linear in
+ * the input length.
+ */
+/**
+ * Converts float samples (-1..1) to 16-bit PCM (scale 32768, the inverse of
+ * `pcm16ToFloat32`, so Int16 round-trips exactly). Clamps; NaN becomes 0.
+ */
+export declare function float32ToPcm16(samples: Float32Array): Int16Array;
+/** Converts 16-bit PCM to float samples in -1..1 (divides by 32768). */
+export declare function pcm16ToFloat32(samples: Int16Array): Float32Array;
+/**
+ * Encodes mono samples as a canonical 44-byte-header 16-bit PCM WAV. Float
+ * input is clamped and converted; `Int16Array` is written as is.
+ */
+export declare function encodeWavPcm16(samples: Float32Array | Int16Array, sampleRate: number): Uint8Array;
+/** Constraints `parseWavPcm16` enforces on the declared format. */
+export interface WavExpectation {
+    /** Required sample rate in Hz. */
+    sampleRate?: number;
+    /** Required channel count. */
+    channels?: number;
+}
+/** A validated 16-bit PCM WAV. */
+export interface ParsedWavPcm16 {
+    sampleRate: number;
+    channels: number;
+    /** Frames (one sample per channel). */
+    frames: number;
+    durationMs: number;
+    /** Interleaved samples, decoded to native endianness (a copy). */
+    samples: Int16Array;
+    /** The little-endian PCM bytes, a view into the input. */
+    data: Uint8Array;
+}
+/**
+ * Strictly parses a 16-bit PCM WAV. Rejects (with `WavFormatError`) anything
+ * that is not a well-formed RIFF/WAVE with a `fmt ` chunk before its `data`
+ * chunk, format tag 1 (or WAVE_FORMAT_EXTENSIBLE with the PCM subtype), 16
+ * bits, a consistent header, and a declared data length that lies within the
+ * buffer, is non-zero and is a whole number of frames. Nothing is clamped or
+ * guessed. Every chunk inside the declared RIFF is bounds-checked, including
+ * those after `data`; bytes beyond the RIFF are ignored.
+ */
+export declare function parseWavPcm16(bytes: Uint8Array, expect?: WavExpectation): ParsedWavPcm16;
+//# sourceMappingURL=wav.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wav.d.ts","sourceRoot":"","sources":["../../src/shared/wav.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAcH;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,UAAU,CAShE;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,YAAY,CAMhE;AAsBD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,GAAG,UAAU,EAClC,UAAU,EAAE,MAAM,GACjB,UAAU,CA6BZ;AAED,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,OAAO,EAAE,UAAU,CAAC;IACpB,0DAA0D;IAC1D,IAAI,EAAE,UAAU,CAAC;CAClB;AAqGD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,MAAM,GAAE,cAAmB,GAC1B,cAAc,CAsGhB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/speech",
-  "version": "0.101.3",
+  "version": "0.102.1",
   "description": "Speech provider abstraction for STT and TTS backends",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,6 +14,14 @@
       "import": "./dist/local.js",
       "types": "./dist/local.d.ts"
     },
+    "./pcm": {
+      "import": "./dist/pcm.js",
+      "types": "./dist/pcm.d.ts"
+    },
+    "./browser": {
+      "import": "./dist/browser.js",
+      "types": "./dist/browser.d.ts"
+    },
     "./conversation": {
       "import": "./dist/conversation.js",
       "types": "./dist/conversation.d.ts"

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

@@ -1 +0,0 @@
-{"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"}