In this post, we’ll learn about Android MediaSession API, why we should use it, and how to implement it on Android TV (or Fire TV) apps. After setting the ground, we’ll follow a step-by-step guide on a basic MediaSession implementation. The sample app used for this article and all the code below can be found here.

If you need to become more familiar with or need a recap on how playback controls are implemented using the Leanback components, check my previous articles. I cover from the basics to further customizations on the Leanback playback controls.

Spotify MediaSession notification

What are the benefits?

The benefits of implementing the MediaSession in our apps vary from device to device.

• The media playback can be controlled by voice on devices that support Google Assistant or other kinds of voice assistant.
• On TV devices that support HDMI-CEC, the playback can be controlled using the conventional remote control media keys.
• On phones, on-screen media controls. Depending on the Android version, the OS can get information about a MediaSession and provide media controls that will appear on the lock screen.
• It also enables other devices, for example, wearables, to connect to your app’s media session and control it from your wrist.
• Provide a way for other apps to control your MediaSession. For example, a navigation app can request a music player to play your favorite playlist when you start driving.

This is a powerful API. It’s not just about transport controls (play, pause, etc.) or displaying the content metadata. It’s also about sending specific media playback requests to an app capable of handling and performing them. This is what allows you to say confidently:

“Hey Google, play The Suburbs from Arcade Fire on Spotify.”

Step-by-Step Implementation Guide

Setting up the project

The first step is to add the androidx.media dependency on your app build.gradle.

implementation "androidx.media:media:1.6.0"

After that, and only if you plan to target Amazon Fire TV devices, you must add the following permission and, optionally, a meta-data to the AndroidManifest.xml.

AndroidManifest.xml

Note: The com.amazon.voice.supports_background_media_session metadata is optional, and the behavior change from its usage is described here.

Creating the MediaSession

To create a MediaSession, the only required arguments are a Context, and a String tag used to identify the MediaSession when debugging.

private val mediaSession = MediaSessionCompat(context, "VideoPlayback")

Conceptually, a MediaSession should live as long as the media player lives. On video apps, this usually means as long as the Activity or Fragment with the playback UI is in the foreground. Meanwhile, an audio app MediaSession might have the same lifecycle of the Service that holds the player instance, as they usually support background playback.

With this in mind, I decided to manage the MediaSession lifecycle for the sample app completely inside the SimplePlaybackTransportControlGlue as it receives all the callbacks about the host lifecycle, in this case, a VideoSupportFragment.

Then, we start the MediaSession configuration by providing a listener that will be called whenever media actions are dispatched. We do so by calling the MediaSession.setCallback() function and passing an instance of MediaSessionComapt.Callback. Inside these callbacks, we’ll perform the play, pause, seek, and any other operation supported by our MediaSession.

Custom Callback class inside SimplePlaybackTransportControlGlue

For the callbacks to be called, though, the MediaSession must be active. We can activate and deactivate a MediaSession by calling MediaSession.isActive = true/false.

Playback State

Once you have the playback information about your media, you should pass it on to the MediaSession. For that, we use the PlaybackState class. This is how the MediaSession knows which actions are available and the current playback state.

The existing playback states for a MediaSession, and their documentation can be found inside the PlaybackStateCompat class or here. In short, they are: STATE_NONE, STATE_STOPPED, STATE_PAUSED, STATE_PLAYING, STATE_FAST_FORWARDING, STATE_REWINDING, STATE_BUFFERING, STATE_ERROR, STATE_CONNECTING, STATE_SKIPPING_TO_PREVIOUS, STATE_SKIPPING_TO_NEXT, and STATE_KIPPING_TO_QUEUE_ITEM.

We can store an Int value that represents the current playback state, and whenever it changes, we will update the MediaSession PlaybackState.

Still, inside the SimplePlaybackTransportControlGlue, we can listen to almost all player events we need. This was another reason I decided to let the MediaSession inside the glue.

Add the following code to your glue to listen to these events and update the playbackState value.

A few events aren’t available to the glue directly. More specifically, the buffering started/finished, and error events are sent to the glue host, the VideoPlaybackFragment. You can receive them on the host and forward them to the glue using public functions. (For simplicity, I decided not to add the error event as there are too many of them)

Playback Actions

We must pass to the MediaSession the actions that it supports. This information is passed as a bitmask of the available actions. At the time of writing, there are 22 different actions a MediaSession supports (check them here). Again, we’ll only support the most common media actions for simplicity.

Note: The supported actions should be updated based on your media playback. For example, if your app plays ads, usually, you shouldn’t allow the user to fast-forward or rewind when the ad is playing. In this case, you should update the PlaybackState and remove the ACTION_FAST_FORWARD, ACTION_REWIND, and any other action that should be prevented during ad playback. Look at the mediaSessionSupportedActions() from the sample app here to clarify this idea.

Setting MediaSession PlaybackState

After gathering all the information about the current playback status, you can pass it to the MediaSession like the following:

This article was previously published on proandroiddev.com