xunfei-tts/README.md

借助“讯飞在线语音合成API”实现浏览器端“文本转语音

> 基于讯飞在线语音合成 API 的浏览器端文本转语音解决方案

# ✨ 特性

- 🎯 **流式合成**：支持实时文本转语音，边输入边播放
- 🔧 **灵活配置**：丰富的音色、语速、音调等参数配置
- 🎵 **高音质**：支持多种音频编码格式（PCM、MP3、Speex 等）
- 🚀 **高性能**：采用串行处理器架构，优化音频处理流程
- 📱 **跨平台**：支持现代浏览器环境
- 🎛️ **事件驱动**：完整的生命周期事件回调
- 🔇 **音量控制**：支持静音/取消静音功能

# 📦 安装

```bash
# 使用 pnpm
pnpm install xunfei-tts

# 使用 npm
npm install xunfei-tts

# 使用 yarn
yarn add xunfei-tts
```

# 🚀 快速开始

## 1. 引入库

```javascript
import xunfeiTts from "xunfei-tts";
```

## 2. 配置系统参数

首先需要在[讯飞开放平台](https://www.xfyun.cn/)申请相关密钥：

```javascript
const systemConfig = {
  API_SECRET: "your_api_secret", // 在平台申请的密钥信息
  APPID: "your_appid", // 在平台申请的APPID信息
  API_KEY: "your_api_key", // 在平台申请的API_KEY信息
};

// 配置系统参数
xunfeiTts.config(systemConfig);
```

## 3. 创建 TTS 实例

```javascript
const ttsInstance = xunfeiTts.create({
  vcn: "xiaoyan", // 音色
  speed: 50, // 语速
  volume: 50, // 音量
  pitch: 50, // 音调
});
```

## 4. 使用 TTS 功能

```javascript
// 启动TTS服务
ttsInstance.start();

// 发送文本进行语音合成
ttsInstance.send("你好，欢迎使用讯飞语音合成服务！");

// 结束文本输入（但继续播放剩余音频）
ttsInstance.end();
```

# 📖 API 文档

## 主要方法

### `xunfeiTts.config(systemConfig)`

配置系统参数

**参数：**

- `systemConfig` (SystemConfig): 系统配置对象

```typescript
interface SystemConfig {
  API_SECRET: string; // 在平台申请的密钥信息
  APPID: string; // 在平台申请的APPID信息
  API_KEY: string; // 在平台申请的API_KEY信息
}
```

### `xunfeiTts.create(businessParams?)`

创建 TTS 控制器实例

**参数：**

- `businessParams` (Partial<BusinessParams>): 可选的业务参数

**返回：**

- `TtsController`: TTS 控制器实例

## TtsController 实例方法

### `start()`

启动 TTS 服务，进入待机状态等待文本输入

**返回：** `TtsController` - 支持链式调用

### `send(text)`

发送文本进行语音合成

**参数：**

- `text` (string): 待转换的文本

**返回：** `TtsController` - 支持链式调用

### `end()`

结束文本输入，但不停止音频播放

**返回：** `TtsController` - 支持链式调用

### `finish()`

停止所有处理器并重置状态，触发 `appFinish` 事件

### `mute()`

静音

### `unmute()`

取消静音

### `on(eventName, callback)`

监听事件

**参数：**

- `eventName` (string): 事件名称
- `callback` (function): 回调函数

**返回：** `TtsController` - 支持链式调用

# 🎛️ 配置参数

## BusinessParams 业务参数

```typescript
interface BusinessParams {
  aue?:
    | "raw"
    | "lame"
    | "speex-org-wb;7"
    | "speex-org-nb;7"
    | "speex;7"
    | "speex-wb;7"; // 音频编码
  sfl?: 1; // 流式返回开关
  auf?: "audio/L16;rate=8000" | "audio/L16;rate=16000"; // 音频采样率
  vcn: string; // 发音人
  speed?: number; // 语速 [0-100]
  volume?: number; // 音量 [0-100]
  pitch?: number; // 音高 [0-100]
  bgs?: 0 | 1; // 背景音
  tte?: "unicode" | "UTF8"; // 文本编码格式
  reg?: "0" | "1" | "2"; // 英文发音方式
  rdn?: "0" | "1" | "2" | "3"; // 数字发音方式
}
```

## 默认配置

```javascript
const defaultBusinessParams = {
  aue: "raw", // 未压缩的PCM
  sfl: 1, // 开启流式返回
  auf: "audio/L16;rate=16000", // 16K采样率
  vcn: "xiaoyan", // 小燕音色
  speed: 50, // 中等语速
  volume: 50, // 中等音量
  pitch: 50, // 中等音调
  bgs: 0, // 无背景音
  tte: "UTF8", // UTF8编码
  reg: "2", // 英文自动判断
  rdn: "0", // 数字自动判断
};
```

# 🎪 事件系统

## `audioFirstStart`

音频首次开始播放时触发

```javascript
ttsInstance.on("audioFirstStart", () => {
  console.log("音频开始播放");
});
```

## `appFinish`

应用销毁时触发

```javascript
ttsInstance.on("appFinish", () => {
  console.log("TTS应用已销毁");
});
```

# 💡 使用示例

## 基础用法

```javascript
import xunfeiTts from 'xunfei-tts'

// 配置系统参数
xunfeiTts.config({
  APPID: 'your_appid',
  API_SECRET: 'your_api_secret',
  API_KEY: 'your_api_key'
})

const playBtn = document.createElement('button')
playBtn.textContent = '播放'

document.body.appendChild(playBtn)

playBtn.addEventListener('click', () => {
  // 创建实例
  const ttsInstance = xunfeiTts.create()

  // 监听事件
  ttsInstance
    .on('audioFirstStart', () => {
      console.log('开始播放音频')
    })
    .on('appFinish', () => {
      console.log('TTS服务已结束')
    })

  // 启动并发送文本
  ttsInstance.start()
  ttsInstance.send('你好，世界！')
  ttsInstance.end()
})
```

## 高级用法 - 流式文本输入

```javascript
import xunfeiTts from 'xunfei-tts'

// 配置系统参数
xunfeiTts.config({
  APPID: 'your_appid',
  API_SECRET: 'your_api_secret',
  API_KEY: 'your_api_key'
})

// 创建播放按钮
const streamPlayBtn = document.createElement('button')
streamPlayBtn.textContent = '开始流式播放'

document.body.appendChild(streamPlayBtn)

streamPlayBtn.addEventListener('click', () => {
  const ttsInstance = xunfeiTts.create({
    vcn: "aisjiuxu", // 使用不同的音色
    speed: 60, // 稍快的语速
    volume: 80, // 较大的音量
  })

  // 监听事件
  ttsInstance
    .on('audioFirstStart', () => {
      console.log('流式播放开始')
      streamPlayBtn.textContent = '播放中...'
      streamPlayBtn.disabled = true
    })
    .on('appFinish', () => {
      console.log('流式播放结束')
      streamPlayBtn.textContent = '开始流式播放'
      streamPlayBtn.disabled = false
    })

  ttsInstance.start()

  const textArray = [
    "欢迎使用讯飞语音合成服务。",
    "这是一个功能强大的文本转语音解决方案。",
    "支持多种音色和丰富的参数配置。",
    "感谢您的使用！",
  ]

  let index = 0
  const timer = setInterval(() => {
    if (index < textArray.length) {
      ttsInstance.send(textArray[index])
      index++
    } else {
      ttsInstance.end()
      clearInterval(timer)
    }
  }, 1000)
})
```

## 音量控制示例

```javascript
import xunfeiTts from 'xunfei-tts'

// 配置系统参数
xunfeiTts.config({
  APPID: 'your_appid',
  API_SECRET: 'your_api_secret',
  API_KEY: 'your_api_key'
})

let ttsInstance = null

// 创建播放按钮
const playBtn = document.createElement('button')
playBtn.textContent = '播放音频'

// 创建控制按钮
const muteBtn = document.createElement('button')
const unmuteBtn = document.createElement('button')
const stopBtn = document.createElement('button')

muteBtn.textContent = '静音'
unmuteBtn.textContent = '取消静音'
stopBtn.textContent = '停止'

// 初始状态下禁用控制按钮
muteBtn.disabled = true
unmuteBtn.disabled = true
stopBtn.disabled = true

// 添加按钮到页面
document.body.append(playBtn, muteBtn, unmuteBtn, stopBtn)

// 播放按钮事件
playBtn.addEventListener('click', () => {
  ttsInstance = xunfeiTts.create()

  // 监听事件
  ttsInstance
    .on('audioFirstStart', () => {
      console.log('音频开始播放')
      playBtn.textContent = '播放中...'
      playBtn.disabled = true
      muteBtn.disabled = false
      unmuteBtn.disabled = false
      stopBtn.disabled = false
    })
    .on('appFinish', () => {
      console.log('音频播放结束')
      playBtn.textContent = '播放音频'
      playBtn.disabled = false
      muteBtn.disabled = true
      unmuteBtn.disabled = true
      stopBtn.disabled = true
    })

  // 开始播放
  ttsInstance.start()
  ttsInstance.send('这是一段测试音频，您可以控制播放状态。您可以尝试静音、取消静音或停止播放功能。')
  ttsInstance.end()
})

// 控制按钮事件
muteBtn.addEventListener('click', () => {
  if (ttsInstance) {
    ttsInstance.mute()
    console.log('已静音')
  }
})

unmuteBtn.addEventListener('click', () => {
  if (ttsInstance) {
    ttsInstance.unmute()
    console.log('已取消静音')
  }
})

stopBtn.addEventListener('click', () => {
  if (ttsInstance) {
    ttsInstance.finish()
    console.log('已停止播放')
  }
})
```

# 🏗️ 架构设计

本库采用串行处理器架构，包含以下核心组件：

1. **TextSplit** - 文本分割处理器
2. **TtsRequest** - TTS 请求处理器
3. **ResponseTranscode** - 响应转码处理器
4. **DecodeData** - 数据解码处理器
5. **AudioActuator** - 音频播放器

各处理器按顺序串联，形成完整的文本转语音处理流水线。

# 🔧 开发

```bash
# 安装依赖
pnpm install

# 构建项目
pnpm run build
```

# 📄 许可证

ISC License

# 🤝 贡献

欢迎提交 Issue 和 Pull Request！

s# 📞 支持

如有问题，请查看[讯飞 TTS 官方文档](https://www.xfyun.cn/doc/tts/online_tts/API.html)或提交 Issue。