@cartesia/cartesia-js 1.0.3 → 1.2.1-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @cartesia/cartesia-js
 
+## 1.1.0
+
+### Minor Changes
+
+- ed6be65: Add WebSocket continue method for input streaming with contexts
+
 ## 1.0.3
 
 ### Patch Changes

package/README.md

@@ -1,7 +1,7 @@
 # Cartesia JavaScript Client
 
 ![NPM Version](https://img.shields.io/npm/v/%40cartesia%2Fcartesia-js?logo=npm)
-[![Discord](https://badgen.net/badge/black/Cartesia/icon?icon=discord&label)](https://discord.gg/ZVxavqHB9X)
+[![Discord](https://badgen.net/badge/black/Cartesia/icon?icon=discord&label)](https://discord.gg/cartesia)
 
 This client provides convenient access to [Cartesia's TTS models](https://cartesia.ai/). Sonic is the fastest text-to-speech model around—it can generate a second of audio in just 650ms, and it can stream out the first audio chunk in just 135ms. Alongside Sonic, we also offer an extensive prebuilt voice library for a variety of use cases.
 
@@ -63,6 +63,13 @@ const mixedVoiceEmbedding = await cartesia.voices.mix({
 	voices: [{ id: "<voice-id-1>", weight: 0.6 }, { id: "<voice-id-2>", weight: 0.4 }],
 });
 
+// Localize a voice.
+const localizedVoiceEmbedding = await cartesia.voices.localize({
+	embedding: Array(192).fill(1.0),
+	original_speaker_gender: "female",
+	language: "es",
+});
+
 // Create a voice.
 const newVoice = await cartesia.voices.create({
 	name: "Tim",
@@ -120,9 +127,31 @@ for await (const message of response.events('message')) {
 
 #### Input Streaming with Contexts
 
-You can perform input streaming with contexts as described in the [docs](https://docs.cartesia.ai/api-reference/endpoints/stream-speech-websocket#input-streaming-with-contexts). The WebSocket's `send` method is just a wrapper around sending a message on the WebSocket, so the request format specified the docs can be used directly.
+```js
+const contextOptions = {
+	context_id: "my-context",
+	model_id: "sonic-english",
+	voice: {
+		mode: "id",
+		id: "a0e99841-438c-4a64-b679-ae501e7d6091",
+	},
+}
+
+// Initial request on the context uses websocket.send().
+// This response object will aggregate the results of all the inputs sent on the context.
+const response = await websocket.send({
+	...contextOptions,
+	transcript: "Hello, world!",
+});
+
+// Subsequent requests on the same context use websocket.continue().
+await websocket.continue({
+	...contextOptions,
+	transcript: " How are you today?",
+});
+```
 
-You should use the return from the first `send` call on a context to receive outputs and events for the entire context. You can ignore the return values of subsequent `send` calls.
+See the [input streaming docs](https://docs.cartesia.ai/reference/web-socket/stream-speech/working-with-web-sockets#input-streaming-with-contexts) for more information.
 
 #### Timestamps
 

package/dist/{chunk-BHY7MNGT.js → chunk-5SBAQNWQ.js}

@@ -1,6 +1,6 @@
 import {
   ENCODING_MAP
-} from "./chunk-6YQ6KDIQ.js";
+} from "./chunk-I5YVYTNK.js";
 
 // src/tts/utils.ts
 import base64 from "base64-js";

package/dist/{chunk-LZO6K34D.js → chunk-CSOXALSC.js}

@@ -1,16 +1,16 @@
 import {
   playAudioBuffer
-} from "./chunk-BHY7MNGT.js";
+} from "./chunk-5SBAQNWQ.js";
 import {
   __async,
   __privateAdd,
   __privateGet,
   __privateMethod,
   __privateSet
-} from "./chunk-GHY2WEOK.js";
+} from "./chunk-NJDRWDQ3.js";
 
 // src/tts/player.ts
-var _context, _startNextPlaybackAt, _bufferDuration, _playBuffer, playBuffer_fn;
+var _context, _startNextPlaybackAt, _bufferDuration, _Player_instances, playBuffer_fn;
 var Player = class {
   /**
    * Create a new Player.
@@ -19,10 +19,10 @@ var Player = class {
    * @param options.bufferDuration - The duration of the audio buffer to play.
    */
   constructor({ bufferDuration }) {
-    __privateAdd(this, _playBuffer);
+    __privateAdd(this, _Player_instances);
     __privateAdd(this, _context, null);
     __privateAdd(this, _startNextPlaybackAt, 0);
-    __privateAdd(this, _bufferDuration, void 0);
+    __privateAdd(this, _bufferDuration);
     __privateSet(this, _bufferDuration, bufferDuration);
   }
   /**
@@ -42,7 +42,7 @@ var Player = class {
       while (true) {
         const read = yield source.read(buffer);
         const playableAudio = buffer.subarray(0, read);
-        plays.push(__privateMethod(this, _playBuffer, playBuffer_fn).call(this, playableAudio, source.sampleRate));
+        plays.push(__privateMethod(this, _Player_instances, playBuffer_fn).call(this, playableAudio, source.sampleRate));
         if (read < buffer.length) {
           break;
         }
@@ -111,7 +111,7 @@ var Player = class {
 _context = new WeakMap();
 _startNextPlaybackAt = new WeakMap();
 _bufferDuration = new WeakMap();
-_playBuffer = new WeakSet();
+_Player_instances = new WeakSet();
 playBuffer_fn = function(buf, sampleRate) {
   return __async(this, null, function* () {
     if (!__privateGet(this, _context)) {

package/dist/{chunk-PISCPZK4.js → chunk-FLWYXP5Z.js}

@@ -7,7 +7,7 @@ import {
   __async,
   __spreadProps,
   __spreadValues
-} from "./chunk-GHY2WEOK.js";
+} from "./chunk-NJDRWDQ3.js";
 
 // src/lib/client.ts
 import fetch from "cross-fetch";

package/dist/chunk-GLZYI5DM.js

@@ -0,0 +1,43 @@
+import {
+  WebSocket
+} from "./chunk-WSIVWXEI.js";
+import {
+  Client
+} from "./chunk-FLWYXP5Z.js";
+import {
+  __async
+} from "./chunk-NJDRWDQ3.js";
+
+// src/tts/index.ts
+var TTS = class extends Client {
+  /**
+   * Get a WebSocket client for streaming audio from the TTS API.
+   *
+   * @returns {WebSocket} A Cartesia WebSocket client.
+   */
+  websocket(options) {
+    return new WebSocket(options, {
+      apiKey: this.apiKey,
+      baseUrl: this.baseUrl
+    });
+  }
+  /**
+   * Generate audio bytes from text.
+   *
+   * @param options - The options for the request.
+   * @returns {Promise<ArrayBuffer>} A promise that resolves to an ArrayBuffer containing the audio bytes.
+   */
+  bytes(options) {
+    return __async(this, null, function* () {
+      const response = yield this._fetch("/tts/bytes", {
+        method: "POST",
+        body: JSON.stringify(options)
+      });
+      return response.arrayBuffer();
+    });
+  }
+};
+
+export {
+  TTS
+};

package/dist/{chunk-6YQ6KDIQ.js → chunk-I5YVYTNK.js}

@@ -4,7 +4,7 @@ import {
   __privateGet,
   __privateMethod,
   __privateSet
-} from "./chunk-GHY2WEOK.js";
+} from "./chunk-NJDRWDQ3.js";
 
 // src/tts/source.ts
 import Emittery from "emittery";
@@ -14,7 +14,7 @@ var ENCODING_MAP = {
   pcm_alaw: { arrayType: Uint8Array, bytesPerElement: 1 },
   pcm_mulaw: { arrayType: Uint8Array, bytesPerElement: 1 }
 };
-var _emitter, _buffer, _readIndex, _writeIndex, _closed, _sampleRate, _encoding, _container, _createBuffer, createBuffer_fn;
+var _emitter, _buffer, _readIndex, _writeIndex, _closed, _sampleRate, _encoding, _container, _Source_instances, createBuffer_fn;
 var Source = class {
   /**
    * Create a new Source.
@@ -27,21 +27,15 @@ var Source = class {
     encoding,
     container
   }) {
-    /**
-     * Create a new buffer for the source.
-     *
-     * @param size - The size of the buffer to create.
-     * @returns The new buffer as a TypedArray based on the encoding.
-     */
-    __privateAdd(this, _createBuffer);
+    __privateAdd(this, _Source_instances);
     __privateAdd(this, _emitter, new Emittery());
-    __privateAdd(this, _buffer, void 0);
+    __privateAdd(this, _buffer);
     __privateAdd(this, _readIndex, 0);
     __privateAdd(this, _writeIndex, 0);
     __privateAdd(this, _closed, false);
-    __privateAdd(this, _sampleRate, void 0);
-    __privateAdd(this, _encoding, void 0);
-    __privateAdd(this, _container, void 0);
+    __privateAdd(this, _sampleRate);
+    __privateAdd(this, _encoding);
+    __privateAdd(this, _container);
     this.on = __privateGet(this, _emitter).on.bind(__privateGet(this, _emitter));
     this.once = __privateGet(this, _emitter).once.bind(__privateGet(this, _emitter));
     this.events = __privateGet(this, _emitter).events.bind(__privateGet(this, _emitter));
@@ -49,7 +43,7 @@ var Source = class {
     __privateSet(this, _sampleRate, sampleRate);
     __privateSet(this, _encoding, encoding);
     __privateSet(this, _container, container);
-    __privateSet(this, _buffer, __privateMethod(this, _createBuffer, createBuffer_fn).call(this, 1024));
+    __privateSet(this, _buffer, __privateMethod(this, _Source_instances, createBuffer_fn).call(this, 1024));
   }
   get sampleRate() {
     return __privateGet(this, _sampleRate);
@@ -73,7 +67,7 @@ var Source = class {
         while (newCapacity < requiredCapacity) {
           newCapacity *= 2;
         }
-        const newBuffer = __privateMethod(this, _createBuffer, createBuffer_fn).call(this, newCapacity);
+        const newBuffer = __privateMethod(this, _Source_instances, createBuffer_fn).call(this, newCapacity);
         newBuffer.set(__privateGet(this, _buffer));
         __privateSet(this, _buffer, newBuffer);
       }
@@ -106,6 +100,37 @@ var Source = class {
       return read;
     });
   }
+  /**
+   * Seek in the buffer.
+   *
+   * @param offset The offset to seek to.
+   * @param whence The position to seek from.
+   * @returns The new position in the buffer.
+   * @throws {Error} If the seek is invalid.
+   */
+  seek(offset, whence) {
+    return __async(this, null, function* () {
+      let position = __privateGet(this, _readIndex);
+      switch (whence) {
+        case "start":
+          position = offset;
+          break;
+        case "current":
+          position += offset;
+          break;
+        case "end":
+          position = __privateGet(this, _writeIndex) + offset;
+          break;
+        default:
+          throw new Error(`Invalid seek mode: ${whence}`);
+      }
+      if (position < 0 || position > __privateGet(this, _writeIndex)) {
+        throw new Error("Seek out of bounds");
+      }
+      __privateSet(this, _readIndex, position);
+      return position;
+    });
+  }
   /**
    * Get the number of samples in a given duration.
    *
@@ -147,7 +172,13 @@ _closed = new WeakMap();
 _sampleRate = new WeakMap();
 _encoding = new WeakMap();
 _container = new WeakMap();
-_createBuffer = new WeakSet();
+_Source_instances = new WeakSet();
+/**
+ * Create a new buffer for the source.
+ *
+ * @param size - The size of the buffer to create.
+ * @returns The new buffer as a TypedArray based on the encoding.
+ */
 createBuffer_fn = function(size) {
   const { arrayType: ArrayType } = ENCODING_MAP[__privateGet(this, _encoding)];
   return new ArrayType(size);

package/dist/{chunk-NQVZNVOU.js → chunk-LKKWJLUG.js}

@@ -1,6 +1,6 @@
 import {
   __async
-} from "./chunk-GHY2WEOK.js";
+} from "./chunk-NJDRWDQ3.js";
 
 // src/react/utils.ts
 function pingServer(url) {

package/dist/{chunk-GHY2WEOK.js → chunk-NJDRWDQ3.js}

@@ -4,6 +4,9 @@ var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
 var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __spreadValues = (a, b) => {
   for (var prop in b || (b = {}))
@@ -17,40 +20,11 @@ var __spreadValues = (a, b) => {
   return a;
 };
 var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
-var __objRest = (source, exclude) => {
-  var target = {};
-  for (var prop in source)
-    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
-      target[prop] = source[prop];
-  if (source != null && __getOwnPropSymbols)
-    for (var prop of __getOwnPropSymbols(source)) {
-      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
-        target[prop] = source[prop];
-    }
-  return target;
-};
-var __accessCheck = (obj, member, msg) => {
-  if (!member.has(obj))
-    throw TypeError("Cannot " + msg);
-};
-var __privateGet = (obj, member, getter) => {
-  __accessCheck(obj, member, "read from private field");
-  return getter ? getter.call(obj) : member.get(obj);
-};
-var __privateAdd = (obj, member, value) => {
-  if (member.has(obj))
-    throw TypeError("Cannot add the same private member more than once");
-  member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
-};
-var __privateSet = (obj, member, value, setter) => {
-  __accessCheck(obj, member, "write to private field");
-  setter ? setter.call(obj, value) : member.set(obj, value);
-  return value;
-};
-var __privateMethod = (obj, member, method) => {
-  __accessCheck(obj, member, "access private method");
-  return method;
-};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
 var __async = (__this, __arguments, generator) => {
   return new Promise((resolve, reject) => {
     var fulfilled = (value) => {
@@ -75,7 +49,6 @@ var __async = (__this, __arguments, generator) => {
 export {
   __spreadValues,
   __spreadProps,
-  __objRest,
   __privateGet,
   __privateAdd,
   __privateSet,

package/dist/{chunk-ZF6HASZT.js → chunk-QWNB544W.js}

@@ -1,12 +1,15 @@
+import {
+  VoiceChanger
+} from "./chunk-WLEVU3HN.js";
 import {
   Voices
-} from "./chunk-YFN6TFR4.js";
+} from "./chunk-RJICGVPL.js";
 import {
   TTS
-} from "./chunk-NWCW6C7H.js";
+} from "./chunk-GLZYI5DM.js";
 import {
   Client
-} from "./chunk-PISCPZK4.js";
+} from "./chunk-FLWYXP5Z.js";
 
 // src/lib/index.ts
 var Cartesia = class extends Client {
@@ -14,6 +17,7 @@ var Cartesia = class extends Client {
     super(options);
     this.tts = new TTS(options);
     this.voices = new Voices(options);
+    this.voiceChanger = new VoiceChanger(options);
   }
 };
 

package/dist/{chunk-YFN6TFR4.js → chunk-RJICGVPL.js}

@@ -1,9 +1,9 @@
 import {
   Client
-} from "./chunk-PISCPZK4.js";
+} from "./chunk-FLWYXP5Z.js";
 import {
   __async
-} from "./chunk-GHY2WEOK.js";
+} from "./chunk-NJDRWDQ3.js";
 
 // src/voices/index.ts
 var Voices = class extends Client {
@@ -56,10 +56,18 @@ var Voices = class extends Client {
   }
   mix(options) {
     return __async(this, null, function* () {
-      const request = options;
       const response = yield this._fetch("/voices/mix", {
         method: "POST",
-        body: JSON.stringify(request)
+        body: JSON.stringify(options)
+      });
+      return response.json();
+    });
+  }
+  localize(options) {
+    return __async(this, null, function* () {
+      const response = yield this._fetch("/voices/localize", {
+        method: "POST",
+        body: JSON.stringify(options)
       });
       return response.json();
     });

package/dist/chunk-WLEVU3HN.js

@@ -0,0 +1,42 @@
+import {
+  Client
+} from "./chunk-FLWYXP5Z.js";
+import {
+  __async
+} from "./chunk-NJDRWDQ3.js";
+
+// src/voice-changer/index.ts
+var VoiceChanger = class extends Client {
+  bytes(options) {
+    return __async(this, null, function* () {
+      const formData = new FormData();
+      formData.append("clip", options.clip);
+      formData.append("voice[id]", options.voice.id);
+      const fmt = options.output_format;
+      formData.append("output_format[container]", fmt.container);
+      if ("encoding" in fmt) {
+        formData.append("output_format[encoding]", fmt.encoding);
+      }
+      if ("bit_rate" in fmt) {
+        formData.append("output_format[bit_rate]", fmt.bit_rate.toString());
+      }
+      if ("sample_rate" in fmt) {
+        formData.append("output_format[sample_rate]", fmt.sample_rate.toString());
+      }
+      const response = yield this._fetch("/voice-changer/bytes", {
+        method: "POST",
+        body: formData
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Voice changer error! status: ${response.status}, message: ${yield response.text()}`
+        );
+      }
+      return { buffer: yield response.arrayBuffer() };
+    });
+  }
+};
+
+export {
+  VoiceChanger
+};

package/dist/{chunk-EUW2435M.js → chunk-WSIVWXEI.js}

@@ -1,6 +1,6 @@
 import {
   Client
-} from "./chunk-PISCPZK4.js";
+} from "./chunk-FLWYXP5Z.js";
 import {
   CARTESIA_VERSION,
   constructApiUrl
@@ -10,26 +10,25 @@ import {
   createMessageHandlerForContextId,
   getEmitteryCallbacks,
   isSentinel
-} from "./chunk-BHY7MNGT.js";
+} from "./chunk-5SBAQNWQ.js";
 import {
   Source
-} from "./chunk-6YQ6KDIQ.js";
+} from "./chunk-I5YVYTNK.js";
 import {
   __async,
-  __objRest,
   __privateAdd,
   __privateGet,
   __privateMethod,
   __privateSet,
   __spreadProps,
   __spreadValues
-} from "./chunk-GHY2WEOK.js";
+} from "./chunk-NJDRWDQ3.js";
 
 // src/tts/websocket.ts
 import Emittery from "emittery";
 import { humanId } from "human-id";
 import { WebSocket as PartySocketWebSocket } from "partysocket";
-var _isConnected, _sampleRate, _container, _encoding, _generateId, generateId_fn;
+var _isConnected, _sampleRate, _container, _encoding, _WebSocket_instances, generateId_fn;
 var WebSocket = class extends Client {
   /**
    * Create a new WebSocket client.
@@ -38,19 +37,11 @@ var WebSocket = class extends Client {
    */
   constructor({ sampleRate, container, encoding }, ...args) {
     super(...args);
-    /**
-     * Generate a unique ID suitable for a streaming context.
-     *
-     * Not suitable for security purposes or as a primary key, since
-     * it lacks the amount of entropy required for those use cases.
-     *
-     * @returns A unique ID.
-     */
-    __privateAdd(this, _generateId);
+    __privateAdd(this, _WebSocket_instances);
     __privateAdd(this, _isConnected, false);
-    __privateAdd(this, _sampleRate, void 0);
-    __privateAdd(this, _container, void 0);
-    __privateAdd(this, _encoding, void 0);
+    __privateAdd(this, _sampleRate);
+    __privateAdd(this, _container);
+    __privateAdd(this, _encoding);
     __privateSet(this, _sampleRate, sampleRate);
     __privateSet(this, _container, container != null ? container : "raw");
     __privateSet(this, _encoding, encoding != null ? encoding : "pcm_f32le");
@@ -58,7 +49,7 @@ var WebSocket = class extends Client {
   /**
    * Send a message over the WebSocket to start a stream.
    *
-   * @param inputs - Stream options. Defined in the StreamRequest type.
+   * @param inputs - Generation parameters. Defined in the StreamRequest type.
    * @param options - Options for the stream.
    * @param options.timeout - The maximum time to wait for a chunk before cancelling the stream.
    *                          If set to `0`, the stream will not time out.
@@ -66,14 +57,13 @@ var WebSocket = class extends Client {
    * @returns An Emittery instance that emits messages from the WebSocket.
    * @returns An abort function that can be called to cancel the stream.
    */
-  send(_a, { timeout = 0 } = {}) {
-    var inputs = __objRest(_a, []);
-    var _a2, _b, _c, _d;
+  send(inputs, { timeout = 0 } = {}) {
+    var _a, _b, _c, _d;
     if (!__privateGet(this, _isConnected)) {
       throw new Error("Not connected to WebSocket. Call .connect() first.");
     }
     if (!inputs.context_id) {
-      inputs.context_id = __privateMethod(this, _generateId, generateId_fn).call(this);
+      inputs.context_id = __privateMethod(this, _WebSocket_instances, generateId_fn).call(this);
     }
     if (!inputs.output_format) {
       inputs.output_format = {
@@ -82,7 +72,7 @@ var WebSocket = class extends Client {
         sample_rate: __privateGet(this, _sampleRate)
       };
     }
-    (_a2 = this.socket) == null ? void 0 : _a2.send(
+    (_a = this.socket) == null ? void 0 : _a.send(
       JSON.stringify(__spreadValues({}, inputs))
     );
     const emitter = new Emittery();
@@ -152,6 +142,32 @@ var WebSocket = class extends Client {
       stop: streamCompleteController.abort.bind(streamCompleteController)
     });
   }
+  /**
+   * Continue a stream.
+   *
+   * @param inputs - Generation parameters. Defined in the StreamRequest type, but must include a `context_id` field. `continue` is set to true by default.
+   */
+  continue(inputs) {
+    var _a;
+    if (!__privateGet(this, _isConnected)) {
+      throw new Error("Not connected to WebSocket. Call .connect() first.");
+    }
+    if (!inputs.context_id) {
+      throw new Error("context_id is required to continue a context.");
+    }
+    if (!inputs.output_format) {
+      inputs.output_format = {
+        container: __privateGet(this, _container),
+        encoding: __privateGet(this, _encoding),
+        sample_rate: __privateGet(this, _sampleRate)
+      };
+    }
+    (_a = this.socket) == null ? void 0 : _a.send(
+      JSON.stringify(__spreadValues({
+        continue: true
+      }, inputs))
+    );
+  }
   /**
    * Authenticate and connect to a Cartesia streaming WebSocket.
    *
@@ -227,7 +243,15 @@ _isConnected = new WeakMap();
 _sampleRate = new WeakMap();
 _container = new WeakMap();
 _encoding = new WeakMap();
-_generateId = new WeakSet();
+_WebSocket_instances = new WeakSet();
+/**
+ * Generate a unique ID suitable for a streaming context.
+ *
+ * Not suitable for security purposes or as a primary key, since
+ * it lacks the amount of entropy required for those use cases.
+ *
+ * @returns A unique ID.
+ */
 generateId_fn = function() {
   return humanId({
     separator: "-",