更新记录

1.2.10（2026-06-15）

• 修复 Android Sherpa-ONNX 离线播报首响等待偏长的问题：离线播报改为后台分段合成播放，长文本会按标点和长度拆成短句逐段生成，首句合成完成后即可开始播放。
• Android 离线合成新增多线程优化：Sherpa-ONNX numThreads 会按设备 CPU 核心数自动设置，高端设备最高使用 6 线程；同时使用合成线程 + 播放线程流水线提前生成下一段音频，减少段落之间的等待。
• Android 离线首响继续优化：首段最大长度缩短为约 12 字、普通分段缩短为约 24 字，并在离线初始化后执行 warmupText 短文本预热，降低首次正式播报冷启动成本。
• 修复 Android 离线播报返回 completed 但听不到声音的问题：AudioTrack 改为小缓冲分块写入 PCM，并等待 playbackHeadPosition 消费完已写入帧后再释放播放器。
• Android 离线播报新增合成与播放诊断日志，输出分段编号、合成耗时、采样率、样本数、音频时长、峰值、RMS、缓冲区、写入帧数和播放头进度，便于定位慢首响、静音音频、写入失败或设备输出路由问题。
• 优化插件离线示例页 example/offline.vue：新增语速快捷档、说话人/音色编号、离线音色查询、音量参数、预热文本、目标采样率和短句/订单/导航/长文本快捷测试内容。
• README 新增当前发布包内置 Sherpa-ONNX Android AAR 的注意事项；不需要离线 TTS、只使用系统 TTS 或云端 TTS 时，可按文档删除 AAR 减小包体。
• README 新增 Sherpa-ONNX 模型 zip 云静态下载地址，并说明下载到 App 私有目录、解压后通过 offline.modelPath 加载模型。
• 本版本修改 Android 原生离线桥接和示例页；使用 Sherpa 离线能力时，需要重新运行 Android 原生联编或重新打 Android 自定义基座。标准基座不包含 AAR / SO，不能用于验证离线 TTS 原生能力。

1.2.9（2026-06-15）

• 修复 Android Sherpa-ONNX 离线引擎初始化在中文 VITS 模型下可能长时间无响应的问题，初始化配置按 vits-melo-tts-zh_en 资源实际情况处理，并保留 offline init start/runtime/create/success 分阶段日志。
• 修复 Android 离线播报返回 completed 但听不到声音的问题：AudioTrack 改为小缓冲分块写入 PCM，并等待 playbackHeadPosition 消费完已写入帧后再释放播放器。
• Android 离线播报新增合成与播放诊断日志，输出合成耗时、采样率、样本数、音频时长、峰值、RMS、缓冲区、写入帧数和播放头进度，便于定位静音音频、写入失败或设备输出路由问题。
• 优化插件离线示例页 example/offline.vue：初始化前自动填入 App 私有目录 modelPath，新增顶部初始化按钮、初始化 loading、状态卡片和更清晰的日志反馈。
• 本版本修改 Android 原生离线桥接和示例页；使用 Sherpa 离线专业包时，需要重新运行 Android 原生联编或重新打 Android 自定义基座。仅更新 wgt / appResource 不能把 AAR / SO 热更新进原生基座。

1.2.8（2026-06-12）

• README 按客户接入路径重新整理为“系统 TTS -> 离线 TTS -> 云端 TTS”，删除产品定位、小说听书完整方案等前置营销说明，让客户先完成最小接入，再按需扩展。
• 新增 Android Sherpa-ONNX 离线 TTS 专业包接入说明，明确 AAR、模型下载脚本、-SkipModel -Arm64Only 轻量打包路径和发布前资源清理流程。
• Android 离线 TTS 支持 offline.modelPath 加载 App 私有目录中的运行时模型，方便业务在自定义基座打包后自行下载并解压模型，规避默认包体超过 60MB 的发布成本。
• 新增 pages/ttsOffline/ttsOffline 离线测试页，并在首页入口跳转到离线 TTS 测试示例，便于验证 Sherpa-ONNX 初始化、播报、暂停、继续、停止和能力查询。
• 新增插件内示例 uni_modules/lizhao-smart-tts/example/offline.vue，并注册到 pages_init.json，客户安装插件后可直接查看离线 TTS 示例代码。
• 离线测试页新增“当前状态”、控制台日志和回调超时保护，修复点击“初始化离线引擎”后首屏没有日志、没有明显响应的问题。
• 新增发布清理与检查脚本，发布插件前可删除本地 Sherpa AAR、模型、下载缓存和资源清单，再用 check-smart-tts-release-clean.js 确认轻量包内不含大资源。
• 本版本包含 Android Sherpa 原生桥接源码和离线测试页；如果要在真机使用 Sherpa 离线引擎，需要将 AAR 放入 utssdk/app-android/libs 后重新运行原生联编或重新打 Android 自定义基座。仅更新页面或 README 不需要重新打基座。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-smart-tts 智能语音播报 TTS 插件

lizhao-smart-tts 是面向 uni-app / uni-app x 的 TTS 语音播报插件。推荐按由浅入深的方式接入：先使用系统 TTS；需要完全离线时接入离线 TTS 资源包；需要固定音色、高音质或统一多端效果时再接入云端 TTS。

当前版本：1.2.10

接入方式选择

安装与导入

把插件放到项目 uni_modules/lizhao-smart-tts 后，只从插件根目录导入：

import {
  initTTS,
  speak,
  pause,
  resume,
  stop,
  getVoices,
  getCapabilities
} from '@/uni_modules/lizhao-smart-tts'

不要直接 import utssdk/index.uts 或平台目录文件。

平台支持

系统 TTS 接入

系统 TTS 是最轻的接入方式，不需要额外模型、服务器或原生依赖。Android 使用系统 TextToSpeech，iOS 使用 AVSpeechSynthesizer，Web 使用浏览器 SpeechSynthesis。

最小示例

import { initTTS, speak } from '@/uni_modules/lizhao-smart-tts'

// 初始化系统 TTS。App Android / iOS 会优先使用 native 系统引擎。
initTTS({
  lang: 'zh-CN',
  fallbackChain: ['native'],
  success(res) {
    console.log('系统 TTS 初始化成功', res.capabilities.adapter)
  },
  fail(err) {
    console.log('系统 TTS 初始化失败', err.errCode, err.errMsg)
  }
})

// 提交一段普通播报。
speak({
  text: '订单已完成，请及时处理',
  rate: 1.0,
  pitch: 1.0,
  volume: 1.0,
  success(res) {
    console.log('系统 TTS 播报完成', res)
  },
  fail(err) {
    console.log('系统 TTS 播报失败', err.errCode, err.errMsg)
  }
})

查询系统音色

import { getVoices, speak } from '@/uni_modules/lizhao-smart-tts'

getVoices({
  success(voices) {
    console.log('可用音色', voices)

    // Android / iOS 会尝试按 voiceName 选择音色，不支持时回退系统默认音色。
    speak({
      text: '这是一段指定音色的系统 TTS 测试',
      voiceName: voices.length > 0 ? voices[0].name : '',
      rate: 1.0
    })
  }
})

控制播报

import { pause, resume, stop } from '@/uni_modules/lizhao-smart-tts'

pause({})
resume({})
stop({ clearQueue: true })

Android 系统 TTS 没有真正的 pause API，插件会用 restart-segment 降级语义处理：暂停后继续会从当前分段开头恢复。

系统 TTS 常见现象

离线 TTS 接入

离线 TTS 用于无网播报。当前发布包内置了 Sherpa-ONNX Android AAR，方便需要离线 TTS 的客户重新打 Android 自定义基座后直接接入离线引擎；模型文件仍建议按项目情况随基座打包或运行后下载。

注意：如果项目不需要离线 TTS，只使用手机系统 TTS 或云端 TTS，可以删除 uni_modules/lizhao-smart-tts/utssdk/app-android/libs/sherpa-onnx-1.13.2.aar 后再发布或打包，这样可以明显减小插件目录和 Android 自定义基座体积。删除 AAR 后不要使用 fallbackChain:['offline-ai']；系统 TTS 仍可正常使用 fallbackChain:['native']。

Android 离线能力分成两类资源：

如果关注 60M 打包限制，推荐使用“arm64 运行库进基座 + 模型运行后下载”的方式：打基座前只放入 arm64-v8a AAR，不放模型；安装基座后下载模型，传入 modelPath 初始化。

默认包行为

未放入离线资源时，显式使用 offline-ai 会返回：

9011006 offline model missing

这不是故障，只表示默认轻量包没有携带离线模型和推理库。

方案一：模型随基座打包

Windows / PowerShell 下在项目根目录执行：

powershell -ExecutionPolicy Bypass -File scripts/download-smart-tts-sherpa-android.ps1

脚本会下载并安装以下资源：

然后使用 modelDir 初始化：

import { initTTS, speak } from '@/uni_modules/lizhao-smart-tts'

// 模型已经随 Android 自定义基座进入 assets 时，使用 modelDir。
initTTS({
  lang: 'zh-CN',
  fallbackChain: ['offline-ai', 'native', 'cloud'],
  offline: {
    engine: 'sherpa-onnx',
    modelDir: 'sherpa-onnx/zh-pro',
    speakerId: 0
  }
})

speak({
  text: '这是一段离线 TTS 语音播报'
})

这种方式最简单，但模型约 180MB，会显著增加自定义基座包体，不适合 60M 限制场景。

方案二：模型运行后下载

# 只准备 arm64-v8a 原生运行库，不把模型放进自定义基座
powershell -ExecutionPolicy Bypass -File scripts/download-smart-tts-sherpa-android.ps1 -SkipModel -Arm64Only

脚本会下载上游 sherpa-onnx-1.13.2.aar，重新打包为只含 arm64-v8a 的 AAR，并安装到：

uni_modules/lizhao-smart-tts/utssdk/app-android/libs/sherpa-onnx-1.13.2-arm64-v8a.aar

完成后重新打 Android 自定义基座。App 运行后，由业务代码下载并解压模型到 App 私有目录，目录内至少需要包含：

推荐把模型 zip 下载到 App 私有目录后解压，例如：

https://env-00jxu7ha8amh.normal.cloudstatic.cn/tts/sherpa-onnx.zip

注意：上面的地址是云静态托管示例地址。如果客户访问失败，或需要使用自己的模型分发链路，可以替换为自己的长期有效 CDN / 云存储下载地址。

建议解压到 App 私有目录，例如：

_doc/lizhao-smart-tts/sherpa-onnx/zh-pro

在 App Android 中可使用 plus.io.convertLocalFileSystemURL('_doc/lizhao-smart-tts/sherpa-onnx/zh-pro') 转成 Android 绝对路径，然后传给 offline.modelPath。

model.onnx
tokens.txt
lexicon.txt
espeak-ng-data/
dict/
phone.fst / date.fst / number.fst（模型包内存在时保留）

然后把解压后的 Android 绝对路径传给 offline.modelPath：

import { initTTS, speak } from '@/uni_modules/lizhao-smart-tts'

// 示例路径请替换为你的下载/解压工具返回的真实 Android 绝对路径。
const modelPath = '/data/user/0/你的包名/files/sherpa-onnx/zh-pro'

// modelPath 是运行时模型加载入口；填写后优先于 modelDir。
initTTS({
  lang: 'zh-CN',
  fallbackChain: ['offline-ai', 'native', 'cloud'],
  offline: {
    engine: 'sherpa-onnx',
    modelPath,
    speakerId: 0
  },
  success(res) {
    console.log('离线模型加载成功', res.capabilities.details)
  },
  fail(err) {
    console.log('离线模型加载失败', err.errCode, err.errMsg, err.details)
  }
})

speak({
  text: '模型不进基座，也可以运行后加载并离线播报'
})

这种方式是当前推荐方案：原生运行库仍需要进基座，但模型不进基座，可以明显降低云打包体积。客户也可以把上面的 zip 下载地址替换成自己的云存储地址，只要最终解压目录内包含 model.onnx / tokens.txt / lexicon.txt 等必要文件即可。

下载脚本参数

# 重新下载并覆盖已有资源
powershell -ExecutionPolicy Bypass -File scripts/download-smart-tts-sherpa-android.ps1 -Force

# 只下载 Android AAR，不下载模型
powershell -ExecutionPolicy Bypass -File scripts/download-smart-tts-sherpa-android.ps1 -SkipModel

# 只保留 arm64-v8a AAR，适合控制 Android 自定义基座体积
powershell -ExecutionPolicy Bypass -File scripts/download-smart-tts-sherpa-android.ps1 -SkipModel -Arm64Only

脚本完成后会生成资源记录：

uni_modules/lizhao-smart-tts/utssdk/app-android/SHERPA_ANDROID_RESOURCE_MANIFEST.md

手动放置资源

如果用户不使用脚本，也可以手动下载并放到以下位置：

uni_modules/lizhao-smart-tts/
└─ utssdk/
   └─ app-android/
      ├─ libs/
      │  └─ sherpa-onnx-1.13.2.aar
      └─ assets/
         └─ sherpa-onnx/
            └─ zh-pro/
               ├─ model.onnx
               ├─ tokens.txt
               ├─ lexicon.txt
               └─ ...

如果模型随基座打包，模型目录必须与代码中的 modelDir: 'sherpa-onnx/zh-pro' 保持一致。如果模型运行后下载，不需要放到 assets，只要把解压后的绝对目录传给 modelPath。

重新打 Android 自定义基座

只更新 wgt / appResource 不能把 AAR / SO 热更新进原生基座。放入或替换 Sherpa-ONNX Android AAR 后，必须重新运行 Android 原生联编或重新打 Android 自定义基座。

如果只替换运行后下载的模型文件，并且 AAR / SO 已经在当前自定义基座里，不需要重新打基座，重新下载模型后再次调用 initTTS({ offline: { modelPath } }) 即可。

项目测试页和插件内示例页已经注册：

pages/ttsOffline/ttsOffline
uni_modules/lizhao-smart-tts/example/offline

测试步骤：

1. 执行下载脚本或手动放置 AAR。
2. 重新打 Android 自定义基座。
3. 如果模型没有进 assets，先把模型下载并解压到 App 私有目录。
4. 打开 pages/ttsOffline/ttsOffline，或打开插件示例 uni_modules/lizhao-smart-tts/example/offline。
5. 使用 modelDir 或填写 modelPath，点击“初始化离线引擎”，再点击“离线播报”。
6. 点击“能力查询”，确认 supportMatrix.offlineAi=true，details.modelReady=true。

业务代码接入

import { initTTS, speak, getCapabilities } from '@/uni_modules/lizhao-smart-tts'

// 二选一：assets 模型使用 modelDir；运行时下载模型使用 modelPath。
const offlineModel = {
  engine: 'sherpa-onnx',
  modelPath: '/data/user/0/你的包名/files/sherpa-onnx/zh-pro',
  speakerId: 0
}

initTTS({
  lang: 'zh-CN',
  fallbackChain: ['offline-ai', 'native', 'cloud'],
  offline: offlineModel,
  success(res) {
    console.log('离线 TTS 初始化成功', res.capabilities.adapter)
  },
  fail(err) {
    console.log('离线 TTS 初始化失败', err.errCode, err.errMsg)
  }
})

speak({
  text: '这是一段离线 TTS 语音播报',
  fallbackChain: ['offline-ai', 'native', 'cloud'],
  offline: offlineModel
})

getCapabilities({
  success(res) {
    console.log('离线能力', res.supportMatrix.offlineAi, res.details)
  }
})

离线包注意事项

• Sherpa-ONNX AAR / SO 不能运行后下载补进自定义基座；能运行后下载的是模型文件。
• modelPath 必须是解压后的模型目录，不是 .tar.bz2 压缩包路径。
• 9011006 通常表示模型目录缺少 model.onnx / tokens.txt / lexicon.txt；9011007 可能表示 AAR / SO 未进入当前自定义基座，或 Sherpa 初始化失败。
• Android 不要一次性塞入所有 ABI，优先只保留业务需要的 arm64-v8a。
• Sherpa-ONNX 代码授权与模型授权不是一回事，上线前必须分别确认。
• iOS 离线资源需要单独准备 .xcframework 和模型目录，本 README 当前只提供 Android 资源脚本。

云端 TTS 接入

云端 TTS 适合固定音色、高音质、多端一致、小程序和 Harmony 音频链路。插件向云端服务提交文本，服务返回可播放的 audioUrl，App 端用音频播放器播放。

云端接口约定

默认约定云端接口返回：

{
  "audioUrl": "https://example.com/audio/demo.wav",
  "cacheHit": false,
  "durationMs": 1200,
  "provider": "edge-tts",
  "voice": "zh-CN-XiaoxiaoNeural"
}

如果你的服务返回字段不是 audioUrl，可以通过 cloud.responseField 指定。

最小示例

import { initTTS, speak } from '@/uni_modules/lizhao-smart-tts'

initTTS({
  lang: 'zh-CN',
  fallbackChain: ['cloud', 'native'],
  cloudOnly: true,
  cloud: {
    provider: 'custom',
    endpoint: 'https://你的域名/v1/tts',
    method: 'POST',
    responseField: 'audioUrl',
    cache: {
      enabled: true,
      namespace: 'tts-demo',
      maxAgeMs: 86400000,
      maxItems: 100
    }
  }
})

speak({
  text: '这是一段云端 TTS 测试',
  voiceName: 'zh-CN-XiaoxiaoNeural',
  cacheKey: 'demo:cloud:001',
  cloudOnly: true
})

cloudOnly: true 用于 App 端云端测试，避免系统 TTS 初始化失败影响云端播放。

Edge TTS uniCloud 免费测试代理

插件内置 Edge TTS uniCloud 免费测试代理模板，目录：

uni_modules/lizhao-smart-tts/uniCloud/cloudfunctions/edge-tts

插件内的 uniCloud 目录不带服务商后缀，HBuilderX 会按项目实际绑定的云空间处理。它不是 CosyVoice 私有化模型服务，而是通过 WebSocket 请求 Edge 在线 TTS，生成音频后上传到 uniCloud 云存储，再返回 audioUrl。该方案适合测试和演示，不建议作为长期商业生产核心链路。

默认测试地址：

https://env-00jxu7ha8amh.dev-hz.cloudbasefunction.cn/tts

部署步骤：

1. 在 HBuilderX 中为项目绑定 uniCloud 云空间。
2. 在项目根 uniCloud 视图中找到 edge-tts 云函数。
3. 右键上传并部署云函数。
4. 在 uniCloud 控制台开启云函数 URL 化，复制 URL 作为 cloud.endpoint。
5. 如果插件物理目录没有上传菜单，可把 uni_modules/lizhao-smart-tts/uniCloud/cloudfunctions/edge-tts 手动复制到项目根 uniCloud/cloudfunctions/edge-tts 后部署。

URL 化位置示意：

Edge TTS 测试页路径：

pages/tts/tts.vue

该页面提供“切换云端测试”“切换系统 TTS”“打开系统 TTS 设置”“播放云端测试”“系统 TTS 一键自检”等按钮。云端测试会使用 uni.request 请求云函数，并用 uni.createInnerAudioContext 播放返回的 audioUrl。

手机系统 TTS 测试路线：点击“切换系统 TTS”，探测成功后点击“使用系统 API：普通播报”或“系统 TTS 一键自检”。

如果 Edge TTS 云函数日志出现 Unexpected server response: 403，通常是在线接口握手参数变更或云函数模板未更新。请更新模板后重新上传部署。

CosyVoice Docker 真实模型服务完整部署

如果需要私有化高音质云端 TTS，可以使用插件附带的 CosyVoice Docker 服务模板：

uni_modules/lizhao-smart-tts/static/server/cosyvoice-cloud-tts

默认模型：

iic/CosyVoice-300M-SFT

默认音色：

中文女 / 中文男 / 英文女 / 英文男

快速启动：

cd uni_modules/lizhao-smart-tts/static/server/cosyvoice-cloud-tts
copy .env.example .env
powershell -ExecutionPolicy Bypass -File .\build-image.ps1
docker compose up -d

常用接口：

生产环境建议配置 HTTPS 反向代理，让手机、小程序和 App 都能访问返回的 audioUrl。Nginx 示例位于：

uni_modules/lizhao-smart-tts/static/server/cosyvoice-cloud-tts/nginx.example.conf

云端服务启动后可运行：

D:\HBuilderX\plugins\node\node.exe scripts\check-smart-tts-cloud-e2e.js --endpoint http://127.0.0.1:8000/v1/tts
D:\HBuilderX\plugins\node\node.exe --test tests\smart-tts-cloud-e2e.test.js

第三方商业 TTS 代理

如果不想自建模型服务，可以把商业 TTS 厂商接口放到服务端代理里。密钥只放服务端，不要写入 App、插件或 README 示例。

模板目录：

uni_modules/lizhao-smart-tts/static/server/commercial-tts-proxy

业务侧仍然只接统一的 cloud.endpoint：

initTTS({
  fallbackChain: ['cloud', 'native'],
  cloud: {
    provider: 'custom',
    endpoint: 'https://你的服务/v1/tts',
    method: 'POST',
    responseField: 'audioUrl'
  }
})

场景字段

云端链路会透传以下业务字段，服务端可用它们做缓存、角色音色和业务路由：

scene/cacheKey/voiceRole/emotion/metadata

示例：

speak({
  text: '欢迎回来',
  scene: 'order',
  cacheKey: 'order:welcome:v1',
  voiceRole: 'narrator',
  emotion: 'warm',
  metadata: {
    source: 'home'
  },
  cloudOnly: true
})

API 说明

API 列表

initTTS(options)

说明 初始化 TTS 运行时。

参数

speak(options)

说明 提交一段文本播报。

参数

SmartTtsOfflineOptions

SmartTtsCloudOptions

返回值字段

能力字段

错误码

验证建议

发布默认轻量包前：

D:\HBuilderX\plugins\node\node.exe scripts\check-smart-tts-release-clean.js
D:\HBuilderX\plugins\node\node.exe scripts\check-smart-tts-cloud-lite.js

验证 Edge TTS uniCloud 模板：

D:\HBuilderX\plugins\node\node.exe scripts\check-smart-tts-edge-unicloud.js

验证 Android Sherpa-ONNX 离线测试包：

D:\HBuilderX\plugins\node\node.exe scripts\check-smart-tts-sherpa-offline-demo.js

验证真实云端服务模板：

D:\HBuilderX\plugins\node\node.exe scripts\check-smart-tts-cloud-e2e.js

阶段完成前建议再做 HBuilderX LSP / appResource 编译校验。不要把真实密钥、Token、生产域名私密配置写进插件仓库。

联系方式

信-微：l-z-1-8-7-1512-5421（-去掉，不这样写会被和谐）