FAQ

Frequently Asked Questions

Why does nothing happen when calling AudioService.start()?

Make sure you have done the following:

1. Your background task entrypoint must be a top-level or static function, don't put in the same class.
2. If on Android, you must follow the Android setup instructions in the README file.

Why does my app get a MissingPluginException?

Make sure you have upgraded your project to the Flutter 1.12 project structure first. If you still get the error, it may be an issue of the specific combination of other plugins you're using. Make sure that the other plugins you're using have also been updated to support Flutter 1.12 (known as the v2 plugin model).

Why does the control center not appear on iOS?

This can result from a conflict with the flutter_tts plugin, which is also used in the example. (See the open issue #202)

Can this plugin be used with android_alarm_manager?

As of audio_service 0.9.0, a callback set by android_alarm_manager can connect to AudioService via AudioService.connect and communicate with a running background audio task, although currently is not allowed to start a new background audio task (this must be done from an activity, when the app is in the foreground).

Can this plugin be used with audioplayers

audioplayers has both worked and not worked at different times in the past. If it currently does not work, you can contact the author of that plugin and make a feature request.

Relevant information: For an audio player plugin to work with audio_service there needs to be clearly delineated roles between the two plugins such that only audio_service controls the various APIs involved in:

1. Enabling background execution
2. Displaying notifications, lock screen controls, Control Center info, etc.
3. Configuring the audio session
4. Handling remote controls from headsets, smart watches, car stereos, etc.
5. Handling audio focus events (e.g. if another app takes over audio focus temporarily)

If the other plugin does any of these things, the two plugins will overlap in responsibility and things will probably not work. In other words, you will need an audio player plugin that just plays audio, and doesn't take on any of these other responsibilities listed above.

If at present audioplayers doesn't work for you, you can alternatively try my plugin just_audio which was designed with this delineation in mind.

How can I send custom messages from the background task to the UI?

The plugin doesn't provide an API for this (yet). However, you can use the standard Dart Isolates API to send arbitrary messages between isolates. Typically, the UI will create a ReceivePort and then register its SendPort in the IsolateNameServer under a particular name:

_receivePort = ReceivePort();
_receivePort.listen((message) {
  // handle message in your UI here
});
IsolateNameServer.registerPortWithName(_receivePort.sendPort, PORT_NAME);

Then in your background task, you can find this SendPort registered in the isolate name server and send messages via it:

SendPort sendPort = IsolateNameServer.lookupPortByName(PORT_NAME);
sendPort?.send(message);

Can I pause audio when receiving an incoming call?

Yes. In your background task, you must override the relevant callbacks:

  void onAudioFocusLost(AudioInterruption interruption) {}
  void onAudioFocusGained(AudioInterruption interruption) {}

When audio focus is lost, you need to observe and remember whether audio was playing at that time. When audio focus is gained, restore audio playback only if audio was originally playing when it was interrupted and the interruption parameter indicates that playback should resume as normal (see the documentation and example for further details).

Is it possible to make the headphone (media) buttons work in a text-to-speech app?

There is an issue on Android, but there is a workaround. Android requires an active media sessions to route media button events to, and actual audio needs to be played to activate a media session (text-to-speech does not count). One trick is to play a short segment of silent audio to activate the session. You can use AudioServiceBackground.androidForceEnableMediaButtons() to achieve this.

How do I send arbitrary initialisation messages to the background task when starting it?

Arbitrary parameters can be passed to AudioService.start via the params parameter. You can use AudioService.customAction(...) to pass an arbitrary message to the background task after it has started. To ensure it has started, you must await the result of AudioService.start:

if (await AudioService.start(...)) {
  AudioService.customAction(...);
}

How do I make a custom action?

If you want to send a message from the UI to your background audio task but it is not one of the predefined messages defined in AudioService, you can send the message as a custom action. E.g.

// In your UI
AudioService.customAction("setVolume", 0.5);

And then in your background audio task, implement the onCustomAction method:

@override
void onCustomAction(String name, dynamic arguments) {
    if (name == 'setVolume') {
        _audioPlayer.setVolume(arguments);
    }
}

Note that the parameter of a custom action can be any data structure that can be encoded by the standard message codec.

How do I update an existing MediaItem?

You cannot update fields in a MediaItem object since it is immutable, although in the same style as ThemeData.copyWith, you can use MediaItem.copyWith to create a copy with some fields modified. e.g.

modifiedMediaItem = mediaItem.copyWith(duration: duration);

If you are updating the current media item in your background audio task, remember to broadcast this change to all clients:

AudioServiceBackground.setMediaItem(modifiedMediaItem);

If you are updating a media item in the queue in your background audio task, remember to broadcast your modified queue to all clients:

myQueue[pos] = modifiedMediaItem;
AudioServiceBackground.setQueue(myQueue);

How do I test the latest code on git master?

Sometimes you may want to try out the latest code on git master, e.g. to try out a bug fix or new feature that hasn't been released yet. To do so, you can temporarily change your pubspec.yaml file to:

  audio_service:
    git:
      url: https://github.com/ryanheise/audio_service.git

Note that git master is not stable and should not be used in production.