MediaRouteProvider 總覽

Android 媒體路由器架構可讓製造商透過名為 MediaRouteProvider 的標準化介面,在裝置上啟用播放功能。路徑供應器會定義在接收端裝置上播放媒體的通用介面,讓您能從任何支援媒體路徑的 Android 應用程式,在裝置上播放媒體。

本指南說明如何為接收端裝置建立媒體路徑供應器,並提供給在 Android 上執行的其他媒體播放應用程式使用。如要使用這個 API,您應熟悉 MediaRouteProvider、MediaRouteProviderDescriptor 和 RouteController 等重要類別。

總覽

Android 媒體路由器架構可讓媒體應用程式開發人員和媒體播放裝置製造商,透過通用 API 和通用使用者介面進行連線。實作 MediaRouter 介面的應用程式開發人員可以連線至架構,並在參與媒體路由器架構的裝置上播放內容。媒體播放裝置製造商可以發布 MediaRouteProvider,讓其他應用程式連線至接收器裝置並播放媒體,藉此參與架構。圖 1 說明應用程式如何透過媒體路由器架構連線至接收裝置。

圖 1. 媒體路徑供應器類別如何提供從媒體應用程式到接收器裝置的通訊總覽。

為接收端裝置建構媒體路徑供應器時,供應器有以下用途:

  • 說明並發布接收器裝置的功能,讓其他應用程式可以探索該裝置並使用其播放功能。
  • 包裝接收器裝置的程式設計介面及其通訊傳輸機制,讓裝置與媒體路由器架構相容。

路線供應商分布

媒體路徑供應器會做為 Android 應用程式的一部分發布。您可以擴充 MediaRouteProviderService,或使用自己的服務包裝 MediaRouteProvider 的實作,並為媒體路徑供應器宣告意圖篩選器,讓其他應用程式可以使用您的路徑供應器。這些步驟可讓其他應用程式探索及使用您的媒體路徑。

注意:含有媒體路徑供應器的應用程式,也可以包含路徑供應器的 MediaRouter 介面,但這並非必要。

MediaRouter 支援資料庫

媒體路由器 API 定義於 AndroidX MediaRouter 程式庫中。您必須將這個程式庫新增至應用程式開發專案。如要進一步瞭解如何在專案中新增支援資料庫,請參閱「支援資料庫設定」。

注意:請務必使用媒體路由器架構的 AndroidX 實作。請勿使用舊版 android.media 套件。

建立供應商服務

媒體路由器架構必須能夠探索並連線至媒體路徑供應器,才能允許其他應用程式使用您的路徑。為此,媒體路由器架構會尋找宣告媒體路徑供應器意圖動作的應用程式。當其他應用程式想要連線至您的供應器時,架構必須能夠叫用並連線至該供應器,因此您的供應器必須封裝在 Service 中。

以下程式碼範例說明資訊清單中的媒體路徑供應器服務和意圖篩選器宣告,讓媒體路由器架構可以探索及使用:

<service android:name=".provider.SampleMediaRouteProviderService"
    android:label="@string/sample_media_route_provider_service"
    android:process=":mrp">
    <intent-filter>
        <action android:name="android.media.MediaRouteProviderService" />
    </intent-filter>
</service>

這個資訊清單範例宣告了一項服務,用於包裝實際的媒體路徑供應器類別。Android 媒體路由器架構提供 MediaRouteProviderService 類別,可做為媒體路徑供應器的服務包裝函式。以下程式碼範例說明如何使用這個包裝函式類別:

class SampleMediaRouteProviderService : MediaRouteProviderService() {

    override fun onCreateMediaRouteProvider(): MediaRouteProvider {
        return SampleMediaRouteProvider(this)
    }
}

指定路線功能

連線至媒體路由器架構的應用程式可透過應用程式的資訊清單宣告,探索媒體路徑,但應用程式也需要知道您提供的媒體路徑功能。媒體路徑可以有不同的類型和功能,其他應用程式必須能夠探索這些詳細資料,才能判斷是否與您的路徑相容。

媒體路由器架構可讓您透過 IntentFilter 物件、MediaRouteDescriptor 物件和 MediaRouteProviderDescriptor 定義及發布媒體路徑的功能。本節說明如何使用這些類別,為其他應用程式發布媒體路徑的詳細資料。

路徑類別

在媒體路徑供應器的程式輔助說明中,您必須指定供應器是否支援遠端播放、次要輸出,或兩者皆支援。以下是媒體路由器架構提供的路徑類別:

如要在媒體路徑說明中加入這些設定,請將設定插入 IntentFilter 物件,然後再將物件新增至 MediaRouteDescriptor 物件:

class SampleMediaRouteProvider(context: Context) : MediaRouteProvider(context) {

    companion object {
        private val CONTROL_FILTERS_BASIC: ArrayList<IntentFilter> = IntentFilter().run {
            addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)
            arrayListOf(this)
        }
    }
}

如果指定 CATEGORY_REMOTE_PLAYBACK 意圖,也必須定義媒體路徑供應器支援的媒體類型和播放控制項。下一節將說明如何為裝置指定這些設定。

媒體類型和通訊協定

遠端播放裝置的媒體路徑供應器必須指定支援的媒體類型和傳輸通訊協定。您可以使用 IntentFilter 類別以及該物件的 addDataScheme() 和 addDataType() 方法來指定這些設定。下列程式碼片段示範如何定義意圖篩選器,以支援使用 HTTP、HTTPS 和即時串流通訊協定 (RTSP) 播放遠端影片:

class SampleMediaRouteProvider(context: Context) : MediaRouteProvider(context) {

    companion object {

        private fun IntentFilter.addDataTypeUnchecked(type: String) {
            try {
                addDataType(type)
            } catch (ex: IntentFilter.MalformedMimeTypeException) {
                throw RuntimeException(ex)
            }
        }

        private val CONTROL_FILTERS_BASIC: ArrayList<IntentFilter> = IntentFilter().run {
            addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)
            addAction(MediaControlIntent.ACTION_PLAY)
            addDataScheme("http")
            addDataScheme("https")
            addDataScheme("rtsp")
            addDataTypeUnchecked("video/*")
            arrayListOf(this)
        }
    }
    // ...
}

播放控制項

提供遠端播放功能的媒體路徑供應商必須指定支援的媒體遙控器類型。媒體路徑可提供下列一般控制項類型:

  • 播放控制項,例如播放、暫停、倒轉和快轉。
  • 佇列功能:傳送端應用程式可透過這項功能,在接收端裝置維護的播放清單中新增及移除項目。
  • 工作階段功能:接收端裝置會向要求應用程式提供工作階段 ID,然後在每次後續播放控制項要求中檢查該 ID,防止傳送應用程式互相干擾。

下列程式碼範例示範如何建構意圖篩選器,以支援基本媒體路徑播放控制項:

class SampleMediaRouteProvider(context: Context) : MediaRouteProvider(context) {

    companion object {
        // ...
        private val CONTROL_FILTERS_BASIC: ArrayList<IntentFilter> = run {
            val videoPlayback: IntentFilter = ...
            // ...
            val playControls = IntentFilter().apply {
                addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)
                addAction(MediaControlIntent.ACTION_SEEK)
                addAction(MediaControlIntent.ACTION_GET_STATUS)
                addAction(MediaControlIntent.ACTION_PAUSE)
                addAction(MediaControlIntent.ACTION_RESUME)
                addAction(MediaControlIntent.ACTION_STOP)
            }
            arrayListOf(videoPlayback, playControls)
        }
    }
    // ...
}

如要進一步瞭解可用的播放控制項意圖,請參閱 MediaControlIntent 類別。

MediaRouteProviderDescriptor

使用 IntentFilter 物件定義媒體路徑的功能後,您可以建立描述元物件,發布至 Android 媒體路由器架構。這個描述元物件包含媒體路徑功能的詳細資料,讓其他應用程式可以判斷如何與媒體路徑互動。

以下程式碼範例示範如何將先前建立的意圖篩選器新增至 MediaRouteProviderDescriptor,並設定媒體路由器架構使用的描述元:

class SampleMediaRouteProvider(context: Context) : MediaRouteProvider(context) {

    init {
        publishRoutes()
    }

    private fun publishRoutes() {
        val resources = context.resources
        val routeName: String = resources.getString(R.string.variable_volume_basic_route_name)
        val routeDescription: String = resources.getString(R.string.sample_route_description)
        // Create a route descriptor using previously created IntentFilters.
        val routeDescriptor: MediaRouteDescriptor =
            MediaRouteDescriptor.Builder(VARIABLE_VOLUME_BASIC_ROUTE_ID, routeName)
                .setDescription(routeDescription)
                .addControlFilters(CONTROL_FILTERS_BASIC)
                .setPlaybackStream(AudioManager.STREAM_MUSIC)
                .setPlaybackType(MediaRouter.RouteInfo.PLAYBACK_TYPE_REMOTE)
                .setVolumeHandling(MediaRouter.RouteInfo.PLAYBACK_VOLUME_VARIABLE)
                .setVolumeMax(VOLUME_MAX)
                .setVolume(mVolume)
                .build()
        // Add the route descriptor to the provider descriptor.
        val providerDescriptor: MediaRouteProviderDescriptor =
            MediaRouteProviderDescriptor.Builder()
                .addRoute(routeDescriptor)
                .build()

        // Publish the descriptor to the framework.
        descriptor = providerDescriptor
    }
    // ...
}

如要進一步瞭解可用的描述元設定,請參閱 MediaRouteDescriptor 和 MediaRouteProviderDescriptor 的參考文件。

控制路徑

當應用程式連線至媒體路徑供應器時,供應器會透過媒體路由器架構,接收其他應用程式傳送至路徑的播放指令。如要處理這些要求,您必須提供 MediaRouteProvider.RouteController 類別的實作,用於處理指令及與接收端裝置的實際通訊。

媒體路由器架構會呼叫路徑供應器的 onCreateRouteController() 方法,取得這個類別的例項,然後將要求轉送至該例項。以下是 MediaRouteProvider.RouteController 類別的主要方法,您必須為媒體路徑供應器實作這些方法:

  • onSelect() — 當應用程式選取您的路徑進行播放時呼叫。您可以使用這個方法,在媒體播放開始前進行任何必要的準備工作。
  • onControlRequest():將特定播放指令傳送至接收裝置。
  • onSetVolume():向接收裝置傳送要求,將播放音量設為特定值。
  • onUpdateVolume():向接收裝置傳送要求,以指定幅度調整播放音量。
  • onUnselect():在應用程式取消選取路徑時呼叫。
  • onRelease() :當架構不再需要路徑時呼叫,允許釋出資源。

除了音量變更外,所有播放控制項要求都會導向 onControlRequest() 方法。您實作這個方法時,必須剖析控制要求並做出適當回應。以下是這個方法的實作範例,可處理遠端播放媒體路徑的指令:

private class SampleRouteController : MediaRouteProvider.RouteController() {
    // ...

    override fun onControlRequest(
        intent: Intent,
        callback: MediaRouter.ControlRequestCallback?
    ): Boolean {
        return if (intent.hasCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)) {
            val action = intent.action
            when (action) {
                MediaControlIntent.ACTION_PLAY -> handlePlay(intent, callback)
                MediaControlIntent.ACTION_ENQUEUE -> handleEnqueue(intent, callback)
                MediaControlIntent.ACTION_REMOVE -> handleRemove(intent, callback)
                MediaControlIntent.ACTION_SEEK -> handleSeek(intent, callback)
                MediaControlIntent.ACTION_GET_STATUS -> handleGetStatus(intent, callback)
                MediaControlIntent.ACTION_PAUSE -> handlePause(intent, callback)
                MediaControlIntent.ACTION_RESUME -> handleResume(intent, callback)
                MediaControlIntent.ACTION_STOP -> handleStop(intent, callback)
                MediaControlIntent.ACTION_START_SESSION -> handleStartSession(intent, callback)
                MediaControlIntent.ACTION_GET_SESSION_STATUS ->
                    handleGetSessionStatus(intent, callback)
                MediaControlIntent.ACTION_END_SESSION -> handleEndSession(intent, callback)
                else -> false
            }.also {
                Log.d(TAG, sessionManager.toString())
            }
        } else {
            false
        }
    }
    // ...
}

請務必瞭解,MediaRouteProvider.RouteController 類別旨在做為媒體播放設備 API 的包裝函式。這個類別中方法的實作方式,完全取決於接收裝置提供的程式輔助介面。

程式碼範例

MediaRouter 範例說明如何建立自訂媒體路徑供應器。