MediaRouteProvider 概览

借助 Android 媒体路由器框架,制造商可以通过名为 MediaRouteProvider 的标准化接口在其设备上实现播放功能。路由提供程序定义了一个用于在接收器设备上播放媒体的通用接口,从而使您能够从任何支持媒体路由的 Android 应用在您的设备上播放媒体。

本指南介绍了如何为接收器设备创建媒体路由提供程序,并将其提供给在 Android 上运行的其他媒体播放应用。如需使用此 API,您应熟悉关键类 MediaRouteProvider、MediaRouteProviderDescriptor 和 RouteController。

概览

借助 Android 媒体路由器框架,媒体应用开发者和媒体播放设备制造商可以通过通用 API 和通用界面进行连接。实现 MediaRouter 接口的应用开发者可以连接到该框架,并向参与媒体路由器框架的设备播放内容。媒体播放设备制造商可以通过发布 MediaRouteProvider 来参与该框架,从而允许其他应用连接到接收器设备并在其上播放媒体。图 1 说明了应用如何通过媒体路由器框架连接到接收设备。

图 1. 媒体路由提供程序类如何提供从媒体应用到接收器设备的通信的概览。

为接收器设备构建媒体路由提供程序时,该提供程序具有以下用途:

  • 描述并发布接收器设备的功能,以便其他应用可以发现该设备并使用其播放功能。
  • 封装接收端设备的编程接口及其通信传输机制,使设备与媒体路由器框架兼容。

分发路由提供程序

媒体路由提供程序作为 Android 应用的一部分进行分发。您可以通过扩展 MediaRouteProviderService 或使用您自己的服务封装 MediaRouteProvider 的实现并为媒体路由提供程序声明 intent 过滤器,使您的路由提供程序可供其他应用使用。通过这些步骤,其他应用可以发现并使用您的媒体路由。

注意:包含媒体路由提供器的应用也可以包含路由提供器的 MediaRouter 接口,但这不是必需的。

MediaRouter 支持库

媒体路由器 API 在 AndroidX MediaRouter 库中定义。您必须将此库添加到应用开发项目中。如需详细了解如何向项目添加支持库,请参阅支持库设置。

注意:请务必使用媒体路由器框架的 AndroidX 实现。 请勿使用旧版 android.media 软件包。

创建提供程序服务

媒体路由器框架必须能够发现并连接到您的媒体路由提供程序,以便其他应用使用您的路由。为此,媒体路由器框架会查找声明媒体路由提供程序 intent 操作的应用。当其他应用想要连接到您的提供程序时,框架必须能够调用并连接到该提供程序,因此您的提供程序必须封装在 Service 中。

以下示例代码展示了清单中媒体路由提供程序服务和 intent 过滤器的声明,这使媒体路由器框架能够发现和使用该服务:

<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 intent,则还必须定义媒体路由提供程序支持哪些媒体类型和播放控件。下一部分将介绍如何为设备指定这些设置。

媒体类型和协议

远程播放设备的媒体路由提供程序必须指定其支持的媒体类型和传输协议。您可以使用 IntentFilter 类以及该对象的 addDataScheme() 和 addDataType() 方法来指定这些设置。以下代码段演示了如何定义 intent 过滤器,以支持使用 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。

以下代码示例演示了如何构建一个 intent 过滤器来支持基本媒体路由播放控件:

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)
        }
    }
    // ...
}

如需详细了解可用的播放控制 intent,请参阅 MediaControlIntent 类。

MediaRouteProviderDescriptor

使用 IntentFilter 对象定义媒体路由的功能后,您可以创建一个描述符对象,以便发布到 Android 媒体路由器框架。此描述符对象包含媒体路由功能的具体信息,以便其他应用可以确定如何与您的媒体路由进行交互。

以下示例代码演示了如何将之前创建的 intent 过滤器添加到 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 示例展示了如何创建自定义媒体路由提供程序。