Tutorial

Tutorial

This tutorial walks you through the steps to create a Flutter app that uses audio_service to play audio in the background.

Prerequisites

You should already have followed the project setup instructions in the audio_service README. It will also help if you are familiar with Dart isolates.

Concepts

This plugin runs all of your audio code in a separate "background" isolate that will survive the destruction of the main isolate that runs your Flutter UI. This allows your audio code to continue playing even when the UI is gone, or even destroyed and reclaimed from memory. Throughout this document, the code that runs in the main isolate will be referred to as your UI, and the code that runs in the background isolate will be referred to as the background audio task.

Since isolates do not share memory, your UI and background audio task will communicate via message passing. A number of standard messages are defined for communicating from the UI to the background audio task, and these are defined as static methods in the AudioService class. They include:

• start
• play
• pause
• skipToNext
• skipToPrevious
• stop

The start and stop methods are special in that they also set up and tear down the background isolate.

Messages are received and handled by your background audio task by defining a subclass of BackgroundAudioTask and overriding corresponding callback methods:

• onStart
• onPlay
• onPause
• onSkipToNext
• onSkipToPrevious
• onStop

You need only override the particular callbacks that are useful in your app. There are additional standard messages, but if you need to send a message that is not among the predefined standard messages, you can use customAction/onCustomAction. None of these callbacks do anything by default, and it is entirely up to your app what code you want to execute in onPlay, onPause, onSkipToNext, and so on. This is where you actually write your code to play audio, or pause audio, or skip between different items.

Conversely, there are also a number of standard messages for communicating from the background audio task to the UI, and these are defined as static methods in the AudioServiceBackground class. They include:

• setState
• setQueue
• setMediaItem

Your background audio task should call setState to send a message to the UI whenever it changes audio playback states. The overall playback state is a collection of different states including whether or not audio is playing, whether or not audio is buffering, the playback position, the current playback speed and others. When your UI receives this message, it should update the UI to reflect the new state. Your background audio task should call setQueue to send a message to the UI whenever the queue (aka "playlist") changes, so that the UI can update its display (if you have one), and you should call setMediaItem to send a message to the UI whenever the currently playing item changes so that the UI can display this updated information.

Note: The media notification will not show until after the first time you call setState(playing: true, ...) AND after you provide information about the currently playing item by calling setMediaItem.

Your Flutter UI receives these messages not via callbacks but instead by listening to the following streams:

• AudioService.playbackStateStream
• AudioService.queueStream
• AudioService.currentMediaItemStream

This plugin defines a standard set of messages for the following reason: this set of messages can also be understood by other user interfaces besides your Flutter UI, including: smart watches, Android Auto, headphones with play/pause/skip buttons, lock screen, Android media notifications, and the iOS control center. Thus, when your background audio task sends the setState message to indicate a transition from playing==true to playing==false, this message will be received not only your Flutter UI, but also your lock screen, your car's Android Auto, and so on. Conversely, if you press the play button on one of these other UIs (e.g. on your watch), this message will be delivered to your background audio task allowing you to process play/pause requests from any connected UI.

Your Flutter UI can only send and receive messages to and from the background audio task while it is connected. You can wrap your application in an AudioServiceWidget to automatically maintain a connection. Otherwise you can manually call AudioService.connect when your UI becomes visible and AudioService.disconnect when your UI is gone.

Starting and stopping a background audio task

Let's start with a simple app with a button to start playing an MP3, and a button to stop playing.

void main() => runApp(new MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Example',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: AudioServiceWidget(child: MainScreen()),
    );
  }
}

The AudioServiceWidget should be inserted near the top of the widget tree to automatically maintain the audio service connection across every route in your app.

Next, define the main screen with two buttons:

class MainScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text("Example")),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            ElevatedButton(child: Text("Start"), onPressed: start),
            ElevatedButton(child: Text("Stop"), onPressed: stop),
          ],
        ),
      ),
    );
  }

  start() =>
      AudioService.start(backgroundTaskEntrypoint: _backgroundTaskEntrypoint);

  stop() => AudioService.stop();
}

With the UI more or less complete, we now must implement the background audio task which runs in the background isolate. To do this, we define _backgroundTaskEntrypoint which must be a top-level function that initialises the isolate by calling AudioServiceBackground.run as the very first line:

_backgroundTaskEntrypoint() {
  AudioServiceBackground.run(() => AudioPlayerTask());
}

Now you can define your audio task which encapsulates all of your audio playing code:

import 'package:just_audio/just_audio.dart';

class AudioPlayerTask extends BackgroundAudioTask {
  final _audioPlayer = AudioPlayer();
  final _completer = Completer();

  @override
  Future<void> onStart(Map<String, dynamic> params) async {
    // Connect to the URL
    await _audioPlayer.setUrl("https://exampledomain.com/song.mp3");
    // Now we're ready to play
    _audioPlayer.play();
  }

  @override
  Future<void> onStop() async {
    // Stop playing audio
    await _audioPlayer.stop();
    // Shut down this background task
    await super.onStop();
  }
}

When the UI calls AudioService.start, the background isolate is created, and your onStart callback is called within that isolate. When the UI calls AudioService.stop, your onStop callback is called within the background isolate and the isolate is destroyed as soon as this method completes. In the above example, we use onStart to start audio playback, and onStop to stop audio playback.

You are free to implement the background audio task callbacks in any way that is appropriate for your app. For example, the following alternative task will use text-to-speech to speak the numbers 1 to 10:

import 'package:flutter_tts/flutter_tts.dart';

class AudioPlayerTask extends BackgroundAudioTask {
  final _tts = FlutterTts();
  bool _finished = false;
  Completer _completer = Completer();

  @override
  Future<void> onStart() async {
    for (var n = 1; !_finished && n <= 10; n++) {
      _tts.speak("$n");
      await Future.delayed(Duration(seconds: 1);
    }
    _completer.complete();
  }

  @override
  void onStop() {
    // Stop speaking the numbers
    _finished = true;
    // Wait for `onStart` to complete
    await _completer.future;
    // Now we're ready to let the isolate shut down
    await super.onStop();
  }
}

Pausing and resuming playback

In the previous example, each time the user presses start and stop, audio_service has to spin up a new isolate and shut it down. This comes with a lot of overheads since audio_service will interface with the platform to properly set up the background execution environment. Instead, an app will typically provide a pause button which puts your app into a state that is not completely dead and is ready to quickly resume playback on demand via a play button.

Let's add play and pause buttons to our app:

class MainScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
            ...
            ElevatedButton(child: Text("Play"), onPressed: play),
            ElevatedButton(child: Text("Pause"), onPressed: pause),
            ...
  }

  ...

  play() => AudioService.play();

  pause() => AudioService.pause();
}

Now let's implement the callbacks in the background audio task:

class AudioPlayerTask extends BackgroundAudioTask {
  ...

  @override
  void onPlay() {
    _audioPlayer.play();
  }

  @override
  void onPause() {
    _audioPlayer.pause();
  }
}

That's it!

Updating the UI in response to state changes

There's one problem with the previous example: The 4 buttons are always visible. Ideally, the visible buttons should reflect the current state of the background audio task. Let's modify the example to manage state changes.

In the following code, we will update the background audio task to broadcast 3 different kinds of state:

1. playing (true or false)
2. processingState (connecting, ready to play or stopped)
3. controls (the set of controls visible in the iOS control center and Android notification)

Let's update the background audio task to broadcast appropriate state changes:

class AudioPlayerTask extends BackgroundAudioTask {
  final AudioPlayer _audioPlayer = AudioPlayer();

  @override
  Future<void> onStart(Map<String, dynamic> params) async {
    // Broadcast that we're connecting, and what controls are available.
    AudioServiceBackground.setState(
        controls: [MediaControl.pause, MediaControl.stop],
        playing: true,
        processingState: AudioProcessingState.connecting);
    // Connect to the URL
    await _audioPlayer.setUrl("https://exampledomain.com/song.mp3");

    // Now we're ready to play
    _audioPlayer.play();
    // Broadcast that we're playing, and what controls are available.
    AudioServiceBackground.setState(
        controls: [MediaControl.pause, MediaControl.stop],
        playing: true,
        processingState: AudioProcessingState.ready);
  }

  @override
  Future<void> onStop() async {
    // Stop playing audio.
    _audioPlayer.stop();
    // Broadcast that we've stopped.
    await AudioServiceBackground.setState(
        controls: [],
        playing: false,
        processingState: AudioProcessingState.stopped);
    // Shut down this background task
    await super.onStop();
  }

  @override
  void onPlay() {
    // Broadcast that we're playing, and what controls are available.
    AudioServiceBackground.setState(
        controls: [MediaControl.pause, MediaControl.stop],
        playing: true,
        processingState: AudioProcessingState.ready);
    // Start playing audio.
    _audioPlayer.play();
  }

  @override
  void onPause() {
    // Broadcast that we're paused, and what controls are available.
    AudioServiceBackground.setState(
        controls: [MediaControl.play, MediaControl.stop],
        playing: false,
        processingState: AudioProcessingState.ready);
    // Pause the audio.
    _audioPlayer.pause();
  }
}

All UIs should now reflect these state changes, except for the Flutter UI itself for which we'll need to write our own code to make that happen. To do that, we will listen to the AudioService.playbackStateStream. Flutter provides an easy way to make a widget responsive to the changing values of a stream using StreamBuilder:

class MainScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text("Example")),
      body: Center(
        child: StreamBuilder<PlaybackState>(
          stream: AudioService.playbackStateStream,
          builder: (context, snapshot) {
            final playing = snapshot.data?.playing ?? false;
            final processingState = snapshot.data?.processingState
                ?? AudioProcessingState.stopped;
            return Column(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                if (playing)
                  ElevatedButton(child: Text("Pause"), onPressed: pause)
                else
                  ElevatedButton(child: Text("Play"), onPressed: play),
                if (processingState != BasicPlaybackState.stopped)
                  ElevatedButton(child: Text("Stop"), onPressed: stop),
              ],
            );
          },
        ),
      ),
    );
  }

  play() async {
    if (await AudioService.running) {
      AudioService.play();
    } else {
      AudioService.start(backgroundTaskEntrypoint: _backgroundTaskEntrypoint);
    }
  }

  pause() => AudioService.pause();

  stop() => AudioService.stop();
}

In the above example, we show either the "play" or the "pause" button depending on the current state, but never both at the same time. We show the "stop" button only if we are currently not stopped. We also have merged the "start" button into the "play" button so that "play" will first check if the service is already running, and if it is, it calls the play method, and otherwise calls the start method.

Conclusion

We have now come full circle. In the Flutter UI, we define buttons that send messages to the background audio task. The background audio task plays audio and modifies playback according to those messages it receives. The background audio task also broadcasts state changes back to the Flutter UI, where the UI updates itself according to the new state.

Using this message passing system, your Flutter UI will also update correctly in response to pressing the play/pause buttons on your headset, your smart watch, and other compatible UIs.

For a more complete example with a queue, skip buttons and seeking, you are encouraged to refer to audio_service/example.