audio_service 0.18.15

Flutter plugin to play audio in the background while the screen is off.

audio_service

This plugin wraps around your existing audio code to allow it to run in the background and interact with the media notification, the lock screen, headset buttons, wearables and Android Auto. It supports Android, iOS, web and Linux (via audio_service_mpris). It is suitable for:

• Music players
• Text-to-speech readers
• Podcast players
• Video players
• Navigators
• More!

How does this plugin work?

You encapsulate your audio code in an audio handler which implements a set of standard system callbacks to handle media playback requests from different sources in a uniform way:

You implement these callbacks to play the particular type of audio that your app needs to play in response to these requests. For example, a Text-to-speech reader app might implement these callbacks using flutter_tts to render the speech, while a music player app might implement these callbacks using just_audio to render the audio.

Feature	Android	iOS	macOS	Web
background audio	✅	✅	✅	✅
headset clicks	✅	✅	✅	✅
play/pause/seek/rate/stop	✅	✅	✅	✅
fast forward/rewind	✅	✅	✅	✅
repeat/shuffle mode	✅	✅	✅	✅
queue manipulation, skip next/prev	✅	✅	✅	✅
custom actions/events/states	✅	✅	✅	✅
notifications/control center	✅	✅	✅	✅
lock screen controls	✅	✅		✅
album art	✅	✅	✅	✅
Android Auto, Apple CarPlay	✅	✅

If you'd like to help with any missing features, please join us on the GitHub issues page.

Tutorials and documentation

• Background audio in Flutter with Audio Service and Just Audio by @suragch
• Tutorial: walks you through building a simple audio player while explaining the basic concepts.
• Full example: The example subdirectory on GitHub demonstrates both music and text-to-speech use cases.
• Frequently Asked Questions
• API documentation

Can I make use of other plugins within the audio handler?

Yes! audio_service is designed to let you implement the audio logic however you want, using whatever plugins you want. You can use your favourite audio plugins such as just_audio, flutter_tts, and others, within your audio handler. There are also plugins like just_audio_handlers that provide default implementations of AudioHandler to make your job easier.

Note that this plugin will not work with other audio plugins that overlap in responsibility with this plugin (i.e. background audio, iOS control center, Android notifications, lock screen, headset buttons, etc.)

Example

Initialisation

Define your AudioHandler with the callbacks that you want your app to handle:

class MyAudioHandler extends BaseAudioHandler
    with QueueHandler, // mix in default queue callback implementations
    SeekHandler { // mix in default seek callback implementations

  final _player = AudioPlayer(); // e.g. just_audio
  
  // The most common callbacks:
  Future<void> play() => _player.play();
  Future<void> pause() => _player.pause();
  Future<void> stop() => _player.stop();
  Future<void> seek(Duration position) => _player.seek(position);
  Future<void> skipToQueueItem(int i) => _player.seek(Duration.zero, index: i);
}

Register your AudioHandler during app startup:

Future<void> main() async {
  // store this in a singleton
  _audioHandler = await AudioService.init(
    builder: () => MyAudioHandler(),
    config: AudioServiceConfig(
      androidNotificationChannelId: 'com.mycompany.myapp.channel.audio',
      androidNotificationChannelName: 'Music playback',
    ),
  );
  runApp(new MyApp());
}

Sending requests to the audio handler from Flutter

Standard controls:

_audioHandler.play();
_audioHandler.seek(Duration(seconds: 10));
_audioHandler.setSpeed(1.5);
_audioHandler.pause();
_audioHandler.stop();

Playing specific media items:

var item = MediaItem(
  id: 'https://example.com/audio.mp3',
  album: 'Album name',
  title: 'Track title',
  artist: 'Artist name',
  duration: const Duration(milliseconds: 123456),
  artUri: Uri.parse('https://example.com/album.jpg'),
);

_audioHandler.playMediaItem(item);
_audioHandler.playFromSearch(queryString);
_audioHandler.playFromUri(uri);
_audioHandler.playFromMediaId(id);

Queue management:

_audioHandler.addQueueItem(item);
_audioHandler.insertQueueItem(1, item);
_audioHandler.removeQueueItem(item);
_audioHandler.updateQueue([item, ...]);
_audioHandler.skipToNext();
_audioHandler.skipToPrevious();
_audioHandler.skipToQueueItem(2);

Looping and shuffling:

_audioHandler.setRepeatMode(AudioServiceRepeatMode.one); // none/one/all/group
_audioHandler.setShuffleMode(AudioServiceShuffleMode.all); // none/all/group

Custom actions:

_audioHandler.customAction('setVolume', {'volume': 0.8});
_audioHandler.customAction('saveBookmark');

Broadcasting state changes

Your audio handler must broadcast state changes so that the system notification and smart watches (etc) know what state to display. Your app's Flutter UI may also listen to these state changes so that it knows what state to display. Thus, the audio handler provides a single source of truth for your audio state to all clients.

Broadcast the current media item:

class MyAudioHandler extends BaseAudioHandler ... {
    ...
    mediaItem.add(item1);
    ...

Broadcast the current queue:

  ...
  queue.add(<MediaItem>[item1, item2, item3]);
  ...

Broadcast the current playback state:

    ...
    // All options shown:
    playbackState.add(PlaybackState(
      // Which buttons should appear in the notification now
      controls: [
        MediaControl.skipToPrevious,
        MediaControl.pause,
        MediaControl.stop,
        MediaControl.skipToNext,
      ],
      // Which other actions should be enabled in the notification
      systemActions: const {
        MediaAction.seek,
        MediaAction.seekForward,
        MediaAction.seekBackward,
      },
      // Which controls to show in Android's compact view.
      androidCompactActionIndices: const [0, 1, 3],
      // Whether audio is ready, buffering, ...
      processingState: AudioProcessingState.ready,
      // Whether audio is playing
      playing: true,
      // The current position as of this update. You should not broadcast
      // position changes continuously because listeners will be able to
      // project the current position after any elapsed time based on the
      // current speed and whether audio is playing and ready. Instead, only
      // broadcast position updates when they are different from expected (e.g.
      // buffering, or seeking).
      updatePosition: Duration(milliseconds: 54321),
      // The current buffered position as of this update
      bufferedPosition: Duration(milliseconds: 65432),
      // The current speed
      speed: 1.0,
      // The current queue position
      queueIndex: 0,
    ));

Broadcasting mutations of the current playback state using copyWith:

    playbackState.add(playbackState.value.copyWith(
      // Keep all existing state the same with only the speed changed:
      speed: newSpeed,
    ));

Listening to state changes

Listen to changes to the currently playing item from the Flutter UI:

_audioHandler.mediaItem.listen((MediaItem item) { ... });

Listen to changes to the queue from the Flutter UI:

_audioHandler.queue.listen((List<MediaItem> queue) { ... });

Listen to playback state changes from the Flutter UI:

_audioHandler.playbackState.listen((PlaybackState state) {
  if (state.playing) ... else ...
  switch (state.processingState) {
    case AudioProcessingState.idle: ...
    case AudioProcessingState.loading: ...
    case AudioProcessingState.buffering: ...
    case AudioProcessingState.ready: ...
    case AudioProcessingState.completed: ...
    case AudioProcessingState.error: ...
  }
});

Listen to a stream of continuous changes to the current playback position:

AudioService.position.listen((Duration position) { ... });

Advanced features

Compose multiple audio handler classes:

_audioHandler = await AudioService.init(
  builder: () => AnalyticsAudioHandler(
    PersistingAudioHandler(
      MyAudioHandler())),
);

Connecting from another isolate:

// Wrap audio handler in IsolatedAudioHandler:
_audioHandler = await AudioService.init(
  builder: () => IsolatedAudioHandler(
    MyAudioHandler(),
    portName: 'my_audio_handler',
  ),
);
// From another isolate, obtain a proxy reference:
_proxyAudioHandler = await IsolatedAudioHandler.lookup(
  portName: 'my_audio_handler',
);

See the full example for how to handle queues/playlists, headset button clicks, media artwork and text to speech.

Configuring the audio session

If your app uses audio, you should tell the operating system what kind of usage scenario your app has and how your app will interact with other audio apps on the device. Different audio apps often have unique requirements. For example, when a navigator app speaks driving instructions, a music player should duck its audio while a podcast player should pause its audio. Depending on which one of these three apps you are building, you will need to configure your app's audio settings and callbacks to appropriately handle these interactions.

Use the audio_session package to change the default audio session configuration for your app. E.g. for a podcast player, you may use:

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

Each time you invoke an audio plugin to play audio, that plugin will activate your app's shared audio session to inform the operating system that your app is actively playing audio. Depending on the configuration set above, this will also inform other audio apps to either stop playing audio, or possibly continue playing at a lower volume (i.e. ducking). You normally do not need to activate the audio session yourself, however if the audio plugin you use does not activate the audio session, you can activate it yourself:

// 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
}

When another app activates its audio session, it similarly may ask your app to pause or duck its audio. Once again, the particular audio plugin you use may automatically pause or duck audio when requested. However, if it does not, you can respond to these events yourself by listening to session.interruptionEventStream. Similarly, if the audio plugin doesn't handle unplugged headphone events, you can respond to these yourself by listening to session.becomingNoisyEventStream. For more information, consult the documentation for audio_session.

Note: If your app uses a number of different audio plugins, e.g. for audio recording, or text to speech, or background audio, it is possible that those plugins may internally override each other's audio session settings since there is only a single audio session shared by your app. Therefore, it is recommended that you apply your own preferred configuration using audio_session after all other audio plugins have loaded. You may consider asking the developer of each audio plugin you use to provide an option to not overwrite these global settings and allow them be managed externally.

Android setup

1. Make the following changes to your project's AndroidManifest.xml file:

<manifest xmlns:tools="http://schemas.android.com/tools" ...>
  <!-- ADD THESE TWO PERMISSIONS -->
  <uses-permission android:name="android.permission.WAKE_LOCK"/>
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
  <!-- ALSO ADD THIS PERMISSION IF TARGETING SDK 34 -->
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK"/>
  
  <application ...>
    
    ...
    
    <!-- EDIT THE android:name ATTRIBUTE IN YOUR EXISTING "ACTIVITY" ELEMENT -->
    <activity android:name="com.ryanheise.audioservice.AudioServiceActivity" ...>
      ...
    </activity>
    
    <!-- ADD THIS "SERVICE" element -->
    <service android:name="com.ryanheise.audioservice.AudioService"
        android:foregroundServiceType="mediaPlayback"
        android:exported="true" tools:ignore="Instantiatable">
      <intent-filter>
        <action android:name="android.media.browse.MediaBrowserService" />
      </intent-filter>
    </service>

    <!-- ADD THIS "RECEIVER" element -->
    <receiver android:name="com.ryanheise.audioservice.MediaButtonReceiver"
        android:exported="true" tools:ignore="Instantiatable">
      <intent-filter>
        <action android:name="android.intent.action.MEDIA_BUTTON" />
      </intent-filter>
    </receiver> 
  </application>
</manifest>

Note: As of Android 12, an app must have permission to restart a foreground service in the background, otherwise a ForegroundServiceStartNotAllowedException will be thrown. To avoid such an exception, you can either set androidStopForegroundOnPause to false in your AudioServiceConfig which keeps the service in the foreground during a pause so that restarting the foreground service is unnecessary, or you can keep the default androidStopForegroundOnPause setting of true (in line with best practices) and request the user to turn of battery optimisation for your app via the optimize_battery package. For more information, read this page.

2. If you use any custom icons in notification, create the file android/app/src/main/res/raw/keep.xml to prevent them from being stripped during the build process:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
  tools:keep="@drawable/*" />

By default plugin's default icons are not stripped by R8. If you don't use them, you may selectively strip them. For example, the rules below will keep all your icons and discard all the plugin's:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
  tools:keep="@drawable/*"
  tools:discard="@drawable/audio_service_*" 
/>

For more information about shrinking see Android documentation.

Custom Android activity

If your app needs to use its own custom activity, make sure you update your AndroidManifest.xml file to reference your activity's class name instead of AudioServiceActivity. For example, if your activity class is named MainActivity, then use:

    <activity android:name=".MainActivity" ...>

Depending on whether you activity is a regular Activity or a FragmentActivity, you must also include some code to link to audio_service's shared FlutterEngine. The easiest way to accomplish this is to inherit that code from one of audio_service's provided base classes.

1. Integration as an Activity:

import com.ryanheise.audioservice.AudioServiceActivity;

class MainActivity extends AudioServiceActivity {
    // ...
}

2. Integration as a FragmentActivity:

import com.ryanheise.audioservice.AudioServiceFragmentActivity;

class MainActivity extends AudioServiceFragmentActivity {
    // ...
}

You can also write your own activity class from scratch, and override the provideFlutterEngine, getCachedEngineId and shouldDestroyEngineWithHost methods yourself. For inspiration, see the source code of the provided AudioServiceActivity and AudioServiceFragmentActivity classes.

iOS setup

Insert this in your Info.plist file:

  <key>UIBackgroundModes</key>
  <array>
    <string>audio</string>
  </array>

The example project may be consulted for context.

Note that the audio background mode permits an app to run in the background only for the purpose of playing audio. The OS may kill your process if it sits idly without playing audio, for example, by using a timer to sleep for a few seconds. If your app needs to pause for a few seconds between audio tracks, consider playing a silent audio track to create that effect rather than using an idle timer.

macOS setup

The minimum supported macOS version is 10.12.2 (though this could be changed with some work in the future).
Modify the platform line in macos/Podfile to look like the following:

platform :osx, '10.12.2'