更新记录

1.0.0（2026-05-18） 下载此版本

• 初始发布 muqian-tts
• 基于 UTS 封装系统 TTS，支持 Android、iOS、Web
• 提供 speak、stop、pause、resume、isSpeaking 能力
• 支持语速、音调、音量、语言参数与统一错误回调

平台兼容性

uni-app(5.08)

muqian-tts 文档

模块说明

muqian-tts 是一个跨平台 TTS 能力封装，当前实现覆盖：

该插件由 AI 开发，遇到问题建议优先问一下 AI。

• Android：基于系统 TextToSpeech
• iOS：基于系统 AVSpeechSynthesizer
• Web：基于浏览器 speechSynthesis

适合用于：

• 文本朗读
• 无障碍语音播报
• 学习类、工具类内容发声
• 轻量提示语音输出

模块位置

• uni_modules/muqian-tts

平台支持

最低平台要求：

• Android：minSdkVersion = 21
• iOS：deploymentTarget = 12.0

对外能力

模块导出以下方法：

• speak(options)：开始播报
• stop()：停止播报
• pause()：暂停播报
• resume()：继续播报
• isSpeaking()：是否正在播报

speak 参数说明

speak(options) 的参数结构如下：

成功回调返回：

{ errMsg: 'speak:ok' }

失败回调返回：

{
  errSubject: 'muqian-tts',
  errCode: 9010001,
  errMsg: 'speak:fail TTS engine not available'
}

错误码

说明：当前源码中虽然预留了 9010003、9010004，但现有 UTS 层实际主要返回的是 9010001 和 9010002。

使用示例

示例按 uni-app 中直接使用 uni_modules 插件的方式编写：

import { speak, stop, pause, resume, isSpeaking } from '@/uni_modules/muqian-tts'

export function playDemo() {
  speak({
    text: '你好，欢迎使用木千语音播报。',
    lang: 'zh-CN',
    rate: 1,
    pitch: 1,
    volume: 1,
    success(res) {
      console.log('播报完成', res)
    },
    fail(err) {
      console.error('播报失败', err)
    }
  })
}

export function stopDemo() {
  if (isSpeaking()) {
    stop()
  }
}

export function pauseDemo() {
  pause()
}

export function resumeDemo() {
  resume()
}

平台差异与注意事项

1. Android 首次调用时会先初始化 TextToSpeech，初始化完成后再执行待播报文本。
2. Android 的 pause() 实际调用的是 stop()，系统 TTS 本身不提供真正的暂停/续播能力，因此 resume() 基本无实际效果。
3. iOS 的默认 rate 为 0.5，并且内部会转换到 AVSpeechUtterance 的速率区间，和 Android/Web 的听感不完全一致。
4. Web 依赖浏览器原生 speechSynthesis，不同浏览器的音色、语言包和触发时机可能不同。
5. 如果调用 speak() 时传入空文本，会直接走失败回调，不会触发播报。
6. 当再次调用 speak() 时，当前实现会中断上一段播报并直接开始新的内容。

接入建议

• 对朗读类页面，建议在新内容播放前先调用一次 stop()，避免并发播报状态混乱。
• 如果业务要求严格的暂停/继续体验，Android 端不要依赖当前 pause()/resume() 语义。
• 如果有多语言需求，优先在业务侧显式传 lang，例如 zh-CN、en-US。

源码参考

• uni_modules/muqian-tts/package.json
• uni_modules/muqian-tts/utssdk/interface.uts
• uni_modules/muqian-tts/utssdk/unierror.uts
• uni_modules/muqian-tts/utssdk/app-android/index.uts
• uni_modules/muqian-tts/utssdk/app-android/MuqianTts.kt
• uni_modules/muqian-tts/utssdk/app-ios/index.uts
• uni_modules/muqian-tts/utssdk/app-ios/MuqianTts.swift
• uni_modules/muqian-tts/utssdk/web/index.uts