📦 flutter_tts 是 Flutter 调用系统语音合成的三方库。我在制作折叠屏双栏有声讲义时,遇到了 oh-flutter/flutter_tts_ohos 首次点击报引擎未初始化、逐段等待毫秒级早退以及离线 WAV 导出未实现的问题,于是串行化了引擎重建与播放完成等待逻辑,并按分片序号补齐了带标准文件头的 WAV 离线合成。
完整代码已开源在 oh-flutter/flutter_tts_ohos,本次修改的接入方式见第五节。有问题可以到仓库提 Issue,也可以来 鸿蒙系统Flutter开源库社区 交流 Flutter 鸿蒙适配问题。
前言
我在 Mate X7 折叠屏模拟器上做了一个双栏有声讲义工作台:左栏展示三段中文技术讲义,点击顺序朗读时跟着当前语音高亮对应卡片;右栏负责把选中的段落离线导出成 WAV 音频并校验文件头。接入 flutter_tts 4.2.5 和社区鸿蒙实现包 flutter_tts_ohos 后,刚打开页面第一次点朗读就弹出了引擎未初始化异常;等后台建好引擎再点一次,声音虽然出来了,页面却在 5 ms 内一连跳完了三段;点右侧导出按钮更是直接抛出方法未实现错误。
顺着插件的 ArkTS 代码往下查,我发现语种配置没有等待底层引擎重建完成,朗读回调也没有区分“合成结束”和“播放结束”,而离线合成写文件接口在原仓里还是空白。把异步锁、队列模式映射、播放阶段过滤和 44 字节 RIFF/WAVE 封装补齐后,模拟器上三段讲义总挂起等待从 5 ms 恢复到 18,658 ms,每段读完才切向下一段,单次离线导出也在 246 ms 内生成了 173,204 B 的标准 WAV 文件;随后在华为畅享 100 Pro Max 真机上跑同一套操作,三段累计等待从 53 ms 恢复到 18,569 ms,导出耗时 356 ms 同样生成 173,204 B 有效 WAV,还捕获并自动重排了 1 次跨进程乱序分片。

图1 讲义操作流程
一、从双栏讲义里的朗读与导出需求说起
1.1 顺序朗读和离线导出各自在等什么
这个讲义页面在折叠屏展开态采用左右双栏布局,到了直板手机竖屏宽度下会自动切换成单栏滚动视图。左栏放了三段中文讲义,点击「顺序朗读全部 3 段」后,高亮边框应当停在当前正在发声的段落上,等这一段读完再推进到下一段;点击右栏导出按钮后,应用需要在沙箱目录拿到一份能被标准音频工具直接解析的 WAV 文件。
之所以把讲义拆成独立段落,是为了让读者一眼看清当前读到了哪一段,也方便单独挑选某一段生成离线音频卡片。这三段示例文字本身很短,分段并不是因为触碰了系统合成长度上限。同时,Example 的职责集中在验证跨端等待时序与导出文件结构,卡片收藏管理、系统媒体播放器界面、外语跟读打分以及多端云同步都不在这次的验证范围内。
排查之前,我先把页面里的两个“等待完成”拆开看:顺序朗读要等扬声器真正把声音播完,离线导出则是不经过扬声器发声、等合成出来的音频分片全部收齐并落盘关闭。两条路径底层都走同一个鸿蒙语音引擎,但终点信号完全不同:
- 系统原生能力层:HarmonyOS 的 CoreSpeechKit(
@kit.CoreSpeechKit)提供端侧离线语音合成,中文默认离线女声输出 16000 Hz、16 位、单声道线性 PCM 字节流。请求参数里的playType决定输出去向:设为 1 时由系统直接驱动扬声器播报,设为 0 时不外放声音、仅通过onData回调分段吐出裸 PCM 数据。系统吐出无头 PCM 属于底层流式接口的正常设计,并非系统缺陷。 - Flutter 插件桥接层:上游主包 flutter_tts 通过
'flutter_tts'方法通道下发语种配置、队列模式、等待开关、语音播报和离线导出指令;鸿蒙实现包 flutter_tts_ohos 负责在 ArkTS 侧管理引擎生命周期、对齐跨端队列枚举、过滤中间态回调,并在请求导出 WAV 时按序拼接分片与写入容器文件头。 - 应用业务与示例层:页面在首次运行前统一初始化一次中文语种与语速,顺序循环中等待每段
speak返回后再切换段落高亮;当用户点击「停止」按钮时,页面根据插件返回的取消状态码立即终止后续段落循环。
1.2 检查上游与社区仓库,为什么以 oh-flutter/flutter_tts_ohos 为准
动手改代码之前,我先检查了 pub.dev 上的上游主包,以及 oh-Flutter 和 CPF-Flutter 两个社区组织下的语音合成仓库,核对各自的目录结构与方法覆盖范围。

图2 上游包页面
图 2 是 flutter_tts 4.2.5 的发布页,维护方为 eyedeadevelopment.com,源码托管在 dlutton/flutter_tts,采用 MIT 许可。我检查了它的 lib/flutter_tts.dart:虽然发布页标签只列出了 Android、iOS、macOS、Web 和 Windows,但朗读、停止、语种配置、完成等待、队列模式与 synthesizeToFile 离线导出等方法全部直接向 'flutter_tts' 通道转发调用,没有在 Dart 层用平台判断拦截鸿蒙设备。只要鸿蒙端有一个注册在该通道上的原生插件包,业务层就能继续使用标准的 package:flutter_tts/flutter_tts.dart 入口。各候选仓库的核对情况见表1。
| 仓库或包来源 | 分支或版本 | 鸿蒙目录与底层依赖 | 关键能力覆盖与选型结论 |
|---|---|---|---|
| pub.dev/packages/flutter_tts | 4.2.5 | 无 ohos 目录 | 提供完整跨端 Dart API 与通道协议,需配合鸿蒙原生实现包使用 |
| oh-flutter/flutter_tts | master 分支 | 无 ohos 目录 | 仅同步上游源码镜像,无 ohos 分支与原生插件代码 |
| oh-flutter/flutter_tts_ohos | master(4.2.5) | 含 ohos(CoreSpeechKit) | oh-flutter 维护的鸿蒙实现包,存在首点未就绪竞态、等待早退与导出未实现缺口 |
| oh-flutter/text_to_speech | main(0.2.3) | 含 ohos(CoreSpeechKit) | 另一套轻量独立库,仅含基础单句朗读,无等待完成与音频文件导出接口 |
| CPF-Flutter/fluttertpc_flutter_tts | br_4.2.5_ohos_dev | 含 ohos(CoreSpeechKit) | 派生自整包仓库,覆盖面较广,同样存在默认等待失效与裸 PCM 无 WAV 头问题 |
表1 跨端库选型对比

图3 社区适配源码
图 3 是 oh-flutter/flutter_tts_ohos 的仓库主页(MIT 许可,版本号 4.2.5)。我检查发现,同组织下的 oh-flutter/flutter_tts 只是不含 ohos 目录的上游镜像,而 oh-flutter/flutter_tts_ohos 才是社区专门维护的鸿蒙原生实现仓:它在 pubspec.yaml 中声明了 FlutterTtsPlugin 原生插件类,构建鸿蒙应用时会自动写入 GeneratedPluginRegistrant.ets 并接管 'flutter_tts' 通道。相比另行复制一整套 Android、iOS、Windows 目录的派生整包,直接在 oh-flutter/flutter_tts_ohos 上补齐缺口既符合社区仓库归属优先级,又能让开发者保持上游 flutter_tts 4.2.5 主包依赖不变。因此,我固定 oh-flutter/flutter_tts_ohos 的 master 分支作为基线进行升级与修复。
1.3 原版实现卡在了哪三步
我对照上游通道契约读完了原仓的 FlutterTtsPlugin.ets,并用双栏讲义页面逐项复现,定位出三处直接阻断场景的问题:
- 语种配置未等待引擎重建,首次点击朗读直接报错 🐛:CoreSpeechKit 的语种与音色是在创建引擎时绑定的。原版的语种与音色设置入口一进函数就先向通道返回成功,随后才在后台不带等待地销毁旧引擎、将引擎实例置空并异步创建新引擎。页面在首次朗读前顺序执行
setLanguage和speak时,前一步瞬间假返回,后一步恰好撞上引擎引用为空的重建窗口,直接抛出PlatformException(Engine not initialized)。 - 等待完成未过滤合成阶段信号,且缺少队列模式与取消状态区分 🐛:即便等后台引擎建好后再点第二次顺序朗读,原版依然会在几毫秒内连跳三段。原因有两层:一是原版未实现
setQueueMode,朗读请求固定按抢占打断模式提交;二是底层onComplete回调会先后触发两次——先报type: 0代表文本转 PCM 合成完毕(此时几秒钟的外放才刚开始),等声音真正播完再报type: 1。原版没有检查回调阶段类型,一收到合成结束或前一段被抢占停止的通知就解挂返回,导致循环立刻冲向下一段。另外,原版在用户主动停止播报时也对挂起请求返回状态码 1,页面无法分辨“自然读完”与“中途取消”。 - 离线导出直接返回未实现,且通道键值表取参方式不兼容 🐛:原版方法分发分支里没有处理
synthesizeToFile与awaitSynthCompletion,点击导出按钮直接落入默认未实现分支,抛出MissingPluginException。我还顺带发现一处隐藏的参数解析问题:Dart 端传入的键值表经鸿蒙 Flutter 引擎的StandardMessageCodec解码后在 ArkTS 侧是 Map 实例,必须通过.get(key)读取;原版直接当成普通对象用下标取值,运行时只会拿到空值。
二、同一页讲义,修复前后的双端实测变化
2.1 对照用的环境、配置与操作步骤
为了保证前后对比公平,我让基线组和修复组共用完全相同的自适应讲义代码、三段中文文本与鸿蒙宿主配置,唯一变量就是底层依赖的 flutter_tts_ohos 插件源码,先后安装到本地 Mate X7 折叠屏模拟器与 USB 直连的华为畅享 100 Pro Max 真机完成验证。具体环境见表2。
| 环境维度 | 实际验证配置 |
|---|---|
| 开发工具与 SDK | DevEco Studio 26.0.0,HarmonyOS SDK API 26;宿主 compatibleSdkVersion 为 5.0.0(12),targetSdkVersion 为 5.1.1(19) |
| Flutter 框架版本 | 3.41.9+ohos-1.0.2(Dart 3.11.5) |
| 折叠屏模拟器镜像 | Mate X7(展开态分辨率 2210 × 2416,系统软件版本 7.0.0.107,系统回报 OpenHarmony-7.0.0.105) |
| 实体手机真机 | 华为畅享 100 Pro Max(公开型号 YEW-AL80,固件 7.0.0.100,分辨率 1128 × 2444,arm64-v8a) |
| 原生语音能力引擎 | CoreSpeechKit 端侧离线引擎(online: 1,中文默认离线女声 person: 13,语速 1.0) |
| 对照基线与验证包 | 基线固定 oh-flutter/flutter_tts_ohos 的 master 分支;模拟器部署无签名包,真机在隔离目录注入调试签名安装 |
表2 实测环境与基线
每次从桌面冷启动应用后,我都按同一顺序执行验证:
- 队列策略保持默认的「默认契约」(不额外调用
setQueueMode),点击左栏底部「顺序朗读全部 3 段」,观察冷启动首点是否报错、每段高亮停留时长以及右上角的回调计数。 - 等朗读流程结束后,保持默认选中的第 1 段,点击右栏「导出 lecture_seg_1.wav 并校验文件头」,由页面直接回读应用沙箱文件并按小端序解析前 44 字节 RIFF/WAVE 头字段。
我也检查了示例工程的 ohos/build-profile.json5 与 entry/src/main/module.json5,同时清理了原仓遗留在版本库里的本地路径文件与作者个人签名配置。实际生效的 SDK 目标版本与设备类型声明见图 4。

图4 宿主关键配置
2.2 Mate X7 折叠屏模拟器运行画面对比
先看原版基线包在 Mate X7 展开态窗口下的表现。从桌面刚打开工作台点击「顺序朗读全部 3 段」,页面在 61 ms 处就停了下来,顶部状态栏和黑底日志框同时报出 PlatformException(Engine not initialized, TTS engine is not initialized),三段讲义一段也没读出来,如图 5 所示。

图5 原版首点报错
等后台异步建好引擎后,我第二次点击顺序朗读,接着再点击右侧导出按钮,完整录制过程见图 6:

图6 原版早退与报错
图 6 里,第二次点击后左栏三张段落卡片几乎一瞬间全部变红,记录到的单段 await speak() 等待时间分别只有 1 ms、1 ms 和 2 ms,整个三段循环 5 ms 就跑完了;此时第一段甚至第二段都被第 3 段的抢占调用冲掉,扬声器只剩最后一段在滞后播报。紧接着点击导出按钮,右下角立刻红框提示 MissingPluginException(No implementation found for method synthesizeToFile on channel flutter_tts),沙箱里没有任何音频文件生成 ❌。
换成升级修复后的插件包,从桌面冷启动后直接点击一次顺序朗读,播完再点导出,运行过程见图 7:

图7 修复后逐段播报
这一次冷启动首点直接进入第 1 段朗读,蓝色高亮框稳稳停在第 1 段上,等足 6,164 ms 至 6,170 ms 播完变绿后才切到第 2 段 ✅。我在另一轮运行至第 2 段中途时抓拍了图 8 的实时状态:

图8 段落挂起高亮态
看图 8 右上角的计数非常有代表性:第 1 段已经在 6,164 ms 处播完解挂,第 2 段刚开始发声,此时「开始回调」是 2 次,「完成回调」只有 1 次。虽然底层引擎在启动第 2 段约两百毫秒后就已经发出了第 2 段的合成阶段完成信号,插件已经把它拦下,没有提前唤醒 Dart 侧的等待逻辑,也没有多发一次完成通知。
两套包各自跑完顺序朗读与 WAV 导出后的最终静止画面对比见图 9 和图 10:

图9 原版失败汇总态

图10 修复通过态
在图 10 中,修复包三段讲义分别等待 6,170 ms、6,318 ms 和 6,168 ms,总挂起耗时 18,658 ms;三次朗读加一次离线导出,一共触发 4 次开始回调和 4 次完成回调,严格一一对应。右下角导出面板耗时 246 ms 一次校验通过,读出文件总长 173,204 B、前 12 字节十六进制 52 49 46 46 8C A4 02 00 57 41 56 45,对应 16000 Hz、16 位、单声道、PCM 载荷 173,160 B,折算音频时长 5.41 s。
2.3 把导出音频与 HiLog 通道日志放在一起核验
除了看界面回读结果,我还通过 HDC 从模拟器应用沙箱 /data/app/el2/100/base/com.example.flutter_tts_ohos_example/files/lecture_seg_1.wav 把生成的音频文件拉回开发机,用 xxd、file 和 ffprobe 命令行工具做独立二进制核验,结果见图 11。

图11 音频头对照
取回的 emulator_lecture_seg_1.wav 共 173,204 B,SHA-256 为 1d50d21c3e056423688188ad494eea20e13a0ac78f497b4c500ec4778151cfe9。对照十六进制前 44 字节:
- 偏移 0x00…0x03 是 ASCII 魔数 52 49 46 46(RIFF),偏移 0x04…0x07 的小端 32 位无符号整数 8C A4 02 00 等于十进制 173,196,恰好是文件总字节数减 8;紧接着 57 41 56 45 是 WAVE 容器标识。
- 偏移 0x0C…0x23 是 24 字节的 fmt 格式块:PCM 编码值为 1,声道数 1,采样率 80 3E 00 00 为 16000,字节率 00 7D 00 00 为 32000,块对齐 2,采样位深 16。
- 偏移 0x24…0x2B 是 data 子块标识与小端长度 68 A4 02 00(十进制 173,160),加上 44 字节头正好等于 173,204 B。按 173,160 ÷ 32000 = 5.411 s 算出的音频净时长,加上首尾播报调度间隙,也和第 1 段外放等待的 6,170 ms 吻合。macOS 系统工具将其识别为标准
pcm_s16le单声道 16000 Hz WAVE 音频。
再看同轮采集的原生与 Flutter 混合 HiLog 日志(图 12):

图12 日志对照
图 12 下半部分清晰记录了修复包(PID 31696)每段朗读的两步时间点:以第 1 段为例,00:55:55.310 就收到了 type=0 合成完成,插件没有放行,一直等到近 6 秒后的 00:56:01.216 收到同一请求号的 type=1 播放完成,才在 00:56:01.224 唤醒第 1 段等待结果。而 00:56:15.951 的文件导出任务本身走静默合成模式,不会产生扬声器播放回调,插件在收到合成完成通知时立即将 15 个 PCM 分片拼接封装为 173,204 B 的 WAV 落盘。表3 汇总了同条件下的关键观测指标。
| 验证指标(Mate X7 同款 3 段讲义与首段导出) | 原版基线 | 升级修复后 | 变化量与结果说明 |
|---|---|---|---|
| 冷启动首次点击顺序朗读结果 | 61 ms 抛未初始化异常 | 一次点通并完整播完 3 段 | 语种重建加异步锁等待,消除首点竞态 |
| 3 段顺序朗读总挂起耗时(引擎就绪态) | 5 ms | 18,658 ms 🟢↑ | +18,653 ms,恢复等待真实播音结束 |
单段 await speak() 挂起耗时 | 1 / 1 / 2 ms | 6,170 / 6,318 / 6,168 ms | 每段均完整覆盖约 6.2 秒的中文离线播报 |
| 3 段朗读完成回调触发次数 | 仅末段滞后触发 1 次 | 3 次 🟢↑ | +2 次,与 3 次开始回调恢复 1:1 对齐 |
离线 synthesizeToFile 导出字节数 | 0 B(抛未实现异常) | 173,204 B 🟢↑ | +173,204 B,含 44 B WAV 头与 173,160 B PCM |
系统 file / ffprobe 格式校验 | 无导出文件 | 标准 16 位单声道 16kHz WAVE | 耗时 246 ms 落盘,解析时长 5.41 s |
表3 修复前后指标
2.4 华为畅享 100 Pro Max 真机投屏复测与乱序分片重排实证
模拟器跑通后,我又在纯英文隔离目录为基线包和修复包注入调试签名,通过 USB 顺序安装到华为畅享 100 Pro Max(公开型号 YEW-AL80,API 26)真机复测同一套流程。在直板手机竖屏宽度下,讲义工作台自动切换为单栏滚动视图(DevEco Studio 独立 Screen Mirroring 投屏窗口顶栏硬件序列号已做像素马赛克脱敏):

图13 真机原版报错

图14 真机修复通过
对照两套签名包在真机上的运行画面与 HiLog 日志:
- 真机原版基线(PID 47470,图 13):冷启动首次点击顺序朗读同样立即抛出
PlatformException(Engine not initialized);等 1.6 秒后台建好引擎后再点一次,三段await speak()分别仅在 1 ms、49 ms、1 ms(总挂起 53 ms)就提前返回,最终只收到末段滞后播完的 1 次完成回调;随后点击导出按钮,直接报出MissingPluginException(No implementation found for method synthesizeToFile on channel flutter_tts),总字节数为 0 B。 - 真机升级修复版(PID 49032,图 14):冷启动首点直接起播,三段讲义依次挂起 6,111 ms、6,308 ms、6,142 ms,总挂起 18,569 ms,三次朗读加一次导出共触发 4 次开始回调与 4 次完成回调,严格一一对应;底部导出面板耗时 356 ms 一次校验通过,生成与模拟器端字节数完全一致的 173,204 B 标准 WAV 文件(头字节 52 49 46 46 8C A4 02 00 57 41 56 45,16000 Hz、16 位、单声道,PCM 载荷 173,160 B,时长 5.41 s)。
更值得留意的是真机导出那一刻的原生日志:Writing synthesized audio: chunks=15 reordered=1 bytes=173204 wav=true。模拟器单次导出 15 个分片刚好按序到达,而在畅享 100 Pro Max 真机的多核跨进程 IPC 投递中,同样这 15 个音频分片真实发生了 1 次相邻序号逆转 🔍。如果直接按回调到达先后往文件里追加,那两段语音切片就会前后错位;加上基于 SynthesisResponse.sequence 的升序重排后,落盘前自动恢复了正确语序,最终得到了与模拟器端完全一致的 173,204 B 音频。
三、顺着通道与原生回调拆解核心实现
升级后的插件把“扬声器顺序播报”和“离线合成写 WAV”拆成两条职责分明的状态线,但共享同一把异步引擎锁。整体协作时序见图 15。

图15 双通路时序
3.1 用异步锁串行化引擎重建,并对齐队列与 Map 取参
首先解决首次点击报引擎未初始化和参数读取问题。我引入 ArkTS 标准库提供的 ArkTSUtils.locks.AsyncLock,把引擎创建和语种切换全部收拢进同一把互斥锁临界区:语种设置、音色切换与音色清空都必须等新引擎真正创建完毕并挂好监听器之后,才向 Dart 层返回成功;即使插件挂载时的后台预热还没跑完,首次朗读或导出请求也会在 ensureEngine 中排队等待同一把锁,不会再读到半空中的空引用。
接着补齐 setQueueMode 的跨端语义映射。上游 Dart 层沿用 Android TextToSpeech 的常量定义,而鸿蒙 CoreSpeechKit 的队列模式数值恰好相反,对应关系见表4。
| 模式语义 | Flutter Dart 层传入值 | 鸿蒙原生引擎值 | 引擎实际行为说明 |
|---|---|---|---|
| 抢占打断模式(默认契约) | 0(对应 QUEUE_FLUSH) | 1 | 新语音立即打断并替换当前正在播报的语音 |
| 排队追加模式 | 1(对应 QUEUE_ADD) | 0 | 新语音排入引擎内部队列尾部,等前序语音播完再播 |
表4 队列模式映射
我将插件内部的队列模式初始值设为 1(对应跨端默认的抢占模式),在设置队列模式时将 0 和 1 做反向映射,并用字典按唯一请求号分别保存等待中的通道回调句柄。需要注意,上游 Android 实现原本只在抢占模式下保存单个等待结果;这里按请求号逐条跟踪排队追加模式下的挂起请求,属于在鸿蒙端补充的增强能力。兼容键值表与普通对象的参数读取辅助方法及 handleSpeak 核心入口如下:
private readArgField(args: ESObject, key: string): Object | undefined {
if (args === undefined || args === null) {
return undefined;
}
// @ohos/flutter_ohos 的 StandardMessageCodec 会将 Dart Map 解码为 ArkTS Map 实例
if (args instanceof Map) {
return (args as Map<string, Object>).get(key);
}
if (typeof args === 'object') {
const record: Record<string, Object> = args as Record<string, Object>;
return record[key];
}
return undefined;
}
private handleSpeak(call: MethodCall, result: MethodResult): void {
if (this.detached) {
result.error('DETACHED', 'Plugin is detached from FlutterEngine', null);
return;
}
const text: string = this.extractSpeakText(call.args);
if (!text || text.length === 0) {
result.success(0);
return;
}
// 离线合成写盘进行中时拒绝并发外放,防止共用引擎任务互相冲掉回调
if (this.synthTask !== null) {
result.error('BUSY', 'File synthesis is in progress, speak rejected', null);
return;
}
const waitCompletion: boolean = this.awaitSpeakCompletion;
const effectiveQueueMode: number = this.queueMode;
if (effectiveQueueMode === 1 && (this.activeSpeakIds.size > 0 || this.pendingSpeakResults.size > 0)) {
// 抢占模式直接打断并结算上一条挂起朗读,而非以 BUSY 拒收新请求
this.flushPendingSpeakResults(0);
this.isSpeaking = false;
this.invokeChannel('speak.onCancel', true);
}
const wasQueueBusy: boolean = effectiveQueueMode === 0 &&
(this.activeSpeakIds.size > 0 || this.pendingSpeakResults.size > 0);
const requestId: string = this.nextRequestId('speak');
this.activeSpeakIds.add(requestId);
if (waitCompletion) {
const ownTimeoutMs: number = this.computeSpeakTimeoutMs(text.length);
let initialBudgetMs: number = ownTimeoutMs;
if (wasQueueBusy) {
// Account for prior queued utterances until handleSpeakStart re-arms ownTimeoutMs.
let queuedBudgetMs: number = 0;
this.speakTimeoutDurations.forEach((ms: number) => {
queuedBudgetMs += ms;
});
initialBudgetMs = ownTimeoutMs + queuedBudgetMs;
}
this.pendingSpeakResults.set(requestId, result);
this.armSpeakTimeout(requestId, ownTimeoutMs, initialBudgetMs);
} else {
result.success(1);
}
this.submitSpeakAsync(text, effectiveQueueMode, requestId, waitCompletion);
}
对于排队模式(queueMode === 0)下的连续入队请求,上面先累加在队列前面的待播语音预算作为 initialBudgetMs,避免后段讲义尚未轮到开播就被提前超时结算;等真正收到系统开播回调 onStart 时再以本句自身的 ownTimeoutMs 重置计时。同理,在 synthesizeToFile 入口也会同步检查 activeSpeakIds.size > 0 || isSpeaking,防止非等待模式下刚起步的外放语音被离线导出意外打断。
3.2 区分合成结束与播放结束,修正停止取消返回值
拿到请求号登记后,下一步就是把完成回调里的阶段信号分清楚。查阅 HarmonyOS SDK 的语音合成声明文件可以看到,CompleteResponse.type 明确区分了两个阶段:
- 取值为 0(合成结束):本条请求的文本转 PCM 阶段结束,所有音频分片已生成完毕。对于静默离线文件导出,这就是触发落盘的终点信号;但对于扬声器播报,此时声音才刚播了开头几百毫秒。
- 取值为 1(播放结束):扬声器播音全部结束,这才是开启
awaitSpeakCompletion后应当解挂并返回状态码 1 的时刻。
同时我还修复了三处等待与取消收尾细节:一是维护活跃朗读请求集合,只在确实存在未播完请求时才向 Dart 层发送 speak.onCancel,并在销毁重建引擎前先解绑旧监听器的宿主引用,避免初始化切换语种时无故触发取消回调;二是把用户主动停止播报时对挂起请求的返回值从原版的 1 改为 0,让业务层的段落循环一旦检测到返回值不是 1 就能立刻跳出,不再继续往下读第 2、第 3 段;三是给挂起的朗读等待请求加上按字数与语速动态估算的超时看门狗,并在完成、报错或停止时回收,防止底层意外漏发结束信号时触发 BUSY 锁死。完整回调分发与停止逻辑如下:
handleSpeakComplete(requestId: string, response: textToSpeech.CompleteResponse): void {
const completeType: number = (response !== undefined && response !== null && typeof response.type === 'number')
? response.type
: 1;
hilog.info(LOG_DOMAIN, LOG_TAG, `onComplete requestId=${requestId} type=${completeType}`);
const task: SynthTask | null = this.synthTask;
if (task !== null && task.requestId === requestId) {
// 离线导出在收到首次完成事件时无缝交接至写盘看门狗并落盘,兼容 type=0 与直接上报 type=1 的固件,并保持占位直至 closeSync
if (!task.writing && !task.cancelled) {
task.writing = true;
this.writeSynthTaskToFile(task);
}
return;
}
// 扬声器播报必须等真正的播放结束信号(type === 1),直接过滤提前到达的合成结束通知
if (completeType !== 1) {
return;
}
this.clearSpeakTimeout(requestId);
const wasActive: boolean = this.activeSpeakIds.delete(requestId);
this.isSpeaking = this.activeSpeakIds.size > 0;
const pending: MethodResult | undefined = this.pendingSpeakResults.get(requestId);
if (pending !== undefined) {
this.pendingSpeakResults.delete(requestId);
pending.success(1);
}
// 仅针对仍在追踪集合中的有效朗读请求向 Dart 派发完成事件,拦截 stop() 之后或离线任务补发的延迟回调
if (wasActive || pending !== undefined) {
this.invokeChannel('speak.onComplete', true);
}
}
private handleStop(result: MethodResult): void {
try {
if (this.engine !== undefined) {
this.engine.stop();
}
} catch (error) {
hilog.warn(LOG_DOMAIN, LOG_TAG, `engine.stop warning: ${JSON.stringify(error)}`);
}
this.isSpeaking = false;
const hadSpeakActive: boolean = this.activeSpeakIds.size > 0 || this.pendingSpeakResults.size > 0;
// 用状态码 0 结算所有挂起中的 speak 请求,明确告知调用方播报已被中途取消而非自然读完
this.flushPendingSpeakResults(0);
if (hadSpeakActive) {
this.invokeChannel('speak.onCancel', true);
}
this.cancelActiveSynthTask(0);
result.success(1);
}
3.3 按分片序号升序重排 PCM 并封装 44 字节 RIFF/WAVE 头
补齐离线文件合成时,插件将播报参数里的播放类型设为静默模式(0),此时 CoreSpeechKit 会通过分片回调一批批送回 PCM 内存块。正如 2.4 节在畅享 100 Pro Max 真机上捕获到的乱序现象,跨进程回调并不能保证严格按时间片顺序抵达,所以我在接收回调里先立刻调用 audio.slice(0) 深拷贝一份独立内存(防止底层 C++ 线程池在等待异步锁期间复用原缓冲区),再把分片序号与到达次序一起推入缓存数组。
全部分片收齐后,除显式指定 .pcm 后缀的裸流请求外,其余导出文件统一前置标准 44 字节小端序线性 PCM RIFF/WAVE 文件头。各字段偏移与计算规则见表5。
| 字节偏移 | 长度 | 字段名与端序 | 写入值或计算公式(以 16kHz 单声道 16 位为例) |
|---|---|---|---|
| 0x00…0x03 | 4 B | ChunkID(ASCII) | 固定魔数 RIFF |
| 0x04…0x07 | 4 B | ChunkSize(小端 32 位无符号整数) | 36 加纯 PCM 总字节数(即文件总长减 8) |
| 0x08…0x0B | 4 B | Format(ASCII) | 固定容器标识 WAVE |
| 0x0C…0x0F | 4 B | Subchunk1ID(ASCII) | 固定格式块标识 'fmt '(末尾含空格) |
| 0x10…0x13 | 4 B | Subchunk1Size(小端 32 位无符号整数) | 线性 PCM 固定为 16 |
| 0x14…0x17 | 4 B | AudioFormat 与 NumChannels | 编码格式固定为 1,单声道固定为 1 |
| 0x18…0x1F | 8 B | SampleRate 与 ByteRate | 采样率 16000,字节率 16000 × 1 × 2 = 32000 |
| 0x20…0x23 | 4 B | BlockAlign 与 BitsPerSample | 块对齐为 2,采样位深为 16 |
| 0x24…0x2B | 8 B | Subchunk2ID 与 Subchunk2Size | 固定 data 标识加纯 PCM 载荷总字节数 |
表5 波形头字段表
负责稳定升序重排与组装 44 字节文件头的纯函数 buildSortedAudioBuffer 如下(独立导出便于在 Node 主机侧直接做二进制单测):
export function buildSortedAudioBuffer(
chunks: SynthPcmChunk[],
wrapWavHeader: boolean,
sampleRate: number,
numChannels: number,
bitsPerSample: number
): ArrayBuffer {
// 优先按 CoreSpeechKit 返回的分片 sequence 升序重排;同序号时保留原始到达次序保证稳定排序
const sorted: SynthPcmChunk[] = chunks.slice().sort((a: SynthPcmChunk, b: SynthPcmChunk): number => {
if (a.sequence !== b.sequence) {
return a.sequence - b.sequence;
}
return a.arrivalIndex - b.arrivalIndex;
});
let pcmByteLength: number = 0;
for (const chunk of sorted) {
pcmByteLength += chunk.data.byteLength;
}
const headerSize: number = wrapWavHeader ? WAV_HEADER_BYTES : 0;
const output: ArrayBuffer = new ArrayBuffer(headerSize + pcmByteLength);
const outBytes: Uint8Array = new Uint8Array(output);
if (wrapWavHeader) {
const safeRate: number = sampleRate > 0 ? sampleRate : DEFAULT_SAMPLE_RATE;
const safeChannels: number = numChannels > 0 ? numChannels : DEFAULT_AUDIO_CHANNELS;
const safeBits: number = bitsPerSample > 0 ? bitsPerSample : DEFAULT_BITS_PER_SAMPLE;
const bytesPerSample: number = Math.max(1, Math.floor(safeBits / 8));
const byteRate: number = safeRate * safeChannels * bytesPerSample;
const blockAlign: number = safeChannels * bytesPerSample;
const view: DataView = new DataView(output);
// 写入 12 字节 RIFF 容器头,小端序 ChunkSize 等于 36 加上全部 PCM 载荷字节数
outBytes[0] = 0x52; // 'R'
outBytes[1] = 0x49; // 'I'
outBytes[2] = 0x46; // 'F'
outBytes[3] = 0x46; // 'F'
view.setUint32(4, 36 + pcmByteLength, true);
outBytes[8] = 0x57; // 'W'
outBytes[9] = 0x41; // 'A'
outBytes[10] = 0x56; // 'V'
outBytes[11] = 0x45; // 'E'
// 写入 24 字节 fmt 格式块,AudioFormat=1 表示未压缩线性 PCM
outBytes[12] = 0x66; // 'f'
outBytes[13] = 0x6d; // 'm'
outBytes[14] = 0x74; // 't'
outBytes[15] = 0x20; // ' '
view.setUint32(16, 16, true);
view.setUint16(20, 1, true);
view.setUint16(22, safeChannels, true);
view.setUint32(24, safeRate, true);
view.setUint32(28, byteRate, true);
view.setUint16(32, blockAlign, true);
view.setUint16(34, safeBits, true);
// 写入 8 字节 data 子块标识与纯 PCM 字节长度
outBytes[36] = 0x64; // 'd'
outBytes[37] = 0x61; // 'a'
outBytes[38] = 0x74; // 't'
outBytes[39] = 0x61; // 'a'
view.setUint32(40, pcmByteLength, true);
}
let offset: number = headerSize;
for (const chunk of sorted) {
const src: Uint8Array = new Uint8Array(chunk.data);
outBytes.set(src, offset);
offset += src.byteLength;
}
return output;
}
3.4 把合成任务占位保持到文件描述符关闭之后
做文件合成时还有一处容易漏掉的并发窗口:收到合成结束回调只代表内存里的分片收齐了,异步写盘和关闭文件描述符还需要几十毫秒。如果一收到完成通知就立刻清空当前合成任务引用,此时用户快速连点第二次导出同一路径,新任务就会与还没写完的旧文件句柄撞在一起 💣。
为此,我给离线合成任务设计了完整的生命周期闭环:
- 在文件合成入口完成参数与路径校验后、进入第一次异步等待引擎就绪之前,先同步登记当前合成任务对象,并快照此刻的
awaitSynthCompletion等待开关与启动 30 秒超时释放定时器,防止后续修改开关或底层长时间不回调时永久卡死BUSY。 - 写盘入口无缝接管写入阶段看门狗,先等待此前已受理但仍在异步锁队列排队的分片入账全部完成,再进入串行锁按覆盖截断模式循环写满全部字节;若写盘期间收到迟到分片则自动重写完整音频,收尾阶段先执行
fileIo.closeSync关闭句柄,最后才清空任务占位引用。 - 如果用户在写盘期间点击了「停止」,取消逻辑会将挂起的通道请求以状态码 0 结算返回,让界面不必卡死等待,同时保留后台任务占位与写入看门狗,正常关闭句柄或极端挂起超时时均能安全释放槽位并清理残缺文件。
围绕这套状态机,我编写了 31 项 Node 主机控制流单测、2 项插件方法通道测试和 4 项 Example 界面测试,覆盖乱序分片 WAV 封装、无序号分片单调递增分配、缺块检测与写盘期迟到分片重写、短写续写与非等待模式写失败报错、合成与播放阶段过滤、过期回调拦截、离线 type=1 完成兼容、语种重建等待与失败回滚恢复、flush 模式下新朗读抢占、排队预算累加与写入看门狗防 BUSY 锁死,全部在本地验证通过。
四、适配过程中踩到的几个细节坑
4.1 StartResponse.audioChannel 不能直接当 WAV 声道数
⚠️ 我在第一版封装 WAV 头时踩过一个字段名误导的坑。看到启动回调返回结构里同时带有采样率、采样位深和 audioChannel 三个字段,我就顺手把第三个字段的值填进了 WAV 头的声道数位置。
结果导出的文件头声道数变成了 3,原本 5 秒多的语音被播放器算成了 1.8 秒。回头去查系统 SDK 的接口注释才恍然大悟:StartResponse.audioChannel 回传的其实是调用方在扩展参数里传入的音频流路由通道 soundChannel(我们传的是 3,代表媒体助手播报通道),根本不是 PCM 音频的物理声道数!现在我只从启动回调动态读取采样率和采样位深,物理声道数则固定使用当前离线中文 PCM 已核实的单声道值 1。如果后续扩展多声道在线模型,仍需单独核实声道元数据。
4.2 请求号字符规则、沙箱目录层级与上游平台枚举陷阱
除声道字段外,联调中还有四处跨端兼容细节很容易踩坑,我先把原版隐患与处理方式归纳在表6 中。
| 细节位置 | 原版隐患 | 本次处理与接入建议 |
|---|---|---|
请求号 requestId | 下划线拼接毫秒戳,含非法字符且同毫秒易重名 | 改为纯字母数字加自增计数器 |
| 文件导出保存路径 | 应用级与模块级沙箱目录层级不同 | 拦截相对路径越界,推荐传完整路径并开启 isFullPath |
| 语速区间与低速传参 | 上游只匹配 android/ios 枚举;低于 0.5 静默失效 | 区间平台字段兼容填 'android',并对 0.0…0.5 做 0.5 下限钳位 |
| 原仓工程跟踪文件 | 误提交生成文件与原作者本机 .p12 签名路径 | 清理构建残留,补齐开源合规说明文档 |
表6 跨端兼容细节
其中最容易让业务层找错文件的是沙箱目录层级。插件挂载到引擎时拿到的是应用级上下文,默认将相对文件名写进 /data/storage/el2/base/files;而常用路径工具库大多基于 Ability 上下文,返回的是模块级目录 /data/storage/el2/base/haps/entry/files。业务代码如果想指定目录并在导出后立即回读,最稳妥的做法是拼好完整沙箱路径,再把 synthesizeToFile 的第三个参数设为布尔真值。
另一处隐蔽崩溃来自 getSpeechRateValidRange。上游 flutter_tts 4.2.5 解析返回字典时,只会在含 android 和 ios 两项的枚举列表里用 firstWhere 硬匹配平台名;原仓返回 'ohos' 会直接触发未匹配异常。因此我在返回鸿蒙有效语速区间 0.5…2.0 时将该标识兼容设为 'android',同时把跨端常见的 0.4 等慢速传参钳位到鸿蒙支持的最低档 0.5。
4.3 连续分段朗读时不要在循环内部重复设语种
由于 CoreSpeechKit 的语种与音色绑定在引擎实例上,每次切换语种或音色都会触发插件销毁旧引擎、重新拉起离线语音服务并加载音色列表。在页面里做多段连续朗读时,应当把语种、音色、语速和音量设置放在初始化阶段执行一次;进入段落循环后只调用 speak 提交下一段文本,既省去每段之间几百毫秒的引擎重建开销,也避免了旧引擎退出时的残余状态干扰。
五、结论与可直接复用的建议
5.1 这次升级修复解决了什么
回到开篇的双栏有声讲义场景,这次针对 oh-flutter/flutter_tts_ohos 的升级修复打通了三件事:第一,给引擎初始化与语种重建加上异步互斥锁,消除了冷启动首次点击朗读的未初始化报错;第二,补齐队列模式映射、过滤合成阶段提前到达的通知并区分停止取消的 0 返回值,让顺序朗读真正等每段语音播完再推进页面高亮;第三,完整实现了鸿蒙端 synthesizeToFile,按分片序号升序重排并写入标准 44 字节小端序 RIFF/WAVE 文件头,让导出的音频能被播放器直接读取。
5.2 在自己的项目中直接接入
💡 由于上游主包 flutter_tts 4.2.5 已经开放了全部方法通道调用,业务项目只需在 pubspec.yaml 中同时声明上游 flutter_tts 与鸿蒙实现包 flutter_tts_ohos 即可,Dart 侧业务代码保持标准的 import 'package:flutter_tts/flutter_tts.dart'; 不用改动任何包名。在社区仓库合并本次改动前,可以通过下面的公开分支固定提交直接拉取包含完整修复与 WAV 导出的版本:
dependencies:
flutter_tts: ^4.2.5
flutter_tts_ohos:
git:
url: https://atomgit.com/abaoge/flutter_tts_ohos.git
ref: 22ec425dfc07431eca327a8538b36786e198a296
导入 flutter_tts 与 dart:io 后,在页面状态类中准备语音实例、初始化标记、会话递增令牌与互斥标记,即可直接实现逐段同步高亮朗读和标准 WAV 文件导出:
Future<void> _initTtsOnce() async {
if (_ready) return;
// 仅在首次使用时绑定一次语种与语速,避免在分段循环内反复销毁重建底层引擎
await _tts.setLanguage('zh-CN');
await _tts.setSpeechRate(1.0);
await _tts.setVolume(1.0);
_ready = true;
}
Future<void> speakSegmentsSequentially(
List<String> segments,
void Function(int activeIndex) onSegmentActive,
) async {
if (_busy) throw StateError('当前已有语音朗读或导出任务正在执行');
_busy = true;
final int session = ++_token;
try {
await _initTtsOnce();
await _tts.awaitSpeakCompletion(true);
for (int i = 0; i < segments.length; i++) {
if (session != _token) break;
onSegmentActive(i);
final dynamic res = await _tts.speak(segments[i]);
// 当用户主动调用 stop() 时插件返回 0,立即终止后续段落翻页
if (res != 1 || session != _token) break;
}
} finally {
_busy = false;
}
}
Future<File> exportParagraphToWav(String text, String fullWavPath) async {
if (_busy) throw StateError('当前已有语音朗读或导出任务正在执行');
_busy = true;
try {
await _initTtsOnce();
await _tts.awaitSynthCompletion(true);
// 显式传入完整沙箱文件路径并将 isFullPath 设为 true,避免应用级与模块级目录混淆
final dynamic res = await _tts.synthesizeToFile(text, fullWavPath, true);
if (res != 1) {
throw StateError('离线合成已取消或未完成(返回值: $res),不读取旧文件');
}
final File wavFile = File(fullWavPath);
if (!await wavFile.exists() || await wavFile.length() < 44) {
throw StateError('导出的 WAV 文件不存在或缺少 44 字节标准文件头');
}
return wavFile;
} finally {
await _tts.awaitSynthCompletion(false);
_busy = false;
}
}
5.3 关键选项与适用边界
- 推荐传完整路径导出:调用
synthesizeToFile时优先传入明确的沙箱绝对路径并设置isFullPath: true;若确需获取不含 44 字节 WAV 头的原始采样流,将目标文件后缀命名为.pcm即可。 - 串行安排朗读与离线合成:底层扬声器播报与离线文件合成共用同一个
TextToSpeechEngine实例,插件在合成落盘直至句柄关闭期间会以BUSY拒绝并发外放请求,业务界面宜将朗读按钮和导出按钮做互斥禁用。 - 已验证范围与未测边界:实际运行验证覆盖了 Mate X7 折叠屏模拟器和华为畅享 100 Pro Max 真机上的中文端侧离线朗读与 WAV 导出,配套 31 项 ArkTS 控制流测试、2 项通道单测与 4 项界面测试均在主机通过。需要克隆完整双栏讲义页面对照查看的读者,可参考公开复现分支下的同款 Example 工程。平板真机、英文在线音色、蓝牙耳机焦点抢占以及 Android、iOS 等其他平台的运行表现不在本次验证范围内。
小结
做这页有声讲义之前,我原本以为调通语音合成只要听到中文发声就算大功告成,真正把分段高亮和离线制卡连起来跑才发现,引擎建好没有、回调报的是合成结束还是声音播完、跨进程送来的音频分片有没有乱序,每一步差一点都会让页面失步。把这些异步边界逐一对齐后,冷启动首点就能顺畅起播,三段讲义在模拟器和真机上都能稳稳等满 18 秒多 逐段翻页,导出的音频也带上了播放器可直接识别的 44 字节标准 WAV 头 🎉。以后对接类似的系统流式媒体能力,我都会先核清每个回调枚举对应的真实物理终点,再让界面状态跟着终点走。
3



被折叠的 条评论
为什么被折叠?



