@cartesia/cartesia-js 1.3.0 → 2.0.0

package/src/tts/websocket.ts

@@ -1,283 +0,0 @@
-import Emittery from "emittery";
-import { humanId } from "human-id";
-import { WebSocket as PartySocketWebSocket } from "partysocket";
-import { Client } from "../lib/client";
-import { CARTESIA_VERSION, constructApiUrl } from "../lib/constants";
-import type {
-	ConnectionEventData,
-	ConnectOptions,
-	ContinueRequest,
-	EmitteryCallbacks,
-	StreamOptions,
-	StreamRequest,
-	WebSocketOptions,
-	WordTimestamps,
-} from "../types";
-import Source from "./source";
-import {
-	base64ToArray,
-	createMessageHandlerForContextId,
-	getEmitteryCallbacks,
-	isSentinel,
-} from "./utils";
-
-export default class WebSocket extends Client {
-	socket?: PartySocketWebSocket;
-	#isConnected = false;
-	#sampleRate: number;
-	#container: string;
-	#encoding: string;
-
-	/**
-	 * Create a new WebSocket client.
-	 *
-	 * @param args - Arguments to pass to the Client constructor.
-	 */
-	constructor(
-		{ sampleRate, container, encoding }: WebSocketOptions,
-		...args: ConstructorParameters<typeof Client>
-	) {
-		super(...args);
-
-		this.#sampleRate = sampleRate;
-		this.#container = container ?? "raw"; // Default to raw audio for backwards compatibility.
-		this.#encoding = encoding ?? "pcm_f32le"; // Default to 32-bit floating point PCM for backwards compatibility.
-	}
-
-	/**
-	 * Send a message over the WebSocket to start a stream.
-	 *
-	 * @param inputs - Generation parameters. Defined in the StreamRequest type.
-	 * @param options - Options for the stream.
-	 * @param options.timeout - The maximum time to wait for a chunk before cancelling the stream.
-	 *                          If set to `0`, the stream will not time out.
-	 * @returns A Source object that can be passed to a Player to play the audio.
-	 * @returns An Emittery instance that emits messages from the WebSocket.
-	 * @returns An abort function that can be called to cancel the stream.
-	 */
-	send(inputs: StreamRequest, { timeout = 0 }: StreamOptions = {}) {
-		if (!this.#isConnected) {
-			throw new Error("Not connected to WebSocket. Call .connect() first.");
-		}
-
-		if (!inputs.context_id) {
-			inputs.context_id = this.#generateId();
-		}
-		if (!inputs.output_format) {
-			inputs.output_format = {
-				container: this.#container,
-				encoding: this.#encoding,
-				sample_rate: this.#sampleRate,
-			};
-		}
-
-		// Send audio request.
-		this.socket?.send(
-			JSON.stringify({
-				...inputs,
-			}),
-		);
-
-		const emitter = new Emittery<{
-			message: string;
-			timestamps: WordTimestamps;
-		}>();
-		const source = new Source({
-			sampleRate: this.#sampleRate,
-			encoding: this.#encoding,
-			container: this.#container,
-		});
-		// Used to signal that the stream is complete, either because the
-		// WebSocket has closed, or because the stream has finished.
-		const streamCompleteController = new AbortController();
-		// Set a timeout.
-		let timeoutId: ReturnType<typeof setTimeout> | null = null;
-		if (timeout > 0) {
-			timeoutId = setTimeout(streamCompleteController.abort, timeout);
-		}
-		const handleMessage = createMessageHandlerForContextId(
-			inputs.context_id,
-			async ({ chunk, message, data }) => {
-				emitter.emit("message", message);
-				if (data.type === "timestamps") {
-					emitter.emit("timestamps", data.word_timestamps);
-					return;
-				}
-				if (isSentinel(chunk)) {
-					await source.close();
-					streamCompleteController.abort();
-					return;
-				}
-				if (timeoutId) {
-					clearTimeout(timeoutId);
-					timeoutId = setTimeout(streamCompleteController.abort, timeout);
-				}
-				if (!chunk) {
-					return;
-				}
-				await source.enqueue(base64ToArray([chunk], this.#encoding));
-			},
-		);
-		this.socket?.addEventListener("message", handleMessage, {
-			signal: streamCompleteController.signal,
-		});
-		this.socket?.addEventListener(
-			"close",
-			() => {
-				streamCompleteController.abort();
-			},
-			{
-				once: true,
-				signal: streamCompleteController.signal,
-			},
-		);
-		this.socket?.addEventListener(
-			"error",
-			() => {
-				streamCompleteController.abort();
-			},
-			{
-				once: true,
-				signal: streamCompleteController.signal,
-			},
-		);
-		streamCompleteController.signal.addEventListener("abort", () => {
-			source.close();
-			if (timeoutId) {
-				clearTimeout(timeoutId);
-			}
-			emitter.clearListeners();
-		});
-
-		return {
-			source,
-			...getEmitteryCallbacks(emitter),
-			stop: streamCompleteController.abort.bind(streamCompleteController),
-		};
-	}
-
-	/**
-	 * Continue a stream.
-	 *
-	 * @param inputs - Generation parameters. Defined in the StreamRequest type, but must include a `context_id` field. `continue` is set to true by default.
-	 */
-	continue(inputs: ContinueRequest) {
-		if (!this.#isConnected) {
-			throw new Error("Not connected to WebSocket. Call .connect() first.");
-		}
-
-		if (!inputs.context_id) {
-			throw new Error("context_id is required to continue a context.");
-		}
-		if (!inputs.output_format) {
-			inputs.output_format = {
-				container: this.#container,
-				encoding: this.#encoding,
-				sample_rate: this.#sampleRate,
-			};
-		}
-
-		// Send continue request.
-		this.socket?.send(
-			JSON.stringify({
-				continue: true,
-				...inputs,
-			}),
-		);
-	}
-
-	/**
-	 * 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.
-	 */
-	#generateId() {
-		return humanId({
-			separator: "-",
-			capitalize: false,
-		});
-	}
-
-	/**
-	 * 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.
-	 */
-	async connect(options: ConnectOptions = {}) {
-		if (this.#isConnected) {
-			throw new Error("WebSocket is already connected.");
-		}
-
-		const emitter = new Emittery<ConnectionEventData>();
-		this.socket = new PartySocketWebSocket(
-			async () => {
-				const url = constructApiUrl(this.baseUrl, "/tts/websocket", {
-					websocket: true,
-				});
-				url.searchParams.set("api_key", await this.apiKey());
-				url.searchParams.set("cartesia_version", CARTESIA_VERSION);
-				return url.toString();
-			},
-			undefined,
-			options,
-		);
-		this.socket.binaryType = "arraybuffer";
-
-		this.socket.onopen = () => {
-			this.#isConnected = true;
-			emitter.emit("open");
-		};
-		this.socket.onclose = () => {
-			this.#isConnected = false;
-			emitter.emit("close");
-		};
-
-		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,
-					},
-				);
-			},
-		);
-	}
-
-	/**
-	 * Disconnect from the Cartesia streaming WebSocket.
-	 */
-	disconnect() {
-		this.socket?.close();
-	}
-}

package/src/types/index.ts

@@ -1,227 +0,0 @@
-import type Emittery from "emittery";
-import type { Options } from "partysocket/ws";
-
-export interface ClientOptions {
-	apiKey?: string | (() => Promise<string>);
-	baseUrl?: string;
-}
-
-export type Sentinel = null;
-
-export type Chunk = string | Sentinel;
-
-export type ConnectionEventData = {
-	open: never;
-	close: never;
-};
-
-export type VoiceSpecifier =
-	| {
-			mode?: "id";
-			id: string;
-	  }
-	| {
-			mode?: "embedding";
-			embedding: number[];
-	  };
-
-export type Emotion =
-	| "anger"
-	| "sadness"
-	| "positivity"
-	| "curiosity"
-	| "surprise";
-export type Intensity = "lowest" | "low" | "high" | "highest";
-export type EmotionControl = Emotion | `${Emotion}:${Intensity}`;
-
-export type VoiceOptions = VoiceSpecifier & {
-	__experimental_controls?: {
-		speed?: "slowest" | "slow" | "normal" | "fast" | "fastest" | number;
-		emotion?: EmotionControl[];
-	};
-};
-
-export type StreamRequest = {
-	model_id: string;
-	transcript: string;
-	voice: VoiceOptions;
-	output_format?: {
-		container: string;
-		encoding: string;
-		sample_rate: number;
-	};
-	context_id?: string;
-	continue?: boolean;
-	duration?: number;
-	language?: Language;
-	add_timestamps?: boolean;
-};
-
-export type BytesRequest = Omit<
-	StreamRequest,
-	"continue" | "add_timestamps" | "context_id"
->;
-
-export type ContinueRequest = StreamRequest & {
-	context_id: string;
-};
-
-export type Language =
-	| "en"
-	| "es"
-	| "fr"
-	| "de"
-	| "ja"
-	| "zh"
-	| "pt"
-	| (string & {});
-
-export type StreamOptions = {
-	timeout?: number;
-};
-
-export type WebSocketBaseResponse = {
-	context_id: string;
-	status_code: number;
-	done: boolean;
-};
-
-export type WordTimestamps = {
-	words: string[];
-	start: number[];
-	end: number[];
-};
-
-export type WebSocketTimestampsResponse = WebSocketBaseResponse & {
-	type: "timestamps";
-	word_timestamps: WordTimestamps;
-};
-
-export type WebSocketChunkResponse = WebSocketBaseResponse & {
-	type: "chunk";
-	data: string;
-	step_time: number;
-};
-
-export type WebSocketErrorResponse = WebSocketBaseResponse & {
-	type: "error";
-	error: string;
-};
-
-export type WebSocketResponse =
-	| WebSocketTimestampsResponse
-	| WebSocketChunkResponse
-	| WebSocketErrorResponse;
-
-export type EmitteryCallbacks<T> = {
-	on: Emittery<T>["on"];
-	off: Emittery<T>["off"];
-	once: Emittery<T>["once"];
-	events: Emittery<T>["events"];
-};
-
-export type CloneOptions =
-	| {
-			mode: "url";
-			link: string;
-			enhance?: boolean;
-	  }
-	| {
-			mode: "clip";
-			clip: Blob;
-			enhance?: boolean;
-	  };
-
-export type VoiceChangerOptions = {
-	clip: File;
-	voice: { id: string }; // match VoiceSpecifier shape, but only id is supported for now
-	output_format:
-		| {
-				container: "mp3";
-				bit_rate: number;
-				sample_rate: number;
-		  }
-		| {
-				container: "wav";
-				encoding: Encoding;
-				sample_rate: number;
-				bit_rate: number;
-		  }
-		| {
-				container: "raw";
-				encoding: Encoding;
-				sample_rate: number;
-		  };
-};
-
-export type LocalizeOptions = {
-	mode: "embedding";
-	embedding: number[];
-} & {
-	language: Language;
-	dialect: string & {};
-	original_speaker_gender: "male" | "female" | (string & {});
-};
-
-export interface VoiceToMix {
-	id?: string;
-	embedding?: number[];
-	weight: number;
-}
-
-export interface MixVoicesOptions {
-	voices: VoiceToMix[];
-}
-
-export type Voice = {
-	id: string;
-	name: string;
-	description: string;
-	embedding: number[];
-	is_public: boolean;
-	user_id: string;
-	created_at: string;
-	language: Language;
-};
-
-export type CreateVoice = Pick<Voice, "name" | "description" | "embedding"> &
-	Partial<Omit<Voice, "name" | "description" | "embedding">>;
-
-export type UpdateVoice = Partial<
-	Pick<Voice, "name" | "description" | "embedding">
->;
-
-export type CloneResponse = {
-	embedding: number[];
-};
-
-export type VoiceChangerBytesResponse = {
-	buffer: ArrayBuffer;
-};
-
-export type LocalizeResponse = {
-	embedding: number[];
-};
-
-export type MixVoicesResponse = {
-	embedding: number[];
-};
-
-export type WebSocketOptions = {
-	container?: string;
-	encoding?: string;
-	sampleRate: number;
-};
-
-export type ConnectOptions = Pick<Options, "WebSocket">;
-
-export type SourceEventData = {
-	enqueue: never;
-	close: never;
-	wait: never;
-	read: never;
-};
-
-export type TypedArray = Float32Array | Int16Array | Uint8Array;
-
-export type Encoding = "pcm_f32le" | "pcm_s16le" | "pcm_alaw" | "pcm_mulaw";

package/src/voice-changer/index.ts

@@ -1,37 +0,0 @@
-import { Client } from "../lib/client";
-import type { VoiceChangerBytesResponse, VoiceChangerOptions } from "../types";
-
-export default class VoiceChanger extends Client {
-	async bytes(
-		options: VoiceChangerOptions,
-	): Promise<VoiceChangerBytesResponse> {
-		const formData = new FormData();
-		formData.append("clip", options.clip); // TODO: handle Blobs that are not Files
-		formData.append("voice[id]", options.voice.id);
-
-		const fmt = options.output_format;
-		formData.append("output_format[container]", fmt.container);
-		if ("encoding" in fmt) {
-			formData.append("output_format[encoding]", fmt.encoding);
-		}
-		if ("bit_rate" in fmt) {
-			formData.append("output_format[bit_rate]", fmt.bit_rate.toString());
-		}
-		if ("sample_rate" in fmt) {
-			formData.append("output_format[sample_rate]", fmt.sample_rate.toString());
-		}
-
-		const response = await this._fetch("/voice-changer/bytes", {
-			method: "POST",
-			body: formData,
-		});
-
-		if (!response.ok) {
-			throw new Error(
-				`Voice changer error! status: ${response.status}, message: ${await response.text()}`,
-			);
-		}
-
-		return { buffer: await response.arrayBuffer() };
-	}
-}

package/src/voices/index.ts

@@ -1,76 +0,0 @@
-import { Client } from "../lib/client";
-import type {
-	CloneOptions,
-	CloneResponse,
-	CreateVoice,
-	LocalizeOptions,
-	LocalizeResponse,
-	MixVoicesOptions,
-	MixVoicesResponse,
-	UpdateVoice,
-	Voice,
-} from "../types";
-
-export default class Voices extends Client {
-	async list(): Promise<Voice[]> {
-		const response = await this._fetch("/voices");
-		return response.json();
-	}
-
-	async get(voiceId: string): Promise<Voice> {
-		const response = await this._fetch(`/voices/${voiceId}`);
-		return response.json();
-	}
-
-	async create(voice: CreateVoice): Promise<Voice> {
-		const response = await this._fetch("/voices", {
-			method: "POST",
-			body: JSON.stringify(voice),
-		});
-		return response.json() as Promise<Voice>;
-	}
-
-	async update(id: string, voice: UpdateVoice): Promise<Voice> {
-		const response = await this._fetch(`/voices/${id}`, {
-			method: "PATCH",
-			body: JSON.stringify(voice),
-		});
-		return response.json() as Promise<Voice>;
-	}
-
-	async clone(options: CloneOptions): Promise<CloneResponse> {
-		if (options.mode === "clip") {
-			const formData = new FormData();
-			formData.append("clip", options.clip);
-			if (options.enhance !== undefined) {
-				formData.append("enhance", options.enhance.toString());
-			}
-
-			const response = await this._fetch("/voices/clone/clip", {
-				method: "POST",
-				body: formData,
-			});
-			return response.json();
-		}
-
-		throw new Error("Invalid mode for clone()");
-	}
-
-	async mix(options: MixVoicesOptions): Promise<MixVoicesResponse> {
-		const response = await this._fetch("/voices/mix", {
-			method: "POST",
-			body: JSON.stringify(options),
-		});
-
-		return response.json() as Promise<MixVoicesResponse>;
-	}
-
-	async localize(options: LocalizeOptions): Promise<LocalizeResponse> {
-		const response = await this._fetch("/voices/localize", {
-			method: "POST",
-			body: JSON.stringify(options),
-		});
-
-		return response.json() as Promise<LocalizeResponse>;
-	}
-}