assemblyai 4.35.4 → 4.36.4

package/dist/streaming.browser.mjs

@@ -584,9 +584,12 @@ class StreamingTranscriber {
         if (!(this.token || this.apiKey)) {
             throw new Error("API key or temporary token is required.");
         }
-        const isOpus = params.encoding === "opus" || params.encoding === "ogg_opus";
-        if (params.sampleRate === undefined && (!isOpus || params.channels)) {
-            throw new Error('`sampleRate` is required; it may only be omitted when `encoding` is "opus" or "ogg_opus" (the Opus stream is self-describing) and dual-channel mode is not used.');
+        const isSelfDescribing = params.encoding === "opus" ||
+            params.encoding === "ogg_opus" ||
+            params.encoding === "aac";
+        if (params.sampleRate === undefined &&
+            (!isSelfDescribing || params.channels)) {
+            throw new Error('`sampleRate` is required; it may only be omitted when `encoding` is "opus", "ogg_opus", or "aac" (these streams are self-describing) and dual-channel mode is not used.');
         }
         if (params.channels) {
             if (params.channels.length !== 2) {
@@ -664,6 +667,9 @@ class StreamingTranscriber {
         if (this.params.formatTurns) {
             searchParams.set("format_turns", this.params.formatTurns.toString());
         }
+        if (this.params.sessionHeartbeat !== undefined) {
+            searchParams.set("session_heartbeat", this.params.sessionHeartbeat.toString());
+        }
         if (this.params.encoding) {
             searchParams.set("encoding", this.params.encoding.toString());
         }
@@ -952,6 +958,10 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c
                         this.listeners.warning?.(warning);
                         break;
                     }
+                    case "Heartbeat": {
+                        this.listeners.heartbeat?.(message);
+                        break;
+                    }
                     case "Termination": {
                         this.sessionTerminatedResolve?.();
                         break;
@@ -1312,7 +1322,7 @@ if (typeof navigator !== "undefined" && navigator.userAgent) {
     defaultUserAgentString += navigator.userAgent;
 }
 const defaultUserAgent = {
-    sdk: { name: "JavaScript", version: "4.35.4" },
+    sdk: { name: "JavaScript", version: "4.36.4" },
 };
 if (typeof process !== "undefined") {
     if (process.versions.node && defaultUserAgentString.indexOf("Node") === -1) {
@@ -1351,12 +1361,15 @@ class BaseService {
             this.userAgent = buildUserAgent(params.userAgent || {});
         }
     }
-    async fetch(input, init) {
+    async fetchResponse(input, init) {
         init = { ...DEFAULT_FETCH_INIT, ...init };
         let headers = {
             Authorization: this.params.apiKey,
-            "Content-Type": "application/json",
         };
+        // FormData bodies must let fetch set the multipart boundary itself.
+        if (!(init.body instanceof FormData)) {
+            headers["Content-Type"] = "application/json";
+        }
         if (DEFAULT_FETCH_INIT?.headers)
             headers = { ...headers, ...DEFAULT_FETCH_INIT.headers };
         if (init?.headers)
@@ -1366,15 +1379,17 @@ class BaseService {
             {
                 // chromium browsers have a bug where the user agent can't be modified
                 if (typeof window !== "undefined" && "chrome" in window) {
-                    headers["AssemblyAI-Agent"] =
-                        this.userAgent;
+                    headers["AssemblyAI-Agent"] = this.userAgent;
                 }
             }
         }
         init.headers = headers;
         if (!input.startsWith("http"))
             input = this.params.baseUrl + input;
-        const response = await fetch(input, init);
+        return await fetch(input, init);
+    }
+    async fetch(input, init) {
+        const response = await this.fetchResponse(input, init);
         if (response.status >= 400) {
             let json;
             const text = await response.text();

package/dist/streaming.cjs

@@ -630,9 +630,12 @@ class StreamingTranscriber {
         if (!(this.token || this.apiKey)) {
             throw new Error("API key or temporary token is required.");
         }
-        const isOpus = params.encoding === "opus" || params.encoding === "ogg_opus";
-        if (params.sampleRate === undefined && (!isOpus || params.channels)) {
-            throw new Error('`sampleRate` is required; it may only be omitted when `encoding` is "opus" or "ogg_opus" (the Opus stream is self-describing) and dual-channel mode is not used.');
+        const isSelfDescribing = params.encoding === "opus" ||
+            params.encoding === "ogg_opus" ||
+            params.encoding === "aac";
+        if (params.sampleRate === undefined &&
+            (!isSelfDescribing || params.channels)) {
+            throw new Error('`sampleRate` is required; it may only be omitted when `encoding` is "opus", "ogg_opus", or "aac" (these streams are self-describing) and dual-channel mode is not used.');
         }
         if (params.channels) {
             if (params.channels.length !== 2) {
@@ -710,6 +713,9 @@ class StreamingTranscriber {
         if (this.params.formatTurns) {
             searchParams.set("format_turns", this.params.formatTurns.toString());
         }
+        if (this.params.sessionHeartbeat !== undefined) {
+            searchParams.set("session_heartbeat", this.params.sessionHeartbeat.toString());
+        }
         if (this.params.encoding) {
             searchParams.set("encoding", this.params.encoding.toString());
         }
@@ -941,7 +947,7 @@ class StreamingTranscriber {
                 (_c = (_b = this.listeners).error) === null || _c === void 0 ? void 0 : _c.call(_b, error);
             };
             this.socket.onmessage = ({ data }) => {
-                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
                 const message = JSON.parse(data.toString());
                 if ("error" in message) {
                     const err = new StreamingError(message.error);
@@ -1001,8 +1007,12 @@ class StreamingTranscriber {
                         (_p = (_o = this.listeners).warning) === null || _p === void 0 ? void 0 : _p.call(_o, warning);
                         break;
                     }
+                    case "Heartbeat": {
+                        (_r = (_q = this.listeners).heartbeat) === null || _r === void 0 ? void 0 : _r.call(_q, message);
+                        break;
+                    }
                     case "Termination": {
-                        (_q = this.sessionTerminatedResolve) === null || _q === void 0 ? void 0 : _q.call(this);
+                        (_s = this.sessionTerminatedResolve) === null || _s === void 0 ? void 0 : _s.call(this);
                         break;
                     }
                 }
@@ -1403,13 +1413,16 @@ class BaseService {
             this.userAgent = buildUserAgent(params.userAgent || {});
         }
     }
-    fetch(input, init) {
+    fetchResponse(input, init) {
         return __awaiter(this, void 0, void 0, function* () {
             init = Object.assign(Object.assign({}, DEFAULT_FETCH_INIT), init);
             let headers = {
                 Authorization: this.params.apiKey,
-                "Content-Type": "application/json",
             };
+            // FormData bodies must let fetch set the multipart boundary itself.
+            if (!(init.body instanceof FormData)) {
+                headers["Content-Type"] = "application/json";
+            }
             if (DEFAULT_FETCH_INIT === null || DEFAULT_FETCH_INIT === void 0 ? void 0 : DEFAULT_FETCH_INIT.headers)
                 headers = Object.assign(Object.assign({}, headers), DEFAULT_FETCH_INIT.headers);
             if (init === null || init === void 0 ? void 0 : init.headers)
@@ -1419,15 +1432,19 @@ class BaseService {
                 {
                     // chromium browsers have a bug where the user agent can't be modified
                     if (typeof window !== "undefined" && "chrome" in window) {
-                        headers["AssemblyAI-Agent"] =
-                            this.userAgent;
+                        headers["AssemblyAI-Agent"] = this.userAgent;
                     }
                 }
             }
             init.headers = headers;
             if (!input.startsWith("http"))
                 input = this.params.baseUrl + input;
-            const response = yield fetch(input, init);
+            return yield fetch(input, init);
+        });
+    }
+    fetch(input, init) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.fetchResponse(input, init);
             if (response.status >= 400) {
                 let json;
                 const text = yield response.text();

package/dist/streaming.mjs

@@ -628,9 +628,12 @@ class StreamingTranscriber {
         if (!(this.token || this.apiKey)) {
             throw new Error("API key or temporary token is required.");
         }
-        const isOpus = params.encoding === "opus" || params.encoding === "ogg_opus";
-        if (params.sampleRate === undefined && (!isOpus || params.channels)) {
-            throw new Error('`sampleRate` is required; it may only be omitted when `encoding` is "opus" or "ogg_opus" (the Opus stream is self-describing) and dual-channel mode is not used.');
+        const isSelfDescribing = params.encoding === "opus" ||
+            params.encoding === "ogg_opus" ||
+            params.encoding === "aac";
+        if (params.sampleRate === undefined &&
+            (!isSelfDescribing || params.channels)) {
+            throw new Error('`sampleRate` is required; it may only be omitted when `encoding` is "opus", "ogg_opus", or "aac" (these streams are self-describing) and dual-channel mode is not used.');
         }
         if (params.channels) {
             if (params.channels.length !== 2) {
@@ -708,6 +711,9 @@ class StreamingTranscriber {
         if (this.params.formatTurns) {
             searchParams.set("format_turns", this.params.formatTurns.toString());
         }
+        if (this.params.sessionHeartbeat !== undefined) {
+            searchParams.set("session_heartbeat", this.params.sessionHeartbeat.toString());
+        }
         if (this.params.encoding) {
             searchParams.set("encoding", this.params.encoding.toString());
         }
@@ -939,7 +945,7 @@ class StreamingTranscriber {
                 (_c = (_b = this.listeners).error) === null || _c === void 0 ? void 0 : _c.call(_b, error);
             };
             this.socket.onmessage = ({ data }) => {
-                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
                 const message = JSON.parse(data.toString());
                 if ("error" in message) {
                     const err = new StreamingError(message.error);
@@ -999,8 +1005,12 @@ class StreamingTranscriber {
                         (_p = (_o = this.listeners).warning) === null || _p === void 0 ? void 0 : _p.call(_o, warning);
                         break;
                     }
+                    case "Heartbeat": {
+                        (_r = (_q = this.listeners).heartbeat) === null || _r === void 0 ? void 0 : _r.call(_q, message);
+                        break;
+                    }
                     case "Termination": {
-                        (_q = this.sessionTerminatedResolve) === null || _q === void 0 ? void 0 : _q.call(this);
+                        (_s = this.sessionTerminatedResolve) === null || _s === void 0 ? void 0 : _s.call(this);
                         break;
                     }
                 }
@@ -1401,13 +1411,16 @@ class BaseService {
             this.userAgent = buildUserAgent(params.userAgent || {});
         }
     }
-    fetch(input, init) {
+    fetchResponse(input, init) {
         return __awaiter(this, void 0, void 0, function* () {
             init = Object.assign(Object.assign({}, DEFAULT_FETCH_INIT), init);
             let headers = {
                 Authorization: this.params.apiKey,
-                "Content-Type": "application/json",
             };
+            // FormData bodies must let fetch set the multipart boundary itself.
+            if (!(init.body instanceof FormData)) {
+                headers["Content-Type"] = "application/json";
+            }
             if (DEFAULT_FETCH_INIT === null || DEFAULT_FETCH_INIT === void 0 ? void 0 : DEFAULT_FETCH_INIT.headers)
                 headers = Object.assign(Object.assign({}, headers), DEFAULT_FETCH_INIT.headers);
             if (init === null || init === void 0 ? void 0 : init.headers)
@@ -1417,15 +1430,19 @@ class BaseService {
                 {
                     // chromium browsers have a bug where the user agent can't be modified
                     if (typeof window !== "undefined" && "chrome" in window) {
-                        headers["AssemblyAI-Agent"] =
-                            this.userAgent;
+                        headers["AssemblyAI-Agent"] = this.userAgent;
                     }
                 }
             }
             init.headers = headers;
             if (!input.startsWith("http"))
                 input = this.params.baseUrl + input;
-            const response = yield fetch(input, init);
+            return yield fetch(input, init);
+        });
+    }
+    fetch(input, init) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.fetchResponse(input, init);
             if (response.status >= 400) {
                 let json;
                 const text = yield response.text();

package/dist/types/asyncapi.generated.d.ts

@@ -6,7 +6,7 @@ export type AudioData = ArrayBufferLike;
  * The encoding of the audio data
  * @defaultValue "pcm_s16"le
  */
-export type AudioEncoding = "pcm_s16le" | "pcm_mulaw" | "opus" | "ogg_opus";
+export type AudioEncoding = "pcm_s16le" | "pcm_mulaw" | "opus" | "ogg_opus" | "aac";
 /**
  * Configure the threshold for how long to wait before ending an utterance. Default is 700ms.
  */

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./sync";
 export * from "./files";
 export * from "./transcripts";
 export * from "./realtime";

package/dist/types/services/index.d.ts

@@ -3,6 +3,7 @@ type BaseServiceParams = {
     apiKey: string;
     baseUrl?: string;
     streamingBaseUrl?: string;
+    syncBaseUrl?: string;
     /**
      * The AssemblyAI user agent to use for requests.
      * The provided components will be merged into the default AssemblyAI user agent.

package/dist/types/streaming/index.d.ts

@@ -89,8 +89,8 @@ export type StreamingTranscriberParams = {
     connectionRetryDelay?: number;
     /**
      * Required for PCM encodings (and for dual-channel mode). May be omitted
-     * for Opus encodings (`opus`, `ogg_opus`) — the stream is self-describing
-     * and the server ignores the value.
+     * for self-describing encodings (`opus`, `ogg_opus`, `aac`) — the stream
+     * carries its own rate and the server ignores the value.
      */
     sampleRate?: number;
     encoding?: AudioEncoding;
@@ -103,6 +103,7 @@ export type StreamingTranscriberParams = {
     maxTurnSilence?: number;
     vadThreshold?: number;
     formatTurns?: boolean;
+    sessionHeartbeat?: boolean;
     filterProfanity?: boolean;
     keyterms?: string[];
     keytermsPrompt?: string[];
@@ -172,7 +173,7 @@ export type StreamingTranscriberParams = {
     /** Tuning for dual-channel attribution. Ignored when `channels` is unset. */
     channelAttribution?: ChannelAttributionParams;
 };
-export type StreamingEvents = "open" | "close" | "turn" | "speechStarted" | "llmGatewayResponse" | "speakerRevision" | "warning" | "vad" | "error";
+export type StreamingEvents = "open" | "close" | "turn" | "speechStarted" | "llmGatewayResponse" | "speakerRevision" | "warning" | "heartbeat" | "vad" | "error";
 export type StreamingListeners = {
     open?: (event: BeginEvent) => void;
     close?: (code: number, reason: string) => void;
@@ -181,6 +182,7 @@ export type StreamingListeners = {
     llmGatewayResponse?: (event: LLMGatewayResponseEvent) => void;
     speakerRevision?: (event: SpeakerRevisionEvent) => void;
     warning?: (event: WarningEvent) => void;
+    heartbeat?: (event: HeartbeatEvent) => void;
     vad?: (event: VadFrame) => void;
     error?: (error: Error) => void;
 };
@@ -266,6 +268,7 @@ export type StreamingUpdateConfiguration = {
     max_turn_silence?: number;
     vad_threshold?: number;
     format_turns?: boolean;
+    session_heartbeat?: boolean;
     keyterms_prompt?: string[];
     prompt?: string;
     agent_context?: string;
@@ -295,6 +298,13 @@ export type WarningEvent = {
     warning_code: number;
     warning: string;
 };
+export type HeartbeatEvent = {
+    type: "Heartbeat";
+    total_audio_received_ms: number;
+    total_duration_ms: number;
+    realtime_factor: number;
+    max_speech_probability: number;
+};
 export type LLMGatewayResponseEvent = {
     type: "LLMGatewayResponse";
     turn_order: number;
@@ -323,5 +333,5 @@ export type SpeakerRevisionEvent = {
     type: "SpeakerRevision";
     revisions: SpeakerRevisionItem[];
 };
-export type StreamingEventMessage = BeginEvent | TurnEvent | SpeechStartedEvent | TerminationEvent | LLMGatewayResponseEvent | SpeakerRevisionEvent | ErrorEvent | WarningEvent;
+export type StreamingEventMessage = BeginEvent | TurnEvent | SpeechStartedEvent | TerminationEvent | LLMGatewayResponseEvent | SpeakerRevisionEvent | ErrorEvent | WarningEvent | HeartbeatEvent;
 export type StreamingOperationMessage = StreamingUpdateConfiguration | StreamingForceEndpoint | StreamingKeepAlive | StreamingTerminateSession;

package/dist/types/sync/index.d.ts

@@ -0,0 +1,133 @@
+/// <reference types="node" />
+import { LiteralUnion } from "../helpers";
+/**
+ * The speech models available on the synchronous transcription API.
+ */
+export type SyncSpeechModel = LiteralUnion<"universal-3-5-pro", string>;
+/**
+ * The default speech model for synchronous transcription.
+ */
+export declare const defaultSyncSpeechModel: SyncSpeechModel;
+/**
+ * Audio input for synchronous transcription: a local file path or
+ * data URL (file system access requires Node.js, Bun, or Deno), raw audio
+ * bytes, a Blob/File, or a readable stream.
+ *
+ * URLs are not accepted — the sync API has no URL ingestion; use
+ * `client.transcripts` for URL or asynchronous transcription.
+ */
+export type SyncAudioInput = string | Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array> | NodeJS.ReadableStream;
+/**
+ * Options for a synchronous transcription request.
+ *
+ * `sample_rate` and `channels` are required only for raw PCM audio — WAV
+ * carries them in its header. `model` is sent as the `X-AAI-Model` routing
+ * header and is never included in the request body.
+ */
+export type SyncTranscriptionConfig = {
+    /**
+     * The sync speech model to route to, sent as the `X-AAI-Model` header.
+     * Defaults to `"universal-3-5-pro"`.
+     */
+    model?: SyncSpeechModel;
+    /**
+     * Custom transcription instruction. Maximum 4096 characters — longer
+     * prompts are rejected.
+     */
+    prompt?: string;
+    /**
+     * Terms to bias the decoder towards. Whitespace is stripped and empty
+     * terms are dropped. Maximum 2048 characters in total — longer lists are
+     * rejected.
+     */
+    keyterms_prompt?: string[];
+    /**
+     * Prior turns from the same conversation, oldest first, most recent last.
+     * A single string is treated as one turn. Capped at 100 turns and 4096
+     * characters in total — over-cap context is trimmed (oldest turns dropped
+     * first), not rejected.
+     */
+    conversation_context?: string | string[];
+    /**
+     * ISO 639-1 codes for the language(s) of the audio — a single-element
+     * array (e.g. `["es"]`) for monolingual audio, or several codes (e.g.
+     * `["en", "es"]`) for multilingual audio. Ignored when `prompt` is set.
+     * Defaults to English.
+     */
+    language_codes?: string[];
+    /**
+     * The source sample rate in Hz. Required for raw PCM audio; ignored for
+     * WAV.
+     */
+    sample_rate?: number;
+    /**
+     * The channel count (1 for mono, 2 for stereo). Required for raw PCM
+     * audio; ignored for WAV.
+     */
+    channels?: number;
+    /**
+     * Whether to compute per-word `start`/`end` timestamps. When `true`,
+     * words carry accurate timestamps at a small latency cost. Defaults to
+     * `false`: no timestamps are returned.
+     */
+    timestamps?: boolean;
+};
+/**
+ * Client-side options for a synchronous transcription request.
+ * These are not sent to the server.
+ */
+export type SyncTranscribeOptions = {
+    /**
+     * The request timeout in milliseconds. Defaults to 60 000, which is kept
+     * above the server's 30 s deadline so the client doesn't race it.
+     */
+    timeout?: number;
+};
+/**
+ * A single word in a sync transcript.
+ *
+ * `start`/`end` are in milliseconds and present only when the request set
+ * `timestamps: true`; otherwise they are omitted.
+ */
+export type SyncWord = {
+    /** The text of the word. */
+    text: string;
+    /**
+     * The start time of the word in milliseconds. Absent unless `timestamps`
+     * was requested.
+     */
+    start?: number;
+    /**
+     * The end time of the word in milliseconds. Absent unless `timestamps`
+     * was requested.
+     */
+    end?: number;
+    /** The confidence score of the word, in the range 0-1. */
+    confidence: number;
+};
+/**
+ * The result of a synchronous transcription request.
+ */
+export type SyncTranscriptResponse = {
+    /** The full transcript text. */
+    text: string;
+    /**
+     * Per-word confidence, plus `start`/`end` timings when the request set
+     * `timestamps: true`.
+     */
+    words: SyncWord[];
+    /** The overall transcript confidence, in the range 0-1. */
+    confidence: number;
+    /** The total audio duration in milliseconds. */
+    audio_duration_ms: number;
+    /**
+     * The server-generated UUID for this request. Record it to correlate a
+     * request with support.
+     */
+    session_id: string;
+    /**
+     * The end-to-end server-side request time in milliseconds. `undefined`
+     * when the server predates the field.
+     */
+    request_time_ms?: number;
+};

package/dist/utils/errors/index.d.ts

@@ -1,2 +1,3 @@
+export { SyncTranscriptError } from "./sync";
 export { RealtimeError, RealtimeErrorType, RealtimeErrorMessages, } from "./realtime";
 export { StreamingError, StreamingErrorType, StreamingErrorMessages, } from "./streaming";

package/dist/utils/errors/sync.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Error thrown when a synchronous transcription request fails.
+ */
+export declare class SyncTranscriptError extends Error {
+    readonly status?: number | undefined;
+    readonly errorCode?: string | undefined;
+    readonly retryAfter?: number | undefined;
+    name: string;
+    /**
+     * Create a new SyncTranscriptError.
+     * @param message - The human-readable error message.
+     * @param status - The HTTP status code of the failed request.
+     * @param errorCode - Machine-readable code — the snake_cased
+     * problem-details `title` from the server (e.g. `bad_audio`,
+     * `audio_too_large`, `capacity_exceeded`, `inference_timeout`).
+     * @param retryAfter - Seconds to wait before retrying, from the
+     * `Retry-After` header on 429/503 responses.
+     */
+    constructor(message: string, status?: number | undefined, errorCode?: string | undefined, retryAfter?: number | undefined);
+}