介绍

浏览器端中文 TTS 控制器，内置流式文本切分与 SSML 转换，支持 iOS/非 iOS 与多供应商接入。

详细配置可参考参数基本说明。

• ✅ 一行初始化与创建控制器
• ✅ 流式处理与事件订阅
• ✅ SSML 发音规则（ 最长匹配）
• ✅ iOS/非 iOS 自动适配

安装

# pnpm
pnpm add @minto-ai/huoshan-tts

快速开始

import huoshanTts from '@minto-ai/huoshan-tts'

// 配置系统
huoshanTts.config({ ttsRequestBaseUrl: 'wss://audio.workbrain.cn/tts' })

// 创建控制器实例
const tts = huoshanTts.create(
  {
    voice_type: 'zh_female_daimengchuanmei_moon_bigtts',
    text_type: 'plain',
    stream: true,
    provider: '0',
  },
  {
    pronunciationRules: [
      // { content: '重庆', alphabet: 'py', ph: 'chong2 qing4' },
    ],
  },
)

// 订阅事件
tts.on('audioFirstStart', () => {
  console.log('首段音频开始播放')
})

// 启动与推送文本
tts.start()
tts.send('你好，欢迎使用中文 TTS。')
tts.send('这是一段第二句。')
tts.end()

// 结束
tts.finish()

API

配置系统

用于设置系统级参数，如 TTS 请求地址。

config(systemConfig)

config(_systemConfig: Partial): this

参数

1. _systemConfig (Partial<SystemConfig)): 系统配置，如 ttsRequestBaseUrl: string

返回值

• (this): 支持链式调用

实例方法

核心实例方法，控制 TTS 生命周期与文本推送。

create(businessParams?, ssmlConfig?)

创建并返回控制器实例，根据设备与供应商自动选择请求与解码管线；用于生命周期管理与文本推送。

create(_businessParams?: Partial, _ssmlConfig?: Partial): TtsController

参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 | | ------------------------------- | ---------------------------------------- | --------------------- | ---------- | ------------------------------- | -------------------- | ---------- | ------ | --- | ----- | -------- | | businessParams.text_type | 'plain' | 'ssml' | 否 | plain | 文本类型 | | businessParams.voice_type | string | 否 | — | 音色类型 | | businessParams.speed_ratio | number | 否 | 1 | 语速，约 [0.2, 3] | | businessParams.volume_ratio | number | 否 | 1 | 音量，约 [0.1, 3] | | businessParams.pitch_ratio | number | 否 | 1 | 音高，约 [0.1, 3] | | businessParams.stream | boolean | 否 | true | 是否流式返回 | | businessParams.language | string | 否 | cn | 语言代码 | | businessParams.provider | string | 否 | 0 | 供应商 Id | | businessParams.cache | boolean | 否 | false | 是否启用缓存 | | businessParams.encoding | 'wav' | 'pcm ' | 'ogg_opus' | 'mp3' | 'pcm' | 'ogg_opus' | 'mp3'| 否 |mp3| 输出编码 | |businessParams.output_format |string | 否 | — | iOS +provider=100时为url| |ssmlConfig.pronunciationRules|Array<{ content: string; alphabet: 'py' | 'ipa'; ph: string }>| 否 |[]` | 发音规则（最长匹配） |

返回值

• (TtsController): 控制器实例

TtsController#start()

进入待机状态，激活处理管线并准备接收文本进行合成。

start(): TtsController

返回值

• (TtsController): 支持链式调用

TtsController#send(text)

推送文本或片段，内部进行分段与 SSML 转换后发起合成；支持流式连续调用。

send(text: string): TtsController

参数

1. text (string): 待转换文本或片段

返回值

• (TtsController): 支持链式调用

TtsController#end()

停止接收文本输入但不打断当前音频播放；用于输入结束的收尾阶段。

end(): TtsController

返回值

• (TtsController): 支持链式调用

TtsController#finish()

停止所有处理器并重置控制器状态，触发 appFinish 事件；用于彻底结束并清理。

finish(): void

返回值

• (void)

TtsController#on(eventName, callback)

订阅控制器公共事件，获取播放开始、错误、结束等通知，支持链式调用。

on(eventName: PublicCustomEventName, callback: (data?: any) => void): TtsController

参数

1. eventName (PublicCustomEventName): 事件名称
2. callback ((data?: any) => void): 回调函数

返回值

• (TtsController): 支持链式调用

TtsController#mute()

静音当前音频输出。

mute(): void

返回值

• (void)

TtsController#unmute()

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

unmute(): void

返回值

• (void)

应用事件

| 事件名 | 触发时机 | 事件说明 | | ----------------- | ---------------------------- | ------------ | | audioFirstStart | 首段音频开始播放前 | 首次播放提示 | | appError | 应用发生错误时 | 携带错误信息 | | appFinish | 调用 finish() 或流程结束时 | 应用结束事件 |

audioFirstStart

触发时机：首段音频片段即将播放前。

作用：用于提示开始播放或进行 UI 预处理。

tts.on('audioFirstStart', () => {
  console.log('首段音频开始播放')
})

appFinish

触发时机：调用 finish() 或处理链自然结束。

作用：用于清理资源或提示应用结束。

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

进阶示例

流式文本处理

import huoshanTts from '@minto-ai/huoshan-tts'

huoshanTts.config()

const ttsInstance = huoshanTts.create({

})

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

const zzButton = document.createElement('button')
zzButton.textContent = '终止'
const jxButton = document.createElement('button')
jxButton.textContent = '继续'

let timer = null
zzButton.onclick = () => {
  ttsInstance.finish()
  clearTimeout(timer)
}

jxButton.onclick = () => {
  clearTimeout(timer)

  const arrText = [
    `你要抱`,
    `抱我吗？`,
    `我好`,
    `喜欢你呀！`,
  ]

  let index = 0

  timer = setInterval(() => {
    ttsInstance.send(arrText[index])
    index += 1
    if (index === arrText.length) {
      ttsInstance.end()
      clearInterval(timer)
    }
  }, 100)
}

document.body.appendChild(jxButton)
document.body.appendChild(zzButton)

多事件组合监听

import huoshanTts from '@minto-ai/huoshan-tts'

const tts = huoshanTts.config({
  ttsRequestBaseUrl: 'wss://audio.workbrain.cn/tts'
}).create({

})
tts
  .on('audioFirstStart', () => console.log('首段开始'))
  .on('appFinish', () => console.log('结束'))
tts.start().send('你好，世界。').end()
setTimeout(
  () => tts.finish(),
  1000
)

SSML 发音规则

import huoshanTts from '@minto-ai/huoshan-tts'

const rules = [{ content: '重庆', alphabet: 'py', ph: 'chong2 qing4' }]
const tts = huoshanTts.config({
  ttsRequestBaseUrl: 'wss://audio.workbrain.cn/tts'
}).create({}, {
  pronunciationRules: rules
})
tts.start().send('我去重庆。').end()