realtime-voice-agents 2.5.1 → 2.5.2
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/README.md +1 -0
- package/dist/gpt-live.cjs +66 -4
- package/dist/gpt-live.d.cts +34 -1
- package/dist/gpt-live.d.mts +34 -1
- package/dist/gpt-live.mjs +66 -5
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -121,6 +121,7 @@ One `SessionOptions` surface configures all four; where a provider can't honor a
|
|
|
121
121
|
- **Immutable session.** Instructions, voice and audio format cannot change after start, so handoffs and reconnects open a fresh session and seed the attributed transcript through `session.input` (≤ 128 messages) — the anti-loop replay is preserved. Sessions expire after 120 minutes; an expiry reconnects the same way.
|
|
122
122
|
- **Transfers wait for the sentence.** A handoff here is a close-and-reopen, and the backend's transfer lands while the voice is still announcing it — the bridge holds the handoff until that utterance has played out (plus one sentence gap, capped at 5 s), so nothing is cut mid-word and `session.handoffHold` audio covers the reopen. Prompt the voice to *delegate first, announce after*: a transfer or tool the voice announces without delegating never happens.
|
|
123
123
|
- **Deafness feeds silence.** The model's session clock runs on input audio, so `deafness` options replace caller audio with silence instead of dropping frames. `ignoreUserAudioUntilFirstTurnDone` therefore defaults to **off** here — the model handles talk-over itself; set it explicitly to keep the greeting deaf.
|
|
124
|
+
- **Real-time stream, 200 ms of cushion.** The voice arrives at exactly real-time pace, so Twilio's buffer never runs ahead of playout and every delivery hiccup between OpenAI, your server and Twilio would be an audible gap (Realtime generates faster than real time, so it never has this problem). The provider holds the first 200 ms of each utterance — the last idle delta included, so soft onsets are not clipped — then streams through. `gptLive({ playoutLeadMs })` tunes it, `0` disables; the cost is that much latency on each turn's first word.
|
|
124
125
|
- **Billing is per second** of session (plus backend tokens). `session.usage.audioSeconds` carries the running total; backend token usage is summed from `response.completed`. The provider sends `session.close` on teardown and waits for `session.closed`, so a hung-up call never keeps billing.
|
|
125
126
|
|
|
126
127
|
## Provider fallbacks
|
package/dist/gpt-live.cjs
CHANGED
|
@@ -310,6 +310,8 @@ const NON_RETRIABLE_CLOSE_CODES = /* @__PURE__ */ new Set([
|
|
|
310
310
|
const APPEND_MAX_CHARS = 1200;
|
|
311
311
|
const TRANSCRIPT_IDLE_EXTRA_MS = 300;
|
|
312
312
|
const GATE_STALL_EXTRA_MS = 500;
|
|
313
|
+
const DEFAULT_PLAYOUT_LEAD_MS = 200;
|
|
314
|
+
const MULAW_BYTES_PER_MS = 8;
|
|
313
315
|
const ACK_TYPES = {
|
|
314
316
|
"session.instructions.append": "session.instructions.appended",
|
|
315
317
|
"session.thinking.append": "session.thinking.appended",
|
|
@@ -346,6 +348,10 @@ var GptLiveProvider = class extends require_BaseRealtimeProvider.BaseRealtimePro
|
|
|
346
348
|
expiresAt = null;
|
|
347
349
|
gate;
|
|
348
350
|
gateStallTimer = null;
|
|
351
|
+
/** Deltas of the current utterance held until the playout lead has accumulated. */
|
|
352
|
+
lead = null;
|
|
353
|
+
/** The last idle delta: becomes the utterance's pre-roll when the gate opens. */
|
|
354
|
+
preRoll = null;
|
|
349
355
|
utteranceCounter = 0;
|
|
350
356
|
currentUtteranceId = null;
|
|
351
357
|
lastUtteranceId = null;
|
|
@@ -492,6 +498,8 @@ var GptLiveProvider = class extends require_BaseRealtimeProvider.BaseRealtimePro
|
|
|
492
498
|
this.inputTranscript.dispose();
|
|
493
499
|
this.outputTranscript.dispose();
|
|
494
500
|
this.clearGateStall();
|
|
501
|
+
this.lead = null;
|
|
502
|
+
this.preRoll = null;
|
|
495
503
|
if (!ws$2 || ws$2.readyState === ws.default.CLOSED) return;
|
|
496
504
|
await new Promise((resolve) => {
|
|
497
505
|
const timer = setTimeout(() => finish(), this.config.closeTimeoutMs ?? 3e3);
|
|
@@ -685,14 +693,63 @@ var GptLiveProvider = class extends require_BaseRealtimeProvider.BaseRealtimePro
|
|
|
685
693
|
for (const gateEvent of events) if (gateEvent.type === "open") {
|
|
686
694
|
this.beginUtterance();
|
|
687
695
|
forwardId = this.currentUtteranceId;
|
|
696
|
+
this.armPlayoutLead();
|
|
688
697
|
} else close = gateEvent;
|
|
689
|
-
if (forwardId) this.
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
698
|
+
if (forwardId) this.forwardAudio(delta, bytes.length / MULAW_BYTES_PER_MS, forwardId);
|
|
699
|
+
else this.preRoll = {
|
|
700
|
+
delta,
|
|
701
|
+
ms: bytes.length / MULAW_BYTES_PER_MS
|
|
702
|
+
};
|
|
693
703
|
if (close) this.endUtterance();
|
|
694
704
|
else if (this.gate.isOpen) this.armGateStall();
|
|
695
705
|
}
|
|
706
|
+
/**
|
|
707
|
+
* The stream is real-time paced, so Twilio's buffer never runs ahead of
|
|
708
|
+
* playout and every delivery hiccup between the model, this server and
|
|
709
|
+
* Twilio is an audible gap (field, Sept 2026: "slightly choppy"). Hold the
|
|
710
|
+
* first `playoutLeadMs` of each utterance — the last idle delta included —
|
|
711
|
+
* then flush and stream through: Twilio keeps that much cushion for the
|
|
712
|
+
* rest of the utterance, at the cost of that much latency on its first word.
|
|
713
|
+
*/
|
|
714
|
+
armPlayoutLead() {
|
|
715
|
+
if (this.playoutLeadMs() <= 0) {
|
|
716
|
+
this.preRoll = null;
|
|
717
|
+
return;
|
|
718
|
+
}
|
|
719
|
+
this.lead = {
|
|
720
|
+
pending: [],
|
|
721
|
+
pendingMs: 0
|
|
722
|
+
};
|
|
723
|
+
if (this.preRoll) {
|
|
724
|
+
this.lead.pending.push(this.preRoll.delta);
|
|
725
|
+
this.lead.pendingMs += this.preRoll.ms;
|
|
726
|
+
this.preRoll = null;
|
|
727
|
+
}
|
|
728
|
+
}
|
|
729
|
+
forwardAudio(delta, ms, responseId) {
|
|
730
|
+
if (!this.lead) {
|
|
731
|
+
this.emit("audio", {
|
|
732
|
+
base64Mulaw: delta,
|
|
733
|
+
responseId
|
|
734
|
+
});
|
|
735
|
+
return;
|
|
736
|
+
}
|
|
737
|
+
this.lead.pending.push(delta);
|
|
738
|
+
this.lead.pendingMs += ms;
|
|
739
|
+
if (this.lead.pendingMs >= this.playoutLeadMs()) this.flushPlayoutLead(responseId);
|
|
740
|
+
}
|
|
741
|
+
flushPlayoutLead(responseId) {
|
|
742
|
+
const lead = this.lead;
|
|
743
|
+
if (!lead) return;
|
|
744
|
+
this.lead = null;
|
|
745
|
+
for (const delta of lead.pending) this.emit("audio", {
|
|
746
|
+
base64Mulaw: delta,
|
|
747
|
+
responseId
|
|
748
|
+
});
|
|
749
|
+
}
|
|
750
|
+
playoutLeadMs() {
|
|
751
|
+
return this.config.playoutLeadMs ?? 200;
|
|
752
|
+
}
|
|
696
753
|
handleBackendEvent(inner, delegationId) {
|
|
697
754
|
const type = inner.type ?? "";
|
|
698
755
|
if (type === "response.output_item.done" && inner.item?.type === "function_call") {
|
|
@@ -729,6 +786,7 @@ var GptLiveProvider = class extends require_BaseRealtimeProvider.BaseRealtimePro
|
|
|
729
786
|
endUtterance() {
|
|
730
787
|
this.clearGateStall();
|
|
731
788
|
const id = this.currentUtteranceId;
|
|
789
|
+
if (id) this.flushPlayoutLead(id);
|
|
732
790
|
this.currentUtteranceId = null;
|
|
733
791
|
if (id) this.emit("responseDone", { responseId: id });
|
|
734
792
|
}
|
|
@@ -757,6 +815,8 @@ var GptLiveProvider = class extends require_BaseRealtimeProvider.BaseRealtimePro
|
|
|
757
815
|
resetUtteranceState() {
|
|
758
816
|
this.clearGateStall();
|
|
759
817
|
this.gate.close();
|
|
818
|
+
this.lead = null;
|
|
819
|
+
this.preRoll = null;
|
|
760
820
|
this.currentUtteranceId = null;
|
|
761
821
|
this.lastUtteranceId = null;
|
|
762
822
|
this.seenCalls.clear();
|
|
@@ -923,6 +983,7 @@ function gptLive(options = {}) {
|
|
|
923
983
|
store: options.store,
|
|
924
984
|
extraSessionOptions: options.sessionOptions,
|
|
925
985
|
connectTimeoutMs: options.connectTimeoutMs,
|
|
986
|
+
playoutLeadMs: options.playoutLeadMs,
|
|
926
987
|
speechGate: options.speechGate,
|
|
927
988
|
transcriptGapMs: options.transcriptGapMs
|
|
928
989
|
};
|
|
@@ -938,6 +999,7 @@ function gptLive(options = {}) {
|
|
|
938
999
|
//#endregion
|
|
939
1000
|
exports.DEFAULT_GATE_QUIET_MS = DEFAULT_GATE_QUIET_MS;
|
|
940
1001
|
exports.DEFAULT_GATE_THRESHOLD_RMS = DEFAULT_GATE_THRESHOLD_RMS;
|
|
1002
|
+
exports.DEFAULT_PLAYOUT_LEAD_MS = DEFAULT_PLAYOUT_LEAD_MS;
|
|
941
1003
|
exports.GPT_LIVE_AUDIO_FORMAT = GPT_LIVE_AUDIO_FORMAT;
|
|
942
1004
|
exports.GPT_LIVE_DEFAULT_BACKEND_MODEL = GPT_LIVE_DEFAULT_BACKEND_MODEL;
|
|
943
1005
|
exports.GPT_LIVE_DEFAULT_BASE_URL = GPT_LIVE_DEFAULT_BASE_URL;
|
package/dist/gpt-live.d.cts
CHANGED
|
@@ -126,6 +126,14 @@ interface GptLiveProviderConfig {
|
|
|
126
126
|
connectTimeoutMs?: number;
|
|
127
127
|
/** How long `close()` waits for `session.closed` (final usage) before dropping the socket. Default 3000. */
|
|
128
128
|
closeTimeoutMs?: number;
|
|
129
|
+
/**
|
|
130
|
+
* Audio held back at the start of each utterance before forwarding begins,
|
|
131
|
+
* so Twilio keeps that much cushion against delivery jitter (the stream is
|
|
132
|
+
* real-time paced — without it any hiccup is an audible gap). The last idle
|
|
133
|
+
* delta before the onset is included, so soft onsets are not clipped.
|
|
134
|
+
* Default 200; 0 forwards every delta as it arrives.
|
|
135
|
+
*/
|
|
136
|
+
playoutLeadMs?: number;
|
|
129
137
|
/** Speech gate tuning (utterance boundaries synthesized from the audio). */
|
|
130
138
|
speechGate?: SpeechGateOptions;
|
|
131
139
|
/** Session-timeline gap that splits transcript fragments into turns. Default 800. */
|
|
@@ -137,6 +145,7 @@ interface GptLiveProviderConfig {
|
|
|
137
145
|
ackTimeoutMs?: number;
|
|
138
146
|
providerName?: string;
|
|
139
147
|
}
|
|
148
|
+
declare const DEFAULT_PLAYOUT_LEAD_MS = 200;
|
|
140
149
|
declare class GptLiveProvider extends BaseRealtimeProvider {
|
|
141
150
|
readonly name: string;
|
|
142
151
|
readonly capabilities: ProviderCapabilities;
|
|
@@ -152,6 +161,10 @@ declare class GptLiveProvider extends BaseRealtimeProvider {
|
|
|
152
161
|
expiresAt: number | null;
|
|
153
162
|
private readonly gate;
|
|
154
163
|
private gateStallTimer;
|
|
164
|
+
/** Deltas of the current utterance held until the playout lead has accumulated. */
|
|
165
|
+
private lead;
|
|
166
|
+
/** The last idle delta: becomes the utterance's pre-roll when the gate opens. */
|
|
167
|
+
private preRoll;
|
|
155
168
|
private utteranceCounter;
|
|
156
169
|
private currentUtteranceId;
|
|
157
170
|
private lastUtteranceId;
|
|
@@ -192,6 +205,18 @@ declare class GptLiveProvider extends BaseRealtimeProvider {
|
|
|
192
205
|
updateSession(patch: Partial<ProviderSessionInit>, options?: SessionUpdateOptions): Promise<boolean>;
|
|
193
206
|
private handleEvent;
|
|
194
207
|
private handleOutputAudio;
|
|
208
|
+
/**
|
|
209
|
+
* The stream is real-time paced, so Twilio's buffer never runs ahead of
|
|
210
|
+
* playout and every delivery hiccup between the model, this server and
|
|
211
|
+
* Twilio is an audible gap (field, Sept 2026: "slightly choppy"). Hold the
|
|
212
|
+
* first `playoutLeadMs` of each utterance — the last idle delta included —
|
|
213
|
+
* then flush and stream through: Twilio keeps that much cushion for the
|
|
214
|
+
* rest of the utterance, at the cost of that much latency on its first word.
|
|
215
|
+
*/
|
|
216
|
+
private armPlayoutLead;
|
|
217
|
+
private forwardAudio;
|
|
218
|
+
private flushPlayoutLead;
|
|
219
|
+
private playoutLeadMs;
|
|
195
220
|
private handleBackendEvent;
|
|
196
221
|
private beginUtterance;
|
|
197
222
|
private endUtterance;
|
|
@@ -244,6 +269,14 @@ interface GptLiveOptions {
|
|
|
244
269
|
/** Provider-native `session.start` fields, deep-merged last. The schema is strict: an unknown field rejects the session. */
|
|
245
270
|
sessionOptions?: Record<string, unknown>;
|
|
246
271
|
connectTimeoutMs?: number;
|
|
272
|
+
/**
|
|
273
|
+
* Cushion held at the start of each utterance before audio is forwarded to
|
|
274
|
+
* Twilio. The model streams at exactly real-time pace, so without it any
|
|
275
|
+
* delivery hiccup is an audible gap; with it Twilio stays that far ahead of
|
|
276
|
+
* playout. Costs the same amount of latency on each turn's first word.
|
|
277
|
+
* Default 200; 0 forwards every delta as it arrives.
|
|
278
|
+
*/
|
|
279
|
+
playoutLeadMs?: number;
|
|
247
280
|
/** Speech gate tuning — utterance boundaries synthesized from the continuous output stream. */
|
|
248
281
|
speechGate?: SpeechGateOptions;
|
|
249
282
|
/** Session-timeline gap that splits transcript fragments into turns. Default 800. */
|
|
@@ -258,4 +291,4 @@ interface GptLiveOptions {
|
|
|
258
291
|
*/
|
|
259
292
|
declare function gptLive(options?: GptLiveOptions): ProviderFactory;
|
|
260
293
|
//#endregion
|
|
261
|
-
export { DEFAULT_GATE_QUIET_MS, DEFAULT_GATE_THRESHOLD_RMS, GPT_LIVE_AUDIO_FORMAT, GPT_LIVE_DEFAULT_BACKEND_MODEL, GPT_LIVE_DEFAULT_BASE_URL, GPT_LIVE_DEFAULT_MODEL, GPT_LIVE_DEFAULT_VOICE, GPT_LIVE_KEY_ENV_VARS, GPT_LIVE_VOICES, type GptLiveDelegationOptions, GptLiveOptions, GptLiveProvider, type GptLiveProviderConfig, type GptLiveSessionConfig, GptLiveVoice, SpeechGate, type SpeechGateOptions, buildDelegation, buildHistoryItems, buildSessionStart, gptLive, splitForAppend };
|
|
294
|
+
export { DEFAULT_GATE_QUIET_MS, DEFAULT_GATE_THRESHOLD_RMS, DEFAULT_PLAYOUT_LEAD_MS, GPT_LIVE_AUDIO_FORMAT, GPT_LIVE_DEFAULT_BACKEND_MODEL, GPT_LIVE_DEFAULT_BASE_URL, GPT_LIVE_DEFAULT_MODEL, GPT_LIVE_DEFAULT_VOICE, GPT_LIVE_KEY_ENV_VARS, GPT_LIVE_VOICES, type GptLiveDelegationOptions, GptLiveOptions, GptLiveProvider, type GptLiveProviderConfig, type GptLiveSessionConfig, GptLiveVoice, SpeechGate, type SpeechGateOptions, buildDelegation, buildHistoryItems, buildSessionStart, gptLive, splitForAppend };
|
package/dist/gpt-live.d.mts
CHANGED
|
@@ -126,6 +126,14 @@ interface GptLiveProviderConfig {
|
|
|
126
126
|
connectTimeoutMs?: number;
|
|
127
127
|
/** How long `close()` waits for `session.closed` (final usage) before dropping the socket. Default 3000. */
|
|
128
128
|
closeTimeoutMs?: number;
|
|
129
|
+
/**
|
|
130
|
+
* Audio held back at the start of each utterance before forwarding begins,
|
|
131
|
+
* so Twilio keeps that much cushion against delivery jitter (the stream is
|
|
132
|
+
* real-time paced — without it any hiccup is an audible gap). The last idle
|
|
133
|
+
* delta before the onset is included, so soft onsets are not clipped.
|
|
134
|
+
* Default 200; 0 forwards every delta as it arrives.
|
|
135
|
+
*/
|
|
136
|
+
playoutLeadMs?: number;
|
|
129
137
|
/** Speech gate tuning (utterance boundaries synthesized from the audio). */
|
|
130
138
|
speechGate?: SpeechGateOptions;
|
|
131
139
|
/** Session-timeline gap that splits transcript fragments into turns. Default 800. */
|
|
@@ -137,6 +145,7 @@ interface GptLiveProviderConfig {
|
|
|
137
145
|
ackTimeoutMs?: number;
|
|
138
146
|
providerName?: string;
|
|
139
147
|
}
|
|
148
|
+
declare const DEFAULT_PLAYOUT_LEAD_MS = 200;
|
|
140
149
|
declare class GptLiveProvider extends BaseRealtimeProvider {
|
|
141
150
|
readonly name: string;
|
|
142
151
|
readonly capabilities: ProviderCapabilities;
|
|
@@ -152,6 +161,10 @@ declare class GptLiveProvider extends BaseRealtimeProvider {
|
|
|
152
161
|
expiresAt: number | null;
|
|
153
162
|
private readonly gate;
|
|
154
163
|
private gateStallTimer;
|
|
164
|
+
/** Deltas of the current utterance held until the playout lead has accumulated. */
|
|
165
|
+
private lead;
|
|
166
|
+
/** The last idle delta: becomes the utterance's pre-roll when the gate opens. */
|
|
167
|
+
private preRoll;
|
|
155
168
|
private utteranceCounter;
|
|
156
169
|
private currentUtteranceId;
|
|
157
170
|
private lastUtteranceId;
|
|
@@ -192,6 +205,18 @@ declare class GptLiveProvider extends BaseRealtimeProvider {
|
|
|
192
205
|
updateSession(patch: Partial<ProviderSessionInit>, options?: SessionUpdateOptions): Promise<boolean>;
|
|
193
206
|
private handleEvent;
|
|
194
207
|
private handleOutputAudio;
|
|
208
|
+
/**
|
|
209
|
+
* The stream is real-time paced, so Twilio's buffer never runs ahead of
|
|
210
|
+
* playout and every delivery hiccup between the model, this server and
|
|
211
|
+
* Twilio is an audible gap (field, Sept 2026: "slightly choppy"). Hold the
|
|
212
|
+
* first `playoutLeadMs` of each utterance — the last idle delta included —
|
|
213
|
+
* then flush and stream through: Twilio keeps that much cushion for the
|
|
214
|
+
* rest of the utterance, at the cost of that much latency on its first word.
|
|
215
|
+
*/
|
|
216
|
+
private armPlayoutLead;
|
|
217
|
+
private forwardAudio;
|
|
218
|
+
private flushPlayoutLead;
|
|
219
|
+
private playoutLeadMs;
|
|
195
220
|
private handleBackendEvent;
|
|
196
221
|
private beginUtterance;
|
|
197
222
|
private endUtterance;
|
|
@@ -244,6 +269,14 @@ interface GptLiveOptions {
|
|
|
244
269
|
/** Provider-native `session.start` fields, deep-merged last. The schema is strict: an unknown field rejects the session. */
|
|
245
270
|
sessionOptions?: Record<string, unknown>;
|
|
246
271
|
connectTimeoutMs?: number;
|
|
272
|
+
/**
|
|
273
|
+
* Cushion held at the start of each utterance before audio is forwarded to
|
|
274
|
+
* Twilio. The model streams at exactly real-time pace, so without it any
|
|
275
|
+
* delivery hiccup is an audible gap; with it Twilio stays that far ahead of
|
|
276
|
+
* playout. Costs the same amount of latency on each turn's first word.
|
|
277
|
+
* Default 200; 0 forwards every delta as it arrives.
|
|
278
|
+
*/
|
|
279
|
+
playoutLeadMs?: number;
|
|
247
280
|
/** Speech gate tuning — utterance boundaries synthesized from the continuous output stream. */
|
|
248
281
|
speechGate?: SpeechGateOptions;
|
|
249
282
|
/** Session-timeline gap that splits transcript fragments into turns. Default 800. */
|
|
@@ -258,4 +291,4 @@ interface GptLiveOptions {
|
|
|
258
291
|
*/
|
|
259
292
|
declare function gptLive(options?: GptLiveOptions): ProviderFactory;
|
|
260
293
|
//#endregion
|
|
261
|
-
export { DEFAULT_GATE_QUIET_MS, DEFAULT_GATE_THRESHOLD_RMS, GPT_LIVE_AUDIO_FORMAT, GPT_LIVE_DEFAULT_BACKEND_MODEL, GPT_LIVE_DEFAULT_BASE_URL, GPT_LIVE_DEFAULT_MODEL, GPT_LIVE_DEFAULT_VOICE, GPT_LIVE_KEY_ENV_VARS, GPT_LIVE_VOICES, type GptLiveDelegationOptions, GptLiveOptions, GptLiveProvider, type GptLiveProviderConfig, type GptLiveSessionConfig, GptLiveVoice, SpeechGate, type SpeechGateOptions, buildDelegation, buildHistoryItems, buildSessionStart, gptLive, splitForAppend };
|
|
294
|
+
export { DEFAULT_GATE_QUIET_MS, DEFAULT_GATE_THRESHOLD_RMS, DEFAULT_PLAYOUT_LEAD_MS, GPT_LIVE_AUDIO_FORMAT, GPT_LIVE_DEFAULT_BACKEND_MODEL, GPT_LIVE_DEFAULT_BASE_URL, GPT_LIVE_DEFAULT_MODEL, GPT_LIVE_DEFAULT_VOICE, GPT_LIVE_KEY_ENV_VARS, GPT_LIVE_VOICES, type GptLiveDelegationOptions, GptLiveOptions, GptLiveProvider, type GptLiveProviderConfig, type GptLiveSessionConfig, GptLiveVoice, SpeechGate, type SpeechGateOptions, buildDelegation, buildHistoryItems, buildSessionStart, gptLive, splitForAppend };
|
package/dist/gpt-live.mjs
CHANGED
|
@@ -307,6 +307,8 @@ const NON_RETRIABLE_CLOSE_CODES = /* @__PURE__ */ new Set([
|
|
|
307
307
|
const APPEND_MAX_CHARS = 1200;
|
|
308
308
|
const TRANSCRIPT_IDLE_EXTRA_MS = 300;
|
|
309
309
|
const GATE_STALL_EXTRA_MS = 500;
|
|
310
|
+
const DEFAULT_PLAYOUT_LEAD_MS = 200;
|
|
311
|
+
const MULAW_BYTES_PER_MS = 8;
|
|
310
312
|
const ACK_TYPES = {
|
|
311
313
|
"session.instructions.append": "session.instructions.appended",
|
|
312
314
|
"session.thinking.append": "session.thinking.appended",
|
|
@@ -343,6 +345,10 @@ var GptLiveProvider = class extends BaseRealtimeProvider {
|
|
|
343
345
|
expiresAt = null;
|
|
344
346
|
gate;
|
|
345
347
|
gateStallTimer = null;
|
|
348
|
+
/** Deltas of the current utterance held until the playout lead has accumulated. */
|
|
349
|
+
lead = null;
|
|
350
|
+
/** The last idle delta: becomes the utterance's pre-roll when the gate opens. */
|
|
351
|
+
preRoll = null;
|
|
346
352
|
utteranceCounter = 0;
|
|
347
353
|
currentUtteranceId = null;
|
|
348
354
|
lastUtteranceId = null;
|
|
@@ -489,6 +495,8 @@ var GptLiveProvider = class extends BaseRealtimeProvider {
|
|
|
489
495
|
this.inputTranscript.dispose();
|
|
490
496
|
this.outputTranscript.dispose();
|
|
491
497
|
this.clearGateStall();
|
|
498
|
+
this.lead = null;
|
|
499
|
+
this.preRoll = null;
|
|
492
500
|
if (!ws || ws.readyState === WebSocket$1.CLOSED) return;
|
|
493
501
|
await new Promise((resolve) => {
|
|
494
502
|
const timer = setTimeout(() => finish(), this.config.closeTimeoutMs ?? 3e3);
|
|
@@ -682,14 +690,63 @@ var GptLiveProvider = class extends BaseRealtimeProvider {
|
|
|
682
690
|
for (const gateEvent of events) if (gateEvent.type === "open") {
|
|
683
691
|
this.beginUtterance();
|
|
684
692
|
forwardId = this.currentUtteranceId;
|
|
693
|
+
this.armPlayoutLead();
|
|
685
694
|
} else close = gateEvent;
|
|
686
|
-
if (forwardId) this.
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
695
|
+
if (forwardId) this.forwardAudio(delta, bytes.length / MULAW_BYTES_PER_MS, forwardId);
|
|
696
|
+
else this.preRoll = {
|
|
697
|
+
delta,
|
|
698
|
+
ms: bytes.length / MULAW_BYTES_PER_MS
|
|
699
|
+
};
|
|
690
700
|
if (close) this.endUtterance();
|
|
691
701
|
else if (this.gate.isOpen) this.armGateStall();
|
|
692
702
|
}
|
|
703
|
+
/**
|
|
704
|
+
* The stream is real-time paced, so Twilio's buffer never runs ahead of
|
|
705
|
+
* playout and every delivery hiccup between the model, this server and
|
|
706
|
+
* Twilio is an audible gap (field, Sept 2026: "slightly choppy"). Hold the
|
|
707
|
+
* first `playoutLeadMs` of each utterance — the last idle delta included —
|
|
708
|
+
* then flush and stream through: Twilio keeps that much cushion for the
|
|
709
|
+
* rest of the utterance, at the cost of that much latency on its first word.
|
|
710
|
+
*/
|
|
711
|
+
armPlayoutLead() {
|
|
712
|
+
if (this.playoutLeadMs() <= 0) {
|
|
713
|
+
this.preRoll = null;
|
|
714
|
+
return;
|
|
715
|
+
}
|
|
716
|
+
this.lead = {
|
|
717
|
+
pending: [],
|
|
718
|
+
pendingMs: 0
|
|
719
|
+
};
|
|
720
|
+
if (this.preRoll) {
|
|
721
|
+
this.lead.pending.push(this.preRoll.delta);
|
|
722
|
+
this.lead.pendingMs += this.preRoll.ms;
|
|
723
|
+
this.preRoll = null;
|
|
724
|
+
}
|
|
725
|
+
}
|
|
726
|
+
forwardAudio(delta, ms, responseId) {
|
|
727
|
+
if (!this.lead) {
|
|
728
|
+
this.emit("audio", {
|
|
729
|
+
base64Mulaw: delta,
|
|
730
|
+
responseId
|
|
731
|
+
});
|
|
732
|
+
return;
|
|
733
|
+
}
|
|
734
|
+
this.lead.pending.push(delta);
|
|
735
|
+
this.lead.pendingMs += ms;
|
|
736
|
+
if (this.lead.pendingMs >= this.playoutLeadMs()) this.flushPlayoutLead(responseId);
|
|
737
|
+
}
|
|
738
|
+
flushPlayoutLead(responseId) {
|
|
739
|
+
const lead = this.lead;
|
|
740
|
+
if (!lead) return;
|
|
741
|
+
this.lead = null;
|
|
742
|
+
for (const delta of lead.pending) this.emit("audio", {
|
|
743
|
+
base64Mulaw: delta,
|
|
744
|
+
responseId
|
|
745
|
+
});
|
|
746
|
+
}
|
|
747
|
+
playoutLeadMs() {
|
|
748
|
+
return this.config.playoutLeadMs ?? 200;
|
|
749
|
+
}
|
|
693
750
|
handleBackendEvent(inner, delegationId) {
|
|
694
751
|
const type = inner.type ?? "";
|
|
695
752
|
if (type === "response.output_item.done" && inner.item?.type === "function_call") {
|
|
@@ -726,6 +783,7 @@ var GptLiveProvider = class extends BaseRealtimeProvider {
|
|
|
726
783
|
endUtterance() {
|
|
727
784
|
this.clearGateStall();
|
|
728
785
|
const id = this.currentUtteranceId;
|
|
786
|
+
if (id) this.flushPlayoutLead(id);
|
|
729
787
|
this.currentUtteranceId = null;
|
|
730
788
|
if (id) this.emit("responseDone", { responseId: id });
|
|
731
789
|
}
|
|
@@ -754,6 +812,8 @@ var GptLiveProvider = class extends BaseRealtimeProvider {
|
|
|
754
812
|
resetUtteranceState() {
|
|
755
813
|
this.clearGateStall();
|
|
756
814
|
this.gate.close();
|
|
815
|
+
this.lead = null;
|
|
816
|
+
this.preRoll = null;
|
|
757
817
|
this.currentUtteranceId = null;
|
|
758
818
|
this.lastUtteranceId = null;
|
|
759
819
|
this.seenCalls.clear();
|
|
@@ -920,6 +980,7 @@ function gptLive(options = {}) {
|
|
|
920
980
|
store: options.store,
|
|
921
981
|
extraSessionOptions: options.sessionOptions,
|
|
922
982
|
connectTimeoutMs: options.connectTimeoutMs,
|
|
983
|
+
playoutLeadMs: options.playoutLeadMs,
|
|
923
984
|
speechGate: options.speechGate,
|
|
924
985
|
transcriptGapMs: options.transcriptGapMs
|
|
925
986
|
};
|
|
@@ -933,4 +994,4 @@ function gptLive(options = {}) {
|
|
|
933
994
|
};
|
|
934
995
|
}
|
|
935
996
|
//#endregion
|
|
936
|
-
export { DEFAULT_GATE_QUIET_MS, DEFAULT_GATE_THRESHOLD_RMS, GPT_LIVE_AUDIO_FORMAT, GPT_LIVE_DEFAULT_BACKEND_MODEL, GPT_LIVE_DEFAULT_BASE_URL, GPT_LIVE_DEFAULT_MODEL, GPT_LIVE_DEFAULT_VOICE, GPT_LIVE_KEY_ENV_VARS, GPT_LIVE_VOICES, GptLiveProvider, SpeechGate, buildDelegation, buildHistoryItems, buildSessionStart, gptLive, splitForAppend };
|
|
997
|
+
export { DEFAULT_GATE_QUIET_MS, DEFAULT_GATE_THRESHOLD_RMS, DEFAULT_PLAYOUT_LEAD_MS, GPT_LIVE_AUDIO_FORMAT, GPT_LIVE_DEFAULT_BACKEND_MODEL, GPT_LIVE_DEFAULT_BASE_URL, GPT_LIVE_DEFAULT_MODEL, GPT_LIVE_DEFAULT_VOICE, GPT_LIVE_KEY_ENV_VARS, GPT_LIVE_VOICES, GptLiveProvider, SpeechGate, buildDelegation, buildHistoryItems, buildSessionStart, gptLive, splitForAppend };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "realtime-voice-agents",
|
|
3
|
-
"version": "2.5.
|
|
3
|
+
"version": "2.5.2",
|
|
4
4
|
"description": "Provider-agnostic bridge between Twilio Media Streams and realtime speech-to-speech AI APIs (OpenAI Realtime, OpenAI GPT-Live full-duplex, xAI Grok Voice, Gemini Live). Multi-agent handoffs, Zod tools with execution strategies, mark-based playback tracking, interruption guards, and hold audio — for Node.js voice agents over the phone.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"twilio",
|