Flutter Audioplayers 鸿蒙使用指南

1. 插件介绍

Flutter Audioplayers 是一个功能强大的 Flutter 插件，用于在 Flutter 应用中播放音频。它支持在多个平台上同时播放多个音频文件，包括 Android、iOS、Linux、macOS、Windows、Web 和鸿蒙系统。

主要功能包括：

• 支持多种音频源：网络 URL、本地文件、字节流
• 完整的播放控制：播放、暂停、停止、跳转、音量调节
• 支持播放速率调节
• 支持平衡左右声道
• 支持监听播放状态和进度
• 支持设置音频上下文参数

2. 插件安装

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

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

配置完成后，执行以下命令获取依赖：

flutter pub get

3. 权限配置

在鸿蒙系统上使用音频播放功能，需要配置相关权限。

3.1 添加后台播放权限

打开 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"
      }
    }
  ]
}

3.2 添加权限描述

打开 entry/src/main/resources/base/element/string.json 文件，添加权限描述：

{
  "string": [
    {
      "name": "background_running_reason",
      "value": "用于支持音频后台播放"
    }
  ]
}

4. 使用方法

4.1 基本使用

以下是一个简单的音频播放示例：

import 'package:audioplayers/audioplayers.dart';

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

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

// 播放本地音频
await player.play(AssetSource('audio/song.mp3'));

4.2 完整的播放控制

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

// 设置音频源（网络URL）
await player.setSourceUrl('https://example.com/music.mp3');

// 或者使用字节流作为音频源
// final bytes = await rootBundle.load('assets/audio/song.mp3');
// await player.setSourceBytes(bytes.buffer.asUint8List());

// 播放
await player.play(UrlSource('https://example.com/music.mp3'));

// 暂停
await player.pause();

// 继续播放
await player.resume();

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

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

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

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

// 设置左右声道平衡（-1.0到1.0）
await player.setBalance(0.5);

// 获取音频总时长
final duration = await player.getDuration();
print('音频时长: $duration');

// 获取当前播放位置
final position = await player.getCurrentPosition();
print('当前播放位置: $position');

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

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

// 释放播放器资源
await player.release();

// 销毁播放器实例
await player.dispose();

4.3 使用 AssetSource 播放本地资源

要播放本地资源，首先需要在 pubspec.yaml 中配置资源：

flutter:
  assets:
    - assets/audio/

然后使用 AssetSource 播放：

await player.play(AssetSource('audio/song.mp3'));

4.4 设置音频上下文

可以设置音频上下文参数来控制音频的播放行为：

await player.setAudioContext(
  AudioContext(
    stayAwake: true, // 播放时保持设备唤醒
    usageType: UsageType.media, // 音频使用类型
    rendererFlags: RendererFlags.normal, // 渲染器标志
  ),
);

在鸿蒙系统上，setAudioContext 支持以下参数：

• isSpeakerphoneOn：是否使用扬声器
• rendererFlags：渲染器标志
• audioScene：音频场景
• usageType：音频使用类型
• stayAwake：播放时是否保持设备唤醒

5. 完整示例

以下是一个在鸿蒙系统上使用 Flutter Audioplayers 播放音频的完整示例：

import 'package:flutter/material.dart';
import 'package:audioplayers/audioplayers.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: '音频播放器示例',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const AudioPlayerScreen(),
    );
  }
}

class AudioPlayerScreen extends StatefulWidget {
  const AudioPlayerScreen({super.key});

  @override
  State<AudioPlayerScreen> createState() => _AudioPlayerScreenState();
}

class _AudioPlayerScreenState extends State<AudioPlayerScreen> {
  final player = AudioPlayer();
  final String audioUrl = 'https://luan.xyz/files/audio/ambient_c_motion.mp3';
  Duration duration = Duration.zero;
  Duration position = Duration.zero;
  PlayerState playerState = PlayerState.stopped;

  @override
  void initState() {
    super.initState();

    // 监听播放状态变化
    player.onPlayerStateChanged.listen((state) {
      setState(() {
        playerState = state;
      });
    });

    // 监听音频时长
    player.onDurationChanged.listen((newDuration) {
      setState(() {
        duration = newDuration;
      });
    });

    // 监听播放进度
    player.onPositionChanged.listen((newPosition) {
      setState(() {
        position = newPosition;
      });
    });
  }

  String formatTime(Duration duration) {
    String twoDigits(int n) => n.toString().padLeft(2, '0');
    final hours = twoDigits(duration.inHours);
    final minutes = twoDigits(duration.inMinutes.remainder(60));
    final seconds = twoDigits(duration.inSeconds.remainder(60));
    return [if (duration.inHours > 0) hours, minutes, seconds].join(':');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('音频播放器'),
      ),
      body: Center(
        child: Padding(
          padding: const EdgeInsets.all(20.0),
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              // 播放控制按钮
              Row(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  IconButton(
                    iconSize: 64.0,
                    icon: Icon(
                      playerState == PlayerState.playing
                          ? Icons.pause
                          : Icons.play_arrow,
                    ),
                    onPressed: () async {
                      if (playerState == PlayerState.playing) {
                        await player.pause();
                      } else {
                        await player.play(UrlSource(audioUrl));
                      }
                    },
                  ),
                  IconButton(
                    iconSize: 64.0,
                    icon: const Icon(Icons.stop),
                    onPressed: () async {
                      await player.stop();
                    },
                  ),
                ],
              ),
              const SizedBox(height: 20),
              // 播放进度条
              Slider(
                min: 0,
                max: duration.inSeconds.toDouble(),
                value: position.inSeconds.toDouble(),
                onChanged: (value) async {
                  final newPosition = Duration(seconds: value.toInt());
                  await player.seek(newPosition);
                },
              ),
              // 时间显示
              Text(
                '${formatTime(position)} / ${formatTime(duration)}',
                style: const TextStyle(fontSize: 18),
              ),
            ],
          ),
        ),
      ),
    );
  }

  @override
  void dispose() {
    player.dispose();
    super.dispose();
  }
}

6. 注意事项

1. 兼容性：

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

2. 功能限制：

   • 在鸿蒙系统中，暂时不支持配置左右声道

3. 性能优化：

   • 不需要播放音频时，记得释放播放器资源
   • 长时间播放音频时，建议使用 release() 方法释放资源，而不是 dispose()

7. 总结

Flutter Audioplayers 插件为鸿蒙系统上的音频应用开发提供了强大的支持，能够帮助开发者轻松实现各种音频播放功能。通过合理配置权限和使用 API，可以创建出功能完整、体验良好的音频应用。

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.youkuaiyun.com