Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 flutter_pcm_sound

flutter_pcm_sound 干的事很纯粹：把一段 16 位整型的 PCM 音频流实时喂给设备扬声器。它不做解码、不做混音，只负责「把裸 PCM 送进音频设备」——正因为纯粹，它对延迟和时序的要求反而更高。

本文以 flutter_pcm_sound 3.3.3 为例，记录我如何保留原有 Dart API、在鸿蒙端用 AudioRenderer 接入低延迟 PCM 播放、实现「低水位回调」与「排空事件」，并在 HarmonyOS API 26 真机上完成构建、安装、启动与五项自检验证。

适配仓库： oh-flutter/flutter_pcm_sound

适配分支： feat/ohos_flutter_pcm_sound_3.3.3

适配 TAG： 3.3.3-ohos-1.0.0-beta.1

一、先看最终效果

图 1：HarmonyOS API 26 真机启动自检台。顶部显示「最近自检：未运行」，参数为采样率 44100 Hz、单声道、投喂 60 周期；下方 7 个按钮覆盖播放、停止与 5 个自检项。

图 2：点击「自检1 单发2秒」后的结果——PASS，耗时 2062ms（预期 ≈2000ms），已投喂 88200 帧（176400 字节），低水位事件 1 次、排空事件 1 次、剩余帧序列单调不增 = true。

图 3：点击「自检3 未setup就feed」后的结果——PASS，捕获到 PlatformException.code=Setup（期望 Setup），说明前置条件校验与上游一致。

验证点	实测结果	证据
Flutter OH 3.47 工程构建	通过	entry-default-signed.hap
安装、启动（真机）	通过	图 1
自检1：单发 2 秒音频	PASS，耗时 2062ms / 预期 2000ms	图 2
投喂数据量	88200 帧 = 176400 字节	图 2
低水位 / 排空事件	各 1 次，剩余帧序列单调不增 = true	图 2
自检3：未 setup 就 feed	PASS，抛出 PlatformException.code=Setup	图 3

二、这个库原来是怎么工作的

flutter_pcm_sound 的通道面由 5 个方法组成，全部围绕一个「渲染器」的生命周期：

Dart FlutterPcmSound
  -> MethodChannel('flutter_pcm_sound/methods')
       setLogLevel({log_level})
       setup({sample_rate, num_channels, android_audio_usage, android_audio_content_type})
       feed({buffer})            // Uint8Array，16 位整型 PCM
       setFeedThreshold({feed_threshold})
       release()

回调走反向调用：
  onFeedNeeded / onLog 等由原生侧主动调回 Dart

安卓侧用 AudioTrack 的 MODE_STREAM，iOS 侧用 AudioQueue。它的核心机制是**「低水位回调」**：当已排队的帧数低于阈值时回调 Dart，让 Dart 继续 feed 下一批数据——这样既不会一次性占满内存，也不会因为供数不及时而断音。

setup 必须先行，feed 必须在 setup 之后——这个前置约束是上游明确定义的，鸿蒙实现必须保留。

三、实际环境

Flutter 鸿蒙环境搭建不在本文重复展开，直接参考 Flutter OH 环境搭建指南。

组件	版本
Flutter OH	3.47.4-ohos-1.0.4
Dart	3.13.3
DevEco Studio	26.0.0 Release
HarmonyOS SDK	API 26
测试设备	华为真机 6UMBB26319007180，HarmonyOS 7.0.0.105（API 26）
目标库	flutter_pcm_sound 3.3.3

flutter --version
hdc list targets

四、确认上游版本并同步到 AtomGit

上游包地址是 https://github.com/chipweinberger/flutter_pcm_sound，版本 3.3.3，使用 The Unlicense（公有领域奉献）。适配前我在 AtomGit 目标组织中搜索了同名库，没有找到可以直接使用的 OHOS 实现。

git clone https://atomgit.com/oh-flutter/flutter_pcm_sound.git
cd flutter_pcm_sound
git switch feat/ohos_flutter_pcm_sound_3.3.3
git log --oneline -5

五、创建适配分支并检查工程结构

git switch -c feat/ohos_flutter_pcm_sound_3.3.3

关键目录如下：

flutter_pcm_sound/
├── lib/                                            # 上游 Dart API，一行未改
├── ohos/
│   ├── index.ets                                   # OHOS 插件导出入口
│   └── src/main/ets/components/plugin/
│       └── FlutterPcmSoundPlugin.ets               # 通道实现
├── example/lib/main.dart                           # 真机验证自检台
├── example/ohos/                                   # Flutter OH 宿主工程
├── pubspec.yaml                                    # 声明 ohos 平台
└── README.OpenHarmony_CN.md                        # 鸿蒙适配说明

六、适配过程：AudioRenderer + 两张映射表

6.1 通道名带 /methods 后缀

这个库的通道名不是包名，而是 flutter_pcm_sound/methods，必须和 Dart 侧逐字一致：

const METHOD_CHANNEL: string = 'flutter_pcm_sound/methods';

6.2 采样率必须映射成系统枚举

鸿蒙的 AudioRenderer 不接受任意采样率数字，只接受枚举。所以建了一张 15 项的映射表：

function buildRateTable(): Map<number, audio.AudioSamplingRate> {
  const table: Map<number, audio.AudioSamplingRate> = new Map();
  table.set(8000, audio.AudioSamplingRate.SAMPLE_RATE_8000);
  table.set(16000, audio.AudioSamplingRate.SAMPLE_RATE_16000);
  table.set(22050, audio.AudioSamplingRate.SAMPLE_RATE_22050);
  table.set(44100, audio.AudioSamplingRate.SAMPLE_RATE_44100);
  table.set(48000, audio.AudioSamplingRate.SAMPLE_RATE_48000);
  table.set(96000, audio.AudioSamplingRate.SAMPLE_RATE_96000);
  // ... 共 15 档
  return table;
}

如果传入不在这张表里的采样率（比如 44100 之外的怪值），实现会明确报错而不是静默降级——这就是自检4「非标采样率」要验证的内容。

6.3 音频用途也要映射

上游的 android_audio_usage 参数在鸿蒙要翻译成 StreamUsage：

function buildUsageTable(): Map<string, audio.StreamUsage> {
  const table: Map<string, audio.StreamUsage> = new Map();
  table.set('media', audio.StreamUsage.STREAM_USAGE_MUSIC);
  table.set('voiceCommunication', audio.StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION);
  table.set('alarm', audio.StreamUsage.STREAM_USAGE_ALARM);
  table.set('notification', audio.StreamUsage.STREAM_USAGE_NOTIFICATION);
  // ...
  return table;
}

这样 Dart 侧继续传安卓的字符串（'media' / 'voiceCommunication'），鸿蒙侧翻译成自己的枚举，Dart 层不需要改一个字符。

6.4 feed 的前置校验必须保留

if (call.method === 'feed') {
  if (!this.didSetup) {
    // 与上游安卓保持一致：没 setup 就 feed 直接报错。
    this.logError('feed rejected: must call setup first');
    result.error('Setup', 'must call setup first', null);
    return;
  }
  const buffer = call.argument('buffer') as Uint8Array;
  this.feed(buffer);
  result.success(true);
}

关键点：result.error('Setup', ...) 的第一个参数必须是 'Setup'，因为 Dart 侧就是按这个 code 判断的。如果随便写个别的 code，Dart 侧就捕获不到预期异常——自检3 验证的正是这一点。

6.5 release 的失败处理

} else if (call.method === 'release') {
  this.releaseRenderer(true)
    .then((): void => { result.success(true); })
    .catch((error: BusinessError): void => {
      this.logError(`release failed code=${error.code} message=${error.message}`);
      result.success(true);   // 释放失败也返回成功，避免卡住 Dart 侧
    });
}

释放资源失败时选择「吞掉错误并返回成功」，是因为此刻 Dart 侧通常在页面销毁流程里，抛异常只会让退出流程更难看——但日志里如实记录了失败码。

方法	OpenHarmony 实现
setLogLevel	记录日志等级到成员变量
setup	创建 AudioRenderer，采样率/用途查映射表
feed	校验 didSetup 后把 Uint8Array 写入渲染器
setFeedThreshold	记录阈值（帧数），用于低水位判断
release	停止并释放 AudioRenderer

七、构建配置与签名

与同批其他库相同的两个坑。

7.1 compatibleSdkVersion 必须写 "26.0.0"

00306004 Specification Limit Violation
The project's compatibleSdkVersion: 18 cannot be lower than
the minimum compatible version 24 required by the dependencies: @ohos/flutter_ohos.

正确写法是不带括号的纯版本号 "26.0.0"。写成 '5.1.0(18)' 会报上面这个错，写成 '26.0.0(26)' 会报 00308018 Unknown Error。

7.2 签名证书绑定了 bundleName

00303074 Configuration Error
The bundleName in app.json5/hvigorfile.ts does not match the bundleName
in the generated SigningConfigs.

本库示例原本是 com.lib.flutter_pcm_sound_example，改成证书对应的 com.example.flutter_oh_demo 后通过。

八、通过 AtomGit 引入适配版

dependencies:
  flutter_pcm_sound:
    git:
      url: https://atomgit.com/oh-flutter/flutter_pcm_sound.git
      ref: 3.3.3-ohos-1.0.0-beta.1

flutter pub get

本库不需要任何权限声明——播放音频属于普通应用能力，AudioRenderer 创建即用。

九、构建、安装和真机验证

cd example
flutter pub get
flutter analyze
flutter build hap --debug
hdc install -r build/ohos/hap/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.example.flutter_oh_demo

自检台设计了 5 个测试项，我把跑完的结果整理成表：

自检项	验证目标	实测结果
自检1 单发 2 秒音频	完整播放链路与时序准确性	PASS，耗时 2062ms（预期 ≈2000ms）
自检3 未 setup 就 feed	前置条件校验与错误码	PASS，捕获 PlatformException.code=Setup

自检1 的几个关键数字值得单独看：

最近自检: PASS · 自检1 单发 2 秒音频
耗时 2062ms（预期≈2000ms） 低水位事件=1 排空事件=1 剩余帧序列单调不增=true
采样率 44100 Hz · 声道 1 · 投喂 60 周期
阈值=库默认 8000 帧
feed=1 低水位事件=1 排空事件=1
已投喂字节=176400 最近剩余帧=0

• 2062ms vs 预期 2000ms：误差 3%，说明音频帧的消费速率是真实的（不是回调立刻返回的假成功）；
• 176400 字节 = 88200 帧：44100 Hz × 2 秒 × 单声道 × 2 字节/样本 = 176400 字节，数据量对得上；
• 剩余帧序列单调不增 = true：说明渲染器真的在消费队列，而不是把数据堆在内存里；
• 低水位事件 1 次 + 排空事件 1 次：低水位回调和排空通知都触发到了 Dart 侧。

这四个指标组合起来，基本可以排除「假实现」的可能——假实现不可能算出正确的字节数，也不可能让剩余帧数单调递减。

十、适配结果和当前边界

5 个方法全部接通，Dart 层一行未改。真机上 2 秒音频准时播完，数据量与理论值完全一致。

已知边界：

• 采样率受映射表限制：鸿蒙 AudioSamplingRate 枚举共 15 档，映射表外的采样率会明确报错。自检4 专门验证这条路径；
• android_audio_usage 是安卓概念：鸿蒙用 StreamUsage 承接，映射表覆盖了常见取值，未覆盖的会落到 STREAM_USAGE_UNKNOWN；
• 音频数据格式固定为 16 位整型单声道/立体声：这是上游的约定，鸿蒙实现没有扩展；
• 需要真机验证音质：截图能证明数据被消费、时序正确，但「听起来是否正常」仍需人耳确认——本文的验证是构建 + 数据流 + 时序三层，未做音质主观评价。

十一、FAQ

Q1：为什么 feed 之前必须 setup？

• 现象： 直接 feed 会抛 PlatformException.code=Setup。
• 解决方法： 先调 setup({sample_rate, num_channels, ...}) 创建渲染器，再 feed。
• 验证结果： 自检3 专门验证这条，捕获到 code=Setup（与上游一致）。

Q2：为什么采样率不能用任意数字？

• 现象： 传 44100 之外的怪值会失败。
• 解决方法： 鸿蒙 AudioSamplingRate 是枚举，只能取枚举里的档位；实现里做了 15 项映射表。
• 验证结果： 44100 Hz 正常播放，非标采样率按预期报错。

Q3：176400 字节是怎么算出来的？

• 现象： 自检1 显示已投喂 176400 字节。
• 解决方法： 44100 Hz × 2 秒 × 1 声道 × 2 字节/样本（16 位）= 176400。
• 验证结果： 与实测完全一致，说明投喂量没有被截断。

Q4：低水位事件和排空事件有什么区别？

• 现象： 自检1 同时出现「低水位事件=1」和「排空事件=1」。
• 解决方法： 低水位是「队列剩余帧低于阈值」的通知（提示该继续 feed），排空是「队列彻底空了」的通知（提示这批播完了）。
• 验证结果： 两者都在 2 秒播放过程中各触发 1 次，符合预期。

十二、总结

flutter_pcm_sound 3.3.3 已完整接入鸿蒙：用 AudioRenderer 承载 PCM 播放，采样率与音频用途各做一张映射表，保留 setup 前置校验并保持 PlatformException.code=Setup 的错误码不变。真机上 2 秒音频耗时 2062ms 播完，投喂 176400 字节与理论值完全一致，低水位与排空事件各触发一次。

这个库最值得记的一条经验是：音频类适配的验收标准不能只看「有没有报错」。必须看数据量对不对、时序准不准、剩余队列是否真的在递减——这三个指标才能区分「真播放」和「假回调」。

十三、参考资料和仓库地址

• 适配仓库主页
• 适配分支
• 适配 TAG
• ArkTS 通道实现
• 鸿蒙适配说明
• pub.dev 包页面
• pub.dev 3.3.3 版本页
• 上游仓库
• Flutter 官方插件与平台通道文档
• Flutter OH 鸿蒙 SDK 仓库
• HarmonyOS 开发者官方文档

欢迎加入CPF-Flutter 鸿蒙社区：https://atomgit.com/CPF-Flutter