# @mt-utils/xunfei-tts 讯飞TTS 文本转语音库，用于将文本转换为语音输出。 ## 特点 - 提供灵活的参数配置，包括语速、音量、音高等。 - 支持使用默认参数或部分覆盖以简化配置流程。 - 支持WebSocket通信，实现实时的文本到语音转换。 - 支持Web Worker，进行音频数据的转换处理，不阻塞主线程。 ## 安装 ```bash pnpm install @mt-utils/xunfei-tts ``` ## 使用方法 ### 引入库 ```javascript import xunfeiTts from '@mt-utils/xunfei-tts' ``` ### 配置系统参数 配置必要的系统参数，这些参数通常在讯飞开放平台申请 ```javascript /** * 平台系统配置 */ const systemConfig = { // 在平台申请的密钥信息 API_SECRET: 'your_api_secret', // 在平台申请的APPID信息 APPID: 'your_appid', // 在平台申请的API_KEY信息 API_KEY: 'your_api_key' } // 配置系统参数 xunfeiTts.config(systemConfig) ``` ### 创建实例 您可以选择使用默认的 `ttsOptions`，或者提供部分参数来覆盖默认设置。 ```javascript /** * 业务参数 */ const ttsOptions = { // 音频编码方式 // 'raw'：未压缩的PCM音频格式 // 'lame'：MP3格式音频，需要配合sfl参数使用 // 'speex-org-wb;7'：标准开源speex宽频16k，数字代表压缩等级（1~10，默认8） // 'speex-org-nb;7'：标准开源speex窄频8k，数字代表压缩等级（1~10，默认8） // 'speex;7'：讯飞定制speex窄频8k，数字代表压缩等级（1~10，默认7） // 'speex-wb;7'：讯飞定制speex宽频16k，数字代表压缩等级（1~10，默认7） aue: 'raw', // 是否开启流式返回，需要配合aue=lame使用 // 1：开启流式返回 sfl: 1, // 音频采样率 // 'audio/L16;rate=8000'：合成8KHz的音频 // 'audio/L16;rate=16000'：合成16KHz的音频 // 若不传值，默认合成16KHz的音频 auf: 'audio/L16;rate=16000', // 语速，取值范围[0-100]，默认为50 speed: 50, // 发音人选择，需要到控制台添加试用或购买发音人后使用 vcn: 'xiaoyan', // 例如：'xiaoyan', 'xiaokun' // 音量，取值范围[0-100]，默认为50 volume: 50, // 音高，取值范围[0-100]，默认为50 pitch: 55, // 合成音频的背景音 // 0：无背景音（默认值） // 1：有背景音 bgs: 0, // 文本编码格式 // 'GB2312', 'GBK', 'BIG5', 'UNICODE', 'GB18030', 'UTF8'（小语种） tte: 'UTF8', // 设置英文发音方式 // 0：自动判断处理，如果不确定将按照英文词语拼写处理（缺省） // 1：所有英文按字母发音 // 2：自动判断处理，如果不确定将按照字母朗读 reg: '2', // 合成音频数字发音方式 // 0：自动判断（默认值） // 1：完全数值 // 2：完全字符串 // 3：字符串优先 rdn: '0' } // 创建mtTts实例 const ttsInstance = xunfeiTts.create(ttsOptions) ``` ### 可用方法 ### 发送文本并播放 > `ttsInstance.send(text: string, options?: Partial): void` `send` 方法现在接受两个参数：待转换的文本 `text` 和一个可选的 `options` 对象。`options` 对象的属性会与默认的 `SendOptions` 合并。 #### 参数说明 - `text (string)`: _字符串_ - 待转换的文本。 - `options (TextSplitOrigina['options'])`: _对象_ - 发送文本时的配置选项，包括： - `isAppend`: _布尔值_ - 是否主动将末尾未加入到此次段落分割中，默认值为 false。 ![]() #### 例子 ```typescript /** * isAppend：false的情况 * 在进行分割段落时，会分割为：["你好，"]，剩余的文本内容“欢迎使用讯”会交给下次的send方法 */ mtTts.send('你好，欢迎使用讯', { isAppend: false }) /** * 首先拼接上次未完全分段的部分“欢迎使用讯”，然后再分割为本内容为["欢迎使用讯飞TTS服务！"] */ mtTts.send('飞TTS服务！') // -----------------两种情况---------------- /** * isAppend：true的情况 * 在进行分割段落时，会分割为：["你好，","剩余的文本内容"] */ mtTts.send('你好，欢迎使用讯', { isAppend: true }) /** * 分割为本内容为["讯飞TTS服务！"]`` */ mtTts.send('飞TTS服务！') ``` ### 终止应用执行 > `ttsInstance.finish()` 终止TTS转换、语音播放 #### 例子 ```javascript mtTts.finish() ``` ## 应用钩子 应用钩子事件允许您在特定时刻执行自定义逻辑。 | 钩子名称 | 触发时机 | 描述 | | :-------------- | :----------------------------------------------------------------- | :--------------------------------------------------------------- | | appCreate | 应用和所有的处理器被创建初始化时触发。 | 可以在这个时候进行一些初始化操作，比如设置初始状态或者日志记录。 | | appStart | 第一个处理器进入运行状态时触发，即有一条源数据进入了第一个处理器。 | 表示应用开始处理数据，可以在这里记录开始时间或者进行一些预处理。 | | appFinish | 应用被停止时触发。 | 可以在这个时候进行清理操作，比如释放资源或者保存最终状态。 | | audioFirstStart | 音频首次播放时触发。 | 可以在这里执行一些在音频播放开始前的准备工作，比如显示播放提示。 | #### `appCreate` 应用和所有的处理器被创建初始化时触发。 ```javascript ttsInstance.on('appCreate', () => { console.log('应用和处理器已创建初始化') }) ``` #### `appStart` 第一个处理器进入运行状态，也就是有一条源数据进入了第一个处理器时触发。 ```javascript ttsInstance.on('appStart', () => { console.log('第一个处理器进入运行状态') }) ``` #### `appFinish` 应用被停止时触发。 ```javascript ttsInstance.on('appFinish', () => { console.log('应用已停止') }) ``` #### `audioFirstStart` 音频首次播放时触发。 ```javascript ttsInstance.on('audioFirstStart', () => { console.log('音频首次播放') }) ``` ## 配置选项 ### SystemConfig 配置选项 | 配置项 | 类型 | 描述 | 必填 | 默认值 | | :--------- | :----- | :---------------------- | :--- | :----- | | API_SECRET | string | 在平台申请的API密钥 | 是 | 无 | | APPID | string | 在平台申请的应用ID | 是 | 无 | | API_KEY | string | 在平台申请的API_KEY信息 | 是 | 无 | ### BusinessParams 配置选项 | 参数名 | 类型 | 必传 | 描述 | 示例值 | | :----- | :----- | :--- | :----------------------------------------------------------- | :--------------------- | | aue | string | 是 | 音频编码，可选值：
- raw：未压缩的pcm
- lame：mp3 (当aue=lame时需传参sfl=1)
- speex-org-wb;7：标准开源speex（for speex_wideband，即16k）数字代表指定压缩等级（默认等级为8）
- speex-org-nb;7：标准开源speex（for speex_narrowband，即8k）数字代表指定压缩等级（默认等级为8）
- speex;7：压缩格式，压缩等级1~10，默认为7（8k讯飞定制speex）
- speex-wb;7：压缩格式，压缩等级1~10，默认为7（16k讯飞定制speex） | "raw" | | sfl | int | 否 | 需要配合aue=lame使用，开启流式返回mp3格式音频
取值：1 开启 | 1 | | auf | string | 否 | 音频采样率，可选值：
- audio/L16;rate=8000：合成8K 的音频
- audio/L16;rate=16000：合成16K 的音频
auf不传值：合成16K 的音频 | "audio/L16;rate=16000" | | vcn | string | 是 | 发音人，可选值：请到控制台添加试用或购买发音人，添加后即显示发音人参数值 | "xiaoyan" | | speed | int | 否 | 语速，可选值：[0-100]，默认为50 | 50 | | volume | int | 否 | 音量，可选值：[0-100]，默认为50 | 50 | | pitch | int | 否 | 音高，可选值：[0-100]，默认为50 | 50 | | bgs | int | 否 | 合成音频的背景音
0:无背景音（默认值）
1:有背景音 | 0 | | tte | string | 否 | 文本编码格式
- GB2312
- GBK
- BIG5
- UNICODE(小语种必须使用UNICODE编码，合成的文本需使用utf16小端的编码方式，详见java示例demo)
- GB18030
- UTF8（小语种） | "GBK" | | reg | string | 否 | 设置英文发音方式：
0：自动判断处理，如果不确定将按照英文词语拼写处理（缺省）
1：所有英文按字母发音
2：自动判断处理，如果不确定将按照字母朗读 | "2" | | rdn | string | 否 | 合成音频数字发音方式
0：自动判断（默认值）
1：完全数值
2：完全字符串
3：字符串优先 | "0" | ### SendOptions 配置项 | 配置项 | 类型 | 描述 | 必填 | 默认值 | | :------- | :------ | :----------------------------------------------------------------------------------------------- | :--- | :----- | | isAppend | boolean | 是否将文本追加到文本分割器中，在进行文本分割的时，分割到最后的时候，是否将文本追加到文本分割器中 | 否 | false | ## 讯飞文档 [讯飞文档]('https://www.xfyun.cn/doc/tts/online_tts/API.html#%E6%8E%A5%E5%8F%A3%E8%B0%83%E7%94%A8%E6%B5%81%E7%A8%8B') ## 注意 明途内部工具库，并不负责改BUG，请勿随便下载