@cartesia/cartesia-js 3.0.0-b5 → 3.0.0-b7

package/src/backcompat/index.ts

@@ -1,302 +1,42 @@
-import WebSocket from "ws";
-import { Cartesia } from "../client";
-
-class AudioSource {
-	private buffers: Buffer[] = [];
-	private waiter: ((val?: any) => void) | null = null;
-	public isDone = false;
-
-	push(data: Buffer) {
-		this.buffers.push(data);
-		if (this.waiter) {
-			this.waiter();
-			this.waiter = null;
-		}
-	}
-
-	markDone() {
-		this.isDone = true;
-		if (this.waiter) {
-			this.waiter();
-			this.waiter = null;
-		}
-	}
-
-	async read(outBuffer: Float32Array): Promise<number> {
-		if (this.buffers.length === 0 && !this.isDone) {
-			await new Promise<void>((resolve) => { this.waiter = resolve; });
-		}
-
-		if (this.buffers.length === 0 && this.isDone) {
-			return 0;
-		}
-
-		let totalFloatsRead = 0;
-		let outOffset = 0;
-		const maxFloats = outBuffer.length;
-
-		while (this.buffers.length > 0 && totalFloatsRead < maxFloats) {
-			const buf = this.buffers[0] as Buffer; // ts not smart enough to check loop condition
-			const floatsInBuf = buf.length / 4;
-			const floatsNeeded = maxFloats - totalFloatsRead;
-
-			const floatsToCopy = Math.min(floatsInBuf, floatsNeeded);
-			const bytesToCopy = floatsToCopy * 4;
-
-			// Copy to outBuffer.
-			// Create a view on the buffer to read floats.
-
-			// We need to ensure byteOffset is a multiple of 4.
-			// If not, we must copy the buffer to a new one.
-			let srcFloats: Float32Array;
-			if (buf.byteOffset % 4 === 0) {
-				srcFloats = new Float32Array(buf.buffer, buf.byteOffset, floatsInBuf);
-			} else {
-				const alignedBuf = new Uint8Array(buf);
-				srcFloats = new Float32Array(alignedBuf.buffer, alignedBuf.byteOffset, floatsInBuf);
-			}
-
-			outBuffer.set(srcFloats.subarray(0, floatsToCopy), outOffset);
-
-			totalFloatsRead += floatsToCopy;
-			outOffset += floatsToCopy;
-
-			if (floatsToCopy < floatsInBuf) {
-				// We didn't use the whole buffer. Update it.
-				this.buffers[0] = buf.subarray(bytesToCopy);
-			} else {
-				// We used the whole buffer. Remove it.
-				this.buffers.shift();
-			}
-		}
-
-		return totalFloatsRead;
-	}
-}
-
-class WebSocketWrapper {
-	private client: Cartesia;
-	private config: any;
-	private socket: WebSocket | null = null;
-	private sources: Map<string, AudioSource> = new Map();
-	// Fallback source for messages without context_id or if we just want to capture everything (legacy behavior?)
-	// The original test didn't use context_id explicitly in send() but expected a response source.
-	// We'll map context_id to source.
-	private defaultSource: AudioSource | null = null;
-
-	constructor(client: Cartesia, config: any) {
-		this.client = client;
-		this.config = config;
-	}
-
-	async connect() {
-		const baseURL = this.client.baseURL;
-		// Construct WebSocket URL
-		// baseURL is like https://api.cartesia.ai
-		let urlStr = baseURL.replace(/^http/, "ws");
-		if (!urlStr.includes("/tts/websocket")) {
-			if (urlStr.endsWith("/")) {
-				urlStr += "tts/websocket";
-			} else {
-				urlStr += "/tts/websocket";
-			}
-		}
-
-		const url = new URL(urlStr);
-
-		const headers: any = {
-			"cartesia-version": "2025-04-16",
-		};
-		if (this.client.apiKey) {
-			headers["Authorization"] = `Bearer ${this.client.apiKey}`;
-		}
-
-		this.socket = new WebSocket(url.toString(), {
-			headers: headers,
-		});
-
-		return new Promise<void>((resolve, reject) => {
-			this.socket!.on("open", () => {
-				console.log("WebSocket connected.");
-				resolve();
-			});
-
-			this.socket!.on("error", (err) => {
-				console.error("WebSocket error:", err);
-				reject(err);
-			});
-
-			this.socket!.on("message", (data) => {
-				this.handleMessage(data);
-			});
-
-			this.socket!.on("close", () => {
-				console.log("WebSocket closed.");
-				this.sources.forEach((s) => { s.markDone(); });
-				if (this.defaultSource) this.defaultSource.markDone();
-			});
-		});
-	}
-
-	private handleMessage(data: WebSocket.Data) {
-		try {
-			const str = data.toString();
-			const msg = JSON.parse(str);
-
-			const contextId = msg.context_id;
-			let source = contextId ? this.sources.get(contextId) : this.defaultSource;
-
-			// If we received a message for a context we don't know about, and we have a default source, use it
-			if (!source && this.defaultSource) {
-				source = this.defaultSource;
-			}
-
-			if (msg.type === "chunk" && msg.data) {
-				const audioData = Buffer.from(msg.data, "base64");
-				if (source) source.push(audioData);
-			} else if (msg.type === "done") {
-				if (source) source.markDone();
-			} else if (msg.type === "error") {
-				console.error("Server error:", msg);
-				if (source) source.markDone(); // Fail the stream?
-			}
-		} catch (e) {
-			console.error("Error parsing message:", e);
-		}
-	}
-
-	async send(request: any) {
-		if (!this.socket) {
-			throw new Error("WebSocket not connected");
-		}
-
-		// Ensure request has a context_id so we can route the response
-		if (!request.context_id) {
-			request.context_id = uuidv4();
-		}
-
-		const source = new AudioSource();
-		this.sources.set(request.context_id, source);
-		// Also set as default source if none exists, for compatibility with simple tests
-		if (!this.defaultSource) {
-			this.defaultSource = source;
-		}
-
-		// Add output format from config if not present
-		if (!request.output_format && this.config) {
-			request.output_format = {
-				container: this.config.container,
-				encoding: this.config.encoding,
-				sample_rate: this.config.sampleRate,
-			};
-		}
-		// Fix camelCase to snake_case for output_format if needed
-		// The new API expects snake_case keys in JSON usually, but let's check.
-		// The GenerationRequest interface has `output_format`.
-		// The config passed to .websocket() uses `sampleRate`.
-		// We might need to map it.
-
-		if (request.output_format) {
-			// Ensure sample_rate is set (mapping from sampleRate)
-			if (request.output_format.sampleRate && !request.output_format.sample_rate) {
-				request.output_format.sample_rate = request.output_format.sampleRate;
-				delete request.output_format.sampleRate;
-			}
-		}
-
-		// Map camelCase request fields to snake_case if necessary?
-		// The old test uses `modelId`, `generationConfig`.
-		// The new API expects `model_id`, `generation_config`.
-		const payload = {
-			...request,
-			model_id: request.modelId || request.model_id,
-			generation_config: request.generationConfig || request.generation_config,
-			context_id: request.context_id,
-		};
-		// Remove camelCase keys if they persist?
-		// JSON.stringify handles it, but we should clean up if we want to be strict.
-
-		// Also `voice` object. Old test: `voice: { mode: 'id', id: ... }`. New API: same.
-
-		this.socket.send(JSON.stringify(payload));
-
-		return {
-			source: source
-		};
-	}
-
-	disconnect() {
-		if (this.socket) {
-			this.socket.close();
-		}
-	}
-}
-
-class TTSWrapper {
+import { Cartesia, type ClientOptions } from "../client";
+import { TTSWrapper } from "./tts-wrapper";
+import { VoicesWrapper } from "./voices-wrapper";
+import { VoiceChangerWrapper } from "./voice-changer-wrapper";
+import type { CartesiaClientOptions } from "./types";
+
+/**
+ * @deprecated Use the {@link Cartesia} class directly instead.
+ * 
+ * This class is provided for backward compatibility with the legacy SDK and may be removed in a future release.
+ */
+export class CartesiaClient {
 	private client: Cartesia;
+	public tts: TTSWrapper;
+	public voices: VoicesWrapper;
+	public voiceChanger: VoiceChangerWrapper;
 
-	constructor(client: Cartesia) {
-		this.client = client;
-	}
-
-	websocket(config: any) {
-		return new WebSocketWrapper(this.client, config);
-	}
-
-	async bytes(request: any, requestOptions?: any) {
-		const params: any = {
-			model_id: request.modelId,
-			transcript: request.transcript,
-			voice: request.voice,
-			generation_config: request.generationConfig,
-			context_id: request.contextId,
-		};
+	constructor(options: CartesiaClientOptions = {}) {
+		const newOptions: ClientOptions = {};
 
-		if (request.outputFormat) {
-			params.output_format = {
-				...request.outputFormat,
-				sample_rate: request.outputFormat.sampleRate,
-				bit_rate: request.outputFormat.bitRate,
-			};
-			// Remove camelCase keys
-			delete params.output_format.sampleRate;
-			delete params.output_format.bitRate;
+		if (options.apiKey) {
+			newOptions.apiKey = options.apiKey as any;
 		}
 
-		const options: any = {};
-		if (requestOptions) {
-			if (requestOptions.timeoutInSeconds) {
-				options.timeout = requestOptions.timeoutInSeconds * 1000;
-			}
-			options.maxRetries = requestOptions.maxRetries;
-			options.headers = requestOptions.headers;
-			options.signal = requestOptions.abortSignal;
+		if (options.baseUrl) {
+			newOptions.baseURL = options.baseUrl as any;
+		} else if (options.environment) {
+			newOptions.baseURL = options.environment as any;
 		}
 
-		// @ts-ignore
-		return this.client.tts.synthesizeBytes(params, options);
-	}
-}
-
-/*
- * CartesiaClient - deprecated backcompat class.
- * New code should use Cartesia class directly instead.
- */
-export class CartesiaClient {
-	private client: Cartesia;
-	public tts: TTSWrapper;
-
-	constructor(options: any) {
-		this.client = new Cartesia(options);
+		this.client = new Cartesia(newOptions);
 		this.tts = new TTSWrapper(this.client);
+		this.voices = new VoicesWrapper(this.client);
+		this.voiceChanger = new VoiceChangerWrapper(this.client);
 	}
 }
 
-
-// Helper for generating UUIDs. Not cryptographically secure.
-function uuidv4() {
-	return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
-		var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
-		return v.toString(16);
-	});
-}
+export * from "./tts-wrapper";
+export * from "./voices-wrapper";
+export * from "./voice-changer-wrapper";
+export * from "./types";
+export * from "./errors";

package/src/backcompat/tts-wrapper.ts

@@ -0,0 +1,328 @@
+import WebSocket from "ws";
+import { Cartesia } from "../client";
+import { type RequestOptions as InternalRequestOptions } from "../internal/request-options";
+import { BackCompatRequestOptions } from "./types";
+import { wrap } from "./errors";
+
+// Define compatible interfaces to match the old SDK types for WebSocket
+export interface BackCompatWebSocketOptions {
+	container?: "raw" | "wav" | "mp3";
+	encoding?: "pcm_f32le" | "pcm_s16le" | "pcm_alaw" | "pcm_mulaw";
+	sampleRate: number;
+}
+
+export type BackCompatTtsRequestVoiceSpecifier =
+	| { mode: "id"; id: string }
+	| { mode: "embedding"; embedding: number[] };
+
+export interface BackCompatGenerationConfig {
+	volume?: number;
+	speed?: number;
+	emotion?: string[]; // Simplified from strict union for backcompat flexibility
+}
+
+export interface BackCompatWebSocketTtsRequest {
+	modelId: string;
+	transcript: string;
+	voice: BackCompatTtsRequestVoiceSpecifier;
+	generationConfig?: BackCompatGenerationConfig;
+	outputFormat?: {
+		container?: "raw" | "wav" | "mp3";
+		encoding?: "pcm_f32le" | "pcm_s16le" | "pcm_alaw" | "pcm_mulaw";
+		sampleRate?: number;
+		bitRate?: number;
+	};
+	contextId?: string; // Backcompat might pass this in request?
+	// Add other fields as needed
+	continue?: boolean;
+	duration?: number;
+	addTimestamps?: boolean;
+	addPhonemeTimestamps?: boolean;
+}
+
+// Helper for generating UUIDs. Not cryptographically secure.
+function uuidv4() {
+	return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+		var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
+		return v.toString(16);
+	});
+}
+
+class AudioSource {
+	private buffers: Buffer[] = [];
+	private waiter: ((val?: any) => void) | null = null;
+	public isDone = false;
+
+	push(data: Buffer) {
+		this.buffers.push(data);
+		if (this.waiter) {
+			this.waiter();
+			this.waiter = null;
+		}
+	}
+
+	markDone() {
+		this.isDone = true;
+		if (this.waiter) {
+			this.waiter();
+			this.waiter = null;
+		}
+	}
+
+	async read(outBuffer: Float32Array): Promise<number> {
+		if (this.buffers.length === 0 && !this.isDone) {
+			await new Promise<void>((resolve) => { this.waiter = resolve; });
+		}
+
+		if (this.buffers.length === 0 && this.isDone) {
+			return 0;
+		}
+
+		let totalFloatsRead = 0;
+		let outOffset = 0;
+		const maxFloats = outBuffer.length;
+
+		while (this.buffers.length > 0 && totalFloatsRead < maxFloats) {
+			const buf = this.buffers[0] as Buffer; // ts not smart enough to check loop condition
+			const floatsInBuf = buf.length / 4;
+			const floatsNeeded = maxFloats - totalFloatsRead;
+
+			const floatsToCopy = Math.min(floatsInBuf, floatsNeeded);
+			const bytesToCopy = floatsToCopy * 4;
+
+			// Copy to outBuffer.
+			// Create a view on the buffer to read floats.
+
+			// We need to ensure byteOffset is a multiple of 4.
+			// If not, we must copy the buffer to a new one.
+			let srcFloats: Float32Array;
+			if (buf.byteOffset % 4 === 0) {
+				srcFloats = new Float32Array(buf.buffer, buf.byteOffset, floatsInBuf);
+			} else {
+				const alignedBuf = new Uint8Array(buf);
+				srcFloats = new Float32Array(alignedBuf.buffer, alignedBuf.byteOffset, floatsInBuf);
+			}
+
+			outBuffer.set(srcFloats.subarray(0, floatsToCopy), outOffset);
+
+			totalFloatsRead += floatsToCopy;
+			outOffset += floatsToCopy;
+
+			if (floatsToCopy < floatsInBuf) {
+				// We didn't use the whole buffer. Update it.
+				this.buffers[0] = buf.subarray(bytesToCopy);
+			} else {
+				// We used the whole buffer. Remove it.
+				this.buffers.shift();
+			}
+		}
+
+		return totalFloatsRead;
+	}
+}
+
+export class WebSocketWrapper {
+	private client: Cartesia;
+	private config: BackCompatWebSocketOptions;
+	private socket: WebSocket | null = null;
+	private sources: Map<string, AudioSource> = new Map();
+	// Fallback source for messages without context_id or if we just want to capture everything (legacy behavior?)
+	// The original test didn't use context_id explicitly in send() but expected a response source.
+	// We'll map context_id to source.
+	private defaultSource: AudioSource | null = null;
+
+	constructor(client: Cartesia, config: BackCompatWebSocketOptions) {
+		this.client = client;
+		this.config = config;
+	}
+
+	async connect() {
+		const baseURL = this.client.baseURL;
+		// Construct WebSocket URL
+		// baseURL is like https://api.cartesia.ai
+		let urlStr = baseURL.replace(/^http/, "ws");
+		if (!urlStr.includes("/tts/websocket")) {
+			if (urlStr.endsWith("/")) {
+				urlStr += "tts/websocket";
+			} else {
+				urlStr += "/tts/websocket";
+			}
+		}
+
+		const url = new URL(urlStr);
+
+		const headers: any = {
+			"cartesia-version": "2025-04-16",
+		};
+		if (this.client.apiKey) {
+			headers["Authorization"] = `Bearer ${this.client.apiKey}`;
+		}
+
+		this.socket = new WebSocket(url.toString(), {
+			headers: headers,
+		});
+
+		return new Promise<void>((resolve, reject) => {
+			this.socket!.on("open", () => {
+				console.log("WebSocket connected.");
+				resolve();
+			});
+
+			this.socket!.on("error", (err) => {
+				console.error("WebSocket error:", err);
+				reject(err);
+			});
+
+			this.socket!.on("message", (data) => {
+				this.handleMessage(data);
+			});
+
+			this.socket!.on("close", () => {
+				console.log("WebSocket closed.");
+				this.sources.forEach((s) => { s.markDone(); });
+				if (this.defaultSource) this.defaultSource.markDone();
+			});
+		});
+	}
+
+	private handleMessage(data: WebSocket.Data) {
+		try {
+			const str = data.toString();
+			const msg = JSON.parse(str);
+
+			const contextId = msg.context_id;
+			let source = contextId ? this.sources.get(contextId) : this.defaultSource;
+
+			// If we received a message for a context we don't know about, and we have a default source, use it
+			if (!source && this.defaultSource) {
+				source = this.defaultSource;
+			}
+
+			if (msg.type === "chunk" && msg.data) {
+				const audioData = Buffer.from(msg.data, "base64");
+				if (source) source.push(audioData);
+			} else if (msg.type === "done") {
+				if (source) source.markDone();
+			} else if (msg.type === "error") {
+				console.error("Server error:", msg);
+				if (source) source.markDone(); // Fail the stream?
+			}
+		} catch (e) {
+			console.error("Error parsing message:", e);
+		}
+	}
+
+	async send(request: BackCompatWebSocketTtsRequest) {
+		if (!this.socket) {
+			throw new Error("WebSocket not connected");
+		}
+
+		// Ensure request has a context_id so we can route the response
+		const contextId = request.contextId || uuidv4();
+
+		const source = new AudioSource();
+		this.sources.set(contextId, source);
+		// Also set as default source if none exists, for compatibility with simple tests
+		if (!this.defaultSource) {
+			this.defaultSource = source;
+		}
+
+		// Construct payload
+		const payload: any = {
+			model_id: request.modelId,
+			transcript: request.transcript,
+			voice: request.voice,
+			context_id: contextId,
+		};
+
+		// Output Format
+		if (request.outputFormat) {
+			payload.output_format = {
+				container: request.outputFormat.container,
+				encoding: request.outputFormat.encoding,
+				sample_rate: request.outputFormat.sampleRate,
+				bit_rate: request.outputFormat.bitRate,
+			};
+		} else if (this.config) {
+			payload.output_format = {
+				container: this.config.container,
+				encoding: this.config.encoding,
+				sample_rate: this.config.sampleRate,
+			};
+		}
+
+		// Generation Config
+		if (request.generationConfig) {
+			payload.generation_config = request.generationConfig;
+		}
+
+		// Other fields
+		if (request.continue !== undefined) payload.continue = request.continue;
+		if (request.duration !== undefined) payload.duration = request.duration;
+		if (request.addTimestamps !== undefined) payload.add_timestamps = request.addTimestamps;
+		if (request.addPhonemeTimestamps !== undefined) payload.add_phoneme_timestamps = request.addPhonemeTimestamps;
+
+		this.socket.send(JSON.stringify(payload));
+
+		return {
+			source: source
+		};
+	}
+
+	disconnect() {
+		if (this.socket) {
+			this.socket.close();
+		}
+	}
+}
+
+/** @deprecated Use the new SDK's tts methods on the {@link Cartesia} instance instead. */
+export class TTSWrapper {
+	private client: Cartesia;
+
+	constructor(client: Cartesia) {
+		this.client = client;
+	}
+
+	/** @deprecated Use {@link Cartesia.tts.websocket} instead. */
+	websocket(config: BackCompatWebSocketOptions) {
+		return new WebSocketWrapper(this.client, config);
+	}
+
+	/** @deprecated Use {@link Cartesia.tts.synthesizeBytes} instead. */
+	async bytes(request: any, requestOptions?: BackCompatRequestOptions) {
+		const params: any = {
+			model_id: request.modelId,
+			transcript: request.transcript,
+			voice: request.voice,
+			generation_config: request.generationConfig,
+			context_id: request.contextId,
+		};
+
+		if (request.outputFormat) {
+			params.output_format = {
+				...request.outputFormat,
+				sample_rate: request.outputFormat.sampleRate,
+				bit_rate: request.outputFormat.bitRate,
+			};
+			// Remove camelCase keys
+			delete params.output_format.sampleRate;
+			delete params.output_format.bitRate;
+		}
+
+		const options: any = {};
+		if (requestOptions) {
+			if (requestOptions.timeoutInSeconds) {
+				options.timeout = requestOptions.timeoutInSeconds * 1000;
+			}
+			if (requestOptions.maxRetries !== undefined) {
+				options.maxRetries = requestOptions.maxRetries;
+			}
+			options.headers = requestOptions.headers;
+			options.signal = requestOptions.abortSignal;
+		}
+
+		// @ts-ignore
+		return wrap(this.client.tts.synthesizeBytes(params, options));
+	}
+}

package/src/backcompat/types.ts

@@ -0,0 +1,19 @@
+export type Supplier<T> = T | Promise<T> | (() => T | Promise<T>);
+
+export interface CartesiaClientOptions {
+	environment?: Supplier<"https://api.cartesia.ai" | string>;
+	/** Specify a custom URL to connect the client to. */
+	baseUrl?: Supplier<string>;
+	apiKey?: Supplier<string | undefined>;
+	/** Override the Cartesia-Version header */
+	cartesiaVersion?: string;
+	fetcher?: any;
+}
+
+export interface BackCompatRequestOptions {
+	timeoutInSeconds?: number;
+	maxRetries?: number;
+	abortSignal?: AbortSignal;
+	cartesiaVersion?: string;
+	headers?: Record<string, string>;
+}