使用 MediaLibraryService 提供内容

媒体应用通常包含以层次结构组织的媒体内容集合。例如，专辑中的歌曲或播放列表中的电视剧集。这种媒体内容的层次结构称为媒体库。

图 1：构成媒体库的媒体内容层次结构示例。

MediaLibraryService 提供标准化 API 来提供和访问媒体库。例如，当向媒体应用添加对 Android Auto 的支持时，这会很有用，因为 Android Auto 会为您的媒体库提供自己的驾驶员安全界面。

构建 MediaLibraryService

实现 MediaLibraryService 与实现 MediaSessionService 类似，但在 onGetSession() 方法中，您应返回 MediaLibrarySession，而不是 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();
  }
}

请务必在清单文件中声明 Service 和必需的权限：

<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" />

注意 ：为了与使用旧版媒体 API 的客户端保持向后兼容性，您还可以在 intent-filter 元素中添加 <action android:name="android.media.browse.MediaBrowserService"/>。

使用 MediaLibrarySession

MediaLibraryService API 要求您的媒体库采用树形结构，其中包含一个根节点和可能可播放或进一步浏览的子节点。

MediaLibrarySession 会扩展 MediaSession API 以添加内容浏览 API。与 MediaSession 回调相比，MediaLibrarySession 回调添加了以下方法：

• onGetLibraryRoot()（适用于客户端请求内容树的根 MediaItem 时）
• onGetChildren() 适用于客户端请求内容树中 MediaItem 的子项的情况
• onGetSearchResult()（适用于客户端针对给定查询从内容树请求搜索结果的情况）

相关回调方法将包含 LibraryParams 对象，其中包含有关客户端应用感兴趣的内容树类型的其他信号。

媒体内容的命令按钮

会话应用可以在 MediaMetadata 中声明 MediaItem 支持的命令按钮。这样，您就可以向控制器可以显示的媒体内容分配一个或多个 CommandButton 条目，并使用这些条目以便以便捷的方式向会话发送内容的自定义命令。

在会话端设置命令按钮

构建会话时，会话应用会声明会话可以处理的一组命令按钮作为自定义命令：

Kotlin

val allCommandButtons =
  listOf(
    CommandButton.Builder(CommandButton.ICON_PLAYLIST_ADD)
      .setDisplayName(context.getString(R.string.add_to_playlist))
      .setDisplayName("Add to playlist")
      .setIconResId(R.drawable.playlist_add)
      .setSessionCommand(SessionCommand(COMMAND_PLAYLIST_ADD, Bundle.EMPTY))
      .setExtras(playlistAddExtras)
      .build(),
    CommandButton.Builder(CommandButton.ICON_RADIO)
      .setDisplayName(context.getString(R.string.radio_station))
      .setIconResId(R.drawable.radio)
      .setSessionCommand(SessionCommand(COMMAND_RADIO, Bundle.EMPTY))
      .setExtras(radioExtras)
      .build(),
    // possibly more here
  )

// Add all command buttons for media items supported by the session.
val session =
  MediaSession.Builder(context, player)
    .setCommandButtonsForMediaItems(allCommandButtons)
    .build()

Java

ImmutableList<CommandButton> allCommandButtons =
    ImmutableList.of(
        new CommandButton.Builder(CommandButton.ICON_PLAYLIST_ADD)
            .setDisplayName("Add to playlist")
            .setIconUri(Uri.parse("http://www.example.com/icon/playlist_add"))
            .setSessionCommand(new SessionCommand(COMMAND_PLAYLIST_ADD, Bundle.EMPTY))
            .setExtras(playlistAddExtras)
            .build(),
        new CommandButton.Builder(CommandButton.ICON_RADIO)
            .setDisplayName("Radio station")
            .setIconUri(Uri.parse("http://www.example.com/icon/radio"))
            .setSessionCommand(new SessionCommand(COMMAND_RADIO, Bundle.EMPTY))
            .setExtras(radioExtras)
            .build());

// Add all command buttons for media items supported by the session.
MediaSession session =
    new MediaSession.Builder(context, player)
        .setCommandButtonsForMediaItems(allCommandButtons)
        .build();

注意： 通过媒体通知提供的 Android 媒体控件不会使用媒体内容的命令按钮。使用自定义布局声明移动设备上的 Android 媒体控件应使用的命令按钮。

构建媒体内容时，会话应用可以添加一组受支持的命令 ID，这些 ID 会引用在构建会话时设置的命令按钮的会话命令：

Kotlin

val mediaItem =
  MediaItem.Builder()
    .setMediaMetadata(
      MediaMetadata.Builder()
        .setSupportedCommands(listOf(COMMAND_PLAYLIST_ADD, COMMAND_RADIO))
        .build())
    .build()

Java

MediaItem mediaItem =
    new MediaItem.Builder()
        .setMediaMetadata(
            new MediaMetadata.Builder()
                .setSupportedCommands(ImmutableList.of(COMMAND_PLAYLIST_ADD, COMMAND_RADIO))
                .build())
        .build();

注意： 控制器仅会看到会话为其提供了相应会话命令的命令按钮。

当控制器或浏览器连接或调用会话 Callback 的其他方法时，会话应用可以检查传递给回调的 ControllerInfo，以获取控制器或浏览器可以显示的命令按钮的数量上限。传递给回调方法的 ControllerInfo 会提供一个用于方便地访问此值的 getter。默认情况下，此值设为 0，表示浏览器或控制器不支持此功能：

Kotlin

override fun onGetItem(
  session: MediaLibrarySession,
  browser: MediaSession.ControllerInfo,
  mediaId: String,
): ListenableFuture<LibraryResult<MediaItem>> {

  val settableFuture = SettableFuture.create<LibraryResult<MediaItem>>()

  val maxCommandsForMediaItems = browser.maxCommandsForMediaItems
  scope.launch {
    loadMediaItem(settableFuture, mediaId, maxCommandsForMediaItems)
  }

  return settableFuture
}

Java

@Override
public ListenableFuture<LibraryResult<MediaItem>> onGetItem(
    MediaLibraryService.MediaLibrarySession session, ControllerInfo browser, String mediaId) {

  SettableFuture<LibraryResult<MediaItem>> settableFuture = SettableFuture.create();

  int maxCommandsForMediaItems = browser.getMaxCommandsForMediaItems();
  loadMediaItemAsync(settableFuture, mediaId, maxCommandsForMediaItems);

  return settableFuture;
}

处理针对媒体内容发送的自定义操作时，会话应用可以从传入 onCustomCommand 的参数 Bundle 中获取媒体内容 ID：

Kotlin

override fun onCustomCommand(
  session: MediaSession,
  controller: MediaSession.ControllerInfo,
  customCommand: SessionCommand,
  args: Bundle,
): ListenableFuture<SessionResult> {
  val mediaItemId = args.getString(MediaConstants.EXTRA_KEY_MEDIA_ID)
  return if (mediaItemId != null)
    handleCustomCommandForMediaItem(controller, customCommand, mediaItemId, args)
  else handleCustomCommand(controller, customCommand, args)
}

Java

@Override
public ListenableFuture<SessionResult> onCustomCommand(
    MediaSession session,
    ControllerInfo controller,
    SessionCommand customCommand,
    Bundle args) {
  String mediaItemId = args.getString(MediaConstants.EXTRA_KEY_MEDIA_ID);
  return mediaItemId != null
      ? handleCustomCommandForMediaItem(controller, customCommand, mediaItemId, args)
      : handleCustomCommand(controller, customCommand, args);
}

将命令按钮用作浏览器或控制器

在 MediaController 端，应用可以在构建 MediaController 或 MediaBrowser 时声明其支持的媒体内容的命令按钮数量上限：

Kotlin

val browserFuture =
  MediaBrowser.Builder(context, sessionToken)
    .setMaxCommandsForMediaItems(3)
    .buildAsync()

Java

ListenableFuture<MediaBrowser> browserFuture =
    new MediaBrowser.Builder(context, sessionToken)
        .setMaxCommandsForMediaItems(3)
        .buildAsync();

注意 ：默认情况下，命令数量设置为 0（零），这会建议会话应用不要为该浏览器或控制器通告命令按钮。

连接到会话后，控制器应用可以接收媒体内容支持的命令按钮，并且控制器对这些按钮拥有会话应用授予的可用命令：

Kotlin

val commandButtonsForMediaItem: List<CommandButton> =
  controller.getCommandButtonsForMediaItem(mediaItem)

Java

ImmutableList<CommandButton> commandButtonsForMediaItem =
    controller.getCommandButtonsForMediaItem(mediaItem);

注意： 返回的命令按钮是会话设置的所有按钮、媒体内容上设置的受支持命令以及控制器的可用命令的交集。

为方便起见，MediaController 可以使用 MediaController.sendCustomCommand(SessionCommand, MediaItem, Bundle) 发送媒体内容专用自定义命令：

Kotlin

controller.sendCustomCommand(addToPlaylistButton.sessionCommand!!, mediaItem, Bundle.EMPTY)

Java

controller.sendCustomCommand(
    checkNotNull(addToPlaylistButton.sessionCommand), mediaItem, Bundle.EMPTY);