@mingto/huoshan-tts

火山引擎在线语音合成（TTS）工具库，专为浏览器端设计，内置流式文本处理与 SSML 转换，支持 iOS/Android 等多平台。

特性

• 🎙️ 流式处理：支持实时文本分段与合成，支持长文本流式输入
• 🌍 跨平台兼容：自动适配 iOS/Android 等多平台音频编码
• 🔧 灵活配置：丰富的业务参数配置，支持多音色、语速、音量等调节
• 📝 SSML 支持：内置 SSML 语音标记语言转换，支持发音规则配置
• 🎯 事件驱动：基于事件总线架构，提供丰富的生命周期钩子
• 📦 TypeScript 支持：完整的类型定义与类型推导
• ⚡ 链式调用：流畅的链式 API 设计
• 🔊 音频控制：支持暂停/恢复、静音/取消静音等操作

安装

# npm
npm install @mingto/huoshan-tts

# yarn
yarn add @mingto/huoshan-tts

# pnpm (推荐)
pnpm add @mingto/huoshan-tts

快速开始

import huoshanTTS from '@mingto/huoshan-tts'

// 1. 配置系统参数（只需配置一次）
huoshanTTS.config({
  ttsRequestBaseUrl: 'wss://audio.workbrain.cn/tts',
})

// 2. 创建 TTS 控制器实例
const tts = huoshanTTS.create({
  // 业务参数（可选）
  voice_type: 'zh_female_daimengchuanmei_moon_bigtts',
  speed_ratio: 1.0,
  volume_ratio: 1.0,
  pitch_ratio: 1.0,
}, {
  // SSML 配置（可选）
  pronunciationRules: [
    // { content: '重庆', alphabet: 'py', ph: 'chong2 qing4' }
  ],
})

// 3. 监听事件
tts
  .on('audioFirstStart', () => {
    console.log('音频首次开始播放')
  })
  .on('appError', (error) => {
    console.error('应用出错:', error)
  })
  .on('appFinish', () => {
    console.log('应用结束')
  })

// 4. 开始并发送文本
tts.start()
tts.send('欢迎使用火山引擎语音合成服务！')
tts.send('这是一段测试文本。')

// 5. 结束输入（继续播放剩余音频）
tts.end()

// 6. 销毁实例（停止所有音频）
// tts.finish()

API 文档

配置系统参数

huoshanTTS.config(systemConfig)

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

huoshanTTS.config({
  ttsRequestBaseUrl: 'wss://audio.workbrain.cn/tts',
})

参数说明：

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | ttsRequestBaseUrl | string | ✅ | wss://audio.workbrain.cn/tts | TTS 服务 WebSocket 地址 |

创建实例

huoshanTTS.create(businessParams?, ssmlConfig?)

创建 TTS 控制器实例。

const tts = huoshanTTS.create({
  voice_type: 'zh_female_daimengchuanmei_moon_bigtts',
  text_type: 'plain',
  speed_ratio: 1.0,
  volume_ratio: 1.0,
  pitch_ratio: 1.0,
  language: 'cn',
  provider: '0',
  cache: false,
  stream: true,
})

业务参数 businessParams:

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | voice_type | string | ❌ | zh_female_daimengchuanmei_moon_bigtts | 音色类型 | | text_type | 'plain' \| 'ssml' | ❌ | 'plain' | 文本类型 | | speed_ratio | number | ❌ | 1.0 | 语速，范围 [0.2, 3.0] | | volume_ratio | number | ❌ | 1.0 | 音量，范围 [0.1, 3.0] | | pitch_ratio | number | ❌ | 1.0 | 音高，范围 [0.1, 3.0] | | stream | boolean | ❌ | true | 是否流式返回 | | language | string | ❌ | 'cn' | 语言代码 | | provider | string | ❌ | '0' | 供应商 ID，'100' 表示巴山大模型 | | cache | boolean | ❌ | false | 是否使用缓存 | | encoding | string | ❌ | - | 音频编码，iOS 环境默认为 pcm，非 iOS 默认为 mp3 | | output_format | string | ❌ | - | 输出格式，巴山大模型默认为 url |

💡 注意：当 provider 为 '100'（巴山大模型）时，不支持 SSML 格式，会自动强制使用 plain 文本类型。

SSML 配置 ssmlConfig:

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | pronunciationRules | PronunciationRule[] | ❌ | [] | 发音规则列表 |

发音规则示例：

{
  pronunciationRules: [
    { content: '重庆', alphabet: 'py', ph: 'chong2 qing4' },
    { content: '厦门', alphabet: 'py', ph: 'xia4 men2' },
  ]
}

实例方法

tts.start()

激活应用，使处理器进入工作状态，准备接收文本。

tts.start()

tts.send(text)

传入文本数据进行语音合成，可多次调用实现流式输入。

tts.send('第一段文本')
tts.send('第二段文本')
tts.send('第三段文本')

tts.end()

通知应用停止接收新文本，但不会停止音频播放，剩余文本会继续处理直到播放完成。

tts.end()

tts.finish()

停止所有处理器，重置应用状态，触发 appFinish 事件，同时停止所有音频播放。

tts.finish()

tts.on(eventName, callback)

监听事件，支持链式调用。

tts
  .on('audioFirstStart', () => {
    console.log('音频首次开始播放')
  })
  .on('appError', (error) => {
    console.error('出错:', error)
  })

tts.mute()

静音当前音频。

tts.mute()

tts.unmute()

取消静音，恢复音频播放。

tts.unmute()

tts.pause()

暂停音频播放。

tts.pause()

tts.resume()

恢复音频播放。

tts.resume()

事件说明

| 事件名 | 触发时机 | 回调参数 | 说明 | |--------|----------|----------|------| | audioFirstStart | 音频首次开始播放时 | - | 标志音频开始工作 | | appError | 应用发生错误时 | Error | 携带错误信息 | | appFinish | 应用结束时（调用 finish() 或处理完成） | - | 所有处理器已停止 |

使用示例

基础流式文本输入

import huoshanTTS from '@mingto/huoshan-tts'

huoshanTTS.config()

const tts = huoshanTTS.create({
  speed_ratio: 1.2,
  volume_ratio: 1.0,
})

tts
  .on('audioFirstStart', () => console.log('开始播放'))
  .on('appFinish', () => console.log('播放完成'))

tts.start()

// 模拟流式接收文本
const texts = ['今天天气真好，', '我想去公园散步，', '看看花，', '听听鸟叫。']
let index = 0

const timer = setInterval(() => {
  if (index < texts.length) {
    tts.send(texts[index])
    index++
  }
  else {
    tts.end()
    clearInterval(timer)
  }
}, 500)

SSML 发音规则配置

import huoshanTTS from '@mingto/huoshan-tts'

huoshanTTS.config()

const tts = huoshanTTS.create(
  {
    text_type: 'ssml',
    voice_type: 'zh_female_daimengchuanmei_moon_bigtts',
  },
  {
    pronunciationRules: [
      { content: '重庆', alphabet: 'py', ph: 'chong2 qing4' },
      { content: '厦门', alphabet: 'py', ph: 'xia4 men2' },
      { content: '六安', alphabet: 'py', ph: 'lu4 an1' },
    ],
  }
)

tts.on('audioFirstStart', () => console.log('开始播放'))

tts.start()
tts.send('我要去重庆和厦门出差。')
tts.end()

使用巴山大模型

import huoshanTTS from '@mingto/huoshan-tts'

huoshanTTS.config()

const tts = huoshanTTS.create({
  provider: '100', // 巴山大模型
  voice_type: 'your_voice_type',
})

tts.start()
tts.send('这是巴山大模型合成的语音')
tts.end()

💡 注意：巴山大模型不支持 SSML 格式，text_type 会自动切换为 plain

在 React 中使用

import { useEffect, useRef } from 'react'
import huoshanTTS from '@mingto/huoshan-tts'

const TTSComponent = () => {
  const ttsRef = useRef(null)

  useEffect(() => {
    // 初始化
    huoshanTTS.config()

    ttsRef.current = huoshanTTS.create({
      speed_ratio: 1.0,
    })

    ttsRef.current
      .on('audioFirstStart', () => {
        console.log('开始播放')
      })
      .on('appError', (error) => {
        console.error('TTS 错误:', error)
      })

    // 组件卸载时销毁
    return () => {
      ttsRef.current?.finish()
    }
  }, [])

  const handleSpeak = (text) => {
    ttsRef.current?.start()
    ttsRef.current?.send(text)
    ttsRef.current?.end()
  }

  const handleStop = () => {
    ttsRef.current?.finish()
  }

  return (
    <div>
      <button onClick={() => handleSpeak('你好，世界！')}>播放</button>
      <button onClick={handleStop}>停止</button>
    </div>
  )
}

export default TTSComponent

音频控制示例

import huoshanTTS from '@mingto/huoshan-tts'

huoshanTTS.config()

const tts = huoshanTTS.create()

tts.start()
tts.send('这是一段较长的测试音频，用于演示音频控制功能。')

// 暂停播放
setTimeout(() => {
  tts.pause()
  console.log('已暂停')
}, 2000)

// 恢复播放
setTimeout(() => {
  tts.resume()
  console.log('已恢复')
}, 4000)

// 静音
setTimeout(() => {
  tts.mute()
  console.log('已静音')
}, 6000)

// 取消静音
setTimeout(() => {
  tts.unmute()
  console.log('取消静音')
}, 8000)

// 结束
setTimeout(() => {
  tts.end()
}, 10000)

内部处理流程

工具库采用链式处理器架构，自动适配不同平台：

iOS 处理流程

TextSplit → CreateSsml（可选） → TTSRequestIos → DecodeDataIos → AudioActuator

非 iOS 处理流程

TextSplit → CreateSsml（可选） → TTSRequestNotIos → ByteBufferNotIos → DecodeDataNotIos → AudioActuator

巴山大模型（iOS）处理流程

TextSplit → CreateSsml（自动跳过） → TTSRequestBaShanIos → DecodeDataBaShanIos → AudioActuator

推荐音色列表

中文常用

| 音色代码 | 说明 | 性别 | |----------|------|------| | zh_female_daimengchuanmei_moon_bigtts | 呆萌川妹 | 女声 |

注意：更多音色可参考火山引擎官方文档

平台兼容性

| 平台 | 编码格式 | 兼容性 | |------|----------|--------| | iOS | PCM | ✅ 完全支持 | | Android | MP3 | ✅ 完全支持 | | Chrome | MP3 | ✅ 完全支持 | | Safari | MP3 / PCM | ✅ 完全支持 | | 微信小程序 | MP3 | ✅ 使用 @mingto/huoshan-tts-mp |

注意事项

1. ⚠️ 配置顺序：必须先调用 config() 再调用 create()，否则会使用默认配置
2. ⚠️ 状态管理：只有在 EXECUTE 状态下调用 send() 才会处理文本
3. ⚠️ end() vs finish()：
   • end()：停止接收新文本，但继续播放剩余音频
   • finish()：立即停止所有处理器，停止音频播放
4. ⚠️ 内存管理：页面卸载或组件销毁时，务必调用 finish() 释放资源
5. ⚠️ SSML 限制：巴山大模型（provider: '100'）不支持 SSML 格式
6. ⚠️ WebSocket：确保网络环境支持 WebSocket 连接

许可证

MIT