@cartesia/cartesia-js 1.0.0-alpha.4 → 1.0.1

package/dist/react/index.cjs

@@ -22,6 +22,18 @@ var __spreadValues = (a, b) => {
   return a;
 };
 var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -135,7 +147,13 @@ var import_partysocket = require("partysocket");
 
 // src/tts/source.ts
 var import_emittery = __toESM(require("emittery"), 1);
-var _emitter, _buffer, _readIndex, _writeIndex, _closed, _sampleRate;
+var ENCODING_MAP = {
+  pcm_f32le: { arrayType: Float32Array, bytesPerElement: 4 },
+  pcm_s16le: { arrayType: Int16Array, bytesPerElement: 2 },
+  pcm_alaw: { arrayType: Uint8Array, bytesPerElement: 1 },
+  pcm_mulaw: { arrayType: Uint8Array, bytesPerElement: 1 }
+};
+var _emitter, _buffer, _readIndex, _writeIndex, _closed, _sampleRate, _encoding, _container, _createBuffer, createBuffer_fn;
 var Source = class {
   /**
    * Create a new Source.
@@ -143,23 +161,44 @@ var Source = class {
    * @param options - Options for the Source.
    * @param options.sampleRate - The sample rate of the audio.
    */
-  constructor({ sampleRate }) {
+  constructor({
+    sampleRate,
+    encoding,
+    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.
+     */
+    __privateAdd(this, _createBuffer);
     __privateAdd(this, _emitter, new import_emittery.default());
     __privateAdd(this, _buffer, void 0);
     __privateAdd(this, _readIndex, 0);
     __privateAdd(this, _writeIndex, 0);
     __privateAdd(this, _closed, false);
     __privateAdd(this, _sampleRate, void 0);
+    __privateAdd(this, _encoding, void 0);
+    __privateAdd(this, _container, void 0);
     this.on = __privateGet(this, _emitter).on.bind(__privateGet(this, _emitter));
     this.once = __privateGet(this, _emitter).once.bind(__privateGet(this, _emitter));
     this.events = __privateGet(this, _emitter).events.bind(__privateGet(this, _emitter));
     this.off = __privateGet(this, _emitter).off.bind(__privateGet(this, _emitter));
     __privateSet(this, _sampleRate, sampleRate);
-    __privateSet(this, _buffer, new Float32Array(1024));
+    __privateSet(this, _encoding, encoding);
+    __privateSet(this, _container, container);
+    __privateSet(this, _buffer, __privateMethod(this, _createBuffer, createBuffer_fn).call(this, 1024));
   }
   get sampleRate() {
     return __privateGet(this, _sampleRate);
   }
+  get encoding() {
+    return __privateGet(this, _encoding);
+  }
+  get container() {
+    return __privateGet(this, _container);
+  }
   /**
    * Append audio to the buffer.
    *
@@ -173,7 +212,7 @@ var Source = class {
         while (newCapacity < requiredCapacity) {
           newCapacity *= 2;
         }
-        const newBuffer = new Float32Array(newCapacity);
+        const newBuffer = __privateMethod(this, _createBuffer, createBuffer_fn).call(this, newCapacity);
         newBuffer.set(__privateGet(this, _buffer));
         __privateSet(this, _buffer, newBuffer);
       }
@@ -221,6 +260,9 @@ var Source = class {
   get readIndex() {
     return __privateGet(this, _readIndex);
   }
+  get writeIndex() {
+    return __privateGet(this, _writeIndex);
+  }
   /**
    * Close the source. This signals that no more audio will be enqueued.
    *
@@ -242,19 +284,27 @@ _readIndex = new WeakMap();
 _writeIndex = new WeakMap();
 _closed = new WeakMap();
 _sampleRate = new WeakMap();
+_encoding = new WeakMap();
+_container = new WeakMap();
+_createBuffer = new WeakSet();
+createBuffer_fn = function(size) {
+  const { arrayType: ArrayType } = ENCODING_MAP[__privateGet(this, _encoding)];
+  return new ArrayType(size);
+};
 
 // src/tts/utils.ts
 var import_base64_js = __toESM(require("base64-js"), 1);
-function base64ToArray(b64) {
+function base64ToArray(b64, encoding) {
   const byteArrays = filterSentinel(b64).map((b) => import_base64_js.default.toByteArray(b));
+  const { arrayType: ArrayType, bytesPerElement } = ENCODING_MAP[encoding];
   const totalLength = byteArrays.reduce(
-    (acc, arr) => acc + arr.length / Float32Array.BYTES_PER_ELEMENT,
+    (acc, arr) => acc + arr.length / bytesPerElement,
     0
   );
-  const result = new Float32Array(totalLength);
+  const result = new ArrayType(totalLength);
   let offset = 0;
   for (const arr of byteArrays) {
-    const floats = new Float32Array(arr.buffer);
+    const floats = new ArrayType(arr.buffer);
     result.set(floats, offset);
     offset += floats.length;
   }
@@ -285,10 +335,10 @@ function createMessageHandlerForContextId(contextId, handler) {
     let chunk;
     if (message.done) {
       chunk = getSentinel();
-    } else {
+    } else if (message.type === "chunk") {
       chunk = message.data;
     }
-    handler({ chunk, message: event.data });
+    handler({ chunk, message: event.data, data: message });
   };
 }
 function getSentinel() {
@@ -312,14 +362,14 @@ function getEmitteryCallbacks(emitter) {
 }
 
 // src/tts/websocket.ts
-var _isConnected, _sampleRate2, _generateId, generateId_fn;
+var _isConnected, _sampleRate2, _container2, _encoding2, _generateId, generateId_fn;
 var WebSocket = class extends Client {
   /**
    * Create a new WebSocket client.
    *
    * @param args - Arguments to pass to the Client constructor.
    */
-  constructor({ sampleRate }, ...args) {
+  constructor({ sampleRate, container, encoding }, ...args) {
     super(...args);
     /**
      * Generate a unique ID suitable for a streaming context.
@@ -332,37 +382,47 @@ var WebSocket = class extends Client {
     __privateAdd(this, _generateId);
     __privateAdd(this, _isConnected, false);
     __privateAdd(this, _sampleRate2, void 0);
+    __privateAdd(this, _container2, void 0);
+    __privateAdd(this, _encoding2, void 0);
     __privateSet(this, _sampleRate2, sampleRate);
+    __privateSet(this, _container2, container != null ? container : "raw");
+    __privateSet(this, _encoding2, encoding != null ? encoding : "pcm_f32le");
   }
   /**
-   * Send a message over the WebSocket in order to start a stream.
+   * Send a message over the WebSocket to start a stream.
    *
-   * @param inputs - Stream options.
+   * @param inputs - Stream options. 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 `0`, the stream will not time out.
+   *                          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, { timeout = 0 } = {}) {
-    var _a, _b, _c, _d;
+  send(_a, { timeout = 0 } = {}) {
+    var inputs = __objRest(_a, []);
+    var _a2, _b, _c, _d;
     if (!__privateGet(this, _isConnected)) {
       throw new Error("Not connected to WebSocket. Call .connect() first.");
     }
-    const contextId = __privateMethod(this, _generateId, generateId_fn).call(this);
-    (_a = this.socket) == null ? void 0 : _a.send(
-      JSON.stringify(__spreadProps(__spreadValues({
-        context_id: contextId
-      }, inputs), {
-        output_format: {
-          container: "raw",
-          encoding: "pcm_f32le",
-          sample_rate: __privateGet(this, _sampleRate2)
-        }
-      }))
+    if (!inputs.context_id) {
+      inputs.context_id = __privateMethod(this, _generateId, generateId_fn).call(this);
+    }
+    if (!inputs.output_format) {
+      inputs.output_format = {
+        container: __privateGet(this, _container2),
+        encoding: __privateGet(this, _encoding2),
+        sample_rate: __privateGet(this, _sampleRate2)
+      };
+    }
+    (_a2 = this.socket) == null ? void 0 : _a2.send(
+      JSON.stringify(__spreadValues({}, inputs))
     );
     const emitter = new import_emittery2.default();
     const source = new Source({
-      sampleRate: __privateGet(this, _sampleRate2)
+      sampleRate: __privateGet(this, _sampleRate2),
+      encoding: __privateGet(this, _encoding2),
+      container: __privateGet(this, _container2)
     });
     const streamCompleteController = new AbortController();
     let timeoutId = null;
@@ -370,19 +430,26 @@ var WebSocket = class extends Client {
       timeoutId = setTimeout(streamCompleteController.abort, timeout);
     }
     const handleMessage = createMessageHandlerForContextId(
-      contextId,
-      (_0) => __async(this, [_0], function* ({ chunk, message }) {
+      inputs.context_id,
+      (_0) => __async(this, [_0], function* ({ chunk, message, data }) {
         emitter.emit("message", message);
+        if (data.type === "timestamps") {
+          emitter.emit("timestamps", data.word_timestamps);
+          return;
+        }
         if (isSentinel(chunk)) {
           yield source.close();
           streamCompleteController.abort();
           return;
         }
-        yield source.enqueue(base64ToArray([chunk]));
         if (timeoutId) {
           clearTimeout(timeoutId);
           timeoutId = setTimeout(streamCompleteController.abort, timeout);
         }
+        if (!chunk) {
+          return;
+        }
+        yield source.enqueue(base64ToArray([chunk], __privateGet(this, _encoding2)));
       })
     );
     (_b = this.socket) == null ? void 0 : _b.addEventListener("message", handleMessage, {
@@ -412,7 +479,11 @@ var WebSocket = class extends Client {
         clearTimeout(timeoutId);
       }
     });
-    return __spreadValues({ source }, getEmitteryCallbacks(emitter));
+    return __spreadProps(__spreadValues({
+      source
+    }, getEmitteryCallbacks(emitter)), {
+      stop: streamCompleteController.abort.bind(streamCompleteController)
+    });
   }
   /**
    * Authenticate and connect to a Cartesia streaming WebSocket.
@@ -482,6 +553,8 @@ var WebSocket = class extends Client {
 };
 _isConnected = new WeakMap();
 _sampleRate2 = new WeakMap();
+_container2 = new WeakMap();
+_encoding2 = new WeakMap();
 _generateId = new WeakSet();
 generateId_fn = function() {
   return (0, import_human_id.humanId)({
@@ -563,8 +636,7 @@ var Cartesia = class extends Client {
 };
 
 // src/tts/player.ts
-var import_emittery3 = __toESM(require("emittery"), 1);
-var _context, _startNextPlaybackAt, _bufferDuration, _emitter2, _playBuffer, playBuffer_fn;
+var _context, _startNextPlaybackAt, _bufferDuration, _playBuffer, playBuffer_fn;
 var Player = class {
   /**
    * Create a new Player.
@@ -577,7 +649,6 @@ var Player = class {
     __privateAdd(this, _context, null);
     __privateAdd(this, _startNextPlaybackAt, 0);
     __privateAdd(this, _bufferDuration, void 0);
-    __privateAdd(this, _emitter2, new import_emittery3.default());
     __privateSet(this, _bufferDuration, bufferDuration);
   }
   /**
@@ -599,7 +670,6 @@ var Player = class {
         const playableAudio = buffer.subarray(0, read);
         plays.push(__privateMethod(this, _playBuffer, playBuffer_fn).call(this, playableAudio, source.sampleRate));
         if (read < buffer.length) {
-          yield __privateGet(this, _emitter2).emit("finish");
           break;
         }
       }
@@ -649,17 +719,33 @@ var Player = class {
       }
     });
   }
+  /**
+   * Stop the audio.
+   *
+   * @returns A promise that resolves when the audio has been stopped.
+   */
+  stop() {
+    return __async(this, null, function* () {
+      var _a;
+      if (!__privateGet(this, _context)) {
+        throw new Error("AudioContext not initialized.");
+      }
+      yield (_a = __privateGet(this, _context)) == null ? void 0 : _a.close();
+    });
+  }
 };
 _context = new WeakMap();
 _startNextPlaybackAt = new WeakMap();
 _bufferDuration = new WeakMap();
-_emitter2 = new WeakMap();
 _playBuffer = new WeakSet();
 playBuffer_fn = function(buf, sampleRate) {
   return __async(this, null, function* () {
     if (!__privateGet(this, _context)) {
       throw new Error("AudioContext not initialized.");
     }
+    if (buf.length === 0) {
+      return;
+    }
     const startAt = __privateGet(this, _startNextPlaybackAt);
     const duration = buf.length / sampleRate;
     __privateSet(this, _startNextPlaybackAt, duration + Math.max(__privateGet(this, _context).currentTime, __privateGet(this, _startNextPlaybackAt)));
@@ -683,7 +769,8 @@ var DEFAULT_BUFFER_DURATION = 0.01;
 function useTTS({
   apiKey,
   baseUrl,
-  sampleRate
+  sampleRate,
+  onError
 }) {
   var _a, _b;
   if (typeof window === "undefined") {
@@ -714,7 +801,11 @@ function useTTS({
     }
     const cartesia = new Cartesia({ apiKey, baseUrl });
     baseUrl = baseUrl != null ? baseUrl : cartesia.baseUrl;
-    return cartesia.tts.websocket({ sampleRate });
+    return cartesia.tts.websocket({
+      container: "raw",
+      encoding: "pcm_f32le",
+      sampleRate
+    });
   }, [apiKey, baseUrl, sampleRate]);
   const websocketReturn = (0, import_react.useRef)(null);
   const player = (0, import_react.useRef)(null);
@@ -726,21 +817,34 @@ function useTTS({
   const [messages, setMessages] = (0, import_react.useState)([]);
   const buffer = (0, import_react.useCallback)(
     (options) => __async(this, null, function* () {
-      var _a2;
-      setMessages([]);
-      setBufferStatus("buffering");
-      websocketReturn.current = (_a2 = websocket == null ? void 0 : websocket.send(options)) != null ? _a2 : null;
-      if (!websocketReturn.current) {
-        return;
+      var _a2, _b2;
+      (_a2 = websocketReturn.current) == null ? void 0 : _a2.stop();
+      try {
+        setMessages([]);
+        setBufferStatus("buffering");
+        websocketReturn.current = (_b2 = websocket == null ? void 0 : websocket.send(options)) != null ? _b2 : null;
+        if (!websocketReturn.current) {
+          return;
+        }
+        const unsubscribe = websocketReturn.current.on("message", (message) => {
+          const parsedMessage = JSON.parse(message);
+          setMessages((messages2) => [...messages2, parsedMessage]);
+          if (parsedMessage.error) {
+            onError == null ? void 0 : onError(new Error(parsedMessage.error));
+          }
+        });
+        yield websocketReturn.current.source.once("close");
+        setBufferStatus("buffered");
+        unsubscribe();
+      } catch (error) {
+        if (error instanceof Error) {
+          onError == null ? void 0 : onError(error);
+        } else {
+          console.error(error);
+        }
       }
-      const unsubscribe = websocketReturn.current.on("message", (message) => {
-        setMessages((messages2) => [...messages2, JSON.parse(message)]);
-      });
-      yield websocketReturn.current.source.once("close");
-      setBufferStatus("buffered");
-      unsubscribe();
     }),
-    [websocket]
+    [websocket, onError]
   );
   const metrics = (0, import_react.useMemo)(() => {
     var _a2;
@@ -809,53 +913,88 @@ function useTTS({
     return () => cleanup == null ? void 0 : cleanup();
   }, [websocket, baseUrl]);
   const play = (0, import_react.useCallback)(() => __async(this, null, function* () {
-    if (playbackStatus === "playing" || !websocketReturn.current) {
-      return;
-    }
-    setPlaybackStatus("playing");
-    const unsubscribes = [];
-    unsubscribes.push(
-      websocketReturn.current.source.on("wait", () => {
-        setIsWaiting(true);
-      })
-    );
-    unsubscribes.push(
-      websocketReturn.current.source.on("read", () => {
-        setIsWaiting(false);
-      })
-    );
-    player.current = new Player({
-      bufferDuration: bufferDuration != null ? bufferDuration : DEFAULT_BUFFER_DURATION
-    });
-    yield player.current.play(websocketReturn.current.source);
-    for (const unsubscribe of unsubscribes) {
-      unsubscribe();
+    try {
+      if (playbackStatus === "playing" || !websocketReturn.current) {
+        return;
+      }
+      if (player.current) {
+        yield player.current.stop();
+      }
+      setPlaybackStatus("playing");
+      const unsubscribes = [];
+      unsubscribes.push(
+        websocketReturn.current.source.on("wait", () => {
+          setIsWaiting(true);
+        })
+      );
+      unsubscribes.push(
+        websocketReturn.current.source.on("read", () => {
+          setIsWaiting(false);
+        })
+      );
+      player.current = new Player({
+        bufferDuration: bufferDuration != null ? bufferDuration : DEFAULT_BUFFER_DURATION
+      });
+      yield player.current.play(websocketReturn.current.source);
+      for (const unsubscribe of unsubscribes) {
+        unsubscribe();
+      }
+      setPlaybackStatus("finished");
+    } catch (error) {
+      if (error instanceof Error) {
+        onError == null ? void 0 : onError(error);
+      } else {
+        console.error(error);
+      }
     }
-    setPlaybackStatus("finished");
-  }), [playbackStatus, bufferDuration]);
+  }), [playbackStatus, bufferDuration, onError]);
   const pause = (0, import_react.useCallback)(() => __async(this, null, function* () {
     var _a2;
-    yield (_a2 = player.current) == null ? void 0 : _a2.pause();
-    setPlaybackStatus("paused");
-  }), []);
+    try {
+      yield (_a2 = player.current) == null ? void 0 : _a2.pause();
+      setPlaybackStatus("paused");
+    } catch (error) {
+      if (error instanceof Error) {
+        onError == null ? void 0 : onError(error);
+      } else {
+        console.error(error);
+      }
+    }
+  }), [onError]);
   const resume = (0, import_react.useCallback)(() => __async(this, null, function* () {
     var _a2;
-    yield (_a2 = player.current) == null ? void 0 : _a2.resume();
-    setPlaybackStatus("playing");
-  }), []);
+    try {
+      yield (_a2 = player.current) == null ? void 0 : _a2.resume();
+      setPlaybackStatus("playing");
+    } catch (error) {
+      if (error instanceof Error) {
+        onError == null ? void 0 : onError(error);
+      } else {
+        console.error(error);
+      }
+    }
+  }), [onError]);
   const toggle = (0, import_react.useCallback)(() => __async(this, null, function* () {
     var _a2;
-    yield (_a2 = player.current) == null ? void 0 : _a2.toggle();
-    setPlaybackStatus((status) => {
-      if (status === "playing") {
-        return "paused";
-      }
-      if (status === "paused") {
-        return "playing";
+    try {
+      yield (_a2 = player.current) == null ? void 0 : _a2.toggle();
+      setPlaybackStatus((status) => {
+        if (status === "playing") {
+          return "paused";
+        }
+        if (status === "paused") {
+          return "playing";
+        }
+        return status;
+      });
+    } catch (error) {
+      if (error instanceof Error) {
+        onError == null ? void 0 : onError(error);
+      } else {
+        console.error(error);
       }
-      return status;
-    });
-  }), []);
+    }
+  }), [onError]);
   return {
     buffer,
     play,

package/dist/react/index.d.cts

@@ -1,11 +1,12 @@
 import Source from '../tts/source.cjs';
+import { StreamRequest } from '../types/index.cjs';
 import 'emittery';
-import '../types/index.cjs';
 
 type UseTTSOptions = {
     apiKey: string | null;
     baseUrl?: string;
     sampleRate: number;
+    onError?: (error: Error) => void;
 };
 type PlaybackStatus = "inactive" | "playing" | "paused" | "finished";
 type BufferStatus = "inactive" | "buffering" | "buffered";
@@ -13,7 +14,7 @@ type Metrics = {
     modelLatency: number | null;
 };
 interface UseTTSReturn {
-    buffer: (options: object) => Promise<void>;
+    buffer: (options: StreamRequest) => Promise<void>;
     play: (bufferDuration?: number) => Promise<void>;
     pause: () => Promise<void>;
     resume: () => Promise<void>;
@@ -28,6 +29,6 @@ interface UseTTSReturn {
 /**
  * React hook to use the Cartesia audio API.
  */
-declare function useTTS({ apiKey, baseUrl, sampleRate, }: UseTTSOptions): UseTTSReturn;
+declare function useTTS({ apiKey, baseUrl, sampleRate, onError, }: UseTTSOptions): UseTTSReturn;
 
 export { type BufferStatus, type Metrics, type PlaybackStatus, type UseTTSOptions, type UseTTSReturn, useTTS };

package/dist/react/index.d.ts

@@ -1,11 +1,12 @@
 import Source from '../tts/source.js';
+import { StreamRequest } from '../types/index.js';
 import 'emittery';
-import '../types/index.js';
 
 type UseTTSOptions = {
     apiKey: string | null;
     baseUrl?: string;
     sampleRate: number;
+    onError?: (error: Error) => void;
 };
 type PlaybackStatus = "inactive" | "playing" | "paused" | "finished";
 type BufferStatus = "inactive" | "buffering" | "buffered";
@@ -13,7 +14,7 @@ type Metrics = {
     modelLatency: number | null;
 };
 interface UseTTSReturn {
-    buffer: (options: object) => Promise<void>;
+    buffer: (options: StreamRequest) => Promise<void>;
     play: (bufferDuration?: number) => Promise<void>;
     pause: () => Promise<void>;
     resume: () => Promise<void>;
@@ -28,6 +29,6 @@ interface UseTTSReturn {
 /**
  * React hook to use the Cartesia audio API.
  */
-declare function useTTS({ apiKey, baseUrl, sampleRate, }: UseTTSOptions): UseTTSReturn;
+declare function useTTS({ apiKey, baseUrl, sampleRate, onError, }: UseTTSOptions): UseTTSReturn;
 
 export { type BufferStatus, type Metrics, type PlaybackStatus, type UseTTSOptions, type UseTTSReturn, useTTS };