连接到媒体应用

媒体控制器与媒体会话互动，以查询和控制媒体应用的播放。在 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());