MediaSession.md

MediaSession

MediaSession from Media3 is needed in some cases:

• Intent to use the player on TV.
• Intent to use the player on Android Auto.
• When playing content in the background with a media notification.
• Handle actions button from headset or remote devices.

Pillarbox enhanced MediaSession with Pillarbox special features, every original Media3 classes have their equivalent in Pillarbox:

• MediaSession : PillarboxMediaSession
• MediaSessionService : PillarboxMediaSessionService
• MediaController : PillarboxMediaController
• MediaLibrarySession : PillarboxMediaLibrarySession
• MediaLibraryService : PillarboxMediaLibraryService
• MediaBrowser: PillarboxMediaBrowser

Connect the player to the MediaSession

val mediaSession = PillarboxMediaSession.Builder(context, player).build()

Remember to release the MediaSession when you no longer need it, or when releasing the player, with:

mediaSession.release()

More information about MediaSession is available here.

System integration and background playback

AndroidX Media3 library recommends to use MediaSessionService or MediaLibraryService to do background playback. MediaLibraryService is useful when the application needs to connect to Android Auto or Automotive. Pillarbox provides an implementation of each service type to help you handle them.

PillarboxMediaSessionService

To use that service, you need to declare it inside your AndroidManifest.xml, as follows:

<service android:exported="true" android:foregroundServiceType="mediaPlayback" android:name=".service.DemoMediaSessionService">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaSessionService" />
    </intent-filter>
</service>

And enable foreground service at the top of the manifest:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

<!-- Only necessary if your target SDK version is 34 or newer -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />

Then, in your code, you have to use PillarboxMediaController to handle playback, instead of PillarboxExoPlayer. Pillarbox provides an easy way to retrieve the MediaController with PillarboxMediaController.Builder.

coroutineScope.launch {
    val mediaController: PillarboxPlayer = PillarboxMediaController.Builder(context, DemoMediaLibraryService::class.java).build()
    doSomethingWith(mediaController)
}

PillarboxMediaLibraryService

PillarboxMediaLibraryService has the same features as PillarboxMediaSessionService, but it allows the application to provide content with MediaBrowser. More information about Android Auto.

To use that service, you need to declare it inside the application manifest as follows:

<service android:exported="true" android:foregroundServiceType="mediaPlayback" android:name=".service.DemoMediaLibraryService">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaLibraryService" />
        <action android:name="android.media.browse.MediaBrowserService" />
    </intent-filter>
</service>

Declare the application as an Android Auto application:

<meta-data android:name="com.google.android.gms.car.application" android:resource="@xml/automotive_app_desc" />

In the res/xml/automotive_app_desc.xml file, add the following:

<?xml version="1.0" encoding="utf-8"?>
<automotiveApp>
    <uses name="media" />
</automotiveApp>

And enable foreground service at the top of the manifest:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

Then, in your code, you have to use PillarboxMediaBrowser to handle playback, instead of PillarboxExoPlayer. Pillarbox provides an easy way to retrieve the MediaBrowser with PillarboxMediaBrowser.Builder.

coroutineScope.launch {
    val mediaBrowser: PillarboxPlayer = PillarboxMediaBrowser.Builder(context, DemoMediaLibraryService::class.java).build()
    doSomethingWith(mediaBrowser)
}