MediaRouter 總覽

如要在應用程式中使用 MediaRouter 架構,您必須取得 MediaRouter 物件的例項,並附加 MediaRouter.Callback 物件來監聽轉送事件。透過媒體路徑傳送的內容會通過路徑相關聯的 MediaRouteProvider (少數特殊情況除外,例如藍牙輸出裝置)。圖 1 概略說明用於在裝置之間轉送內容的類別。

圖 1. 應用程式使用的主要媒體路由器類別總覽。

注意:如要讓應用程式支援 Google Cast 裝置,請使用 Cast SDK,並將應用程式建構為 Cast 傳送端。請按照 Cast 說明文件中的指示操作,不要直接使用 MediaRouter 架構。

媒體路徑按鈕

Android 應用程式應使用媒體路徑按鈕控制媒體路徑。MediaRouter 架構為按鈕提供標準介面,可協助使用者在可用時辨識及使用轉送功能。媒體路徑按鈕通常位於應用程式動作列的右側,如圖 2 所示。

圖 2. 動作列中的媒體路徑按鈕。

使用者按下媒體路徑按鈕時,可用的媒體路徑會顯示在清單中,如圖 3 所示。

圖 3. 按下媒體路徑按鈕後,系統會顯示可用的媒體路徑清單。

請按照下列步驟建立媒體路徑按鈕:

  1. 使用 AppCompatActivity
  2. 定義媒體路徑按鈕選單項目
  3. 建立 MediaRouteSelector
  4. 在動作列中新增媒體路徑按鈕
  5. 在活動生命週期中建立及管理 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 的用法。