連線至媒體應用程式

媒體控制器會與媒體工作階段互動，查詢及控制媒體 播放。在 Media3 中，MediaController API 會實作 Player 介面。使用媒體的用戶端應用程式範例 控制器包括：

• Android 系統媒體控制項
• Android Wear OS 隨附應用程式
• Android Auto 和 Automotive OS
• 語音助理 (例如 Google 助理)
• Media Controller Test 應用程式

在媒體應用程式中，媒體控制器也很實用； 播放器和媒體工作階段位於獨立於 Activity 的 Service 中； 建議您透過 UI 設定 Fragment。

建立 MediaController

如要建立 MediaController，請先為SessionToken 對應的 MediaSession。Activity 或 Fragment 的 onStart() 方法是這項操作的理想位置。

KotlinJava

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

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

使用這個 SessionToken 接著建構 MediaController 會連結 指派給指定工作階段這項作業以非同步方式進行，因此您應該 聽取結果，並在結果可用的情況下使用

KotlinJava

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

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

注意：如果您在 UI 以外的程序中執行服務，請使用 ContextCompat.getMainExecutor() 而非 MoreExecutors.directExecutor()。

注意：指定目標為 SDK 級別 30 以上版本的應用程式，必須在資訊清單中加入 <queries> 元素，才能連線至其他應用程式的 MediaSessionService (或類似元件)。請參閱套件瀏覽權限 指南。

使用 MediaController

MediaController 會實作 Player 介面，因此您可以使用介面中定義的指令，控制已連線 MediaSession 的播放作業。也就是說，在 MediaController 上呼叫 play() 會將指令傳送至已連結的 MediaSession，後者隨後會將指令委派給其基礎 Player。

提示： 媒體控制器會實作 Player 介面，因此您可以 透過 UI 指派給播放器。

同樣地，您可以在控制器中新增 Player.Listener 來監聽 Player 狀態中的變更。詳情請參閱 「玩家事件」指南 進一步瞭解如何使用 Player.Listener。MediaController.Listener 介面會為 連結 MediaSession，例如 onAvailableSessionCommandsChanged() 觸發媒體工作階段變更可用的工作階段指令 onDisconnected() 。

如同其他元件，請記得在不再需要 MediaController 時釋放，例如在 Activity 或 Fragment 的 onStop() 方法中。

KotlinJava

MediaController.releaseFuture(controllerFuture)

MediaController.releaseFuture(controllerFuture);

儘管釋出控制器仍會將所有待處理的指令傳送至 而且必須在這些指令執行下列情況時，才與工作階段服務解除繫結 或逾時期限過後 (兩者取其先)。

建立及使用 MediaBrowser

MediaBrowser 可在 MediaController 提供的功能上加以建構，同時還能瀏覽媒體應用程式的 MediaLibraryService 所提供的媒體資料庫。

KotlinJava

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

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

如要開始瀏覽媒體應用程式的內容庫，請先使用 getLibraryRoot() 擷取根節點：

KotlinJava

// 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())

// 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 的子項：

KotlinJava

// 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())

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