1. 插件介绍

flutter_audio_session 是一个功能强大的 Flutter 插件，用于管理应用程序的音频会话。它能够通知操作系统应用程序的音频性质（例如游戏、媒体播放器、助手等），并处理音频中断（如电话呼叫中断）。该插件提供了对 iOS 的 AVAudioSession 和 Android 的 AudioManager 功能的访问，支持音频硬件的发现和配置。

在鸿蒙系统上，此插件已进行了自定义修改，以支持鸿蒙特有的音频会话管理功能，允许开发者轻松配置音频属性、处理音频焦点变化以及监听音频设备状态。

2. 插件特性

• 音频会话配置：轻松配置应用程序的音频会话，适用于不同场景（音乐、语音、游戏等）
• 音频焦点管理：自动处理音频焦点的获取和释放
• 中断处理：监听和响应各种音频中断事件（如电话呼叫、系统通知等）
• 设备管理：发现和监听音频设备的连接状态变化
• 音量控制：获取和设置系统音量
• 扬声器控制：管理扬声器和麦克风的状态

3. 安装与配置

3.1 引入依赖

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

dependencies:
  audio_session:
    git:
      url: "https://gitcode.com/openharmony-sig/flutter_audio_session.git"

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

flutter pub get

3.2 项目配置

在使用音频功能之前，确保您的鸿蒙应用已经获得了必要的权限。在鸿蒙应用的配置文件中添加音频相关权限：

// entry/src/main/module.json5
{
  "module": {
    "abilities": [
      {
        "permissions": [
          "ohos.permission.MICROPHONE",
          "ohos.permission.MODIFY_AUDIO_SETTINGS"
        ]
      }
    ]
  }
}

4. API 使用指南

4.1 获取音频会话实例

首先，获取音频会话的单例实例：

import 'package:audio_session/audio_session.dart';

final session = await AudioSession.instance;

4.2 配置音频会话

配置音频会话以适应不同的音频应用场景。

4.2.1 使用预设配置

对于音乐播放应用：

await session.configure(AudioSessionConfiguration.music());

对于语音播放应用（如播客、有声书）：

await session.configure(AudioSessionConfiguration.speech());

4.2.2 使用自定义配置

您可以根据应用需求创建自定义配置：

await session.configure(AudioSessionConfiguration(
  // 鸿蒙特有的音频属性配置
  ohosAudioAttributes: OhosAudioAttributes(
    streamUsage: StreamUsage.music,
    samplingRate: AudioSamplingRate.sampleRate44100,
    channels: AudioChannel.channel2,
    sampleFormat: AudioSampleFormat.sampleFormatS16LE,
    encodingType: AudioEncodingType.encodingTypeRaw,
  ),
  // 其他平台配置...
));

4.3 激活音频会话

在播放或录制音频之前，需要激活音频会话：

if (await session.setActive(true,
    ohosAudioConcurrencyMode: AudioConcurrencyMode.concurrencyPauseOthers)) {
  // 音频会话激活成功，可以开始播放或录制音频
} else {
  // 音频会话激活失败，可能是因为有其他高优先级的音频应用正在运行
}

4.4 监听音频事件

4.4.1 监听音频中断

session.interruptionEventStream.listen((event) {
  if (event.begin) {
    switch (event.type) {
      case AudioInterruptionType.duck:
        // 其他应用开始播放音频，当前音频应该降低音量
        break;
      case AudioInterruptionType.pause:
      case AudioInterruptionType.unknown:
        // 其他应用开始播放音频，当前音频应该暂停
        break;
    }
  } else {
    switch (event.type) {
      case AudioInterruptionType.duck:
        // 中断结束，当前音频应该恢复正常音量
        break;
      case AudioInterruptionType.pause:
        // 中断结束，当前音频应该恢复播放
      case AudioInterruptionType.unknown:
        // 中断结束，但不应该恢复播放
        break;
    }
  }
});

4.4.2 监听设备连接变化

session.devicesChangedEventStream.listen((event) {
  print('设备添加: ${event.devicesAdded}');
  print('设备移除: ${event.devicesRemoved}');
});

4.4.3 监听耳机插拔事件

session.becomingNoisyEventStream.listen((_) {
  // 用户拔下耳机，应该暂停音频或降低音量
});

4.5 管理音频设备

4.5.1 获取可用音频设备

final devices = await session.getDevices();
for (var device in devices) {
  print('设备: ${device.name}, 类型: ${device.type}');
}

4.5.2 控制扬声器

// 打开扬声器
await session.ohosAudioManager?.setSpeakerphoneOn(true);

// 关闭扬声器
await session.ohosAudioManager?.setSpeakerphoneOn(false);

// 检查扬声器状态
final isSpeakerOn = await session.ohosAudioManager?.isSpeakerphoneOn() ?? false;

4.6 音量控制

// 获取媒体音量
final mediaVolume = await session.ohosAudioManager?.getVolume(AudioVolumeType.media) ?? 0;

// 获取最大音量
final maxVolume = await session.ohosAudioManager?.getMaxVolume(AudioVolumeType.media) ?? 100;

// 获取静音状态
final isMuted = await session.ohosAudioManager?.isMute(AudioVolumeType.media) ?? false;

5. 完整示例

以下是一个完整的示例，展示了如何在鸿蒙应用中使用 flutter_audio_session 插件：

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

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Audio Session Demo',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: AudioSessionDemo(),
    );
  }
}

class AudioSessionDemo extends StatefulWidget {
  @override
  _AudioSessionDemoState createState() => _AudioSessionDemoState();
}

class _AudioSessionDemoState extends State<AudioSessionDemo> {
  AudioSession? _session;
  bool _isPlaying = false;
  String _status = '未初始化';

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

  Future<void> _initAudioSession() async {
    try {
      _session = await AudioSession.instance;

      // 配置为音乐播放模式
      await _session!.configure(AudioSessionConfiguration.music());

      // 监听中断事件
      _session!.interruptionEventStream.listen((event) {
        if (event.begin) {
          setState(() {
            _isPlaying = false;
            _status = '音频被中断';
          });
        }
      });

      // 监听设备变化
      _session!.devicesChangedEventStream.listen((event) {
        setState(() {
          _status = '设备变化: 添加 ${event.devicesAdded.length} 个, 移除 ${event.devicesRemoved.length} 个';
        });
      });

      setState(() {
        _status = '音频会话已初始化';
      });
    } catch (e) {
      setState(() {
        _status = '初始化失败: $e';
      });
    }
  }

  Future<void> _togglePlayback() async {
    if (_session == null) return;

    try {
      if (_isPlaying) {
        // 停止播放
        await _session!.setActive(false);
        setState(() {
          _isPlaying = false;
          _status = '已停止';
        });
      } else {
        // 开始播放
        final success = await _session!.setActive(true,
            ohosAudioConcurrencyMode: AudioConcurrencyMode.concurrencyPauseOthers);
        if (success) {
          setState(() {
            _isPlaying = true;
            _status = '正在播放';
          });
        } else {
          setState(() {
            _status = '无法获取音频焦点';
          });
        }
      }
    } catch (e) {
      setState(() {
        _status = '操作失败: $e';
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('音频会话演示')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text('状态: $_status'),
            SizedBox(height: 20),
            ElevatedButton(
              onPressed: _togglePlayback,
              child: Text(_isPlaying ? '停止播放' : '开始播放'),
            ),
          ],
        ),
      ),
    );
  }
}

6. 注意事项

1. 权限处理：确保在鸿蒙应用中正确配置了音频相关权限
2. 音频焦点：合理管理音频焦点，避免与其他应用的音频冲突
3. 中断处理：务必处理音频中断事件，提供良好的用户体验
4. 设备兼容性：不同鸿蒙设备可能有不同的音频硬件配置，需要进行充分测试
5. 资源释放：在应用退出或不再需要音频功能时，记得释放音频会话

7. 总结

flutter_audio_session 插件为鸿蒙系统上的 Flutter 应用提供了强大的音频会话管理能力。通过简单的 API 调用，开发者可以轻松配置音频属性、处理音频焦点变化以及监听音频设备状态。无论是开发音乐播放器、语音助手还是游戏应用，此插件都能提供可靠的音频会话管理支持。

使用 Git 形式引入自定义修改版本的插件，确保了开发者能够获取到针对鸿蒙系统优化的最新功能。通过遵循本指南中的步骤，您可以快速集成并使用此插件，为您的鸿蒙应用提供出色的音频体验。

---

希望本指南能帮助您在鸿蒙系统上成功使用 flutter_audio_session 插件。如果您在使用过程中遇到任何问题，建议参考官方文档或提交 issue 寻求帮助。