@cartesia/cartesia-js 0.0.3 → 1.0.0-alpha.1

package/.turbo/turbo-build.log

@@ -1,45 +1,75 @@
 $ tsup src/ --format cjs,esm --dts
-CLI Building entry: 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/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
-ESM dist/types/index.mjs    0 B
-ESM dist/chunk-3CYTAFLF.mjs 7.43 KB
-ESM dist/chunk-FRIBQZPN.mjs 3.22 KB
-ESM dist/chunk-XSFPHPPG.mjs 386.00 B
-ESM dist/chunk-HNLIBHEN.mjs 2.02 KB
-ESM dist/audio/index.mjs    192.00 B
-ESM dist/lib/client.mjs     103.00 B
-ESM dist/react/index.mjs    3.31 KB
-ESM dist/audio/utils.mjs    469.00 B
-ESM dist/lib/constants.mjs  155.00 B
-ESM dist/lib/index.mjs      355.00 B
-ESM ⚡️ Build success in 78ms
-CJS dist/audio/index.js   12.63 KB
-CJS dist/audio/utils.js   5.23 KB
-CJS dist/lib/client.js    1.40 KB
-CJS dist/lib/constants.js 1.35 KB
-CJS dist/lib/index.js     12.89 KB
-CJS dist/react/index.js   17.16 KB
-CJS dist/types/index.js   764.00 B
-CJS ⚡️ Build success in 79ms
+ESM dist/index.js          437.00 B
+ESM dist/chunk-FXPGR372.js 0 B
+ESM dist/lib/client.js     132.00 B
+ESM dist/react/index.js    6.00 KB
+ESM dist/tts/index.js      261.00 B
+ESM dist/lib/constants.js  143.00 B
+ESM dist/lib/index.js      322.00 B
+ESM dist/chunk-X7SJMF2R.js 353.00 B
+ESM dist/chunk-WBK6LLXX.js 1.35 KB
+ESM dist/react/utils.js    109.00 B
+ESM dist/chunk-3FL2SNIR.js 337.00 B
+ESM dist/chunk-4RMSIQLG.js 439.00 B
+ESM dist/chunk-NDNN326Q.js 5.73 KB
+ESM dist/chunk-JOHSCOLW.js 3.39 KB
+ESM dist/chunk-BCQ63627.js 775.00 B
+ESM dist/chunk-3GBZUGUD.js 487.00 B
+ESM dist/tts/player.js     143.00 B
+ESM dist/chunk-WE63M7PJ.js 3.52 KB
+ESM dist/chunk-LYPTISWL.js 1.81 KB
+ESM dist/chunk-WIFMLPT5.js 2.27 KB
+ESM dist/types/index.js    31.00 B
+ESM dist/voices/index.js   174.00 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 ⚡️ Build success in 115ms
+CJS dist/index.cjs         20.24 KB
+CJS dist/lib/client.cjs    3.43 KB
+CJS dist/lib/constants.cjs 1.51 KB
+CJS dist/lib/index.cjs     16.42 KB
+CJS dist/react/index.cjs   26.25 KB
+CJS dist/react/utils.cjs   1.80 KB
+CJS dist/tts/index.cjs     14.89 KB
+CJS dist/tts/player.cjs    6.66 KB
+CJS dist/tts/source.cjs    5.99 KB
+CJS dist/tts/utils.cjs     3.73 KB
+CJS dist/tts/websocket.cjs 14.58 KB
+CJS dist/types/index.cjs   764.00 B
+CJS dist/voices/index.cjs  5.13 KB
+CJS ⚡️ Build success in 117ms
 DTS Build start
-DTS ⚡️ Build success in 5506ms
-DTS dist/lib/constants.d.ts   211.00 B
-DTS dist/lib/index.d.ts       324.00 B
-DTS dist/react/index.d.ts     720.00 B
-DTS dist/lib/client.d.ts      180.00 B
-DTS dist/types/index.d.ts     103.00 B
-DTS dist/audio/utils.d.ts     397.00 B
-DTS dist/audio/index.d.ts     229.00 B
-DTS dist/index-qwAyxV5I.d.ts  6.49 KB
-DTS dist/lib/constants.d.mts  211.00 B
-DTS dist/lib/index.d.mts      327.00 B
-DTS dist/react/index.d.mts    723.00 B
-DTS dist/lib/client.d.mts     181.00 B
-DTS dist/types/index.d.mts    103.00 B
-DTS dist/audio/utils.d.mts    400.00 B
-DTS dist/audio/index.d.mts    232.00 B
-DTS dist/index-DSBmfK9-.d.mts 6.49 KB
+DTS ⚡️ Build success in 8423ms
+DTS dist/index.d.cts         509.00 B
+DTS dist/lib/constants.d.cts 184.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  184.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.1
+
+### Major Changes
+
+- 3ee5bfc: Initial release of Cartesia client with voices and WebSocket support
+
+## 0.0.4-alpha.0
+
+### Patch Changes
+
+- 8ecf940: Add provisional Node.js support
+
 ## 0.0.3
 
 ### 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-3FL2SNIR.js

@@ -0,0 +1,17 @@
+import {
+  __async
+} from "./chunk-WIFMLPT5.js";
+
+// src/react/utils.ts
+function pingServer(url) {
+  return __async(this, null, function* () {
+    const start = (/* @__PURE__ */ new Date()).getTime();
+    yield fetch(url);
+    const end = (/* @__PURE__ */ new Date()).getTime();
+    return end - start;
+  });
+}
+
+export {
+  pingServer
+};

package/dist/chunk-3GBZUGUD.js

@@ -0,0 +1,17 @@
+// src/lib/constants.ts
+var BASE_URL = "https://api.cartesia.ai/v0";
+var constructApiUrl = (baseUrl, path, protocol) => {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  if (!protocol) {
+    return new URL(`${baseUrl}${normalizedPath}`);
+  }
+  if (!["http", "ws"].includes(protocol)) {
+    throw new Error(`Invalid protocol: ${protocol}`);
+  }
+  return new URL(`${baseUrl.replace(/^http/, protocol)}${normalizedPath}`);
+};
+
+export {
+  BASE_URL,
+  constructApiUrl
+};

package/dist/chunk-4RMSIQLG.js

@@ -0,0 +1,25 @@
+import {
+  WebSocket
+} from "./chunk-NDNN326Q.js";
+import {
+  Client
+} from "./chunk-BCQ63627.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
+    });
+  }
+};
+
+export {
+  TTS
+};

package/dist/chunk-BCQ63627.js

@@ -0,0 +1,32 @@
+import {
+  BASE_URL,
+  constructApiUrl
+} from "./chunk-3GBZUGUD.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
+      }, options.headers)
+    }));
+  }
+};
+
+export {
+  Client
+};

package/dist/chunk-JOHSCOLW.js

@@ -0,0 +1,106 @@
+import {
+  __async,
+  __privateAdd,
+  __privateGet,
+  __privateSet
+} from "./chunk-WIFMLPT5.js";
+
+// src/tts/source.ts
+import Emittery from "emittery";
+var _emitter, _buffer, _readIndex, _closed, _sampleRate;
+var Source = class {
+  /**
+   * Create a new Source.
+   *
+   * @param options - Options for the Source.
+   * @param options.sampleRate - The sample rate of the audio.
+   */
+  constructor({ sampleRate }) {
+    __privateAdd(this, _emitter, new Emittery());
+    __privateAdd(this, _buffer, new Float32Array());
+    __privateAdd(this, _readIndex, 0);
+    __privateAdd(this, _closed, false);
+    __privateAdd(this, _sampleRate, void 0);
+    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));
+    this.off = __privateGet(this, _emitter).off.bind(__privateGet(this, _emitter));
+    __privateSet(this, _sampleRate, sampleRate);
+  }
+  get sampleRate() {
+    return __privateGet(this, _sampleRate);
+  }
+  /**
+   * Append audio to the buffer.
+   *
+   * @param src The audio to append.
+   */
+  enqueue(src) {
+    return __async(this, null, function* () {
+      __privateSet(this, _buffer, new Float32Array([...__privateGet(this, _buffer), ...src]));
+      yield __privateGet(this, _emitter).emit("enqueue");
+    });
+  }
+  /**
+   * Read audio from the buffer.
+   *
+   * @param dst The buffer to read the audio into.
+   * @returns The number of samples read. If the source is closed, this will be
+   * less than the length of the provided buffer.
+   */
+  read(dst) {
+    return __async(this, null, function* () {
+      const targetReadIndex = __privateGet(this, _readIndex) + dst.length;
+      while (!__privateGet(this, _closed) && targetReadIndex > __privateGet(this, _buffer).length) {
+        yield __privateGet(this, _emitter).emit("wait");
+        yield Promise.race([
+          __privateGet(this, _emitter).once("enqueue"),
+          __privateGet(this, _emitter).once("close")
+        ]);
+        yield __privateGet(this, _emitter).emit("read");
+      }
+      const read = Math.min(dst.length, __privateGet(this, _buffer).length - __privateGet(this, _readIndex));
+      dst.set(__privateGet(this, _buffer).slice(__privateGet(this, _readIndex), __privateGet(this, _readIndex) + read));
+      __privateSet(this, _readIndex, __privateGet(this, _readIndex) + read);
+      return read;
+    });
+  }
+  /**
+   * Get the number of samples in a given duration.
+   *
+   * @param durationSecs The duration in seconds.
+   * @returns The number of samples.
+   */
+  durationToSampleCount(durationSecs) {
+    return Math.trunc(durationSecs * __privateGet(this, _sampleRate));
+  }
+  get buffer() {
+    return __privateGet(this, _buffer);
+  }
+  get readIndex() {
+    return __privateGet(this, _readIndex);
+  }
+  /**
+   * Close the source. This signals that no more audio will be enqueued.
+   *
+   * This will emit a "close" event.
+   *
+   * @returns A promise that resolves when the source is closed.
+   */
+  close() {
+    return __async(this, null, function* () {
+      __privateSet(this, _closed, true);
+      yield __privateGet(this, _emitter).emit("close");
+      __privateGet(this, _emitter).clearListeners();
+    });
+  }
+};
+_emitter = new WeakMap();
+_buffer = new WeakMap();
+_readIndex = new WeakMap();
+_closed = new WeakMap();
+_sampleRate = new WeakMap();
+
+export {
+  Source
+};

package/dist/chunk-LYPTISWL.js

@@ -0,0 +1,75 @@
+// src/tts/utils.ts
+import base64 from "base64-js";
+function base64ToArray(b64) {
+  return filterSentinel(b64).reduce((acc, b) => {
+    const floats = new Float32Array(base64.toByteArray(b).buffer);
+    const newAcc = new Float32Array(acc.length + floats.length);
+    newAcc.set(acc, 0);
+    newAcc.set(floats, acc.length);
+    return newAcc;
+  }, new Float32Array(0));
+}
+function playAudioBuffer(floats, context, startAt, sampleRate) {
+  const source = context.createBufferSource();
+  const buffer = context.createBuffer(1, floats.length, sampleRate);
+  buffer.getChannelData(0).set(floats);
+  source.buffer = buffer;
+  source.connect(context.destination);
+  source.start(startAt);
+  return new Promise((resolve) => {
+    source.onended = () => {
+      resolve();
+    };
+  });
+}
+function createMessageHandlerForContextId(contextId, handler) {
+  return (event) => {
+    if (typeof event.data !== "string") {
+      return;
+    }
+    const message = JSON.parse(event.data);
+    if (message.context_id !== contextId) {
+      return;
+    }
+    let chunk;
+    if (message.done) {
+      chunk = getSentinel();
+    } else {
+      chunk = message.data;
+    }
+    handler({ chunk, message: event.data });
+  };
+}
+function getSentinel() {
+  return null;
+}
+function isSentinel(x) {
+  return x === getSentinel();
+}
+function filterSentinel(collection) {
+  return collection.filter(
+    (x) => !isSentinel(x)
+  );
+}
+function isComplete(chunks) {
+  return isSentinel(chunks[chunks.length - 1]);
+}
+function getEmitteryCallbacks(emitter) {
+  return {
+    on: emitter.on.bind(emitter),
+    off: emitter.off.bind(emitter),
+    once: emitter.once.bind(emitter),
+    events: emitter.events.bind(emitter)
+  };
+}
+
+export {
+  base64ToArray,
+  playAudioBuffer,
+  createMessageHandlerForContextId,
+  getSentinel,
+  isSentinel,
+  filterSentinel,
+  isComplete,
+  getEmitteryCallbacks
+};