插件介绍

flutter_audioplayers 是一个功能强大的 Flutter 音频播放插件，支持在多种平台上同时播放多个音频文件。该插件提供了简单易用的 API，支持本地文件、网络 URL、字节流等多种音频源，并提供了丰富的播放控制功能。

在 HarmonyOS 平台上，flutter_audioplayers 已经进行了专门适配，允许开发者在鸿蒙应用中轻松实现音频播放功能，包括：

• 支持多种音频源（网络 URL、本地文件、字节流）
• 完整的播放控制（播放、暂停、停止、跳转）
• 音量和播放速率调节
• 音频上下文配置
• 后台播放支持

安装与配置

1. 添加依赖

由于这是适配 HarmonyOS 的自定义修改版本，需要通过 Git 形式引入依赖。在项目的 pubspec.yaml 文件中添加以下配置：

dependencies:
  flutter:
    sdk: flutter
  audioplayers:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_audioplayers.git
      path: packages/audioplayers

然后执行以下命令获取依赖：

flutter pub get

2. 配置权限

在 HarmonyOS 平台上使用音频播放功能，需要配置相应的权限。

2.1 修改 module.json5

打开 entry/src/main/module.json5 文件，添加后台播放权限：

{
  "abilities": [
    {
      "backgroundModes": [
        "audioPlayback"
      ]
    }
  ],
  "requestPermissions": [
    {
      "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
      "reason": "$string:background_running_reason",
      "usedScene": {
        "abilities": [
          "EntryAbility"
        ],
        "when": "inuse"
      }
    }
  ]
}

2.2 添加权限说明

打开 entry/src/main/resources/base/element/string.json 文件，添加权限申请的原因：

{
  "string": [
    {
      "name": "background_running_reason",
      "value": "需要后台运行权限以支持音频后台播放"
    }
  ]
}

API 使用示例

1. 基本用法

import 'package:audioplayers/audioplayers.dart';

// 创建音频播放器实例
final player = AudioPlayer();

// 播放网络音频
await player.play(UrlSource('https://example.com/audio.mp3'));

// 暂停播放
await player.pause();

// 恢复播放
await player.resume();

// 停止播放
await player.stop();

// 释放资源
await player.dispose();

2. 播放本地文件

// 播放本地资产文件
await player.play(AssetSource('audio/local_song.mp3'));

// 播放本地文件系统中的文件
await player.play(DeviceFileSource('/path/to/local/file.mp3'));

3. 播放字节流

// 从字节流播放音频
Uint8List audioBytes = /* 从某处获取音频字节数据 */;
await player.play(BytesSource(audioBytes));

4. 高级控制

// 设置音量（0.0 到 1.0）
await player.setVolume(0.7);

// 设置播放速率（0.5 到 2.0）
await player.setPlaybackRate(1.2);

// 跳转到指定位置（毫秒）
await player.seek(const Duration(seconds: 30));

// 获取音频总时长
Duration? duration = await player.getDuration();

// 获取当前播放位置
Duration? position = await player.getCurrentPosition();

5. 音频上下文配置

// 配置音频上下文
await player.setAudioContext(
  AudioContext(
    iOS: AudioContextIOS(
      category: AVAudioSessionCategory.playback,
      options: [
        AVAudioSessionOptions.mixWithOthers,
      ],
    ),
    android: AudioContextAndroid(
      isSpeakerphoneOn: true,
      stayAwake: true,
      contentType: AndroidContentType.music,
      usageType: AndroidUsageType.media,
      audioFocus: AndroidAudioFocus.gain,
    ),
  ),
);

6. 监听播放状态

// 监听播放完成事件
player.onPlayerComplete.listen((event) {
  print('播放完成');
});

// 监听播放位置变化
player.onPositionChanged.listen((position) {
  print('当前位置: $position');
});

// 监听播放器状态变化
player.onPlayerStateChanged.listen((state) {
  print('播放器状态: $state');
});

支持的 API 列表

API 方法	描述	鸿蒙支持情况
play	播放音频	yes
pause	暂停播放	yes
resume	恢复播放	yes
stop	停止播放	yes
seek	跳转到指定位置	yes
setVolume	设置音量	yes
setPlaybackRate	设置播放速率	yes
setBalance	设置左右声道平衡	yes
release	释放播放器资源	yes
dispose	销毁播放器实例	yes
getDuration	获取音频总时长	yes
getCurrentPosition	获取当前播放位置	yes
setAudioContext	设置音频上下文	yes
setPlayerMode	设置播放模式	yes

兼容性与限制

兼容性

已在以下环境中测试通过：

• Flutter: 3.7.12-ohos-1.0.6 / 3.22.1-ohos-1.0.1
• HarmonyOS SDK: 5.0.0(12)
• DevEco Studio: 5.0.13.200

限制

• 在 HarmonyOS 中，暂时不支持配置左右声道的详细参数
• 部分高级音频效果可能与其他平台存在差异

示例应用

flutter_audioplayers 提供了完整的示例应用，可以在以下路径找到：
packages/audioplayers/example/lib/main.dart

该示例展示了插件的各种功能，包括：

• 不同音频源的播放
• 完整的播放控制界面
• 音频上下文配置
• 播放状态监听

总结

flutter_audioplayers 是一个功能丰富且易于使用的音频播放插件，在 HarmonyOS 平台上已经进行了良好的适配。通过本指南，开发者可以快速集成该插件到鸿蒙应用中，实现各种音频播放功能。

主要特点包括：

• 简单易用的 API 设计
• 支持多种音频源
• 完整的播放控制功能
• 灵活的音频上下文配置
• 良好的跨平台兼容性

使用 flutter_audioplayers，开发者可以轻松为 HarmonyOS 应用添加高质量的音频播放功能，提升用户体验。