连接到媒体应用

您可以通过以下两种方式连接到媒体应用：

  1. MediaController
  2. MediaBrowser

MediaController

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

媒体控制器在媒体应用中也很有用，例如，如果播放器和媒体会话位于与 Activity 或包含界面的 Fragment 分开的 Service 中。

创建 MediaController

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

Kotlin

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

Java

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

使用此 SessionToken 构建 MediaController 可将控制器连接到指定会话。此过程以异步方式进行，因此您应监听结果并在结果可用时使用。

Kotlin

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

Java

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

使用 MediaController

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

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

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

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

Kotlin

val controllerFuture =
  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()
ConnectToMediaApp.kt

Java

ListenableFuture<MediaController> controllerFuture =
    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();
ConnectToMediaApp.java

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

Kotlin

MediaController.releaseFuture(controllerFuture)
ConnectToMediaApp.kt

Java

MediaController.releaseFuture(controllerFuture);
ConnectToMediaApp.java

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

MediaBrowser

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

创建 MediaBrowser

Kotlin

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

Java

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

使用 MediaBrowser

如需开始浏览媒体应用的内容库，请先使用 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(),
)
ConnectToMediaApp.kt

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());
ConnectToMediaApp.java

然后，您可以通过使用 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(),
)
ConnectToMediaApp.kt

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());
ConnectToMediaApp.java

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

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

如需根据界面约束条件和要求解析应用的偏好设置，请使用 CommandButton.DisplayConstraints。您可以定义界面可以执行的操作的限制和限制，而 resolve 方法提供了一个明确的按钮列表，其中包含要显示的按钮及其图标、位置和预期操作。如果用户点击其中一个按钮，您可以使用 CommandButton.executeAction 在媒体应用中触发关联的操作。

Kotlin

// Get media button preferences from media app
val mediaButtonPreferences = controller.getMediaButtonPreferences()
// Declare constraints of UI (example: limit overflow button to one)
val displayConstraints =
  DisplayConstraints.Builder().setMaxButtonsForSlot(CommandButton.SLOT_OVERFLOW, 1).build()
// Resolve media app preferences with constraints
val resolvedButtons = displayConstraints.resolve(mediaButtonPreferences, controller)
// Display buttons in UI
for (button in resolvedButtons) {
  generateUiButton(
    uiPosition = button.slots[0],
    icon = getIconRes(button.icon),
    onClick = { button.executeAction(controller) },
  )
}
ConnectToMediaApp.kt

Java

// Get media button preferences from media app
List<CommandButton> mediaButtonPreferences = controller.getMediaButtonPreferences();
// Declare constraints of UI (example: limit overflow button to one)
DisplayConstraints displayConstraints =
    new DisplayConstraints.Builder()
        .setMaxButtonsForSlot(CommandButton.SLOT_OVERFLOW, 1)
        .build();
// Resolve media app preferences with constraints
List<CommandButton> resolvedButtons =
    displayConstraints.resolve(mediaButtonPreferences, controller);
// Display buttons in UI
for (CommandButton button : resolvedButtons) {
  generateUiButton(
      /* uiPosition= */ button.slots.get(0),
      /* icon= */ getIconRes(button.icon),
      /* onClick= */ () -> button.executeAction(controller));
}
ConnectToMediaApp.java