连接到媒体应用

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

• Android 系统媒体控件
• Android Wear OS 配套应用
• Android Auto 和 Automotive OS
• 语音助理，例如 Google 助理
• “媒体控制器测试”应用

媒体控制器在媒体应用中也很有用，例如，如果播放器和媒体会话位于与界面的 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());

注意：如果您在界面以外的其他进程中运行服务，请使用 ContextCompat.getMainExecutor() 而不是 MoreExecutors.directExecutor()。

注意：以 SDK 级别 30 或更高级别为目标的应用必须在其清单中包含 <queries> 元素，以连接到其他应用的 MediaSessionService（或类似组件）。如需了解详情，请参阅软件包可见性指南。

使用 MediaController

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

提示： 媒体控制器实现了 Player 接口，因此，您可以在界面中将其分配给播放器。

同样，您可以向控制器添加 Player.Listener 以监听 Player 状态的变化。如需详细了解如何使用 Player.Listener，请参阅玩家事件指南。MediaController.Listener 接口定义了针对已连接 MediaSession 的事件和传入命令的其他回调，例如，为 onAvailableSessionCommandsChanged() 定义媒体会话更改可用会话命令时的回调，以及针对控制器与会话断开连接时使用的 onDisconnected() 进行定义。

与其他组件一样，请记住在不再需要 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());