@cartesia/cartesia-js 1.0.0 → 1.0.2

package/dist/types/index.d.cts

@@ -1,7 +1,7 @@
 import emittery__default from 'emittery';
 
 interface ClientOptions {
-    apiKey?: string;
+    apiKey?: string | (() => Promise<string>);
     baseUrl?: string;
 }
 type Sentinel = null;
@@ -10,12 +10,64 @@ type ConnectionEventData = {
     open: never;
     close: never;
 };
+type VoiceSpecifier = {
+    mode: "id";
+    id: string;
+} | {
+    mode: "embedding";
+    embedding: number[];
+};
+type Emotion = "anger" | "sadness" | "positivity" | "curiosity" | "surprise";
+type Intensity = "lowest" | "low" | "high" | "highest";
+type EmotionControl = Emotion | `${Emotion}:${Intensity}`;
+type VoiceOptions = VoiceSpecifier & {
+    __experimental_controls?: {
+        speed?: "slowest" | "slow" | "normal" | "fast" | "fastest";
+        emotion?: EmotionControl[];
+    };
+};
 type StreamRequest = {
-    inputs: object;
-    options: {
-        timeout?: number;
+    model_id: string;
+    transcript: string;
+    voice: VoiceOptions;
+    output_format?: {
+        container: string;
+        encoding: string;
+        sample_rate: number;
     };
+    context_id?: string;
+    continue?: boolean;
+    duration?: number;
+    language?: string;
+    add_timestamps?: boolean;
+};
+type StreamOptions = {
+    timeout?: number;
+};
+type WebSocketBaseResponse = {
+    context_id: string;
+    status_code: number;
+    done: boolean;
+};
+type WordTimestamps = {
+    words: string[];
+    start: number[];
+    end: number[];
+};
+type WebSocketTimestampsResponse = WebSocketBaseResponse & {
+    type: "timestamps";
+    word_timestamps: WordTimestamps;
+};
+type WebSocketChunkResponse = WebSocketBaseResponse & {
+    type: "chunk";
+    data: string;
+    step_time: number;
+};
+type WebSocketErrorResponse = WebSocketBaseResponse & {
+    type: "error";
+    error: string;
 };
+type WebSocketResponse = WebSocketTimestampsResponse | WebSocketChunkResponse | WebSocketErrorResponse;
 type EmitteryCallbacks<T> = {
     on: emittery__default<T>["on"];
     off: emittery__default<T>["off"];
@@ -25,9 +77,11 @@ type EmitteryCallbacks<T> = {
 type CloneOptions = {
     mode: "url";
     link: string;
+    enhance?: boolean;
 } | {
     mode: "clip";
     clip: Blob;
+    enhance?: boolean;
 };
 type Voice = {
     id: string;
@@ -37,12 +91,16 @@ type Voice = {
     is_public: boolean;
     user_id: string;
     created_at: string;
+    language: string;
 };
 type CreateVoice = Pick<Voice, "name" | "description" | "embedding"> & Partial<Omit<Voice, "name" | "description" | "embedding">>;
+type UpdateVoice = Partial<Pick<Voice, "name" | "description" | "embedding">>;
 type CloneResponse = {
     embedding: number[];
 };
 type WebSocketOptions = {
+    container?: string;
+    encoding?: string;
     sampleRate: number;
 };
 type SourceEventData = {
@@ -51,5 +109,7 @@ type SourceEventData = {
     wait: never;
     read: never;
 };
+type TypedArray = Float32Array | Int16Array | Uint8Array;
+type Encoding = "pcm_f32le" | "pcm_s16le" | "pcm_alaw" | "pcm_mulaw";
 
-export type { Chunk, ClientOptions, CloneOptions, CloneResponse, ConnectionEventData, CreateVoice, EmitteryCallbacks, Sentinel, SourceEventData, StreamRequest, Voice, WebSocketOptions };
+export type { Chunk, ClientOptions, CloneOptions, CloneResponse, ConnectionEventData, CreateVoice, EmitteryCallbacks, Emotion, EmotionControl, Encoding, Intensity, Sentinel, SourceEventData, StreamOptions, StreamRequest, TypedArray, UpdateVoice, Voice, VoiceOptions, VoiceSpecifier, WebSocketBaseResponse, WebSocketChunkResponse, WebSocketErrorResponse, WebSocketOptions, WebSocketResponse, WebSocketTimestampsResponse, WordTimestamps };

package/dist/types/index.d.ts

@@ -1,7 +1,7 @@
 import emittery__default from 'emittery';
 
 interface ClientOptions {
-    apiKey?: string;
+    apiKey?: string | (() => Promise<string>);
     baseUrl?: string;
 }
 type Sentinel = null;
@@ -10,12 +10,64 @@ type ConnectionEventData = {
     open: never;
     close: never;
 };
+type VoiceSpecifier = {
+    mode: "id";
+    id: string;
+} | {
+    mode: "embedding";
+    embedding: number[];
+};
+type Emotion = "anger" | "sadness" | "positivity" | "curiosity" | "surprise";
+type Intensity = "lowest" | "low" | "high" | "highest";
+type EmotionControl = Emotion | `${Emotion}:${Intensity}`;
+type VoiceOptions = VoiceSpecifier & {
+    __experimental_controls?: {
+        speed?: "slowest" | "slow" | "normal" | "fast" | "fastest";
+        emotion?: EmotionControl[];
+    };
+};
 type StreamRequest = {
-    inputs: object;
-    options: {
-        timeout?: number;
+    model_id: string;
+    transcript: string;
+    voice: VoiceOptions;
+    output_format?: {
+        container: string;
+        encoding: string;
+        sample_rate: number;
     };
+    context_id?: string;
+    continue?: boolean;
+    duration?: number;
+    language?: string;
+    add_timestamps?: boolean;
+};
+type StreamOptions = {
+    timeout?: number;
+};
+type WebSocketBaseResponse = {
+    context_id: string;
+    status_code: number;
+    done: boolean;
+};
+type WordTimestamps = {
+    words: string[];
+    start: number[];
+    end: number[];
+};
+type WebSocketTimestampsResponse = WebSocketBaseResponse & {
+    type: "timestamps";
+    word_timestamps: WordTimestamps;
+};
+type WebSocketChunkResponse = WebSocketBaseResponse & {
+    type: "chunk";
+    data: string;
+    step_time: number;
+};
+type WebSocketErrorResponse = WebSocketBaseResponse & {
+    type: "error";
+    error: string;
 };
+type WebSocketResponse = WebSocketTimestampsResponse | WebSocketChunkResponse | WebSocketErrorResponse;
 type EmitteryCallbacks<T> = {
     on: emittery__default<T>["on"];
     off: emittery__default<T>["off"];
@@ -25,9 +77,11 @@ type EmitteryCallbacks<T> = {
 type CloneOptions = {
     mode: "url";
     link: string;
+    enhance?: boolean;
 } | {
     mode: "clip";
     clip: Blob;
+    enhance?: boolean;
 };
 type Voice = {
     id: string;
@@ -37,12 +91,16 @@ type Voice = {
     is_public: boolean;
     user_id: string;
     created_at: string;
+    language: string;
 };
 type CreateVoice = Pick<Voice, "name" | "description" | "embedding"> & Partial<Omit<Voice, "name" | "description" | "embedding">>;
+type UpdateVoice = Partial<Pick<Voice, "name" | "description" | "embedding">>;
 type CloneResponse = {
     embedding: number[];
 };
 type WebSocketOptions = {
+    container?: string;
+    encoding?: string;
     sampleRate: number;
 };
 type SourceEventData = {
@@ -51,5 +109,7 @@ type SourceEventData = {
     wait: never;
     read: never;
 };
+type TypedArray = Float32Array | Int16Array | Uint8Array;
+type Encoding = "pcm_f32le" | "pcm_s16le" | "pcm_alaw" | "pcm_mulaw";
 
-export type { Chunk, ClientOptions, CloneOptions, CloneResponse, ConnectionEventData, CreateVoice, EmitteryCallbacks, Sentinel, SourceEventData, StreamRequest, Voice, WebSocketOptions };
+export type { Chunk, ClientOptions, CloneOptions, CloneResponse, ConnectionEventData, CreateVoice, EmitteryCallbacks, Emotion, EmotionControl, Encoding, Intensity, Sentinel, SourceEventData, StreamOptions, StreamRequest, TypedArray, UpdateVoice, Voice, VoiceOptions, VoiceSpecifier, WebSocketBaseResponse, WebSocketChunkResponse, WebSocketErrorResponse, WebSocketOptions, WebSocketResponse, WebSocketTimestampsResponse, WordTimestamps };

package/dist/voices/index.cjs

@@ -88,20 +88,25 @@ var constructApiUrl = (baseUrl, path, { websocket = false } = {}) => {
 // src/lib/client.ts
 var Client = class {
   constructor(options = {}) {
-    if (!(options.apiKey || process.env.CARTESIA_API_KEY)) {
+    const apiKey = options.apiKey || process.env.CARTESIA_API_KEY;
+    if (!apiKey) {
       throw new Error("Missing Cartesia API key.");
     }
-    this.apiKey = options.apiKey || process.env.CARTESIA_API_KEY;
+    this.apiKey = typeof apiKey === "function" ? apiKey : () => __async(this, null, function* () {
+      return apiKey;
+    });
     this.baseUrl = options.baseUrl || BASE_URL;
   }
-  fetch(path, options = {}) {
-    const url = constructApiUrl(this.baseUrl, path);
-    return (0, import_cross_fetch.default)(url.toString(), __spreadProps(__spreadValues({}, options), {
-      headers: __spreadValues({
-        "X-API-Key": this.apiKey,
-        "Cartesia-Version": CARTESIA_VERSION
-      }, options.headers)
-    }));
+  _fetch(_0) {
+    return __async(this, arguments, function* (path, options = {}) {
+      const url = constructApiUrl(this.baseUrl, path);
+      const headers = new Headers(options.headers);
+      headers.set("X-API-Key", yield this.apiKey());
+      headers.set("Cartesia-Version", CARTESIA_VERSION);
+      return (0, import_cross_fetch.default)(url.toString(), __spreadProps(__spreadValues({}, options), {
+        headers
+      }));
+    });
   }
 };
 
@@ -109,40 +114,43 @@ var Client = class {
 var Voices = class extends Client {
   list() {
     return __async(this, null, function* () {
-      const response = yield this.fetch("/voices");
+      const response = yield this._fetch("/voices");
       return response.json();
     });
   }
   get(voiceId) {
     return __async(this, null, function* () {
-      const response = yield this.fetch(`/voices/${voiceId}`);
+      const response = yield this._fetch(`/voices/${voiceId}`);
       return response.json();
     });
   }
   create(voice) {
     return __async(this, null, function* () {
-      const response = yield this.fetch("/voices", {
+      const response = yield this._fetch("/voices", {
         method: "POST",
         body: JSON.stringify(voice)
       });
       return response.json();
     });
   }
+  update(id, voice) {
+    return __async(this, null, function* () {
+      const response = yield this._fetch(`/voices/${id}`, {
+        method: "PATCH",
+        body: JSON.stringify(voice)
+      });
+      return response.json();
+    });
+  }
   clone(options) {
     return __async(this, null, function* () {
-      if (options.mode === "url") {
-        const response = yield this.fetch(
-          `/voices/clone/url?link=${options.link}`,
-          {
-            method: "POST"
-          }
-        );
-        return response.json();
-      }
       if (options.mode === "clip") {
         const formData = new FormData();
         formData.append("clip", options.clip);
-        const response = yield this.fetch("/voices/clone/clip", {
+        if (options.enhance !== void 0) {
+          formData.append("enhance", options.enhance.toString());
+        }
+        const response = yield this._fetch("/voices/clone/clip", {
           method: "POST",
           body: formData
         });

package/dist/voices/index.d.cts

@@ -1,11 +1,12 @@
 import { Client } from '../lib/client.cjs';
-import { Voice, CreateVoice, CloneOptions, CloneResponse } from '../types/index.cjs';
+import { Voice, CreateVoice, UpdateVoice, CloneOptions, CloneResponse } from '../types/index.cjs';
 import 'emittery';
 
 declare class Voices extends Client {
     list(): Promise<Voice[]>;
     get(voiceId: string): Promise<Voice>;
     create(voice: CreateVoice): Promise<Voice>;
+    update(id: string, voice: UpdateVoice): Promise<Voice>;
     clone(options: CloneOptions): Promise<CloneResponse>;
 }
 

package/dist/voices/index.d.ts

@@ -1,11 +1,12 @@
 import { Client } from '../lib/client.js';
-import { Voice, CreateVoice, CloneOptions, CloneResponse } from '../types/index.js';
+import { Voice, CreateVoice, UpdateVoice, CloneOptions, CloneResponse } from '../types/index.js';
 import 'emittery';
 
 declare class Voices extends Client {
     list(): Promise<Voice[]>;
     get(voiceId: string): Promise<Voice>;
     create(voice: CreateVoice): Promise<Voice>;
+    update(id: string, voice: UpdateVoice): Promise<Voice>;
     clone(options: CloneOptions): Promise<CloneResponse>;
 }
 

package/dist/voices/index.js

@@ -1,9 +1,9 @@
 import {
   Voices
-} from "../chunk-SGXUEFII.js";
-import "../chunk-PQ5EVEEH.js";
+} from "../chunk-UCYL2SOX.js";
+import "../chunk-PISCPZK4.js";
 import "../chunk-2BFEKY3F.js";
-import "../chunk-WIFMLPT5.js";
+import "../chunk-GHY2WEOK.js";
 export {
   Voices as default
 };

package/package.json

@@ -4,7 +4,7 @@
 		"name": "Cartesia",
 		"url": "https://cartesia.ai"
 	},
-	"version": "1.0.0",
+	"version": "1.0.2",
 	"description": "Client for the Cartesia API.",
 	"type": "module",
 	"module": "./dist/index.js",

package/src/index.ts

@@ -2,3 +2,5 @@ export { Cartesia as default } from "./lib";
 export * from "./lib";
 export * from "./types";
 export { default as WebPlayer } from "./tts/player";
+export { default as Source } from "./tts/source";
+export { default as WebSocket } from "./tts/websocket";

package/src/lib/client.ts

@@ -3,29 +3,29 @@ import type { ClientOptions } from "../types";
 import { BASE_URL, CARTESIA_VERSION, constructApiUrl } from "./constants";
 
 export class Client {
-	apiKey: string;
+	apiKey: () => Promise<string>;
 	baseUrl: string;
 
 	constructor(options: ClientOptions = {}) {
-		if (!(options.apiKey || process.env.CARTESIA_API_KEY)) {
+		const apiKey = options.apiKey || process.env.CARTESIA_API_KEY;
+		if (!apiKey) {
 			throw new Error("Missing Cartesia API key.");
 		}
 
-		// biome-ignore lint/style/noNonNullAssertion: Guaranteed to be defined by the check above.
-		this.apiKey = (options.apiKey || process.env.CARTESIA_API_KEY)!;
+		this.apiKey = typeof apiKey === "function" ? apiKey : async () => apiKey;
 		this.baseUrl = options.baseUrl || BASE_URL;
 	}
 
-	fetch(path: string, options: RequestInit = {}) {
+	protected async _fetch(path: string, options: RequestInit = {}) {
 		const url = constructApiUrl(this.baseUrl, path);
+		const headers = new Headers(options.headers);
+
+		headers.set("X-API-Key", await this.apiKey());
+		headers.set("Cartesia-Version", CARTESIA_VERSION);
 
 		return fetch(url.toString(), {
 			...options,
-			headers: {
-				"X-API-Key": this.apiKey,
-				"Cartesia-Version": CARTESIA_VERSION,
-				...options.headers,
-			},
+			headers,
 		});
 	}
 }

package/src/react/index.ts

@@ -4,12 +4,14 @@ import { Cartesia } from "../lib";
 import Player from "../tts/player";
 import type Source from "../tts/source";
 import type WebSocket from "../tts/websocket";
+import type { StreamRequest } from "../types";
 import { pingServer } from "./utils";
 
 export type UseTTSOptions = {
-	apiKey: string | null;
+	apiKey: string | (() => Promise<string>) | null;
 	baseUrl?: string;
 	sampleRate: number;
+	onError?: (error: Error) => void;
 };
 
 export type PlaybackStatus = "inactive" | "playing" | "paused" | "finished";
@@ -20,7 +22,7 @@ export type Metrics = {
 };
 
 export interface UseTTSReturn {
-	buffer: (options: object) => Promise<void>;
+	buffer: (options: StreamRequest) => Promise<void>;
 	play: (bufferDuration?: number) => Promise<void>;
 	pause: () => Promise<void>;
 	resume: () => Promise<void>;
@@ -47,6 +49,7 @@ export function useTTS({
 	apiKey,
 	baseUrl,
 	sampleRate,
+	onError,
 }: UseTTSOptions): UseTTSReturn {
 	if (typeof window === "undefined") {
 		return {
@@ -72,7 +75,11 @@ export function useTTS({
 		}
 		const cartesia = new Cartesia({ apiKey, baseUrl });
 		baseUrl = baseUrl ?? cartesia.baseUrl;
-		return cartesia.tts.websocket({ sampleRate });
+		return cartesia.tts.websocket({
+			container: "raw",
+			encoding: "pcm_f32le",
+			sampleRate,
+		});
 	}, [apiKey, baseUrl, sampleRate]);
 	const websocketReturn = useRef<ReturnType<WebSocket["send"]> | null>(null);
 	const player = useRef<Player | null>(null);
@@ -85,23 +92,35 @@ export function useTTS({
 	const [messages, setMessages] = useState<Message[]>([]);
 
 	const buffer = useCallback(
-		async (options: object) => {
+		async (options: StreamRequest) => {
 			websocketReturn.current?.stop(); // Abort the previous request if it exists.
 
-			setMessages([]);
-			setBufferStatus("buffering");
-			websocketReturn.current = websocket?.send(options) ?? null;
-			if (!websocketReturn.current) {
-				return;
+			try {
+				setMessages([]);
+				setBufferStatus("buffering");
+				websocketReturn.current = websocket?.send(options) ?? null;
+				if (!websocketReturn.current) {
+					return;
+				}
+				const unsubscribe = websocketReturn.current.on("message", (message) => {
+					const parsedMessage = JSON.parse(message);
+					setMessages((messages) => [...messages, parsedMessage]);
+					if (parsedMessage.error) {
+						onError?.(new Error(parsedMessage.error));
+					}
+				});
+				await websocketReturn.current.source.once("close");
+				setBufferStatus("buffered");
+				unsubscribe();
+			} catch (error) {
+				if (error instanceof Error) {
+					onError?.(error);
+				} else {
+					console.error(error);
+				}
 			}
-			const unsubscribe = websocketReturn.current.on("message", (message) => {
-				setMessages((messages) => [...messages, JSON.parse(message)]);
-			});
-			await websocketReturn.current.source.once("close");
-			setBufferStatus("buffered");
-			unsubscribe();
 		},
-		[websocket],
+		[websocket, onError],
 	);
 
 	const metrics = useMemo(() => {
@@ -173,64 +192,96 @@ export function useTTS({
 	}, [websocket, baseUrl]);
 
 	const play = useCallback(async () => {
-		if (playbackStatus === "playing" || !websocketReturn.current) {
-			return;
-		}
-		if (player.current) {
-			// Stop the current player if it exists.
-			await player.current.stop();
-		}
+		try {
+			if (playbackStatus === "playing" || !websocketReturn.current) {
+				return;
+			}
+			if (player.current) {
+				// Stop the current player if it exists.
+				await player.current.stop();
+			}
 
-		setPlaybackStatus("playing");
-
-		const unsubscribes = [];
-		unsubscribes.push(
-			websocketReturn.current.source.on("wait", () => {
-				setIsWaiting(true);
-			}),
-		);
-		unsubscribes.push(
-			websocketReturn.current.source.on("read", () => {
-				setIsWaiting(false);
-			}),
-		);
-
-		player.current = new Player({
-			bufferDuration: bufferDuration ?? DEFAULT_BUFFER_DURATION,
-		});
-		// Wait for the playback to finish before setting isPlaying to false.
-		await player.current.play(websocketReturn.current.source);
+			setPlaybackStatus("playing");
 
-		for (const unsubscribe of unsubscribes) {
-			// Deregister the event listeners (.on()) that we registered above to avoid memory leaks.
-			unsubscribe();
-		}
+			const unsubscribes = [];
+			unsubscribes.push(
+				websocketReturn.current.source.on("wait", () => {
+					setIsWaiting(true);
+				}),
+			);
+			unsubscribes.push(
+				websocketReturn.current.source.on("read", () => {
+					setIsWaiting(false);
+				}),
+			);
 
-		setPlaybackStatus("finished");
-	}, [playbackStatus, bufferDuration]);
+			player.current = new Player({
+				bufferDuration: bufferDuration ?? DEFAULT_BUFFER_DURATION,
+			});
+			// Wait for the playback to finish before setting isPlaying to false.
+			await player.current.play(websocketReturn.current.source);
+
+			for (const unsubscribe of unsubscribes) {
+				// Deregister the event listeners (.on()) that we registered above to avoid memory leaks.
+				unsubscribe();
+			}
+
+			setPlaybackStatus("finished");
+		} catch (error) {
+			if (error instanceof Error) {
+				onError?.(error);
+			} else {
+				console.error(error);
+			}
+		}
+	}, [playbackStatus, bufferDuration, onError]);
 
 	const pause = useCallback(async () => {
-		await player.current?.pause();
-		setPlaybackStatus("paused");
-	}, []);
+		try {
+			await player.current?.pause();
+			setPlaybackStatus("paused");
+		} catch (error) {
+			if (error instanceof Error) {
+				onError?.(error);
+			} else {
+				console.error(error);
+			}
+		}
+	}, [onError]);
 
 	const resume = useCallback(async () => {
-		await player.current?.resume();
-		setPlaybackStatus("playing");
-	}, []);
+		try {
+			await player.current?.resume();
+			setPlaybackStatus("playing");
+		} catch (error) {
+			if (error instanceof Error) {
+				onError?.(error);
+			} else {
+				console.error(error);
+			}
+		}
+	}, [onError]);
 
 	const toggle = useCallback(async () => {
-		await player.current?.toggle();
-		setPlaybackStatus((status) => {
-			if (status === "playing") {
-				return "paused";
-			}
-			if (status === "paused") {
-				return "playing";
+		try {
+			await player.current?.toggle();
+			setPlaybackStatus((status) => {
+				if (status === "playing") {
+					return "paused";
+				}
+				if (status === "paused") {
+					return "playing";
+				}
+				return status;
+			});
+		} catch (error) {
+			if (error instanceof Error) {
+				onError?.(error);
+			} else {
+				console.error(error);
 			}
-			return status;
-		});
-	}, []);
+		}
+	}, [onError]);
 
 	return {
 		buffer,