Serve content with a MediaLibraryService

Media apps often contain collections of media items, organized in a hierarchy. For example, songs in an album or TV episodes in a playlist. This hierarchy of media items is known as a media library.

Examples of media content arranged in a hierarchy
Figure 1:Examples of media item hierarchies that form a media library.

AMediaLibraryServiceprovides a standardized API to serve and access your media library. This can be helpful, for example, when adding support for Android Autoto your media app, which provides its own driver-safe UI for your media library.

Build aMediaLibraryService

Implementing aMediaLibraryServiceis similar to implementing aMediaSessionService, except that in theonGetSession()method, you should return aMediaLibrarySessioninstead of aMediaSession.

Kotlin

classPlaybackService:MediaLibraryService(){
varmediaLibrarySession:MediaLibrarySession?=null
varcallback:MediaLibrarySession.Callback=object:MediaLibrarySession.Callback{...}

// If desired, validate the controller before returning the media library session
overridefunonGetSession(controllerInfo:MediaSession.ControllerInfo):MediaLibrarySession?=
mediaLibrarySession

// Create your player and media library session in the onCreate lifecycle event
overridefunonCreate(){
super.onCreate()
valplayer=ExoPlayer.Builder(this).build()
mediaLibrarySession=MediaLibrarySession.Builder(this,player,callback).build()
}

// Remember to release the player and media library session in onDestroy
overridefunonDestroy(){
mediaLibrarySession?.run{
player.release()
release()
mediaLibrarySession=null
}
super.onDestroy()
}
}

Java

classPlaybackServiceextendsMediaLibraryService{
MediaLibrarySessionmediaLibrarySession=null;
MediaLibrarySession.Callbackcallback=newMediaLibrarySession.Callback(){...};

@Override
publicMediaLibrarySessiononGetSession(MediaSession.ControllerInfocontrollerInfo){
// If desired, validate the controller before returning the media library session
returnmediaLibrarySession;
}

// Create your player and media library session in the onCreate lifecycle event
@Override
publicvoidonCreate(){
super.onCreate();
ExoPlayerplayer=newExoPlayer.Builder(this).build();
mediaLibrarySession=newMediaLibrarySession.Builder(this,player,callback).build();
}

// Remember to release the player and media library session in onDestroy
@Override
publicvoidonDestroy(){
if(mediaLibrarySession!=null){
mediaLibrarySession.getPlayer().release();
mediaLibrarySession.release();
mediaLibrarySession=null;
}
super.onDestroy();
}
}

Remember to declare yourServiceand required permissions in the manifest file as well:

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

<uses-permissionandroid:name= "android.permission.FOREGROUND_SERVICE"/>
<!--FortargetSdk34+-->
<uses-permissionandroid:name= "android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK"/>

Use aMediaLibrarySession

TheMediaLibraryServiceAPI expects your media library to be structured in a tree format, with a single root node and children nodes that may be playable or furtherbrowsable.

AMediaLibrarySession extends theMediaSessionAPI to add content browsing APIs. Compared to the MediaSessioncallback, theMediaLibrarySessioncallback adds methods such as:

  • onGetLibraryRoot() for when a client requests the rootMediaItemof a content tree
  • onGetChildren() for when a client requests the children of aMediaItemin the content tree
  • onGetSearchResult() for when a client requests search results from the content tree for a given query

Relevant callback methods will include aLibraryParams object with additional signals about the type of content tree that a client app is interested in.