# @amaster\.ai/tts-client 中文文档

规范地址：https://npmcn.com/package/%40amaster.ai/tts-client/

版本：1\.1\.72
npm 元数据更新时间：2026-11-05T13:04:19.991Z
中文译文更新时间：2026-11-07T07:17:27.132Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40amaster.ai/tts-client
原文对照：https://npmcn.com/package/%40amaster.ai/tts-client/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：184 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-02-02T03:39:13.373Z
- 最新版本发布：2026-11-05T13:04:19.756Z
- 近 30 天下载量：2016（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：202（近 12 个月 202 个）

## 中文简介

Qwen TTS 实时WebSocket客户端的音频播放

## 安装

```sh
npm install @amaster.ai/tts-client
```

也可以使用：`pnpm add @amaster.ai/tts-client`、`yarn add @amaster.ai/tts-client`、`bun add @amaster.ai/tts-client`

## README

# TTS Realtime WebSocket Client SDK

基于 WebSocket 的实时文本转语音（TTS）客户端 SDK，用于对接 `qwen-tts` 实时语音合成服务，支持流式音频返回与自动播放。

* * *

## 特性

-   🔊 WebSocket 实时 TTS
-   🎵 支持多种音频格式（`pcm` / `mp3` / `wav` / `opus`）
-   ▶️ 支持自动播放或手动播放
-   📦 支持音频流分片回调
-   🎧 浏览器原生 `AudioContext` 播放（PCM）
-   🎭 多种音色可选

* * *

## 安装

```bash
# npm
npm install @amaster.ai/tts-client

# pnpm
pnpm add @amaster.ai/tts-client

# yarn
yarn add @amaster.ai/tts-client
```

* * *

## 快速开始

### 基础用法

```ts
import { createTTSClient } from "@amaster.ai/tts-client";

const tts = createTTSClient({
  voice: "Cherry",
  autoPlay: true,
  audioFormat: "pcm",
  sampleRate: 24000,
  onReady() {
    console.log("TTS 已就绪");
  },
  onAudioStart() {
    console.log("开始播放");
  },
  onAudioEnd() {
    console.log("播放结束");
  },
  onAudioChunk(chunks) {
    console.log("收到音频片段:", chunks.length);
  },
  onError(err) {
    console.error("TTS 错误:", err);
  },
});

// 建立连接
await tts.connect();

// 合成并播放语音
await tts.speak("你好，欢迎使用实时语音合成服务。");

// 关闭连接
// tts.close();
```

* * *

### React 完整示例

```tsx
import { useRef, useState } from "react";
import { createTTSClient, type TTSClient } from "@amaster.ai/tts-client";

const VoiceTypes = {
  Cherry: "Cherry - 甜美女声",
  Serena: "苏瑶 - 温柔小姐姐",
  Ethan: "晨煦 - 标准普通话",
  Chelsie: "千雪 - 二次元虚拟女友",
  Peter: "天津话",
};

function TTSPlayer() {
  const [voice, setVoice] = useState("Cherry");
  const [connected, setConnected] = useState(false);
  const [status, setStatus] = useState("disconnected");
  const [text, setText] = useState("你好，欢迎使用通义千问实时语音合成服务。");
  const clientRef = useRef<TTSClient | null>(null);

  const connectTTS = () => {
    if (clientRef.current) return;

    const ttsClient = createTTSClient({
      voice,
      autoPlay: true,
      audioFormat: "pcm",
      sampleRate: 24000,
      onReady: () => {
        setConnected(true);
        setStatus("connected");
      },
      onAudioStart: () => setStatus("playing"),
      onAudioEnd: () => setStatus("connected"),
      onAudioChunk: (chunks) => {
        console.log("音频片段数:", chunks.length);
      },
      onError: (err) => {
        console.error("TTS Error:", err);
        setStatus("error");
        setConnected(false);
      },
    });

    ttsClient.connect();
    clientRef.current = ttsClient;
  };

  const sendTTS = () => {
    if (!text || !clientRef.current) return;
    clientRef.current.speak(text);
  };

  const disconnectTTS = () => {
    clientRef.current?.close();
    clientRef.current = null;
    setConnected(false);
    setStatus("disconnected");
  };

  return (
    <div>
      <h3>🔊 实时语音合成（TTS）</h3>

      <div>状态: {status}</div>

      <div>
        <label>音色:</label>
        <select value={voice} onChange={(e) => setVoice(e.target.value)}>
          {Object.entries(VoiceTypes).map(([key, label]) => (
            <option key={key} value={key}>
              {label}
            </option>
          ))}
        </select>
      </div>

      <div>
        <label>合成文本:</label>
        <textarea rows={4} value={text} onChange={(e) => setText(e.target.value)} />
      </div>

      <div>
        <button onClick={connectTTS} disabled={connected}>
          1. 连接
        </button>
        <button onClick={sendTTS} disabled={!connected}>
          2. 合成语音
        </button>
        <button onClick={disconnectTTS} disabled={!connected}>
          断开
        </button>
      </div>
    </div>
  );
}
```

* * *

## API 说明

### `createTTSClient(config)`

创建一个 TTS 客户端实例。

#### `TTSClientConfig`

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `voice` | `string` | `"Cherry"` | 发音人名称，可选值：`Cherry`, `Serena`, `Ethan`, `Chelsie`, `Peter` 等 |
| `autoPlay` | `boolean` | `true` | 是否在音频接收完成后自动播放 |
| `audioFormat` | `"pcm" | "mp3" | "wav" | "opus"` | `"pcm"` | 音频格式，**注意：内置播放仅支持 `pcm`** |
| `sampleRate` | `number` | `24000` | 采样率 |
| `getAccessToken` | `() => string | null` | \- | 获取访问令牌（用于 WebSocket 认证） |
| `onReady` | `() => void` | \- | 会话初始化完成回调 |
| `onAudioStart` | `() => void` | \- | 音频开始播放回调 |
| `onAudioEnd` | `() => void` | \- | 音频播放结束回调 |
| `onAudioChunk` | `(chunks: string[]) => void` | \- | 接收到音频分片回调 |
| `onError` | `(error: Error) => void` | \- | 错误回调 |

#### `TTSClient`

```ts
interface TTSClient {
  connect(): Promise<void>; // 建立 WebSocket 连接
  speak(text: string): Promise<void>; // 发送文本进行语音合成
  play(): void; // 手动播放（autoPlay=false 时使用）
  close(): void; // 关闭连接并释放资源
}
```

* * *

## 配合统一客户端使用

推荐与 `@amaster.ai/client` 统一客户端一起使用，自动处理认证：

```tsx
import { createClient } from "@amaster.ai/client";

const client = createClient();

const ttsClient = client.tts({
  voice: "Cherry",
  autoPlay: true,
  onReady() {
    console.log("TTS 已就绪");
  },
  onAudioStart() {
    console.log("开始播放");
  },
  onAudioEnd() {
    console.log("播放结束");
  },
});

await ttsClient.connect();
await ttsClient.speak("你好，欢迎使用 Amaster AI！");
```

* * *

## 音频说明

-   当前内置播放逻辑 **仅支持 `pcm` 格式**
-   `pcm` 数据为 **16-bit little-endian 单声道**
-   播放基于 `AudioContext`，仅支持浏览器环境
-   若使用 `mp3 / wav / opus`，需自行实现解码与播放逻辑

* * *

## 运行环境

-   浏览器（Chrome / Edge / Safari）
-   需支持：
    -   WebSocket
    -   AudioContext
    -   atob

* * *

## 注意事项

-   WebSocket 必须在 `connect()` 成功后才能调用 `speak()`
-   多次 `speak()` 会覆盖之前的音频缓存
-   自动播放依赖浏览器的自动播放策略，部分场景可能需要用户交互触发
-   建议在组件卸载时调用 `close()` 释放资源

* * *

## License

MIT

## 常见问题

### @amaster\.ai/tts-client 是什么？

Qwen TTS 实时WebSocket客户端的音频播放

### 如何安装 @amaster\.ai/tts-client？

在项目目录运行 npm install @amaster\.ai/tts-client，或使用 pnpm add / yarn add / bun add。

### @amaster\.ai/tts-client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @amaster\.ai/tts-client 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @amaster\.ai/tts-client 可以商用吗？

@amaster\.ai/tts-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @amaster\.ai/tts-client 的下载量有多少？

根据 npm 官方下载统计，@amaster\.ai/tts-client 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,016 次，日均约 67 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @amaster\.ai/tts-client 还在维护吗？

最新版本 1\.1\.72 发布于 2026/11/05（2 天前）；至今共发布 202 个版本，其中过去 12 个月发布了 202 个；首次发布于 2026/02/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。