@absolutejs/voice 0.0.22-beta.552 → 0.0.22-beta.553

package/dist/core/types.d.ts

@@ -894,6 +894,28 @@ export type CreateVoiceSessionOptions<TContext = unknown, TSession extends Voice
     };
     redact?: import("./redaction").VoiceTranscriptRedactor;
     semanticTurnDetector?: import("./semanticTurn").VoiceSemanticTurnDetector;
+    /**
+     * Pre-rendered filler phrases the runtime plays in the gap between
+     * user-turn-commit and real assistant audio (typically 800-1500ms). The
+     * caller hears something within ~150-300ms of stopping speaking, so the
+     * LLM/TTS latency feels like the bot thinking instead of dead air. Boardy's
+     * killer UX feature.
+     *
+     * Behavior:
+     *  - After a turn commits, a timer fires at `fillerDelayMs` (default
+     *    250ms). At that point, if the real assistant audio for this turn
+     *    hasn't started flowing yet, a random phrase is rendered via the
+     *    configured `tts` adapter and pushed to the socket.
+     *  - When the real assistant audio's first chunk arrives, any in-flight
+     *    filler is cancelled (`cancelActiveTTS` clears the carrier buffer).
+     *  - Cooldown protects against double-fillers per turn.
+     *
+     * Set `fillerPhrases: []` (or omit) to disable. Reasonable defaults if
+     * you enable: `["Hmm.", "Got it.", "Right.", "Mm-hm.", "Let me think.", "Okay."]`.
+     */
+    fillerPhrases?: ReadonlyArray<string>;
+    /** Milliseconds after turn-commit before the filler fires. Default 250ms — short enough to feel instant, long enough to skip if the LLM is very fast. */
+    fillerDelayMs?: number;
     assistantMode?: import("./assistantMode").VoiceAssistantMode;
     modalities?: ReadonlyArray<"audio" | "text">;
     prosody?: VoiceTTSProsody;

package/dist/index.js

@@ -3870,6 +3870,11 @@ var createVoiceSession = (options) => {
   let adapterGenerationCounter = 0;
   let activeAdapterGeneration = 0;
   let activeTTSTurnId;
+  let fillerTimer = null;
+  let fillerActive = false;
+  let fillerToken = 0;
+  const fillerPhrases = (options.fillerPhrases ?? []).filter((p) => typeof p === "string" && p.trim().length > 0);
+  const fillerDelayMs = options.fillerDelayMs ?? 250;
   const currentTurnAudio = [];
   const pendingUserAttachments = [];
   let fallbackAttemptsForCurrentTurn = 0;
@@ -5268,6 +5273,36 @@ var createVoiceSession = (options) => {
     }
     const injectedInstruction = liveOpsControl?.injectedInstruction?.trim();
     const ttsStreamer = options.tts ? createTurnTTSStreamer(turn, session) : undefined;
+    if (fillerPhrases.length > 0 && options.tts && !ttsStreamer) {}
+    if (fillerPhrases.length > 0 && options.tts) {
+      fillerToken += 1;
+      const myToken = fillerToken;
+      if (fillerTimer)
+        clearTimeout(fillerTimer);
+      fillerTimer = setTimeout(() => {
+        fillerTimer = null;
+        if (myToken !== fillerToken)
+          return;
+        if (activeTTSTurnId === turn.id)
+          return;
+        const phrase = fillerPhrases[Math.floor(Math.random() * fillerPhrases.length)] ?? "";
+        if (!phrase)
+          return;
+        runSerial("filler.send", async () => {
+          if (myToken !== fillerToken || activeTTSTurnId === turn.id)
+            return;
+          const adapterSession = await ensureTTSSession();
+          if (!adapterSession)
+            return;
+          fillerActive = true;
+          try {
+            await adapterSession.send(phrase);
+          } catch {
+            fillerActive = false;
+          }
+        });
+      }, fillerDelayMs);
+    }
     const committedOutput = await options.route.onTurn({
       api,
       context: options.context,
@@ -5348,6 +5383,15 @@ var createVoiceSession = (options) => {
       try {
         const activeTTSSession = await ensureTTSSession();
         if (activeTTSSession) {
+          fillerToken += 1;
+          if (fillerTimer) {
+            clearTimeout(fillerTimer);
+            fillerTimer = null;
+          }
+          if (fillerActive) {
+            await cancelActiveTTS("filler-superseded").catch(() => {});
+            fillerActive = false;
+          }
           const ttsStartedAt = Date.now();
           activeTTSTurnId = turn.id;
           await appendTurnLatencyStage({
@@ -24562,6 +24606,8 @@ var createTwilioMediaStreamBridge = (socket, options) => {
       sttFallback: resolveSTTFallbackConfig(options.sttFallback),
       sttLifecycle: options.sttLifecycle ?? runtimePreset.sttLifecycle,
       ...options.semanticTurnDetector ? { semanticTurnDetector: options.semanticTurnDetector } : {},
+      ...options.fillerPhrases ? { fillerPhrases: options.fillerPhrases } : {},
+      ...options.fillerDelayMs !== undefined ? { fillerDelayMs: options.fillerDelayMs } : {},
       trace: options.trace,
       tts: options.tts,
       turnDetection

package/dist/telephony/twilio.d.ts

@@ -123,6 +123,15 @@ export type TwilioMediaStreamBridgeOptions<TContext = unknown, TSession extends
      * snappy responses on clear-cut answers. See VoiceSemanticTurnDetector.
      */
     semanticTurnDetector?: import("../core/semanticTurn").VoiceSemanticTurnDetector;
+    /**
+     * Pre-rendered filler phrases ("Hmm.", "Got it.", "Let me think.") played
+     * in the gap between user-turn-commit and real assistant audio. Boardy's
+     * "the pause is character, not lag" pattern. See CreateVoiceSessionOptions
+     * for full semantics.
+     */
+    fillerPhrases?: ReadonlyArray<string>;
+    /** Milliseconds after turn-commit before the filler fires. Default 250ms. */
+    fillerDelayMs?: number;
 };
 export type TwilioMediaStreamBridge = {
     close: (reason?: string) => Promise<void>;

package/dist/testing/index.js

@@ -5687,6 +5687,11 @@ var createVoiceSession = (options) => {
   let adapterGenerationCounter = 0;
   let activeAdapterGeneration = 0;
   let activeTTSTurnId;
+  let fillerTimer = null;
+  let fillerActive = false;
+  let fillerToken = 0;
+  const fillerPhrases = (options.fillerPhrases ?? []).filter((p) => typeof p === "string" && p.trim().length > 0);
+  const fillerDelayMs = options.fillerDelayMs ?? 250;
   const currentTurnAudio = [];
   const pendingUserAttachments = [];
   let fallbackAttemptsForCurrentTurn = 0;
@@ -7085,6 +7090,36 @@ var createVoiceSession = (options) => {
     }
     const injectedInstruction = liveOpsControl?.injectedInstruction?.trim();
     const ttsStreamer = options.tts ? createTurnTTSStreamer(turn, session) : undefined;
+    if (fillerPhrases.length > 0 && options.tts && !ttsStreamer) {}
+    if (fillerPhrases.length > 0 && options.tts) {
+      fillerToken += 1;
+      const myToken = fillerToken;
+      if (fillerTimer)
+        clearTimeout(fillerTimer);
+      fillerTimer = setTimeout(() => {
+        fillerTimer = null;
+        if (myToken !== fillerToken)
+          return;
+        if (activeTTSTurnId === turn.id)
+          return;
+        const phrase = fillerPhrases[Math.floor(Math.random() * fillerPhrases.length)] ?? "";
+        if (!phrase)
+          return;
+        runSerial("filler.send", async () => {
+          if (myToken !== fillerToken || activeTTSTurnId === turn.id)
+            return;
+          const adapterSession = await ensureTTSSession();
+          if (!adapterSession)
+            return;
+          fillerActive = true;
+          try {
+            await adapterSession.send(phrase);
+          } catch {
+            fillerActive = false;
+          }
+        });
+      }, fillerDelayMs);
+    }
     const committedOutput = await options.route.onTurn({
       api,
       context: options.context,
@@ -7165,6 +7200,15 @@ var createVoiceSession = (options) => {
       try {
         const activeTTSSession = await ensureTTSSession();
         if (activeTTSSession) {
+          fillerToken += 1;
+          if (fillerTimer) {
+            clearTimeout(fillerTimer);
+            fillerTimer = null;
+          }
+          if (fillerActive) {
+            await cancelActiveTTS("filler-superseded").catch(() => {});
+            fillerActive = false;
+          }
           const ttsStartedAt = Date.now();
           activeTTSTurnId = turn.id;
           await appendTurnLatencyStage({
@@ -13098,6 +13142,8 @@ var createTwilioMediaStreamBridge = (socket, options) => {
       sttFallback: resolveSTTFallbackConfig(options.sttFallback),
       sttLifecycle: options.sttLifecycle ?? runtimePreset.sttLifecycle,
       ...options.semanticTurnDetector ? { semanticTurnDetector: options.semanticTurnDetector } : {},
+      ...options.fillerPhrases ? { fillerPhrases: options.fillerPhrases } : {},
+      ...options.fillerDelayMs !== undefined ? { fillerDelayMs: options.fillerDelayMs } : {},
       trace: options.trace,
       tts: options.tts,
       turnDetection

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/voice",
-	"version": "0.0.22-beta.552",
+	"version": "0.0.22-beta.553",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",