此页面由 Cloud Translation API 翻译。

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

使用 `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();

构建媒体内容时，会话应用可以添加一组受支持的命令 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();

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

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);

使用 MediaLibraryService 提供内容

构建 MediaLibraryService

Kotlin

Java

使用 MediaLibrarySession

媒体内容的命令按钮

在会话端设置命令按钮

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

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

Kotlin

Java

Kotlin

Java

Kotlin

Java

构建 `MediaLibraryService`

使用 `MediaLibrarySession`