@livekit/agents 1.1.0 → 1.2.1

package/dist/voice/index.js

@@ -1,12 +1,29 @@
-import { Agent, StopResponse } from "./agent.js";
+import { Agent, AgentTask, StopResponse } from "./agent.js";
 import { AgentSession } from "./agent_session.js";
 export * from "./avatar/index.js";
+export * from "./background_audio.js";
+import {
+  RemoteSession,
+  SessionHost,
+  SessionTransport,
+  RoomSessionTransport
+} from "./remote_session.js";
 export * from "./events.js";
+import {} from "./io.js";
+export * from "./report.js";
+export * from "./room_io/index.js";
 import { RunContext } from "./run_context.js";
+import * as testing from "./testing/index.js";
 export {
   Agent,
   AgentSession,
+  AgentTask,
+  RemoteSession,
+  RoomSessionTransport,
   RunContext,
-  StopResponse
+  SessionHost,
+  SessionTransport,
+  StopResponse,
+  testing
 };
 //# sourceMappingURL=index.js.map

package/dist/voice/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/voice/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nexport { Agent, StopResponse, type AgentOptions, type ModelSettings } from './agent.js';\nexport { AgentSession, type AgentSessionOptions } from './agent_session.js';\n\nexport * from './avatar/index.js';\nexport * from './events.js';\nexport { RunContext } from './run_context.js';\n"],"mappings":"AAGA,SAAS,OAAO,oBAA2D;AAC3E,SAAS,oBAA8C;AAEvD,cAAc;AACd,cAAc;AACd,SAAS,kBAAkB;","names":[]}
+{"version":3,"sources":["../../src/voice/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nexport { Agent, AgentTask, StopResponse, type AgentOptions, type ModelSettings } from './agent.js';\nexport { AgentSession, type AgentSessionOptions, type VoiceOptions } from './agent_session.js';\nexport * from './avatar/index.js';\nexport * from './background_audio.js';\nexport {\n  type TextInputCallback,\n  type TextInputEvent,\n  RemoteSession,\n  type RemoteSessionCallbacks,\n  type RemoteSessionEventTypes,\n  SessionHost,\n  SessionTransport,\n  RoomSessionTransport,\n} from './remote_session.js';\nexport * from './events.js';\nexport { type TimedString } from './io.js';\nexport * from './report.js';\nexport * from './room_io/index.js';\nexport { RunContext } from './run_context.js';\nexport * as testing from './testing/index.js';\n"],"mappings":"AAGA,SAAS,OAAO,WAAW,oBAA2D;AACtF,SAAS,oBAAiE;AAC1E,cAAc;AACd,cAAc;AACd;AAAA,EAGE;AAAA,EAGA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,cAAc;AACd,eAAiC;AACjC,cAAc;AACd,cAAc;AACd,SAAS,kBAAkB;AAC3B,YAAY,aAAa;","names":[]}

package/dist/voice/interruption_detection.test.cjs

@@ -0,0 +1,114 @@
+"use strict";
+var import_vitest = require("vitest");
+var import_word = require("../tokenize/basic/word.cjs");
+(0, import_vitest.describe)("Interruption Detection - Word Counting", () => {
+  (0, import_vitest.describe)("Word Splitting Behavior", () => {
+    (0, import_vitest.it)("should count empty string as 0 words", () => {
+      const text = "";
+      const wordCount = (0, import_word.splitWords)(text, true).length;
+      (0, import_vitest.expect)(wordCount).toBe(0);
+    });
+    (0, import_vitest.it)("should count single word correctly", () => {
+      const text = "hello";
+      const wordCount = (0, import_word.splitWords)(text, true).length;
+      (0, import_vitest.expect)(wordCount).toBe(1);
+    });
+    (0, import_vitest.it)("should count two words correctly", () => {
+      const text = "hello world";
+      const wordCount = (0, import_word.splitWords)(text, true).length;
+      (0, import_vitest.expect)(wordCount).toBe(2);
+    });
+    (0, import_vitest.it)("should count multiple words correctly", () => {
+      const text = "hello this is a full sentence";
+      const wordCount = (0, import_word.splitWords)(text, true).length;
+      (0, import_vitest.expect)(wordCount).toBe(6);
+    });
+    (0, import_vitest.it)("should handle punctuation correctly", () => {
+      const text = "hello, world!";
+      const wordCount = (0, import_word.splitWords)(text, true).length;
+      (0, import_vitest.expect)(wordCount).toBe(2);
+    });
+    (0, import_vitest.it)("should handle multiple spaces between words", () => {
+      const text = "hello  world";
+      const wordCount = (0, import_word.splitWords)(text, true).length;
+      (0, import_vitest.expect)(wordCount).toBe(2);
+    });
+    (0, import_vitest.it)("should count whitespace-only string as 0 words", () => {
+      const text = "   ";
+      const wordCount = (0, import_word.splitWords)(text, true).length;
+      (0, import_vitest.expect)(wordCount).toBe(0);
+    });
+    (0, import_vitest.it)("should handle leading and trailing whitespace", () => {
+      const text = "  hello world  ";
+      const wordCount = (0, import_word.splitWords)(text, true).length;
+      (0, import_vitest.expect)(wordCount).toBe(2);
+    });
+  });
+  (0, import_vitest.describe)("Integration: Full Interruption Check Logic", () => {
+    (0, import_vitest.it)("should block interruption for empty transcript with threshold 2", () => {
+      const text = "";
+      const minInterruptionWords = 2;
+      const normalizedText = text ?? "";
+      const wordCount = (0, import_word.splitWords)(normalizedText, true).length;
+      const shouldBlock = wordCount < minInterruptionWords;
+      (0, import_vitest.expect)(normalizedText).toBe("");
+      (0, import_vitest.expect)(wordCount).toBe(0);
+      (0, import_vitest.expect)(shouldBlock).toBe(true);
+    });
+    (0, import_vitest.it)("should block interruption for undefined transcript with threshold 2", () => {
+      const text = void 0;
+      const minInterruptionWords = 2;
+      const normalizedText = text ?? "";
+      const wordCount = (0, import_word.splitWords)(normalizedText, true).length;
+      const shouldBlock = wordCount < minInterruptionWords;
+      (0, import_vitest.expect)(normalizedText).toBe("");
+      (0, import_vitest.expect)(wordCount).toBe(0);
+      (0, import_vitest.expect)(shouldBlock).toBe(true);
+    });
+    (0, import_vitest.it)("should block interruption for single word with threshold 2", () => {
+      const text = "hello";
+      const minInterruptionWords = 2;
+      const normalizedText = text ?? "";
+      const wordCount = (0, import_word.splitWords)(normalizedText, true).length;
+      const shouldBlock = wordCount < minInterruptionWords;
+      (0, import_vitest.expect)(normalizedText).toBe("hello");
+      (0, import_vitest.expect)(wordCount).toBe(1);
+      (0, import_vitest.expect)(shouldBlock).toBe(true);
+    });
+    (0, import_vitest.it)("should allow interruption when word count exactly meets threshold", () => {
+      const text = "hello world";
+      const minInterruptionWords = 2;
+      const normalizedText = text ?? "";
+      const wordCount = (0, import_word.splitWords)(normalizedText, true).length;
+      const shouldBlock = wordCount < minInterruptionWords;
+      (0, import_vitest.expect)(normalizedText).toBe("hello world");
+      (0, import_vitest.expect)(wordCount).toBe(2);
+      (0, import_vitest.expect)(shouldBlock).toBe(false);
+    });
+    (0, import_vitest.it)("should allow interruption when word count exceeds threshold", () => {
+      const text = "hello this is a full sentence";
+      const minInterruptionWords = 2;
+      const normalizedText = text ?? "";
+      const wordCount = (0, import_word.splitWords)(normalizedText, true).length;
+      const shouldBlock = wordCount < minInterruptionWords;
+      (0, import_vitest.expect)(normalizedText).toBe("hello this is a full sentence");
+      (0, import_vitest.expect)(wordCount).toBe(6);
+      (0, import_vitest.expect)(shouldBlock).toBe(false);
+    });
+    (0, import_vitest.it)("should apply consistent word counting logic in both methods", () => {
+      const transcripts = ["", "hello", "hello world", "this is a longer sentence"];
+      const threshold = 2;
+      transcripts.forEach((transcript) => {
+        const text1 = transcript;
+        const normalizedText1 = text1 ?? "";
+        const wordCount1 = (0, import_word.splitWords)(normalizedText1, true).length;
+        const shouldBlock1 = wordCount1 < threshold;
+        const wordCount2 = (0, import_word.splitWords)(transcript, true).length;
+        const shouldBlock2 = wordCount2 < threshold;
+        (0, import_vitest.expect)(wordCount1).toBe(wordCount2);
+        (0, import_vitest.expect)(shouldBlock1).toBe(shouldBlock2);
+      });
+    });
+  });
+});
+//# sourceMappingURL=interruption_detection.test.cjs.map

package/dist/voice/interruption_detection.test.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/voice/interruption_detection.test.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Unit tests for interruption detection logic in AgentActivity.\n *\n * Tests the refactored minInterruptionWords check which ensures:\n * - Consistent word count filtering across all speech scenarios\n * - Proper handling of empty strings, undefined, and short speech\n * - Interruptions allowed only when word count meets or exceeds minInterruptionWords threshold\n */\nimport { describe, expect, it } from 'vitest';\nimport { splitWords } from '../tokenize/basic/word.js';\n\ndescribe('Interruption Detection - Word Counting', () => {\n  describe('Word Splitting Behavior', () => {\n    it('should count empty string as 0 words', () => {\n      const text = '';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(0);\n    });\n\n    it('should count single word correctly', () => {\n      const text = 'hello';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(1);\n    });\n\n    it('should count two words correctly', () => {\n      const text = 'hello world';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(2);\n    });\n\n    it('should count multiple words correctly', () => {\n      const text = 'hello this is a full sentence';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(6);\n    });\n\n    it('should handle punctuation correctly', () => {\n      const text = 'hello, world!';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(2);\n    });\n\n    it('should handle multiple spaces between words', () => {\n      const text = 'hello  world';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(2);\n    });\n\n    it('should count whitespace-only string as 0 words', () => {\n      const text = '   ';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(0);\n    });\n\n    it('should handle leading and trailing whitespace', () => {\n      const text = '  hello world  ';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(2);\n    });\n  });\n\n  describe('Integration: Full Interruption Check Logic', () => {\n    it('should block interruption for empty transcript with threshold 2', () => {\n      const text = '';\n      const minInterruptionWords = 2;\n\n      const normalizedText = text ?? '';\n      const wordCount = splitWords(normalizedText, true).length;\n      const shouldBlock = wordCount < minInterruptionWords;\n\n      expect(normalizedText).toBe('');\n      expect(wordCount).toBe(0);\n      expect(shouldBlock).toBe(true);\n    });\n\n    it('should block interruption for undefined transcript with threshold 2', () => {\n      const text: string | undefined = undefined;\n      const minInterruptionWords = 2;\n\n      const normalizedText = text ?? '';\n      const wordCount = splitWords(normalizedText, true).length;\n      const shouldBlock = wordCount < minInterruptionWords;\n\n      expect(normalizedText).toBe('');\n      expect(wordCount).toBe(0);\n      expect(shouldBlock).toBe(true);\n    });\n\n    it('should block interruption for single word with threshold 2', () => {\n      const text = 'hello';\n      const minInterruptionWords = 2;\n\n      const normalizedText = text ?? '';\n      const wordCount = splitWords(normalizedText, true).length;\n      const shouldBlock = wordCount < minInterruptionWords;\n\n      expect(normalizedText).toBe('hello');\n      expect(wordCount).toBe(1);\n      expect(shouldBlock).toBe(true);\n    });\n\n    it('should allow interruption when word count exactly meets threshold', () => {\n      const text = 'hello world';\n      const minInterruptionWords = 2;\n\n      const normalizedText = text ?? '';\n      const wordCount = splitWords(normalizedText, true).length;\n      const shouldBlock = wordCount < minInterruptionWords;\n\n      expect(normalizedText).toBe('hello world');\n      expect(wordCount).toBe(2);\n      expect(shouldBlock).toBe(false);\n    });\n\n    it('should allow interruption when word count exceeds threshold', () => {\n      const text = 'hello this is a full sentence';\n      const minInterruptionWords = 2;\n\n      const normalizedText = text ?? '';\n      const wordCount = splitWords(normalizedText, true).length;\n      const shouldBlock = wordCount < minInterruptionWords;\n\n      expect(normalizedText).toBe('hello this is a full sentence');\n      expect(wordCount).toBe(6);\n      expect(shouldBlock).toBe(false);\n    });\n\n    it('should apply consistent word counting logic in both methods', () => {\n      const transcripts = ['', 'hello', 'hello world', 'this is a longer sentence'];\n      const threshold = 2;\n\n      transcripts.forEach((transcript) => {\n        const text1 = transcript;\n        const normalizedText1 = text1 ?? '';\n        const wordCount1 = splitWords(normalizedText1, true).length;\n        const shouldBlock1 = wordCount1 < threshold;\n\n        const wordCount2 = splitWords(transcript, true).length;\n        const shouldBlock2 = wordCount2 < threshold;\n\n        expect(wordCount1).toBe(wordCount2);\n        expect(shouldBlock1).toBe(shouldBlock2);\n      });\n    });\n  });\n});\n"],"mappings":"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","names":[]}

package/dist/voice/interruption_detection.test.js

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import { splitWords } from "../tokenize/basic/word.js";
+describe("Interruption Detection - Word Counting", () => {
+  describe("Word Splitting Behavior", () => {
+    it("should count empty string as 0 words", () => {
+      const text = "";
+      const wordCount = splitWords(text, true).length;
+      expect(wordCount).toBe(0);
+    });
+    it("should count single word correctly", () => {
+      const text = "hello";
+      const wordCount = splitWords(text, true).length;
+      expect(wordCount).toBe(1);
+    });
+    it("should count two words correctly", () => {
+      const text = "hello world";
+      const wordCount = splitWords(text, true).length;
+      expect(wordCount).toBe(2);
+    });
+    it("should count multiple words correctly", () => {
+      const text = "hello this is a full sentence";
+      const wordCount = splitWords(text, true).length;
+      expect(wordCount).toBe(6);
+    });
+    it("should handle punctuation correctly", () => {
+      const text = "hello, world!";
+      const wordCount = splitWords(text, true).length;
+      expect(wordCount).toBe(2);
+    });
+    it("should handle multiple spaces between words", () => {
+      const text = "hello  world";
+      const wordCount = splitWords(text, true).length;
+      expect(wordCount).toBe(2);
+    });
+    it("should count whitespace-only string as 0 words", () => {
+      const text = "   ";
+      const wordCount = splitWords(text, true).length;
+      expect(wordCount).toBe(0);
+    });
+    it("should handle leading and trailing whitespace", () => {
+      const text = "  hello world  ";
+      const wordCount = splitWords(text, true).length;
+      expect(wordCount).toBe(2);
+    });
+  });
+  describe("Integration: Full Interruption Check Logic", () => {
+    it("should block interruption for empty transcript with threshold 2", () => {
+      const text = "";
+      const minInterruptionWords = 2;
+      const normalizedText = text ?? "";
+      const wordCount = splitWords(normalizedText, true).length;
+      const shouldBlock = wordCount < minInterruptionWords;
+      expect(normalizedText).toBe("");
+      expect(wordCount).toBe(0);
+      expect(shouldBlock).toBe(true);
+    });
+    it("should block interruption for undefined transcript with threshold 2", () => {
+      const text = void 0;
+      const minInterruptionWords = 2;
+      const normalizedText = text ?? "";
+      const wordCount = splitWords(normalizedText, true).length;
+      const shouldBlock = wordCount < minInterruptionWords;
+      expect(normalizedText).toBe("");
+      expect(wordCount).toBe(0);
+      expect(shouldBlock).toBe(true);
+    });
+    it("should block interruption for single word with threshold 2", () => {
+      const text = "hello";
+      const minInterruptionWords = 2;
+      const normalizedText = text ?? "";
+      const wordCount = splitWords(normalizedText, true).length;
+      const shouldBlock = wordCount < minInterruptionWords;
+      expect(normalizedText).toBe("hello");
+      expect(wordCount).toBe(1);
+      expect(shouldBlock).toBe(true);
+    });
+    it("should allow interruption when word count exactly meets threshold", () => {
+      const text = "hello world";
+      const minInterruptionWords = 2;
+      const normalizedText = text ?? "";
+      const wordCount = splitWords(normalizedText, true).length;
+      const shouldBlock = wordCount < minInterruptionWords;
+      expect(normalizedText).toBe("hello world");
+      expect(wordCount).toBe(2);
+      expect(shouldBlock).toBe(false);
+    });
+    it("should allow interruption when word count exceeds threshold", () => {
+      const text = "hello this is a full sentence";
+      const minInterruptionWords = 2;
+      const normalizedText = text ?? "";
+      const wordCount = splitWords(normalizedText, true).length;
+      const shouldBlock = wordCount < minInterruptionWords;
+      expect(normalizedText).toBe("hello this is a full sentence");
+      expect(wordCount).toBe(6);
+      expect(shouldBlock).toBe(false);
+    });
+    it("should apply consistent word counting logic in both methods", () => {
+      const transcripts = ["", "hello", "hello world", "this is a longer sentence"];
+      const threshold = 2;
+      transcripts.forEach((transcript) => {
+        const text1 = transcript;
+        const normalizedText1 = text1 ?? "";
+        const wordCount1 = splitWords(normalizedText1, true).length;
+        const shouldBlock1 = wordCount1 < threshold;
+        const wordCount2 = splitWords(transcript, true).length;
+        const shouldBlock2 = wordCount2 < threshold;
+        expect(wordCount1).toBe(wordCount2);
+        expect(shouldBlock1).toBe(shouldBlock2);
+      });
+    });
+  });
+});
+//# sourceMappingURL=interruption_detection.test.js.map

package/dist/voice/interruption_detection.test.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/voice/interruption_detection.test.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Unit tests for interruption detection logic in AgentActivity.\n *\n * Tests the refactored minInterruptionWords check which ensures:\n * - Consistent word count filtering across all speech scenarios\n * - Proper handling of empty strings, undefined, and short speech\n * - Interruptions allowed only when word count meets or exceeds minInterruptionWords threshold\n */\nimport { describe, expect, it } from 'vitest';\nimport { splitWords } from '../tokenize/basic/word.js';\n\ndescribe('Interruption Detection - Word Counting', () => {\n  describe('Word Splitting Behavior', () => {\n    it('should count empty string as 0 words', () => {\n      const text = '';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(0);\n    });\n\n    it('should count single word correctly', () => {\n      const text = 'hello';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(1);\n    });\n\n    it('should count two words correctly', () => {\n      const text = 'hello world';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(2);\n    });\n\n    it('should count multiple words correctly', () => {\n      const text = 'hello this is a full sentence';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(6);\n    });\n\n    it('should handle punctuation correctly', () => {\n      const text = 'hello, world!';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(2);\n    });\n\n    it('should handle multiple spaces between words', () => {\n      const text = 'hello  world';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(2);\n    });\n\n    it('should count whitespace-only string as 0 words', () => {\n      const text = '   ';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(0);\n    });\n\n    it('should handle leading and trailing whitespace', () => {\n      const text = '  hello world  ';\n      const wordCount = splitWords(text, true).length;\n      expect(wordCount).toBe(2);\n    });\n  });\n\n  describe('Integration: Full Interruption Check Logic', () => {\n    it('should block interruption for empty transcript with threshold 2', () => {\n      const text = '';\n      const minInterruptionWords = 2;\n\n      const normalizedText = text ?? '';\n      const wordCount = splitWords(normalizedText, true).length;\n      const shouldBlock = wordCount < minInterruptionWords;\n\n      expect(normalizedText).toBe('');\n      expect(wordCount).toBe(0);\n      expect(shouldBlock).toBe(true);\n    });\n\n    it('should block interruption for undefined transcript with threshold 2', () => {\n      const text: string | undefined = undefined;\n      const minInterruptionWords = 2;\n\n      const normalizedText = text ?? '';\n      const wordCount = splitWords(normalizedText, true).length;\n      const shouldBlock = wordCount < minInterruptionWords;\n\n      expect(normalizedText).toBe('');\n      expect(wordCount).toBe(0);\n      expect(shouldBlock).toBe(true);\n    });\n\n    it('should block interruption for single word with threshold 2', () => {\n      const text = 'hello';\n      const minInterruptionWords = 2;\n\n      const normalizedText = text ?? '';\n      const wordCount = splitWords(normalizedText, true).length;\n      const shouldBlock = wordCount < minInterruptionWords;\n\n      expect(normalizedText).toBe('hello');\n      expect(wordCount).toBe(1);\n      expect(shouldBlock).toBe(true);\n    });\n\n    it('should allow interruption when word count exactly meets threshold', () => {\n      const text = 'hello world';\n      const minInterruptionWords = 2;\n\n      const normalizedText = text ?? '';\n      const wordCount = splitWords(normalizedText, true).length;\n      const shouldBlock = wordCount < minInterruptionWords;\n\n      expect(normalizedText).toBe('hello world');\n      expect(wordCount).toBe(2);\n      expect(shouldBlock).toBe(false);\n    });\n\n    it('should allow interruption when word count exceeds threshold', () => {\n      const text = 'hello this is a full sentence';\n      const minInterruptionWords = 2;\n\n      const normalizedText = text ?? '';\n      const wordCount = splitWords(normalizedText, true).length;\n      const shouldBlock = wordCount < minInterruptionWords;\n\n      expect(normalizedText).toBe('hello this is a full sentence');\n      expect(wordCount).toBe(6);\n      expect(shouldBlock).toBe(false);\n    });\n\n    it('should apply consistent word counting logic in both methods', () => {\n      const transcripts = ['', 'hello', 'hello world', 'this is a longer sentence'];\n      const threshold = 2;\n\n      transcripts.forEach((transcript) => {\n        const text1 = transcript;\n        const normalizedText1 = text1 ?? '';\n        const wordCount1 = splitWords(normalizedText1, true).length;\n        const shouldBlock1 = wordCount1 < threshold;\n\n        const wordCount2 = splitWords(transcript, true).length;\n        const shouldBlock2 = wordCount2 < threshold;\n\n        expect(wordCount1).toBe(wordCount2);\n        expect(shouldBlock1).toBe(shouldBlock2);\n      });\n    });\n  });\n});\n"],"mappings":"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","names":[]}

package/dist/voice/io.cjs

@@ -22,17 +22,37 @@ __export(io_exports, {
   AgentOutput: () => AgentOutput,
   AudioInput: () => AudioInput,
   AudioOutput: () => AudioOutput,
-  TextOutput: () => TextOutput
+  TIMED_STRING_SYMBOL: () => TIMED_STRING_SYMBOL,
+  TextOutput: () => TextOutput,
+  createTimedString: () => createTimedString,
+  isTimedString: () => isTimedString
 });
 module.exports = __toCommonJS(io_exports);
 var import_node_events = require("node:events");
 var import_log = require("../log.cjs");
-var import_deferred_stream = require("../stream/deferred_stream.cjs");
+var import_multi_input_stream = require("../stream/multi_input_stream.cjs");
 var import_utils = require("../utils.cjs");
+const TIMED_STRING_SYMBOL = Symbol.for("lk.TimedString");
+function createTimedString(opts) {
+  return {
+    [TIMED_STRING_SYMBOL]: true,
+    text: opts.text,
+    startTime: opts.startTime,
+    endTime: opts.endTime,
+    confidence: opts.confidence,
+    startTimeOffset: opts.startTimeOffset
+  };
+}
+function isTimedString(value) {
+  return typeof value === "object" && value !== null && TIMED_STRING_SYMBOL in value && value[TIMED_STRING_SYMBOL] === true;
+}
 class AudioInput {
-  deferredStream = new import_deferred_stream.DeferredReadableStream();
+  multiStream = new import_multi_input_stream.MultiInputStream();
   get stream() {
-    return this.deferredStream.stream;
+    return this.multiStream.stream;
+  }
+  async close() {
+    await this.multiStream.close();
   }
   onAttached() {
   }
@@ -40,17 +60,23 @@ class AudioInput {
   }
 }
 class AudioOutput extends import_node_events.EventEmitter {
-  constructor(sampleRate, nextInChain) {
+  constructor(sampleRate, nextInChain, capabilities = { pause: false }) {
     super();
     this.sampleRate = sampleRate;
     this.nextInChain = nextInChain;
+    this.capabilities = capabilities;
     if (this.nextInChain) {
+      this.nextInChain.on(
+        AudioOutput.EVENT_PLAYBACK_STARTED,
+        (ev) => this.onPlaybackStarted(ev.createdAt)
+      );
       this.nextInChain.on(
         AudioOutput.EVENT_PLAYBACK_FINISHED,
         (ev) => this.onPlaybackFinished(ev)
       );
     }
   }
+  static EVENT_PLAYBACK_STARTED = "playbackStarted";
   static EVENT_PLAYBACK_FINISHED = "playbackFinished";
   playbackFinishedFuture = new import_utils.Future();
   _capturing = false;
@@ -61,6 +87,14 @@ class AudioOutput extends import_node_events.EventEmitter {
     interrupted: false
   };
   logger = (0, import_log.log)();
+  capabilities;
+  /**
+   * Whether this output and all outputs in the chain support pause/resume.
+   */
+  get canPause() {
+    var _a;
+    return this.capabilities.pause && (((_a = this.nextInChain) == null ? void 0 : _a.canPause) ?? true);
+  }
   /**
    * Capture an audio frame for playback, frames can be pushed faster than real-time
    */
@@ -83,6 +117,13 @@ class AudioOutput extends import_node_events.EventEmitter {
     }
     return this.lastPlaybackEvent;
   }
+  /**
+   * Called when playback actually starts (first frame is sent to output).
+   * Developers building audio sinks should call this when the first frame is captured.
+   */
+  onPlaybackStarted(createdAt) {
+    this.emit(AudioOutput.EVENT_PLAYBACK_STARTED, { createdAt });
+  }
   /**
    * Developers building audio sinks must call this method when a playback/segment is finished.
    * Segments are segmented by calls to flush() or clearBuffer()
@@ -110,6 +151,22 @@ class AudioOutput extends import_node_events.EventEmitter {
       this.nextInChain.onDetached();
     }
   }
+  /**
+   * Pause the audio playback
+   */
+  pause() {
+    if (this.nextInChain) {
+      this.nextInChain.pause();
+    }
+  }
+  /**
+   * Resume the audio playback
+   */
+  resume() {
+    if (this.nextInChain) {
+      this.nextInChain.resume();
+    }
+  }
 }
 class TextOutput {
   constructor(nextInChain) {
@@ -240,6 +297,9 @@ class AgentOutput {
   AgentOutput,
   AudioInput,
   AudioOutput,
-  TextOutput
+  TIMED_STRING_SYMBOL,
+  TextOutput,
+  createTimedString,
+  isTimedString
 });
 //# sourceMappingURL=io.cjs.map

package/dist/voice/io.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/voice/io.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type { AudioFrame } from '@livekit/rtc-node';\nimport { EventEmitter } from 'node:events';\nimport type { ReadableStream } from 'node:stream/web';\nimport type { ChatContext } from '../llm/chat_context.js';\nimport type { ChatChunk } from '../llm/llm.js';\nimport type { ToolContext } from '../llm/tool_context.js';\nimport { log } from '../log.js';\nimport { DeferredReadableStream } from '../stream/deferred_stream.js';\nimport type { SpeechEvent } from '../stt/stt.js';\nimport { Future } from '../utils.js';\nimport type { ModelSettings } from './agent.js';\n\nexport type STTNode = (\n  audio: ReadableStream<AudioFrame>,\n  modelSettings: ModelSettings,\n) => Promise<ReadableStream<SpeechEvent | string> | null>;\n\nexport type LLMNode = (\n  chatCtx: ChatContext,\n  toolCtx: ToolContext,\n  modelSettings: ModelSettings,\n) => Promise<ReadableStream<ChatChunk | string> | null>;\n\nexport type TTSNode = (\n  text: ReadableStream<string>,\n  modelSettings: ModelSettings,\n) => Promise<ReadableStream<AudioFrame> | null>;\nexport abstract class AudioInput {\n  protected deferredStream: DeferredReadableStream<AudioFrame> =\n    new DeferredReadableStream<AudioFrame>();\n\n  get stream(): ReadableStream<AudioFrame> {\n    return this.deferredStream.stream;\n  }\n\n  onAttached(): void {}\n\n  onDetached(): void {}\n}\n\nexport abstract class AudioOutput extends EventEmitter {\n  static readonly EVENT_PLAYBACK_FINISHED = 'playbackFinished';\n\n  private playbackFinishedFuture: Future<void> = new Future();\n  private _capturing: boolean = false;\n  private playbackFinishedCount: number = 0;\n  private playbackSegmentsCount: number = 0;\n  private lastPlaybackEvent: PlaybackFinishedEvent = {\n    playbackPosition: 0,\n    interrupted: false,\n  };\n  protected logger = log();\n\n  constructor(\n    public sampleRate?: number,\n    protected readonly nextInChain?: AudioOutput,\n  ) {\n    super();\n    if (this.nextInChain) {\n      this.nextInChain.on(AudioOutput.EVENT_PLAYBACK_FINISHED, (ev: PlaybackFinishedEvent) =>\n        this.onPlaybackFinished(ev),\n      );\n    }\n  }\n\n  /**\n   * Capture an audio frame for playback, frames can be pushed faster than real-time\n   */\n  async captureFrame(_frame: AudioFrame): Promise<void> {\n    if (!this._capturing) {\n      this._capturing = true;\n      this.playbackSegmentsCount++;\n    }\n  }\n\n  /**\n   * Wait for the past audio segments to finish playing out.\n   *\n   * @returns The event that was emitted when the audio finished playing out (only the last segment information)\n   */\n  async waitForPlayout(): Promise<PlaybackFinishedEvent> {\n    const target = this.playbackSegmentsCount;\n\n    while (this.playbackFinishedCount < target) {\n      await this.playbackFinishedFuture.await;\n      this.playbackFinishedFuture = new Future();\n    }\n\n    return this.lastPlaybackEvent;\n  }\n\n  /**\n   * Developers building audio sinks must call this method when a playback/segment is finished.\n   * Segments are segmented by calls to flush() or clearBuffer()\n   */\n  onPlaybackFinished(options: PlaybackFinishedEvent) {\n    if (this.playbackFinishedCount >= this.playbackSegmentsCount) {\n      this.logger.warn('playback_finished called more times than playback segments were captured');\n      return;\n    }\n\n    this.lastPlaybackEvent = options;\n    this.playbackFinishedCount++;\n    this.playbackFinishedFuture.resolve();\n    this.emit(AudioOutput.EVENT_PLAYBACK_FINISHED, options);\n  }\n\n  flush(): void {\n    this._capturing = false;\n  }\n\n  /**\n   * Clear the buffer, stopping playback immediately\n   */\n  abstract clearBuffer(): void;\n\n  onAttached(): void {\n    if (this.nextInChain) {\n      this.nextInChain.onAttached();\n    }\n  }\n\n  onDetached(): void {\n    if (this.nextInChain) {\n      this.nextInChain.onDetached();\n    }\n  }\n}\n\nexport interface PlaybackFinishedEvent {\n  // How much of the audio was played back\n  playbackPosition: number;\n  // Interrupted is True if playback was interrupted (clearBuffer() was called)\n  interrupted: boolean;\n  // Transcript synced with playback; may be partial if the audio was interrupted\n  // When null, the transcript is not synchronized with the playback\n  synchronizedTranscript?: string;\n}\n\nexport abstract class TextOutput {\n  constructor(protected readonly nextInChain?: TextOutput) {}\n\n  /**\n   * Capture a text segment (Used by the output of LLM nodes)\n   */\n  abstract captureText(text: string): Promise<void>;\n\n  /**\n   * Mark the current text segment as complete (e.g LLM generation is complete)\n   */\n  abstract flush(): void;\n\n  onAttached(): void {\n    if (this.nextInChain) {\n      this.nextInChain.onAttached();\n    }\n  }\n\n  onDetached(): void {\n    if (this.nextInChain) {\n      this.nextInChain.onDetached();\n    }\n  }\n}\n\nexport class AgentInput {\n  private _audioStream: AudioInput | null = null;\n  // enabled by default\n  private _audioEnabled: boolean = true;\n\n  constructor(private readonly audioChanged: () => void) {}\n\n  setAudioEnabled(enable: boolean): void {\n    if (enable === this._audioEnabled) {\n      return;\n    }\n\n    this._audioEnabled = enable;\n\n    if (!this._audioStream) {\n      return;\n    }\n\n    if (enable) {\n      this._audioStream.onAttached();\n    } else {\n      this._audioStream.onDetached();\n    }\n  }\n\n  get audioEnabled(): boolean {\n    return this._audioEnabled;\n  }\n\n  get audio(): AudioInput | null {\n    return this._audioStream;\n  }\n\n  set audio(stream: AudioInput | null) {\n    this._audioStream = stream;\n    this.audioChanged();\n  }\n}\n\nexport class AgentOutput {\n  private _audioSink: AudioOutput | null = null;\n  private _transcriptionSink: TextOutput | null = null;\n  private _audioEnabled: boolean = true;\n  private _transcriptionEnabled: boolean = true;\n\n  constructor(\n    private readonly audioChanged: () => void,\n    private readonly transcriptionChanged: () => void,\n  ) {}\n\n  setAudioEnabled(enabled: boolean): void {\n    if (enabled === this._audioEnabled) {\n      return;\n    }\n\n    this._audioEnabled = enabled;\n\n    if (!this._audioSink) {\n      return;\n    }\n\n    if (enabled) {\n      this._audioSink.onAttached();\n    } else {\n      this._audioSink.onDetached();\n    }\n  }\n\n  setTranscriptionEnabled(enabled: boolean): void {\n    if (enabled === this._transcriptionEnabled) {\n      return;\n    }\n\n    this._transcriptionEnabled = enabled;\n\n    if (!this._transcriptionSink) {\n      return;\n    }\n\n    if (enabled) {\n      this._transcriptionSink.onAttached();\n    } else {\n      this._transcriptionSink.onDetached();\n    }\n  }\n\n  get audioEnabled(): boolean {\n    return this._audioEnabled;\n  }\n\n  get transcriptionEnabled(): boolean {\n    return this._transcriptionEnabled;\n  }\n\n  get audio(): AudioOutput | null {\n    return this._audioSink;\n  }\n\n  set audio(sink: AudioOutput | null) {\n    if (sink === this._audioSink) {\n      return;\n    }\n\n    if (this._audioSink) {\n      this._audioSink.onDetached();\n    }\n\n    this._audioSink = sink;\n    this.audioChanged();\n\n    if (this._audioSink) {\n      this._audioSink.onAttached();\n    }\n  }\n\n  get transcription(): TextOutput | null {\n    return this._transcriptionSink;\n  }\n\n  set transcription(sink: TextOutput | null) {\n    if (sink === this._transcriptionSink) {\n      return;\n    }\n\n    if (this._transcriptionSink) {\n      this._transcriptionSink.onDetached();\n    }\n\n    this._transcriptionSink = sink;\n    this.transcriptionChanged();\n\n    if (this._transcriptionSink) {\n      this._transcriptionSink.onAttached();\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAIA,yBAA6B;AAK7B,iBAAoB;AACpB,6BAAuC;AAEvC,mBAAuB;AAkBhB,MAAe,WAAW;AAAA,EACrB,iBACR,IAAI,8CAAmC;AAAA,EAEzC,IAAI,SAAqC;AACvC,WAAO,KAAK,eAAe;AAAA,EAC7B;AAAA,EAEA,aAAmB;AAAA,EAAC;AAAA,EAEpB,aAAmB;AAAA,EAAC;AACtB;AAEO,MAAe,oBAAoB,gCAAa;AAAA,EAarD,YACS,YACY,aACnB;AACA,UAAM;AAHC;AACY;AAGnB,QAAI,KAAK,aAAa;AACpB,WAAK,YAAY;AAAA,QAAG,YAAY;AAAA,QAAyB,CAAC,OACxD,KAAK,mBAAmB,EAAE;AAAA,MAC5B;AAAA,IACF;AAAA,EACF;AAAA,EAtBA,OAAgB,0BAA0B;AAAA,EAElC,yBAAuC,IAAI,oBAAO;AAAA,EAClD,aAAsB;AAAA,EACtB,wBAAgC;AAAA,EAChC,wBAAgC;AAAA,EAChC,oBAA2C;AAAA,IACjD,kBAAkB;AAAA,IAClB,aAAa;AAAA,EACf;AAAA,EACU,aAAS,gBAAI;AAAA;AAAA;AAAA;AAAA,EAiBvB,MAAM,aAAa,QAAmC;AACpD,QAAI,CAAC,KAAK,YAAY;AACpB,WAAK,aAAa;AAClB,WAAK;AAAA,IACP;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,iBAAiD;AACrD,UAAM,SAAS,KAAK;AAEpB,WAAO,KAAK,wBAAwB,QAAQ;AAC1C,YAAM,KAAK,uBAAuB;AAClC,WAAK,yBAAyB,IAAI,oBAAO;AAAA,IAC3C;AAEA,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,mBAAmB,SAAgC;AACjD,QAAI,KAAK,yBAAyB,KAAK,uBAAuB;AAC5D,WAAK,OAAO,KAAK,0EAA0E;AAC3F;AAAA,IACF;AAEA,SAAK,oBAAoB;AACzB,SAAK;AACL,SAAK,uBAAuB,QAAQ;AACpC,SAAK,KAAK,YAAY,yBAAyB,OAAO;AAAA,EACxD;AAAA,EAEA,QAAc;AACZ,SAAK,aAAa;AAAA,EACpB;AAAA,EAOA,aAAmB;AACjB,QAAI,KAAK,aAAa;AACpB,WAAK,YAAY,WAAW;AAAA,IAC9B;AAAA,EACF;AAAA,EAEA,aAAmB;AACjB,QAAI,KAAK,aAAa;AACpB,WAAK,YAAY,WAAW;AAAA,IAC9B;AAAA,EACF;AACF;AAYO,MAAe,WAAW;AAAA,EAC/B,YAA+B,aAA0B;AAA1B;AAAA,EAA2B;AAAA,EAY1D,aAAmB;AACjB,QAAI,KAAK,aAAa;AACpB,WAAK,YAAY,WAAW;AAAA,IAC9B;AAAA,EACF;AAAA,EAEA,aAAmB;AACjB,QAAI,KAAK,aAAa;AACpB,WAAK,YAAY,WAAW;AAAA,IAC9B;AAAA,EACF;AACF;AAEO,MAAM,WAAW;AAAA,EAKtB,YAA6B,cAA0B;AAA1B;AAAA,EAA2B;AAAA,EAJhD,eAAkC;AAAA;AAAA,EAElC,gBAAyB;AAAA,EAIjC,gBAAgB,QAAuB;AACrC,QAAI,WAAW,KAAK,eAAe;AACjC;AAAA,IACF;AAEA,SAAK,gBAAgB;AAErB,QAAI,CAAC,KAAK,cAAc;AACtB;AAAA,IACF;AAEA,QAAI,QAAQ;AACV,WAAK,aAAa,WAAW;AAAA,IAC/B,OAAO;AACL,WAAK,aAAa,WAAW;AAAA,IAC/B;AAAA,EACF;AAAA,EAEA,IAAI,eAAwB;AAC1B,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,IAAI,QAA2B;AAC7B,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,IAAI,MAAM,QAA2B;AACnC,SAAK,eAAe;AACpB,SAAK,aAAa;AAAA,EACpB;AACF;AAEO,MAAM,YAAY;AAAA,EAMvB,YACmB,cACA,sBACjB;AAFiB;AACA;AAAA,EAChB;AAAA,EARK,aAAiC;AAAA,EACjC,qBAAwC;AAAA,EACxC,gBAAyB;AAAA,EACzB,wBAAiC;AAAA,EAOzC,gBAAgB,SAAwB;AACtC,QAAI,YAAY,KAAK,eAAe;AAClC;AAAA,IACF;AAEA,SAAK,gBAAgB;AAErB,QAAI,CAAC,KAAK,YAAY;AACpB;AAAA,IACF;AAEA,QAAI,SAAS;AACX,WAAK,WAAW,WAAW;AAAA,IAC7B,OAAO;AACL,WAAK,WAAW,WAAW;AAAA,IAC7B;AAAA,EACF;AAAA,EAEA,wBAAwB,SAAwB;AAC9C,QAAI,YAAY,KAAK,uBAAuB;AAC1C;AAAA,IACF;AAEA,SAAK,wBAAwB;AAE7B,QAAI,CAAC,KAAK,oBAAoB;AAC5B;AAAA,IACF;AAEA,QAAI,SAAS;AACX,WAAK,mBAAmB,WAAW;AAAA,IACrC,OAAO;AACL,WAAK,mBAAmB,WAAW;AAAA,IACrC;AAAA,EACF;AAAA,EAEA,IAAI,eAAwB;AAC1B,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,IAAI,uBAAgC;AAClC,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,IAAI,QAA4B;AAC9B,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,IAAI,MAAM,MAA0B;AAClC,QAAI,SAAS,KAAK,YAAY;AAC5B;AAAA,IACF;AAEA,QAAI,KAAK,YAAY;AACnB,WAAK,WAAW,WAAW;AAAA,IAC7B;AAEA,SAAK,aAAa;AAClB,SAAK,aAAa;AAElB,QAAI,KAAK,YAAY;AACnB,WAAK,WAAW,WAAW;AAAA,IAC7B;AAAA,EACF;AAAA,EAEA,IAAI,gBAAmC;AACrC,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,IAAI,cAAc,MAAyB;AACzC,QAAI,SAAS,KAAK,oBAAoB;AACpC;AAAA,IACF;AAEA,QAAI,KAAK,oBAAoB;AAC3B,WAAK,mBAAmB,WAAW;AAAA,IACrC;AAEA,SAAK,qBAAqB;AAC1B,SAAK,qBAAqB;AAE1B,QAAI,KAAK,oBAAoB;AAC3B,WAAK,mBAAmB,WAAW;AAAA,IACrC;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../src/voice/io.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type { AudioFrame } from '@livekit/rtc-node';\nimport { EventEmitter } from 'node:events';\nimport type { ReadableStream } from 'node:stream/web';\nimport type { ChatContext } from '../llm/chat_context.js';\nimport type { ChatChunk } from '../llm/llm.js';\nimport type { ToolContext } from '../llm/tool_context.js';\nimport { log } from '../log.js';\nimport { MultiInputStream } from '../stream/multi_input_stream.js';\nimport type { SpeechEvent } from '../stt/stt.js';\nimport { Future } from '../utils.js';\nimport type { ModelSettings } from './agent.js';\n\nexport type STTNode = (\n  audio: ReadableStream<AudioFrame>,\n  modelSettings: ModelSettings,\n) => Promise<ReadableStream<SpeechEvent | string> | null>;\n\nexport type LLMNode = (\n  chatCtx: ChatContext,\n  toolCtx: ToolContext,\n  modelSettings: ModelSettings,\n) => Promise<ReadableStream<ChatChunk | string> | null>;\n\nexport type TTSNode = (\n  text: ReadableStream<string>,\n  modelSettings: ModelSettings,\n) => Promise<ReadableStream<AudioFrame> | null>;\n\n/**\n * Symbol used to identify TimedString objects.\n */\nexport const TIMED_STRING_SYMBOL = Symbol.for('lk.TimedString');\n\n/**\n * A string with optional start and end timestamps for word-level alignment.\n */\nexport interface TimedString {\n  readonly [TIMED_STRING_SYMBOL]: true;\n  text: string;\n  startTime?: number; // seconds\n  endTime?: number; // seconds\n  confidence?: number;\n  startTimeOffset?: number;\n}\n\n/**\n * Factory function to create a TimedString object.\n */\nexport function createTimedString(opts: {\n  text: string;\n  startTime?: number;\n  endTime?: number;\n  confidence?: number;\n  startTimeOffset?: number;\n}): TimedString {\n  return {\n    [TIMED_STRING_SYMBOL]: true,\n    text: opts.text,\n    startTime: opts.startTime,\n    endTime: opts.endTime,\n    confidence: opts.confidence,\n    startTimeOffset: opts.startTimeOffset,\n  };\n}\n\n/**\n * Type guard to check if a value is a TimedString.\n */\nexport function isTimedString(value: unknown): value is TimedString {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    TIMED_STRING_SYMBOL in value &&\n    (value as TimedString)[TIMED_STRING_SYMBOL] === true\n  );\n}\n\nexport interface AudioOutputCapabilities {\n  /** Whether this output supports pause/resume functionality */\n  pause: boolean;\n}\n\nexport abstract class AudioInput {\n  protected multiStream: MultiInputStream<AudioFrame> = new MultiInputStream<AudioFrame>();\n\n  get stream(): ReadableStream<AudioFrame> {\n    return this.multiStream.stream;\n  }\n\n  async close(): Promise<void> {\n    await this.multiStream.close();\n  }\n\n  onAttached(): void {}\n\n  onDetached(): void {}\n}\n\nexport abstract class AudioOutput extends EventEmitter {\n  static readonly EVENT_PLAYBACK_STARTED = 'playbackStarted';\n  static readonly EVENT_PLAYBACK_FINISHED = 'playbackFinished';\n\n  private playbackFinishedFuture: Future<void> = new Future();\n  private _capturing: boolean = false;\n  private playbackFinishedCount: number = 0;\n  private playbackSegmentsCount: number = 0;\n  private lastPlaybackEvent: PlaybackFinishedEvent = {\n    playbackPosition: 0,\n    interrupted: false,\n  };\n  protected logger = log();\n  protected readonly capabilities: AudioOutputCapabilities;\n\n  constructor(\n    public sampleRate?: number,\n    protected readonly nextInChain?: AudioOutput,\n    capabilities: AudioOutputCapabilities = { pause: false },\n  ) {\n    super();\n    this.capabilities = capabilities;\n\n    if (this.nextInChain) {\n      this.nextInChain.on(AudioOutput.EVENT_PLAYBACK_STARTED, (ev: PlaybackStartedEvent) =>\n        this.onPlaybackStarted(ev.createdAt),\n      );\n      this.nextInChain.on(AudioOutput.EVENT_PLAYBACK_FINISHED, (ev: PlaybackFinishedEvent) =>\n        this.onPlaybackFinished(ev),\n      );\n    }\n  }\n\n  /**\n   * Whether this output and all outputs in the chain support pause/resume.\n   */\n  get canPause(): boolean {\n    return this.capabilities.pause && (this.nextInChain?.canPause ?? true);\n  }\n\n  /**\n   * Capture an audio frame for playback, frames can be pushed faster than real-time\n   */\n  async captureFrame(_frame: AudioFrame): Promise<void> {\n    if (!this._capturing) {\n      this._capturing = true;\n      this.playbackSegmentsCount++;\n    }\n  }\n\n  /**\n   * Wait for the past audio segments to finish playing out.\n   *\n   * @returns The event that was emitted when the audio finished playing out (only the last segment information)\n   */\n  async waitForPlayout(): Promise<PlaybackFinishedEvent> {\n    const target = this.playbackSegmentsCount;\n\n    while (this.playbackFinishedCount < target) {\n      await this.playbackFinishedFuture.await;\n      this.playbackFinishedFuture = new Future();\n    }\n\n    return this.lastPlaybackEvent;\n  }\n\n  /**\n   * Called when playback actually starts (first frame is sent to output).\n   * Developers building audio sinks should call this when the first frame is captured.\n   */\n  onPlaybackStarted(createdAt: number): void {\n    this.emit(AudioOutput.EVENT_PLAYBACK_STARTED, { createdAt } as PlaybackStartedEvent);\n  }\n\n  /**\n   * Developers building audio sinks must call this method when a playback/segment is finished.\n   * Segments are segmented by calls to flush() or clearBuffer()\n   */\n  onPlaybackFinished(options: PlaybackFinishedEvent) {\n    if (this.playbackFinishedCount >= this.playbackSegmentsCount) {\n      this.logger.warn('playback_finished called more times than playback segments were captured');\n      return;\n    }\n\n    this.lastPlaybackEvent = options;\n    this.playbackFinishedCount++;\n    this.playbackFinishedFuture.resolve();\n    this.emit(AudioOutput.EVENT_PLAYBACK_FINISHED, options);\n  }\n\n  flush(): void {\n    this._capturing = false;\n  }\n\n  /**\n   * Clear the buffer, stopping playback immediately\n   */\n  abstract clearBuffer(): void;\n\n  onAttached(): void {\n    if (this.nextInChain) {\n      this.nextInChain.onAttached();\n    }\n  }\n\n  onDetached(): void {\n    if (this.nextInChain) {\n      this.nextInChain.onDetached();\n    }\n  }\n\n  /**\n   * Pause the audio playback\n   */\n  pause(): void {\n    if (this.nextInChain) {\n      this.nextInChain.pause();\n    }\n  }\n\n  /**\n   * Resume the audio playback\n   */\n  resume(): void {\n    if (this.nextInChain) {\n      this.nextInChain.resume();\n    }\n  }\n}\n\nexport interface PlaybackFinishedEvent {\n  /** How much of the audio was played back, in seconds */\n  playbackPosition: number;\n  /** True if playback was interrupted (clearBuffer() was called) */\n  interrupted: boolean;\n  /**\n   * Transcript synced with playback; may be partial if the audio was interrupted.\n   * When undefined, the transcript is not synchronized with the playback.\n   */\n  synchronizedTranscript?: string;\n}\n\nexport interface PlaybackStartedEvent {\n  /** The timestamp (Date.now()) when the playback started */\n  createdAt: number;\n}\n\nexport abstract class TextOutput {\n  constructor(protected readonly nextInChain?: TextOutput) {}\n\n  abstract captureText(text: string | TimedString): Promise<void>;\n\n  /**\n   * Mark the current text segment as complete (e.g LLM generation is complete)\n   */\n  abstract flush(): void;\n\n  onAttached(): void {\n    if (this.nextInChain) {\n      this.nextInChain.onAttached();\n    }\n  }\n\n  onDetached(): void {\n    if (this.nextInChain) {\n      this.nextInChain.onDetached();\n    }\n  }\n}\n\nexport class AgentInput {\n  private _audioStream: AudioInput | null = null;\n  // enabled by default\n  private _audioEnabled: boolean = true;\n\n  constructor(private readonly audioChanged: () => void) {}\n\n  setAudioEnabled(enable: boolean): void {\n    if (enable === this._audioEnabled) {\n      return;\n    }\n\n    this._audioEnabled = enable;\n\n    if (!this._audioStream) {\n      return;\n    }\n\n    if (enable) {\n      this._audioStream.onAttached();\n    } else {\n      this._audioStream.onDetached();\n    }\n  }\n\n  get audioEnabled(): boolean {\n    return this._audioEnabled;\n  }\n\n  get audio(): AudioInput | null {\n    return this._audioStream;\n  }\n\n  set audio(stream: AudioInput | null) {\n    this._audioStream = stream;\n    this.audioChanged();\n  }\n}\n\nexport class AgentOutput {\n  private _audioSink: AudioOutput | null = null;\n  private _transcriptionSink: TextOutput | null = null;\n  private _audioEnabled: boolean = true;\n  private _transcriptionEnabled: boolean = true;\n\n  constructor(\n    private readonly audioChanged: () => void,\n    private readonly transcriptionChanged: () => void,\n  ) {}\n\n  setAudioEnabled(enabled: boolean): void {\n    if (enabled === this._audioEnabled) {\n      return;\n    }\n\n    this._audioEnabled = enabled;\n\n    if (!this._audioSink) {\n      return;\n    }\n\n    if (enabled) {\n      this._audioSink.onAttached();\n    } else {\n      this._audioSink.onDetached();\n    }\n  }\n\n  setTranscriptionEnabled(enabled: boolean): void {\n    if (enabled === this._transcriptionEnabled) {\n      return;\n    }\n\n    this._transcriptionEnabled = enabled;\n\n    if (!this._transcriptionSink) {\n      return;\n    }\n\n    if (enabled) {\n      this._transcriptionSink.onAttached();\n    } else {\n      this._transcriptionSink.onDetached();\n    }\n  }\n\n  get audioEnabled(): boolean {\n    return this._audioEnabled;\n  }\n\n  get transcriptionEnabled(): boolean {\n    return this._transcriptionEnabled;\n  }\n\n  get audio(): AudioOutput | null {\n    return this._audioSink;\n  }\n\n  set audio(sink: AudioOutput | null) {\n    if (sink === this._audioSink) {\n      return;\n    }\n\n    if (this._audioSink) {\n      this._audioSink.onDetached();\n    }\n\n    this._audioSink = sink;\n    this.audioChanged();\n\n    if (this._audioSink) {\n      this._audioSink.onAttached();\n    }\n  }\n\n  get transcription(): TextOutput | null {\n    return this._transcriptionSink;\n  }\n\n  set transcription(sink: TextOutput | null) {\n    if (sink === this._transcriptionSink) {\n      return;\n    }\n\n    if (this._transcriptionSink) {\n      this._transcriptionSink.onDetached();\n    }\n\n    this._transcriptionSink = sink;\n    this.transcriptionChanged();\n\n    if (this._transcriptionSink) {\n      this._transcriptionSink.onAttached();\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/voice/io.d.cts

@@ -6,21 +6,56 @@ import type { ReadableStream } from 'node:stream/web';
 import type { ChatContext } from '../llm/chat_context.js';
 import type { ChatChunk } from '../llm/llm.js';
 import type { ToolContext } from '../llm/tool_context.js';
-import { DeferredReadableStream } from '../stream/deferred_stream.js';
+import { MultiInputStream } from '../stream/multi_input_stream.js';
 import type { SpeechEvent } from '../stt/stt.js';
 import type { ModelSettings } from './agent.js';
 export type STTNode = (audio: ReadableStream<AudioFrame>, modelSettings: ModelSettings) => Promise<ReadableStream<SpeechEvent | string> | null>;
 export type LLMNode = (chatCtx: ChatContext, toolCtx: ToolContext, modelSettings: ModelSettings) => Promise<ReadableStream<ChatChunk | string> | null>;
 export type TTSNode = (text: ReadableStream<string>, modelSettings: ModelSettings) => Promise<ReadableStream<AudioFrame> | null>;
+/**
+ * Symbol used to identify TimedString objects.
+ */
+export declare const TIMED_STRING_SYMBOL: unique symbol;
+/**
+ * A string with optional start and end timestamps for word-level alignment.
+ */
+export interface TimedString {
+    readonly [TIMED_STRING_SYMBOL]: true;
+    text: string;
+    startTime?: number;
+    endTime?: number;
+    confidence?: number;
+    startTimeOffset?: number;
+}
+/**
+ * Factory function to create a TimedString object.
+ */
+export declare function createTimedString(opts: {
+    text: string;
+    startTime?: number;
+    endTime?: number;
+    confidence?: number;
+    startTimeOffset?: number;
+}): TimedString;
+/**
+ * Type guard to check if a value is a TimedString.
+ */
+export declare function isTimedString(value: unknown): value is TimedString;
+export interface AudioOutputCapabilities {
+    /** Whether this output supports pause/resume functionality */
+    pause: boolean;
+}
 export declare abstract class AudioInput {
-    protected deferredStream: DeferredReadableStream<AudioFrame>;
+    protected multiStream: MultiInputStream<AudioFrame>;
     get stream(): ReadableStream<AudioFrame>;
+    close(): Promise<void>;
     onAttached(): void;
     onDetached(): void;
 }
 export declare abstract class AudioOutput extends EventEmitter {
     sampleRate?: number | undefined;
     protected readonly nextInChain?: AudioOutput | undefined;
+    static readonly EVENT_PLAYBACK_STARTED = "playbackStarted";
     static readonly EVENT_PLAYBACK_FINISHED = "playbackFinished";
     private playbackFinishedFuture;
     private _capturing;
@@ -28,7 +63,12 @@ export declare abstract class AudioOutput extends EventEmitter {
     private playbackSegmentsCount;
     private lastPlaybackEvent;
     protected logger: import("pino").Logger;
-    constructor(sampleRate?: number | undefined, nextInChain?: AudioOutput | undefined);
+    protected readonly capabilities: AudioOutputCapabilities;
+    constructor(sampleRate?: number | undefined, nextInChain?: AudioOutput | undefined, capabilities?: AudioOutputCapabilities);
+    /**
+     * Whether this output and all outputs in the chain support pause/resume.
+     */
+    get canPause(): boolean;
     /**
      * Capture an audio frame for playback, frames can be pushed faster than real-time
      */
@@ -39,6 +79,11 @@ export declare abstract class AudioOutput extends EventEmitter {
      * @returns The event that was emitted when the audio finished playing out (only the last segment information)
      */
     waitForPlayout(): Promise<PlaybackFinishedEvent>;
+    /**
+     * Called when playback actually starts (first frame is sent to output).
+     * Developers building audio sinks should call this when the first frame is captured.
+     */
+    onPlaybackStarted(createdAt: number): void;
     /**
      * Developers building audio sinks must call this method when a playback/segment is finished.
      * Segments are segmented by calls to flush() or clearBuffer()
@@ -51,19 +96,34 @@ export declare abstract class AudioOutput extends EventEmitter {
     abstract clearBuffer(): void;
     onAttached(): void;
     onDetached(): void;
+    /**
+     * Pause the audio playback
+     */
+    pause(): void;
+    /**
+     * Resume the audio playback
+     */
+    resume(): void;
 }
 export interface PlaybackFinishedEvent {
+    /** How much of the audio was played back, in seconds */
     playbackPosition: number;
+    /** True if playback was interrupted (clearBuffer() was called) */
     interrupted: boolean;
+    /**
+     * Transcript synced with playback; may be partial if the audio was interrupted.
+     * When undefined, the transcript is not synchronized with the playback.
+     */
     synchronizedTranscript?: string;
 }
+export interface PlaybackStartedEvent {
+    /** The timestamp (Date.now()) when the playback started */
+    createdAt: number;
+}
 export declare abstract class TextOutput {
     protected readonly nextInChain?: TextOutput | undefined;
     constructor(nextInChain?: TextOutput | undefined);
-    /**
-     * Capture a text segment (Used by the output of LLM nodes)
-     */
-    abstract captureText(text: string): Promise<void>;
+    abstract captureText(text: string | TimedString): Promise<void>;
     /**
      * Mark the current text segment as complete (e.g LLM generation is complete)
      */