@amaster.ai/tts-client 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amaster Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# @amaster.ai/tts-client
+
+通义千问实时语音合成（TTS）WebSocket 客户端，支持自动音频播放。
+
+## 特性
+
+- ✅ 完整的 WebSocket 协议封装
+- ✅ 自动音频解码和播放（Web Audio API）
+- ✅ 事件驱动的 API 设计
+- ✅ TypeScript 类型支持
+- ✅ 基于实际调试验证的实现
+
+## 安装
+
+```bash
+npm install @amaster.ai/tts-client
+```
+
+## 快速开始
+
+```typescript
+import { createTTSClient } from '@amaster.ai/tts-client';
+
+// 创建客户端
+const tts = createTTSClient({
+  gatewayUrl: 'ws://www.appok.ai/api/proxy/builtin/platform/qwen-tts/api-ws/v1/realtime',
+  voice: 'Cherry',
+  autoPlay: true, // 自动播放音频
+});
+
+// 监听事件
+tts.on('session-created', (session) => {
+  console.log('会话创建:', session.id, session.model);
+});
+
+tts.on('audio-chunk', ({ chunk, count }) => {
+  console.log('接收音频片段:', count);
+});
+
+tts.on('completed', () => {
+  console.log('合成完成');
+});
+
+// 连接并合成
+await tts.connect();
+await tts.speak('你好，欢迎使用通义千问实时语音合成服务。');
+```
+
+## API 文档
+
+### createTTSClient(config)
+
+创建 TTS 客户端实例。
+
+**参数**：
+- `gatewayUrl`: Gateway WebSocket URL（会自动追加 model 参数）
+- `voice`: 音色名称，默认 `'Cherry'`
+- `autoPlay`: 是否自动播放，默认 `true`
+- `audioFormat`: 音频格式，默认 `'pcm'`
+- `sampleRate`: 采样率，默认 `24000`
+
+**返回**：`TTSClient` 实例
+
+### TTSClient
+
+#### connect()
+
+连接到 TTS 服务。
+
+**返回**：`Promise<void>`
+
+#### speak(text)
+
+合成语音。
+
+**参数**：
+- `text`: 要合成的文本
+
+**返回**：`Promise<void>`
+
+#### on(event, callback)
+
+监听事件。
+
+**事件类型**：
+- `connected`: WebSocket 连接建立
+- `session-created`: 会话创建成功
+- `session-updated`: 会话配置完成
+- `audio-chunk`: 收到音频片段
+- `audio-done`: 音频生成完成
+- `completed`: 响应完成
+- `error`: 发生错误
+- `closed`: 连接关闭
+
+#### disconnect()
+
+断开连接并清理资源。
+
+#### getSession()
+
+获取当前会话信息。
+
+**返回**：`TTSSession | null`
+
+## 实现细节
+
+### 音频格式处理
+
+- 接收：Base64 编码的 PCM 16-bit 数据
+- 解码：自动转换为 Float32 AudioBuffer
+- 播放：使用 Web Audio API
+- 采样率：24kHz（高清音质）
+
+### WebSocket 协议
+
+基于实际验证的消息类型：
+- `session.update` - 配置会话
+- `input_text_buffer.append` - 发送文本
+- `input_text_buffer.commit` - 提交文本
+- `session.finish` - 结束会话
+
+### 错误处理
+
+自动处理：
+- WebSocket 连接错误
+- 会话配置错误
+- 音频解码错误
+
+## 开发
+
+```bash
+# 构建
+npm run build
+
+# 开发模式
+npm run dev
+
+# 类型检查
+npm run type-check
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,168 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createTTSClient: () => createTTSClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/tts-client.ts
+function createTTSClient(config) {
+  const {
+    url,
+    voice = "Cherry",
+    autoPlay = true,
+    audioFormat = "pcm",
+    sampleRate = 24e3,
+    onReady,
+    onAudioStart,
+    onAudioEnd,
+    onError
+  } = config;
+  let ws = null;
+  let audioChunks = [];
+  let audioContext = null;
+  async function connect() {
+    return new Promise((resolve, reject) => {
+      ws = new WebSocket(url);
+      ws.onopen = () => {
+      };
+      ws.onmessage = (event) => {
+        const data = JSON.parse(event.data);
+        if (data.type === "session.created") {
+          ws.send(JSON.stringify({
+            type: "session.update",
+            session: {
+              mode: "server_commit",
+              voice,
+              response_format: audioFormat,
+              sample_rate: sampleRate
+            }
+          }));
+        }
+        if (data.type === "session.updated") {
+          onReady?.();
+          resolve();
+        }
+        if (data.type === "response.audio.delta") {
+          audioChunks.push(data.delta);
+        }
+        if (data.type === "response.audio.done") {
+          if (autoPlay && typeof window !== "undefined") {
+            playAudio(audioChunks);
+          }
+        }
+        if (data.type === "response.done") {
+          ws.send(JSON.stringify({ type: "session.finish" }));
+        }
+        if (data.type === "error") {
+          const err = new Error(data.error?.message || "Unknown error");
+          onError?.(err);
+          reject(err);
+        }
+      };
+      ws.onerror = () => {
+        const err = new Error("WebSocket connection error");
+        onError?.(err);
+        reject(err);
+      };
+      ws.onclose = () => {
+        ws = null;
+      };
+    });
+  }
+  async function speak(text) {
+    if (!ws || ws.readyState !== WebSocket.OPEN) {
+      throw new Error("WebSocket not connected");
+    }
+    audioChunks = [];
+    ws.send(JSON.stringify({
+      type: "input_text_buffer.append",
+      text
+    }));
+    setTimeout(() => {
+      ws.send(JSON.stringify({
+        type: "input_text_buffer.commit"
+      }));
+    }, 100);
+  }
+  function playAudio(chunks) {
+    if (typeof window === "undefined") return;
+    try {
+      if (!audioContext) {
+        audioContext = new AudioContext();
+      }
+      onAudioStart?.();
+      let totalBytes = 0;
+      const allBytes = [];
+      for (const chunk of chunks) {
+        const binaryString = atob(chunk);
+        const bytes = new Uint8Array(binaryString.length);
+        for (let i = 0; i < binaryString.length; i++) {
+          bytes[i] = binaryString.charCodeAt(i);
+        }
+        allBytes.push(bytes);
+        totalBytes += bytes.length;
+      }
+      const combined = new Uint8Array(totalBytes);
+      let offset = 0;
+      for (const bytes of allBytes) {
+        combined.set(bytes, offset);
+        offset += bytes.length;
+      }
+      const numSamples = combined.length / 2;
+      const audioBuffer = audioContext.createBuffer(1, numSamples, sampleRate);
+      const channelData = audioBuffer.getChannelData(0);
+      const dataView = new DataView(combined.buffer);
+      for (let i = 0; i < numSamples; i++) {
+        const int16 = dataView.getInt16(i * 2, true);
+        channelData[i] = int16 / 32768;
+      }
+      const source = audioContext.createBufferSource();
+      source.buffer = audioBuffer;
+      source.connect(audioContext.destination);
+      source.onended = () => onAudioEnd?.();
+      source.start(0);
+    } catch (err) {
+      onError?.(err);
+    }
+  }
+  function close() {
+    if (ws) {
+      ws.close();
+      ws = null;
+    }
+    if (audioContext) {
+      audioContext.close();
+      audioContext = null;
+    }
+  }
+  return {
+    connect,
+    speak,
+    close
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createTTSClient
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/tts-client.ts"],"sourcesContent":["export type { TTSClient, TTSClientConfig } from './tts-client';\nexport { createTTSClient } from './tts-client';\n","/**\n * TTS Realtime WebSocket Client\n */\n\nexport interface TTSClientConfig {\n  /** WebSocket endpoint URL */\n  url: string;\n  /** Voice name, default 'Cherry' */\n  voice?: string;\n  /** Auto play audio, default true */\n  autoPlay?: boolean;\n  /** Audio format, default 'pcm' */\n  audioFormat?: 'pcm' | 'mp3' | 'wav' | 'opus';\n  /** Sample rate, default 24000 */\n  sampleRate?: number;\n  /** Called when connection is ready */\n  onReady?: () => void;\n  /** Called when audio playback starts */\n  onAudioStart?: () => void;\n  /** Called when audio playback ends */\n  onAudioEnd?: () => void;\n  /** Called on error */\n  onError?: (error: Error) => void;\n}\n\nexport interface TTSClient {\n  /** Connect to TTS service */\n  connect(): Promise<void>;\n  /** Synthesize speech from text */\n  speak(text: string): Promise<void>;\n  /** Close connection */\n  close(): void;\n}\n\nexport function createTTSClient(config: TTSClientConfig): TTSClient {\n  const {\n    url,\n    voice = 'Cherry',\n    autoPlay = true,\n    audioFormat = 'pcm',\n    sampleRate = 24000,\n    onReady,\n    onAudioStart,\n    onAudioEnd,\n    onError,\n  } = config;\n\n  let ws: WebSocket | null = null;\n  let audioChunks: string[] = [];\n  let audioContext: AudioContext | null = null;\n\n  async function connect(): Promise<void> {\n    return new Promise((resolve, reject) => {\n      ws = new WebSocket(url);\n\n      ws.onopen = () => {};\n\n      ws.onmessage = (event) => {\n        const data = JSON.parse(event.data);\n\n        if (data.type === 'session.created') {\n          ws!.send(JSON.stringify({\n            type: 'session.update',\n            session: {\n              mode: 'server_commit',\n              voice,\n              response_format: audioFormat,\n              sample_rate: sampleRate,\n            },\n          }));\n        }\n\n        if (data.type === 'session.updated') {\n          onReady?.();\n          resolve();\n        }\n\n        if (data.type === 'response.audio.delta') {\n          audioChunks.push(data.delta);\n        }\n\n        if (data.type === 'response.audio.done') {\n          if (autoPlay && typeof window !== 'undefined') {\n            playAudio(audioChunks);\n          }\n        }\n\n        if (data.type === 'response.done') {\n          ws!.send(JSON.stringify({ type: 'session.finish' }));\n        }\n\n        if (data.type === 'error') {\n          const err = new Error(data.error?.message || 'Unknown error');\n          onError?.(err);\n          reject(err);\n        }\n      };\n\n      ws.onerror = () => {\n        const err = new Error('WebSocket connection error');\n        onError?.(err);\n        reject(err);\n      };\n\n      ws.onclose = () => {\n        ws = null;\n      };\n    });\n  }\n\n  async function speak(text: string): Promise<void> {\n    if (!ws || ws.readyState !== WebSocket.OPEN) {\n      throw new Error('WebSocket not connected');\n    }\n\n    audioChunks = [];\n\n    ws.send(JSON.stringify({\n      type: 'input_text_buffer.append',\n      text,\n    }));\n\n    setTimeout(() => {\n      ws!.send(JSON.stringify({\n        type: 'input_text_buffer.commit',\n      }));\n    }, 100);\n  }\n\n  function playAudio(chunks: string[]) {\n    if (typeof window === 'undefined') return;\n\n    try {\n      if (!audioContext) {\n        audioContext = new AudioContext();\n      }\n\n      onAudioStart?.();\n\n      let totalBytes = 0;\n      const allBytes: Uint8Array[] = [];\n\n      for (const chunk of chunks) {\n        const binaryString = atob(chunk);\n        const bytes = new Uint8Array(binaryString.length);\n        for (let i = 0; i < binaryString.length; i++) {\n          bytes[i] = binaryString.charCodeAt(i);\n        }\n        allBytes.push(bytes);\n        totalBytes += bytes.length;\n      }\n\n      const combined = new Uint8Array(totalBytes);\n      let offset = 0;\n      for (const bytes of allBytes) {\n        combined.set(bytes, offset);\n        offset += bytes.length;\n      }\n\n      const numSamples = combined.length / 2;\n      const audioBuffer = audioContext.createBuffer(1, numSamples, sampleRate);\n      const channelData = audioBuffer.getChannelData(0);\n\n      const dataView = new DataView(combined.buffer);\n      for (let i = 0; i < numSamples; i++) {\n        const int16 = dataView.getInt16(i * 2, true);\n        channelData[i] = int16 / 32768.0;\n      }\n\n      const source = audioContext.createBufferSource();\n      source.buffer = audioBuffer;\n      source.connect(audioContext.destination);\n      source.onended = () => onAudioEnd?.();\n      source.start(0);\n    } catch (err) {\n      onError?.(err as Error);\n    }\n  }\n\n  function close() {\n    if (ws) {\n      ws.close();\n      ws = null;\n    }\n    if (audioContext) {\n      audioContext.close();\n      audioContext = null;\n    }\n  }\n\n  return {\n    connect,\n    speak,\n    close,\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,34 @@
+/**
+ * TTS Realtime WebSocket Client
+ */
+interface TTSClientConfig {
+    /** WebSocket endpoint URL */
+    url: string;
+    /** Voice name, default 'Cherry' */
+    voice?: string;
+    /** Auto play audio, default true */
+    autoPlay?: boolean;
+    /** Audio format, default 'pcm' */
+    audioFormat?: 'pcm' | 'mp3' | 'wav' | 'opus';
+    /** Sample rate, default 24000 */
+    sampleRate?: number;
+    /** Called when connection is ready */
+    onReady?: () => void;
+    /** Called when audio playback starts */
+    onAudioStart?: () => void;
+    /** Called when audio playback ends */
+    onAudioEnd?: () => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+}
+interface TTSClient {
+    /** Connect to TTS service */
+    connect(): Promise<void>;
+    /** Synthesize speech from text */
+    speak(text: string): Promise<void>;
+    /** Close connection */
+    close(): void;
+}
+declare function createTTSClient(config: TTSClientConfig): TTSClient;
+
+export { type TTSClient, type TTSClientConfig, createTTSClient };

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * TTS Realtime WebSocket Client
+ */
+interface TTSClientConfig {
+    /** WebSocket endpoint URL */
+    url: string;
+    /** Voice name, default 'Cherry' */
+    voice?: string;
+    /** Auto play audio, default true */
+    autoPlay?: boolean;
+    /** Audio format, default 'pcm' */
+    audioFormat?: 'pcm' | 'mp3' | 'wav' | 'opus';
+    /** Sample rate, default 24000 */
+    sampleRate?: number;
+    /** Called when connection is ready */
+    onReady?: () => void;
+    /** Called when audio playback starts */
+    onAudioStart?: () => void;
+    /** Called when audio playback ends */
+    onAudioEnd?: () => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+}
+interface TTSClient {
+    /** Connect to TTS service */
+    connect(): Promise<void>;
+    /** Synthesize speech from text */
+    speak(text: string): Promise<void>;
+    /** Close connection */
+    close(): void;
+}
+declare function createTTSClient(config: TTSClientConfig): TTSClient;
+
+export { type TTSClient, type TTSClientConfig, createTTSClient };

package/dist/index.js

@@ -0,0 +1,141 @@
+// src/tts-client.ts
+function createTTSClient(config) {
+  const {
+    url,
+    voice = "Cherry",
+    autoPlay = true,
+    audioFormat = "pcm",
+    sampleRate = 24e3,
+    onReady,
+    onAudioStart,
+    onAudioEnd,
+    onError
+  } = config;
+  let ws = null;
+  let audioChunks = [];
+  let audioContext = null;
+  async function connect() {
+    return new Promise((resolve, reject) => {
+      ws = new WebSocket(url);
+      ws.onopen = () => {
+      };
+      ws.onmessage = (event) => {
+        const data = JSON.parse(event.data);
+        if (data.type === "session.created") {
+          ws.send(JSON.stringify({
+            type: "session.update",
+            session: {
+              mode: "server_commit",
+              voice,
+              response_format: audioFormat,
+              sample_rate: sampleRate
+            }
+          }));
+        }
+        if (data.type === "session.updated") {
+          onReady?.();
+          resolve();
+        }
+        if (data.type === "response.audio.delta") {
+          audioChunks.push(data.delta);
+        }
+        if (data.type === "response.audio.done") {
+          if (autoPlay && typeof window !== "undefined") {
+            playAudio(audioChunks);
+          }
+        }
+        if (data.type === "response.done") {
+          ws.send(JSON.stringify({ type: "session.finish" }));
+        }
+        if (data.type === "error") {
+          const err = new Error(data.error?.message || "Unknown error");
+          onError?.(err);
+          reject(err);
+        }
+      };
+      ws.onerror = () => {
+        const err = new Error("WebSocket connection error");
+        onError?.(err);
+        reject(err);
+      };
+      ws.onclose = () => {
+        ws = null;
+      };
+    });
+  }
+  async function speak(text) {
+    if (!ws || ws.readyState !== WebSocket.OPEN) {
+      throw new Error("WebSocket not connected");
+    }
+    audioChunks = [];
+    ws.send(JSON.stringify({
+      type: "input_text_buffer.append",
+      text
+    }));
+    setTimeout(() => {
+      ws.send(JSON.stringify({
+        type: "input_text_buffer.commit"
+      }));
+    }, 100);
+  }
+  function playAudio(chunks) {
+    if (typeof window === "undefined") return;
+    try {
+      if (!audioContext) {
+        audioContext = new AudioContext();
+      }
+      onAudioStart?.();
+      let totalBytes = 0;
+      const allBytes = [];
+      for (const chunk of chunks) {
+        const binaryString = atob(chunk);
+        const bytes = new Uint8Array(binaryString.length);
+        for (let i = 0; i < binaryString.length; i++) {
+          bytes[i] = binaryString.charCodeAt(i);
+        }
+        allBytes.push(bytes);
+        totalBytes += bytes.length;
+      }
+      const combined = new Uint8Array(totalBytes);
+      let offset = 0;
+      for (const bytes of allBytes) {
+        combined.set(bytes, offset);
+        offset += bytes.length;
+      }
+      const numSamples = combined.length / 2;
+      const audioBuffer = audioContext.createBuffer(1, numSamples, sampleRate);
+      const channelData = audioBuffer.getChannelData(0);
+      const dataView = new DataView(combined.buffer);
+      for (let i = 0; i < numSamples; i++) {
+        const int16 = dataView.getInt16(i * 2, true);
+        channelData[i] = int16 / 32768;
+      }
+      const source = audioContext.createBufferSource();
+      source.buffer = audioBuffer;
+      source.connect(audioContext.destination);
+      source.onended = () => onAudioEnd?.();
+      source.start(0);
+    } catch (err) {
+      onError?.(err);
+    }
+  }
+  function close() {
+    if (ws) {
+      ws.close();
+      ws = null;
+    }
+    if (audioContext) {
+      audioContext.close();
+      audioContext = null;
+    }
+  }
+  return {
+    connect,
+    speak,
+    close
+  };
+}
+export {
+  createTTSClient
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tts-client.ts"],"sourcesContent":["/**\n * TTS Realtime WebSocket Client\n */\n\nexport interface TTSClientConfig {\n  /** WebSocket endpoint URL */\n  url: string;\n  /** Voice name, default 'Cherry' */\n  voice?: string;\n  /** Auto play audio, default true */\n  autoPlay?: boolean;\n  /** Audio format, default 'pcm' */\n  audioFormat?: 'pcm' | 'mp3' | 'wav' | 'opus';\n  /** Sample rate, default 24000 */\n  sampleRate?: number;\n  /** Called when connection is ready */\n  onReady?: () => void;\n  /** Called when audio playback starts */\n  onAudioStart?: () => void;\n  /** Called when audio playback ends */\n  onAudioEnd?: () => void;\n  /** Called on error */\n  onError?: (error: Error) => void;\n}\n\nexport interface TTSClient {\n  /** Connect to TTS service */\n  connect(): Promise<void>;\n  /** Synthesize speech from text */\n  speak(text: string): Promise<void>;\n  /** Close connection */\n  close(): void;\n}\n\nexport function createTTSClient(config: TTSClientConfig): TTSClient {\n  const {\n    url,\n    voice = 'Cherry',\n    autoPlay = true,\n    audioFormat = 'pcm',\n    sampleRate = 24000,\n    onReady,\n    onAudioStart,\n    onAudioEnd,\n    onError,\n  } = config;\n\n  let ws: WebSocket | null = null;\n  let audioChunks: string[] = [];\n  let audioContext: AudioContext | null = null;\n\n  async function connect(): Promise<void> {\n    return new Promise((resolve, reject) => {\n      ws = new WebSocket(url);\n\n      ws.onopen = () => {};\n\n      ws.onmessage = (event) => {\n        const data = JSON.parse(event.data);\n\n        if (data.type === 'session.created') {\n          ws!.send(JSON.stringify({\n            type: 'session.update',\n            session: {\n              mode: 'server_commit',\n              voice,\n              response_format: audioFormat,\n              sample_rate: sampleRate,\n            },\n          }));\n        }\n\n        if (data.type === 'session.updated') {\n          onReady?.();\n          resolve();\n        }\n\n        if (data.type === 'response.audio.delta') {\n          audioChunks.push(data.delta);\n        }\n\n        if (data.type === 'response.audio.done') {\n          if (autoPlay && typeof window !== 'undefined') {\n            playAudio(audioChunks);\n          }\n        }\n\n        if (data.type === 'response.done') {\n          ws!.send(JSON.stringify({ type: 'session.finish' }));\n        }\n\n        if (data.type === 'error') {\n          const err = new Error(data.error?.message || 'Unknown error');\n          onError?.(err);\n          reject(err);\n        }\n      };\n\n      ws.onerror = () => {\n        const err = new Error('WebSocket connection error');\n        onError?.(err);\n        reject(err);\n      };\n\n      ws.onclose = () => {\n        ws = null;\n      };\n    });\n  }\n\n  async function speak(text: string): Promise<void> {\n    if (!ws || ws.readyState !== WebSocket.OPEN) {\n      throw new Error('WebSocket not connected');\n    }\n\n    audioChunks = [];\n\n    ws.send(JSON.stringify({\n      type: 'input_text_buffer.append',\n      text,\n    }));\n\n    setTimeout(() => {\n      ws!.send(JSON.stringify({\n        type: 'input_text_buffer.commit',\n      }));\n    }, 100);\n  }\n\n  function playAudio(chunks: string[]) {\n    if (typeof window === 'undefined') return;\n\n    try {\n      if (!audioContext) {\n        audioContext = new AudioContext();\n      }\n\n      onAudioStart?.();\n\n      let totalBytes = 0;\n      const allBytes: Uint8Array[] = [];\n\n      for (const chunk of chunks) {\n        const binaryString = atob(chunk);\n        const bytes = new Uint8Array(binaryString.length);\n        for (let i = 0; i < binaryString.length; i++) {\n          bytes[i] = binaryString.charCodeAt(i);\n        }\n        allBytes.push(bytes);\n        totalBytes += bytes.length;\n      }\n\n      const combined = new Uint8Array(totalBytes);\n      let offset = 0;\n      for (const bytes of allBytes) {\n        combined.set(bytes, offset);\n        offset += bytes.length;\n      }\n\n      const numSamples = combined.length / 2;\n      const audioBuffer = audioContext.createBuffer(1, numSamples, sampleRate);\n      const channelData = audioBuffer.getChannelData(0);\n\n      const dataView = new DataView(combined.buffer);\n      for (let i = 0; i < numSamples; i++) {\n        const int16 = dataView.getInt16(i * 2, true);\n        channelData[i] = int16 / 32768.0;\n      }\n\n      const source = audioContext.createBufferSource();\n      source.buffer = audioBuffer;\n      source.connect(audioContext.destination);\n      source.onended = () => onAudioEnd?.();\n      source.start(0);\n    } catch (err) {\n      onError?.(err as Error);\n    }\n  }\n\n  function close() {\n    if (ws) {\n      ws.close();\n      ws = null;\n    }\n    if (audioContext) {\n      audioContext.close();\n      audioContext = null;\n    }\n  }\n\n  return {\n    connect,\n    speak,\n    close,\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@amaster.ai/tts-client",
+  "version": "1.0.0-beta.1",
+  "description": "Qwen TTS Realtime WebSocket client with audio playback",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "tts",
+    "text-to-speech",
+    "qwen",
+    "realtime",
+    "websocket",
+    "audio",
+    "speech-synthesis"
+  ],
+  "author": "Amaster Team",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "~5.7.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "type-check": "tsc --noEmit"
+  }
+}