更新记录

1.0.0（2026-10-26）

• 支持 Android、iOS、鸿蒙、Web、小程序及元服务文字转语音。
• 支持音色选择、语速、音调、音量调节与停止朗读。

平台兼容性

uni-app(4.86)

uni-app x(4.86)

其他

umi-tts

基本使用

import { speak, stop, destroy, isSpeaking } from '@/uni_modules/umi-tts'
import { TtsError } from '@/uni_modules/umi-tts/utssdk/interface.uts'

speak({
  text: '你好，欢迎使用文字合成语音。',
  language: 'zh-CN',
  voiceId: '', // 默认音色；其他音色请填写 getVoices 返回的 id
  rate: 1,
  pitch: 1,
  volume: 1,
  onStart: () => { console.log('开始朗读') },
  success: (result) => { console.log(result.errMsg) },
  fail: (error: TtsError) => { console.log(error.errCode, error.errMsg) },
  complete: () => { console.log('任务结束') }
})

// isSpeaking() 包含初始化、网络合成、加载音频和实际播报阶段。
// stop() 取消当前任务，触发 fail(903003) 与 complete。
// destroy() 停止并释放资源，同时清空服务端配置。

调用 speak 后，通过回调了解朗读进度，函数本身不返回结果。整段文字朗读完毕才会调用 success，准备语音或下载音频完成时不会调用。

一次只能朗读一段文字。如果上一段还在准备或朗读，再次调用会返回错误码 903002，上一段会继续朗读。想换一段文字时，先调用 stop()，再调用 speak()。每次调用结束时，会先调用 success 或 fail，再调用 complete。

目前不支持暂停后继续、自动排队、保证后台持续朗读或导出音频文件。同一个应用中的多个页面共用一个朗读任务。示例会在页面隐藏时调用 stop()，离开并卸载页面时调用 destroy()。

音色与音调

音色是选择谁来朗读，音调是调整这个声音的高低，两项可以单独设置。例如，先选择某位发音人，再用 pitch 调低声音。调高、调低音调不会切换发音人。

使用 getVoices 获取当前平台提供的音色，再把选中音色的 id 传给 speak：

import { getVoices, speak } from '@/uni_modules/umi-tts'
import { TtsVoice } from '@/uni_modules/umi-tts/utssdk/interface.uts'

let selectedVoiceId = ''
getVoices({
  language: 'zh-CN',
  success: (voices: Array<TtsVoice>) => {
    console.log('可选音色', voices)
    // 实际页面可以展示列表，让用户选择。此处示意选择第一项。
    selectedVoiceId = voices.length > 0 ? voices[0].id : ''
  },
  fail: (error) => { console.log(error.errMsg) }
})

// 绑定到朗读按钮，由用户点击调用，避免浏览器限制自动发声。
function speakWithVoice() {
  speak({ text: '你好，这是选中的发音人。', language: 'zh-CN', voiceId: selectedVoiceId, pitch: 1 })
}

音色名称和数量取决于设备、语音引擎或服务端，不保证一定有男声、女声，也不会根据名字猜测性别。列表为空时仍可使用“默认音色”；刷新列表不会停止当前朗读。切换音色影响下一次朗读，不改变正在播放的声音。

Android 的 zh-CN 音色列表可能包含标记为 zh 或 zh-Hans 的音色，不包含明确不匹配的地区或简繁体音色，例如 zh-Hant。音色名称相同但 ID 不同时，仍可能是不同音色。

音色 ID 不能跨平台通用，切换语言或语音引擎后应重新查询。App 与 Web 指定的音色失效或语言不匹配时会报错，请刷新列表后重新选择。小程序和元服务会把所选 voiceId 发给服务端，由服务端检查并使用对应发音人。

小程序与元服务服务端协议

import { configureTtsService, speak } from '@/uni_modules/umi-tts'

configureTtsService({
  url: 'https://你的业务域名/api/tts',
  token: '业务短期访问凭证', // 可选，非云厂商 SecretKey
  voices: [ // 可选，请填写业务服务实际支持的 ID 和名称
    { id: 'speaker-a', name: '发音人 A', language: 'zh-CN' },
    { id: 'speaker-b', name: '发音人 B', language: 'zh-CN' }
  ]
})
speak({ text: '这段文字将发送至业务服务端', voiceId: 'speaker-a', rate: 1, pitch: 1 })

configureTtsService 只用于小程序和元服务，在 App 与 Web 调用没有效果。voices 用于展示音色列表，应填写服务端实际支持的音色。未配置时 getVoices 返回空数组，仍可用默认音色朗读。修改配置只影响后续任务。调用 destroy 后接口、凭证与音色列表都会清空，需重新配置。

请求为 HTTPS POST，30 秒超时：

Content-Type: application/json
Authorization: Bearer 业务短期访问凭证

{"text":"你好","language":"zh-CN","voiceId":"speaker-a","rate":1,"pitch":1}

未配置 token 时 Authorization 为空。接口必须返回 HTTP 200 与 JSON：

{"audioUrl":"https://你的音频域名/临时签名地址.mp3"}

接口需支持传入的语言、音色、语速和音调，不支持时应返回错误。voiceId 为空字符串表示默认音色。返回的 HTTPS 音频地址必须可直接播放，播放请求不携带上述 Authorization。请勿在小程序或元服务中配置云厂商密钥。使用前需自行准备可用的语音合成接口；取消任务不保证撤销服务端合成计费。

微信配置 request 合法域名，以及音频下载/播放域名；其他小程序按宿主要求配置。元服务需在独立工程配置网络访问、AppID、包名和签名。开发阶段关闭域名校验不能替代发布配置。

原生及 Web 注意事项

• Android 无需录音权限。初始化最多等待 15 秒；缺少语音引擎或语言包时会失败。是否需要联网取决于设备使用的语音引擎。
• iOS 的声音路由、静音策略及与其他音频的协调需由应用按业务配置。
• HarmonyOS 需要可用的离线语言资源和音色，初始化最多等待 15 秒。
• Web 必须在用户交互中调用，不支持语音合成的浏览器会返回失败。不保证离线可用；停止朗读可能影响页面内其他语音库的播报，请避免同时使用。
• 操作系统/浏览器中断、后台挂起可能影响回调与播放。本插件不申请后台运行能力。

错误码