realtime-voice-agents 2.0.1 → 2.2.0

package/dist/audio.cjs

@@ -1,21 +1,24 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_mulaw = require("./mulaw-DLUObjdP.cjs");
-const require_BackgroundAudioPlayer = require("./BackgroundAudioPlayer-jfRULWKC.cjs");
+const require_noise = require("./noise-D9jKottW.cjs");
 const require_transcode = require("./transcode-C9aJG7_W.cjs");
-exports.BackgroundAudioPlayer = require_BackgroundAudioPlayer.BackgroundAudioPlayer;
+exports.BackgroundAudioPlayer = require_noise.BackgroundAudioPlayer;
 exports.InboundTranscoder = require_transcode.InboundTranscoder;
 exports.MULAW_FRAME_BYTES_20MS = require_mulaw.MULAW_FRAME_BYTES_20MS;
 exports.MULAW_SAMPLE_RATE = require_mulaw.MULAW_SAMPLE_RATE;
 exports.MULAW_SILENCE_BYTE = require_mulaw.MULAW_SILENCE_BYTE;
+exports.NOISE_DBFS_FLOOR = require_noise.NOISE_DBFS_FLOOR;
+exports.NoiseFloorEstimator = require_noise.NoiseFloorEstimator;
 exports.OutboundTranscoder = require_transcode.OutboundTranscoder;
 exports.Resampler = require_transcode.Resampler;
 exports.base64ByteLength = require_mulaw.base64ByteLength;
-exports.fadeMulaw = require_BackgroundAudioPlayer.fadeMulaw;
-exports.isPresetName = require_BackgroundAudioPlayer.isPresetName;
-exports.loadBackgroundAudio = require_BackgroundAudioPlayer.loadBackgroundAudio;
+exports.fadeMulaw = require_noise.fadeMulaw;
+exports.isPresetName = require_noise.isPresetName;
+exports.loadBackgroundAudio = require_noise.loadBackgroundAudio;
 exports.mulawBytesToMs = require_mulaw.mulawBytesToMs;
 exports.mulawDecodeSample = require_mulaw.mulawDecodeSample;
 exports.mulawEncodeSample = require_mulaw.mulawEncodeSample;
+exports.mulawFrameDbfs = require_noise.mulawFrameDbfs;
 exports.mulawToPcm16 = require_mulaw.mulawToPcm16;
 exports.pcm16ToMulaw = require_mulaw.pcm16ToMulaw;
-exports.scaleMulaw = require_BackgroundAudioPlayer.scaleMulaw;
+exports.scaleMulaw = require_noise.scaleMulaw;

package/dist/audio.d.cts

@@ -25,6 +25,56 @@ 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/noise.d.ts
+/**
+ * Inbound noise metering: μ-law frames → dBFS levels → a sliding noise-floor
+ * estimate. Pure DSP — no timers, no audio-path buffering, no base64. The
+ * caller decides which frames to feed (exclusion policy lives upstream), so
+ * the estimator stays reusable outside the bridge.
+ */
+/** Clamp for silent/near-silent frames (all-0xFF μ-law decodes to 0). */
+declare const NOISE_DBFS_FLOOR = -100;
+/**
+ * RMS level of a μ-law frame in dBFS relative to PCM16 full scale (32768).
+ * μ-law's max decoded magnitude is 32124, so a full-scale μ-law tone reads
+ * ≈ −0.17 dBFS instead of 0 — negligible, and the numbers stay comparable to
+ * any standard PCM16 meter.
+ */
+declare function mulawFrameDbfs(mulaw: Uint8Array): number;
+interface NoiseFloorEstimatorOptions {
+  /** Sliding window of analyzed audio. Default 5000. */
+  windowMs?: number;
+  /** Percentile of per-slot RMS taken as the floor. Default 0.2. */
+  percentile?: number;
+}
+/**
+ * Sliding-window noise-floor estimator over 20 ms μ-law slots.
+ *
+ * The floor is a low percentile of per-slot RMS: speech bursts sit above it
+ * without inflating it, and genuine quiet pauses pull it down. With the
+ * default p20, `floorDb() ≥ T` means at least 80% of the window sits at or
+ * above T — pervasive line noise, not a loud caller. O(1) per slot: a 1 dB
+ * histogram plus a ring buffer of bucket indices.
+ */
+declare class NoiseFloorEstimator {
+  private readonly windowFrames;
+  private readonly percentile;
+  private readonly histogram;
+  private readonly ring;
+  private ringIndex;
+  private count;
+  /** <20 ms tail carried between addAudio calls (real Twilio frames are exactly 160 bytes). */
+  private residual;
+  constructor(options?: NoiseFloorEstimatorOptions);
+  /** Feed raw μ-law bytes (any length; 20 ms slotting + residual carry inside). */
+  addAudio(mulaw: Uint8Array): void;
+  /** True once a full window of analyzed audio has been observed. */
+  get isWarm(): boolean;
+  /** Noise floor over the window, dBFS in [NOISE_DBFS_FLOOR, 0]. */
+  floorDb(): number;
+  private addSlot;
+}
+//#endregion
 //#region src/audio/resampler.d.ts
 /**
  * Stateful polyphase FIR sample-rate converter.
@@ -162,4 +212,4 @@ declare function isPresetName(spec: BackgroundAudioSpec): spec is BackgroundAudi
 /** 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 };
+export { type BackgroundAudioOptions, BackgroundAudioPlayer, type BackgroundAudioPlayerDeps, type BackgroundAudioPreset, type BackgroundAudioSpec, InboundTranscoder, MULAW_FRAME_BYTES_20MS, MULAW_SAMPLE_RATE, MULAW_SILENCE_BYTE, NOISE_DBFS_FLOOR, NoiseFloorEstimator, type NoiseFloorEstimatorOptions, OutboundTranscoder, Resampler, type ResamplerOptions, base64ByteLength, fadeMulaw, isPresetName, loadBackgroundAudio, mulawBytesToMs, mulawDecodeSample, mulawEncodeSample, mulawFrameDbfs, mulawToPcm16, pcm16ToMulaw, scaleMulaw };

package/dist/audio.d.mts

@@ -25,6 +25,56 @@ 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/noise.d.ts
+/**
+ * Inbound noise metering: μ-law frames → dBFS levels → a sliding noise-floor
+ * estimate. Pure DSP — no timers, no audio-path buffering, no base64. The
+ * caller decides which frames to feed (exclusion policy lives upstream), so
+ * the estimator stays reusable outside the bridge.
+ */
+/** Clamp for silent/near-silent frames (all-0xFF μ-law decodes to 0). */
+declare const NOISE_DBFS_FLOOR = -100;
+/**
+ * RMS level of a μ-law frame in dBFS relative to PCM16 full scale (32768).
+ * μ-law's max decoded magnitude is 32124, so a full-scale μ-law tone reads
+ * ≈ −0.17 dBFS instead of 0 — negligible, and the numbers stay comparable to
+ * any standard PCM16 meter.
+ */
+declare function mulawFrameDbfs(mulaw: Uint8Array): number;
+interface NoiseFloorEstimatorOptions {
+  /** Sliding window of analyzed audio. Default 5000. */
+  windowMs?: number;
+  /** Percentile of per-slot RMS taken as the floor. Default 0.2. */
+  percentile?: number;
+}
+/**
+ * Sliding-window noise-floor estimator over 20 ms μ-law slots.
+ *
+ * The floor is a low percentile of per-slot RMS: speech bursts sit above it
+ * without inflating it, and genuine quiet pauses pull it down. With the
+ * default p20, `floorDb() ≥ T` means at least 80% of the window sits at or
+ * above T — pervasive line noise, not a loud caller. O(1) per slot: a 1 dB
+ * histogram plus a ring buffer of bucket indices.
+ */
+declare class NoiseFloorEstimator {
+  private readonly windowFrames;
+  private readonly percentile;
+  private readonly histogram;
+  private readonly ring;
+  private ringIndex;
+  private count;
+  /** <20 ms tail carried between addAudio calls (real Twilio frames are exactly 160 bytes). */
+  private residual;
+  constructor(options?: NoiseFloorEstimatorOptions);
+  /** Feed raw μ-law bytes (any length; 20 ms slotting + residual carry inside). */
+  addAudio(mulaw: Uint8Array): void;
+  /** True once a full window of analyzed audio has been observed. */
+  get isWarm(): boolean;
+  /** Noise floor over the window, dBFS in [NOISE_DBFS_FLOOR, 0]. */
+  floorDb(): number;
+  private addSlot;
+}
+//#endregion
 //#region src/audio/resampler.d.ts
 /**
  * Stateful polyphase FIR sample-rate converter.
@@ -162,4 +212,4 @@ declare function isPresetName(spec: BackgroundAudioSpec): spec is BackgroundAudi
 /** 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 };
+export { type BackgroundAudioOptions, BackgroundAudioPlayer, type BackgroundAudioPlayerDeps, type BackgroundAudioPreset, type BackgroundAudioSpec, InboundTranscoder, MULAW_FRAME_BYTES_20MS, MULAW_SAMPLE_RATE, MULAW_SILENCE_BYTE, NOISE_DBFS_FLOOR, NoiseFloorEstimator, type NoiseFloorEstimatorOptions, OutboundTranscoder, Resampler, type ResamplerOptions, base64ByteLength, fadeMulaw, isPresetName, loadBackgroundAudio, mulawBytesToMs, mulawDecodeSample, mulawEncodeSample, mulawFrameDbfs, mulawToPcm16, pcm16ToMulaw, scaleMulaw };

package/dist/audio.mjs

@@ -1,4 +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 { a as isPresetName, c as scaleMulaw, i as BackgroundAudioPlayer, n as NoiseFloorEstimator, o as loadBackgroundAudio, r as mulawFrameDbfs, s as fadeMulaw, t as NOISE_DBFS_FLOOR } from "./noise-CJ789zzj.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 };
+export { BackgroundAudioPlayer, InboundTranscoder, MULAW_FRAME_BYTES_20MS, MULAW_SAMPLE_RATE, MULAW_SILENCE_BYTE, NOISE_DBFS_FLOOR, NoiseFloorEstimator, OutboundTranscoder, Resampler, base64ByteLength, fadeMulaw, isPresetName, loadBackgroundAudio, mulawBytesToMs, mulawDecodeSample, mulawEncodeSample, mulawFrameDbfs, mulawToPcm16, pcm16ToMulaw, scaleMulaw };

package/dist/gemini.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_BaseRealtimeProvider = require("./BaseRealtimeProvider-DI4pKtOb.cjs");
+const require_BaseRealtimeProvider = require("./BaseRealtimeProvider-C2mRn1V_.cjs");
 const require_env = require("./env-DSnGaERV.cjs");
 const require_transcode = require("./transcode-C9aJG7_W.cjs");
 //#region src/providers/gemini/GeminiLiveProvider.ts
@@ -125,6 +125,7 @@ var GeminiLiveProvider = class extends require_BaseRealtimeProvider.BaseRealtime
 				throw setupError ?? (error instanceof Error ? error : new Error(String(error)));
 			}
 			await setupDone;
+			this.effectiveVadValue = init.vad !== void 0 ? init.vad : this.config.defaultVad;
 		} finally {
 			clearTimeout(timer);
 		}
@@ -372,12 +373,14 @@ const GEMINI_VOICES = [
 	"Kore",
 	"Puck"
 ];
-/** Create a Gemini Live provider factory for the bridge. */
+/**
+* Create a Gemini Live provider factory for the bridge. Credentials are
+* resolved per call (see `openaiRealtime` — missing credentials fail that
+* call's connect so a fallback chain can absorb it, instead of crashing
+* config construction).
+*/
 function geminiLive(options = {}) {
-	const apiKey = require_env.resolveApiKey(options.apiKey, GEMINI_KEY_ENV_VARS);
-	if (!apiKey && !options.vertex && !options.connector) throw new Error(`geminiLive: credentials missing (pass apiKey, set one of ${GEMINI_KEY_ENV_VARS.join("/")}, or configure vertex)`);
 	const config = {
-		apiKey,
 		vertex: options.vertex,
 		model: options.model ?? "gemini-2.5-flash-native-audio-preview-12-2025",
 		voice: options.voice ?? "Aoede",
@@ -390,7 +393,14 @@ function geminiLive(options = {}) {
 		connectTimeoutMs: options.connectTimeoutMs,
 		connector: options.connector
 	};
-	return ({ logger }) => new GeminiLiveProvider(config, logger);
+	return ({ logger }) => {
+		const apiKey = require_env.resolveApiKey(options.apiKey, GEMINI_KEY_ENV_VARS);
+		if (!apiKey && !options.vertex && !options.connector) throw new Error(`geminiLive: credentials missing (pass apiKey, set one of ${GEMINI_KEY_ENV_VARS.join("/")}, or configure vertex)`);
+		return new GeminiLiveProvider({
+			...config,
+			apiKey
+		}, logger);
+	};
 }
 //#endregion
 exports.GEMINI_DEFAULT_MODEL = GEMINI_DEFAULT_MODEL;

package/dist/gemini.d.cts

@@ -1,5 +1,5 @@
-import { c as VadConfig, n as ProviderFactory } from "./BaseRealtimeProvider-BehPNT1r.cjs";
-import { a as GeminiLiveSessionLike, i as GeminiLiveProviderConfig, n as GeminiLiveConnector, r as GeminiLiveProvider, t as GeminiConnectParams } from "./GeminiLiveProvider-DvkTgzjG.cjs";
+import { l as VadConfig, n as ProviderFactory } from "./BaseRealtimeProvider-BL75_HHh.cjs";
+import { a as GeminiLiveSessionLike, i as GeminiLiveProviderConfig, n as GeminiLiveConnector, r as GeminiLiveProvider, t as GeminiConnectParams } from "./GeminiLiveProvider-Cc1dkxW6.cjs";
 //#region src/gemini.d.ts
 /** Env vars checked (in order) when no explicit apiKey is passed. */
 declare const GEMINI_KEY_ENV_VARS: readonly ["GOOGLE_API_KEY", "GEMINI_API_KEY", "GOOGLE_GENAI_API_KEY"];
@@ -35,7 +35,12 @@ interface GeminiLiveOptions {
   /** Test seam: replaces the @google/genai live connection. */
   connector?: GeminiLiveConnector;
 }
-/** Create a Gemini Live provider factory for the bridge. */
+/**
+ * Create a Gemini Live provider factory for the bridge. Credentials are
+ * resolved per call (see `openaiRealtime` — missing credentials fail that
+ * call's connect so a fallback chain can absorb it, instead of crashing
+ * config construction).
+ */
 declare function geminiLive(options?: GeminiLiveOptions): ProviderFactory;
 //#endregion
 export { GEMINI_DEFAULT_MODEL, GEMINI_DEFAULT_VOICE, GEMINI_KEY_ENV_VARS, GEMINI_VOICES, type GeminiConnectParams, type GeminiLiveConnector, GeminiLiveOptions, GeminiLiveProvider, type GeminiLiveProviderConfig, type GeminiLiveSessionLike, geminiLive };

package/dist/gemini.d.mts

@@ -1,5 +1,5 @@
-import { c as VadConfig, n as ProviderFactory } from "./BaseRealtimeProvider-ClP8Wx1X.mjs";
-import { a as GeminiLiveSessionLike, i as GeminiLiveProviderConfig, n as GeminiLiveConnector, r as GeminiLiveProvider, t as GeminiConnectParams } from "./GeminiLiveProvider-x2nyx5aO.mjs";
+import { l as VadConfig, n as ProviderFactory } from "./BaseRealtimeProvider-CWJ81HIt.mjs";
+import { a as GeminiLiveSessionLike, i as GeminiLiveProviderConfig, n as GeminiLiveConnector, r as GeminiLiveProvider, t as GeminiConnectParams } from "./GeminiLiveProvider-TvY_cQQZ.mjs";
 //#region src/gemini.d.ts
 /** Env vars checked (in order) when no explicit apiKey is passed. */
 declare const GEMINI_KEY_ENV_VARS: readonly ["GOOGLE_API_KEY", "GEMINI_API_KEY", "GOOGLE_GENAI_API_KEY"];
@@ -35,7 +35,12 @@ interface GeminiLiveOptions {
   /** Test seam: replaces the @google/genai live connection. */
   connector?: GeminiLiveConnector;
 }
-/** Create a Gemini Live provider factory for the bridge. */
+/**
+ * Create a Gemini Live provider factory for the bridge. Credentials are
+ * resolved per call (see `openaiRealtime` — missing credentials fail that
+ * call's connect so a fallback chain can absorb it, instead of crashing
+ * config construction).
+ */
 declare function geminiLive(options?: GeminiLiveOptions): ProviderFactory;
 //#endregion
 export { GEMINI_DEFAULT_MODEL, GEMINI_DEFAULT_VOICE, GEMINI_KEY_ENV_VARS, GEMINI_VOICES, type GeminiConnectParams, type GeminiLiveConnector, GeminiLiveOptions, GeminiLiveProvider, type GeminiLiveProviderConfig, type GeminiLiveSessionLike, geminiLive };

package/dist/gemini.mjs

@@ -1,4 +1,4 @@
-import { a as noopLogger, n as deepMerge, t as BaseRealtimeProvider } from "./BaseRealtimeProvider-BQigr5mB.mjs";
+import { a as noopLogger, n as deepMerge, t as BaseRealtimeProvider } from "./BaseRealtimeProvider-C9C3s8jx.mjs";
 import { t as resolveApiKey } from "./env-DUwUWTsg.mjs";
 import { n as OutboundTranscoder, t as InboundTranscoder } from "./transcode-CsAp97G9.mjs";
 //#region src/providers/gemini/GeminiLiveProvider.ts
@@ -124,6 +124,7 @@ var GeminiLiveProvider = class extends BaseRealtimeProvider {
 				throw setupError ?? (error instanceof Error ? error : new Error(String(error)));
 			}
 			await setupDone;
+			this.effectiveVadValue = init.vad !== void 0 ? init.vad : this.config.defaultVad;
 		} finally {
 			clearTimeout(timer);
 		}
@@ -371,12 +372,14 @@ const GEMINI_VOICES = [
 	"Kore",
 	"Puck"
 ];
-/** Create a Gemini Live provider factory for the bridge. */
+/**
+* Create a Gemini Live provider factory for the bridge. Credentials are
+* resolved per call (see `openaiRealtime` — missing credentials fail that
+* call's connect so a fallback chain can absorb it, instead of crashing
+* config construction).
+*/
 function geminiLive(options = {}) {
-	const apiKey = resolveApiKey(options.apiKey, GEMINI_KEY_ENV_VARS);
-	if (!apiKey && !options.vertex && !options.connector) throw new Error(`geminiLive: credentials missing (pass apiKey, set one of ${GEMINI_KEY_ENV_VARS.join("/")}, or configure vertex)`);
 	const config = {
-		apiKey,
 		vertex: options.vertex,
 		model: options.model ?? "gemini-2.5-flash-native-audio-preview-12-2025",
 		voice: options.voice ?? "Aoede",
@@ -389,7 +392,14 @@ function geminiLive(options = {}) {
 		connectTimeoutMs: options.connectTimeoutMs,
 		connector: options.connector
 	};
-	return ({ logger }) => new GeminiLiveProvider(config, logger);
+	return ({ logger }) => {
+		const apiKey = resolveApiKey(options.apiKey, GEMINI_KEY_ENV_VARS);
+		if (!apiKey && !options.vertex && !options.connector) throw new Error(`geminiLive: credentials missing (pass apiKey, set one of ${GEMINI_KEY_ENV_VARS.join("/")}, or configure vertex)`);
+		return new GeminiLiveProvider({
+			...config,
+			apiKey
+		}, logger);
+	};
 }
 //#endregion
 export { GEMINI_DEFAULT_MODEL, GEMINI_DEFAULT_VOICE, GEMINI_KEY_ENV_VARS, GEMINI_VOICES, GeminiLiveProvider, geminiLive };