@cartesia/cartesia-js 0.0.1

package/dist/chunk-5RMUZJV7.mjs

@@ -0,0 +1,240 @@
+import {
+  createMessageHandlerForContextId,
+  getBufferDuration,
+  isComplete,
+  isSentinel,
+  playAudioBuffer
+} from "./chunk-BTFHUVNH.mjs";
+import {
+  Client
+} from "./chunk-ERFCRIWU.mjs";
+import {
+  SAMPLE_RATE,
+  __async,
+  __forAwait,
+  constructWebsocketUrl
+} from "./chunk-35HX6ML3.mjs";
+
+// src/audio/index.ts
+import Emittery from "emittery";
+import { humanId } from "human-id";
+var audio_default = class extends Client {
+  constructor() {
+    super(...arguments);
+    this.isConnected = false;
+  }
+  /**
+   * Stream audio from a model.
+   *
+   * @param inputs - Stream options. Includes a `model` key and some `parameters`, which
+   * are model-specific and can be found in the model's documentation.
+   * @param options - Options for the stream.
+   * @param options.timeout - The maximum time to wait for a chunk before cancelling the stream.
+   * If `0`, the stream will not time out.
+   * @returns An object with a method `play` of type `(bufferDuration: number) => Promise<void>`
+   * that plays the audio as it arrives, with `bufferDuration` seconds of audio buffered before
+   * starting playback.
+   */
+  stream(inputs, { timeout = 0 } = {}) {
+    var _a, _b, _c, _d;
+    if (!this.isConnected) {
+      throw new Error("Not connected to WebSocket. Call .connect() first.");
+    }
+    const contextId = this.generateId();
+    (_a = this.socket) == null ? void 0 : _a.send(
+      JSON.stringify({
+        data: inputs,
+        context_id: contextId
+      })
+    );
+    const streamCompleteController = new AbortController();
+    let timeoutId = null;
+    if (timeout > 0) {
+      timeoutId = setTimeout(streamCompleteController.abort, timeout);
+    }
+    const chunks = [];
+    const emitter = new Emittery();
+    const handleMessage = createMessageHandlerForContextId(
+      contextId,
+      (_0) => __async(this, [_0], function* ({ chunk, message }) {
+        chunks.push(chunk);
+        yield emitter.emit("chunk", {
+          chunk,
+          chunks
+        });
+        yield emitter.emit("message", message);
+        if (isSentinel(chunk)) {
+          streamCompleteController.abort();
+        } else if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = setTimeout(streamCompleteController.abort, timeout);
+        }
+      })
+    );
+    (_b = this.socket) == null ? void 0 : _b.addEventListener("message", handleMessage, {
+      signal: streamCompleteController.signal
+    });
+    (_c = this.socket) == null ? void 0 : _c.addEventListener("close", streamCompleteController.abort, {
+      once: true
+    });
+    (_d = this.socket) == null ? void 0 : _d.addEventListener("error", streamCompleteController.abort, {
+      once: true
+    });
+    streamCompleteController.signal.addEventListener("abort", () => {
+      emitter.clearListeners();
+    });
+    const play = (_0) => __async(this, [_0], function* ({ bufferDuration }) {
+      const context = new AudioContext({
+        sampleRate: SAMPLE_RATE
+      });
+      let startNextPlaybackAt = 0;
+      const playLatestChunk = (chunk) => {
+        if (isSentinel(chunk)) {
+          return true;
+        }
+        startNextPlaybackAt = playAudioBuffer([chunk], context, startNextPlaybackAt) + Math.max(context.currentTime, startNextPlaybackAt);
+        return false;
+      };
+      const playChunks = (chunks2) => {
+        startNextPlaybackAt += playAudioBuffer(
+          chunks2,
+          context,
+          startNextPlaybackAt
+        );
+        if (isComplete(chunks2)) {
+          return;
+        }
+      };
+      const tryStart = (chunks2) => __async(this, null, function* () {
+        startNextPlaybackAt = context.currentTime;
+        if (isComplete(chunks2) || streamCompleteController.signal.aborted) {
+          playChunks(chunks2);
+          return true;
+        }
+        if (getBufferDuration(chunks2) > bufferDuration) {
+          playChunks(chunks2);
+          try {
+            for (var iter2 = __forAwait(emitter.events("chunk")), more2, temp2, error2; more2 = !(temp2 = yield iter2.next()).done; more2 = false) {
+              const { chunk } = temp2.value;
+              if (playLatestChunk(chunk)) {
+                break;
+              }
+            }
+          } catch (temp2) {
+            error2 = [temp2];
+          } finally {
+            try {
+              more2 && (temp2 = iter2.return) && (yield temp2.call(iter2));
+            } finally {
+              if (error2)
+                throw error2[0];
+            }
+          }
+          return true;
+        }
+        return false;
+      });
+      if (!(yield tryStart(chunks))) {
+        try {
+          for (var iter = __forAwait(emitter.events("chunk")), more, temp, error; more = !(temp = yield iter.next()).done; more = false) {
+            const { chunks: chunks2 } = temp.value;
+            if (yield tryStart(chunks2)) {
+              break;
+            }
+          }
+        } catch (temp) {
+          error = [temp];
+        } finally {
+          try {
+            more && (temp = iter.return) && (yield temp.call(iter));
+          } finally {
+            if (error)
+              throw error[0];
+          }
+        }
+      }
+    });
+    return {
+      play,
+      on: emitter.on.bind(emitter),
+      off: emitter.off.bind(emitter),
+      once: emitter.once.bind(emitter),
+      events: emitter.events.bind(emitter)
+    };
+  }
+  /**
+   * 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.
+   */
+  connect() {
+    const url = constructWebsocketUrl(this.baseUrl);
+    url.searchParams.set("api_key", this.apiKey);
+    this.socket = new WebSocket(url);
+    this.socket.onopen = () => {
+      this.isConnected = true;
+    };
+    this.socket.onclose = () => {
+      this.isConnected = false;
+    };
+    return new Promise((resolve, reject) => {
+      var _a, _b, _c;
+      (_a = this.socket) == null ? void 0 : _a.addEventListener(
+        "open",
+        () => {
+          resolve();
+        },
+        {
+          once: true
+        }
+      );
+      const aborter = new AbortController();
+      (_b = this.socket) == null ? void 0 : _b.addEventListener(
+        "error",
+        () => {
+          aborter.abort();
+          reject(new Error("WebSocket failed to connect."));
+        },
+        {
+          signal: aborter.signal
+        }
+      );
+      (_c = this.socket) == null ? void 0 : _c.addEventListener(
+        "close",
+        () => {
+          aborter.abort();
+          reject(new Error("WebSocket closed before it could connect."));
+        },
+        {
+          signal: aborter.signal
+        }
+      );
+    });
+  }
+  /**
+   * Disconnect from the Cartesia streaming WebSocket.
+   */
+  disconnect() {
+    var _a;
+    (_a = this.socket) == null ? void 0 : _a.close();
+  }
+};
+
+export {
+  audio_default
+};

package/dist/chunk-BTFHUVNH.mjs

@@ -0,0 +1,71 @@
+import {
+  SAMPLE_RATE
+} from "./chunk-35HX6ML3.mjs";
+
+// src/audio/utils.ts
+import base64 from "base64-js";
+function getBufferDuration(b64) {
+  const floats = base64ToArray(b64);
+  return floats.length / SAMPLE_RATE;
+}
+function base64ToArray(b64) {
+  return filterSentinel(b64).reduce((acc, b) => {
+    const floats = new Float32Array(base64.toByteArray(b).buffer);
+    const newAcc = new Float32Array(acc.length + floats.length);
+    newAcc.set(acc, 0);
+    newAcc.set(floats, acc.length);
+    return newAcc;
+  }, new Float32Array(0));
+}
+function playAudioBuffer(b64, context, maybeStartAt = null, onEnded = null) {
+  const startAt = maybeStartAt != null ? maybeStartAt : context.currentTime;
+  const floats = base64ToArray(b64);
+  const source = context.createBufferSource();
+  const buffer = context.createBuffer(1, floats.length, SAMPLE_RATE);
+  buffer.getChannelData(0).set(floats);
+  source.buffer = buffer;
+  source.connect(context.destination);
+  source.start(startAt);
+  source.onended = onEnded;
+  return buffer.duration;
+}
+function createMessageHandlerForContextId(contextId, handler) {
+  return (event) => {
+    const message = JSON.parse(event.data);
+    if (message.context_id !== contextId) {
+      return;
+    }
+    let chunk;
+    if (message.done) {
+      chunk = getSentinel();
+    } else {
+      chunk = message.data;
+    }
+    handler({ chunk, message });
+  };
+}
+function getSentinel() {
+  return null;
+}
+function isSentinel(x) {
+  return x === getSentinel();
+}
+function filterSentinel(collection) {
+  return collection.filter(
+    (x) => !isSentinel(x)
+  );
+}
+function isComplete(chunks) {
+  return isSentinel(chunks[chunks.length - 1]);
+}
+
+export {
+  getBufferDuration,
+  base64ToArray,
+  playAudioBuffer,
+  createMessageHandlerForContextId,
+  getSentinel,
+  isSentinel,
+  filterSentinel,
+  isComplete
+};

package/dist/chunk-ERFCRIWU.mjs

@@ -0,0 +1,18 @@
+import {
+  BASE_URL
+} from "./chunk-35HX6ML3.mjs";
+
+// src/lib/client.ts
+var Client = class {
+  constructor(options = {}) {
+    if (!(options.apiKey || process.env.CARTESIA_API_KEY)) {
+      throw new Error("Missing Cartesia API key.");
+    }
+    this.apiKey = options.apiKey || process.env.CARTESIA_API_KEY;
+    this.baseUrl = options.baseUrl || BASE_URL;
+  }
+};
+
+export {
+  Client
+};

package/dist/index-Ds4LDkmk.d.ts

@@ -0,0 +1,127 @@
+import * as emittery from 'emittery';
+import { Client } from './lib/client.js';
+
+/**
+ * Get the duration of base64-encoded audio buffer(s) in seconds.
+ *
+ * @param b64 The base64-encoded audio buffer, or an array of base64-encoded
+ * audio buffers.
+ * @returns The duration of the buffer(s) in seconds.
+ */
+declare function getBufferDuration(b64: Chunk[]): number;
+/**
+ * Convert base64-encoded audio buffer(s) to a Float32Array.
+ *
+ * @param b64 The base64-encoded audio buffer, or an array of base64-encoded
+ * audio buffers.
+ * @returns The audio buffer(s) as a Float32Array.
+ */
+declare function base64ToArray(b64: Chunk[]): Float32Array;
+/**
+ * Schedule an audio buffer to play at a given time in the passed context.
+ *
+ * @param b64 The base64-encoded audio buffer to play.
+ * @param context The audio context to play the buffer in.
+ * @param maybeStartAt The time to start playing the buffer at, or null to play
+ * immediately.
+ * @param onEnded The callback to call when the buffer has finished playing.
+ * @returns The duration of the buffer in seconds.
+ */
+declare function playAudioBuffer(b64: Chunk[], context: AudioContext, maybeStartAt?: number | null, onEnded?: AudioScheduledSourceNode["onended"]): number;
+/**
+ * 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.
+ */
+declare function createMessageHandlerForContextId(contextId: string, handler: ({ chunk, message, }: {
+    chunk: Chunk;
+    message: StreamEventData["message"];
+}) => void): (event: MessageEvent) => void;
+type Sentinel = null;
+/**
+ * Get a sentinel value that indicates the end of a stream.
+ * @returns A sentinel value to indicate the end of a stream.
+ */
+declare function getSentinel(): Sentinel;
+/**
+ * Check if a chunk is a sentinel value (i.e. null).
+ *
+ * @param chunk
+ * @returns Whether the chunk is a sentinel value.
+ */
+declare function isSentinel(x: unknown): x is Sentinel;
+/**
+ * Filter out null values from a collection.
+ *
+ * @param collection The collection to filter.
+ * @returns The collection with null values removed.
+ */
+declare function filterSentinel<T>(collection: T[]): Exclude<T, Sentinel>[];
+/**
+ * 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.
+ */
+declare function isComplete(chunks: Chunk[]): boolean;
+
+type Chunk = string | Sentinel;
+type StreamEventData = {
+    chunk: {
+        chunk: Chunk;
+        chunks: Chunk[];
+    };
+    message: unknown;
+};
+declare class export_default extends Client {
+    socket?: WebSocket;
+    isConnected: boolean;
+    /**
+     * Stream audio from a model.
+     *
+     * @param inputs - Stream options. Includes a `model` key and some `parameters`, which
+     * are model-specific and can be found in the model's documentation.
+     * @param options - Options for the stream.
+     * @param options.timeout - The maximum time to wait for a chunk before cancelling the stream.
+     * If `0`, the stream will not time out.
+     * @returns An object with a method `play` of type `(bufferDuration: number) => Promise<void>`
+     * that plays the audio as it arrives, with `bufferDuration` seconds of audio buffered before
+     * starting playback.
+     */
+    stream(inputs: object, { timeout }?: {
+        timeout?: number;
+    }): {
+        play: ({ bufferDuration }: {
+            bufferDuration: number;
+        }) => Promise<void>;
+        on: <Name extends keyof StreamEventData | keyof emittery.OmnipresentEventData>(eventName: Name | readonly Name[], listener: (eventData: (StreamEventData & emittery.OmnipresentEventData)[Name]) => void | Promise<void>) => emittery.UnsubscribeFunction;
+        off: <Name_1 extends keyof StreamEventData | keyof emittery.OmnipresentEventData>(eventName: Name_1 | readonly Name_1[], listener: (eventData: (StreamEventData & emittery.OmnipresentEventData)[Name_1]) => void | Promise<void>) => void;
+        once: <Name_2 extends keyof StreamEventData | keyof emittery.OmnipresentEventData>(eventName: Name_2 | readonly Name_2[]) => emittery.EmitteryOncePromise<(StreamEventData & emittery.OmnipresentEventData)[Name_2]>;
+        events: <Name_3 extends keyof StreamEventData>(eventName: Name_3 | readonly Name_3[]) => AsyncIterableIterator<StreamEventData[Name_3]>;
+    };
+    /**
+     * 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(): string;
+    /**
+     * 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.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the Cartesia streaming WebSocket.
+     */
+    disconnect(): void;
+}
+
+export { type Chunk as C, type StreamEventData as S, type Sentinel as a, base64ToArray as b, createMessageHandlerForContextId as c, getSentinel as d, export_default as e, filterSentinel as f, getBufferDuration as g, isComplete as h, isSentinel as i, playAudioBuffer as p };

package/dist/index-Dt9A_pEb.d.mts

@@ -0,0 +1,127 @@
+import * as emittery from 'emittery';
+import { Client } from './lib/client.mjs';
+
+/**
+ * Get the duration of base64-encoded audio buffer(s) in seconds.
+ *
+ * @param b64 The base64-encoded audio buffer, or an array of base64-encoded
+ * audio buffers.
+ * @returns The duration of the buffer(s) in seconds.
+ */
+declare function getBufferDuration(b64: Chunk[]): number;
+/**
+ * Convert base64-encoded audio buffer(s) to a Float32Array.
+ *
+ * @param b64 The base64-encoded audio buffer, or an array of base64-encoded
+ * audio buffers.
+ * @returns The audio buffer(s) as a Float32Array.
+ */
+declare function base64ToArray(b64: Chunk[]): Float32Array;
+/**
+ * Schedule an audio buffer to play at a given time in the passed context.
+ *
+ * @param b64 The base64-encoded audio buffer to play.
+ * @param context The audio context to play the buffer in.
+ * @param maybeStartAt The time to start playing the buffer at, or null to play
+ * immediately.
+ * @param onEnded The callback to call when the buffer has finished playing.
+ * @returns The duration of the buffer in seconds.
+ */
+declare function playAudioBuffer(b64: Chunk[], context: AudioContext, maybeStartAt?: number | null, onEnded?: AudioScheduledSourceNode["onended"]): number;
+/**
+ * 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.
+ */
+declare function createMessageHandlerForContextId(contextId: string, handler: ({ chunk, message, }: {
+    chunk: Chunk;
+    message: StreamEventData["message"];
+}) => void): (event: MessageEvent) => void;
+type Sentinel = null;
+/**
+ * Get a sentinel value that indicates the end of a stream.
+ * @returns A sentinel value to indicate the end of a stream.
+ */
+declare function getSentinel(): Sentinel;
+/**
+ * Check if a chunk is a sentinel value (i.e. null).
+ *
+ * @param chunk
+ * @returns Whether the chunk is a sentinel value.
+ */
+declare function isSentinel(x: unknown): x is Sentinel;
+/**
+ * Filter out null values from a collection.
+ *
+ * @param collection The collection to filter.
+ * @returns The collection with null values removed.
+ */
+declare function filterSentinel<T>(collection: T[]): Exclude<T, Sentinel>[];
+/**
+ * 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.
+ */
+declare function isComplete(chunks: Chunk[]): boolean;
+
+type Chunk = string | Sentinel;
+type StreamEventData = {
+    chunk: {
+        chunk: Chunk;
+        chunks: Chunk[];
+    };
+    message: unknown;
+};
+declare class export_default extends Client {
+    socket?: WebSocket;
+    isConnected: boolean;
+    /**
+     * Stream audio from a model.
+     *
+     * @param inputs - Stream options. Includes a `model` key and some `parameters`, which
+     * are model-specific and can be found in the model's documentation.
+     * @param options - Options for the stream.
+     * @param options.timeout - The maximum time to wait for a chunk before cancelling the stream.
+     * If `0`, the stream will not time out.
+     * @returns An object with a method `play` of type `(bufferDuration: number) => Promise<void>`
+     * that plays the audio as it arrives, with `bufferDuration` seconds of audio buffered before
+     * starting playback.
+     */
+    stream(inputs: object, { timeout }?: {
+        timeout?: number;
+    }): {
+        play: ({ bufferDuration }: {
+            bufferDuration: number;
+        }) => Promise<void>;
+        on: <Name extends keyof StreamEventData | keyof emittery.OmnipresentEventData>(eventName: Name | readonly Name[], listener: (eventData: (StreamEventData & emittery.OmnipresentEventData)[Name]) => void | Promise<void>) => emittery.UnsubscribeFunction;
+        off: <Name_1 extends keyof StreamEventData | keyof emittery.OmnipresentEventData>(eventName: Name_1 | readonly Name_1[], listener: (eventData: (StreamEventData & emittery.OmnipresentEventData)[Name_1]) => void | Promise<void>) => void;
+        once: <Name_2 extends keyof StreamEventData | keyof emittery.OmnipresentEventData>(eventName: Name_2 | readonly Name_2[]) => emittery.EmitteryOncePromise<(StreamEventData & emittery.OmnipresentEventData)[Name_2]>;
+        events: <Name_3 extends keyof StreamEventData>(eventName: Name_3 | readonly Name_3[]) => AsyncIterableIterator<StreamEventData[Name_3]>;
+    };
+    /**
+     * 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(): string;
+    /**
+     * 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.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the Cartesia streaming WebSocket.
+     */
+    disconnect(): void;
+}
+
+export { type Chunk as C, type StreamEventData as S, type Sentinel as a, base64ToArray as b, createMessageHandlerForContextId as c, getSentinel as d, export_default as e, filterSentinel as f, getBufferDuration as g, isComplete as h, isSentinel as i, playAudioBuffer as p };

package/dist/lib/client.d.mts

@@ -0,0 +1,9 @@
+import { ClientOptions } from '../types/index.mjs';
+
+declare class Client {
+    apiKey: string;
+    baseUrl: string;
+    constructor(options?: ClientOptions);
+}
+
+export { Client };

package/dist/lib/client.d.ts

@@ -0,0 +1,9 @@
+import { ClientOptions } from '../types/index.js';
+
+declare class Client {
+    apiKey: string;
+    baseUrl: string;
+    constructor(options?: ClientOptions);
+}
+
+export { Client };

package/dist/lib/client.js

@@ -0,0 +1,43 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/client.ts
+var client_exports = {};
+__export(client_exports, {
+  Client: () => Client
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/lib/constants.ts
+var BASE_URL = "https://api.cartesia.ai/v0";
+
+// src/lib/client.ts
+var Client = class {
+  constructor(options = {}) {
+    if (!(options.apiKey || process.env.CARTESIA_API_KEY)) {
+      throw new Error("Missing Cartesia API key.");
+    }
+    this.apiKey = options.apiKey || process.env.CARTESIA_API_KEY;
+    this.baseUrl = options.baseUrl || BASE_URL;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Client
+});

package/dist/lib/client.mjs

@@ -0,0 +1,7 @@
+import {
+  Client
+} from "../chunk-ERFCRIWU.mjs";
+import "../chunk-35HX6ML3.mjs";
+export {
+  Client
+};

package/dist/lib/constants.d.mts

@@ -0,0 +1,5 @@
+declare const BASE_URL = "https://api.cartesia.ai/v0";
+declare const SAMPLE_RATE = 44100;
+declare const constructWebsocketUrl: (baseUrl: string) => URL;
+
+export { BASE_URL, SAMPLE_RATE, constructWebsocketUrl };

package/dist/lib/constants.d.ts

@@ -0,0 +1,5 @@
+declare const BASE_URL = "https://api.cartesia.ai/v0";
+declare const SAMPLE_RATE = 44100;
+declare const constructWebsocketUrl: (baseUrl: string) => URL;
+
+export { BASE_URL, SAMPLE_RATE, constructWebsocketUrl };