更新记录

1.0.0（2026-09-14）

首次发布独立 Android 语音 UTS 插件。
支持离线文字朗读、停止播放及资源释放。
支持本机语音引擎和已安装离线音色选择。
支持语速、音高、单次朗读音量和系统媒体音量设置。
支持通信扬声器状态查询、切换及系统语音设置。
提供 uni-app Vue2 示例工程。

平台兼容性

uni-app(5.25)

Vue2	Vue2插件版本	Vue3	Chrome	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
√	1.0.0	-	-	-	-	-	-	-	-

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
-	-	-	-	-	-	-	-	-	-	-	-

uni-app x(5.26)

Chrome	Safari	Android	iOS	鸿蒙	微信小程序
-	-	-	-	-	-

葫芦离线语音 UTS

Android 手机已有离线语音引擎的文字朗读插件，支持停止、引擎与音色选择、语速、音高、单次朗读音量、系统媒体音量及通信扬声器切换。独立版本1.0.0，构建标识 2026-09-14-uts-speech。

这是 UTS接口 + Java AAR 的混编UTS插件：package.json 中 dcloudext.type=uts，页面import命名导出，入口为 utssdk/app-android/index.uts。无需旧nativeplugins注册、requireNativePlugin、UniModule或SDK桩。完整通信插件不是依赖。

安装

将整个 hulu-yuyin 文件夹放入应用 uni_modules。Android5.0+、HBuilderX4.27+；4.27要求来自持续回调注解 @UTSJS.keepAlive。本次提供的Demo是普通uni-app Vue2，非uni-app x；不实现iOS、Web或小程序。

本地Java库在 utssdk/app-android/libs/hulu-yuyin-core.aar，config.json声明fastjson1.2.83。制作并安装包含插件的Android自定义基座或正式APK；修改Java/AAR/原生配置必须重新打基座，页面热更新不会更新Java。插件Manifest仅声明 MODIFY_AUDIO_SETTINGS 与TTS_SERVICE查询，没有电话、短信、联系人、存储、录音权限和Service，也没有声明INTERNET权限。宿主本身可能另有权限。

// #ifdef APP-PLUS
import { speakText, stopSpeak, getVoices, getSpeechEngines, release } from '@/uni_modules/hulu-yuyin'
// #endif

// 在Android App前台页面中调用。
getSpeechEngines(result => console.log('引擎列表', result))
getVoices({ language: 'zh-CN' }, result => console.log('离线音色', result))
speakText({ text: '你好，欢迎使用葫芦。', rate: 1, pitch: 1, volume: 0.8 }, result => {
  console.log(result.code, result.data, result.message)
})
// 停止按钮：stopSpeak(result => console.log(result))
// 页面onUnload：release(() => {})

参数与返回

有参接口 method(options, callback)，无参接口 method(callback)；getVoices即使无筛选也传 {}。返回 {code,data,message}，0成功、-1失败；data为对象，无业务数据时为 {}。必须先检查code，错误原因见message。只有speakText是持续回调，其余单次。

接口	参数	返回data / 行为
debugPing	无	module、nativeVersion、nativeBuild、packageName、androidSdk、manufacturer、model、offlineOnly
speakText	见下方SpeechOptions	status：started、done、stopped、error
stopSpeak	无	取消当前初始化或播放，原朗读收到stopped，停止接口另有单次回调
getSpeechEngines	无	list：name包名、label名称、isDefault；defaultEngine
getVoices	engine、language可选	list、requestedEngine、defaultEngine、defaultVoice、offlineOnly
getMediaVolume	无	index、min、max系统档位，volume归一值、fixed
setMediaVolume	volume必填，0～1	返回实际音量字段并附requested，按系统档位取整
toggleSpeaker	无	requested请求状态、status实际读回状态；true表示通信扬声器
getSpeakerState	无	status，通信设备是否为扬声器
openSpeechSettings	无	打开系统TTS设置，不启动下载或安装
release	无	关闭当前Activity所有语音请求、TTS客户端及插件选择的通信设备

SpeechOptions：

字段	类型/默认值	说明
text	string，必填	非空文字，长度上限取系统TextToSpeech.getMaxSpeechInputLength
language	string，zh-CN	BCP47语言标签，如en-US
engine	string，可省略	本机引擎包名，省略/空使用系统默认
voiceName	string，可省略	所选引擎getVoices返回项的name，省略自动选同语言离线音色
rate	number，1	语速0.5～2
pitch	number，1	音高0.5～2
volume	number，1	本次朗读增益0～1，0静音，不改系统媒体音量

选择音色：先查询引擎列表，再用该引擎包名请求 getVoices({engine:'实际包名',language:'zh-CN'},cb)，最后把同一个engine和列表项name作为voiceName传给speakText。音色项包含name、language、displayLanguage、networkRequired、quality、latency、isDefault、features、requiresDownload；只返回引擎报告已安装且无需网络的音色。未指定language时查询全部语言；指定后按语言筛选。

没有统一男女声名称，也不内置额外音色包。音色数量、中文支持及听感取决于手机现有引擎；列表为空或缺本地资源时返回空列表/朗读错误，不联网合成、不自动下载、不回退在线音色。Android可能回退到默认引擎，requestedEngine仅表示请求包名，公共API不能可靠确认实际绑定包名；朗读前仍会校验选中音色名称及离线状态。

生命周期及音频语义

新speakText校验有效后停止旧朗读。初始化超时15秒；started为持续事件，done/stopped/error为终态；失败也可能只有code=-1/message。getVoices/getSpeechEngines独立查询，不停止播放；快速切换列表时页面应按请求序号忽略旧返回。

页面退出调用release，Activity销毁有Fragment兜底。release丢弃未完成查询/朗读的后续回调，并关闭客户端；需要正常收到stopped时先单独stopSpeak。会话按Activity共享，多页面共用同一Activity时也共享语音会话。再次调用可重新创建控制器。

TTS使用媒体流：单次volume与系统媒体音量相乘影响响度。setMediaVolume立即影响其他应用，释放时不还原用户设置的媒体音量。toggleSpeaker切换的是通信免提/听筒，系统可能拒绝，不能保证改变TTS的耳机/蓝牙路由；也不会把文字播给通话对方。Android12+ release清除本插件主动选择的通信设备；旧版沿用AudioManager免提开关，release不自动恢复旧开关值。

演示与构建

独立Demo hulu-yuyin-uts-demo 提供文本框、引擎/语言/音色下拉框、语速/音高/音量滑块、播放停止、系统音量应用、通信扬声器、连接诊断和资源释放。启动只诊断并查询本机信息，不自动朗读或改系统音量。系统音量滑块只修改待应用值，点击“应用音量”才修改手机。

完整Java源码位于相邻 hulu-yuyin-uts-java，详见其AGENTS.md/PLUGIN_FLOW.md。插件ZIP只包含可集成UTS和AAR，不是完整Java源码备份。

Java构建、UTS转译、模拟页面检查与真机验证是不同层级。首次版本的最终结果见Java工程AGENTS.md；尚未制作新自定义基座或完成手机功能验证，需填写新Demo自己的appid后测试。离线资格来自引擎报告，应断网验证目标手机，插件不提供其他进程的网络隔离。

参考：UTS插件、Android UTS、原生混编。