一个只有 ArkTS 入口的离线合成引擎、一条会回调两次的完成通知、一套跑在 Kotlin 里的队列与状态机——这篇文章用一个跑在鸿蒙 2in1 上的 KMP 工程,把这三件事一次讲透。

仓库地址:https://atomgit.com/oh-tpc/tts-kmp-ohos
版本地址:https://atomgit.com/CPF-KMP-CMP/compose-multiplatform-core/tree/main-1.9.2-OH
三方库框架:https://atomgit.com/CPF-KMP-CMP

0. 环境与实测设备

项版本/型号
DevEco Studio26.0.0(构建用 HarmonyOS SDK 26.0.0)
Kotlin / Kotlin/Native2.2.21-1.0.0(目标 ohosArm64)
Gradle / JDK8.14.3(wrapper)/ 17(gradle.properties 固定 org.gradle.java.home;DevEco 自带的 JBR 是 25.0.2,Kotlin 编译器解析不了它的版本串)
工程 SDK 版本6.0.0(20)(compatibleSdkVersion / targetSdkVersion,API 20 起)
TTS 模块1.0.0(本仓库,com.ohos.tts:tts,jvm + ohosArm64 两个变体)
系统能力Core Speech Kit textToSpeech(离线引擎,online: 1)
原生产物libohos_tts.so 8.21 MiB(debug 构建);entry-default-signed.hap 4.34 MB
测试24 项 JVM 用例(引擎 21 + 示例门面 3),0 失败;共享引擎自检 13 项
实测设备HUAWEI MateBook Pro S(MOR-M1),HarmonyOS 7.0.0.111(SP15C00E101R9P2),API 26

1. 合成完成不等于播放完成

这个仓库上一版是"端侧语音识别示例";这一版反着来:不收音,只发声。用的是 HarmonyOS 的系统级 TTS——Core Speech Kit 的 textToSpeech。它是离线引擎(online: 1),免联网、免麦克风权限、不按次计费,模型随系统提供。仓库播报、订单提示、无障碍朗读这类需要离线出声的场景,它比在线 TTS 更稳。

我一开始的想法很直接:调一次 speak,系统读完,再播下一句。

动手之后才发现,平台没有单个 finished 回调,只给了一组异步回调:

  • onComplete 会来两次:response.type === 0 是"合成完成",此时音频还没播完;type === 1 才是"播放完成"。只等一次,短句会在几毫秒内连续推进三次状态,长句会被下一句提前打断;
  • 抢占和停止之后,旧请求的回调还会来:一条 type=1、一条 onStop,都可能在你已经切到新请求之后才到达;
  • 引擎实例全设备合计不超过 3 个,不能每次点击都 createEngine;
  • 音色不是每个设备都有:2in1 不支持 downloadVoice,需要下载的音色在 PC 上根本不可用。

所以这一版的边界很清楚:平台负责发声,KMP 负责队列和状态。具体拆成三件事,正好对应上面这几条:

  • 校验与 requestId:文本长度、语速、音量、音调、声道这些平台约束,前移到共享层的构造器里,错误在本地就拦住;
  • 队列与抢占:一个 active 加一个双端队列,宿主只执行 TtsUpdate.command,不自己判断状态;
  • 事件归一化:把平台的五种回调收敛成 start / synthesized / complete / stop / error / audio,每个事件带 requestId,迟到的按"过期"丢弃。

结果是:一个由 24 项 JVM 用例和 13 项共享自检覆盖的 TtsEngine,页面只做三件事——输入文本、点按钮、渲染快照。

2. 效果展示

先看效果。这是页面在 2in1 上的样子:

在这里插入图片描述

窗口与页面标题都是 系统级 TTS,副标题写着 Core Speech Kit 离线合成 · KMP 共享队列。一块输入框里是示例话术 3 号库位,B 区,共 12 件,其中 2 件临期。;下面三颗按钮:蓝底的 开始播报、灰底的 停止、连续 3 段;再下面一排是语言和音色:中文 选中,右侧 聆小珊 与 聆小珊兼容档;一行语速滑杆停在 1.0x。

再往下是这套共享引擎的状态面板:状态:空闲、active:- 队列:0、submitted 0 · completed 0 · interrupted 0 · errors 0、lastEvent:无;事件区只有一行 暂无事件。

这是页面刚打开的样子,不是接错了:系统引擎要等第一次 speak 才创建(TtsHost.ensureEngine() 在第一次派发命令时才调 createEngine),省掉一次无用的创建。所以打开页面时,状态机还停在 IDLE,所有计数都是 0。

音色那一排也受设备能力限制:PC 上只出现 中文,音色只有 13(聆小珊)和 0(兼容档)。目录里有 21(男声)和 8(英文 Laura),但都要 downloadVoice,而 2in1 不支持下载;英文只剩一个需要下载的音色,于是连 English 这个语言入口都被页面隐掉了。目录里有音色,不等于设备上能用,这条后面还会说。

音频没法截图,效果只能看日志。点一次 开始播报,设备上真实的时间线是:

墙钟平台回调归一化事件共享状态
0 mscode: 2 开始startSPEAKING
400 mscode: 4,res.type=0(合成完成,count: 21)synthesizedSYNTHESIZED
5778 mscode: 4,res.type=1(播放完成)completeIDLE

原始日志长这样:

AI_INNER: [(OnResult)]onResult code: 2, req id: kmp-ohos-tts-1,
  res: {"audioType":"pcm","sampleRate":16000,"sampleBit":16,"audioChannel":3,"eventType":0}
AI_INNER: [(OnResult)]onResult code: 4, req id: kmp-ohos-tts-1,
  res: {"type":0,"msg":"synthesis complete","count":21}
AI_INNER: [(OnResult)]onResult code: 4, req id: kmp-ohos-tts-1,
  res: {"type":1,"msg":"speak complete"}
JSAPP: [kmp-tts] start kmp-ohos-tts-1 code=0 duration=0
JSAPP: [kmp-tts] synthesized kmp-ohos-tts-1 code=0 duration=400
JSAPP: [kmp-tts] complete kmp-ohos-tts-1 code=0 duration=5778
JSAPP: [kmp-tts] state=IDLE active=none queued=0

先看 400 ms 和 5778 ms 之间那 5.4 秒:合成只花了 400 ms,声音却还在播。这就是只等一次 onComplete 会出错的窗口:它占了播报生命周期的大部分时间。上面两段是设备验证记录里的原始摘录,完整日志和复现命令都在那份文档里。

连续三段也验过:submitted 7 · completed 7 · interrupted 0 · errors 0,事件列表按 START → SYNTHESIZED → COMPLETE 逐条推进;抢占模式下,旧请求迟到的 type=1 被共享引擎识别为过期事件,没有把新请求的状态带偏。这些机制在第 3 节和 5.3 展开。

3. 一条播报的生命周期:从 speak 到 type=1

写代码之前先把链路说清楚。整条链上,Kotlin 和 ArkTS 各管一段:

ArkUI 页面(Index.ets)
   │ speak(text, language, person, speed, queueMode)
   ▼
TtsHost.ets(ArkTS 适配层)
   │ JSON.stringify → ttsSpeak()
   ▼
libentry.so(C++ N-API)
   │ TtsSpeak(requestJson)
   ▼
libohos_tts.so(Kotlin/Native TtsEngine)
   │ 校验 → requestId → 入队/抢占 → 快照 + command
   ▼
TtsUpdate.command(TtsCommand)
   │ 平台参数就绪,Kotlin 的角色到此结束
   ▼
textToSpeech.speak(text, { requestId, extraParams })
   │ onStart / onComplete×2 / onStop / onError / onData
   ▼
TtsHost 归一化为事件 → ttsOnEvent() → TtsEngine.onEvent()
   ▼
新的快照 + 队列里的下一条 command

关键在最后两行:引擎从不直接调用系统,系统也从不直接改状态。所有平台回调都要先变成一条带 requestId 的事件,穿过 N-API 回到 Kotlin;所有状态迁移都在 Kotlin 里发生;ArkTS 拿到的是"快照 + 下一步命令"。

这一步的映射规则写死在 TtsHost 里:

平台回调归一化事件共享引擎动作
onStartstartSPEAKING
onComplete,type=0 且 playType=1synthesizedSYNTHESIZED,队列不动
onComplete,type=1complete出队下一条;队列空则回 IDLE
onComplete,type=0 且 playType=0complete只合成不播报时,type=0 就是终点
onStopstopSTOPPED
onErrorerror(带 code/message)ERROR,清空队列
onDataaudio(带 audioBytes/sequence)累计 audioBytes

状态机本身很小,但每一条边都有对应的真实场景:

IDLE --speak--> SPEAKING --synthesized--> SYNTHESIZED --complete--> IDLE
  ^                 |                         |                       |
  |                 +------stop/stop event----+--> STOPPED            |
  |                 +------error--------------+--> ERROR              |
  +-------------------------- new speak ------------------------------

SPEAKING --complete 且队列非空--> SPEAKING(下一条 command)
SPEAKING --interrupt speak-----> SPEAKING(stop=true + 新 command)

三个设计决定需要单独说明:

SYNTHESIZED 是一个独立状态,不是过渡。 它表示"音频已经生成,但还没放完"。把这 5.4 秒单独标出来,页面才能区分"合成完成"和"播报完成",队列也不会提前出队。只监听一次 onComplete 的实现,缺的正是这个状态。

只有 COMPLETE 推进队列。 START 和 SYNTHESIZED 都只更新快照;complete() 里才 removeFirstOrNull() 并把下一条设为 active,同时在 TtsUpdate 里返回 command。这样同一时刻只有一条请求处于活动状态,由共享层保证,不依赖宿主自己判断。

抢占与停止是两种语义。 抢占(INTERRUPT)清空队列、把新请求设为活跃,并返回 stop=true;宿主可以选择显式 engine.stop(),也可以直接执行新命令、靠新命令的 queueMode=1 让系统引擎自己换掉旧请求——示例用的是后者,少一次停止回调,也少一次状态抖动。用户点"停止"才调用 engine.stop(),共享层把状态置为 STOPPED 并记住被停的 requestId,等它迟到的 onStop 回来时只记一条 lastEvent,不再改状态。

4. 工程怎么搭:一个 KMP 引擎,八个 N-API 导出,一层 ArkTS 适配

先看整体结构。可测试的规则在 tts 模块,原生桥和鸿蒙宿主退到 example/:

tts-kmp-ohos/                                 # 仓库根:Gradle 工程 A
├─ tts/                                        # 公共 KMP 模块(jvm + ohosArm64,运行时零三方依赖)
│  └─ src/commonMain/kotlin/com/ohos/tts/
│     ├─ TtsModels.kt                          # 请求 / 命令 / 事件 / 快照 / 音色目录
│     ├─ TtsEngine.kt                          # 校验、requestId、队列、抢占、状态机、统计
│     └─ TtsJson.kt                            # JSON 编解码与无依赖解析器
├─ example/                                    # Gradle 工程 B(把 tts 的 projectDir 指到 ../tts)
│  ├─ shared/                                  # 门面 TtsExamples + JVM 验收测试
│  ├─ nativeApp/                               # ohosArm64 动态库与 C ABI
│  │  └─ src/ohosArm64Main/kotlin/…/NativeBridge.kt    # @CName 导出 9 个符号
│  └─ ohosApp/                                 # DevEco Stage 工程(不参与 Gradle)
│     ├─ entry/src/main/cpp/                   # N-API 壳:napi_init.cpp + CMakeLists.txt
│     ├─ entry/src/main/ets/tts/               # TtsHost / TtsProtocol / NativeTts
│     └─ entry/src/main/ets/pages/Index.ets    # 功能页
├─ docs/                                       # 设备验证日志、协议、接入清单
└─ README.OpenHarmony_CN.md

在这里插入图片描述

这次设计有四个关键决定:

规则在 KMP,平台调用在 ArkTS。 Core Speech Kit 只有 ArkTS 入口,就不额外包一层"伪 C++ TTS";KMP 管校验、requestId、队列、状态机、统计,ArkTS 只负责"建引擎、执行命令、转发回调"。设备上跑的规则,就是 21 项 JVM 用例覆盖的那份代码。

用两个 Gradle 工程。 DevEco 的 ohosApp 不参与 Gradle;example 用 include("tts") 再把 projectDir 指到 ../tts。Gradle 和 hvigor 各跑各的,HAP 那边只需要一个 .so 和一个头文件。

只过字符串,不过二进制。 请求、事件、快照全是 JSON 字符串;音频由系统直接播,跨语言边界上没有任何 PCM 缓冲。8 个 N-API 导出全部是"字符串进、字符串出",C++ 壳只做类型检查和 TtsFree。

音色目录也归 KMP。 TtsVoiceCatalog 是共享层的静态目录(13/0/21/8,带 requiresDownload 标记),页面按设备能力过滤。这样"哪些音色可用"不散落在 ArkTS 里,JVM 测试也能断言目录和语言回退。

桥的协议只有两个方法:speak 收请求 JSON、回 TtsUpdate;onEvent 收事件 JSON、回同一个 TtsUpdate。下面这份是 speak 返回的命令,字段和系统 SpeakParams 一一对应:

// TtsUpdate.command(节选)
{ "requestId": "kmp-ohos-tts-1",
  "text": "3 号库位,B 区,共 12 件。",
  "language": "zh-CN", "person": 13, "speed": 1.0,
  "volume": 1.0, "pitch": 1.0,
  "queueMode": 0, "playType": 1, "soundChannel": 3,
  "engineName": "kmp-ohos-tts", "online": 1 }

第一条播完后,onEvent 返回的快照和命令是这样的(字段有删减):

// TtsUpdate(complete 之后,队列里还有第二条)
{ "snapshot": { "status": "SPEAKING",
    "active": { "requestId": "kmp-ohos-tts-2", "text": "其中 2 件临期,请优先上架。" },
    "lastEvent": { "type": "COMPLETE", "requestId": "kmp-ohos-tts-1", "durationMs": 5778 },
    "stats": { "submitted": 2, "completed": 1, "interrupted": 0, "errors": 0, "spokenMs": 5778 },
    "revision": 4 },
  "command": { "requestId": "kmp-ohos-tts-2", "queueMode": 0, "playType": 1 },
  "stop": false, "shutdown": false }

对使用方来说,一次"连续 3 段"就是三次 speak 加一串事件:

// example/ohosApp/entry/src/main/ets/pages/Index.ets(节选)
private speakDemoQueue(): void {
  this.demoTexts.forEach((text: string) => this.speak(text, 0));   // 0 = 排队
}

// TtsHost 里:命令被串行派发,一次只有一条在飞
private enqueue(command: TtsCommandView): void {
  this.pendingRequestId = command.requestId;
  this.chain = this.chain
    .then(() => this.dispatch(command))
    .catch((error: BusinessError) => this.emitError(command.requestId, 0, this.errorText(error)));
}

这里没有"等 3 秒再播下一句"的定时器:下一句的派发时机完全由共享引擎在 complete 时给出。

5. 把代码讲透

5.1 校验与 requestId:把平台约束前移到构造器

平台对 speak 的参数是有硬约束的:文本非空且不超过 10000 字符、语速 0.5–2.0、音量 0.0–2.0、音调 0.5–2.0、声道 0–16。这些约束如果只写在文档里,调用方总能找到一个越界的组合,然后把 401 或 1002300001 留给用户。

共享层把它们放进了 TtsSpeakRequest 的 init:

// tts/src/commonMain/kotlin/com/ohos/tts/TtsModels.kt - TtsSpeakRequest.init(节选)
require(text.trim().isNotEmpty()) { "TTS text must not be blank" }
require(text.trim().length <= TTS_MAX_TEXT_LENGTH) {
  "TTS text must not exceed $TTS_MAX_TEXT_LENGTH characters"
}
require(speed in 0.5..2.0) { "speed must be between 0.5 and 2.0" }
require(volume in 0.0..2.0) { "volume must be between 0.0 and 2.0" }
require(pitch in 0.5..2.0) { "pitch must be between 0.5 and 2.0" }
require(soundChannel in 0..16) { "soundChannel must be between 0 and 16" }

text 在构造时只做 trim,实际送到引擎的是 normalizedText;characterCount 用的是 UTF-16 码元数(String.length 的口径)。语言标签走一层宽松解析:zh-CN、en-US、枚举名都能认,认不出就安全回退到中文——这比让一个未知字符串一路传到 createEngine 再报 1002300002 要好。

requestId 是整条链路的主键:事件靠它归属,队列靠它去重,迟到的回调靠它丢弃。共享层用"引擎名 + 自增序号"生成,不依赖 UUID,也不依赖宿主传:

// TtsEngine.kt - nextRequestId()
private fun nextRequestId(): String {
  sequence += 1
  return "$engineName-$sequence"
}

于是日志里看到的就是 kmp-ohos-tts-1、kmp-ohos-tts-2 这样一串可读的 id。requestId 只在内存里单调递增,进程重启从 1 开始;它只在当前会话里要求唯一。

5.2 队列与抢占:一个 active,一个双端队列

TtsEngine 的状态只有 9 个字段,其中主要的状态是 active 和 queued:

private var active: TtsCommand? = null
private val queued: ArrayDeque<TtsCommand> = ArrayDeque()

speak() 的分支很短:空闲就直接派发;不空闲就看队列模式:

// TtsEngine.kt - speak()(节选)
val current = active
if (current == null) {
  active = command
  status = TtsStatus.SPEAKING
  return publish(command = command)
}
return when (request.queueMode) {
  TtsQueueMode.QUEUE -> {
    queued.addLast(command)
    publish()
  }
  TtsQueueMode.INTERRUPT -> {
    stats = stats.copy(interrupted = stats.interrupted + 1)
    queued.clear()
    active = command
    status = TtsStatus.SPEAKING
    publish(command = command, stop = true)
  }
}

QUEUE 分支只返回快照、不带 command——排队的那条不会被提前派发。INTERRUPT 分支一次做四件事:计数、清队列、换 active、返回 stop=true 和新 command。

出队发生在 complete():

// 同文件 - complete()(节选)
stats = stats.copy(completed = stats.completed + 1, spokenMs = stats.spokenMs + event.durationMs)
active = null
lastError = null
val next = queued.removeFirstOrNull()
return if (next != null) {
  active = next
  status = TtsStatus.SPEAKING
  publish(command = next)
} else {
  status = TtsStatus.IDLE
  publish()
}

几个当时想清楚的点:

为什么不用系统自带的 queueMode=0 排队? 系统队列只保证"引擎内部按序播",它不提供"我提交了哪几条、现在播到第几条、还剩几条"的记录。页面要显示 队列:N、要支持"停止并清空"、要在抢占时丢弃旧请求,这些都需要应用侧的队列。系统队列继续用,但只作为最后一层的兜底。

抢占为什么还返回新 command? 因为"停旧"和"播新"要尽量合并成一次状态迁移。返回 stop=true 是给宿主的提示:想显式停就停;不想停,就让新 command 的 queueMode=1 去抢。示例选了后者,所以 5.5 里那句 if (update.stop && update.command === null) 才成立。

统计也属于状态。 submitted / completed / stopped / interrupted / errors / ignoredEvents / characters / spokenMs 全在快照里,页面、日志、JVM 测试看到的是同一份数字。completed 只在 complete() 里加,interrupted 只在抢占时加,ignoredEvents 只记被丢弃的迟到事件——这三个计数是排查队列问题最直接的入口。

引擎不保证线程安全,也不需要。 注释里写得很直白:ArkTS 宿主在 UI 线程调用它,SpeakListener 的回调也回到同一个线程。共享层因此不用锁;串行化由 ArkTS 侧的 chain 完成(5.5)。

5.3 事件归一化:type=0 是过程,type=1 才是结果

onEvent() 是事件处理的核心。它先过三道校验,再分发:

// TtsEngine.kt - onEvent()(节选)
if (status == TtsStatus.SHUTDOWN) {
  stats = stats.copy(ignoredEvents = stats.ignoredEvents + 1)
  return publish()
}
val current = active
if (current == null && event.type == TtsEventType.STOP && event.requestId == stoppedRequestId) {
  stoppedRequestId = null
  lastEvent = event
  return publish()
}
if (current != null && event.requestId.isNotEmpty() && event.requestId != current.requestId) {
  // A stop callback for an interrupted request is expected; anything else
  // belongs to a request that is no longer active.
  if (event.type == TtsEventType.STOP) {
    lastEvent = event
  } else {
    stats = stats.copy(ignoredEvents = stats.ignoredEvents + 1)
  }
  return publish()
}

三道校验分别对应三种真实情况:

已经 shutdown 的会话:宿主释放之后,任何回调都只会增加 ignoredEvents,不能把状态从 SHUTDOWN 拉回去。

用户点了停止:共享层把 active 清空、记下 stoppedRequestId。随后平台可能送来一条 onStop,这条事件没有 active 可以匹配,但它是我们自己停止的回执——于是只记 lastEvent,不再改状态,也不重复计数。日志里 STOPPED 之后那两条:code 6(onStop)被第二道校验记作 lastEvent,type=1(完成)在 complete() 里因为 active 为空被记成过期事件。

抢占之后旧请求的迟到事件:active 已经是新请求,旧 requestId 的 type=1 到达时既不能推进队列,也不能算完成。STOP 是预期内的,记一条;其他类型一律 ignoredEvents++。

校验通过之后才是状态迁移:

// 同文件 - onEvent() 的分发(节选)
TtsEventType.SYNTHESIZED -> {
  if (active != null) status = TtsStatus.SYNTHESIZED
  publish()
}
TtsEventType.AUDIO -> {
  stats = stats.copy(audioBytes = stats.audioBytes + event.audioBytes)
  publish()
}
TtsEventType.COMPLETE -> complete(event)
TtsEventType.STOP -> stopEvent(event)

SYNTHESIZED 只改状态、不动队列,这就是那 5.4 秒里页面能显示"合成完成"、而下一句不会提前开始播报的原因。COMPLETE 由 complete() 处理,由它决定是"下一条"还是"回空闲"。

complete() 里还有一层防御:如果 event.requestId 和当前 active 对不上,直接记 ignoredEvents 返回。入口已经校验过一遍,这里是第二道校验——共享层在这里多校验一次。

5.4 桥:字符串往返,九个符号

C ABI 上只有 9 个符号,除 TtsFree 外都是字符串进、字符串出:

符号作用
TtsSpeak校验 + 入队/抢占,返回 TtsUpdate
TtsOnEvent应用一条归一化事件,返回 TtsUpdate
TtsStop / TtsShutdown停止 / 释放,返回 TtsUpdate
TtsSnapshot当前快照
TtsVoices内置音色目录
TtsChecks13 项自检报告
TtsReset清空共享状态
TtsFree释放返回的字符串
// example/nativeApp/src/ohosArm64Main/kotlin/com/ohos/tts/example/NativeBridge.kt(节选)
@CName("TtsSpeak")
public fun ttsSpeak(requestJson: String): CPointer<ByteVar> = response {
  TtsExamples.speakJson(requestJson)
}

@CName("TtsOnEvent")
public fun ttsOnEvent(eventJson: String): CPointer<ByteVar> = response {
  TtsExamples.onEventJson(eventJson)
}

response { } 把异常统一转成 {"error":"..."},宿主那边只需要判断一个字段,不用理解 N-API 的错误码。NAPI 壳负责把 JS 字符串读成 std::string,调用完再把返回的 char* 复制成 JS 字符串并 TtsFree:

// example/ohosApp/entry/src/main/cpp/napi_init.cpp(节选)
static bool ReadUtf8(napi_env env, napi_value value, std::string& output) {
  size_t length = 0;
  if (napi_get_value_string_utf8(env, value, nullptr, 0, &length) != napi_ok) {
    return false;
  }
  std::string text(length + 1, '\0');
  if (napi_get_value_string_utf8(env, value, &text[0], text.size(), &length) != napi_ok) {
    return false;
  }
  output.assign(text.c_str(), length);
  return true;
}

几个取舍:

只过字符串。 请求、事件、快照都是 JSON;音频由系统直接播,PCM 不跨语言边界。这样 C ABI 上没有任何需要对齐的结构体,字段增删只影响 JSON 解析。

TtsFree 归 C++ 所有。 Kotlin 侧 nativeHeap.allocArray 分配,NAPI 壳 napi_create_string_utf8 复制后立刻释放;ArkTS 永远拿到独立字符串,不是指针。

NAPI 只暴露 8 个方法。 TtsFree 是 C++ 内部用的,ArkTS 侧只要 speak / stop / shutdown / onEvent / snapshot / getChecks / getVoices / reset(NativeTts.ets 里一一对应)。

version script 收敛导出面。 shared-library.map 只列 9 个符号、local: * 兜底,链接参数带 --entry=0。示例链的是 debug 构建,libohos_tts.so 8.21 MiB,签名 HAP 4.34 MB;要发布时换成 release 链接任务,体积会小一截。

5.5 ArkTS 适配层:单例引擎、串行 dispatch 与创建期间的竞态

TtsHost.ets 是整条链路里唯一碰系统 API 的地方。它要解决四个问题:引擎复用、创建串行化、命令串行化、回调归一化。

引擎按 (language, person) 复用。 全设备最多 3 个 TTS 引擎,页面每次切音色都重建会很快撞上限(1002300005)。ensureEngine() 只在语言或音色变化时 releaseEngine() + createEngine();并发创建用 creating 这个 Promise 兜住,后来者等前一个创建完再判断参数是否已经匹配。

// example/ohosApp/entry/src/main/ets/tts/TtsHost.ets(节选)
private async ensureEngine(language: string, person: number): Promise<textToSpeech.TextToSpeechEngine> {
  if (this.engine !== null && this.engineLanguage === language && this.enginePerson === person) {
    return this.engine;
  }
  if (this.creating !== null) {
    try { await this.creating; } catch (error) { /* 退回重试 */ }
    if (this.engine !== null && this.engineLanguage === language && this.enginePerson === person) {
      return this.engine;
    }
  }
  this.releaseEngine();
  this.creating = textToSpeech.createEngine({ language, person, online: 1, extraParams: { name: ENGINE_NAME } });
  try {
    const engine = await this.creating;
    engine.setListener(this.buildListener());
    this.engine = engine;
    this.engineLanguage = language;
    this.enginePerson = person;
    return engine;
  } finally {
    this.creating = null;
  }
}

命令串行派发。 chain 是一个 Promise 链:每次拿到 command 就 then 到队尾,保证 createEngine 和 speak 不会并发。这里还有一个很细的竞态:createEngine 还没返回时,用户就点了停止或另一条抢占。等引擎创建完,这条请求已经失效,不能再调用 speak:

private async dispatch(command: TtsCommandView): Promise<void> {
  if (this.disposed) {
    return;
  }
  const engine = await this.ensureEngine(command.language, command.person);
  if (this.disposed || this.pendingRequestId !== command.requestId) {
    // A stop or interrupt retired this request while the engine was warming up.
    return;
  }
  this.activeRequestId = command.requestId;
  this.activePlayType = command.playType;
  this.startTimes.set(command.requestId, Date.now());
  engine.speak(command.text, { requestId: command.requestId, extraParams: { /* speed / volume / pitch / queueMode / playType / soundChannel */ } });
}

pendingRequestId 是"当前唯一允许调用 speak 的请求";stop 和抢占会把它清掉或换成新 id,于是已失效的请求在这一步被静默丢弃。

回调归一化里的关键判断。 onComplete 的 type=0 到底算"合成完成"还是"最终完成",取决于这次请求的 playType:

// 同文件 - onComplete(节选)
const stage = complete.type;
const isSynthesisStage = stage === 0 && this.activePlayType === 1;
const startedAt = this.startTimes.get(requestId);
const durationMs = startedAt !== undefined ? Date.now() - startedAt : 0;
this.emit({
  type: isSynthesisStage ? 'synthesized' : 'complete',
  requestId: requestId,
  durationMs: durationMs,
  // …
});

只合成不播报(playType=0)时,type=0 就是终点,直接映射成 complete;合成并播报时,type=0 是过程,type=1 才是终点。durationMs 从宿主调用 engine.speak 的时刻算起,所以日志里的 complete 带着 5778 ms,而不是只有合成耗时。

抢占时不显式 stop。 前面提过,handleUpdate() 只在 update.stop && update.command === null 时调 engine.stop();抢占时 stop=true 但带着新 command,宿主直接派发新 command,由它自己的 queueMode=1 让系统引擎换掉旧请求。少一次 engine.stop(),也就少一次 onStop 回调和一次状态抖动。

释放要成对。 aboutToDisappear() → host.deactivate() → ttsShutdown() + engine.shutdown()。TtsHost 的注释里写得很清楚:一个页面一个 host,deactivate 之后不允许再 speak。

6. 踩坑与经验

以下坑来自这次开发的真实编译报错、设备日志和平台回执——有的是一条 C++ 编译错误,有的是一段只有 2in1 上才会出现的空音色列表,还有几处必须靠日志才能看出来的时序。

坑一:napi_get_value_string_utf8 的 const 正确性,直接编译不过。

napi_init.cpp:27:7: error: no matching function for call to 'napi_get_value_string_utf8'
  if (napi_get_value_string_utf8(env, value, text.data(), length + 1, &length) != napi_ok) {
      ^~~~~~~~~~~~~~~~~~~~~~~~~~
note: candidate function not viable: 3rd argument
      ('const std::basic_string<char>::value_type *' (aka 'const char *'))
      would lose const qualifier

NAPI 的这个参数要的是"可写缓冲区",而 .data() 在 const 字符串上返回 const char*,C++ 的 const 正确性在这里直接把编译拦住了——错误信息很长,但关键就一行 would lose const qualifier。修法是先用 nullptr 探长度,再拿非 const 的 &text[0] 填内容(5.4 那段就是修完的样子)。NAPI 不会绕开 const;出参缓冲区必须是可写内存。

坑二:onComplete 会来两次,只等一次会提前推进队列。

onResult code: 4, req id: kmp-ohos-tts-1, res: {"type":0,"msg":"synthesis complete","count":21}
onResult code: 4, req id: kmp-ohos-tts-1, res: {"type":1,"msg":"speak complete"}

type=0 是合成完成(音频已生成,但还在播),type=1 才是播放完成。设备上这两条之间隔着 5.4 秒(400 ms → 5778 ms)。只监听一次 onComplete 的话,短句会在几毫秒内把队列连跳三段,长句则会被下一句提前打断——两种症状完全相反,原因却是同一个。修法是把 type=0 映射成瞬态 SYNTHESIZED,只有 type=1(或 playType=0 时的 type=0)才推进队列。"合成完成"和"播报完成"之间隔着整段音频,不能当成同一个事件。

坑三:DevEco 的 JBR 25,Kotlin 编译器解析不了。

# Kotlin compiler cannot parse the DevEco JBR 25 version string; pin Gradle to a normal JDK 17.
org.gradle.java.home=<JDK 17 路径>

这是 gradle.properties 里的原文。DevEco 自带 JBR 25,Kotlin 2.2.21 的版本解析在这个版本串上失败;解决办法是把 JDK 17 固定进 gradle.properties,而不是每条命令前 export 一次 JAVA_HOME,让 ./gradlew 在任何终端里都跑同一套工具链。工具链问题用配置固定,不要依赖每台机器的默认 JDK。

坑四:SDK component missing,命令行 hvigor 指着另一套 SDK。

SDK component missing

独立的命令行 Hvigor wrapper 可能指向另一套 SDK。仓库说明的修法是显式设置 NODE_HOME 和 DEVECO_SDK_HOME,并且用 DevEco 安装目录下的 Hvigor wrapper:

export NODE_HOME="<DevEco Node 目录>"
export DEVECO_SDK_HOME="<DevEco SDK 路径>"

同一个工程、同一条命令,工具链换了就过——这种时候别改工程,先改 PATH 和 SDK 环境变量。

坑五:2in1 上没有 downloadVoice,音色目录不等于可用音色。

目录里写着四个音色:13、0、21、8。页面在 PC 上只显示前两个——21(男声)和 8(英文 Laura)都要下载,而 2in1 不支持 downloadVoice。英文只剩一个需要下载的音色,于是连 English 语言入口都被隐掉。如果不做这个过滤,直接把 21 递给 createEngine,可能撞上的是:

错误码含义
1002300003音色不支持/未下载
1002300005引擎创建失败(实例数超限等)

"目录里有"和"设备上能用"是两件事;音色列表要按 requiresDownload 和设备能力过滤,别等 createEngine 报错才发现。

坑六:停止和抢占之后,旧请求的回调还会来。

JSAPP: [kmp-tts] state=SPEAKING active=kmp-ohos-tts-2 queued=0
JSAPP: [kmp-tts] state=SPEAKING active=kmp-ohos-tts-3 queued=0
onResult code: 4, req id: kmp-ohos-tts-2, res: {"type":1,"msg":"speak complete"}
onResult code: 2, req id: kmp-ohos-tts-3, res: {...}

抢占之后,旧请求 2 的 type=1 才到达;如果按"收到 complete 就出队"处理,就会把新请求 3 的状态带偏。停止也一样:

JSAPP: [kmp-tts] state=STOPPED active=none queued=0
onResult code: 4, req id: kmp-ohos-tts-1, res: {"type":1,"msg":"speak complete"}
onResult code: 6, req id: kmp-ohos-tts-1, res: {"type":1,"msg":"stop success"}

修法是 5.3 那三道校验:requestId 对不上的一律不进状态机,STOP 只记 lastEvent,其余 ignoredEvents++。回调是异步的,requestId 是唯一的归属凭证;停止/抢占之后,必须按 id 丢弃,而不是按"最后一条"丢弃。

7. 现在怎么用:从 Maven 坐标到 2in1 上的一次 5.8 秒播报

经过上面的整理,这个工程是三层交付(Apache-2.0):

  • KMP 引擎(com.ohos.tts:tts):校验、requestId、队列、抢占、状态机、统计、音色目录和 JSON 契约,jvm 与 ohosArm64 两个变体,运行时零三方依赖;
  • 原生桥(example/nativeApp):9 个 @CName 导出 + version script,编成 libohos_tts.so;
  • ArkTS 适配层(example/ohosApp):TtsHost(Core Speech Kit)+ TtsProtocol(线协议)+ NativeTts(libentry.so 包装),以及整页示例。

接入 KMP 工程,先发布到本地 Maven 再引用:

./gradlew :tts:publishToMavenLocal
// commonMain
implementation("com.ohos.tts:tts:1.0.0")

产物是 tts(KMP 元数据)+ tts-jvm + tts-ohosarm64 三个坐标,Gradle 按目标自动选变体;消费端记得把 mavenLocal() 加进 repositories。这一版没有往公共仓库发——本机 本地 Maven 仓库 里能查到这三个变体,上面的坐标直接可用。

要接原生桥,把 example/nativeApp 里的 9 个 @CName 导出、napi_init.cpp 和 entry/src/main/ets/tts/ 三个文件抄过去即可;嫌麻烦就把 example/ohosApp 整个复制走。示例工程的 build-profile.json5 里带着本机的调试签名配置(证书、Profile、密钥库路径都是本机的),换机器时要换成自己的——个人 .p12 / .p7b / .cer 不要提交进公开仓库。

# 1) 21 项引擎用例 + 3 项示例门面用例(在仓库根执行)
./gradlew :tts:jvmTest
(cd example && ./gradlew :shared:jvmTest)

# 2) debug so + 头文件 → example/ohosApp/entry(在仓库根执行)
(cd example && ./gradlew :nativeApp:linkDebugSharedOhosArm64 :nativeApp:prepareOhos)

# 3) HAP(必须用 DevEco 自带 hvigor,见坑四)
cd example/ohosApp
export NODE_HOME="<DevEco Node 目录>"
export DEVECO_SDK_HOME="<DevEco SDK 路径>"
hvigorw \
  assembleHap --no-daemon --no-parallel

hdc -t "$DEVICE" install -r entry/build/default/outputs/default/entry-default-signed.hap
hdc -t "$DEVICE" shell aa start -a EntryAbility -b com.ohos.tts.sample

宿主检查清单就五条:

  1. 一个页面一个 TtsHost,createEngine 按 (language, person) 复用,全设备实例别超过 3 个;
  2. setListener 必须在第一次 speak 之前装好;
  3. onComplete 的 type=0 是合成、type=1 是播放,队列只在 type=1 前进;
  4. 所有平台回调都带 requestId 回共享层,停止/抢占之后按 id 丢弃迟到事件;
  5. aboutToDisappear 里调 deactivate(),把 engine.shutdown() 和共享 shutdown 都走一遍。

能力边界、构建步骤和 FAQ 都写在OpenHarmony 接入说明里,本文只挑了与这版 TTS 链路直接相关的部分。

当前版本在 DevEco Studio 26.0.0(SDK 26)、鸿蒙 2in1(HarmonyOS 7.0.0.111,API 26)上验证:24 项 JVM 用例全绿(引擎 21 + 示例门面 3),共享引擎的 13 项自检在 JVM 侧通过,assembleHap 产出 4.34 MB 签名 HAP;2in1 上短句从 start 到 complete 为 400 ms / 5778 ms 两段,连续三段按 START → SYNTHESIZED → COMPLETE 严格串行,submitted 7 · completed 7;抢占后旧请求的迟到 type=1 被记为过期事件;停止后 STOPPED 状态稳定,onStop 只记事件不改状态。

下一步的计划也记在这里:一是把 TtsHost + nativeApp + libohos_tts.so 打成 HAR,做成可独立分发的 OHOS 三方库;二是补 playType=0 的 WAV 封装与离线导出,现在这条路径只验证了事件和字节统计;三是把 listVoices() / downloadVoice() 的 UI 补上,让手机/平板上需要下载的音色也能选;四是给 Android/iOS 写 expect/actual 实现,复用同一套队列和状态机。如果你想看哪一个,可以在仓库 issue 里提。

Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐