连接到媒体应用

媒体控制器与媒体会话互动，以查询和控制媒体应用的播放。在 Media3 中，MediaController API 实现了 Player 接口。使用媒体控制器的客户端应用示例包括：

媒体控制器在媒体应用中也很有用，例如，如果播放器和媒体会话位于与界面一起使用的 Activity 或 Fragment 之外的 Service 中。

创建 MediaController

如需创建 MediaController，请先为相应的 MediaSession 创建 SessionToken。Activity 或 Fragment 的 onStart() 方法是一个不错的选择。

Kotlin

val sessionToken =
  SessionToken(context, ComponentName(context, PlaybackService::class.java))

Java

SessionToken sessionToken =
  new SessionToken(context, new ComponentName(context, PlaybackService.class));

然后，使用此 SessionToken 构建 MediaController 会将控制器连接到给定会话。这项操作是异步进行的，因此您应监听结果，并在有结果时使用。

Kotlin

val controllerFuture =
  MediaController.Builder(context, sessionToken).buildAsync()
controllerFuture.addListener({
  // MediaController is available here with controllerFuture.get()
}, MoreExecutors.directExecutor())

Java

ListenableFuture<MediaController> controllerFuture =
  new MediaController.Builder(context, sessionToken).buildAsync();
controllerFuture.addListener(() -> {
  // MediaController is available here with controllerFuture.get()
}, MoreExecutors.directExecutor());

使用 MediaController

MediaController 会实现 Player 接口，因此您可以使用接口中定义的命令来控制已连接的 MediaSession 的播放。也就是说，对 MediaController 调用 play() 会将命令发送到关联的 MediaSession，后者随后会将命令委托给其底层 Player。

您可以向控制器添加 Player.Listener，以监听 Player 状态的变化。如需详细了解如何使用 Player.Listener，请参阅玩家事件指南。

MediaController.Listener 接口为来自关联的 MediaSession 的事件和自定义命令定义了其他回调。例如，当会话发送自定义命令时发送 onCustomCommand()，当会话更改可用的会话命令时发送 onAvailableSessionCommandsChanged()，或者当控制器与会话断开连接时发送 onDisconnected()。

您可以在使用 Builder 构建控制器时设置 MediaController.Listener：

Kotlin

MediaController.Builder(context, sessionToken)
    .setListener(
      object : MediaController.Listener {
        override fun onCustomCommand(
          controller: MediaController,
          command: SessionCommand,
          args: Bundle,
        ): ListenableFuture<SessionResult> {
          // Handle custom command.
          return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
        }

        override fun onDisconnected(controller: MediaController) {
          // Handle disconnection.
        }
      }
    )
    .buildAsync()

Java

new MediaController.Builder(context, sessionToken)
    .setListener(
        new MediaController.Listener() {
          @Override
          public ListenableFuture<SessionResult> onCustomCommand(
              MediaController controller, SessionCommand command, Bundle args) {
            // Handle custom command.
            return Futures.immediateFuture(new SessionResult(SessionResult.RESULT_SUCCESS));
          }

          @Override
          public void onDisconnected(MediaController controller) {
            // Handle disconnection.
          }
        })
    .buildAsync();

与其他组件一样，请记得在不再需要 MediaController 时释放它，例如在 Activity 或 Fragment 的 onStop() 方法中。

Kotlin

MediaController.releaseFuture(controllerFuture)

Java

MediaController.releaseFuture(controllerFuture);

释放控制器后，系统仍会传送发送到会话的所有待处理命令，并且仅在处理完这些命令或超时期限结束后（以先到者为准）解除与会话服务的绑定。

创建和使用 MediaBrowser

MediaBrowser 基于 MediaController 提供的功能构建，还支持浏览媒体应用的 MediaLibraryService 提供的媒体库。

Kotlin

val browserFuture = MediaBrowser.Builder(context, sessionToken).buildAsync()
browserFuture.addListener({
  // MediaBrowser is available here with browserFuture.get()
}, MoreExecutors.directExecutor())

Java

ListenableFuture<MediaBrowser> browserFuture =
  new MediaBrowser.Builder(context, sessionToken).buildAsync();
browserFuture.addListener(() -> {
  // MediaBrowser is available here with browserFuture.get()
}, MoreExecutors.directExecutor());

如需开始浏览媒体应用的内容库，请先使用 getLibraryRoot() 检索根节点：

Kotlin

// Get the library root to start browsing the library tree.
val rootFuture = mediaBrowser.getLibraryRoot(/* params= */ null)
rootFuture.addListener({
  // Root node MediaItem is available here with rootFuture.get().value
}, MoreExecutors.directExecutor())

Java

// Get the library root to start browsing the library tree.
ListenableFuture<LibraryResult<MediaItem>> rootFuture =
  mediaBrowser.getLibraryRoot(/* params= */ null);
rootFuture.addListener(() -> {
  // Root node MediaItem is available here with rootFuture.get().value
}, MoreExecutors.directExecutor());

然后，您可以使用 getChildren() 检索库中 MediaItem 的子项，以便浏览媒体库。例如，如需检索根节点 MediaItem 的子节点，请执行以下操作：

Kotlin

// Get the library root to start browsing the library tree.
val childrenFuture = 
  mediaBrowser.getChildren(rootMediaItem.mediaId, 0, Int.MAX_VALUE, null)
childrenFuture.addListener({
  // List of children MediaItem nodes is available here with
  // childrenFuture.get().value
}, MoreExecutors.directExecutor())

Java

ListenableFuture<LibraryResult<ImmutableList<MediaItem>>> childrenFuture =
  mediaBrowser.getChildren(rootMediaItem.mediaId, 0, Integer.MAX_VALUE, null);
childrenFuture.addListener(() -> {
  // List of children MediaItem nodes is available here with
  // childrenFuture.get().value
}, MoreExecutors.directExecutor());

显示其他媒体应用的播放控件

在显示包含其他媒体应用按钮的界面控件时，请务必遵循该应用声明的媒体按钮偏好设置。

如需解决应用的偏好设置以及界面的约束条件和要求，最好的方法是使用 CommandButton.DisplayConstraints。您可以定义界面可以执行的限制和限制，并且 resolve 方法会提供一个明确的按钮列表，其中包含按钮的图标、位置和预期操作。