@cartesia/cartesia-js 2.2.5 → 2.2.8

package/wrapper/StreamingSTTClient.js

@@ -1,4 +1,33 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -10,8 +39,102 @@ class StreamingSTTClient extends Client_1.Stt {
     constructor(options = {}) {
         super(options);
     }
-    websocket(options = {}) {
+    /**
+     * Create a WebSocket connection for real-time speech transcription.
+     *
+     * @param options - Configuration options for the STT WebSocket
+     * @param options.model - ID of the model to use for transcription (required)
+     * @param options.language - The language of the input audio in ISO-639-1 format (defaults to "en")
+     * @param options.encoding - The encoding format of the audio data (required). Must be one of: "pcm_s16le", "pcm_s32le", "pcm_f16le", "pcm_f32le", "pcm_mulaw", "pcm_alaw"
+     * @param options.sampleRate - The sample rate of the audio in Hz (required)
+     * @param options.minVolume - Volume threshold for voice activity detection (0.0-1.0)
+     * @param options.maxSilenceDurationSecs - Maximum duration of silence before endpointing
+     * @returns SttWebsocket instance for STT operations
+     */
+    websocket(options) {
         return new SttWebsocket_1.default(options, Object.assign({ cartesiaVersion: "2024-06-10" }, this._options));
     }
+    /**
+     * Transcribe audio chunks using WebSocket with automatic connection management.
+     *
+     * @param audioChunks - Iterator of audio chunks as ArrayBuffer
+     * @param options - Configuration options for the STT WebSocket
+     * @returns AsyncGenerator yielding transcription results
+     */
+    transcribeChunks(audioChunks, options) {
+        return __asyncGenerator(this, arguments, function* transcribeChunks_1() {
+            const ws = this.websocket(options);
+            try {
+                // Set up message handling
+                const resultQueue = [];
+                let isComplete = false;
+                let error = null;
+                yield __await(ws.onMessage((result) => {
+                    if (result.type === "error") {
+                        error = new Error(result.message || "STT error occurred");
+                    }
+                    else if (result.type === "done") {
+                        isComplete = true;
+                    }
+                    resultQueue.push(result);
+                }));
+                // Send audio chunks
+                const sendAudio = () => __awaiter(this, void 0, void 0, function* () {
+                    var _a, e_1, _b, _c;
+                    try {
+                        try {
+                            for (var _d = true, audioChunks_1 = __asyncValues(audioChunks), audioChunks_1_1; audioChunks_1_1 = yield audioChunks_1.next(), _a = audioChunks_1_1.done, !_a; _d = true) {
+                                _c = audioChunks_1_1.value;
+                                _d = false;
+                                const chunk = _c;
+                                yield ws.send(chunk);
+                            }
+                        }
+                        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                        finally {
+                            try {
+                                if (!_d && !_a && (_b = audioChunks_1.return)) yield _b.call(audioChunks_1);
+                            }
+                            finally { if (e_1) throw e_1.error; }
+                        }
+                        // Finalize and close session
+                        yield ws.finalize();
+                        yield ws.done();
+                    }
+                    catch (e) {
+                        error = e instanceof Error ? e : new Error(String(e));
+                    }
+                });
+                // Start sending audio in background
+                const sendPromise = sendAudio();
+                // Yield results as they come in
+                while (!isComplete && !error) {
+                    if (resultQueue.length > 0) {
+                        const result = resultQueue.shift();
+                        yield yield __await(result);
+                        if (result.type === "done") {
+                            break;
+                        }
+                    }
+                    else {
+                        // Small delay to avoid busy waiting
+                        yield __await(new Promise(resolve => setTimeout(resolve, 10)));
+                    }
+                }
+                // Wait for sending to complete and handle any errors
+                yield __await(sendPromise);
+                if (error) {
+                    throw error;
+                }
+                // Yield any remaining results
+                while (resultQueue.length > 0) {
+                    yield yield __await(resultQueue.shift());
+                }
+            }
+            finally {
+                ws.disconnect();
+            }
+        });
+    }
 }
 exports.StreamingSTTClient = StreamingSTTClient;

package/wrapper/SttWebsocket.d.ts

@@ -1,10 +1,14 @@
 import { ReconnectingWebSocket, Options } from "../core/websocket";
 import { Stt } from "../api/resources/stt/client/Client";
+import * as Cartesia from "../api/index";
+import { SttEncoding } from "../api/resources/stt/types/SttEncoding";
 export interface SttWebSocketOptions {
     model?: string;
     language?: string;
-    encoding?: string;
-    sampleRate?: number;
+    encoding: SttEncoding;
+    sampleRate: number;
+    minVolume?: number;
+    maxSilenceDurationSecs?: number;
 }
 export interface TranscriptionResult {
     type: "transcript" | "flush_done" | "done" | "error";
@@ -13,13 +17,14 @@ export interface TranscriptionResult {
     isFinal?: boolean;
     duration?: number;
     language?: string;
+    words?: Cartesia.TranscriptionWord[];
     message?: string;
 }
 export default class SttWebsocket {
     #private;
     private readonly options;
     socket?: ReconnectingWebSocket;
-    constructor({ model, language, encoding, sampleRate, }: SttWebSocketOptions, options: Stt.Options);
+    constructor({ model, language, encoding, sampleRate, minVolume, maxSilenceDurationSecs, }: SttWebSocketOptions, options: Stt.Options);
     send(audioData: ArrayBuffer): Promise<void>;
     finalize(): Promise<void>;
     done(): Promise<void>;

package/wrapper/SttWebsocket.js

@@ -52,13 +52,13 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _SttWebsocket_instances, _SttWebsocket_isConnected, _SttWebsocket_model, _SttWebsocket_language, _SttWebsocket_encoding, _SttWebsocket_sampleRate, _SttWebsocket_connectionPromise, _SttWebsocket_ensureConnected;
+var _SttWebsocket_instances, _SttWebsocket_isConnected, _SttWebsocket_model, _SttWebsocket_language, _SttWebsocket_encoding, _SttWebsocket_sampleRate, _SttWebsocket_minVolume, _SttWebsocket_maxSilenceDurationSecs, _SttWebsocket_connectionPromise, _SttWebsocket_ensureConnected;
 Object.defineProperty(exports, "__esModule", { value: true });
 const core = __importStar(require("../core"));
 const environments = __importStar(require("../environments"));
 const websocket_1 = require("../core/websocket");
 class SttWebsocket {
-    constructor({ model = "ink-whisper", language = "en", encoding = "pcm_s16le", sampleRate = 16000, }, options) {
+    constructor({ model = "ink-whisper", language = "en", encoding, sampleRate, minVolume, maxSilenceDurationSecs, }, options) {
         _SttWebsocket_instances.add(this);
         this.options = options;
         _SttWebsocket_isConnected.set(this, false);
@@ -66,11 +66,24 @@ class SttWebsocket {
         _SttWebsocket_language.set(this, void 0);
         _SttWebsocket_encoding.set(this, void 0);
         _SttWebsocket_sampleRate.set(this, void 0);
+        _SttWebsocket_minVolume.set(this, void 0);
+        _SttWebsocket_maxSilenceDurationSecs.set(this, void 0);
         _SttWebsocket_connectionPromise.set(this, void 0);
+        if (!model) {
+            throw new Error("model parameter is required");
+        }
+        if (!encoding) {
+            throw new Error("encoding parameter is required");
+        }
+        if (!sampleRate) {
+            throw new Error("sampleRate parameter is required");
+        }
         __classPrivateFieldSet(this, _SttWebsocket_model, model, "f");
         __classPrivateFieldSet(this, _SttWebsocket_language, language, "f");
         __classPrivateFieldSet(this, _SttWebsocket_encoding, encoding, "f");
         __classPrivateFieldSet(this, _SttWebsocket_sampleRate, sampleRate, "f");
+        __classPrivateFieldSet(this, _SttWebsocket_minVolume, minVolume, "f");
+        __classPrivateFieldSet(this, _SttWebsocket_maxSilenceDurationSecs, maxSilenceDurationSecs, "f");
     }
     send(audioData) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -112,6 +125,10 @@ class SttWebsocket {
                         result.isFinal = data.is_final || false;
                         result.duration = data.duration;
                         result.language = data.language;
+                        // Include word-level timestamps if available
+                        if (data.words) {
+                            result.words = data.words;
+                        }
                     }
                     else if (data.type === "flush_done") {
                         // Acknowledgment for finalize command
@@ -152,6 +169,10 @@ class SttWebsocket {
                 };
                 if (__classPrivateFieldGet(this, _SttWebsocket_language, "f"))
                     params.language = __classPrivateFieldGet(this, _SttWebsocket_language, "f");
+                if (__classPrivateFieldGet(this, _SttWebsocket_minVolume, "f") !== undefined)
+                    params.min_volume = __classPrivateFieldGet(this, _SttWebsocket_minVolume, "f").toString();
+                if (__classPrivateFieldGet(this, _SttWebsocket_maxSilenceDurationSecs, "f") !== undefined)
+                    params.max_silence_duration_secs = __classPrivateFieldGet(this, _SttWebsocket_maxSilenceDurationSecs, "f").toString();
                 const apiKey = yield core.Supplier.get(this.options.apiKey);
                 if (apiKey) {
                     params.api_key = apiKey;
@@ -185,7 +206,7 @@ class SttWebsocket {
         __classPrivateFieldSet(this, _SttWebsocket_isConnected, false, "f");
     }
 }
-_SttWebsocket_isConnected = new WeakMap(), _SttWebsocket_model = new WeakMap(), _SttWebsocket_language = new WeakMap(), _SttWebsocket_encoding = new WeakMap(), _SttWebsocket_sampleRate = new WeakMap(), _SttWebsocket_connectionPromise = new WeakMap(), _SttWebsocket_instances = new WeakSet(), _SttWebsocket_ensureConnected = function _SttWebsocket_ensureConnected() {
+_SttWebsocket_isConnected = new WeakMap(), _SttWebsocket_model = new WeakMap(), _SttWebsocket_language = new WeakMap(), _SttWebsocket_encoding = new WeakMap(), _SttWebsocket_sampleRate = new WeakMap(), _SttWebsocket_minVolume = new WeakMap(), _SttWebsocket_maxSilenceDurationSecs = new WeakMap(), _SttWebsocket_connectionPromise = new WeakMap(), _SttWebsocket_instances = new WeakSet(), _SttWebsocket_ensureConnected = function _SttWebsocket_ensureConnected() {
     return __awaiter(this, void 0, void 0, function* () {
         if (__classPrivateFieldGet(this, _SttWebsocket_isConnected, "f"))
             return;

package/wrapper/Websocket.js

@@ -180,7 +180,7 @@ class Websocket {
                 var _a;
                 const baseUrl = ((_a = (yield core.Supplier.get(this.options.environment))) !== null && _a !== void 0 ? _a : environments.CartesiaEnvironment.Production).replace(/^https?:\/\//, "");
                 const params = {
-                    cartesia_version: this.options.cartesiaVersion || "2024-06-10",
+                    cartesia_version: this.options.cartesiaVersion || "2025-04-16",
                 };
                 const apiKey = yield core.Supplier.get(this.options.apiKey);
                 if (apiKey) {