@crewhaus/barge-in-controller 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json ADDED
@@ -0,0 +1,42 @@
1
+ {
2
+ "name": "@crewhaus/barge-in-controller",
3
+ "version": "0.1.0",
4
+ "type": "module",
5
+ "description": "Barge-in coordinator: watches inbound audio via vad-engine, fires interrupt() on adapter when user speaks during agent playback (Section 24 VOICE)",
6
+ "main": "src/index.ts",
7
+ "types": "src/index.ts",
8
+ "exports": {
9
+ ".": "./src/index.ts"
10
+ },
11
+ "scripts": {
12
+ "test": "bun test src"
13
+ },
14
+ "dependencies": {
15
+ "@crewhaus/vad-engine": "0.0.0",
16
+ "@crewhaus/voice-runtime": "0.0.0"
17
+ },
18
+ "license": "Apache-2.0",
19
+ "author": {
20
+ "name": "Max Meier",
21
+ "email": "max@studiomax.io",
22
+ "url": "https://studiomax.io"
23
+ },
24
+ "repository": {
25
+ "type": "git",
26
+ "url": "git+https://github.com/crewhaus/factory.git",
27
+ "directory": "packages/barge-in-controller"
28
+ },
29
+ "homepage": "https://github.com/crewhaus/factory/tree/main/packages/barge-in-controller#readme",
30
+ "bugs": {
31
+ "url": "https://github.com/crewhaus/factory/issues"
32
+ },
33
+ "publishConfig": {
34
+ "access": "restricted"
35
+ },
36
+ "files": [
37
+ "src",
38
+ "README.md",
39
+ "LICENSE",
40
+ "NOTICE"
41
+ ]
42
+ }
@@ -0,0 +1,133 @@
1
+ import { describe, expect, test } from "bun:test";
2
+ import type { RealtimeAdapter, RealtimeEvent, RealtimeEventHandler } from "@crewhaus/voice-runtime";
3
+ import { createBargeInController } from "./index.js";
4
+
5
+ /**
6
+ * Stub adapter that exposes the event-bus + records interrupt() calls.
7
+ */
8
+ function makeStubAdapter(): {
9
+ adapter: RealtimeAdapter;
10
+ fire(event: RealtimeEvent): void;
11
+ interrupts: string[];
12
+ } {
13
+ const handlers = new Set<RealtimeEventHandler>();
14
+ const interrupts: string[] = [];
15
+ const adapter: RealtimeAdapter = {
16
+ providerId: "openai",
17
+ sampleRate: 24_000,
18
+ get connected() {
19
+ return true;
20
+ },
21
+ async connect() {},
22
+ sendAudio() {},
23
+ sendText() {},
24
+ interrupt(reason) {
25
+ interrupts.push(reason);
26
+ // Mimic the real adapter: emit a synthetic interrupt event.
27
+ for (const h of handlers) h({ kind: "interrupt", reason });
28
+ },
29
+ on(h) {
30
+ handlers.add(h);
31
+ return () => {
32
+ handlers.delete(h);
33
+ };
34
+ },
35
+ async disconnect() {},
36
+ };
37
+ return {
38
+ adapter,
39
+ fire: (event) => {
40
+ for (const h of handlers) h(event);
41
+ },
42
+ interrupts,
43
+ };
44
+ }
45
+
46
+ function speechFrame(): Int16Array {
47
+ // Energy + ZCR sufficient to trigger speech verdict at aggressiveness 1.
48
+ const out = new Int16Array(720);
49
+ for (let i = 0; i < 720; i++) {
50
+ const sig =
51
+ 0.7 * Math.sin((2 * Math.PI * 500 * i) / 24_000) +
52
+ 0.3 * Math.sin((2 * Math.PI * 1500 * i) / 24_000);
53
+ out[i] = Math.round(sig * 8000);
54
+ }
55
+ return out;
56
+ }
57
+
58
+ function silentFrame(): Int16Array {
59
+ return new Int16Array(720);
60
+ }
61
+
62
+ describe("createBargeInController", () => {
63
+ test("does NOT interrupt when the agent is idle (T1)", () => {
64
+ const { adapter, interrupts } = makeStubAdapter();
65
+ const ctrl = createBargeInController({ adapter });
66
+ for (let i = 0; i < 10; i++) ctrl.feedAudioFrame(speechFrame());
67
+ expect(interrupts).toHaveLength(0);
68
+ ctrl.stop();
69
+ });
70
+
71
+ test("does NOT interrupt on a single speech frame (hysteresis)", () => {
72
+ const { adapter, fire, interrupts } = makeStubAdapter();
73
+ const ctrl = createBargeInController({ adapter, triggerFrames: 4 });
74
+ fire({ kind: "audio_chunk", pcm: new Int16Array(0), sampleRate: 24_000 });
75
+ ctrl.feedAudioFrame(speechFrame());
76
+ ctrl.feedAudioFrame(silentFrame());
77
+ expect(interrupts).toHaveLength(0);
78
+ ctrl.stop();
79
+ });
80
+
81
+ test("interrupts after triggerFrames consecutive speech frames during agent playback (T3)", () => {
82
+ const { adapter, fire, interrupts } = makeStubAdapter();
83
+ const onBargeIn: { hits: number } = { hits: 0 };
84
+ const ctrl = createBargeInController({
85
+ adapter,
86
+ triggerFrames: 4,
87
+ windowMs: 200,
88
+ frameMs: 30,
89
+ onBargeIn: () => {
90
+ onBargeIn.hits += 1;
91
+ },
92
+ });
93
+ // Mark agent speaking.
94
+ fire({ kind: "audio_chunk", pcm: new Int16Array(0), sampleRate: 24_000 });
95
+ expect(ctrl.isAgentSpeaking()).toBe(true);
96
+
97
+ for (let i = 0; i < 4; i++) ctrl.feedAudioFrame(speechFrame());
98
+ expect(interrupts).toHaveLength(1);
99
+ expect(interrupts[0]).toBe("user barged in");
100
+ expect(onBargeIn.hits).toBe(1);
101
+ expect(ctrl.isAgentSpeaking()).toBe(false);
102
+ ctrl.stop();
103
+ });
104
+
105
+ test("idle agent → speech doesn't trigger interrupt", () => {
106
+ const { adapter, fire, interrupts } = makeStubAdapter();
107
+ const ctrl = createBargeInController({ adapter, triggerFrames: 2, windowMs: 200, frameMs: 30 });
108
+ // Without an audio_chunk event, agent stays idle.
109
+ for (let i = 0; i < 10; i++) ctrl.feedAudioFrame(speechFrame());
110
+ expect(interrupts).toHaveLength(0);
111
+ // Now mark agent idle->speaking and feed speech: SHOULD trigger.
112
+ fire({ kind: "audio_chunk", pcm: new Int16Array(0), sampleRate: 24_000 });
113
+ ctrl.feedAudioFrame(speechFrame());
114
+ ctrl.feedAudioFrame(speechFrame());
115
+ expect(interrupts).toHaveLength(1);
116
+ ctrl.stop();
117
+ });
118
+
119
+ test("transcript_final marks agent idle and resets the speech-frame window", () => {
120
+ const { adapter, fire, interrupts } = makeStubAdapter();
121
+ const ctrl = createBargeInController({ adapter, triggerFrames: 4, windowMs: 200, frameMs: 30 });
122
+ fire({ kind: "audio_chunk", pcm: new Int16Array(0), sampleRate: 24_000 });
123
+ ctrl.feedAudioFrame(speechFrame());
124
+ ctrl.feedAudioFrame(speechFrame());
125
+ fire({ kind: "transcript_final", text: "..." });
126
+ expect(ctrl.isAgentSpeaking()).toBe(false);
127
+ // Now agent idle: 2 more speech frames shouldn't trigger.
128
+ ctrl.feedAudioFrame(speechFrame());
129
+ ctrl.feedAudioFrame(speechFrame());
130
+ expect(interrupts).toHaveLength(0);
131
+ ctrl.stop();
132
+ });
133
+ });
package/src/index.ts ADDED
@@ -0,0 +1,124 @@
1
+ /**
2
+ * Catalog R16 `barge-in-controller` — Section 24 VOICE.
3
+ *
4
+ * Coordinator between `vad-engine` and a `RealtimeAdapter`. Watches
5
+ * inbound user audio frames; when the user starts speaking AND the
6
+ * agent is currently playing audio back, fires `adapter.interrupt()`
7
+ * so the agent's response is cancelled and the user's turn takes over.
8
+ *
9
+ * Hysteresis: a single 30ms speech frame is not enough to barge in
10
+ * (rejects a 50ms cough). The controller waits for `triggerFrames`
11
+ * consecutive speech-classified frames within a `windowMs` window
12
+ * before firing. Defaults: 4 frames in 200ms.
13
+ *
14
+ * Playback tracking: the controller listens for `audio_chunk` events on
15
+ * the adapter to mark the agent as "speaking", and for
16
+ * `transcript_final` / `interrupt` / `disconnect` to mark the agent as
17
+ * "idle". Barge-in only fires while the agent is speaking — when it's
18
+ * idle, `feedAudioFrame` is a no-op (the user's normal turn ends with
19
+ * server VAD, no need to interrupt anything).
20
+ */
21
+ import { type VadDetector, createVadDetector } from "@crewhaus/vad-engine";
22
+ import type { RealtimeAdapter } from "@crewhaus/voice-runtime";
23
+
24
+ export type BargeInOptions = {
25
+ readonly adapter: RealtimeAdapter;
26
+ readonly detector?: VadDetector;
27
+ /**
28
+ * Consecutive speech frames inside `windowMs` to trigger an
29
+ * interrupt. Defaults to 4 (≈ 120ms of continuous speech at 30ms
30
+ * framing).
31
+ */
32
+ readonly triggerFrames?: number;
33
+ /** Sliding-window bound for the trigger count. Defaults to 200ms. */
34
+ readonly windowMs?: number;
35
+ /** Per-frame elapsed time advances. Defaults to 30ms. */
36
+ readonly frameMs?: number;
37
+ readonly onBargeIn?: (info: { reason: string; speechFrames: number }) => void;
38
+ };
39
+
40
+ export interface BargeInController {
41
+ /** Push one inbound user-mic PCM frame. Returns the VAD verdict for diagnostics. */
42
+ feedAudioFrame(frame: Int16Array): "speech" | "silence" | "transitioning";
43
+ /** Whether the agent is currently speaking (set by adapter `audio_chunk` events). */
44
+ isAgentSpeaking(): boolean;
45
+ /** Detach the adapter listener. */
46
+ stop(): void;
47
+ }
48
+
49
+ const DEFAULT_TRIGGER_FRAMES = 4;
50
+ const DEFAULT_WINDOW_MS = 200;
51
+ const DEFAULT_FRAME_MS = 30;
52
+
53
+ export function createBargeInController(opts: BargeInOptions): BargeInController {
54
+ const detector = opts.detector ?? createVadDetector({ aggressiveness: 1 });
55
+ const triggerFrames = opts.triggerFrames ?? DEFAULT_TRIGGER_FRAMES;
56
+ const windowMs = opts.windowMs ?? DEFAULT_WINDOW_MS;
57
+ const frameMs = opts.frameMs ?? DEFAULT_FRAME_MS;
58
+
59
+ let agentSpeaking = false;
60
+ let virtualNowMs = 0;
61
+ // Sliding window of speech frame timestamps.
62
+ const speechFrameStamps: number[] = [];
63
+
64
+ const off = opts.adapter.on((event) => {
65
+ if (event.kind === "audio_chunk") {
66
+ agentSpeaking = true;
67
+ } else if (
68
+ event.kind === "transcript_final" ||
69
+ event.kind === "interrupt" ||
70
+ event.kind === "disconnect"
71
+ ) {
72
+ agentSpeaking = false;
73
+ // Reset window so a stray pre-event frame doesn't carry over.
74
+ speechFrameStamps.length = 0;
75
+ }
76
+ });
77
+
78
+ return {
79
+ feedAudioFrame(frame) {
80
+ virtualNowMs += frameMs;
81
+ const verdict = detector.detect(frame);
82
+ if (!agentSpeaking) {
83
+ // No audio playing → no barge-in needed. Still advance the
84
+ // window so it doesn't accumulate stale frames.
85
+ if (verdict === "speech") {
86
+ speechFrameStamps.push(virtualNowMs);
87
+ }
88
+ // Trim window
89
+ const cutoff = virtualNowMs - windowMs;
90
+ while (speechFrameStamps.length > 0 && (speechFrameStamps[0] ?? cutoff) < cutoff) {
91
+ speechFrameStamps.shift();
92
+ }
93
+ return verdict;
94
+ }
95
+
96
+ if (verdict === "speech") {
97
+ speechFrameStamps.push(virtualNowMs);
98
+ }
99
+ const cutoff = virtualNowMs - windowMs;
100
+ while (speechFrameStamps.length > 0 && (speechFrameStamps[0] ?? cutoff) < cutoff) {
101
+ speechFrameStamps.shift();
102
+ }
103
+
104
+ if (speechFrameStamps.length >= triggerFrames) {
105
+ const count = speechFrameStamps.length;
106
+ speechFrameStamps.length = 0;
107
+ agentSpeaking = false;
108
+ try {
109
+ opts.adapter.interrupt("user barged in");
110
+ } catch {
111
+ /* tolerate adapter disconnect mid-barge-in */
112
+ }
113
+ opts.onBargeIn?.({ reason: "user barged in", speechFrames: count });
114
+ }
115
+ return verdict;
116
+ },
117
+ isAgentSpeaking() {
118
+ return agentSpeaking;
119
+ },
120
+ stop() {
121
+ off();
122
+ },
123
+ };
124
+ }