realtime-voice-agents 2.0.0

package/dist/audio.d.mts

@@ -0,0 +1,165 @@
+import { n as BackgroundAudioPreset, r as BackgroundAudioSpec, t as BackgroundAudioOptions } from "./presets-Bf75YXs5.mjs";
+//#region src/audio/mulaw.d.ts
+/**
+ * G.711 μ-law codec (the format Twilio Media Streams speak: 8 kHz, 1 byte/sample).
+ *
+ * Decode uses a 256-entry lookup table; encode uses the canonical Sun g711.c
+ * algorithm (bias 0x84, clip 32635). μ-law silence is 0xFF.
+ */
+/** One byte of μ-law silence (encodes linear 0). */
+declare const MULAW_SILENCE_BYTE = 255;
+/** Samples per second on the Twilio media stream. μ-law is 1 byte per sample. */
+declare const MULAW_SAMPLE_RATE = 8000;
+/** Bytes per 20 ms Twilio media frame at 8 kHz μ-law. */
+declare const MULAW_FRAME_BYTES_20MS = 160;
+/** Decode a single μ-law byte to a linear PCM16 sample. */
+declare function mulawDecodeSample(byte: number): number;
+/** Encode a single linear PCM16 sample to a μ-law byte. */
+declare function mulawEncodeSample(sample: number): number;
+/** Decode a μ-law buffer to linear PCM16 samples. */
+declare function mulawToPcm16(mulaw: Uint8Array): Int16Array;
+/** Encode linear PCM16 samples to a μ-law buffer. */
+declare function pcm16ToMulaw(pcm: Int16Array): Uint8Array;
+/** Duration in milliseconds of a μ-law byte count at 8 kHz (1 byte = 125 µs). */
+declare function mulawBytesToMs(bytes: number): number;
+/** Byte length of a base64 string without decoding it. */
+declare function base64ByteLength(base64: string): number;
+//#endregion
+//#region src/audio/resampler.d.ts
+/**
+ * Stateful polyphase FIR sample-rate converter.
+ *
+ * Built for streaming telephony audio: the instance carries the FIR history
+ * across process() calls, so chunk boundaries produce bit-identical output to
+ * single-pass processing — no per-chunk zero-padding, no boundary clicks.
+ * Coefficients are computed once per (from, to, quality) in a module cache.
+ *
+ * Rational L/M design: the prototype lowpass is a Kaiser-windowed sinc at the
+ * upsampled rate (from × L), decomposed into L phases of N/L taps. Each phase
+ * is normalized to unit DC gain so constant signals pass through exactly.
+ */
+interface ResamplerOptions {
+  /**
+   * Prototype filter length multiplier. The prototype has
+   * `quality × max(L, M)` taps (rounded up to a multiple of L); higher is
+   * cleaner and slower. Default 48 (≈70–80 dB alias rejection for 24k→8k).
+   */
+  quality?: number;
+  /** Kaiser window beta. Default 8. */
+  kaiserBeta?: number;
+  /** Passband edge as a fraction of the tighter Nyquist. Default 0.9. */
+  rolloff?: number;
+}
+declare class Resampler {
+  readonly fromRate: number;
+  readonly toRate: number;
+  private readonly L;
+  private readonly M;
+  private readonly bank;
+  /** Trailing input samples carried between chunks (tapsPerPhase − 1 long). */
+  private hist;
+  /** Phase index of the next output sample. */
+  private phase;
+  /**
+   * Input index (relative to the start of the next [hist + chunk] buffer) that
+   * the next output sample is anchored on. Always ≥ tapsPerPhase − 1.
+   */
+  private kRel;
+  constructor(fromRate: number, toRate: number, options?: ResamplerOptions);
+  /** True when no rate conversion is needed (input is passed through). */
+  get isPassthrough(): boolean;
+  process(input: Int16Array): Int16Array;
+  /** Drain the filter tail by pushing one phase-length of silence. */
+  flush(): Int16Array;
+  /** Clear all carried state (history, phase) for reuse on a fresh stream. */
+  reset(): void;
+}
+//#endregion
+//#region src/audio/transcode.d.ts
+/** Twilio → provider: base64 μ-law 8 kHz in, base64 PCM16LE at `outRate` out. */
+declare class InboundTranscoder {
+  private readonly resampler;
+  constructor(outRate?: number, options?: ResamplerOptions);
+  process(base64Mulaw: string): string;
+  reset(): void;
+}
+/** Provider → Twilio: base64 PCM16LE at `inRate` in, base64 μ-law 8 kHz out. */
+declare class OutboundTranscoder {
+  private readonly resampler;
+  /** Dangling byte from a chunk that split a 16-bit sample. */
+  private carry;
+  constructor(inRate?: number, options?: ResamplerOptions);
+  process(base64Pcm16: string): string;
+  reset(): void;
+}
+//#endregion
+//#region src/audio/gain.d.ts
+/**
+ * Gain application on μ-law frames, used for background-audio fades and volume.
+ * μ-law is logarithmic, so gain must ramp in the linear domain:
+ * decode → scale → re-encode.
+ */
+/** Scale an entire μ-law frame by a constant linear gain. */
+declare function scaleMulaw(frame: Uint8Array, gain: number): Uint8Array;
+/**
+ * Apply a linearly interpolated gain ramp across a μ-law frame
+ * (`startGain` at the first sample → `endGain` at the last).
+ */
+declare function fadeMulaw(frame: Uint8Array, startGain: number, endGain: number): Uint8Array;
+//#endregion
+//#region src/audio/background/BackgroundAudioPlayer.d.ts
+interface BackgroundAudioPlayerDeps {
+  sendMedia: (base64Payload: string) => void;
+  onStarted?: (info: {
+    preset?: string;
+  }) => void;
+  onStopped?: (info: {
+    preset?: string;
+  }) => void;
+  now?: () => number;
+}
+declare class BackgroundAudioPlayer {
+  private readonly deps;
+  private readonly now;
+  private generation;
+  private active;
+  private startDelayTimer;
+  /** Tool-call ids currently holding the loop. */
+  private readonly holders;
+  private pendingSpec;
+  constructor(deps: BackgroundAudioPlayerDeps);
+  get isPlaying(): boolean;
+  /**
+   * Refcounted acquisition (one holder per tool call). The loop starts after
+   * `startDelayMs` unless every holder releases first.
+   */
+  acquire(holderId: string, spec: BackgroundAudioSpec, options?: BackgroundAudioOptions): void;
+  /** Release one holder; the loop stops when the last holder releases. */
+  release(holderId: string, opts?: {
+    immediate?: boolean;
+  }): void;
+  /** Direct start (facade `playBackgroundAudio`). Bypasses refcounting. */
+  start(spec: BackgroundAudioSpec, options?: BackgroundAudioOptions): void;
+  /**
+   * Stop the loop. Fade-out is applied when `immediate` is false and a
+   * fadeOutMs was configured; agent-audio preemption should pass
+   * `immediate: true` (a fade would delay real speech behind it).
+   */
+  stop(opts?: {
+    immediate?: boolean;
+  }): void;
+  /** Real agent audio arrived — kill the loop instantly, no fade, no clear. */
+  notifyAgentAudio(): void;
+  private cancelDelay;
+  private startNow;
+  private tick;
+  /** Wrap-around frame extraction for seamless looping. */
+  private extractFrame;
+}
+//#endregion
+//#region src/audio/background/loader.d.ts
+declare function isPresetName(spec: BackgroundAudioSpec): spec is BackgroundAudioPreset;
+/** Resolve a spec to raw μ-law bytes (cached per preset/path). */
+declare function loadBackgroundAudio(spec: BackgroundAudioSpec): Buffer;
+//#endregion
+export { type BackgroundAudioOptions, BackgroundAudioPlayer, type BackgroundAudioPlayerDeps, type BackgroundAudioPreset, type BackgroundAudioSpec, InboundTranscoder, MULAW_FRAME_BYTES_20MS, MULAW_SAMPLE_RATE, MULAW_SILENCE_BYTE, OutboundTranscoder, Resampler, type ResamplerOptions, base64ByteLength, fadeMulaw, isPresetName, loadBackgroundAudio, mulawBytesToMs, mulawDecodeSample, mulawEncodeSample, mulawToPcm16, pcm16ToMulaw, scaleMulaw };

package/dist/audio.mjs

@@ -0,0 +1,4 @@
+import { a as mulawBytesToMs, c as mulawToPcm16, i as base64ByteLength, l as pcm16ToMulaw, n as MULAW_SAMPLE_RATE, o as mulawDecodeSample, r as MULAW_SILENCE_BYTE, s as mulawEncodeSample, t as MULAW_FRAME_BYTES_20MS } from "./mulaw--cwU2c9L.mjs";
+import { a as scaleMulaw, i as fadeMulaw, n as isPresetName, r as loadBackgroundAudio, t as BackgroundAudioPlayer } from "./BackgroundAudioPlayer-iMcivjis.mjs";
+import { n as OutboundTranscoder, r as Resampler, t as InboundTranscoder } from "./transcode-CsAp97G9.mjs";
+export { BackgroundAudioPlayer, InboundTranscoder, MULAW_FRAME_BYTES_20MS, MULAW_SAMPLE_RATE, MULAW_SILENCE_BYTE, OutboundTranscoder, Resampler, base64ByteLength, fadeMulaw, isPresetName, loadBackgroundAudio, mulawBytesToMs, mulawDecodeSample, mulawEncodeSample, mulawToPcm16, pcm16ToMulaw, scaleMulaw };

package/dist/env-DSnGaERV.cjs

@@ -0,0 +1,19 @@
+//#region src/internal/env.ts
+/**
+* Resolve an API key: an explicitly passed key always wins; otherwise the
+* first non-empty value among the given environment variable names is used.
+*/
+function resolveApiKey(explicit, envNames) {
+	if (explicit) return explicit;
+	for (const name of envNames) {
+		const value = process.env[name];
+		if (value) return value;
+	}
+}
+//#endregion
+Object.defineProperty(exports, "resolveApiKey", {
+	enumerable: true,
+	get: function() {
+		return resolveApiKey;
+	}
+});

package/dist/env-DUwUWTsg.mjs

@@ -0,0 +1,14 @@
+//#region src/internal/env.ts
+/**
+* Resolve an API key: an explicitly passed key always wins; otherwise the
+* first non-empty value among the given environment variable names is used.
+*/
+function resolveApiKey(explicit, envNames) {
+	if (explicit) return explicit;
+	for (const name of envNames) {
+		const value = process.env[name];
+		if (value) return value;
+	}
+}
+//#endregion
+export { resolveApiKey as t };

package/dist/events-BUMYdETO.d.cts

@@ -0,0 +1,24 @@
+//#region src/internal/events.d.ts
+type Listener = (...args: any[]) => void;
+/**
+ * EventEmitter with a typed event map. Listener errors are contained per
+ * Node's usual semantics; `emit` returns whether any listener ran.
+ *
+ * The constraint deliberately avoids `Record<string, Listener>`: event-map
+ * interfaces must NOT carry a string index signature, or `keyof` widens to
+ * `string` and misspelled event names compile silently (a listener that can
+ * never fire). With the mapped-type constraint, plain interfaces qualify and
+ * unknown names are compile-time errors.
+ */
+declare class TypedEmitter<Events extends { [K in keyof Events]: Listener; }> {
+  private readonly emitter;
+  constructor();
+  on<K extends keyof Events & string>(event: K, listener: Events[K]): this;
+  once<K extends keyof Events & string>(event: K, listener: Events[K]): this;
+  off<K extends keyof Events & string>(event: K, listener: Events[K]): this;
+  removeAllListeners(event?: keyof Events & string): this;
+  protected emit<K extends keyof Events & string>(event: K, ...args: Parameters<Events[K]>): boolean;
+  listenerCount(event: keyof Events & string): number;
+}
+//#endregion
+export { TypedEmitter as t };

package/dist/events-BUMYdETO.d.mts

@@ -0,0 +1,24 @@
+//#region src/internal/events.d.ts
+type Listener = (...args: any[]) => void;
+/**
+ * EventEmitter with a typed event map. Listener errors are contained per
+ * Node's usual semantics; `emit` returns whether any listener ran.
+ *
+ * The constraint deliberately avoids `Record<string, Listener>`: event-map
+ * interfaces must NOT carry a string index signature, or `keyof` widens to
+ * `string` and misspelled event names compile silently (a listener that can
+ * never fire). With the mapped-type constraint, plain interfaces qualify and
+ * unknown names are compile-time errors.
+ */
+declare class TypedEmitter<Events extends { [K in keyof Events]: Listener; }> {
+  private readonly emitter;
+  constructor();
+  on<K extends keyof Events & string>(event: K, listener: Events[K]): this;
+  once<K extends keyof Events & string>(event: K, listener: Events[K]): this;
+  off<K extends keyof Events & string>(event: K, listener: Events[K]): this;
+  removeAllListeners(event?: keyof Events & string): this;
+  protected emit<K extends keyof Events & string>(event: K, ...args: Parameters<Events[K]>): boolean;
+  listenerCount(event: keyof Events & string): number;
+}
+//#endregion
+export { TypedEmitter as t };

package/dist/events-BxDTIKKq.cjs

@@ -0,0 +1,48 @@
+let node_events = require("node:events");
+//#region src/internal/events.ts
+/**
+* EventEmitter with a typed event map. Listener errors are contained per
+* Node's usual semantics; `emit` returns whether any listener ran.
+*
+* The constraint deliberately avoids `Record<string, Listener>`: event-map
+* interfaces must NOT carry a string index signature, or `keyof` widens to
+* `string` and misspelled event names compile silently (a listener that can
+* never fire). With the mapped-type constraint, plain interfaces qualify and
+* unknown names are compile-time errors.
+*/
+var TypedEmitter = class {
+	emitter = new node_events.EventEmitter();
+	constructor() {
+		this.emitter.setMaxListeners(50);
+	}
+	on(event, listener) {
+		this.emitter.on(event, listener);
+		return this;
+	}
+	once(event, listener) {
+		this.emitter.once(event, listener);
+		return this;
+	}
+	off(event, listener) {
+		this.emitter.off(event, listener);
+		return this;
+	}
+	removeAllListeners(event) {
+		this.emitter.removeAllListeners(event);
+		return this;
+	}
+	emit(event, ...args) {
+		if (event === "error" && this.emitter.listenerCount("error") === 0) return false;
+		return this.emitter.emit(event, ...args);
+	}
+	listenerCount(event) {
+		return this.emitter.listenerCount(event);
+	}
+};
+//#endregion
+Object.defineProperty(exports, "TypedEmitter", {
+	enumerable: true,
+	get: function() {
+		return TypedEmitter;
+	}
+});

package/dist/events-BylBSBW-.mjs

@@ -0,0 +1,43 @@
+import { EventEmitter } from "node:events";
+//#region src/internal/events.ts
+/**
+* EventEmitter with a typed event map. Listener errors are contained per
+* Node's usual semantics; `emit` returns whether any listener ran.
+*
+* The constraint deliberately avoids `Record<string, Listener>`: event-map
+* interfaces must NOT carry a string index signature, or `keyof` widens to
+* `string` and misspelled event names compile silently (a listener that can
+* never fire). With the mapped-type constraint, plain interfaces qualify and
+* unknown names are compile-time errors.
+*/
+var TypedEmitter = class {
+	emitter = new EventEmitter();
+	constructor() {
+		this.emitter.setMaxListeners(50);
+	}
+	on(event, listener) {
+		this.emitter.on(event, listener);
+		return this;
+	}
+	once(event, listener) {
+		this.emitter.once(event, listener);
+		return this;
+	}
+	off(event, listener) {
+		this.emitter.off(event, listener);
+		return this;
+	}
+	removeAllListeners(event) {
+		this.emitter.removeAllListeners(event);
+		return this;
+	}
+	emit(event, ...args) {
+		if (event === "error" && this.emitter.listenerCount("error") === 0) return false;
+		return this.emitter.emit(event, ...args);
+	}
+	listenerCount(event) {
+		return this.emitter.listenerCount(event);
+	}
+};
+//#endregion
+export { TypedEmitter as t };