@cartesia/cartesia-js 1.3.0 → 2.0.0

package/src/tts/player.ts

@@ -1,117 +0,0 @@
-import type Source from "./source";
-import { playAudioBuffer } from "./utils";
-
-export default class Player {
-	#context: AudioContext | null = null;
-	#startNextPlaybackAt = 0;
-	#bufferDuration: number;
-
-	/**
-	 * Create a new Player.
-	 *
-	 * @param options - Options for the Player.
-	 * @param options.bufferDuration - The duration of the audio buffer to play.
-	 */
-	constructor({ bufferDuration }: { bufferDuration: number }) {
-		this.#bufferDuration = bufferDuration;
-	}
-
-	async #playBuffer(buf: Float32Array, sampleRate: number) {
-		if (!this.#context) {
-			throw new Error("AudioContext not initialized.");
-		}
-		if (buf.length === 0) {
-			return;
-		}
-
-		const startAt = this.#startNextPlaybackAt;
-		const duration = buf.length / sampleRate;
-		this.#startNextPlaybackAt =
-			duration + Math.max(this.#context.currentTime, this.#startNextPlaybackAt);
-
-		await playAudioBuffer(buf, this.#context, startAt, sampleRate);
-	}
-
-	/**
-	 * Play audio from a source.
-	 *
-	 * @param source The source to play audio from.
-	 * @returns A promise that resolves when the audio has finished playing.
-	 */
-	async play(source: Source) {
-		this.#startNextPlaybackAt = 0;
-		this.#context = new AudioContext({ sampleRate: source.sampleRate });
-		const buffer = new Float32Array(
-			source.durationToSampleCount(this.#bufferDuration),
-		);
-
-		const plays: Promise<void>[] = [];
-		while (true) {
-			const read = await source.read(buffer);
-			// If we've reached the end of the source, then read < buffer.length.
-			// In that case, we don't want to play the entire buffer, as that
-			// will cause repeated audio.
-			// So we set the buffer to the correct length.
-			const playableAudio = buffer.subarray(0, read);
-			plays.push(this.#playBuffer(playableAudio, source.sampleRate));
-
-			if (read < buffer.length) {
-				// No more audio to read.
-				break;
-			}
-		}
-		await Promise.all(plays);
-	}
-
-	/**
-	 * Pause the audio.
-	 *
-	 * @returns A promise that resolves when the audio has been paused.
-	 */
-	async pause() {
-		if (!this.#context) {
-			throw new Error("AudioContext not initialized.");
-		}
-		await this.#context.suspend();
-	}
-
-	/**
-	 * Resume the audio.
-	 *
-	 * @returns A promise that resolves when the audio has been resumed.
-	 */
-	async resume() {
-		if (!this.#context) {
-			throw new Error("AudioContext not initialized.");
-		}
-		await this.#context.resume();
-	}
-
-	/**
-	 * Toggle the audio.
-	 *
-	 * @returns A promise that resolves when the audio has been toggled.
-	 */
-	async toggle() {
-		if (!this.#context) {
-			throw new Error("AudioContext not initialized.");
-		}
-		if (this.#context.state === "running") {
-			await this.pause();
-		} else {
-			await this.resume();
-		}
-	}
-
-	/**
-	 * Stop the audio.
-	 *
-	 * @returns A promise that resolves when the audio has been stopped.
-	 */
-	async stop() {
-		if (!this.#context) {
-			throw new Error("AudioContext not initialized.");
-		}
-		await this.#context?.close();
-	}
-}

package/src/tts/source.ts

@@ -1,196 +0,0 @@
-import Emittery from "emittery";
-import type { Encoding, SourceEventData, TypedArray } from "../types";
-
-type EncodingInfo = {
-	arrayType:
-		| Float32ArrayConstructor
-		| Int16ArrayConstructor
-		| Uint8ArrayConstructor;
-	bytesPerElement: number;
-};
-
-export const ENCODING_MAP: Record<Encoding, EncodingInfo> = {
-	pcm_f32le: { arrayType: Float32Array, bytesPerElement: 4 },
-	pcm_s16le: { arrayType: Int16Array, bytesPerElement: 2 },
-	pcm_alaw: { arrayType: Uint8Array, bytesPerElement: 1 },
-	pcm_mulaw: { arrayType: Uint8Array, bytesPerElement: 1 },
-};
-
-export default class Source {
-	#emitter = new Emittery<SourceEventData>();
-	#buffer: TypedArray;
-	#readIndex = 0;
-	#writeIndex = 0;
-	#closed = false;
-	#sampleRate: number;
-	#encoding: Encoding;
-	#container: string;
-
-	on = this.#emitter.on.bind(this.#emitter);
-	once = this.#emitter.once.bind(this.#emitter);
-	events = this.#emitter.events.bind(this.#emitter);
-	off = this.#emitter.off.bind(this.#emitter);
-
-	/**
-	 * Create a new Source.
-	 *
-	 * @param options - Options for the Source.
-	 * @param options.sampleRate - The sample rate of the audio.
-	 */
-	constructor({
-		sampleRate,
-		encoding,
-		container,
-	}: { sampleRate: number; encoding: string; container: string }) {
-		this.#sampleRate = sampleRate;
-		this.#encoding = encoding as Encoding;
-		this.#container = container;
-		this.#buffer = this.#createBuffer(1024); // Initial size, can be adjusted
-	}
-
-	get sampleRate() {
-		return this.#sampleRate;
-	}
-
-	get encoding() {
-		return this.#encoding;
-	}
-
-	get container() {
-		return this.#container;
-	}
-
-	/**
-	 * Create a new buffer for the source.
-	 *
-	 * @param size - The size of the buffer to create.
-	 * @returns The new buffer as a TypedArray based on the encoding.
-	 */
-	#createBuffer(size: number): TypedArray {
-		const { arrayType: ArrayType } = ENCODING_MAP[this.#encoding];
-		return new ArrayType(size);
-	}
-
-	/**
-	 * Append audio to the buffer.
-	 *
-	 * @param src The audio to append.
-	 */
-	async enqueue(src: TypedArray) {
-		const requiredCapacity = this.#writeIndex + src.length;
-
-		// Resize buffer if necessary
-		if (requiredCapacity > this.#buffer.length) {
-			let newCapacity = this.#buffer.length;
-			while (newCapacity < requiredCapacity) {
-				newCapacity *= 2; // Double the buffer size
-			}
-
-			const newBuffer = this.#createBuffer(newCapacity);
-			newBuffer.set(this.#buffer);
-			this.#buffer = newBuffer;
-		}
-
-		// Append the audio to the buffer.
-		this.#buffer.set(src, this.#writeIndex);
-		this.#writeIndex += src.length;
-		await this.#emitter.emit("enqueue");
-	}
-
-	/**
-	 * Read audio from the buffer.
-	 *
-	 * @param dst The buffer to read the audio into.
-	 * @returns The number of samples read. If the source is closed, this will be
-	 * less than the length of the provided buffer.
-	 */
-	async read(dst: TypedArray): Promise<number> {
-		// Read the buffer into the provided buffer.
-		const targetReadIndex = this.#readIndex + dst.length;
-
-		while (!this.#closed && targetReadIndex > this.#writeIndex) {
-			// Wait for more audio to be enqueued.
-			await this.#emitter.emit("wait");
-			await Promise.race([
-				this.#emitter.once("enqueue"),
-				this.#emitter.once("close"),
-			]);
-			await this.#emitter.emit("read");
-		}
-
-		const read = Math.min(dst.length, this.#writeIndex - this.#readIndex);
-		dst.set(this.#buffer.subarray(this.#readIndex, this.#readIndex + read));
-		this.#readIndex += read;
-		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.
-	 *
-	 * @param durationSecs The duration in seconds.
-	 * @returns The number of samples.
-	 */
-	durationToSampleCount(durationSecs: number) {
-		return Math.trunc(durationSecs * this.#sampleRate);
-	}
-
-	get buffer() {
-		return this.#buffer;
-	}
-
-	get readIndex() {
-		return this.#readIndex;
-	}
-
-	get writeIndex() {
-		return this.#writeIndex;
-	}
-
-	/**
-	 * Close the source. This signals that no more audio will be enqueued.
-	 *
-	 * This will emit a "close" event.
-	 *
-	 * @returns A promise that resolves when the source is closed.
-	 */
-	async close() {
-		this.#closed = true;
-		await this.#emitter.emit("close");
-		this.#emitter.clearListeners();
-	}
-}

package/src/tts/utils.ts

@@ -1,164 +0,0 @@
-import base64 from "base64-js";
-import type Emittery from "emittery";
-import type {
-	Chunk,
-	EmitteryCallbacks,
-	Encoding,
-	Sentinel,
-	TypedArray,
-	WebSocketResponse,
-} from "../types";
-import { ENCODING_MAP } from "./source";
-
-/**
- * Convert base64-encoded audio buffer(s) to a TypedArray.
- *
- * @param b64 The base64-encoded audio buffer, or an array of base64-encoded
- * audio buffers.
- * @param encoding The encoding of the audio buffer(s).
- * @returns The audio buffer(s) as a TypedArray.
- */
-export function base64ToArray(b64: Chunk[], encoding: string): TypedArray {
-	const byteArrays = filterSentinel(b64).map((b) => base64.toByteArray(b));
-
-	const { arrayType: ArrayType, bytesPerElement } =
-		ENCODING_MAP[encoding as Encoding];
-
-	const totalLength = byteArrays.reduce(
-		(acc, arr) => acc + arr.length / bytesPerElement,
-		0,
-	);
-	const result = new ArrayType(totalLength);
-
-	let offset = 0;
-	for (const arr of byteArrays) {
-		const floats = new ArrayType(arr.buffer);
-		result.set(floats, offset);
-		offset += floats.length;
-	}
-
-	return result;
-}
-
-/**
- * Schedule an audio buffer to play at a given time in the passed context.
- *
- * @param floats The audio buffer to play.
- * @param context The audio context to play the buffer in.
- * @param startAt The time to start playing the buffer at.
- * @param sampleRate The sample rate of the audio.
- * @returns A promise that resolves when the audio has finished playing.
- */
-export function playAudioBuffer(
-	floats: Float32Array,
-	context: AudioContext,
-	startAt: number,
-	sampleRate: number,
-) {
-	const source = context.createBufferSource();
-	const buffer = context.createBuffer(1, floats.length, sampleRate);
-	buffer.getChannelData(0).set(floats);
-	source.buffer = buffer;
-	source.connect(context.destination);
-	source.start(startAt);
-
-	return new Promise<void>((resolve) => {
-		source.onended = () => {
-			resolve();
-		};
-	});
-}
-
-/**
- * Unwraps a chunk of audio data from a message event and calls the
- * handler with it if the context ID matches.
- *
- * @param contextId The context ID to listen for.
- * @param handler The handler to call with the chunk of audio data.
- * @returns A message event handler.
- */
-export function createMessageHandlerForContextId(
-	contextId: string,
-	handler: ({
-		chunk,
-		message,
-	}: {
-		chunk?: Chunk;
-		message: string;
-		data: WebSocketResponse;
-	}) => void,
-) {
-	return (event: MessageEvent) => {
-		if (typeof event.data !== "string") {
-			return; // Ignore non-string messages.
-		}
-		const message: WebSocketResponse = JSON.parse(event.data);
-		if (message.context_id !== contextId) {
-			return; // Ignore messages for other contexts.
-		}
-		let chunk: Chunk | undefined;
-		if (message.done) {
-			// Convert the done message to a sentinel value.
-			chunk = getSentinel();
-		} else if (message.type === "chunk") {
-			chunk = message.data;
-		}
-		handler({ chunk, message: event.data, data: message });
-	};
-}
-
-/**
- * Get a sentinel value that indicates the end of a stream.
- * @returns A sentinel value to indicate the end of a stream.
- */
-export function getSentinel(): Sentinel {
-	return null;
-}
-
-/**
- * Check if a chunk is a sentinel value (i.e. null).
- *
- * @param chunk
- * @returns Whether the chunk is a sentinel value.
- */
-export function isSentinel(x: unknown): x is Sentinel {
-	return x === getSentinel();
-}
-
-/**
- * Filter out null values from a collection.
- *
- * @param collection The collection to filter.
- * @returns The collection with null values removed.
- */
-export function filterSentinel<T>(collection: T[]): Exclude<T, Sentinel>[] {
-	return collection.filter(
-		(x): x is Exclude<T, ReturnType<typeof getSentinel>> => !isSentinel(x),
-	);
-}
-
-/**
- * Check if an array of chunks is complete by testing if the last chunk is a sentinel
- * value (i.e. null).
- * @param chunk
- * @returns Whether the array of chunks is complete.
- */
-export function isComplete(chunks: Chunk[]) {
-	return isSentinel(chunks[chunks.length - 1]);
-}
-
-/**
- * Get user-facing emitter callbacks for an Emittery instance.
- * @param emitter The Emittery instance to get callbacks for.
- * @returns User-facing emitter callbacks.
- */
-export function getEmitteryCallbacks<T>(
-	emitter: Emittery<T>,
-): EmitteryCallbacks<T> {
-	return {
-		on: emitter.on.bind(emitter),
-		off: emitter.off.bind(emitter),
-		once: emitter.once.bind(emitter),
-		events: emitter.events.bind(emitter),
-	};
-}