HarmonyOS 弦乐调音器开发实战 04：Flutter 页面如何通过 ArkTS 插件接入系统音频-三亩地-编程学习日记

这篇文章只讨论项目中的 Flutter 1.0.8 工程，不把它和前面几篇使用的原生 ArkTS 1.0.7 工程混在一起。页面由 Flutter 绘制，但隐私同意、麦克风权限、PCM 采集、音高检测和参考音播放仍然要落到 HarmonyOS 系统能力上。项目没有把系统 API 零散地塞进每一个页面，而是用一个 Dart 门面类和一个 ArkTS 插件建立边界：离散命令走MethodChannel，连续音频结果走EventChannel。

本文展示的通道名、方法名、采样参数和算法阈值都来自当前源码。本轮确实完成了 Flutter 静态分析、一个页面冒烟测试和 release HAP 构建；但是当前没有 HDC 设备，因此没有对新生成的最终包执行安装、启动、麦克风采集或真实乐器回归。下面会把“源码存在”“构建通过”和“实机验证”分别说明。

先明确本文对应的是 Flutter 1.0.8 工程

这个目录中同时保留了两套实现。根工程是 HarmonyOS Stage 模型的 ArkTS/ArkUI 应用，版本为 1.0.7；string_tuner_flutter才是本文分析的 Flutter/OHOS 工程，版本为 1.0.8。Flutter 工程的页面源码位于string_tuner_flutter/lib，HarmonyOS 插件位于string_tuner_flutter/ohos/entry/src/main/ets/plugins。

区分这两条工程线十分重要。2026-05-14 的早期截图属于原生 ArkTS 实现，2026-07-05 的截图属于 Flutter 调试运行。两批截图都早于本轮重新生成的 release HAP，不能拿旧截图证明最新包已经回归。本文使用 Flutter 截图，是为了说明当时页面和系统权限弹窗曾经运行，而不是把它包装成这次最终包的验收回执。

Flutter 页面已经包含首页、调音、历史、我的和曲库等入口。曲库页能够说明页面路由和数据渲染已经落地，但静态截图不能证明参考音真的从扬声器播放，也不能证明音色、时延或音量符合预期。

为什么 Flutter 页面不能直接承担系统音频生命周期

Flutter 擅长组织跨平台界面和状态，但 HarmonyOS 的隐私托管、运行时权限、AudioCapturer、AudioRenderer与Preferences都属于平台侧能力。如果页面直接拼接这些能力，会出现三个问题：第一，Dart 页面必须知道平台 API 的细节；第二，麦克风的创建、停止和释放容易散落到多个生命周期回调；第三，连续 PCM 数据如果按一次次方法调用返回，会产生不必要的请求与响应开销。

当前项目把职责切成三层：

Flutter 页面决定“现在是否需要实时音频”，并展示TunerFrame；
NativeTuner统一封装 Dart 到原生的调用和异常回退；
StringTunerPlugin持有 Ability 上下文、系统音频对象和事件出口。

这种分层并不意味着所有调音逻辑都放在 ArkTS。插件负责把 PCM 变成频率、清晰度、波形摘要和“频谱”摘要；Flutter 层再根据当前乐器、A4 参考频率和自动/手动模式选择目标弦，并计算音分与会话统计。边界清楚以后，页面不需要持有AudioCapturer，插件也不需要理解具体的卡片布局。

桥接总览：一条命令通道，一条事件通道

项目约定了两个完全一致的通道名：

string_tuner/native：方法通道，处理隐私确认、开始/停止采音、屏幕常亮、设置与历史持久化、参考音播放；
string_tuner/audio_events：事件通道，持续发送频率、清晰度、波形和摘要数组。

方法通道适合有明确返回值的离散动作，事件通道适合原生侧主动推送的连续状态。页面只在需要实时音频时订阅事件，停止时取消订阅并通知插件释放采音资源。

项目相对路径：string_tuner_flutter/lib/native_tuner.dart

class NativeTuner { NativeTuner._(); static const MethodChannel _method = MethodChannel('string_tuner/native'); static const EventChannel _events = EventChannel('string_tuner/audio_events');

项目中的启动方法保持原始返回结构：

项目相对路径：string_tuner_flutter/lib/native_tuner.dart

static Future<MicStartResult> startAudio() async { try { final Map<dynamic, dynamic>? value = await _method .invokeMapMethod<dynamic, dynamic>('startAudio', <String, Object>{ 'debugPrivacyFallback': kDebugMode, }); return MicStartResult.fromMap(value); } on MissingPluginException { return const MicStartResult(granted: false, wasAlreadyGranted: false); } on PlatformException { return const MicStartResult(granted: false, wasAlreadyGranted: false); } }

连续事件则由同一文件中的广播流转换成TunerFrame：

项目相对路径：string_tuner_flutter/lib/native_tuner.dart

static Stream<TunerFrame> audioFrames() { return _events.receiveBroadcastStream().map((Object? event) { if (event is Map) { return TunerFrame.fromMap(event); } return TunerFrame.empty(); }); }

这里不能把不同调用的回退能力混为一谈。NativeTuner的部分MethodChannel辅助方法会捕获平台调用异常并返回“未授权”等默认值；但上面的audioFrames()没有捕获MissingPluginException，TunerFrame.empty()只处理事件不是Map的情况。当前页面冒烟测试之所以没有订阅失败，是因为隐私同步回退为未接受后没有启动实时音频流；它既没有测试EventChannel缺失时的兜底，也没有验证原生插件。

Dart 侧只暴露业务需要的类型

NativeTuner没有把平台侧的复杂对象直接交给页面。隐私结果被转换成PrivacyConsentResult，麦克风启动结果被转换成MicStartResult，音频事件被转换成TunerFrame。页面关心的是accepted、granted、frequency和clarity，而不是平台权限返回数组或ArrayBuffer。

这种类型收口还能避免一个常见错误：把“已经授权”和“本次刚刚授权”混为一谈。插件返回wasAlreadyGranted，Flutter 页面据此决定是否显示“权限已经授权”的提示；无论哪一种情况，真正能否开始采音仍由granted决定。

项目相对路径：string_tuner_flutter/lib/native_tuner.dart

class MicStartResult { const MicStartResult({ required this.granted, required this.wasAlreadyGranted, }); factory MicStartResult.fromMap(Map<dynamic, dynamic>? value) { return MicStartResult( granted: value?['granted'] == true, wasAlreadyGranted: value?['wasAlreadyGranted'] == true, ); } final bool granted; final bool wasAlreadyGranted; }

ArkTS 插件如何注册并分发方法调用

StringTunerPlugin同时实现FlutterPlugin、AbilityAware、MethodCallHandler和StreamHandler。它在绑定 Flutter Engine 时创建两个通道，在绑定 Ability 时取得UIAbilityContext。后者是隐私接口、权限请求和窗口控制的必要上下文。