Flutter `audio_service` 在鸿蒙端的后台音频服务适配实践

摘要

这篇指南主要介绍如何将 Flutter 生态中广泛使用的后台音频播放插件 audio_service 适配到 OpenHarmony 平台。内容从环境搭建、原理分析，到完整代码实现和调试优化，覆盖了整个流程，希望能帮助开发者解决在鸿蒙系统上实现后台音频播放与控制的关键问题。

第一章：引言

1.1 背景与挑战

随着鸿蒙（HarmonyOS / OpenHarmony）生态的快速发展，很多 Flutter 开发者希望自己的应用也能顺畅运行在鸿蒙设备上。audio_service 是 Flutter 中用来管理后台音频播放、锁屏控件、通知栏交互以及系统媒体中心集成的核心插件，但其官方实现只支持 Android 和 iOS，在鸿蒙上缺少对应的原生支持。

主要的挑战集中在以下几点：

平台接口缺失 ：鸿蒙没有与 Android MediaBrowserService 完全对应的后台服务框架，需要自己搭建类似的能力。
通信机制差异：Flutter 插件通过 MethodChannel 和 EventChannel 与原生平台通信，这套机制需要在鸿蒙端重新实现。
音频生命周期管理：鸿蒙的后台任务管理机制和 Android 不同，要确保音频服务在后台不会被意外回收。

1.2 适配目标

这次适配的核心目标是构建一个名为 audio_service_ohos_adapter 的鸿蒙平台插件，实现 audio_service 接口的关键功能，让 Flutter 应用在鸿蒙设备上也能稳定运行。具体来说，需要支持：

应用退到后台或锁屏后，音频继续播放。
接收来自系统通知栏、耳机按键或车载系统的播放控制指令。
在系统媒体中心显示并实时更新播放信息（如标题、歌手、播放进度）。

第二章：技术分析与准备工作

2.1 Flutter 插件架构回顾

audio_service 采用标准的 Flutter 插件架构：

Dart 层 (lib/)：定义统一的 API 接口（如 AudioService）以及数据模型（如 MediaItem、AudioProcessingState）。
平台层 (android/、ios/)：实现平台相关的后台服务、音频播放引擎及系统媒体集成。通过 MethodChannel 接收 Dart 端的指令，并通过 EventChannel 向 Dart 端发送状态更新。

2.2 鸿蒙平台关键技术分析

适配过程中需要重点理解以下鸿蒙特性：

ServiceAbility ：鸿蒙的后台服务组件，可以作为音频服务的载体。它支持通过 IRemoteObject 进行跨进程通信（虽然 Flutter 插件一般跑在同一个进程内）。
CommonEvent ：系统公共事件，可以用来监听耳机按键、蓝牙设备连接等全局事件，相当于 Android 的 BroadcastReceiver。
AVSession（API Version 9+）：媒体会话控制器，是与系统媒体中心以及外部控制设备（如耳机、手表）交互的核心。它负责管理播放状态、媒体元数据，并分发控制命令。
AudioManager：用于管理音频焦点、输出设备等。

2.3 开发环境配置

首先确保你的开发环境满足以下条件：

bash 复制代码

# 1. 检查基础环境
flutter --version
# 建议 Flutter 3.13.0 或更高版本（稳定渠道）
dart --version
# 建议 Dart 3.1.0 或更高版本

# 2. 启用 OpenHarmony 桌面支持（目前鸿蒙应用开发主要依赖此模式）
flutter config --enable-ohos-desktop

# 3. 安装鸿蒙开发工具链（DevEco Studio、SDK），并确保 `ohos` 命令可用
ohos --version

2.4 创建适配项目

bash 复制代码

# 创建工作目录
mkdir flutter_audio_service_ohos_adaptation
cd flutter_audio_service_ohos_adaptation

# 创建 Flutter 插件项目，类型选 plugin，并指定 ohos 平台
flutter create --template=plugin --platforms=ohos audio_service_ohos_adapter

cd audio_service_ohos_adapter

# 添加对原始 audio_service 插件的依赖，便于分析其 API
flutter pub add audio_service

第三章：插件目录结构设计

3.1 原始插件结构分析

复制代码

audio_service/
├── lib/                 # Dart 公共接口层
│   ├── audio_service.dart
│   ├── android.dart    # Android 特定接口（后续需替换或继承）
│   └── ...
├── android/            # Android 原生实现
└── ios/                # iOS 原生实现

3.2 鸿蒙适配插件的目标结构

复制代码

audio_service_ohos_adapter/
├── lib/
│   ├── audio_service_ohos.dart      # 主入口，导出适配后的接口
│   └── src/
│       └── ohos_bridge.dart         # 与鸿蒙原生层的桥接实现
├── ohos/                            # 鸿蒙原生实现（核心部分）
│   ├── entry/
│   │   └── src/
│   │       ├── main/
│   │       │   ├── ets/             # ArkTS 代码目录
│   │       │   │   ├── AudioServiceAbility.ts     # 后台服务 Ability
│   │       │   │   ├── AVSessionManager.ts        # 媒体会话管理
│   │       │   │   ├── MethodChannelHandler.ts    # 方法通道处理
│   │       │   │   └── EventChannelEmitter.ts     # 事件通道发射器
│   │       │   └── resources/       # 资源配置（如通知图标）
│   │       └── module.json5         # 模块配置文件
│   └── build.gradle                 # 鸿蒙模块构建配置
├── pubspec.yaml                     # 插件依赖声明
└── example/                         # 示例应用，用于测试验证

第四章：核心代码实现

4.1 Dart 层桥接实现 (`lib/src/ohos_bridge.dart`)

dart 复制代码

import 'dart:async';
import 'package:audio_service/audio_service.dart';
import 'package:flutter/services.dart';

/// 鸿蒙平台专用的 `AudioService` 实现
class AudioServiceOhos extends AudioServiceInterface {
  static const MethodChannel _methodChannel = MethodChannel(
      'xyz.yourcompany.audio_service_ohos/adapter');
  static const EventChannel _eventChannel = EventChannel(
      'xyz.yourcompany.audio_service_ohos/events');

  Stream<AudioProcessingState>? _processingStateStream;
  Stream<Map<String, dynamic>>? _customEventStream;

  @override
  Future<void> configure({
    AudioTaskHandler? androidTaskHandler, // 参数名保持兼容，实际在鸿蒙中另有用途
    // ... 其他参数
  }) async {
    // 启动鸿蒙后台服务，并传递配置参数
    try {
      await _methodChannel.invokeMethod('configure', {
        'params': {
          // 序列化配置参数并传递
        }
      });
      // 初始化事件流监听
      _setupEventStreams();
    } on PlatformException catch (e) {
      throw Exception('鸿蒙音频服务配置失败: ${e.message}');
    }
  }

  @override
  Future<void> start() async {
    await _methodChannel.invokeMethod('start');
  }

  @override
  Stream<AudioProcessingState> get processingStateStream {
    _processingStateStream ??= _eventChannel
        .receiveBroadcastStream('processing_state')
        .map((event) => _parseProcessingState(event));
    return _processingStateStream!;
  }

  // ... 实现其他必要方法，例如 setMediaItem、play、pause、stop 等
  // 它们内部都通过 _methodChannel.invokeMethod 调用鸿蒙原生方法

  void _setupEventStreams() {
    // 解析从鸿蒙原生层发来的事件，并转换为 Dart Stream
  }

  AudioProcessingState _parseProcessingState(dynamic state) {
    // 将原生状态字符串转换为枚举值
    switch (state) {
      case 'connecting':
        return AudioProcessingState.connecting;
      case 'ready':
        return AudioProcessingState.ready;
      case 'buffering':
        return AudioProcessingState.buffering;
      case 'completed':
        return AudioProcessingState.completed;
      default:
        return AudioProcessingState.none;
    }
  }
}

4.2 鸿蒙原生层 - 服务 Ability (`AudioServiceAbility.ts`)

typescript 复制代码

// entry/src/main/ets/AudioServiceAbility.ts
import Ability from '@ohos.app.ability.Ability';
import Want from '@ohos.app.ability.Want';
import window from '@ohos.window';
import audio from '@ohos.multimedia.audio';
import AVSession from '@ohos.multimedia.avsession';
import commonEvent from '@ohos.commonEvent';
import { MethodChannelHandler } from './MethodChannelHandler';

export default class AudioServiceAbility extends Ability {
  private avSession: AVSession | null = null;
  private audioPlayer: audio.AudioPlayer | null = null;
  private methodChannelHandler: MethodChannelHandler;

  onCreate(want: Want, launchParam: Ability.LaunchParam) {
    console.info('AudioServiceAbility onCreate');
    this.methodChannelHandler = new MethodChannelHandler(this.context);
    this.methodChannelHandler.setServiceAbility(this);
    this.initAVSession();
    this.subscribeCommonEvents();
  }

  private async initAVSession() {
    // 1. 创建 AVSession
    try {
      this.avSession = await AVSession.createAVSession(this.context, 'FlutterAudioPlayer', 'audio');
      console.info('AVSession 创建成功');

      // 2. 设置会话激活/失活回调
      this.avSession.on('activate', () => { /* 会话被激活，例如连接车载系统 */ });
      this.avSession.on('deactivate', () => { /* 会话失活 */ });

      // 3. 监听控制命令
      this.avSession.on('controlCommand', (command: AVSession.AVControlCommand) => {
        this.handleControlCommand(command);
      });

      // 4. 设置初始媒体信息
      let metadata: AVSession.AVMetadata = {
        assetId: 'default',
        title: '未在播放',
        artist: '',
        duration: 0
      };
      await this.avSession.setAVMetadata(metadata);
    } catch (err) {
      console.error(`AVSession 初始化失败. Code: ${err.code}, message: ${err.message}`);
    }
  }

  private handleControlCommand(command: AVSession.AVControlCommand) {
    // 处理来自系统或外部的播放控制命令
    const cmd = command.command;
    switch (cmd) {
      case 'play':
        this.methodChannelHandler.invokeToDart('onPlay');
        break;
      case 'pause':
        this.methodChannelHandler.invokeToDart('onPause');
        break;
      case 'playFromMediaId':
        const mediaId = command.parameters?.mediaId;
        // 转发给 Dart 层处理
        break;
      // ... 其他命令
    }
  }

  // 供 MethodChannel 调用的方法
  public async setMediaItem(mediaItem: any): Promise<void> {
    if (this.avSession) {
      const metadata: AVSession.AVMetadata = {
        assetId: mediaItem['id'],
        title: mediaItem['title'],
        artist: mediaItem['artist'] ?? '',
        duration: mediaItem['duration'] ?? 0,
        // 可扩展更多属性，如专辑封面 URI
      };
      await this.avSession.setAVMetadata(metadata);
      // 更新播放状态为"正在播放"
      await this.avSession.setAVPlaybackState({ state: AVSession.PlaybackState.PLAYBACK_STATE_PLAYING });
    }
  }

  public async startPlayback(audioUri: string): Promise<void> {
    // 使用鸿蒙 audio API 初始化播放器并开始播放
    try {
      this.audioPlayer = await audio.createAudioPlayer();
      // ... 配置播放器参数
      await this.audioPlayer.reset();
      await this.audioPlayer.setSource(audio.AudioSource.createSource(audioUri));
      await this.audioPlayer.play();
      // 通过 EventChannel 向 Dart 发送状态更新
      this.methodChannelHandler.emitEvent('processing_state', 'playing');
    } catch (err) {
      this.methodChannelHandler.emitEvent('error', { code: err.code, message: err.message });
    }
  }

  private subscribeCommonEvents() {
    // 订阅耳机插拔事件
    commonEvent.subscribe('usual.event.HEADSET_PLUG', (err, data) => {
      if (err) { return; }
      const plugged = data?.parameters?.state;
      // 处理耳机插拔逻辑
    });
  }

  onDestroy() {
    console.info('AudioServiceAbility onDestroy');
    this.avSession?.destroy();
    this.audioPlayer?.release();
    commonEvent.unsubscribeAll();
  }
}

4.3 鸿蒙原生层 - MethodChannel 处理器

typescript 复制代码

// entry/src/main/ets/MethodChannelHandler.ts
import { AudioServiceAbility } from './AudioServiceAbility';
import { EventChannelEmitter } from './EventChannelEmitter';

export class MethodChannelHandler {
  private context: any; // AbilityContext
  private serviceAbility: AudioServiceAbility | null = null;
  private eventEmitter: EventChannelEmitter;

  constructor(context: any) {
    this.context = context;
    this.eventEmitter = new EventChannelEmitter(context);
    this.registerMethodChannel();
  }

  private registerMethodChannel() {
    // 注册方法通道（此处为概念性实现，假设存在全局的 ohosFlutterBridge 对象）
    if (globalThis.ohosFlutterBridge) {
      globalThis.ohosFlutterBridge.registerMethodCallHandler(
        'xyz.yourcompany.audio_service_ohos/adapter',
        this.handleMethodCall.bind(this)
      );
    }
  }

  private async handleMethodCall(call: { method: string; arguments: any }): Promise<any> {
    console.info(`收到方法调用: ${call.method}`);
    switch (call.method) {
      case 'configure':
        // 存储配置
        return { result: 'configured' };
      case 'start':
        // 确保服务已启动
        return { result: 'started' };
      case 'setMediaItem':
        await this.serviceAbility?.setMediaItem(call.arguments);
        return { result: 'success' };
      case 'play':
        await this.serviceAbility?.startPlayback(call.arguments['uri']);
        return { result: 'playback_started' };
      case 'pause':
        await this.serviceAbility?.pausePlayback();
        return { result: 'paused' };
      default:
        console.warn(`未知方法: ${call.method}`);
        throw new Error(`方法 '${call.method}' 尚未实现`);
    }
  }

  public setServiceAbility(ability: AudioServiceAbility) {
    this.serviceAbility = ability;
  }

  // 供原生层主动向 Dart 层发送事件
  public emitEvent(eventName: string, data: any) {
    this.eventEmitter.emit(eventName, data);
  }

  // 调用 Dart 端定义的"客户端"方法（模拟）
  public invokeToDart(method: string, args?: any) {
    if (globalThis.ohosFlutterBridge) {
      globalThis.ohosFlutterBridge.invokeMethod(`audio_service.client.${method}`, args);
    }
  }
}

第五章：集成、调试与性能优化

5.1 集成步骤

配置 pubspec.yaml：

yaml 复制代码

dependencies:
  audio_service: ^1.0.0 # 保留原插件，用于接口
  audio_service_ohos_adapter:
    path: ../path/to/your/adapter

在代码中按条件导入适配器：

dart 复制代码

import 'package:audio_service/audio_service.dart';
import 'package:audio_service_ohos_adapter/audio_service_ohos_adapter.dart'
  if (dart.library.io) 'package:audio_service/audio_service.dart' as platform;

// 初始化时根据平台判断
if (Platform.isOHOS) {
  // 使用 audio_service_ohos_adapter 提供的启动方法
} else {
  await AudioService.configure(...); // 使用原版
}

配置鸿蒙模块权限 (module.json5)：

json 复制代码

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // 保持后台运行
      },
      {
        "name": "ohos.permission.MICROPHONE" // 如需录音
      },
      {
        "name": "ohos.permission.USE_BLUETOOTH" // 蓝牙音频设备
      }
    ],
    "abilities": [
      {
        "name": "AudioServiceAbility",
        "type": "service",
        "backgroundModes": ["audioPlayback"] // 声明音频播放后台模式
      }
    ]
  }
}

5.2 调试技巧

日志追踪 ：在 Dart 和 ArkTS 代码的关键路径添加详细日志，使用鸿蒙的 hilog 命令或 DevEco Studio 的日志面板查看输出。
检查 AVSession 状态 ：通过 dumpsys avsession（或鸿蒙对应的命令）在终端检查媒体会话是否被正确创建和激活。
模拟控制命令 ：可以编写简单的测试脚本，通过鸿蒙的 avsession 命令行工具或测试应用向服务发送控制命令，验证通信是否畅通。

5.3 性能优化建议

后台保活 ：
- 合理使用 backgroundModes 和 KEEP_BACKGROUND_RUNNING 权限。
- 在 AudioServiceAbility 的 onBackground 回调中，尝试申请一个短暂的 延迟挂起 令牌，以便完成关键的播放操作。
资源管理 ：
- AudioPlayer 对象在不使用时及时调用 release() 释放资源。
- 图片等资源尽量使用 URI 引用，避免直接加载到内存，尤其在通知栏更新时要注意内存占用。
通信效率 ：
- 对频繁通过 MethodChannel 传递的数据（比如播放进度）进行节流，或者改用更高效的 EventChannel 流。
- 尽量合并多个状态更新，减少跨语言边界的调用次数。

第六章：总结与展望

6.1 成果总结

本文详细介绍了将 Flutter audio_service 插件适配到 OpenHarmony 平台的完整过程。通过构建独立的 audio_service_ohos_adapter 插件，我们实现了：

架构映射 ：成功将 Android 的 Service + MediaSession 架构映射到鸿蒙的 ServiceAbility + AVSession 架构。
功能闭环：完成了后台播放、系统控件交互、状态同步等核心功能的基础实现。
跨平台兼容：提供了条件导入的方案，使得 Flutter 应用能够无缝兼容 Android、iOS 和鸿蒙平台。

6.2 遇到的挑战与解决思路

API 差异 ：鸿蒙的 AVSession API 较新，且与 Android MediaSession 不完全一致。我们的解决方案是封装一个兼容层，将 audio_service 的抽象模型转换成鸿蒙 API 能理解的格式。
Flutter 鸿蒙引擎成熟度：目前 Flutter for OHOS 仍在快速发展中，插件通道的稳定性和功能可能还有局限。需要持续关注引擎更新，必要时向开源社区提交补丁。

6.3 未来展望

功能完善：进一步适配更高级的功能，比如音频焦点管理、精确的播放队列、歌词同步等。
生态推广 ：将适配后的插件提交到 Pub.dev，并贡献给 audio_service 社区，探讨将其作为官方多平台支持一部分的可能性。
性能基准测试：在真实鸿蒙设备上进行全面的性能与功耗测试，并与 Android 平台对比，为进一步优化提供方向。

通过这次适配实践，我们不仅解决了具体的技术问题，也为 Flutter 生态在鸿蒙平台上的拓展提供了可复用的路径和经验。随着鸿蒙系统的普及以及 Flutter 对其支持的不断完善，这类跨平台适配工作会变得越来越重要。

Flutter `audio_service` 在鸿蒙端的后台音频服务适配实践