@cartesia/cartesia-js 0.0.4-alpha.0 → 1.0.0-alpha.2

package/.turbo/turbo-build.log

@@ -1,57 +1,75 @@
 $ tsup src/ --format cjs,esm --dts
-CLI Building entry: src/index.ts, src/audio/index.ts, src/audio/utils.ts, src/lib/client.ts, src/lib/constants.ts, src/lib/index.ts, src/react/index.ts, src/react/utils.ts, src/types/index.ts
+CLI Building entry: src/index.ts, src/lib/client.ts, src/lib/constants.ts, src/lib/index.ts, src/react/index.ts, src/react/utils.ts, src/tts/index.ts, src/tts/player.ts, src/tts/source.ts, src/tts/utils.ts, src/tts/websocket.ts, src/types/index.ts, src/voices/index.ts
 CLI Using tsconfig: tsconfig.json
 CLI tsup v8.0.2
 CLI Target: es6
 CJS Build start
 ESM Build start
+CJS dist/index.cjs         21.16 KB
+CJS dist/lib/client.cjs    3.51 KB
+CJS dist/react/index.cjs   27.38 KB
+CJS dist/tts/index.cjs     15.80 KB
 CJS dist/types/index.cjs   764.00 B
-CJS dist/index.cjs         13.34 KB
-CJS dist/audio/index.cjs   13.05 KB
-CJS dist/audio/utils.cjs   5.24 KB
-CJS dist/lib/client.cjs    1.40 KB
-CJS dist/lib/constants.cjs 1.35 KB
-CJS dist/lib/index.cjs     13.32 KB
-CJS dist/react/index.cjs   18.78 KB
+CJS dist/voices/index.cjs  5.21 KB
+CJS dist/lib/constants.cjs 1.61 KB
+CJS dist/lib/index.cjs     17.33 KB
 CJS dist/react/utils.cjs   1.80 KB
-CJS ⚡️ Build success in 76ms
-ESM dist/index.js          276.00 B
-ESM dist/audio/index.js    219.00 B
+CJS dist/tts/player.cjs    6.66 KB
+CJS dist/tts/source.cjs    6.63 KB
+CJS dist/tts/utils.cjs     3.87 KB
+CJS dist/tts/websocket.cjs 15.49 KB
+CJS ⚡️ Build success in 134ms
 ESM dist/chunk-FXPGR372.js 0 B
+ESM dist/tts/source.js     112.00 B
+ESM dist/tts/utils.js      395.00 B
+ESM dist/tts/websocket.js  242.00 B
+ESM dist/types/index.js    31.00 B
+ESM dist/voices/index.js   174.00 B
+ESM dist/index.js          437.00 B
 ESM dist/lib/client.js     132.00 B
-ESM dist/react/index.js    4.31 KB
-ESM dist/audio/utils.js    498.00 B
-ESM dist/lib/constants.js  185.00 B
-ESM dist/lib/index.js      229.00 B
-ESM dist/chunk-S6A27RQL.js 288.00 B
-ESM dist/chunk-4MHF74A7.js 7.88 KB
-ESM dist/chunk-5TSWLYOW.js 3.22 KB
-ESM dist/chunk-MJIFZWHS.js 385.00 B
-ESM dist/chunk-OVI3W3GG.js 275.00 B
+ESM dist/lib/constants.js  183.00 B
+ESM dist/lib/index.js      322.00 B
+ESM dist/react/index.js    6.22 KB
+ESM dist/chunk-T3RG6WV4.js 353.00 B
+ESM dist/chunk-WVTITUXX.js 1.35 KB
 ESM dist/react/utils.js    109.00 B
-ESM dist/chunk-XPIMIAAE.js 337.00 B
-ESM dist/chunk-R4P7LWVZ.js 1.76 KB
-ESM dist/types/index.js    31.00 B
-ESM ⚡️ Build success in 78ms
+ESM dist/chunk-3FL2SNIR.js 337.00 B
+ESM dist/tts/index.js      261.00 B
+ESM dist/chunk-KWBSQZTY.js 439.00 B
+ESM dist/chunk-3F5E46FT.js 5.81 KB
+ESM dist/chunk-PQ6CIPFW.js 4.02 KB
+ESM dist/chunk-JGP5BIUV.js 841.00 B
+ESM dist/chunk-XHTDPLFR.js 542.00 B
+ESM dist/tts/player.js     143.00 B
+ESM dist/chunk-36JBKJUN.js 3.52 KB
+ESM dist/chunk-RO7TY474.js 1.95 KB
+ESM dist/chunk-WIFMLPT5.js 2.27 KB
+ESM ⚡️ Build success in 140ms
 DTS Build start
-DTS ⚡️ Build success in 7157ms
-DTS dist/lib/constants.d.cts  211.00 B
-DTS dist/react/index.d.cts    749.00 B
-DTS dist/lib/client.d.cts     181.00 B
-DTS dist/react/utils.d.cts    240.00 B
-DTS dist/types/index.d.cts    103.00 B
-DTS dist/lib/index.d.cts      327.00 B
-DTS dist/audio/utils.d.cts    400.00 B
-DTS dist/audio/index.d.cts    232.00 B
-DTS dist/index.d.cts          215.00 B
-DTS dist/index-C2_3XFxn.d.cts 6.59 KB
-DTS dist/lib/constants.d.ts   211.00 B
-DTS dist/react/index.d.ts     746.00 B
-DTS dist/lib/client.d.ts      180.00 B
-DTS dist/react/utils.d.ts     240.00 B
-DTS dist/types/index.d.ts     103.00 B
-DTS dist/lib/index.d.ts       324.00 B
-DTS dist/audio/utils.d.ts     397.00 B
-DTS dist/audio/index.d.ts     229.00 B
-DTS dist/index.d.ts           211.00 B
-DTS dist/index-DgwnZezj.d.ts  6.59 KB
+DTS ⚡️ Build success in 8877ms
+DTS dist/index.d.cts         509.00 B
+DTS dist/lib/constants.d.cts 247.00 B
+DTS dist/lib/index.d.cts     410.00 B
+DTS dist/react/index.d.cts   1018.00 B
+DTS dist/react/utils.d.cts   240.00 B
+DTS dist/tts/index.d.cts     471.00 B
+DTS dist/tts/player.d.cts    1.06 KB
+DTS dist/tts/utils.d.cts     2.56 KB
+DTS dist/tts/websocket.d.cts 2.39 KB
+DTS dist/tts/source.d.cts    2.17 KB
+DTS dist/voices/index.d.cts  399.00 B
+DTS dist/lib/client.d.cts    267.00 B
+DTS dist/types/index.d.cts   1.28 KB
+DTS dist/index.d.ts          501.00 B
+DTS dist/lib/constants.d.ts  247.00 B
+DTS dist/lib/index.d.ts      404.00 B
+DTS dist/react/index.d.ts    1016.00 B
+DTS dist/react/utils.d.ts    240.00 B
+DTS dist/tts/index.d.ts      467.00 B
+DTS dist/tts/player.d.ts     1.06 KB
+DTS dist/tts/utils.d.ts      2.55 KB
+DTS dist/tts/websocket.d.ts  2.39 KB
+DTS dist/tts/source.d.ts     2.16 KB
+DTS dist/voices/index.d.ts   397.00 B
+DTS dist/lib/client.d.ts     266.00 B
+DTS dist/types/index.d.ts    1.28 KB

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @cartesia/cartesia-js
 
+## 1.0.0-alpha.2
+
+### Patch Changes
+
+- 585d2c9: Makes JS client compatible with the Cartesia Stable API (2024-06-10)
+
+## 1.0.0-alpha.1
+
+### Major Changes
+
+- 3ee5bfc: Initial release of Cartesia client with voices and WebSocket support
+
 ## 0.0.4-alpha.0
 
 ### Patch Changes

package/README.md

@@ -15,39 +15,146 @@ bun add @cartesia/cartesia-js
 
 ## Usage
 
-```javascript
+### CRUD on Voices
+
+```js
+import Cartesia from "@cartesia/cartesia-js";
+
+const cartesia = new Cartesia({
+	apiKey: "your-api-key",
+});
+
+// List all voices.
+const voices = await cartesia.voices.list();
+console.log(voices);
+
+// Get a voice.
+const voice = await cartesia.voices.get("<voice-id>");
+console.log(voice);
+
+// Create a voice.
+const newVoice = await cartesia.voices.create({
+	name: "Tim",
+	description: "A deep, resonant voice.",
+	embedding: Array(192).fill(1.0),
+});
+console.log(newVoice);
+
+// Clone a voice from a URL.
+const clonedVoice = await cartesia.voices.clone({
+	mode: "url",
+	url: "https://youtu.be/AdtLxlttrHg?si=07OLmDPg__0IN14f&t=6",
+});
+
+// Clone a voice from a file.
+const clonedVoice = await cartesia.voices.clone({
+	mode: "clip",
+	clip: myFile, // Pass a File object or a Blob.
+});
+```
+
+### TTS over WebSocket
+
+```js
 import Cartesia from "@cartesia/cartesia-js";
 
-const cartesia = new Cartesia();
+const cartesia = new Cartesia({
+	apiKey: "your-api-key",
+});
+
+// Initialize the WebSocket. Make sure the sample rate you specify is supported.
+const websocket = cartesia.tts.websocket({ sampleRate: 44100 });
 
 try {
-	await cartesia.audio.connect();
+	await websocket.connect();
 } catch (error) {
 	console.error(`Failed to connect to Cartesia: ${error}`);
 }
 
-const stream = await cartesia.audio.stream({
+// Create a stream.
+const response = await websocket.send({
 	model: "upbeat-moon",
-	options: {
-		transcript: "Hello, world!",
-		chunk_time: 0.1,
+	voice: {
+		mode: "embedding",
+		embedding: Array(192).fill(1.0),
 	},
+	transcript: "Hello, world!"
+	// The WebSocket sets output_format on your behalf.
+	// The container is "raw" and the encoding is "pcm_f32le".
 });
 
-console.log(`Created stream ${stream.id}.`);
-
-stream.on("chunk", ({ chunk, chunks }) => {
-	console.log("Received chunk:", chunk);
-	console.log("All chunks:", chunks);
+// Access the raw messages from the WebSocket.
+response.on("message", (message) => {
+	// Raw message.
+	console.log("Received message:", message);
 });
 
-stream.on("message", ({ message }) => {
+// You can also access messages using a for-await-of loop.
+for await (const message of response.events('message')) {
 	// Raw message.
 	console.log("Received message:", message);
-});
+}
+```
+
+#### Playing audio in the browser
+
+(We currently only support playing audio in the browser. Support for other JS environments is coming soon.)
+
+```js
+// If you're using the client in the browser, you can play the audio like this:
+import { WebPlayer } from "@cartesia/cartesia-js";
 
-// If you're using the client in the browser, you can play the stream like this:
 console.log("Playing stream...");
-await stream.play();
+
+// Create a Player object.
+const player = new WebPlayer();
+
+// Play the audio. (`response` includes a custom Source object that the Player can play.)
+// The call resolves when the audio finishes playing.
+await player.play(response.source);
+
 console.log("Done playing.");
 ```
+
+## React
+
+We export a React hook that simplifies the process of using the TTS API. The hook manages the WebSocket connection and provides a simple interface for buffering and playing audio.
+
+```jsx
+import { useTTS } from '@cartesia/cartesia-js/react';
+
+function TextToSpeech() {
+	const tts = useTTS({
+		apiKey: "your-api-key",
+		samplingRate: 44100,
+	})
+
+	const [text, setText] = useState("");
+
+	const handlePlay = async () => {
+		// Begin buffering the audio.
+		const response = await tts.buffer({
+			model: "upbeat-moon",
+			voice: {
+				mode: "embedding",
+				embedding: Array(192).fill(1.0),
+			},
+			transcript: text,
+		});
+
+		// Immediately play the audio. (You can also buffer in advance and play later.)
+		await tts.play();
+	}
+
+	return (
+		<div>
+			<input type="text" value={text} onChange={(event) => setText(event.target.value)} />
+			<button onClick={handlePlay}>Play</button>
+
+			<div>
+				{tts.playbackStatus} | {tts.bufferStatus} | {tts.isWaiting}
+			</div>
+		</div>
+	);
+}
+```

package/dist/chunk-36JBKJUN.js

@@ -0,0 +1,119 @@
+import {
+  playAudioBuffer
+} from "./chunk-RO7TY474.js";
+import {
+  __async,
+  __privateAdd,
+  __privateGet,
+  __privateMethod,
+  __privateSet
+} from "./chunk-WIFMLPT5.js";
+
+// src/tts/player.ts
+import Emittery from "emittery";
+var _context, _startNextPlaybackAt, _bufferDuration, _emitter, _playBuffer, playBuffer_fn;
+var Player = class {
+  /**
+   * Create a new Player.
+   *
+   * @param options - Options for the Player.
+   * @param options.bufferDuration - The duration of the audio buffer to play.
+   */
+  constructor({ bufferDuration }) {
+    __privateAdd(this, _playBuffer);
+    __privateAdd(this, _context, null);
+    __privateAdd(this, _startNextPlaybackAt, 0);
+    __privateAdd(this, _bufferDuration, void 0);
+    __privateAdd(this, _emitter, new Emittery());
+    __privateSet(this, _bufferDuration, bufferDuration);
+  }
+  /**
+   * Play audio from a source.
+   *
+   * @param source The source to play audio from.
+   * @returns A promise that resolves when the audio has finished playing.
+   */
+  play(source) {
+    return __async(this, null, function* () {
+      __privateSet(this, _startNextPlaybackAt, 0);
+      __privateSet(this, _context, new AudioContext({ sampleRate: source.sampleRate }));
+      const buffer = new Float32Array(
+        source.durationToSampleCount(__privateGet(this, _bufferDuration))
+      );
+      const plays = [];
+      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));
+        if (read < buffer.length) {
+          yield __privateGet(this, _emitter).emit("finish");
+          break;
+        }
+      }
+      yield Promise.all(plays);
+    });
+  }
+  /**
+   * Pause the audio.
+   *
+   * @returns A promise that resolves when the audio has been paused.
+   */
+  pause() {
+    return __async(this, null, function* () {
+      if (!__privateGet(this, _context)) {
+        throw new Error("AudioContext not initialized.");
+      }
+      yield __privateGet(this, _context).suspend();
+    });
+  }
+  /**
+   * Resume the audio.
+   *
+   * @returns A promise that resolves when the audio has been resumed.
+   */
+  resume() {
+    return __async(this, null, function* () {
+      if (!__privateGet(this, _context)) {
+        throw new Error("AudioContext not initialized.");
+      }
+      yield __privateGet(this, _context).resume();
+    });
+  }
+  /**
+   * Toggle the audio.
+   *
+   * @returns A promise that resolves when the audio has been toggled.
+   */
+  toggle() {
+    return __async(this, null, function* () {
+      if (!__privateGet(this, _context)) {
+        throw new Error("AudioContext not initialized.");
+      }
+      if (__privateGet(this, _context).state === "running") {
+        yield this.pause();
+      } else {
+        yield this.resume();
+      }
+    });
+  }
+};
+_context = new WeakMap();
+_startNextPlaybackAt = new WeakMap();
+_bufferDuration = new WeakMap();
+_emitter = new WeakMap();
+_playBuffer = new WeakSet();
+playBuffer_fn = function(buf, sampleRate) {
+  return __async(this, null, function* () {
+    if (!__privateGet(this, _context)) {
+      throw new Error("AudioContext not initialized.");
+    }
+    const startAt = __privateGet(this, _startNextPlaybackAt);
+    const duration = buf.length / sampleRate;
+    __privateSet(this, _startNextPlaybackAt, duration + Math.max(__privateGet(this, _context).currentTime, __privateGet(this, _startNextPlaybackAt)));
+    yield playAudioBuffer(buf, __privateGet(this, _context), startAt, sampleRate);
+  });
+};
+
+export {
+  Player
+};

package/dist/chunk-3F5E46FT.js

@@ -0,0 +1,212 @@
+import {
+  Source
+} from "./chunk-PQ6CIPFW.js";
+import {
+  Client
+} from "./chunk-JGP5BIUV.js";
+import {
+  CARTESIA_VERSION,
+  constructApiUrl
+} from "./chunk-XHTDPLFR.js";
+import {
+  base64ToArray,
+  createMessageHandlerForContextId,
+  getEmitteryCallbacks,
+  isSentinel
+} from "./chunk-RO7TY474.js";
+import {
+  __async,
+  __privateAdd,
+  __privateGet,
+  __privateMethod,
+  __privateSet,
+  __spreadProps,
+  __spreadValues
+} from "./chunk-WIFMLPT5.js";
+
+// src/tts/websocket.ts
+import Emittery from "emittery";
+import { humanId } from "human-id";
+import { WebSocket as PartySocketWebSocket } from "partysocket";
+var _isConnected, _sampleRate, _generateId, generateId_fn;
+var WebSocket = class extends Client {
+  /**
+   * Create a new WebSocket client.
+   *
+   * @param args - Arguments to pass to the Client constructor.
+   */
+  constructor({ sampleRate }, ...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, _isConnected, false);
+    __privateAdd(this, _sampleRate, void 0);
+    __privateSet(this, _sampleRate, sampleRate);
+  }
+  /**
+   * Send a message over the WebSocket in order to start a stream.
+   *
+   * @param inputs - Stream options.
+   * @param options - Options for the stream.
+   * @param options.timeout - The maximum time to wait for a chunk before cancelling the stream.
+   * If `0`, the stream will not time out.
+   * @returns A Source object that can be passed to a Player to play the audio.
+   */
+  send(inputs, { timeout = 0 } = {}) {
+    var _a, _b, _c, _d;
+    if (!__privateGet(this, _isConnected)) {
+      throw new Error("Not connected to WebSocket. Call .connect() first.");
+    }
+    const contextId = __privateMethod(this, _generateId, generateId_fn).call(this);
+    (_a = this.socket) == null ? void 0 : _a.send(
+      JSON.stringify(__spreadProps(__spreadValues({
+        context_id: contextId
+      }, inputs), {
+        output_format: {
+          container: "raw",
+          encoding: "pcm_f32le",
+          sample_rate: __privateGet(this, _sampleRate)
+        }
+      }))
+    );
+    const emitter = new Emittery();
+    const source = new Source({
+      sampleRate: __privateGet(this, _sampleRate)
+    });
+    const streamCompleteController = new AbortController();
+    let timeoutId = null;
+    if (timeout > 0) {
+      timeoutId = setTimeout(streamCompleteController.abort, timeout);
+    }
+    const handleMessage = createMessageHandlerForContextId(
+      contextId,
+      (_0) => __async(this, [_0], function* ({ chunk, message }) {
+        emitter.emit("message", message);
+        if (isSentinel(chunk)) {
+          yield source.close();
+          streamCompleteController.abort();
+          return;
+        }
+        yield source.enqueue(base64ToArray([chunk]));
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = setTimeout(streamCompleteController.abort, timeout);
+        }
+      })
+    );
+    (_b = this.socket) == null ? void 0 : _b.addEventListener("message", handleMessage, {
+      signal: streamCompleteController.signal
+    });
+    (_c = this.socket) == null ? void 0 : _c.addEventListener(
+      "close",
+      () => {
+        streamCompleteController.abort();
+      },
+      {
+        once: true
+      }
+    );
+    (_d = this.socket) == null ? void 0 : _d.addEventListener(
+      "error",
+      () => {
+        streamCompleteController.abort();
+      },
+      {
+        once: true
+      }
+    );
+    streamCompleteController.signal.addEventListener("abort", () => {
+      source.close();
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    });
+    return __spreadValues({ source }, getEmitteryCallbacks(emitter));
+  }
+  /**
+   * Authenticate and connect to a Cartesia streaming WebSocket.
+   *
+   * @returns A promise that resolves when the WebSocket is connected.
+   * @throws {Error} If the WebSocket fails to connect.
+   */
+  connect() {
+    const url = constructApiUrl(
+      this.baseUrl,
+      `/tts/websocket?cartesia_version=${CARTESIA_VERSION}`,
+      "ws"
+    );
+    url.searchParams.set("api_key", this.apiKey);
+    const emitter = new Emittery();
+    this.socket = new PartySocketWebSocket(url.toString());
+    this.socket.onopen = () => {
+      __privateSet(this, _isConnected, true);
+      emitter.emit("open");
+    };
+    this.socket.onclose = () => {
+      __privateSet(this, _isConnected, false);
+      emitter.emit("close");
+    };
+    return new Promise(
+      (resolve, reject) => {
+        var _a, _b, _c;
+        (_a = this.socket) == null ? void 0 : _a.addEventListener(
+          "open",
+          () => {
+            resolve(getEmitteryCallbacks(emitter));
+          },
+          {
+            once: true
+          }
+        );
+        const aborter = new AbortController();
+        (_b = this.socket) == null ? void 0 : _b.addEventListener(
+          "error",
+          () => {
+            aborter.abort();
+            reject(new Error("WebSocket failed to connect."));
+          },
+          {
+            signal: aborter.signal
+          }
+        );
+        (_c = this.socket) == null ? void 0 : _c.addEventListener(
+          "close",
+          () => {
+            aborter.abort();
+            reject(new Error("WebSocket closed before it could connect."));
+          },
+          {
+            signal: aborter.signal
+          }
+        );
+      }
+    );
+  }
+  /**
+   * Disconnect from the Cartesia streaming WebSocket.
+   */
+  disconnect() {
+    var _a;
+    (_a = this.socket) == null ? void 0 : _a.close();
+  }
+};
+_isConnected = new WeakMap();
+_sampleRate = new WeakMap();
+_generateId = new WeakSet();
+generateId_fn = function() {
+  return humanId({
+    separator: "-",
+    capitalize: false
+  });
+};
+
+export {
+  WebSocket
+};

package/dist/{chunk-XPIMIAAE.js → chunk-3FL2SNIR.js}

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

package/dist/chunk-JGP5BIUV.js

@@ -0,0 +1,34 @@
+import {
+  BASE_URL,
+  CARTESIA_VERSION,
+  constructApiUrl
+} from "./chunk-XHTDPLFR.js";
+import {
+  __spreadProps,
+  __spreadValues
+} from "./chunk-WIFMLPT5.js";
+
+// src/lib/client.ts
+import fetch from "cross-fetch";
+var Client = class {
+  constructor(options = {}) {
+    if (!(options.apiKey || process.env.CARTESIA_API_KEY)) {
+      throw new Error("Missing Cartesia API key.");
+    }
+    this.apiKey = options.apiKey || process.env.CARTESIA_API_KEY;
+    this.baseUrl = options.baseUrl || BASE_URL;
+  }
+  fetch(path, options = {}) {
+    const url = constructApiUrl(this.baseUrl, path);
+    return fetch(url.toString(), __spreadProps(__spreadValues({}, options), {
+      headers: __spreadValues({
+        "X-API-Key": this.apiKey,
+        "Cartesia-Version": CARTESIA_VERSION
+      }, options.headers)
+    }));
+  }
+};
+
+export {
+  Client
+};