phonic 0.1.3 → 0.3.0

package/README.md

@@ -50,47 +50,106 @@ if (error === null) {
 
 ### Text-to-speech via WebSocket
 
+Open a WebSocket connection:
+
 ```js
-const { data, error } = await phonic.tts.websocket();
+const { data, error } = await phonic.tts.websocket({
+  model: "shasta",
+  output_format: "mulaw_8000",
+  voice_id: "australian-man",
+});
 
-if (error === null) {
-  const { phonicWebSocket } = data;
-  const stream = phonicWebSocket.send({
-    script: "How can I help you today?", // 600 characters max
-    output_format: "mulaw_8000", // or "pcm_44100"
-  });
-
-  for await (const data of stream) {
-    if (data instanceof Buffer) {
-      // Do something with the audio chunk,
-      // e.g. send `data.toString("base64")` to Twilio.
-    }
+if (error !== null) {
+  throw new Error(error.message);
+}
+
+// Here we know that the WebSocket connection is open.
+const { phonicWebSocket } = data;
+```
+
+Process audio chunks that Phonic sends back to you, by sending them to Twilio, for example:
+
+```js
+phonicWebSocket.onMessage((message) => {
+  if (message.type === "audio_chunk") {
+    ws.send(
+      JSON.stringify({
+        event: "media",
+        streamSid: "...",
+        media: {
+          payload: message.audio,
+        },
+      }),
+    );
   }
+});
+```
+
+Send text chunks to Phonic for audio generation as you receive them from LLM:
+
+```js
+const stream = await openai.chat.completions.create(...);
 
-  phonicWebSocket.close();
+for await (const chunk of stream) {
+  const text = chunk.choices[0]?.delta?.content || "";
+
+  if (text) {
+    phonicWebSocket.generate({ text });
+  }
 }
 ```
 
-To perform other work while receiving chunks, use:
+Tell Phonic to finish generating audio for all text chunks you've sent:
 
 ```js
-phonicWebSocket.onMessage((data) => {
-  if (data instanceof Buffer) {
-    // Do something with the audio chunk,
-    // e.g. send `data.toString("base64")` to Twilio.
+phonicWebSocket.flush();
+```
+
+You can also tell Phonic to stop sending audio chunks back, e.g. if the user interrupts the conversation:
+
+```js
+phonicWebSocket.stop();
+```
+
+To close the WebSocket connection:
+
+```js
+phonicWebSocket.close();
+```
+
+To know when the last audio chunk has been received:
+
+```js
+phonicWebSocket.onMessage((message) => {
+  if (message.type === "flushed") {
+    console.log("Last audio chunk received");
   }
 });
+```
 
-phonicWebSocket.send({
-  script: "How can I help you today?",
-  output_format: "mulaw_8000",
-});
+You can also listen for close and error events:
 
-// Perform other work here
+```js
+phonicWebSocket.onClose((event) => {
+  console.log(
+    `Phonic WebSocket closed with code ${event.code} and reason "${event.reason}"`,
+  );
+});
 
-await phonicWebSocket.streamEnded; // This Promise will be resolved once the last chunk is received
+phonicWebSocket.onError((event) => {
+  console.log(`Error from Phonic WebSocket: ${event.message}`);
+});
 ```
 
+## Release a new version to npm
+
+1. `bunx changeset`
+2. `git add .`
+3. `git commit -m "Add changeset"`
+4. `git push`
+
+Git action will run and create a PR.
+Once this PR is merged, the new version will be released to npm.
 
 ## License
 

package/dist/index.d.mts

@@ -18,39 +18,64 @@ type DataOrError<T> = Promise<{
     error: ErrorResponse;
 }>;
 
-type PhonicWebSocketMessage = {
-    script: string;
-    output_format: "pcm_44100" | "mulaw_8000";
+type PhonicWebSocketParams = {
+    model?: string;
+    output_format?: string;
+    voice_id?: string;
 };
 type PhonicWebSocketResponseMessage = {
-    type: "stream-ended";
-    error?: {
+    type: "config";
+    model: string;
+    output_format: string;
+    voice_id: string;
+} | {
+    type: "audio_chunk";
+    audio: string;
+    text: string;
+} | {
+    type: "flush_confirm";
+} | {
+    type: "stop_confirm";
+} | {
+    type: "error";
+    error: {
         message: string;
         code?: string;
     };
     paramErrors?: {
-        script?: string;
+        model?: string;
         output_format?: string;
+        voice_id?: string;
+        text?: string;
+        speed?: string;
     };
 };
-type OnMessageCallback = (data: PhonicWebSocketResponseMessage | Buffer) => void;
+type OnMessageCallback = (message: PhonicWebSocketResponseMessage) => void;
+type OnCloseCallback = (event: WebSocket.CloseEvent) => void;
+type OnErrorCallback = (event: WebSocket.ErrorEvent) => void;
 
 declare class PhonicWebSocket {
     private readonly ws;
     private onMessageCallback;
-    private streamEndedResolve;
-    readonly streamEnded: Promise<void>;
-    private streamController;
+    private onCloseCallback;
+    private onErrorCallback;
     constructor(ws: WebSocket);
     onMessage(callback: OnMessageCallback): void;
-    send(message: PhonicWebSocketMessage): ReadableStream<PhonicWebSocketResponseMessage | Buffer>;
+    onClose(callback: OnCloseCallback): void;
+    onError(callback: OnErrorCallback): void;
+    generate(message: {
+        text: string;
+        speed?: number;
+    }): void;
+    flush(): void;
+    stop(): void;
     close(): void;
 }
 
 declare class TextToSpeech {
     private readonly phonic;
     constructor(phonic: Phonic);
-    websocket(): DataOrError<{
+    websocket(params?: PhonicWebSocketParams): DataOrError<{
         phonicWebSocket: PhonicWebSocket;
     }>;
 }

package/dist/index.d.ts

@@ -18,39 +18,64 @@ type DataOrError<T> = Promise<{
     error: ErrorResponse;
 }>;
 
-type PhonicWebSocketMessage = {
-    script: string;
-    output_format: "pcm_44100" | "mulaw_8000";
+type PhonicWebSocketParams = {
+    model?: string;
+    output_format?: string;
+    voice_id?: string;
 };
 type PhonicWebSocketResponseMessage = {
-    type: "stream-ended";
-    error?: {
+    type: "config";
+    model: string;
+    output_format: string;
+    voice_id: string;
+} | {
+    type: "audio_chunk";
+    audio: string;
+    text: string;
+} | {
+    type: "flush_confirm";
+} | {
+    type: "stop_confirm";
+} | {
+    type: "error";
+    error: {
         message: string;
         code?: string;
     };
     paramErrors?: {
-        script?: string;
+        model?: string;
         output_format?: string;
+        voice_id?: string;
+        text?: string;
+        speed?: string;
     };
 };
-type OnMessageCallback = (data: PhonicWebSocketResponseMessage | Buffer) => void;
+type OnMessageCallback = (message: PhonicWebSocketResponseMessage) => void;
+type OnCloseCallback = (event: WebSocket.CloseEvent) => void;
+type OnErrorCallback = (event: WebSocket.ErrorEvent) => void;
 
 declare class PhonicWebSocket {
     private readonly ws;
     private onMessageCallback;
-    private streamEndedResolve;
-    readonly streamEnded: Promise<void>;
-    private streamController;
+    private onCloseCallback;
+    private onErrorCallback;
     constructor(ws: WebSocket);
     onMessage(callback: OnMessageCallback): void;
-    send(message: PhonicWebSocketMessage): ReadableStream<PhonicWebSocketResponseMessage | Buffer>;
+    onClose(callback: OnCloseCallback): void;
+    onError(callback: OnErrorCallback): void;
+    generate(message: {
+        text: string;
+        speed?: number;
+    }): void;
+    flush(): void;
+    stop(): void;
     close(): void;
 }
 
 declare class TextToSpeech {
     private readonly phonic;
     constructor(phonic: Phonic);
-    websocket(): DataOrError<{
+    websocket(params?: PhonicWebSocketParams): DataOrError<{
         phonicWebSocket: PhonicWebSocket;
     }>;
 }

package/dist/index.js

@@ -35,7 +35,7 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // package.json
-var version = "0.1.3";
+var version = "0.3.0";
 
 // src/tts/index.ts
 var import_ws = __toESM(require("ws"));
@@ -45,45 +45,58 @@ var PhonicWebSocket = class {
   constructor(ws) {
     this.ws = ws;
     this.ws.onmessage = (event) => {
-      if (typeof event.data === "string") {
-        const dataObj = JSON.parse(
-          event.data
-        );
-        this.onMessageCallback?.(dataObj);
-        if (dataObj.type === "stream-ended") {
-          this.streamEndedResolve();
-          this.streamController?.close();
-        } else {
-          this.streamController?.enqueue(dataObj);
-        }
-      } else if (event.data instanceof Buffer) {
-        this.onMessageCallback?.(event.data);
-        this.streamController?.enqueue(event.data);
+      if (this.onMessageCallback === null) {
+        return;
+      }
+      if (typeof event.data !== "string") {
+        throw new Error("Received non-string message");
+      }
+      const dataObj = JSON.parse(event.data);
+      this.onMessageCallback(dataObj);
+    };
+    this.ws.onclose = (event) => {
+      if (this.onCloseCallback === null) {
+        return;
       }
+      this.onCloseCallback(event);
     };
+    this.ws.onerror = (event) => {
+      if (this.onErrorCallback === null) {
+        return;
+      }
+      this.onErrorCallback(event);
+    };
+    this.onMessage = this.onMessage.bind(this);
+    this.generate = this.generate.bind(this);
+    this.flush = this.flush.bind(this);
+    this.stop = this.stop.bind(this);
+    this.close = this.close.bind(this);
   }
   onMessageCallback = null;
-  streamEndedResolve = () => {
-  };
-  streamEnded = new Promise((resolve) => {
-    this.streamEndedResolve = resolve;
-  });
-  streamController = null;
+  onCloseCallback = null;
+  onErrorCallback = null;
   onMessage(callback) {
     this.onMessageCallback = callback;
   }
-  send(message) {
-    const self = this;
-    try {
-      self.streamController?.close();
-    } catch (error) {
-    }
-    this.ws.send(JSON.stringify(message));
-    return new ReadableStream({
-      start(controller) {
-        self.streamController = controller;
-      }
-    });
+  onClose(callback) {
+    this.onCloseCallback = callback;
+  }
+  onError(callback) {
+    this.onErrorCallback = callback;
+  }
+  generate(message) {
+    this.ws.send(
+      JSON.stringify({
+        type: "generate",
+        ...message
+      })
+    );
+  }
+  flush() {
+    this.ws.send(JSON.stringify({ type: "flush" }));
+  }
+  stop() {
+    this.ws.send(JSON.stringify({ type: "stop" }));
   }
   close() {
     this.ws.close();
@@ -95,10 +108,11 @@ var TextToSpeech = class {
   constructor(phonic) {
     this.phonic = phonic;
   }
-  async websocket() {
+  async websocket(params) {
     return new Promise((resolve) => {
       const wsBaseUrl = this.phonic.baseUrl.replace(/^http/, "ws");
-      const ws = new import_ws.default(`${wsBaseUrl}/v1/tts/ws`, {
+      const queryString = new URLSearchParams(params).toString();
+      const ws = new import_ws.default(`${wsBaseUrl}/v1/tts/ws?${queryString}`, {
         headers: {
           Authorization: `Bearer ${this.phonic.apiKey}`
         }

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.1.3";
+var version = "0.3.0";
 
 // src/tts/index.ts
 import WebSocket from "ws";
@@ -9,45 +9,58 @@ var PhonicWebSocket = class {
   constructor(ws) {
     this.ws = ws;
     this.ws.onmessage = (event) => {
-      if (typeof event.data === "string") {
-        const dataObj = JSON.parse(
-          event.data
-        );
-        this.onMessageCallback?.(dataObj);
-        if (dataObj.type === "stream-ended") {
-          this.streamEndedResolve();
-          this.streamController?.close();
-        } else {
-          this.streamController?.enqueue(dataObj);
-        }
-      } else if (event.data instanceof Buffer) {
-        this.onMessageCallback?.(event.data);
-        this.streamController?.enqueue(event.data);
+      if (this.onMessageCallback === null) {
+        return;
+      }
+      if (typeof event.data !== "string") {
+        throw new Error("Received non-string message");
+      }
+      const dataObj = JSON.parse(event.data);
+      this.onMessageCallback(dataObj);
+    };
+    this.ws.onclose = (event) => {
+      if (this.onCloseCallback === null) {
+        return;
       }
+      this.onCloseCallback(event);
     };
+    this.ws.onerror = (event) => {
+      if (this.onErrorCallback === null) {
+        return;
+      }
+      this.onErrorCallback(event);
+    };
+    this.onMessage = this.onMessage.bind(this);
+    this.generate = this.generate.bind(this);
+    this.flush = this.flush.bind(this);
+    this.stop = this.stop.bind(this);
+    this.close = this.close.bind(this);
   }
   onMessageCallback = null;
-  streamEndedResolve = () => {
-  };
-  streamEnded = new Promise((resolve) => {
-    this.streamEndedResolve = resolve;
-  });
-  streamController = null;
+  onCloseCallback = null;
+  onErrorCallback = null;
   onMessage(callback) {
     this.onMessageCallback = callback;
   }
-  send(message) {
-    const self = this;
-    try {
-      self.streamController?.close();
-    } catch (error) {
-    }
-    this.ws.send(JSON.stringify(message));
-    return new ReadableStream({
-      start(controller) {
-        self.streamController = controller;
-      }
-    });
+  onClose(callback) {
+    this.onCloseCallback = callback;
+  }
+  onError(callback) {
+    this.onErrorCallback = callback;
+  }
+  generate(message) {
+    this.ws.send(
+      JSON.stringify({
+        type: "generate",
+        ...message
+      })
+    );
+  }
+  flush() {
+    this.ws.send(JSON.stringify({ type: "flush" }));
+  }
+  stop() {
+    this.ws.send(JSON.stringify({ type: "stop" }));
   }
   close() {
     this.ws.close();
@@ -59,10 +72,11 @@ var TextToSpeech = class {
   constructor(phonic) {
     this.phonic = phonic;
   }
-  async websocket() {
+  async websocket(params) {
     return new Promise((resolve) => {
       const wsBaseUrl = this.phonic.baseUrl.replace(/^http/, "ws");
-      const ws = new WebSocket(`${wsBaseUrl}/v1/tts/ws`, {
+      const queryString = new URLSearchParams(params).toString();
+      const ws = new WebSocket(`${wsBaseUrl}/v1/tts/ws?${queryString}`, {
         headers: {
           Authorization: `Bearer ${this.phonic.apiKey}`
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phonic",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "Phonic Node.js SDK",
   "scripts": {
     "build": "tsup",
@@ -38,11 +38,11 @@
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
     "@changesets/changelog-github": "0.5.0",
-    "@changesets/cli": "2.27.10",
+    "@changesets/cli": "2.27.11",
     "@types/bun": "1.1.14",
     "tsup": "8.3.5",
     "typescript": "5.7.2",
-    "zod": "3.23.8"
+    "zod": "3.24.1"
   },
   "files": ["dist/**"],
   "author": {