更新记录

1.0.0（2026-09-13） 下载此版本

初版

平台兼容性

uni-app(3.8.3)

sl-uniplugin-tts 离线语音播报插件

简介

基于 sherpa-onnx + MeloTTS 的离线中文语音合成（TTS） UTS 插件，无需依赖系统 TTS 引擎或网络服务。

目录结构

sl-uniplugin-tts/
├── package.json
└── utssdk/app-android/
    ├── index.uts              # TTS 实现
    ├── config.json           # 依赖与构建配置
    ├── AndroidManifest.xml   # 权限声明
    ├── libs/
    │   └── sherpa-onnx-1.12.39.aar   # sherpa-onnx 引擎 (56MB)
    └── assets/tts/           # MeloTTS 模型
        ├── model.onnx        # VITS 模型 (~162MB)
        ├── tokens.txt        # 音素表
        ├── lexicon.txt       # 词典
        ├── phone.fst         # 文本规整（电话号）
        ├── date.fst          # 日期规整
        ├── number.fst        # 数字规整
        ├── new_heteronym.fst # 多音字
        └── dict/             # 结巴分词词典

权限

<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

依赖配置

config.json

{
    "minSdkVersion": 21,
    "dependencies": [
        { "id": "org.jetbrains.kotlin:kotlin-stdlib", "version": "1.8.22" }
    ],
    "libs": ["sherpa-onnx-1.12.39.aar"],
    "abiFilters": ["arm64-v8a", "armeabi-v7a"],
    "noCompress": ["onnx", "fst", "txt"]
}

build.gradle（Android 工程侧）

android {
    defaultConfig {
        ndk { abiFilters 'arm64-v8a', 'armeabi-v7a' }
    }
    aaptOptions { noCompress 'onnx', 'fst', 'txt' }
}

dependencies {
    // sherpa-onnx 离线 TTS 引擎
    implementation fileTree(dir: "libs", include: ['*.aar', '*.jar'])
}

proguard-rules.pro / consumer-rules.pro

-keep class com.k2fsa.sherpa.onnx.** { *; }
-keepclasseswithmembernames class * { native <methods>; }

API

initTTS(options, callback)

初始化离线 TTS 引擎，从 assets 加载 ONNX 模型。在子线程执行，不阻塞 UI。

回调返回值：

{ "code": 0, "success": true, "msg": "TTS ready" }

示例：

import { initTTS } from '@/uni_modules/sl-uniplugin-tts'

initTTS({}, (res) => {
  if (res.code === 0) {
    console.log('TTS 就绪')
  } else {
    console.error('初始化失败：', res.msg)
  }
})

首次初始化需加载 ~162MB 模型，约需数秒。

speak(options, callback)

将中文文本转为语音并播放。

回调返回值：

// 播报完成
{ "code": 0, "success": true, "msg": "Done" }

// 被停止
{ "code": 0, "success": false, "msg": "Stopped" }

// 失败
{ "code": 1, "success": false, "msg": "Speak error: ..." }

示例：

import { speak } from '@/uni_modules/sl-uniplugin-tts'

speak({ text: '你好，欢迎使用离线语音播报', speed: 1.0 }, (res) => {
  if (res.code === 0) {
    console.log('播报完成')
  } else {
    console.error('播报失败：', res.msg)
  }
})

stopSpeak(options, callback)

停止当前播报。

示例：

import { stopSpeak } from '@/uni_modules/sl-uniplugin-tts'

stopSpeak({}, (res) => {
  console.log('已停止播报')
})

destroy(options, callback)

释放 TTS 引擎和 AudioTrack 资源。释放后需重新 initTTS() 才能使用。

示例：

import { destroy } from '@/uni_modules/sl-uniplugin-tts'

destroy({}, (res) => {
  console.log('资源已释放')
})

技术细节

• sherpa-onnx API 调用：Kotlin 数据类用属性赋值（vitsConfig.model = ...），不用 setter 方法（vitsConfig.setModel(...)）
• 类型转换：UTS 的 number 类型需显式转换（.toInt() / .toFloat() / .toShort()），UTS 不支持 1.0f 字面量后缀
• 数组下标：UTS 的 for 循环变量是 Number 类型，用作 Kotlin 数组下标时需 .toInt() 转换
• AudioTrack.MODE_STATIC：一次性写入全部 PCM 数据后再播放，避免流式缓冲导致开头吞音
• 3ms 淡入淡出：消除 AudioTrack 启动/停止时的爆破音
• 子线程生成：OfflineTts.generateWithConfig() 在后台线程执行，不阻塞 UI
• 模型不压缩：config.json 配置 noCompress: ["onnx", "fst", "txt"]，sherpa-onnx 可直接从 assets mmap 读取
• Runnable 语法：UTS 中用 new class implements Runnable { override run(): void {} }，不支持 new Runnable({ run: () => {} }) 和 Kotlin 的 object : Runnable {} 语法
• FloatArray/ShortArray：UTS 中用 Kotlin 原生数组类型，不用 TS 的 Float32Array/Int16Array；数组长度用 .size 属性，不用 .length

注意事项

1. minSdkVersion 21（Android 5.0+）
2. 调用 speak() 会自动停止上一次未完成的播报
3. 首次 initTTS() 会加载 System.loadLibrary("sherpa-onnx-jni")
4. APK 体积约 +200MB（含 TTS 模型）
5. 不要重复初始化：initTTS() 成功后需先 destroy() 才能再次初始化
6. UTS callback 一次性限制：在 uni-app Vue3（非 uni-app x）项目 + App-Android 真机环境下，UTS callback 只能被 JS 端接收一次。本插件的 speak() callback 只在播报完成/失败/停止时触发一次，无多次回调需求