@mingto/xunfei-tts

讯飞文本转语音（TTS）服务工具库，基于讯飞开放平台 WebAPI 实现流式语音合成。

特性

• 🎙️ 流式处理：支持流式文本合成与播放
• 🌍 多语言支持：支持中文、英文及多种方言
• 🔧 灵活配置：支持自定义音频编码、语速、音量、音高、背景音等
• 📱 浏览器端支持：专为浏览器环境优化
• 🔇 静音控制：支持静音/取消静音操作
• 🎵 丰富音色：支持多种讯飞官方音色

安装

pnpm add @mingto/xunfei-tts

快速开始

import xunfeiTTS from '@mingto/xunfei-tts'

// 配置全局参数
xunfeiTTS.config({
  API_SECRET: 'your-api-secret',
  APPID: 'your-app-id',
  API_KEY: 'your-api-key',
})

// 创建应用实例（必需参数：aue、vcn）
const ttsInstance = xunfeiTTS.create({
  aue: 'lame',
  vcn: 'xiaoyan',
  speed: 50,
  volume: 50,
  pitch: 50,
})

// 订阅事件
ttsInstance.on('audioFirstStart', () => {
  console.log('音频首次播放')
})

ttsInstance.on('appFinish', () => {
  console.log('应用已结束')
})

// 开始转换
ttsInstance.start()

// 发送文本
ttsInstance.send('你好，欢迎使用讯飞语音合成。')

// 结束转换
ttsInstance.end()

// 销毁应用
// ttsInstance.finish()

// 调整音量
// ttsInstance.mute()     // 静音
// ttsInstance.unmute()   // 恢复音量

API

全局配置

xunfeiTTS.config(systemConfig)

配置系统参数，全局只需配置一次。

xunfeiTTS.config({
  API_SECRET: 'your-api-secret',
  APPID: 'your-app-id',
  API_KEY: 'your-api-key',
})

参数说明：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | API_SECRET | string | ✅ | 在讯飞开放平台申请的 API Secret | | APPID | string | ✅ | 在讯飞开放平台申请的 APPID | | API_KEY | string | ✅ | 在讯飞开放平台申请的 API Key |

创建应用实例

xunfeiTTS.create(businessParams)

创建 TTS 应用实例。

const ttsInstance = xunfeiTTS.create({
  aue: 'lame',
  vcn: 'xiaoyan',
})

业务参数 businessParams：

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | aue | string | ✅ | - | 音频编码格式 | | vcn | string | ✅ | - | 发音人名称 | | auf | string | ❌ | audio/L16;rate=16000 | 音频采样率 | | speed | number | ❌ | 50 | 语速，范围 0-100 | | volume | number | ❌ | 50 | 音量，范围 0-100 | | pitch | number | ❌ | 50 | 音高，范围 0-100 | | bgs | number | ❌ | 0 | 背景音，0-无，1-有 | | tte | string | ❌ | - | 文本编码，unicode/UTF8 | | reg | string | ❌ | 0 | 英文发音方式 | | rdn | string | ❌ | 0 | 数字发音方式 | | sfl | number | ❌ | - | 配合 aue=lame 使用，开启流式返回 |

音频编码 aue 可选值：

| 值 | 说明 | |----|------| | raw | 未压缩的 PCM | | lame | MP3 格式（配合 sfl=1 实现流式返回） | | speex-org-wb;7 | 标准开源 speex（16k） | | speex-org-nb;7 | 标准开源 speex（8k） | | speex;7 | 讯飞定制 speex（8k） | | speex-wb;7 | 讯飞定制 speex（16k） |

实例方法

ttsInstance.start()

激活应用，准备接收文本进行语音播放。

ttsInstance.start()

ttsInstance.send(text)

发送文本进行语音合成。

ttsInstance.send('你好，世界。')

ttsInstance.end()

通知应用发送文本已经结束，但是不会销毁应用，剩余的文本将会继续播放。

ttsInstance.end()

ttsInstance.finish()

应用播放结束，应用将会被销毁，剩余的文本将会停止播放。

ttsInstance.finish()

ttsInstance.mute()

静音当前音频输出。

ttsInstance.mute()

ttsInstance.unmute()

取消静音，恢复音频输出。

ttsInstance.unmute()

ttsInstance.on(eventName, callback)

订阅应用事件，获取播放开始、结束等通知。

ttsInstance.on('audioFirstStart', () => {
  console.log('音频首次播放')
})

应用事件

| 事件名 | 触发时机 | 说明 | |--------|----------|------| | audioFirstStart | 音频首次播放时触发 | 首次播放提示 | | appFinish | 调用 finish() 或流程结束时触发 | 应用结束事件 |

流式文本处理示例

import xunfeiTTS from '@mingto/xunfei-tts'

xunfeiTTS.config({
  API_SECRET: 'your-api-secret',
  APPID: 'your-app-id',
  API_KEY: 'your-api-key',
})

const ttsInstance = xunfeiTTS.create({
  aue: 'lame',
  vcn: 'xiaoyan',
  speed: 50,
  volume: 50,
})

ttsInstance
  .on('appFinish', () => console.log('appFinish'))
  .on('audioFirstStart', () => console.log('audioFirstStart'))

const textStream = [
  '今天天气真好，',
  '我想去公园散步，',
  '看看花，',
  '听听鸟叫，',
  '享受这美好的一天。',
]

let index = 0
ttsInstance.start()

const interval = setInterval(() => {
  if (index < textStream.length) {
    ttsInstance.send(textStream[index])
    index++
  } else {
    ttsInstance.end()
    clearInterval(interval)
  }
}, 500)

讯飞控制台参数获取

1. 登录 讯飞开放平台
2. 创建语音合成应用
3. 在控制台获取 APPID、API_KEY、API_SECRET
4. 在「语音合成」→「发音人」中添加并获取 vcn（发音人参数值）

发音人说明

发音人需要在讯飞控制台添加试用或购买后才会显示参数值。

中文常用发音人

| vcn 值 | 说明 | 性别 | |--------|------|------| | xiaoyan | 小燕 | 女声 | | xiaofeng | 小枫 | 男声 | | aisjiuxu | 许久 | 女声 | | aisxping | 思蓓 | 女声 |

英文常用发音人

| vcn 值 | 说明 | |--------|------| | catherine | Catherine | 英文女声 | | john | John | 英文男声 |

注意事项

• ⚠️ 需要在讯飞开放平台申请账号并获取 APPID、API_KEY、API_SECRET
• ⚠️ aue 和 vcn 是必需参数，必须在 create() 时传入
• ⚠️ 建议将 API 配置放在服务端，前端通过接口获取，避免密钥泄露
• ⚠️ 长文本建议分段发送，提高合成效率
• ⚠️ 在页面离开或组件卸载时，记得调用 finish() 方法销毁实例
• ⚠️ 使用流式返回需设置 aue: 'lame' 并添加 sfl: 1

参考文档

• 讯飞语音合成 WebAPI 文档
• 讯飞控制台

许可证

MIT