@cartesia/cartesia-js 0.0.1 → 0.0.2

package/dist/react/index.mjs

@@ -1,42 +1,58 @@
 import {
   audio_default
-} from "../chunk-5RMUZJV7.mjs";
-import "../chunk-BTFHUVNH.mjs";
-import "../chunk-ERFCRIWU.mjs";
+} from "../chunk-3CYTAFLF.mjs";
 import {
+  base64ToArray,
+  bufferToWav
+} from "../chunk-FRIBQZPN.mjs";
+import "../chunk-XSFPHPPG.mjs";
+import {
+  SAMPLE_RATE,
   __async
-} from "../chunk-35HX6ML3.mjs";
+} from "../chunk-HNLIBHEN.mjs";
 
 // src/react/index.ts
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 function useAudio({ apiKey, baseUrl }) {
-  if (typeof window === "undefined" || !apiKey) {
+  if (typeof window === "undefined") {
     return {
       stream: () => {
       },
       play: () => __async(this, null, function* () {
       }),
+      download: () => null,
+      isConnected: false,
       isPlaying: false,
+      isStreamed: false,
       chunks: [],
       messages: []
     };
   }
   const audio = useMemo(() => {
+    if (!apiKey) {
+      return null;
+    }
     const audio2 = new audio_default({ apiKey, baseUrl });
     return audio2;
   }, [apiKey, baseUrl]);
   const streamReturn = useRef(null);
+  const [isStreamed, setIsStreamed] = useState(false);
   const [isPlaying, setIsPlaying] = useState(false);
+  const [isConnected, setIsConnected] = useState(false);
   const [chunks, setChunks] = useState([]);
   const [messages, setMessages] = useState([]);
   const stream = useCallback(
-    (options) => {
+    (options) => __async(this, null, function* () {
       var _a;
       streamReturn.current = (_a = audio == null ? void 0 : audio.stream(options)) != null ? _a : null;
+      if (!streamReturn.current) {
+        return;
+      }
+      setMessages([]);
       streamReturn.current.on(
         "chunk",
-        ({ chunks: chunks2 }) => {
-          setChunks(chunks2);
+        ({ chunks: chunks3 }) => {
+          setChunks(chunks3);
         }
       );
       streamReturn.current.on(
@@ -45,23 +61,46 @@ function useAudio({ apiKey, baseUrl }) {
           setMessages((messages2) => [...messages2, message]);
         }
       );
-    },
+      const { chunks: chunks2 } = yield streamReturn.current.once("streamed");
+      setChunks(chunks2);
+      setIsStreamed(true);
+    }),
     [audio]
   );
+  const download = useCallback(() => {
+    if (!isStreamed) {
+      return null;
+    }
+    const audio2 = bufferToWav(SAMPLE_RATE, [base64ToArray(chunks)]);
+    return new Blob([audio2], { type: "audio/wav" });
+  }, [isStreamed, chunks]);
   useEffect(() => {
-    function initialize() {
+    let cleanup = () => {
+    };
+    function setupConnection() {
       return __async(this, null, function* () {
         try {
-          yield audio == null ? void 0 : audio.connect();
+          const connection = yield audio == null ? void 0 : audio.connect();
+          if (!connection) {
+            return;
+          }
+          setIsConnected(true);
+          const unsubscribe = connection.on("close", () => {
+            setIsConnected(false);
+          });
+          return () => {
+            unsubscribe();
+            audio == null ? void 0 : audio.disconnect();
+          };
         } catch (e) {
           console.error(e);
         }
-        return () => {
-          audio == null ? void 0 : audio.disconnect();
-        };
       });
     }
-    initialize();
+    setupConnection().then((cleanupConnection) => {
+      cleanup = cleanupConnection;
+    });
+    return () => cleanup == null ? void 0 : cleanup();
   }, [audio]);
   const play = useCallback(
     (bufferDuration = 0) => __async(this, null, function* () {
@@ -75,7 +114,16 @@ function useAudio({ apiKey, baseUrl }) {
     }),
     [isPlaying]
   );
-  return { stream, play, isPlaying, chunks, messages };
+  return {
+    stream,
+    play,
+    download,
+    isPlaying,
+    isConnected,
+    isStreamed,
+    chunks,
+    messages
+  };
 }
 export {
   useAudio

package/package.json

@@ -4,7 +4,7 @@
 		"name": "Cartesia",
 		"url": "https://cartesia.ai"
 	},
-	"version": "0.0.1",
+	"version": "0.0.2",
 	"description": "Client for the Cartesia API.",
 	"main": "./dist/index.js",
 	"module": "./dist/index.mjs",
@@ -22,13 +22,14 @@
 	"dependencies": {
 		"base64-js": "^1.5.1",
 		"emittery": "^1.0.3",
-		"human-id": "^4.1.1"
+		"human-id": "^4.1.1",
+		"partysocket": "^1.0.1"
 	},
 	"publishConfig": {
-		"access": "restricted"
+		"access": "public"
 	},
 	"scripts": {
-		"build": "tsup src/ --format cjs,esm --dts --clean",
+		"build": "tsup src/ --format cjs,esm --dts",
 		"dev": "bun run build -- --watch"
 	},
 	"peerDependencies": {

package/src/audio/index.ts

@@ -1,11 +1,14 @@
 import Emittery from "emittery";
 import { humanId } from "human-id";
+import { WebSocket } from "partysocket";
 import { Client } from "../lib/client";
 import { SAMPLE_RATE, constructWebsocketUrl } from "../lib/constants";
 import {
+	type EmitteryCallbacks,
 	type Sentinel,
 	createMessageHandlerForContextId,
 	getBufferDuration,
+	getEmitteryCallbacks,
 	isComplete,
 	isSentinel,
 	playAudioBuffer,
@@ -17,8 +20,22 @@ export type StreamEventData = {
 		chunk: Chunk;
 		chunks: Chunk[];
 	};
+	streamed: {
+		chunks: Chunk[];
+	};
 	message: unknown;
 };
+export type ConnectionEventData = {
+	open: never;
+	close: never;
+};
+export type StreamRequest = {
+	inputs: object;
+	options: {
+		timeout?: number;
+	};
+};
+
 export default class extends Client {
 	socket?: WebSocket;
 	isConnected = false;
@@ -35,7 +52,10 @@ export default class extends Client {
 	 * that plays the audio as it arrives, with `bufferDuration` seconds of audio buffered before
 	 * starting playback.
 	 */
-	stream(inputs: object, { timeout = 0 }: { timeout?: number } = {}) {
+	stream(
+		inputs: StreamRequest["inputs"],
+		{ timeout = 0 }: StreamRequest["options"] = {},
+	) {
 		if (!this.isConnected) {
 			throw new Error("Not connected to WebSocket. Call .connect() first.");
 		}
@@ -72,6 +92,9 @@ export default class extends Client {
 				});
 				await emitter.emit("message", message);
 				if (isSentinel(chunk)) {
+					await emitter.emit("streamed", {
+						chunks,
+					});
 					streamCompleteController.abort();
 				} else if (timeoutId) {
 					clearTimeout(timeoutId);
@@ -82,13 +105,28 @@ export default class extends Client {
 		this.socket?.addEventListener("message", handleMessage, {
 			signal: streamCompleteController.signal,
 		});
-		this.socket?.addEventListener("close", streamCompleteController.abort, {
-			once: true,
-		});
-		this.socket?.addEventListener("error", streamCompleteController.abort, {
-			once: true,
-		});
+		this.socket?.addEventListener(
+			"close",
+			() => {
+				streamCompleteController.abort();
+			},
+			{
+				once: true,
+			},
+		);
+		this.socket?.addEventListener(
+			"error",
+			() => {
+				streamCompleteController.abort();
+			},
+			{
+				once: true,
+			},
+		);
 		streamCompleteController.signal.addEventListener("abort", () => {
+			if (timeoutId) {
+				clearTimeout(timeoutId);
+			}
 			emitter.clearListeners();
 		});
 
@@ -158,10 +196,7 @@ export default class extends Client {
 
 		return {
 			play,
-			on: emitter.on.bind(emitter),
-			off: emitter.off.bind(emitter),
-			once: emitter.once.bind(emitter),
-			events: emitter.events.bind(emitter),
+			...getEmitteryCallbacks(emitter),
 		};
 	}
 
@@ -189,48 +224,53 @@ export default class extends Client {
 	connect() {
 		const url = constructWebsocketUrl(this.baseUrl);
 		url.searchParams.set("api_key", this.apiKey);
-		this.socket = new WebSocket(url);
+		const emitter = new Emittery<ConnectionEventData>();
+		this.socket = new WebSocket(url.toString());
 		this.socket.onopen = () => {
 			this.isConnected = true;
+			emitter.emit("open");
 		};
 		this.socket.onclose = () => {
 			this.isConnected = false;
+			emitter.emit("close");
 		};
 
-		return new Promise<void>((resolve, reject) => {
-			this.socket?.addEventListener(
-				"open",
-				() => {
-					resolve();
-				},
-				{
-					once: true,
-				},
-			);
-
-			const aborter = new AbortController();
-			this.socket?.addEventListener(
-				"error",
-				() => {
-					aborter.abort();
-					reject(new Error("WebSocket failed to connect."));
-				},
-				{
-					signal: aborter.signal,
-				},
-			);
-
-			this.socket?.addEventListener(
-				"close",
-				() => {
-					aborter.abort();
-					reject(new Error("WebSocket closed before it could connect."));
-				},
-				{
-					signal: aborter.signal,
-				},
-			);
-		});
+		return new Promise<EmitteryCallbacks<ConnectionEventData>>(
+			(resolve, reject) => {
+				this.socket?.addEventListener(
+					"open",
+					() => {
+						resolve(getEmitteryCallbacks(emitter));
+					},
+					{
+						once: true,
+					},
+				);
+
+				const aborter = new AbortController();
+				this.socket?.addEventListener(
+					"error",
+					() => {
+						aborter.abort();
+						reject(new Error("WebSocket failed to connect."));
+					},
+					{
+						signal: aborter.signal,
+					},
+				);
+
+				this.socket?.addEventListener(
+					"close",
+					() => {
+						aborter.abort();
+						reject(new Error("WebSocket closed before it could connect."));
+					},
+					{
+						signal: aborter.signal,
+					},
+				);
+			},
+		);
 	}
 
 	/**

package/src/audio/utils.ts

@@ -1,4 +1,5 @@
 import base64 from "base64-js";
+import type Emittery from "emittery";
 import type { Chunk, StreamEventData } from ".";
 import { SAMPLE_RATE } from "../lib/constants";
 
@@ -136,3 +137,84 @@ export function filterSentinel<T>(collection: T[]): Exclude<T, Sentinel>[] {
 export function isComplete(chunks: Chunk[]) {
 	return isSentinel(chunks[chunks.length - 1]);
 }
+
+export type EmitteryCallbacks<T> = {
+	on: Emittery<T>["on"];
+	off: Emittery<T>["off"];
+	once: Emittery<T>["once"];
+	events: Emittery<T>["events"];
+};
+/**
+ * Get user-facing emitter callbacks for an Emittery instance.
+ * @param emitter The Emittery instance to get callbacks for.
+ * @returns User-facing emitter callbacks.
+ */
+export function getEmitteryCallbacks<T>(
+	emitter: Emittery<T>,
+): EmitteryCallbacks<T> {
+	return {
+		on: emitter.on.bind(emitter),
+		off: emitter.off.bind(emitter),
+		once: emitter.once.bind(emitter),
+		events: emitter.events.bind(emitter),
+	};
+}
+
+/**
+ * Converts a base64-encoded audio buffer to a WAV file.
+ * Source: https://gist.github.com/Daninet/22edc59cf2aee0b9a90c18e553e49297
+ * @param b64 The base64-encoded audio buffer to convert to a WAV file.
+ */
+export function bufferToWav(
+	sampleRate: number,
+	channelBuffers: Float32Array[],
+) {
+	const totalSamples = channelBuffers[0].length * channelBuffers.length;
+
+	const buffer = new ArrayBuffer(44 + totalSamples * 2);
+	const view = new DataView(buffer);
+
+	const writeString = (view: DataView, offset: number, string: string) => {
+		for (let i = 0; i < string.length; i++) {
+			view.setUint8(offset + i, string.charCodeAt(i));
+		}
+	};
+
+	/* RIFF identifier */
+	writeString(view, 0, "RIFF");
+	/* RIFF chunk length */
+	view.setUint32(4, 36 + totalSamples * 2, true);
+	/* RIFF type */
+	writeString(view, 8, "WAVE");
+	/* format chunk identifier */
+	writeString(view, 12, "fmt ");
+	/* format chunk length */
+	view.setUint32(16, 16, true);
+	/* sample format (raw) */
+	view.setUint16(20, 1, true);
+	/* channel count */
+	view.setUint16(22, channelBuffers.length, true);
+	/* sample rate */
+	view.setUint32(24, sampleRate, true);
+	/* byte rate (sample rate * block align) */
+	view.setUint32(28, sampleRate * 4, true);
+	/* block align (channel count * bytes per sample) */
+	view.setUint16(32, channelBuffers.length * 2, true);
+	/* bits per sample */
+	view.setUint16(34, 16, true);
+	/* data chunk identifier */
+	writeString(view, 36, "data");
+	/* data chunk length */
+	view.setUint32(40, totalSamples * 2, true);
+
+	let offset = 44;
+	for (let i = 0; i < channelBuffers[0].length; i++) {
+		for (let channel = 0; channel < channelBuffers.length; channel++) {
+			const s = Math.max(-1, Math.min(1, channelBuffers[channel][i]));
+			view.setInt16(offset, s < 0 ? s * 0x8000 : s * 0x7fff, true);
+			offset += 2;
+		}
+	}
+
+	return buffer;
+}

package/src/lib/constants.ts

@@ -2,5 +2,5 @@ export const BASE_URL = "https://api.cartesia.ai/v0";
 export const SAMPLE_RATE = 44100;
 
 export const constructWebsocketUrl = (baseUrl: string) => {
-	return new URL(`${baseUrl.replace(/^http/, "ws")}/ws`);
+	return new URL(`${baseUrl.replace(/^http/, "ws")}/audio/websocket`);
 };

package/src/react/index.ts

@@ -1,15 +1,20 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import CartesiaAudio, { type Chunk, type StreamEventData } from "../audio";
+import { base64ToArray, bufferToWav } from "../audio/utils";
+import { SAMPLE_RATE } from "../lib/constants";
 
-interface UseAudioOptions {
-	apiKey: string;
+export type UseAudioOptions = {
+	apiKey: string | null;
 	baseUrl?: string;
-}
+};
 
 interface UseAudioReturn {
 	stream: (options: object) => void;
 	play: (bufferDuration?: number) => Promise<void>;
+	download: () => Blob | null;
 	isPlaying: boolean;
+	isConnected: boolean;
+	isStreamed: boolean;
 	chunks: Chunk[];
 	messages: StreamEventData["message"][];
 }
@@ -17,28 +22,40 @@ interface UseAudioReturn {
  * React hook to use the Cartesia audio API.
  */
 export function useAudio({ apiKey, baseUrl }: UseAudioOptions): UseAudioReturn {
-	if (typeof window === "undefined" || !apiKey) {
+	if (typeof window === "undefined") {
 		return {
 			stream: () => {},
 			play: async () => {},
+			download: () => null,
+			isConnected: false,
 			isPlaying: false,
+			isStreamed: false,
 			chunks: [],
 			messages: [],
 		};
 	}
 
 	const audio = useMemo(() => {
+		if (!apiKey) {
+			return null;
+		}
 		const audio = new CartesiaAudio({ apiKey, baseUrl });
 		return audio;
 	}, [apiKey, baseUrl]);
 	const streamReturn = useRef<ReturnType<CartesiaAudio["stream"]> | null>(null);
+	const [isStreamed, setIsStreamed] = useState(false);
 	const [isPlaying, setIsPlaying] = useState(false);
+	const [isConnected, setIsConnected] = useState(false);
 	const [chunks, setChunks] = useState<Chunk[]>([]);
 	const [messages, setMessages] = useState<StreamEventData["message"][]>([]);
 
 	const stream = useCallback(
-		(options: object) => {
+		async (options: object) => {
 			streamReturn.current = audio?.stream(options) ?? null;
+			if (!streamReturn.current) {
+				return;
+			}
+			setMessages([]);
 			streamReturn.current.on(
 				"chunk",
 				({ chunks }: StreamEventData["chunk"]) => {
@@ -51,22 +68,45 @@ export function useAudio({ apiKey, baseUrl }: UseAudioOptions): UseAudioReturn {
 					setMessages((messages) => [...messages, message]);
 				},
 			);
+			const { chunks } = await streamReturn.current.once("streamed");
+			setChunks(chunks);
+			setIsStreamed(true);
 		},
 		[audio],
 	);
 
+	const download = useCallback(() => {
+		if (!isStreamed) {
+			return null;
+		}
+		const audio = bufferToWav(SAMPLE_RATE, [base64ToArray(chunks)]);
+		return new Blob([audio], { type: "audio/wav" });
+	}, [isStreamed, chunks]);
+
 	useEffect(() => {
-		async function initialize() {
+		let cleanup: (() => void) | undefined = () => {};
+		async function setupConnection() {
 			try {
-				await audio?.connect();
+				const connection = await audio?.connect();
+				if (!connection) {
+					return;
+				}
+				setIsConnected(true);
+				const unsubscribe = connection.on("close", () => {
+					setIsConnected(false);
+				});
+				return () => {
+					unsubscribe();
+					audio?.disconnect();
+				};
 			} catch (e) {
 				console.error(e);
 			}
-			return () => {
-				audio?.disconnect();
-			};
 		}
-		initialize();
+		setupConnection().then((cleanupConnection) => {
+			cleanup = cleanupConnection;
+		});
+		return () => cleanup?.();
 	}, [audio]);
 
 	const play = useCallback(
@@ -87,5 +127,14 @@ export function useAudio({ apiKey, baseUrl }: UseAudioOptions): UseAudioReturn {
 	// - [] Seek to a specific time.
 	// These are probably best implemented by adding event listener
 	// functionality to the base library.
-	return { stream, play, isPlaying, chunks, messages };
+	return {
+		stream,
+		play,
+		download,
+		isPlaying,
+		isConnected,
+		isStreamed,
+		chunks,
+		messages,
+	};
 }