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.

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

Build a `MediaLibraryService`

Implementing a MediaLibraryService is similar to implementing a MediaSessionService, except that in the onGetSession() method, you should return a MediaLibrarySession instead of a MediaSession.

Kotlin

class PlaybackService : MediaLibraryService() {
  var mediaLibrarySession: MediaLibrarySession? = null
  var callback: MediaLibrarySession.Callback = object : MediaLibrarySession.Callback {...}

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

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

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

Java

class PlaybackService extends MediaLibraryService {
  MediaLibrarySession mediaLibrarySession = null;
  MediaLibrarySession.Callback callback = new MediaLibrarySession.Callback() {...};

  @Override
  public MediaLibrarySession onGetSession(MediaSession.ControllerInfo controllerInfo) {
    // If desired, validate the controller before returning the media library session
    return mediaLibrarySession;
  }

  // Create your player and media library session in the onCreate lifecycle event
  @Override
  public void onCreate() {
    super.onCreate();
    ExoPlayer player = new ExoPlayer.Builder(this).build();
    mediaLibrarySession = new MediaLibrarySession.Builder(this, player, callback).build();
  }

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

Remember to declare your Service and required permissions in the manifest file as well:

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

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<!-- For targetSdk 34+ -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />

Use a `MediaLibrarySession`

The MediaLibraryService API expects your media library to be structured in a tree format, with a single root node and children nodes that may be playable or further browsable.

A MediaLibrarySession extends the MediaSession API to add content browsing APIs. Compared to the MediaSession callback, the MediaLibrarySession callback adds methods such as:

onGetLibraryRoot() for when a client requests the root MediaItem of a content tree
onGetChildren() for when a client requests the children of a MediaItem in the content tree
onGetSearchResult() for when a client requests search results from the content tree for a given query

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