audio_session

To customize the launch screen for your iOS application, you can replace the image files located in the example/ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory with your own assets.

Alternatively, you can manage these assets using Xcode:

1. Open your Flutter project's iOS workspace using open ios/Runner.xcworkspace.
2. In the Xcode Project Navigator, navigate to Runner/Assets.xcassets.
3. Drag and drop your desired images into the asset catalog to replace the existing launch images.

Use the following streams to handle hardware changes:

• session.becomingNoisyEventStream: Emits when headphones are unplugged (the app should typically pause or lower volume).
• session.devicesChangedEventStream: Emits when audio devices are added or removed. The event contains devicesAdded and devicesRemoved lists.

// Observe unplugged headphones
session.becomingNoisyEventStream.listen((_) {
  // The user unplugged the headphones, so we should pause or lower the volume.
});

// Observe when devices are added or removed
session.devicesChangedEventStream.listen((event) {
  print('Devices added:   ${event.devicesAdded}');
  print('Devices removed: ${event.devicesRemoved}');
});

While most audio plugins activate the audio session automatically when playing audio, you can manually activate it using session.setActive(true). This informs the OS that your app is actively using audio. The method returns a bool indicating if the request was successful (e.g., it might fail if a phone call is in progress).

// Activate the audio session before playing audio.
if (await session.setActive(true)) {
  // Now play audio.
} else {
  // The request was denied and the app should not play audio
}

Use AudioSession.instance.configure() to set the app's audio behavior. The plugin provides pre-defined configurations for common use cases like music or speech (podcasts/audiobooks).

Important Note on Shared State: On iOS, there is a single audio session shared by all audio plugins in your app. To prevent other plugins from overwriting your settings, it is recommended to apply your preferred configuration using audio_session after all other audio plugins have loaded.

final session = await AudioSession.instance;

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

// For podcasts/audiobooks
await session.configure(AudioSessionConfiguration.speech());

On Android, audio attributes are per-player/track rather than app-wide. To ensure a plugin respects the global configuration set via audio_session, it should listen to the configurationStream. This stream emits the latest configuration as its first event and subsequent changes thereafter.

audioSession.configurationStream
    .map((conf) => conf?.androidAudioAttributes)
    .distinct()
    .listen((attributes) {
  // apply the attributes to this Android audio track
  _channel.invokeMethod("setAudioAttributes", attributes.toJson());
});

An AudioDevice represents a piece of audio hardware. It includes:

• id: A unique identifier.
• name: The device name.
• isInput: Whether it can record audio.
• isOutput: Whether it can play audio.
• type: An AudioDeviceType describing the hardware category.

AudioDeviceType is an enumeration covering various types such as builtInSpeaker, wiredHeadphones, bluetoothA2dp, usbAudio, airPlay, and more. Note that AudioDeviceType is currently marked as @experimental.

To interact with the audio session, you must obtain the singleton instance of AudioSession. This instance is shared across all Flutter engines and should be used to configure the app's audio behavior during startup.

final session = await AudioSession.instance;

Use devicesChangedEventStream to detect when audio hardware (like headphones or Bluetooth devices) is added or removed.

An AudioDevicesChangedEvent contains:

• devicesAdded: A set of AudioDevice objects that were just connected.
• devicesRemoved: A set of AudioDevice objects that were just disconnected.

Alternatively, use devicesStream to get the current complete set of connected devices whenever any change occurs.

final session = await AudioSession.instance;

// Listen for specific changes
session.devicesChangedEventStream.listen((event) {
  print('Added: ${event.devicesAdded}');
  print('Removed: ${event.devicesRemoved}');
});

// Or listen to the full set of current devices
session.devicesStream.listen((devices) {
  print('Current devices: $devices');
});