媒體控制器會與媒體工作階段互動,以查詢及控制媒體應用程式的播放作業。在 Media3 中,MediaController
API 會導入 Player
介面。以下列舉使用媒體控制器的用戶端應用程式範例:
- Android 系統媒體控制項
- Android Wear OS 隨附應用程式
- Android Auto 和 Automotive OS
- 語音助理 (例如 Google 助理)
- Media Controller Test 應用程式
媒體控制器在媒體應用程式中也相當實用,例如當播放器和媒體工作階段位於 Service
中,而非與 UI 中的 Activity
或 Fragment
分開時。
建立 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
的事件和傳入指令的其他回呼,例如 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());