Migration Guide

Migration Guide

0.18.0 (preview)

A preview of the 0.18.0 release is available on the one-isolate branch ( README ).

NOTE: While the API is beginning to stabilise, it may still undergo further changes before the final release.

To try out the head of this branch, use the following pubspec dependency:

dependencies:
  audio_service:
    git: 
      url: https://github.com/ryanheise/audio_service.git
      ref: one-isolate
      path: audio_service

(The path is required now that audio_service has a federated plugin directory structure in git.)

Alternatively you can pin your your pubspec dependency to a specific commit to achieve some level of stability while development continues. For example, the following pins your build to a commit just before the plugin was migrated to a federated architecture:

dependencies:
  audio_service:
    git: 
      url: https://github.com/ryanheise/audio_service.git
      ref: 9c1dfc4

Basic migration steps:

1. On Android, edit your AndroidManifest.xml file by setting the android:name attribute of your <activity> element to com.ryanheise.audioservice.AudioServiceActivity as outlined in the "Android setup" section of the README.
2. Call AudioService.init() in your app's main() as per the example in the README, passing any configuration options and callbacks you previously passed into AudioService.start().
3. Remove any call to AudioService.start(). The media notification should now show automatically on the first time you call play().
4. Remove your corresponding implementation of onStart() and move any initialisation code into the constructor or other callbacks as appropriate.
5. If you use customAction/onCustomAction, the second argument is now required to be a Map.

Optional (recommended) step:

6. BackgroundAudioTask is deprecated and replaced by AudioHandler, a new composable and mixable API allowing functionality from multiple audio handlers to be combined. To migrate, change your base class from BackgroundAudioTask to BaseAudioHandler and remove the on prefix from each method name (e.g. rename onPlay to play).

0.14.0

This plugin has been split into two separate packages:

1. audio_session interacts with your app's native audio session, and controls how your app reacts when it is interrupted by another audio app (e.g. a phone call) as well as how other apps should behave when your app interrupts their audio. It also lets your app communicate to the operating system what type of audio it intends to play so that it can manage your app appropriately. This set of features is useful even outside the context of background audio apps (e.g. games also need to pause audio during a phone call, and apps that simply play sound notifications need to be able to request other apps to duck audio). It is not necessary to use this package directly if you are happy with the default audio behaviour.
2. audio_service keeps every other piece of functionality. Namely, it wraps around your audio code to allow it to run in the background and provides a set of callbacks that allow this background code to be controlled from the Flutter UI as well as the lock screen, notification, control center, car displays and smart watches.

In the bigger picture, individual audio plugins may opt to manage the audio session for you. E.g. just_audio will now by default pause or duck audio when its audio session is interrupted by another app playing audio, and will resume normal playback once the interruption has ended if deemed appropriate by the operating system. This default behaviour can be disabled by using the AudioPlayer constructor, allowing you to implement your own audio interruption logic by using the audio_session API directly.

Migration steps:

(Required) Remove the following methods from your BackgroundAudioTask if you have implemented them:

  onAudioFocusLost(AudioInterruption interruption)
  onAudioFocusGained(AudioInterruption interruption)
  onAudioBecomingNoisy()

(Optional) It is recommended to announce to the operating system on startup what type of audio requirements your app has via the audio_session package. E.g. for a podcast or audiobook app, use the speech preset, and for a music player use the music preset:

final session = await AudioSession.instance;
await session.configure(AudioSessionConfiguration.speech());

If no configuration is set, it will default to settings appropriate for a music app.

(Optional) If you want to handle your own logic for audio interruptions and unplugged headphones, listen to the following two streams:

session.interruptionEventStream.listen((event) {
  if (event.begin) {
    switch (event.type) {
      case AudioInterruptionType.duck:
        // Another app started playing audio and we should duck.
        break;
      case AudioInterruptionType.pause:
      case AudioInterruptionType.unknown:
        // Another app started playing audio and we should pause.
        break;
    }
  } else {
    switch (event.type) {
      case AudioInterruptionType.duck:
        // The interruption ended and we should unduck.
        break;
      case AudioInterruptionType.pause:
        // The interruption ended and we should resume.
      case AudioInterruptionType.unknown:
        // The interruption ended but we should not resume.
        break;
    }
  }
});
session.becomingNoisyEventStream.listen((_) {
  // The user unplugged the headphones, so we should pause or lower the volume.
});

0.13.0

All callbacks in AudioBackgroundTask are now asynchronous. This allows the main isolate to await their completion and better synchronise with the background audio task.

0.11.0

The background audio task now terminates when onStop completes rather than when onStart completes.

0.10.0

Your broadcast receiver in AndroidManifest.xml should be replaced with the one below to ensure that headset and notification clicks continue to work:

    <receiver android:name="com.ryanheise.audioservice.MediaButtonReceiver" >
      <intent-filter>
        <action android:name="android.intent.action.MEDIA_BUTTON" />
      </intent-filter>
    </receiver>