Jetpack Media3 1.0.0-beta01 — What’s new?

Jetpack Media3 1.0.0-beta01 is now out! This post highlights some of the most significant changes. As always, we recommend also taking a look at the full release notes. Please note that the Jetpack Media3 1.0.0-beta01 release corresponds to the ExoPlayer 2.18.0 release.

Jetpack library versioning and API stability

Aligned with other Jetpack libraries, Media3 follows a semantic versioning scheme. One of the key benefits of using Jetpack libraries is API stability. If you use symbols that are part of the stable API, you generally don’t need to update your code to use a new release of that library within the same major version.

This implies that this first beta release is declared functionally stable and has an API surface that remains backwards compatible within the 1.x.x versions. In Media3, some of the most commonly used APIs are marked as stable, including the Player interface and media session classes.

APIs intended for more advanced use cases are marked as unstable. To use an unstable method or class without lint warnings, you’ll need to add the OptIn annotation before using it.

Opting-in in Java:

@OptIn(markerClass = UnstableApi.class)
private void methodUsingUnstableApis() { /* … */ }

Opting-in in Kotlin:

@OptIn(UnstableApi::class)
private fun methodUsingUnstableApis() { /* … */ }

If your project uses a lot of unstable methods it may be more convenient to add this suppression to your project-wide lint.xml.

<issue id=”UnsafeOptInUsageError”>
 <ignore
 regexp=”\(markerClass = androidx\.media3\.common\.util\.UnstableApi\.class\)” />
</issue>

Just because part of an API is marked as unstable doesn’t mean that the API is unreliable or that you shouldn’t use it — it’s just a way of informing you that it might change in the future. We also intend to stabilize additional parts of the API over time, in order to support more media use cases. If you have a use case that isn’t possible with the existing stable API, and you think it should be, please let us know the details via our issue tracker.

Changes in the session module

Adding media with MediaController

Adding items with MediaController has been simplified, it is now more flexible and supports asynchronously loading required data to complete a media item sent from the controller.

A new method onAddMediaItems() has been added to MediaSession.Callback. It is called when a controller has requested to add new media items to the playlist via one of the Player.addMediaItem(s) or Player.setMediaItem(s) methods. This allows for asynchronously loading media details, for instance from a local database to build a list of media items containing all the required local properties and metadata fields.

Loading media metadata is required because the media items sent from the controller to the session don’t have a MediaItem.LocalConfiguration, and so need to be replaced with a full media item that’s playable by the underlying Player. The MediaSession.Callback implementation is able to identify the correct item by its MediaItem.mediaId or MediaItem.requestMetadata.

The new callback method is further called when a legacy MediaControllerCompat client app like Google Assistant or Android Automotive OS calls one of the following methods:

• MediaControllerCompat.TransportControls.prepareFromUri
• MediaControllerCompat.TransportControls.playFromUri
• MediaControllerCompat.TransportControls.prepareFromMediaId
• MediaControllerCompat.TransportControls.playFromMediaId
• MediaControllerCompat.TransportControls.prepareFromSearch
• MediaControllerCompat.TransportControls.playFromSearch
• MediaControllerCompat.TransportControls.addQueueItem

The previous MediaItemFiller based API has been removed.

MediaNotification.Provider and DefaultMediaNotificationProvider

The MediaNotification.Provider is responsible for providing the media notification shown in the notification drawer. Apps can provide their own implementation or customize the DefaultMediaNotificationProvider that comes with the library. Using the DefaultMediaNotificationProvider makes sure that the notification is in sync with the custom layout on all API levels.

The DefaultMediaNotificationProvider uses a BitmapLoader for downloading artwork bitmaps. By default SimpleBitmapLoader is used. If you prefer to use a specific image downloading library like for instance Glide, you can inject your own bitmap loader.

Custom commands and custom layout

Custom commands are generally used by Android (System UI and Android Auto/Automotive OS) to allow apps to customize the playback controls displayed on a notification or the car UI. Media3 now implements custom session commands so that custom commands and the custom layout can be used by apps to tell Media3 how to render the media notification actions. Media3 then automatically replicates custom session commands to the legacy custom PlaybackStateCompat actions of the legacy session. A Media3 session by default receives custom commands at the session callback, no matter whether these are sent from a notification via PendingIntent (prior to Android 13) or directly to the MediaSession (starting with Android 13).

Interoperability improvements

Besides the new features, this release includes interoperability improvements on supported API levels. Thanks everyone for early testing and filing issues! One significant improvement is that MediaLibraryService/MediaSessionService now work nicely together with Android 12 since which the foreground service starting policy has been tightened. The DefaultMediaNotificationProvider now provides a unified approach for interoperability with all API levels including Android 13 with which system media controls start sending commands directly to the media session.

If you want to see this in code, take a look at the session demo app.

Changes in audio track selection

On handheld devices, the player now applies additional channel count constraints when selecting the audio track in order to save network and battery resources. Under these constraints, when the media has multiple audio tracks available:

• On Android 12L+ devices that support audio spatialization, the player will select a surround sound audio track only if the platform reports it will output spatialized audio. That is when audio spatialization is available, enabled and the audio format can be spatialized. Otherwise the player will prefer a stereo track. The player will listen to events reported from the Spatializer.OnSpatializerStateChangedListener and trigger a new track selection so that the selected audio track matches the current Spatializer properties. This will cause a short rebuffer when the spatializer properties change.
• On other devices, for Dolby surround formats (Dolby Digital, Dolby Digital Plus, Dolby Atmos) the previous behavior remains and the track with the highest channel count is preferred. For other audio formats, the player will prefer a stereo track over a surround sound one.

These changes are not applied on devices with a television UI mode.

You may turn off these constraints and switch back to the previous track selection logic by setting DefaultTrackSelection.Parameters.constrainAudioChannelCountToDeviceCapabilities to false.

Platform diagnostics

The new release integrates ExoPlayer with Android Platform Diagnostics from Android 12. This helps to provide performance and debugging information on the device, for example when using sysdump. If the user enabled sharing usage and diagnostics data, this data may also be collected by Google together with other existing platform diagnostics data from MediaCodec, AudioTrack or MediaDrm. Apps can opt-out of contributing to platform diagnostics for ExoPlayer with ExoPlayer.Builder.setUsePlatformDiagnostics(false).

Media3 documentation pages on DAC

At the same time as releasing the beta version, we’ve also published some initial Media3 documentation. Stay tuned for future updates of these pages and a migration guide that gives developers an overview of how to migrate from the legacy MediaSessionCompat/MediaBrowserServiceCompat to the latest Media3 stable APIs.

…

As always, we recommend taking a look at the full release notes. Please feel free to get in touch via our issue tracker if you have any questions or encounter problems with the new release. Thanks for reading!

p.s., we’re hiring!