如要在應用程式中使用 MediaRouter 架構,您必須取得 MediaRouter 物件的例項,並附加 MediaRouter.Callback 物件來監聽轉送事件。透過媒體路徑傳送的內容會通過路徑相關聯的 MediaRouteProvider (少數特殊情況除外,例如藍牙輸出裝置)。圖 1 概略說明用於在裝置之間轉送內容的類別。
圖 1. 應用程式使用的主要媒體路由器類別總覽。
注意:如要讓應用程式支援 Google Cast 裝置,請使用 Cast SDK,並將應用程式建構為 Cast 傳送端。請按照 Cast 說明文件中的指示操作,不要直接使用 MediaRouter 架構。
媒體路徑按鈕
Android 應用程式應使用媒體路徑按鈕控制媒體路徑。MediaRouter 架構為按鈕提供標準介面,可協助使用者在可用時辨識及使用轉送功能。媒體路徑按鈕通常位於應用程式動作列的右側,如圖 2 所示。
圖 2. 動作列中的媒體路徑按鈕。
使用者按下媒體路徑按鈕時,可用的媒體路徑會顯示在清單中,如圖 3 所示。
圖 3. 按下媒體路徑按鈕後,系統會顯示可用的媒體路徑清單。
請按照下列步驟建立媒體路徑按鈕:
- 使用 AppCompatActivity
- 定義媒體路徑按鈕選單項目
- 建立 MediaRouteSelector
- 在動作列中新增媒體路徑按鈕
- 在活動生命週期中建立及管理 MediaRouter.Callback 方法
本節將說明前四個步驟。下一節將說明回呼方法。
使用 AppCompatActivity
在活動中使用媒體路由器架構時,應從 AppCompatActivity 擴充活動,並匯入 androidx.appcompat.app 套件。您必須將 androidx.appcompat:appcompat 和 androidx.mediarouter:mediarouter 支援程式庫新增至應用程式開發專案。如要進一步瞭解如何在專案中新增支援資料庫,請參閱「開始使用 Android Jetpack」。
注意:請務必使用媒體路由器架構的 androidx 實作。請勿使用舊版 android.media 套件。
定義媒體路徑按鈕選單項目
建立 XML 檔案,定義媒體路徑按鈕的選單項目。項目的動作應為 MediaRouteActionProvider 類別。以下是範例檔案:
<menu xmlns:android="http://schemas.android.com/apk/res/android" xmlns:app="http://schemas.android.com/apk/res-auto" > <item android:id="@+id/media_route_menu_item" android:title="@string/media_route_menu_title" app:actionProviderClass="androidx.mediarouter.app.MediaRouteActionProvider" app:showAsAction="always" /> </menu>
建立 MediaRouteSelector
媒體路徑按鈕選單中顯示的路徑由 MediaRouteSelector 決定。從 AppCompatActivity 擴充活動,並在建立活動時,從 onCreate() 方法呼叫 MediaRouteSelector.Builder 建構選取器,如以下程式碼範例所示。請注意,選取器會儲存在類別變數中,而允許的路線類型則是透過新增 MediaControlIntent 物件來指定:
class MediaRouterPlaybackActivity : AppCompatActivity() { private var mSelector: MediaRouteSelector? = null override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) // Create a route selector for the type of routes your app supports. mSelector = MediaRouteSelector.Builder() // These are the framework-supported intents. .addControlCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK) .build() } }
對大多數應用程式來說,唯一需要的路徑類型是 CATEGORY_REMOTE_PLAYBACK。這種路徑類型會將執行應用程式的裝置視為遙控器。連線的接收端裝置會處理所有內容資料擷取、解碼和播放作業。支援 Google Cast 的應用程式 (例如 Chromecast) 就是以這種方式運作。
部分製造商支援稱為「次要輸出」的特殊轉送選項。透過這項轉送功能,媒體應用程式會擷取、算繪影片或音樂,並直接串流至所選遠端接收器裝置的螢幕和/或喇叭。使用次要輸出,將內容傳送至支援無線功能的音樂系統或影片螢幕。如要啟用這些裝置的探索和選取功能,您必須將 CATEGORY_LIVE_AUDIO 或 CATEGORY_LIVE_VIDEO 控制類別新增至 MediaRouteSelector。您也需要建立及處理自己的 Presentation 對話方塊。
在動作列中新增媒體路徑按鈕
定義媒體路徑選單和 MediaRouteSelector 後,您現在可以將媒體路徑按鈕新增至活動。覆寫每個活動的 onCreateOptionsMenu() 方法,即可新增選項選單。
override fun onCreateOptionsMenu(menu: Menu): Boolean { super.onCreateOptionsMenu(menu) // Inflate the menu and configure the media router action provider. menuInflater.inflate(R.menu.sample_media_router_menu, menu) // Attach the MediaRouteSelector to the menu item. val mediaRouteMenuItem = menu.findItem(R.id.media_route_menu_item) val mediaRouteActionProvider = MenuItemCompat.getActionProvider(mediaRouteMenuItem) as MediaRouteActionProvider // Attach the MediaRouteSelector that you built in onCreate(). selector?.also(mediaRouteActionProvider::setRouteSelector) // Return true to show the menu. return true }
如要進一步瞭解如何在應用程式中實作動作列,請參閱動作列開發人員指南。
您也可以在任何檢視畫面中,將媒體路徑按鈕新增為 MediaRouteButton。您必須使用 setRouteSelector() 方法,將 MediaRouteSelector 附加至按鈕。如需將媒體路徑按鈕整合至應用程式的指南,請參閱 Google Cast 設計檢查清單。
MediaRouter 回呼
在同一部裝置上執行的所有應用程式都會共用單一 MediaRouter 執行個體及其路徑 (由應用程式的 MediaRouteSelector 依應用程式篩選)。每個活動都會使用自己的 MediaRouter.Callback 方法實作與 MediaRouter 通訊。每當使用者選取、變更或中斷連線路徑時,MediaRouter 都會呼叫回呼方法。
回呼中有多種方法可覆寫,以便接收轉送事件的相關資訊。實作 MediaRouter.Callback 類別時,至少應覆寫 onRouteSelected() 和 onRouteUnselected()。
由於 MediaRouter 是共用資源,因此應用程式需要管理 MediaRouter 回呼,以回應一般的活動生命週期回呼:
- 建立活動 (
onCreate(Bundle)) 時,請擷取MediaRouter的指標,並在應用程式的生命週期內保留該指標。 - 在活動顯示時 (
onStart()) 將回呼附加至 MediaRouter,並在活動隱藏時 (onStop()) 卸除回呼。
以下程式碼範例說明如何建立及儲存回呼物件、如何取得 MediaRouter 的例項,以及如何管理回呼。請注意,在 onStart() 中附加回呼時,請使用 CALLBACK_FLAG_REQUEST_DISCOVERY 旗標。這樣一來,MediaRouteSelector 就能重新整理媒體路徑按鈕的可用路徑清單。
class MediaRouterPlaybackActivity : AppCompatActivity() { private var mediaRouter: MediaRouter? = null private var mSelector: MediaRouteSelector? = null // Variables to hold the currently selected route and its playback client. private var mRoute: MediaRouter.RouteInfo? = null private var remotePlaybackClient: RemotePlaybackClient? = null // Define the Callback object and its methods, save the object in a class variable. private val mediaRouterCallback = object : MediaRouter.Callback() { override fun onRouteSelected( router: MediaRouter, route: MediaRouter.RouteInfo, reason: Int ) { Log.d(TAG, "onRouteSelected: route=$route") if (route.supportsControlCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)) { // Stop local playback (if necessary). // ... // Save the new route. mRoute = route // Attach a new playback client. remotePlaybackClient = RemotePlaybackClient(this@MediaRouterPlaybackActivity, route) // Start remote playback (if necessary). // ... } } override fun onRouteUnselected( router: MediaRouter, route: MediaRouter.RouteInfo, reason: Int ) { Log.d(TAG, "onRouteUnselected: route=$route") if (route.supportsControlCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)) { // Changed route: tear down previous client. mRoute?.also { remotePlaybackClient?.release() remotePlaybackClient = null } // Save the new route. mRoute = route when { reason != MediaRouter.UNSELECT_REASON_ROUTE_CHANGED -> { // Resume local playback (if necessary). // ... } } } } } // Retain a pointer to the MediaRouter. override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) // Get the media router service. mediaRouter = MediaRouter.getInstance(this) // ... } // Use this callback to run your MediaRouteSelector to generate the // list of available media routes. override fun onStart() { mSelector?.also { selector -> mediaRouter?.addCallback( selector, mediaRouterCallback, MediaRouter.CALLBACK_FLAG_REQUEST_DISCOVERY ) } super.onStart() } // Remove the selector on stop to tell the media router that it no longer // needs to discover routes for your app. override fun onStop() { mediaRouter?.removeCallback(mediaRouterCallback) super.onStop() } // ... }
媒體路由器架構也提供 MediaRouteDiscoveryFragment 類別,負責新增及移除活動的回呼。
注意:如果您正在編寫音樂播放應用程式,並希望應用程式在背景播放音樂,則必須建構 Service 進行播放,並從 Service 的生命週期回呼呼叫媒體路由器架構。
控制遠端播放路徑
選取遠端播放路徑後,應用程式就會做為遙控器。路徑另一端的裝置會處理所有內容資料擷取、解碼和播放功能。應用程式 UI 中的控制項會使用 RemotePlaybackClient 物件與接收端裝置通訊。
RemotePlaybackClient 類別提供其他管理內容播放的方法。以下是 RemotePlaybackClient 類別中的幾個重要播放方法:
play():播放由Uri指定的特定媒體檔案。pause():暫停目前播放的媒體曲目。resume():在暫停指令後繼續播放目前曲目。seek():移至目前曲目的特定位置。release():中斷應用程式與遠端播放裝置的連線。
您可以使用這些方法,將動作附加至應用程式中提供的播放控制項。其中大多數方法也允許您加入回呼物件,以便監控播放工作或控制要求的進度。
RemotePlaybackClient 類別也支援將多個媒體項目排入佇列,以便播放及管理媒體佇列。
程式碼範例
Android BasicMediaRouter 和 MediaRouter 範例進一步示範了 MediaRouter API 的用法。