From 093aea0fd571d7271d19ff1fd8d7dedc3c5ca31e Mon Sep 17 00:00:00 2001 From: Carter Campbell Date: Mon, 16 Nov 2026 17:50:01 -0700 Subject: [PATCH] Emit streaming termination and resolve close() with it StreamingTranscriber emits a "termination" event with the server's Termination message, close() resolves with it (undefined when it did not wait or the frame did not arrive), and close() calls the close listener once for a client-initiated close before clearing listeners. Bumps to 4.43.3. Fixes #212 Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 4 ++ package.json | 2 +- src/services/streaming/service.ts | 66 ++++++++++++----- src/types/streaming/index.ts | 2 + tests/unit/streaming-close.test.ts | 112 +++++++++++++++++++++++++++++ 5 files changed, 168 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 61a2242..4bbe92c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog +## [4.43.3] + +- `StreamingTranscriber` emits a `termination` event with the server's `Termination` message (`TerminationEvent`: `audio_duration_seconds`, `session_duration_seconds`), and `close()` resolves with it, or with `undefined` when it did not wait for the message or the message did not arrive before the timeout or the socket closed. `close()` now calls the `close` listener for a client-initiated close (code `1000`, reason `"Session ended"` or `"Closed by the client"`) before it clears the listeners; it is called once per session. Code that types `close()`'s result as `Promise` must widen it to `Promise` + ## [4.43.1] - `client.tts.synthesize()` and `client.tts.stream()` send the camelCase names `voiceId`, `modelId`, `sampleRate`, `bitRate` and `extendBiometricConsent`, which plain JavaScript can pass, as their snake_case request fields (`voice_id`, ...) and warn once. The API ignored them before, so such a request got the default voice, model or sample rate. These values now reach the API, so a value it refuses (a `sampleRate` outside the supported set, `bitRate` without the `mp3` encoding, `extendBiometricConsent` on a voice the account does not own) fails with the same `TextToSpeechError` as its snake_case spelling, where before the request used the default. When a request gives both names of a field with different values, the snake_case value is sent, with a warning once. A `TextToSpeechSession` warns once on the snake_case names it ignores (`voice_id`, `model_id`, `sample_rate`, `extend_biometric_consent`, `word_boundaries`, `inactivity_timeout`) diff --git a/package.json b/package.json index e9d9913..4d8c9b2 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "assemblyai", - "version": "4.43.1", + "version": "4.43.3", "description": "The AssemblyAI JavaScript SDK provides an easy-to-use interface for interacting with the AssemblyAI API, which supports async and real-time transcription and text-to-speech.", "engines": { "node": ">=18" diff --git a/src/services/streaming/service.ts b/src/services/streaming/service.ts index 60ff025..b2d6f46 100644 --- a/src/services/streaming/service.ts +++ b/src/services/streaming/service.ts @@ -22,6 +22,7 @@ import { WarningEvent, HeartbeatEvent, SilenceEvent, + TerminationEvent, } from "../.."; import type { VadDetector, VadFrame } from "../../types/streaming/dual-channel"; import { EnergyVad } from "./energy-vad"; @@ -140,7 +141,9 @@ export class StreamingTranscriber { private socket?: PolyfillWebSocket; private listeners: StreamingListeners = {}; - private sessionTerminatedResolve?: () => void; + private sessionTerminatedResolve?: (event?: TerminationEvent) => void; + /** True from `Begin` until the `close` listener has been called. */ + private closePending = false; // Dual-channel mode state (allocated only when params.channels is set). private isDualChannel = false; @@ -243,16 +246,24 @@ export class StreamingTranscriber { } /** - * Releases a `close()` that is waiting for the session to terminate. + * Releases a `close()` that is waiting for the session to terminate, with + * the `Termination` frame when there is one. * * Called from the `Termination` frame and from `onclose`. Without the * `onclose` call, a socket that dies without a `Termination` frame leaves * `close()` awaiting forever. */ - private resolveSessionTermination(): void { + private resolveSessionTermination(event?: TerminationEvent): void { const resolve = this.sessionTerminatedResolve; this.sessionTerminatedResolve = undefined; - resolve?.(); + resolve?.(event); + } + + /** Calls the `close` listener once per opened session. */ + private emitClose(code: number, reason: string): void { + if (!this.closePending) return; + this.closePending = false; + this.listeners.close?.(code, reason); } private connectionUrl(): URL { @@ -527,6 +538,7 @@ export class StreamingTranscriber { on(event: "heartbeat", listener: (event: HeartbeatEvent) => void): void; on(event: "silence", listener: (event: SilenceEvent) => void): void; on(event: "vad", listener: (event: VadFrame) => void): void; + on(event: "termination", listener: (event: TerminationEvent) => void): void; on(event: "error", listener: (error: Error) => void): void; on(event: "close", listener: (code: number, reason: string) => void): void; // eslint-disable-next-line @typescript-eslint/no-explicit-any @@ -606,6 +618,7 @@ export class StreamingTranscriber { if (settled) return; settled = true; if (timer) clearTimeout(timer); + this.closePending = true; resolve(begin); }; @@ -665,7 +678,7 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c // The socket is gone, so no `Termination` frame is coming. Release a // `close()` that is waiting for one. this.resolveSessionTermination(); - this.listeners.close?.(code, reason); + this.emitClose(code, reason); }; this.socket.onerror = (event: ErrorEvent) => { @@ -757,7 +770,8 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c break; } case "Termination": { - this.resolveSessionTermination(); + this.listeners.termination?.(message); + this.resolveSessionTermination(message); break; } } @@ -1077,22 +1091,25 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c this.send(JSON.stringify(message)); } - /** Awaits the session-termination frame, bounded by `timeoutMs`. */ + /** + * Awaits the session-termination frame, bounded by `timeoutMs`. Resolves + * with the frame, or `undefined` when the timeout or a socket close comes + * first. + */ private async waitForTermination( - sessionTerminated: Promise, + sessionTerminated: Promise, timeoutMs: number, - ): Promise { + ): Promise { if (timeoutMs <= 0) { - await sessionTerminated; - return; + return sessionTerminated; } let timer: ReturnType | undefined; try { - await Promise.race([ + return await Promise.race([ sessionTerminated, - new Promise((resolve) => { - timer = setTimeout(resolve, timeoutMs); + new Promise((resolve) => { + timer = setTimeout(() => resolve(undefined), timeoutMs); }), ]); } finally { @@ -1115,11 +1132,17 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c * transcript and the session information. * @param terminationTimeout - How long to wait for that frame, in * milliseconds. `0` waits indefinitely. The socket closes either way. + * @returns The `Termination` frame (`audio_duration_seconds`, + * `session_duration_seconds`), or `undefined` when `close()` did not wait + * for it or it did not arrive before the timeout or the socket closed. + * The `close` listener is called before this resolves, unless the session + * never opened or the socket had already closed and reported it. */ async close( waitForSessionTermination = true, terminationTimeout = DEFAULT_TERMINATION_TIMEOUT_MS, - ) { + ): Promise { + let termination: TerminationEvent | undefined; if (this.flushTimer) { clearInterval(this.flushTimer); this.flushTimer = undefined; @@ -1132,11 +1155,13 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c if (this.socket) { if (this.socket.readyState === this.socket.OPEN) { if (waitForSessionTermination) { - const sessionTerminatedPromise = new Promise((resolve) => { + const sessionTerminatedPromise = new Promise< + TerminationEvent | undefined + >((resolve) => { this.sessionTerminatedResolve = resolve; }); this.socket.send(terminateSessionMessage); - await this.waitForTermination( + termination = await this.waitForTermination( sessionTerminatedPromise, terminationTimeout, ); @@ -1152,9 +1177,16 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c this.socket.onerror = () => {}; } this.socket.close(); + // The socket's own close event is detached above, so report the + // client-initiated close here, before the listeners are cleared. + this.emitClose( + 1000, + termination ? "Session ended" : "Closed by the client", + ); } this.listeners = {}; this.socket = undefined; + return termination; } } diff --git a/src/types/streaming/index.ts b/src/types/streaming/index.ts index ef8fc55..3b3e53d 100644 --- a/src/types/streaming/index.ts +++ b/src/types/streaming/index.ts @@ -207,6 +207,7 @@ export type StreamingEvents = | "heartbeat" | "silence" | "vad" + | "termination" | "error"; export type StreamingListeners = { @@ -220,6 +221,7 @@ export type StreamingListeners = { heartbeat?: (event: HeartbeatEvent) => void; silence?: (event: SilenceEvent) => void; vad?: (event: VadFrame) => void; + termination?: (event: TerminationEvent) => void; error?: (error: Error) => void; }; diff --git a/tests/unit/streaming-close.test.ts b/tests/unit/streaming-close.test.ts index 3ebe659..48c349f 100644 --- a/tests/unit/streaming-close.test.ts +++ b/tests/unit/streaming-close.test.ts @@ -86,4 +86,116 @@ describe("streaming close", () => { await expect(rt.close()).resolves.toBeUndefined(); }); + + describe("termination and close events", () => { + const termination = { + type: "Termination", + audio_duration_seconds: 12, + session_duration_seconds: 14, + }; + + it("emits termination and resolves close() with the frame", async () => { + const onTermination = jest.fn(); + const onClose = jest.fn(); + rt.on("termination", onTermination); + rt.on("close", onClose); + + const closePromise = rt.close(); + await expect(server).toReceiveMessage( + JSON.stringify({ type: "Terminate" }), + ); + server.send(JSON.stringify(termination)); + + await expect(closePromise).resolves.toEqual(termination); + expect(onTermination).toHaveBeenCalledTimes(1); + expect(onTermination).toHaveBeenCalledWith(termination); + expect(onClose).toHaveBeenCalledTimes(1); + expect(onClose).toHaveBeenCalledWith(1000, "Session ended"); + // The termination listener runs before close() resolves, and close + // after it. + expect(onTermination.mock.invocationCallOrder[0]).toBeLessThan( + onClose.mock.invocationCallOrder[0], + ); + }); + + it("emits termination for a frame the server sends unprompted", async () => { + const onTermination = jest.fn(); + rt.on("termination", onTermination); + + server.send(JSON.stringify(termination)); + await new Promise((resolve) => setTimeout(resolve, 20)); + + expect(onTermination).toHaveBeenCalledWith(termination); + await rt.close(false); + }); + + it("calls close once when close() does not wait", async () => { + const onClose = jest.fn(); + rt.on("close", onClose); + + await expect(rt.close(false)).resolves.toBeUndefined(); + expect(onClose).toHaveBeenCalledTimes(1); + expect(onClose).toHaveBeenCalledWith(1000, "Closed by the client"); + }); + + it("calls close once and resolves undefined on timeout", async () => { + const onClose = jest.fn(); + rt.on("close", onClose); + + await expect(rt.close(true, 50)).resolves.toBeUndefined(); + expect(onClose).toHaveBeenCalledTimes(1); + expect(onClose).toHaveBeenCalledWith(1000, "Closed by the client"); + }); + + it("calls close once with the server's code when the server closes first", async () => { + const onClose = jest.fn(); + rt.on("close", onClose); + + const closePromise = rt.close(); + server.close({ code: 1000, reason: "bye", wasClean: true }); + + await expect(closePromise).resolves.toBeUndefined(); + expect(onClose).toHaveBeenCalledTimes(1); + expect(onClose).toHaveBeenCalledWith(1000, "bye"); + }); + + it("does not call close again after a server-initiated close", async () => { + const onClose = jest.fn(); + rt.on("close", onClose); + + server.close({ code: 4031, reason: "idle", wasClean: false }); + await new Promise((resolve) => setTimeout(resolve, 20)); + await rt.close(); + + expect(onClose).toHaveBeenCalledTimes(1); + expect(onClose).toHaveBeenCalledWith(4031, "idle"); + }); + + it("clears the listeners once closed", async () => { + const onClose = jest.fn(); + rt.on("close", onClose); + await rt.close(false); + + expect( + (rt as unknown as { listeners: Record }).listeners, + ).toEqual({}); + // A second close() has no session to report. + await rt.close(false); + expect(onClose).toHaveBeenCalledTimes(1); + }); + + it("does not call close for a session that never opened", async () => { + const unopened = aai.streaming.transcriber({ + websocketBaseUrl, + apiKey: "123", + sampleRate: 16_000, + }); + const onClose = jest.fn(); + unopened.on("close", onClose); + + await expect(unopened.close()).resolves.toBeUndefined(); + expect(onClose).not.toHaveBeenCalled(); + await rt.close(false); + }); + }); });