@cartesia/cartesia-js 1.0.3 → 1.2.1-alpha.2

package/dist/voice-changer/index.cjs

@@ -0,0 +1,143 @@
+"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/voice-changer/index.ts
+var voice_changer_exports = {};
+__export(voice_changer_exports, {
+  default: () => VoiceChanger
+});
+module.exports = __toCommonJS(voice_changer_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/voice-changer/index.ts
+var VoiceChanger = class extends Client {
+  bytes(options) {
+    return __async(this, null, function* () {
+      const formData = new FormData();
+      formData.append("clip", options.clip);
+      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 = yield this._fetch("/voice-changer/bytes", {
+        method: "POST",
+        body: formData
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Voice changer error! status: ${response.status}, message: ${yield response.text()}`
+        );
+      }
+      return { buffer: yield response.arrayBuffer() };
+    });
+  }
+};

package/dist/voice-changer/index.d.cts

@@ -0,0 +1,9 @@
+import { Client } from '../lib/client.cjs';
+import { VoiceChangerOptions, VoiceChangerBytesResponse } from '../types/index.cjs';
+import 'emittery';
+
+declare class VoiceChanger extends Client {
+    bytes(options: VoiceChangerOptions): Promise<VoiceChangerBytesResponse>;
+}
+
+export { VoiceChanger as default };

package/dist/voice-changer/index.d.ts

@@ -0,0 +1,9 @@
+import { Client } from '../lib/client.js';
+import { VoiceChangerOptions, VoiceChangerBytesResponse } from '../types/index.js';
+import 'emittery';
+
+declare class VoiceChanger extends Client {
+    bytes(options: VoiceChangerOptions): Promise<VoiceChangerBytesResponse>;
+}
+
+export { VoiceChanger as default };

package/dist/voice-changer/index.js

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

package/dist/voices/index.cjs

@@ -161,10 +161,18 @@ var Voices = class extends Client {
   }
   mix(options) {
     return __async(this, null, function* () {
-      const request = options;
       const response = yield this._fetch("/voices/mix", {
         method: "POST",
-        body: JSON.stringify(request)
+        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,5 +1,5 @@
 import { Client } from '../lib/client.cjs';
-import { Voice, CreateVoice, UpdateVoice, CloneOptions, CloneResponse, MixVoicesOptions, MixVoicesResponse } from '../types/index.cjs';
+import { Voice, CreateVoice, UpdateVoice, CloneOptions, CloneResponse, MixVoicesOptions, MixVoicesResponse, LocalizeOptions, LocalizeResponse } from '../types/index.cjs';
 import 'emittery';
 
 declare class Voices extends Client {
@@ -9,6 +9,7 @@ declare class Voices extends Client {
     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,5 +1,5 @@
 import { Client } from '../lib/client.js';
-import { Voice, CreateVoice, UpdateVoice, CloneOptions, CloneResponse, MixVoicesOptions, MixVoicesResponse } from '../types/index.js';
+import { Voice, CreateVoice, UpdateVoice, CloneOptions, CloneResponse, MixVoicesOptions, MixVoicesResponse, LocalizeOptions, LocalizeResponse } from '../types/index.js';
 import 'emittery';
 
 declare class Voices extends Client {
@@ -9,6 +9,7 @@ declare class Voices extends Client {
     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 +1,9 @@
 import {
   Voices
-} from "../chunk-YFN6TFR4.js";
-import "../chunk-PISCPZK4.js";
+} from "../chunk-RJICGVPL.js";
+import "../chunk-FLWYXP5Z.js";
 import "../chunk-2BFEKY3F.js";
-import "../chunk-GHY2WEOK.js";
+import "../chunk-NJDRWDQ3.js";
 export {
   Voices as default
 };

package/package.json

@@ -4,7 +4,7 @@
 		"name": "Cartesia",
 		"url": "https://cartesia.ai"
 	},
-	"version": "1.0.3",
+	"version": "1.2.1-alpha.2",
 	"description": "Client for the Cartesia API.",
 	"type": "module",
 	"module": "./dist/index.js",
@@ -27,7 +27,8 @@
 		"cross-fetch": "^4.0.0",
 		"emittery": "^1.0.3",
 		"human-id": "^4.1.1",
-		"partysocket": "^1.0.1"
+		"partysocket": "^1.0.1",
+		"react": "^18.3.1"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -36,20 +37,11 @@
 		"build": "tsup src/ --format cjs,esm --dts",
 		"dev": "bun run build -- --watch"
 	},
-	"peerDependencies": {
-		"react": "^18.2.0",
-		"@types/react": "^18.2.58"
-	},
-	"peerDependenciesMeta": {
-		"react": {
-			"optional": true
-		},
-		"@types/react": {
-			"optional": true
-		}
-	},
 	"devDependencies": {
-		"@repo/config-typescript": "workspace:*",
-		"tsup": "^8.0.2"
+		"@biomejs/biome": "^1.9.4",
+		"@types/node": "^22.7.9",
+		"@types/react": "^18.3.12",
+		"tsup": "^8.0.2",
+		"typescript": "^5.6.3"
 	}
 }

package/src/lib/index.ts

@@ -1,16 +1,19 @@
 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

@@ -201,6 +201,10 @@ export function useTTS({
 				await player.current.stop();
 			}
 
+			if (playbackStatus === "finished") {
+				websocketReturn.current.source.seek(0, "start");
+			}
+
 			setPlaybackStatus("playing");
 
 			const unsubscribes = [];

package/src/tts/index.ts

@@ -1,5 +1,5 @@
 import { Client } from "../lib/client";
-import type { WebSocketOptions } from "../types";
+import type { BytesRequest, WebSocketOptions } from "../types";
 import WebSocket from "./websocket";
 
 export default class TTS extends Client {
@@ -14,4 +14,19 @@ export default class TTS extends Client {
 			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();
+	}
 }

package/src/tts/source.ts

@@ -124,6 +124,41 @@ export default class Source {
 		return read;
 	}
 
+	/**
+	 * Seek in the buffer.
+	 *
+	 * @param offset The offset to seek to.
+	 * @param whence The position to seek from.
+	 * @returns The new position in the buffer.
+	 * @throws {Error} If the seek is invalid.
+	 */
+	async seek(
+		offset: number,
+		whence: "start" | "current" | "end",
+	): Promise<number> {
+		let position = this.#readIndex;
+		switch (whence) {
+			case "start":
+				position = offset;
+				break;
+			case "current":
+				position += offset;
+				break;
+			case "end":
+				position = this.#writeIndex + offset;
+				break;
+			default:
+				throw new Error(`Invalid seek mode: ${whence}`);
+		}
+
+		if (position < 0 || position > this.#writeIndex) {
+			throw new Error("Seek out of bounds");
+		}
+
+		this.#readIndex = position;
+		return position;
+	}
+
 	/**
 	 * Get the number of samples in a given duration.
 	 *

package/src/tts/websocket.ts

@@ -5,6 +5,7 @@ import { Client } from "../lib/client";
 import { CARTESIA_VERSION, constructApiUrl } from "../lib/constants";
 import type {
 	ConnectionEventData,
+	ContinueRequest,
 	EmitteryCallbacks,
 	StreamOptions,
 	StreamRequest,
@@ -45,7 +46,7 @@ export default class WebSocket extends Client {
 	/**
 	 * Send a message over the WebSocket to start a stream.
 	 *
-	 * @param inputs - Stream options. Defined in the StreamRequest type.
+	 * @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.
@@ -53,7 +54,7 @@ export default class WebSocket extends Client {
 	 * @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 = {}) {
+	send(inputs: StreamRequest, { timeout = 0 }: StreamOptions = {}) {
 		if (!this.#isConnected) {
 			throw new Error("Not connected to WebSocket. Call .connect() first.");
 		}
@@ -151,6 +152,36 @@ export default class WebSocket extends Client {
 		};
 	}
 
+	/**
+	 * 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.
 	 *

package/src/types/index.ts

@@ -52,10 +52,29 @@ export type StreamRequest = {
 	context_id?: string;
 	continue?: boolean;
 	duration?: number;
-	language?: string;
+	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;
 };
@@ -112,6 +131,37 @@ export type CloneOptions =
 			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[];
@@ -130,7 +180,7 @@ export type Voice = {
 	is_public: boolean;
 	user_id: string;
 	created_at: string;
-	language: string;
+	language: Language;
 };
 
 export type CreateVoice = Pick<Voice, "name" | "description" | "embedding"> &
@@ -144,6 +194,14 @@ export type CloneResponse = {
 	embedding: number[];
 };
 
+export type VoiceChangerBytesResponse = {
+	buffer: ArrayBuffer;
+};
+
+export type LocalizeResponse = {
+	embedding: number[];
+};
+
 export type MixVoicesResponse = {
 	embedding: number[];
 };

package/src/voice-changer/index.ts

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

@@ -3,6 +3,8 @@ import type {
 	CloneOptions,
 	CloneResponse,
 	CreateVoice,
+	LocalizeOptions,
+	LocalizeResponse,
 	MixVoicesOptions,
 	MixVoicesResponse,
 	UpdateVoice,
@@ -55,13 +57,20 @@ export default class Voices extends Client {
 	}
 
 	async mix(options: MixVoicesOptions): Promise<MixVoicesResponse> {
-		const request: MixVoicesOptions = options;
-
 		const response = await this._fetch("/voices/mix", {
 			method: "POST",
-			body: JSON.stringify(request),
+			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>;
+	}
 }