Flutter 修复 audio_waveforms 鸿蒙波形提取句柄与内存驻留:多段语音备忘录预览与切歌释放
Flutter 三方库 audio_waveforms 用来提取音频波形和控制试听播放。在语音备忘录列表里连续预览、快速切歌时,原版鸿蒙实现漏关文件,提取任务也没有及时停止,留下了句柄和内存。我在原库上补齐了文件关闭、任务取消和播放器释放。
完整代码已提交 PR 至官方仓库 CPF-Flutter/fluttertpc_audio_waveforms,有问题可以到仓库提 Issue,也可以来 鸿蒙系统Flutter开源库社区 交流。
前言
我在做一个本地语音备忘录页面,希望点开录音就能看到波形,切到下一条时也能释放上一条的资源。拿六段合成音频在鸿蒙模拟器上试了一遍,却发现波形已经画出来了,等待提取结束的调用还没返回。继续切换,音频文件句柄和内存占用也在往上走。
我沿着播放器、Worker 和原生解码器检查释放代码,补上文件关闭、提取取消和 EOS 收尾,再统一两组沙箱样本并把诊断器改成三秒等待、收到首包进度后取消。重新在 Mate X7 模拟器上跑完五对冷启动对照和单进程 144 轮连续切换后,原库每 24 轮有 20 轮超时、残留 48 个音频句柄,修复版 16 次完整提取和 8 次中途取消全部按期结束,音频句柄始终为零,总句柄在 144 轮里稳定在 104;内存增量较原库大幅下降并在多批运行中出现回落,不过仍在 164.98 至 236.85 MiB 之间波动,底层分配器保留与缓存占用仍需区分。

图1 波形提取链路
一、从多条语音备忘录预览与切歌开始
1.1 列表预览与中途切歌需要完成的操作
📱 我做的示例页面是一个本地“语音备忘录”列表,放了 6 条时长 15 秒的 m4a 音频。点选一条时,页面先释放上一条使用的 PlayerController,再创建新控制器,按 80 个均方根(RMS)振幅点的目标提取并绘制柱状波形。用户可以播放、暂停试听,也可以在提取结束前直接点下一条。
页面有手动预览和自动诊断两个入口,都调用公开的 PlayerController 接口:
- 手动预览:点击条目后,先使旧选择失效,再依次停止、释放和销毁旧控制器。新控制器通过
preparePlayer开始提取,页面订阅onCurrentExtractedWaveformData更新波形,并提供播放控制。 - 24 轮诊断:6 条 15 秒音频循环 4 圈,每 3 轮安排 2 次完整提取、1 次取消尝试。完整提取最多等 3 秒;取消组先等首批非空波形进度,记录提取是否还没结束,再释放控制器。每轮分别记录成功、取消后结束、提前完成、超时或失败,最后静置 1.8 秒采样。
这些音频由 Example 的宿主诊断模块用鸿蒙 OH_AudioCodec 和 OH_AVMuxer 合成,内容是确定性的包络信号,没有真实录音。我把同一组六份 m4a 放进两组 Example 的 rawfile 资源,启动时写入各自沙箱,再逐个核对 SHA-256,避免两个应用各自编码产生不同文件。
采样从样本准备好以后开始,首次编码和复制的开销不计入结果。文件随应用提供,也不需要联网下载。
这个页面里的工作分别由系统、插件和 Example 承担:
- 鸿蒙系统提供底层能力:CoreFileKit 打开、关闭文件描述符,MediaKit 的
AVPlayer播放音频,OH_AVSource、OH_AVDemuxer和OH_AudioCodec完成容器解复用与 AAC 解码。ArkTS 的ThreadWorker让解码工作离开 UI 主线程。 - audio_waveforms 按
playerKey管理播放器和提取器,把文件句柄交给 Worker 与 C++ 库解码,再按时间窗将 PCM 帧算成归一化 RMS 数组,回传 Dart。控制器停止或释放时,插件负责通知底层清理对象。 - Example 调用插件来切换备忘录、绘制波形。进程句柄、线程目录和
hidebug内存数据由示例宿主单独读取,诊断代码没有放进插件的生产实现。
1.2 社区仓库检索与基线版本核对
🔍 我先检查了上游主包和鸿蒙社区仓库。社区已经有波形提取实现,所以我选择在现有库上修复,接着核对不同分支已经补了哪些代码。

图2 上游包页面
上游 audio_waveforms 由 simform.com 团队维护,源码在 SimformSolutionsPvtLtd/audio_waveforms,采用 MIT 许可。图 2 中的 pub.dev 版本为 2.0.2,平台标签是 Android 和 iOS。
主包提供 PlayerController、RecorderController 和 AudioFileWaveforms,支持录音、波形提取和试听状态流,但源码里没有 ohos 目录。鸿蒙的 Worker 与 C++ 解码实现由 CPF-Flutter/fluttertpc_audio_waveforms 维护。

图3 社区适配仓
图 3 是社区适配仓,和前面的上游发布页各有分工。访问仓库时,游客文件列表触发了频次限制,我改用匿名 Git 读取标签、分支,再核对取回的源码。
我检查了 oh-flutter 和 CPF-Flutter 两个组织,找到的情况是:
- 在检索的 oh-flutter 仓库范围内,我没有找到同名实现。CPF-Flutter 的 fluttertpc_audio_waveforms 已有录音、播放和波形提取代码,默认分支 main 与标签 2.0.0-ohos-1.0.0 指向同一提交。
- 同仓的 br_v2.0.2_ohos_dev 分支还没有合入 main,也没有正式标签。我逐文件比对后看到,它已经补上播放器文件关闭、Map 方法调用、
stopExtraction通道和 Worker 两段握手。无播放器提取、零字节 EOS 检查,以及 C++ 队列、线程安全函数的释放仍有缺口,具体列在表 1 中。
| 核查维度 | 公开标签 main (2.0.0-ohos-1.0.0) | 社区开发分支 br_v2.0.2_ohos_dev | 本文修复补丁 |
|---|---|---|---|
| 播放器音频 FD 关闭 | 未关闭,每次准备泄漏 1 个 FD | 已在释放路径补齐关闭 | 全路径幂等关闭并注销状态监听 |
| 插件实例容器与取消通道 | 误用对象属性索引,无取消通道 | 已改用 Map 接口并恢复取消通道 | Map 托管并在释放时自动前置停止 |
| Worker 停止与解码器销毁 | 发消息后同步强杀线程导致丢消息 | 已引入两段式停机握手 | 两段握手加 800 毫秒超时兜底与单点清理 |
| 无播放器独立提取波形 | 轮询空播放器导致提取无法启动 | 直接返回错误,仍强依赖先建播放器 | 原生 OH_AVSource 自解析元数据,零播放器提取 |
| 0 字节 EOS 终态包收尾 | 误报空指针错误,Worker 无完成分支致挂死 | 未改动 C++ 层 0 字节缓冲校验 | 修正零字节误报,Worker 显式处理 EOS |
| C++ 死队列与线程安全函数 | 全量 PCM 逐字节压入死队列,漏放 tsfn | 未改动解码死队列与停止释放逻辑 | 移除无消费者死队列,单点排空释放 tsfn |
表1 分支能力核对
我选 main 的公开标签 2.0.0-ohos-1.0.0 做原版基线,保留包名、MIT 许可和既有公共 Dart API。修复时参考了开发分支的 Worker 握手方式,再处理 ArkTS 到 C++ 之间漏关的句柄、没有退出的线程,以及仍被持有的队列和缓冲。
两组工程还有几处共同的编译调整。原版 Dart 代码导入了 plugin_platform_interface,pubspec.yaml 却没声明依赖,静态检查因此报错;脚手架测试也把组件类当成了平台接口类调用。我在基线组和修复组都补了依赖、改正基础测试桩,让它们能使用同一套 Flutter 3.41.9+ohos-1.0.2 工具链。基线控制器里另有一条重复导入,我按 lint 提示删掉了。这些调整没有改变基线插件的运行行为。
1.3 原版复现步骤与两类实际故障
我在 Mate X7(API 26)模拟器上运行 fluttertpc_audio_waveforms 的 2.0.0-ohos-1.0.0 标签,按下面的操作复现:
- 在应用沙箱准备 6 段 15 秒、44.1kHz 双声道 AAC 编码的 m4a 备忘录文件。
- 对单条文件创建
PlayerController,调用preparePlayer(path: path, shouldExtractWaveform: true, noOfSamples: 80)提取波形,随后调用stopPlayer()、release()和dispose(),如此连续切换或中途打断 24 轮。 - 观察
preparePlayer返回的Future完成情况,并在 24 轮结束静置 1.8 秒后通过进程句柄目录、hidebug与外部hidumper核对进程句柄、线程与内存。
我预期解码结束后能拿到实际算出的归一化波形点,数量接近目标的 80 个。切歌或释放控制器后,音频文件应当关闭,Worker 和 C++ 解码实例也应退出,而不是随着预览次数增加继续占用句柄和原生堆。
原版运行时,我先遇到了提取调用不结束的问题。
❌ 第一轮提取 15 秒音频,流式事件已经让页面画出了 79 根波形柱,preparePlayer 返回的 Future 却还在等待。我抓取 HiLog,看到解码线程已经输出到第 646 帧,读到了流结束标志 EOS,随后 N-API 完成回调打出一条错误:
W A02B66/com.example.pgc25wavebase/audio_waveform_decoder: {AudioDecOutputThread():289} Out buffer count: 646, size: 4096, offset: 0, flag: 10, pts: 14999251
I A02B66/com.example.pgc25wavebase/audio_waveform_decoder: {AudioDecOutputThread():277} Catch EOS, thread out
I A02B66/com.example.pgc25wavebase/audio_waveform_decoder: {AudioDecOutputThread():310} Out buffer end,Audio decoding completed
E A0FF00/com.example.pgc25wavebase/audio_waveform_decoder_native: {CompleteWork():62} create array buffer size: 0, status: 0, (nil)
日志里的 14999251 是最后一帧的时间戳,换算后为 14999.251 毫秒。另一个算法是按 646 个输出帧、每帧 1024 个采样帧计算,得到 661,504 个采样帧,在 44.1kHz 下约为 15000.091 毫秒。前者是时间戳,后者是采样帧数换算出的时长。
Worker 根据容器时长算出的单柱步长为 8269,80 个窗口需要 661,520 个采样帧。它又是在累加下一个采样前判断窗口是否已满,所以这两个乘法只能帮助理解窗口差异,不能精确算出最后一柱还差多少。
我继续看原版 CompleteWork,发现零字节缓冲的数据指针为空时,它虽然打印错误,后面的 napi_call_function 仍会执行。EOS 回调到了 Worker,但空缓冲不会进入采样循环,也没有单独触发完成通知。主线程还在等波形点数达到目标,提取就一直挂着。
因此,我在 Worker 中补上 EOS 完成分支,同时改正 C++ 对零字节缓冲的误报。解码结束不能只靠柱数判断。
继续切换备忘录后,我又看到了残留的 m4a 句柄和增长的内存。诊断器会在提取等待超时后继续执行停止、释放和销毁,再进入下一轮;这些清理调用执行过,仍不足以说明底层对象已经释放。具体是哪个对象没放开,我需要接着查文件打开位置、实例表和清理日志。
二、运行观察与测量边界
2.1 环境和两套诊断条件
我先后用初版诊断器和升级后的新版诊断器验证原库与补丁版:初版诊断器在 Mate X7 模拟器上记录了最初的排查现象;升级诊断器统一沙箱音频 SHA-256 校验、逐轮终态统计和“收到首包进度后再取消”的条件后,我又在 Mate X7 模拟器上完成了五对 AB/BA 冷启动基准与单进程 144 轮长测,并在华为畅享 100 Pro Max 真机上做了补充验证。
| 环境项 | 版本与配置 |
|---|---|
| Flutter / Dart | 3.41.9+ohos-1.0.2 / 3.11.5 |
| DevEco Studio | 26.0.0.865 |
| SDK / API | OpenHarmony API 26 |
| 本地模拟器 | Mate X7 折叠屏(镜像 7.0.0.107(SP8DEVC00E999R4P11),系统回报 OpenHarmony-7.0.0.105) |
| 实体真机 | 华为畅享 100 Pro Max(YEW-AL80,固件 7.0.0.100(SP9C00E100R9P4),OpenHarmony-7.0.0.105,arm64-v8a) |
| 基线插件 | 社区标签 2.0.0-ohos-1.0.0 |
| 构建方式 | Profile(模拟器无签名 HAP;真机隔离注入调试签名) |
表2 实测环境
先看 2.2 与 2.3 节来自初版诊断器的记录:完整提取最多等待 750 毫秒,取消组在启动提取 55 毫秒后释放。五对冷启动按 AB、BA、AB、BA、AB 顺序运行,每次做 24 轮,静置 1.8 秒后采样。它和后文 2.4、2.5 节三秒等待、收到进度后取消的新条件不同。
复核时,我发现两组各自编码的文件 SHA-256 不一致,原诊断器还吞掉了超时和异常,没有逐轮记录提取是否成功。固定等 55 毫秒,也无法确认取消时 Worker 已经开始解码。这些记录可以保留当时的现象,但输入和实际工作量都没有严格对齐,我不再用它们计算优化百分比。
2.2 原始记录中的句柄与内存现象
第一对记录里,原库的总 FD 从 99 增至 224,其中 40 个指向样本音频;补丁版从 99 增至 104,样本音频 FD 为零。图 4 的两段日志分别对应进程 20586 和 21849。

图4 原始阶段日志
我重新核对了十次运行的原始数值。表 3 的增量都以各自运行前的快照为起点,KiB 按 1024 换算为 MiB。hidumper 的 Total PSS 取自随后读取的系统内存表,与 hidebug PSS 的采样时刻不同,因此分开列出。均值、中位数和范围只描述这五次观察。
| 原始观测指标 | 原库均值 / 中位数(范围) | 补丁版均值 / 中位数(范围) |
|---|---|---|
| 音频 FD(个) | 39.4 / 39(39–40) | 0 / 0(0–0) 🔴↓ |
| 总 FD 增量(个) | +124.4 / +124(124–125) | +5 / +5(5–5) 🔴↓ |
| hidebug PSS 增量(MiB) | +183.58 / +185.02(174.96–192.80) | +74.95 / +84.45(57.69–85.16) 🔴↓ |
| Native 已分配增量(MiB) | +116.37 / +114.40(113.50–120.09) | +23.30 / +28.16(15.20–28.52) 🔴↓ |
| hidumper Total PSS(MiB) | 278.42 / 277.36(271.18–290.07) | 168.05 / 173.86(154.43–181.02) 🔴↓ |
| 活跃线程增量(个) | +16.4 / +16(15–18) | -4 / -3(-7 至 -2) 🔴↓ |
表3 原始观测汇总

图5 原始FD均值
图 5 画的是五次观察的音频 FD 均值和总 FD 增量均值。句柄更少,与文件关闭和实例移除的修改相符;但要确定内存具体少在哪个对象上,还需要分配栈或对象存活记录。总 FD 差额也不能直接换算成 Worker 数量。
2.3 句柄归零不代表内存收敛
我把第一对补丁版的日志单独拉出来看:第 6、12、18、24 轮和静置后的总 FD 都是 104,音频 FD 都是零;PSS 却依次为 124048、135539、149595、158604、160256 KiB。Native 已分配内存也从 70720 KiB 增至 80193 KiB。句柄没有继续累加,内存仍在增长。

图6 PSS阶段变化
这部分增长还没有查清。媒体库加载、分配器保留和运行时缓存都可能影响占用,我目前没有证据把它全部归为“正常缓存”。静置 1.8 秒只是固定的读取时点,也不足以证明稳态。已有记录支持音频 FD 在采样点归零,长期内存趋势仍待确认。
2.4 让诊断器先如实报告失败
于是我先改诊断器,让它把每轮结果记清楚。完整提取要在期限内返回非空数组才算成功;取消前要收到非空进度,并记录调用是否还在等待。释放后 Future 结束时,我还保存返回点数,以便区分“取消后返回部分数组”和“继续解码到文件末尾才返回”。
在改用三秒期限前,一次修复版预跑的 16 次完整提取中有 14 次成功、2 次超时,8 次取消请求后的 Future 都结束了,最终音频 FD 仍然是零。只看句柄卡片,两个超时就被漏掉了。
新页面分别显示这些结果。采样为空、目录打不开或必要字段无效时,页面会报错,不再用零值填出一个“成功”。
采集脚本也一起调整了:接受结果前核对两组固定音频的 SHA-256,每次冷启动前停止两个测试包,检查新 PID、轮次和汇总是否齐全,并记录宿主负载。逐轮结果和阶段指标同时写入应用文件,避免 HiLog 环形缓冲把前面的内容覆盖。
不完整的采样要单独保留,不能拼进旧样本。改完诊断器后,我在 Mate X7 模拟器上重新跑了五对 AB/BA 冷启动基准与单进程 144 轮长测,并在华为畅享 100 Pro Max 真机上做了补充验证;结果见下一节。
2.5 Mate X7 新条件五对基准与 144 轮长测
在新诊断条件下,单次完整提取最多等待 3 秒,取消组收到首批非空波形进度后再发起取消。两组应用启动后先把 rawfile 内置的 6 段合成 m4a 落地到沙箱并逐个校验 SHA-256,再按 AB、BA、AB、BA、AB 顺序完成五对共 10 次冷启动,每次运行 24 轮(16 轮完整提取、8 轮收到进度后取消),结束后静置 1.8 秒采集进程快照。

图7 基线24轮动效

图8 修复24轮动效
图 7 和图 8 是两组在 Mate X7 模拟器上执行 24 轮诊断的真实录制动效,图 9 和图 10 是静置采样完成后的终态画面。原库基线版由于缺少 EOS 0 字节完成分支,16 轮完整提取与 4 轮取消组全部卡满 3 秒超时,24 轮总耗时约 66.2 秒;修复验证版每轮在解码结束或取消握手后立即收敛,24 轮总耗时约 8.6 秒。

图9 基线终态画面

图10 修复终态画面
表 4 汇总了 Mate X7 新条件下五对冷启动(每组 n=5,共 24 轮/次)的逐轮终态与进程资源指标:
| 新条件五对指标(n=5) | 原库基线均值 / 中位数(范围) | 修复版均值 / 中位数(范围) |
|---|---|---|
| 24 轮逐轮终态分布 | 20 次超时、4 次成功(5 次一致) | 16 次成功、8 次取消后结束(5 次一致) 🎉 |
| 样本音频 FD(静置后,个) | 48.0 / 48(48–48) | 0.0 / 0(0–0) 🔴↓ |
| 进程总 FD 增量(个) | +133.0 / +133(+132 至 +134) | +4.2 / +5(+2 至 +5) 🔴↓ |
| hidebug PSS 增量(MiB) | +219.77 / +219.73(215.95–224.56) | +60.58 / +61.22(57.63–63.52) 🔴↓ |
| Native 已分配增量(MiB) | +165.58 / +165.62(165.20–165.98) | +26.50 / +26.48(26.10–26.85) 🔴↓ |
| hidumper Total PSS(MiB) | 334.69 / 335.54(330.05–339.20) | 176.04 / 176.17(173.07–178.86) 🔴↓ |
| 活跃线程增量/静置媒体线程(个) | +13.0 / +14(+9 至 +15)/21.4 | -1.2 / -1(-2 至 0)/3.0 🔴↓ |
表4 新条件五对汇总
为了验证 2.3 节提到的“单次 24 轮后内存是否还会无限上涨”,我接着在同一个修复版进程(PID 7401)内不重启应用,连续运行 6 批 24 轮诊断(累计 144 轮:96 次完整提取、48 次中途取消)。各批静置 1.8 秒后的采样列在表 5 中:
| 连续批次(累计轮次) | 本批终态分布 | 音频 FD / 总 FD | hidebug PSS(MiB) | Native 已分配(MiB) | 线程 / 媒体线程 |
|---|---|---|---|---|---|
| 启动基线(0 轮) | — | 0 / 101 | 114.60 | 63.10 | 49 / 4 |
| 第 1 批静置(24 轮) | 16 成功 / 8 取消结束 | 0 / 104 | 181.75 | 89.62 | 47 / 3 |
| 第 2 批静置(48 轮) | 16 成功 / 8 取消结束 | 0 / 104 | 197.68 | 111.29 | 49 / 3 |
| 第 3 批静置(72 轮) | 16 成功 / 8 取消结束 | 0 / 104 | 236.85 | 132.61 | 49 / 3 |
| 第 4 批静置(96 轮) | 16 成功 / 8 取消结束 | 0 / 104 | 183.40 🔴↓ | 73.10 🔴↓ | 49 / 3 |
| 第 5 批静置(120 轮) | 16 成功 / 8 取消结束 | 0 / 104 | 164.98 🔴↓ | 67.79 🔴↓ | 49 / 3 |
| 第 6 批静置(144 轮) | 16 成功 / 8 取消结束 | 0 / 104 | 176.73 | 76.66 | 46 / 2 |
表5 144轮批次快照
可以看到,从第 1 批(第 24 轮)到第 6 批(第 144 轮),样本音频 FD 始终为 0,进程总 FD 恒定停在 104(后 120 轮零新增句柄),媒体线程保持在 2 至 3 个。PSS 与 Native 已分配内存虽然在前 3 批上升至 236.85 MiB 和 132.61 MiB,但在第 4、第 5 批触发运行时与原生分配器回收后回落到 164.98 MiB 和 67.79 MiB,第 144 轮结束时为 176.73 MiB,不再像原库那样单批就突破 334 MiB 并伴随句柄与媒体线程持续堆积。
此外,我还在华为畅享 100 Pro Max(YEW-AL80)真机上跑过一次 24 轮新条件对照:原库(PID 15129)同样出现 20 次超时、样本音频 FD 涨至 48、总 FD 增加 132、PSS 增加 222.23 MiB;修复版(PID 17483)16 次完整提取与 8 次取消全部按期结束,样本音频 FD 归零,总 FD 仅增 3,PSS 从第 24 轮末的 201.77 MiB 回落至静置后的 184.50 MiB(增量 +48.41 MiB)。由于真机那次归档缺少原库第 4、22 轮逐轮日志及沙箱文件哈希表,我将它作为跨设备补充参考,主结论以 Mate X7 上完整核验的五对基准与 144 轮长测为准。
三、四层驻留根因与核心修复代码解析
我沿着一次波形提取往下查,会经过 Dart 控制器、ArkTS 主线程插件、ArkTS Worker,再到通过 N-API 调用的 C++ 解码库。图 11 是插件与原生库的配置。取消通知要传到这些对象,已经打开的文件和创建的线程也要在各自的释放代码中处理。

图11 插件原生配置
正常提取完成和中途取消都会进入清理代码。图 12 展开的是中途取消:停止请求回执先返回,Worker 清理与播放器释放可以并行执行,彼此不等待。

图12 两段停机握手
我按调用顺序修改了四处:
- 恢复 Dart 取消通道,让常规释放调用能通知提取器停止。
- 改正 ArkTS 的 Map 存取,并在播放器释放时关闭文件。
- 让 Worker 清理后回复确认,再由主线程销毁它;另补上无播放器提取所需的元数据读取。
- 删除 C++ 中无人读取的 PCM 队列,改正零字节误报,补齐线程安全函数与上下文的释放。
3.1 Dart 控制器取消契约与通道类型收敛
我检查 Dart 代码时,看到 Constants.stopExtraction 常量还在,对应的平台接口和 PlayerController 通道调用却已在早期提交中删去。应用调用 release() 或 dispose() 时,原生端只会收到释放播放器的指令,后台提取器收不到取消通知。
回传数组的类型也有一处问题:如果鸿蒙端传来的数值中含有整型 0 或 1,原版用 List<double>.from 转换就可能抛异常。我补了显式转浮点的处理,并恢复 stopWaveformExtraction(String key) 接口。
下面是 PlayerController 中的停止与释放方法,位于 lib/src/controllers/player_controller.dart。类里的 playerKey 标识当前实例,_isDisposed 记录是否已销毁;释放播放器前,先请求停止提取:
/// 请求停止当前控制器的在途提取;通道回执不等于 Worker 已经销毁
Future<bool> stopWaveformExtraction() async {
if (_isDisposed) return true;
try {
return await AudioWaveformsInterface.instance
.stopWaveformExtraction(playerKey);
} on MissingPluginException {
return false;
}
}
/// 释放关联播放器前先行中断在途波形提取,兼容既有业务释放调用链
Future<void> release() async {
await stopWaveformExtraction();
await AudioWaveformsInterface.instance.release(playerKey);
}
dispose() 也先请求停止提取,再释放平台对象和流控制器。只提取静态波形时,可以直接调用 controller.stopWaveformExtraction() 取消。至于页面连点时谁持有当前控制器,还需要 Example 自己处理,第四节会展开。
3.2 ArkTS 插件实例托管与播放器句柄回收
接着看鸿蒙插件入口。我发现播放器和提取器虽然声明为 Map,写入时却用了 this.audioPlayers[playerKey] = newPlayer 这样的对象属性语法。释放分支只调用对象的方法,没有移除容器条目;暂停列表又把删除元素的 splice 写成了只返回切片的 slice。
方括号写入的是 Map 对象上的普通属性,不会进入 Map 的键值集合,清空 Map 时也处理不到这些引用。因此,旧播放器和提取器一直被单例插件对象持有。
我把容器操作改为 .get()、.set() 和 .delete()。覆盖同名键、释放播放器或引擎执行 onDetachedFromEngine 时,都先通知提取器停止;异步回调删除引用前,再比较它是否仍是原来的实例,免得删掉后来创建的对象。
文件句柄的问题在 AudioPlayer.ets。原版 preparePlayer 用 fs.openSync(path) 打开文件,把句柄拼成 fd:// 地址交给 AVPlayer,但文件对象只存在于局部变量中。播放结束、释放播放器或再次准备其他音频时,都没有对应的关闭操作。
我增加了成员 playerFile 保存文件对象,用递增的 prepareGeneration 拦住快速切歌后过期的准备回调。释放时先拒绝还在等待的准备请求,再通过下面两个方法注销监听、释放播放器并关闭文件;重复调用不会再关闭同一个句柄:
private closePlayerFile(): void {
if (this.playerFile != null) {
try {
// 幂等关闭之前打开的沙箱音频文件描述符,归还内核句柄配额
fs.closeSync(this.playerFile.fd);
} catch (e) {
console.error(Constants.LOG_TAG, `Failed to close player fd: ${e}`);
}
this.playerFile = null;
}
}
private async releasePlayerResource(): Promise<void> {
this.stopListening();
this.isPlayerPrepared = false;
const current = this.avPlayer;
this.avPlayer = null;
if (current != null) {
try {
// 先解绑状态与错误监听,避免释放过程中重入触发旧回调
current.off('stateChange', this.stateCall);
current.off('error', this.errorCallback);
} catch (e) {
console.error(Constants.LOG_TAG, `Failed to off player listeners: ${e}`);
}
try {
await current.release();
} catch (e) {
console.error(Constants.LOG_TAG, `Failed to release AVPlayer: ${e}`);
}
}
this.closePlayerFile();
}
裸 PCM 播放用的渲染器封装也补了文件关闭分支。不过,本篇实际运行的是 AVPlayer 播放 m4a,PCM 后端只核对了源码并完成构建,还没单独跑过。
3.3 Worker 两段式停机握手与无播放器独立提取
⚠️ 停止提取的时序在 WaveformExtractor.ets 和 InternalWorker.ets 之间出了问题。原版 stopDecode() 先检查解码实例编号是否非空,再用 postMessage 发送停止消息,紧接着就调用 terminate() 销毁 Worker。
如果切歌太快,Worker 还没回传实例编号,检查条件就不成立,停止消息根本不会发出。即使拿到了编号,postMessage 也只是把消息放进 Worker 的队列;主线程马上终止 Worker,可能在 Worker 处理完排在停止消息之前的 PCM 回调之前,就把线程销毁。
这样一来,Worker 来不及关闭音频文件,也来不及通知 C++ 停止。全局表 g_decodeInstances 继续持有解码实例,两个底层解码线程也没有退出。
我把停止过程改为先请求清理、收到确认后再销毁 Worker:
- 主线程调用
stopDecode()后清除轮询定时器。如果还没向 Dart 交付结果,就先返回已采集的快照,让等待中的 Future 结束。随后发送停止消息并启动 800 毫秒兜底定时器,暂不终止 Worker。 - Worker 收到停止消息、正常解码结束或捕获异常时,都调用同一个可重复执行的清理函数:先通过
libdecode.stopDecode停止 C++ 解码线程、释放线程安全函数,再关闭音频文件,最后回复stopped。 - 主线程收到确认后清除定时器,调用
terminateWorkerSafely()。若 Worker 一直没有回复,则由 800 毫秒定时器强制终止。
下面是 WaveformExtractor.ets 中完整的 stopDecode()。类里保存 Worker、采样数组和待返回的结果,兜底时长由 TERMINATE_FALLBACK_MS = 800 指定:
stopDecode() {
if (this.isStopped) {
return;
}
this.isStopped = true;
this.clearPollInterval();
// 若调用方在提取完成前主动取消或释放,返回当前已采集快照以解开挂起的 Dart Future
if (!this.isResultDelivered) {
this.isResultDelivered = true;
this.result.success([...this.sampleData]);
}
try {
this.workerInstance.postMessage({
event: "stop",
instanceId: this.decoderInstanceId
});
// 等待 Worker 回传 stopped 后再销毁,超时未响应则强制兜底终止
this.terminateTimerId = setTimeout(() => {
this.terminateTimerId = -1;
this.terminateWorkerSafely();
}, TERMINATE_FALLBACK_MS);
} catch (error) {
console.error(Constants.LOG_TAG, `Error stopping decoder: ${error}`);
this.terminateWorkerSafely();
}
const cb = this.onStoppedCallback;
this.onStoppedCallback = null;
if (cb != null) {
cb();
}
}
另一个问题出现在只画静态波形的用法里。原版提取器每隔 100 毫秒查询播放器,等它准备好后再取采样率、声道数和时长。如果只调用 extractWaveformData,没有先准备 AVPlayer,原版就会一直轮询空对象;社区开发分支则直接返回错误。
我在 C++ 库中补了 extractAudioMeta,用公开 NDK 的 OH_AVSource_CreateWithFD、OH_AVSource_GetSourceFormat 和 OH_AVSource_GetTrackFormat 从文件读取采样率、声道数及微秒级容器时长。Worker 因而可以不依赖播放器取得这些信息。这属于功能扩展;本文备忘录运行先准备播放器,还没有单独验证这个入口,也没有测它的性能收益。
3.4 C++ 队列清理与跨线程上下文释放
查到 C++ 后,我继续处理没有消费者的 PCM 队列,以及回传 Worker 时用到的线程安全函数和上下文。
Decode.cpp 来自鸿蒙官方的音频解码播放 NDK 样例。原样例把解码后的 PCM 字节送进 audioDecContext_->renderQueue,由渲染回调取出后播放。改成波形提取器时,渲染器的创建和启动代码被注释掉了,ProcessPcmData 开头逐字节加锁入队的循环却留了下来。队列一直有数据写入,却没有代码读取。
按 15 秒、44.1kHz、双声道、16 位计算,一段音频解码后有 2,646,000 字节 PCM,约 2.52 MiB。如果音频长达 10 分钟,仅这些数据就超过 100 MiB,全都会留在这个无消费者的队列里。
前面的停机竞态又可能让 StopDecode 没有执行。全局表仍通过智能指针持有 Decode 实例,实例里的队列和缓冲也就留着。取消发生的时机不同,每个实例实际积累的量不同,不能按总轮数直接推算队列数量。
我删除了 Decode::ProcessPcmData 对 renderQueue 的写入,改为每次回调创建独立的 DecodePacket,保存当前帧数据。这样也避开了原版把可变上下文指针直接交给异步队列时的数据竞争:
void Decode::ProcessPcmData(uint8_t *source, size_t size)
{
// 移除无消费者的 renderQueue 逐字节入队,仅构建单帧载荷跨线程送入 Worker 计算 RMS
std::unique_lock<std::mutex> lock(doneMutex);
auto *context = static_cast<DecodeCallbackContext *>(sampleInfo_.playDoneCallbackData);
if (context == nullptr || context->closed.load() || context->tsfn == nullptr) {
return;
}
auto *packet = new DecodePacket();
packet->audioData.assign(source, source + size);
packet->isEos = false;
napi_status status = napi_call_threadsafe_function(
context->tsfn, packet, napi_tsfn_nonblocking);
if (status != napi_ok) {
delete packet;
}
}
DecodeNative.cpp 负责检查零字节缓冲,以及释放线程安全函数 tsfn 和会话上下文。
在当前模拟器上,零字节 EOS 的创建状态是 napi_ok,JS 缓冲对象有效,只是数据指针为空。我改成检查状态码和 JS 对象句柄,去掉这条误报。提取何时完成,仍由 Worker 的 EOS 分支通知。
下面的函数也处理了 Worker 环境销毁和打开句柄作用域失败的情况:即使不能再回调 JS,也会删除当前载荷。
原版 StopDecode 还有一处遗漏:移除全局表条目后,没有释放 tsfn 和上下文。直接删除上下文也不行,异步队列中可能还有回调在用它。
我在创建 tsfn 时绑定 FinalizeCallbackContext。停止时,先从全局表取出 Decode 实例,在锁外取消完成回调并等待解码线程退出,再由 ReleaseAndDeleteContext 设置关闭标志、调用 napi_release_threadsafe_function。上下文留给 N-API 排空队列后,通过终结回调删除:
static void FinalizeCallbackContext(napi_env env, void *finalize_data, void *finalize_hint)
{
(void)env;
(void)finalize_hint;
delete static_cast<DecodeCallbackContext *>(finalize_data);
}
static void CompleteWork(napi_env env, napi_value callback, void* ctx, void* data)
{
(void)ctx;
auto *packet = static_cast<DecodePacket *>(data);
if (packet == nullptr) {
return;
}
// 当 Worker 环境正在销毁或队列排空时,env 或 callback 为空,仅回收堆载荷即可
if (env == nullptr || callback == nullptr) {
delete packet;
return;
}
napi_handle_scope scope = nullptr;
if (napi_open_handle_scope(env, &scope) != napi_ok) {
delete packet;
return;
}
size_t bufferSize = packet->isEos ? 0 : packet->audioData.size();
void *bufferData = nullptr;
napi_value arrayBuffer = nullptr;
napi_status stat = napi_create_arraybuffer(env, bufferSize, &bufferData, &arrayBuffer);
// 0 字节 EOS 终态包满足 stat == napi_ok 且 arrayBuffer 非空(bufferData 为空属正常语义)
if (stat == napi_ok && arrayBuffer != nullptr) {
if (bufferSize > 0 && bufferData != nullptr) {
std::copy(packet->audioData.data(),
packet->audioData.data() + bufferSize,
static_cast<uint8_t*>(bufferData));
}
napi_call_function(env, nullptr, callback, 1, &arrayBuffer, nullptr);
} else {
AVCODEC_SAMPLE_LOGE("create array buffer failed, size: %{public}zu, status: %{public}d",
bufferSize, stat);
}
napi_close_handle_scope(env, scope);
delete packet;
}
static void ReleaseAndDeleteContext(DecodeCallbackContext* context)
{
if (context == nullptr) {
return;
}
context->closed.store(true);
if (context->tsfn != nullptr) {
napi_threadsafe_function fn = context->tsfn;
context->tsfn = nullptr;
// 交由 FinalizeCallbackContext 在线程安全队列排空后统一 delete context
napi_release_threadsafe_function(fn, napi_tsfn_abort);
} else {
delete context;
}
}
最后我调整了 Decode::Release() 的销毁顺序。原版还没等输入、输出线程退出,就开始销毁解复用器和解码器,快速中断时可能让后台线程访问已经释放的句柄。现在先清除运行标志、唤醒条件变量,并等待两个线程完成 join(),然后再销毁解复用器、解码器和上下文。
四、工程踩坑、分支对照与边界条件
4.1 返回点数与取消结果要按实际语义使用
容器时长用于计算波形窗口,EOS 用于判断解码结束。本文的 AAC 样本完整提取后可能有 79 或 80 个点,页面按实际数组长度绘制即可。等满目标柱数,或者补一个未经计算的零值,都会掩盖真实结果。
当前 Worker 收到 EOS 后会清理解码器、关闭文件并通知完成,不会补算不足一个窗口的尾部 RMS。如果业务要求所有音频返回相同点数,还需要定义重采样或尾窗策略,并覆盖短音频、不同声道数和异常文件。
取消时返回的是已采集的部分数组,也可能为空;Dart 接口会对空数组抛异常。调用结束后,应用仍要判断拿到的是完整波形、部分结果还是错误。
Example 里也有一处连点竞态。两个选择请求都在等旧控制器释放,恢复执行后,就可能各自创建一个播放器。比较回调里的控制器引用只能防止旧数据上屏,已经失去引用的播放器却收不回来。
我让持有器在等待之前递增请求序号,并移走当前引用;清理结束后,仅序号仍匹配的请求可以创建控制器。退出页面同样递增序号,让等待中的选择失效。清理会依次尝试 stop、release 和 dispose,即使一步报错,也继续后面的操作,最后向调用者抛出首个错误。
测试时,我控制清理 Future 的完成时机,模拟多个选择同时等待:旧请求不再创建对象,最后一次选择只创建一个。退出取消等待、停止失败后继续释放,以及失败后重新选择也都有对应测试。这些用例检查的是页面控制器的归属;鸿蒙端是否回收文件和内存,仍要看运行采样。
4.2 进程内句柄自观测的目录流陷阱与权限边界
写 API 26 诊断模块时,我还遇到了句柄读取和 Profile 构建两个问题。
hdc shell 默认是受限 shell 用户,可以用 hidumper 查看进程内存,却会被 SELinux 阻止直接列举目标应用的句柄目录。我把巡检放进应用自己的原生模块,读取本进程的 /proc/self/fd 和符号链接,这样才能取得句柄信息。
不过,opendir("/proc/self/fd") 自己也会打开一个目录流 FD。遍历时,我用 dirfd 找到它并排除,否则每次都会把诊断器临时打开的句柄算进去。
构建问题来自旧脚手架:build-profile.json5 缺少 buildModeSet,执行 Profile 构建会报 Hvigor 配置错误。我在 app 下补齐 debug、profile、release,并让工程配置的 modelVersion 保持一致,例如都为 5.0.0,之后才完成 Profile 构建。
还有一个接入时要记住的时序:通道回执只表示停止请求已接收,Worker 随后才清理解码器和文件。800 毫秒强制终止是异常兜底,不能保证异常路径都回收完成。最终快照取于静置后,诊断器也没有直接统计 C++ 实例表,所以页面报告的是读到的 FD 和内存值,不是全部对象的销毁清单。
五、结论与可直接复用的建议
5.1 对列表预览的实际帮助
对于这个备忘录列表,补丁让常规停止、释放调用能通知鸿蒙提取器取消任务,EOS 到达后也能结束提取,不必等满目标柱数。静态缩略图还可以走不准备播放器的提取入口,不过这条扩展路径尚未单独运行验证。句柄和内存的观察范围见第二节。
5.2 在自己的项目中使用
💡 在应用的 pubspec.yaml 中加入下面的 Git 依赖,固定到已经公开的修复提交。社区原分支尚不含这份补丁,pub.dev 主包也不包含鸿蒙实现,只填写主包版本号还不够:
dependencies:
audio_waveforms:
git:
url: https://atomgit.com/abaoge/fluttertpc_audio_waveforms.git
ref: 15620ed675070aa4c22c321238a85059c546480d
鸿蒙宿主的 ohos/entry/src/main/module.json5 需要按目标设备设置 deviceTypes,例如 phone 或 tablet。本文使用 SDK API 26,其他版本需要另行验证。
提取和试听应用沙箱中的本地音频,不需要额外申请敏感权限。如果还要用 RecorderController 录音,则要在 requestPermissions 中声明 ohos.permission.MICROPHONE,并填写权限使用说明。
只取波形缩略图时,可以在一个函数里创建控制器、提取数组,再释放资源。下面的完整函数返回后,数组可用于自定义画布,也可按文件摘要缓存。3 秒是应用选择的等待期限,长录音需要按实际负载调整:
import 'package:audio_waveforms/audio_waveforms.dart';
Future<List<double>> loadMemoWaveform(String path) async {
final controller = PlayerController();
try {
return await controller
.extractWaveformData(path: path, noOfSamples: 80)
.timeout(const Duration(seconds: 3));
} finally {
try {
// timeout 只结束 Dart 的等待,仍需显式释放底层任务。
await controller.release();
} finally {
controller.dispose();
}
}
}
需要试听时,选中条目后调用 preparePlayer,再通过 startPlayer、pausePlayer 控制播放。页面只持有当前控制器,切换和退出时释放。连点按第四节的请求序号处理,创建对象和更新界面前都检查请求是否有效,避免几个等待中的点击各自创建播放器。
5.3 使用时保留这几个判断
- 长列表不必为每条语音常驻一个已准备好的控制器。列表态可以调用
extractWaveformData,把数组交给画布或波形组件;用户选中试听时再准备播放器。 - 长音频适合缓存波形数组。移除 renderQueue 后,解码不会再向这条队列积存整份 PCM,但数十分钟音频仍需要解码时间、CPU 和电量。可以按文件摘要保存首次提取的数组,供后续复用。
- 现有验证覆盖 Mate X7 折叠屏模拟器(五对 AB/BA 冷启动基准与单进程 144 轮连续压测)及华为畅享 100 Pro Max(YEW-AL80)真机 24 轮补充运行,音频为本地 m4a(AAC-LC),SDK 为 API 26。硬件解码功耗、超长录音长稳以及 Android、iOS 运行回归尚未覆盖。
公开 Example 提供了备忘录页面和新版诊断宿主(支持 3 秒超时与收到进度后取消,以及 --batches 连续多批压测),可以直接对照查看插件接法。接入自己的页面时,还要处理好连续选择的请求顺序。
小结
排查这个备忘录列表问题时,波形已经画出来、提取调用却迟迟不返回的现象,成了我顺着 Dart 控制器一路追到 Worker 停机握手和 C++ 解码器的起点。补上取消通知、零字节 EOS 收尾与跨线程上下文释放后,五对新条件基准里的 16 次完整提取与 8 次中途取消全部按期完成 🎉,单进程连续跑满 144 轮后音频句柄依然保持为零,总句柄恒定在 104;内存增量较原库大幅回落并在多批运行间形成回收波动。判断一个跨端音频能力有没有收拾干净,不能只看页面上画没画出波形,调用何时返回、文件何时关闭、连续多轮后的内存怎样波动,都得靠各自的实测记录来回答。
参考资料
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐

所有评论(0)