一、插件介绍

Flutter Sound 是一个功能强大的 Flutter 音频处理插件，支持音频录制、播放和流处理等功能。本版本是专为 HarmonyOS 适配的自定义修改版本，提供了与原生平台一致的音频处理能力，适用于开发需要音频功能的 HarmonyOS 应用。

主要功能

• 音频录制：支持多种音频格式的录制，包括 AAC、PCM、MP3 等
• 音频播放：支持播放多种音频格式文件
• 流处理：支持录制到流和从流播放功能
• 音频控制：提供开始、暂停、恢复、停止等完整的音频控制功能
• HarmonyOS 适配：针对 HarmonyOS 平台进行了专门优化，确保良好的兼容性和性能

二、插件安装与配置

2.1 Git 依赖引入

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

dependencies:
  flutter_sound:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_sound.git
      path: flutter_sound

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

flutter pub get

2.2 HarmonyOS 权限配置

使用 Flutter Sound 插件需要配置相应的 HarmonyOS 权限。

2.2.1 在 module.json5 中添加权限

打开 entry/src/main/module.json5 文件，添加以下权限配置：

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

2.2.2 在 string.json 中添加权限原因

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

{
  "string": [
    {
      "name": "microphone_reason",
      "value": "使用麦克风"
    },
    {
      "name": "background_running_reason",
      "value": "后台运行"
    }
  ]
}

三、API 调用示例

3.1 音频录制

3.1.1 基本录制示例

import 'package:flutter_sound/flutter_sound.dart';

// 初始化录音器
final recorder = FlutterSoundRecorder();

// 打开录音器
await recorder.openRecorder();

// 开始录制（保存到文件）
await recorder.startRecorder(
  toFile: 'recording.aac',
  codec: Codec.aacMP4,
  sampleRate: 16000,
  numChannels: 1,
  bitRate: 16000,
);

// 录制5秒后停止
await Future.delayed(Duration(seconds: 5));
await recorder.stopRecorder();

// 关闭录音器
await recorder.closeRecorder();

3.1.2 录制到流

// 创建流接收器
final StreamController<Food> recordingDataController = StreamController<Food>();

// 开始录制到流
await recorder.startRecorder(
  toStream: recordingDataController.sink,
  codec: Codec.pcm16,
  sampleRate: 16000,
  numChannels: 1,
  bitRate: 16000,
);

// 处理流数据
recordingDataController.stream.listen((buffer) {
  // 处理音频数据
});

// 停止录制
await recorder.stopRecorder();
await recordingDataController.close();

3.2 音频播放

3.2.1 基本播放示例

import 'package:flutter_sound/flutter_sound.dart';

// 初始化播放器
final player = FlutterSoundPlayer();

// 打开播放器
await player.openPlayer();

// 开始播放
await player.startPlayer(
  fromURI: 'path/to/audio.mp3',
  codec: Codec.mp3,
);

// 播放3秒后暂停
await Future.delayed(Duration(seconds: 3));
await player.pausePlayer();

// 暂停2秒后恢复
await Future.delayed(Duration(seconds: 2));
await player.resumePlayer();

// 播放完成后停止
await player.stopPlayer();

// 关闭播放器
await player.closePlayer();

3.2.2 从流播放

// 准备音频数据流
final StreamController<Uint8List> audioDataController = StreamController<Uint8List>();

// 开始从流播放
await player.startPlayer(
  fromURI: null,
  codec: Codec.pcm16,
  sampleRate: 16000,
  numChannels: 1,
);

// 向流中添加音频数据
audioDataController.stream.listen((buffer) {
  // 处理音频数据并播放
});

// 停止播放
await player.stopPlayer();
await audioDataController.close();

3.3 音频控制功能

3.3.1 进度控制

// 设置进度回调
player.setSubscriptionDuration(Duration(milliseconds: 100));

// 监听播放进度
player.onProgress.listen((e) {
  final duration = e.duration;
  final position = e.position;
  print('播放进度：$position / $duration');
});

// 跳转到指定位置
await player.seekToPlayer(Duration(seconds: 10));

3.3.2 音量和速度控制

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

// 设置播放速度
await player.setSpeed(1.5); // 1.5倍速播放

四、编解码器支持

4.1 录制支持的编解码器

编解码器	HarmonyOS 支持
aacMP4	✅
pcm16	✅
pcm16WAV	✅
amrNB	✅ (API>=18)
amrWB	✅ (API>=18)
mp3	✅
pcmFloat32	✅

4.2 播放支持的编解码器

编解码器	HarmonyOS 支持
aacADTS	✅
opusOGG	✅
mp3	✅
vorbisOGG	✅
pcm16	✅
pcmWAV	✅
flac	✅
aacMP4	✅
pcmFloat32	✅

五、约束与限制

1. 兼容性：已在以下版本中测试通过

   • 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

2. 权限要求：必须在应用中声明并获取麦克风和后台运行权限

3. 编解码器限制：仅支持上述列表中的编解码器格式

4. 功能限制：在 HarmonyOS 平台上不支持对同一个媒体文件边播放边录制功能

六、总结

Flutter Sound 插件为 HarmonyOS 应用提供了完整的音频处理解决方案，支持音频录制、播放和流处理等功能。通过 Git 形式引入后，开发者可以轻松在 Flutter 应用中使用丰富的音频功能。

优势

• 功能丰富：提供了完整的音频处理能力，满足大多数应用的音频需求
• 易于使用：API 设计简洁直观，易于集成和使用
• HarmonyOS 适配：针对 HarmonyOS 平台进行了专门优化，确保良好的兼容性
• 灵活性：支持多种音频格式和流处理功能，适应不同的应用场景

使用建议

1. 在使用音频功能前，确保已正确配置并获取所需的权限
2. 根据应用需求选择合适的编解码器格式
3. 注意音频资源的生命周期管理，及时关闭不再使用的录音器和播放器
4. 对于长时间运行的音频任务，建议使用后台运行权限
5. 在使用流处理功能时，注意内存管理，避免内存泄漏

通过本指南，您可以快速上手 Flutter Sound 插件在 HarmonyOS 上的开发，为您的应用添加丰富的音频功能。