@cartesia/cartesia-js 1.3.0 → 2.0.0

package/dist/voices/index.cjs

@@ -1,180 +0,0 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __defProps = Object.defineProperties;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropSymbols = Object.getOwnPropertySymbols;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __propIsEnum = Object.prototype.propertyIsEnumerable;
-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 = {}))
-    if (__hasOwnProp.call(b, prop))
-      __defNormalProp(a, prop, b[prop]);
-  if (__getOwnPropSymbols)
-    for (var prop of __getOwnPropSymbols(b)) {
-      if (__propIsEnum.call(b, prop))
-        __defNormalProp(a, prop, b[prop]);
-    }
-  return a;
-};
-var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var __async = (__this, __arguments, generator) => {
-  return new Promise((resolve, reject) => {
-    var fulfilled = (value) => {
-      try {
-        step(generator.next(value));
-      } catch (e) {
-        reject(e);
-      }
-    };
-    var rejected = (value) => {
-      try {
-        step(generator.throw(value));
-      } catch (e) {
-        reject(e);
-      }
-    };
-    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
-    step((generator = generator.apply(__this, __arguments)).next());
-  });
-};
-
-// src/voices/index.ts
-var voices_exports = {};
-__export(voices_exports, {
-  default: () => Voices
-});
-module.exports = __toCommonJS(voices_exports);
-
-// src/lib/client.ts
-var import_cross_fetch = __toESM(require("cross-fetch"), 1);
-
-// src/lib/constants.ts
-var BASE_URL = "https://api.cartesia.ai";
-var CARTESIA_VERSION = "2024-06-10";
-var constructApiUrl = (baseUrl, path, { websocket = false } = {}) => {
-  const url = new URL(path, baseUrl);
-  if (websocket) {
-    url.protocol = baseUrl.replace(/^http/, "ws");
-  }
-  return url;
-};
-
-// src/lib/client.ts
-var Client = class {
-  constructor(options = {}) {
-    const apiKey = options.apiKey || process.env.CARTESIA_API_KEY;
-    if (!apiKey) {
-      throw new Error("Missing Cartesia API key.");
-    }
-    this.apiKey = typeof apiKey === "function" ? apiKey : () => __async(this, null, function* () {
-      return apiKey;
-    });
-    this.baseUrl = options.baseUrl || BASE_URL;
-  }
-  _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
-      }));
-    });
-  }
-};
-
-// src/voices/index.ts
-var Voices = class extends Client {
-  list() {
-    return __async(this, null, function* () {
-      const response = yield this._fetch("/voices");
-      return response.json();
-    });
-  }
-  get(voiceId) {
-    return __async(this, null, function* () {
-      const response = yield this._fetch(`/voices/${voiceId}`);
-      return response.json();
-    });
-  }
-  create(voice) {
-    return __async(this, null, function* () {
-      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 === "clip") {
-        const formData = new FormData();
-        formData.append("clip", options.clip);
-        if (options.enhance !== void 0) {
-          formData.append("enhance", options.enhance.toString());
-        }
-        const response = yield this._fetch("/voices/clone/clip", {
-          method: "POST",
-          body: formData
-        });
-        return response.json();
-      }
-      throw new Error("Invalid mode for clone()");
-    });
-  }
-  mix(options) {
-    return __async(this, null, function* () {
-      const response = yield this._fetch("/voices/mix", {
-        method: "POST",
-        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/voices/index.d.cts

@@ -1,16 +0,0 @@
-import { Client } from '../lib/client.cjs';
-import { Voice, CreateVoice, UpdateVoice, CloneOptions, CloneResponse, MixVoicesOptions, MixVoicesResponse, LocalizeOptions, LocalizeResponse } from '../types/index.cjs';
-import 'emittery';
-import 'partysocket/ws';
-
-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>;
-    mix(options: MixVoicesOptions): Promise<MixVoicesResponse>;
-    localize(options: LocalizeOptions): Promise<LocalizeResponse>;
-}
-
-export { Voices as default };

package/dist/voices/index.d.ts

@@ -1,16 +0,0 @@
-import { Client } from '../lib/client.js';
-import { Voice, CreateVoice, UpdateVoice, CloneOptions, CloneResponse, MixVoicesOptions, MixVoicesResponse, LocalizeOptions, LocalizeResponse } from '../types/index.js';
-import 'emittery';
-import 'partysocket/ws';
-
-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>;
-    mix(options: MixVoicesOptions): Promise<MixVoicesResponse>;
-    localize(options: LocalizeOptions): Promise<LocalizeResponse>;
-}
-
-export { Voices as default };

package/dist/voices/index.js

@@ -1,9 +0,0 @@
-import {
-  Voices
-} from "../chunk-RJICGVPL.js";
-import "../chunk-FLWYXP5Z.js";
-import "../chunk-2BFEKY3F.js";
-import "../chunk-NJDRWDQ3.js";
-export {
-  Voices as default
-};

package/src/index.ts

@@ -1,6 +0,0 @@
-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

@@ -1,31 +0,0 @@
-import fetch from "cross-fetch";
-import type { ClientOptions } from "../types";
-import { BASE_URL, CARTESIA_VERSION, constructApiUrl } from "./constants";
-
-export class Client {
-	apiKey: () => Promise<string>;
-	baseUrl: string;
-
-	constructor(options: ClientOptions = {}) {
-		const apiKey = options.apiKey || process.env.CARTESIA_API_KEY;
-		if (!apiKey) {
-			throw new Error("Missing Cartesia API key.");
-		}
-
-		this.apiKey = typeof apiKey === "function" ? apiKey : async () => apiKey;
-		this.baseUrl = options.baseUrl || BASE_URL;
-	}
-
-	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,
-		});
-	}
-}

package/src/lib/constants.ts

@@ -1,25 +0,0 @@
-export const BASE_URL = "https://api.cartesia.ai";
-export const CARTESIA_VERSION = "2024-06-10";
-
-/**
- * Construct a URL for the Cartesia API.
- *
- * @param baseUrl The base URL for the API.
- * @param path The path to append to the base URL.
- * @param options Options for the URL.
- * @param options.websocket Whether to use the WebSocket protocol.
- * @returns A URL object.
- */
-export const constructApiUrl = (
-	baseUrl: string,
-	path: string,
-	{ websocket = false } = {},
-) => {
-	const url = new URL(path, baseUrl);
-	if (websocket) {
-		// Using find-and-replace ensures that if the base URL uses TLS, the
-		// new protocol does too.
-		url.protocol = baseUrl.replace(/^http/, "ws");
-	}
-	return url;
-};

package/src/lib/index.ts

@@ -1,19 +0,0 @@
-import TTS from "../tts";
-import type { ClientOptions } from "../types";
-import VoiceChanger from "../voice-changer";
-import Voices from "../voices";
-import { Client } from "./client";
-
-export class Cartesia extends Client {
-	tts: TTS;
-	voices: Voices;
-	voiceChanger: VoiceChanger;
-
-	constructor(options: ClientOptions = {}) {
-		super(options);
-
-		this.tts = new TTS(options);
-		this.voices = new Voices(options);
-		this.voiceChanger = new VoiceChanger(options);
-	}
-}

package/src/react/index.ts

@@ -1,303 +0,0 @@
-import type { UnsubscribeFunction } from "emittery";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-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 | (() => Promise<string>) | null;
-	baseUrl?: string;
-	sampleRate: number;
-	onError?: (error: Error) => void;
-};
-
-export type PlaybackStatus = "inactive" | "playing" | "paused" | "finished";
-export type BufferStatus = "inactive" | "buffering" | "buffered";
-
-export type Metrics = {
-	modelLatency: number | null;
-};
-
-export interface UseTTSReturn {
-	buffer: (options: StreamRequest) => Promise<void>;
-	play: (bufferDuration?: number) => Promise<void>;
-	pause: () => Promise<void>;
-	resume: () => Promise<void>;
-	toggle: () => Promise<void>;
-	source: Source | null;
-	playbackStatus: PlaybackStatus;
-	bufferStatus: BufferStatus;
-	isWaiting: boolean;
-	isConnected: boolean;
-	metrics: Metrics;
-}
-
-const PING_INTERVAL = 5000;
-const DEFAULT_BUFFER_DURATION = 0.01;
-
-type Message = {
-	step_time: number;
-};
-
-/**
- * React hook to use the Cartesia audio API.
- */
-export function useTTS({
-	apiKey,
-	baseUrl,
-	sampleRate,
-	onError,
-}: UseTTSOptions): UseTTSReturn {
-	if (typeof window === "undefined") {
-		return {
-			buffer: async () => {},
-			play: async () => {},
-			pause: async () => {},
-			resume: async () => {},
-			toggle: async () => {},
-			playbackStatus: "inactive",
-			bufferStatus: "inactive",
-			isWaiting: false,
-			source: null,
-			isConnected: false,
-			metrics: {
-				modelLatency: null,
-			},
-		};
-	}
-
-	const websocket = useMemo(() => {
-		if (!apiKey) {
-			return null;
-		}
-		const cartesia = new Cartesia({ apiKey, baseUrl });
-		baseUrl = baseUrl ?? cartesia.baseUrl;
-		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);
-	const [playbackStatus, setPlaybackStatus] =
-		useState<PlaybackStatus>("inactive");
-	const [bufferStatus, setBufferStatus] = useState<BufferStatus>("inactive");
-	const [isWaiting, setIsWaiting] = useState(false);
-	const [isConnected, setIsConnected] = useState(false);
-	const [bufferDuration, setBufferDuration] = useState<number | null>(null);
-	const [messages, setMessages] = useState<Message[]>([]);
-
-	const buffer = useCallback(
-		async (options: StreamRequest) => {
-			websocketReturn.current?.stop(); // Abort the previous request if it exists.
-
-			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);
-				}
-			}
-		},
-		[websocket, onError],
-	);
-
-	const metrics = useMemo(() => {
-		// Model Latency is the first step time
-		if (messages.length === 0) {
-			return {
-				modelLatency: null,
-			};
-		}
-		const modelLatency = messages[0].step_time ?? null;
-		return {
-			modelLatency: Math.trunc(modelLatency),
-		};
-	}, [messages]);
-
-	useEffect(() => {
-		let cleanup: (() => void) | undefined = () => {};
-		async function setupConnection() {
-			try {
-				const connection = await websocket?.connect();
-				if (!connection) {
-					return;
-				}
-				const unsubscribes = <UnsubscribeFunction[]>[];
-				// The await ensures that the connection is open, so we already know that we are connected.
-				setIsConnected(true);
-				// If the WebSocket is the kind that automatically reconnects, we need an additional
-				// listener for the open event to update the connection status.
-				unsubscribes.push(
-					connection.on("open", () => {
-						setIsConnected(true);
-					}),
-				);
-				unsubscribes.push(
-					connection.on("close", () => {
-						setIsConnected(false);
-					}),
-				);
-				const intervalId = setInterval(() => {
-					if (baseUrl) {
-						pingServer(new URL(baseUrl).origin).then((ping) => {
-							let bufferDuration: number;
-							if (ping < 300) {
-								bufferDuration = 0.01; // No buffering for very low latency
-							} else if (ping > 1500) {
-								bufferDuration = 6; // Max buffering for very high latency (6 seconds)
-							} else {
-								bufferDuration = (ping / 1000) * 4; // Adjust buffer duration based on ping
-							}
-							setBufferDuration(bufferDuration);
-						});
-					}
-				}, PING_INTERVAL);
-				return () => {
-					for (const unsubscribe of unsubscribes) {
-						unsubscribe();
-					}
-					clearInterval(intervalId);
-					websocket?.disconnect();
-				};
-			} catch (e) {
-				console.error(e);
-			}
-		}
-		setupConnection().then((cleanupConnection) => {
-			cleanup = cleanupConnection;
-		});
-		return () => cleanup?.();
-	}, [websocket, baseUrl]);
-
-	const play = useCallback(async () => {
-		try {
-			if (playbackStatus === "playing" || !websocketReturn.current) {
-				return;
-			}
-			if (player.current) {
-				// Stop the current player if it exists.
-				await player.current.stop();
-			}
-
-			if (playbackStatus === "finished") {
-				websocketReturn.current.source.seek(0, "start");
-			}
-
-			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);
-
-			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 () => {
-		try {
-			await player.current?.pause();
-			setPlaybackStatus("paused");
-		} catch (error) {
-			if (error instanceof Error) {
-				onError?.(error);
-			} else {
-				console.error(error);
-			}
-		}
-	}, [onError]);
-
-	const resume = useCallback(async () => {
-		try {
-			await player.current?.resume();
-			setPlaybackStatus("playing");
-		} catch (error) {
-			if (error instanceof Error) {
-				onError?.(error);
-			} else {
-				console.error(error);
-			}
-		}
-	}, [onError]);
-
-	const toggle = useCallback(async () => {
-		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);
-			}
-		}
-	}, [onError]);
-
-	return {
-		buffer,
-		play,
-		pause,
-		source: websocketReturn.current?.source ?? null,
-		resume,
-		toggle,
-		playbackStatus,
-		bufferStatus,
-		isWaiting,
-		isConnected,
-		metrics,
-	};
-}

package/src/react/utils.ts

@@ -1,11 +0,0 @@
-/**
- * Ping the server to calculate the round-trip time. This is useful for buffering audio in high-latency environments.
- * @param url The URL to ping.
- */
-
-export async function pingServer(url: string): Promise<number> {
-	const start = new Date().getTime();
-	await fetch(url);
-	const end = new Date().getTime();
-	return end - start;
-}

package/src/tts/index.ts

@@ -1,32 +0,0 @@
-import { Client } from "../lib/client";
-import type { BytesRequest, WebSocketOptions } from "../types";
-import WebSocket from "./websocket";
-
-export default class TTS extends Client {
-	/**
-	 * Get a WebSocket client for streaming audio from the TTS API.
-	 *
-	 * @returns {WebSocket} A Cartesia WebSocket client.
-	 */
-	websocket(options: WebSocketOptions): WebSocket {
-		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.
-	 */
-	async bytes(options: BytesRequest): Promise<ArrayBuffer> {
-		const response = await this._fetch("/tts/bytes", {
-			method: "POST",
-			body: JSON.stringify(options),
-		});
-
-		return response.arrayBuffer();
-	}
-}