MediaRouteProvider 概览

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

本指南介绍如何为接收端设备创建媒体路由提供程序,并使其可供在 Android 上运行的其他媒体播放应用使用。要使用此 API,您应熟悉关键类 MediaRouteProviderMediaRouteProviderDescriptorRouteController

概览

借助 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 类,用作媒体路由提供程序的服务封装容器。以下示例代码演示了如何使用此封装容器类:

Kotlin

class SampleMediaRouteProviderService : MediaRouteProviderService() {

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

Java

public class SampleMediaRouteProviderService extends MediaRouteProviderService {

    @Override
    public MediaRouteProvider onCreateMediaRouteProvider() {
        return new SampleMediaRouteProvider(this);
    }
}

指定路由功能

连接到媒体路由器框架的应用可以通过应用的清单声明发现您的媒体路由,但它们还需要知道您提供的媒体路由的功能。媒体路由可能具有不同的类型且具有不同的功能,其他应用需要能够发现这些详细信息,以确定它们是否与您的路由兼容。

媒体路由器框架允许您通过 IntentFilter 对象、MediaRouteDescriptor 对象和 MediaRouteProviderDescriptor 定义和发布媒体路由的功能。本部分介绍如何使用这些类为其他应用发布媒体路由的详细信息。

路由类别

在以程序化方式描述媒体路由提供程序时,您必须指定您的提供程序是否支持远程播放和/或辅助输出。以下是媒体路由器框架提供的路由类别:

若要将这些设置包含在媒体路由的说明中,您需要将它们插入到 IntentFilter 对象中,然后您再将该对象添加到 MediaRouteDescriptor 对象中:

Kotlin

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

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

Java

public final class SampleMediaRouteProvider extends MediaRouteProvider {
    private static final ArrayList<IntentFilter> CONTROL_FILTERS_BASIC;
    static {
        IntentFilter videoPlayback = new IntentFilter();
        videoPlayback.addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK);
        CONTROL_FILTERS_BASIC = new ArrayList<IntentFilter>();
        CONTROL_FILTERS_BASIC.add(videoPlayback);
    }
}

如果您指定 CATEGORY_REMOTE_PLAYBACK intent,则还必须定义您的媒体路由提供程序支持的媒体类型和播放控件。下一部分将介绍如何为您的设备指定这些设置。

媒体类型和协议

远程播放设备的媒体路由提供程序必须指定其支持的媒体类型和传输协议。您可以使用 IntentFilter 类以及该对象的 addDataScheme()addDataType() 方法指定这些设置。以下代码段演示了如何使用 http、https 和实时流式传输协议 (RTSP) 定义支持远程视频播放的 intent 过滤器:

Kotlin

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

Java

public final class SampleMediaRouteProvider extends MediaRouteProvider {

    private static final ArrayList<IntentFilter> CONTROL_FILTERS_BASIC;

    static {
        IntentFilter videoPlayback = new IntentFilter();
        videoPlayback.addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK);
        videoPlayback.addAction(MediaControlIntent.ACTION_PLAY);
        videoPlayback.addDataScheme("http");
        videoPlayback.addDataScheme("https");
        videoPlayback.addDataScheme("rtsp");
        addDataTypeUnchecked(videoPlayback, "video/*");
        CONTROL_FILTERS_BASIC = new ArrayList<IntentFilter>();
        CONTROL_FILTERS_BASIC.add(videoPlayback);
    }
    ...

    private static void addDataTypeUnchecked(IntentFilter filter, String type) {
        try {
            filter.addDataType(type);
        } catch (MalformedMimeTypeException ex) {
            throw new RuntimeException(ex);
        }
    }
}

播放控件

提供远程播放的媒体路由提供程序必须指定其支持的媒体控件的类型。媒体路由可以提供以下几种常规控件类型:

  • 播放控件,例如播放、暂停、快退和快进。
  • 加入队列功能,可让发送方应用向接收方设备维护的播放列表中添加项以及从中移除项。
  • 会话功能,可让接收方设备向发出请求的应用提供会话 ID,然后在每个后续播放控制请求中检查该 ID,从而防止发送方应用相互干扰。

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

Kotlin

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

Java

public final class SampleMediaRouteProvider extends MediaRouteProvider {
    private static final ArrayList<IntentFilter> CONTROL_FILTERS_BASIC;
    static {
        ...
        IntentFilter playControls = new IntentFilter();
        playControls.addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK);
        playControls.addAction(MediaControlIntent.ACTION_SEEK);
        playControls.addAction(MediaControlIntent.ACTION_GET_STATUS);
        playControls.addAction(MediaControlIntent.ACTION_PAUSE);
        playControls.addAction(MediaControlIntent.ACTION_RESUME);
        playControls.addAction(MediaControlIntent.ACTION_STOP);
        CONTROL_FILTERS_BASIC = new ArrayList<IntentFilter>();
        CONTROL_FILTERS_BASIC.add(videoPlayback);
        CONTROL_FILTERS_BASIC.add(playControls);
    }
    ...
}

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

MediaRouteProviderDescriptor

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

以下示例代码演示了如何将之前创建的 intent 过滤器添加到 MediaRouteProviderDescriptor,并设置媒体路由器框架使用的描述符:

Kotlin

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

Java

public SampleMediaRouteProvider(Context context) {
    super(context);
    publishRoutes();
}

private void publishRoutes() {
    Resources r = getContext().getResources();
    // Create a route descriptor using previously created IntentFilters
    MediaRouteDescriptor routeDescriptor = new MediaRouteDescriptor.Builder(
            VARIABLE_VOLUME_BASIC_ROUTE_ID,
            r.getString(R.string.variable_volume_basic_route_name))
            .setDescription(r.getString(R.string.sample_route_description))
            .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
    MediaRouteProviderDescriptor providerDescriptor =
            new MediaRouteProviderDescriptor.Builder()
            .addRoute(routeDescriptor)
            .build();

    // Publish the descriptor to the framework
    setDescriptor(providerDescriptor);
}

如需详细了解可用的描述符设置,请参阅 MediaRouteDescriptorMediaRouteProviderDescriptor 的参考文档。

控制路由

当应用连接到您的媒体路由提供程序时,该提供程序会通过其他应用发送到您的路由的媒体路由器框架接收播放命令。为了处理这些请求,您必须提供 MediaRouteProvider.RouteController 类的实现,该类会处理命令并处理与接收方设备的实际通信。

媒体路由器框架会调用您的路由提供程序的 onCreateRouteController() 方法以获取此类的实例,然后将请求路由到该实例。 以下是您必须为媒体路由提供程序实现的 MediaRouteProvider.RouteController 类的主要方法:

  • onSelect() - 当应用选择您的路由进行播放时调用。您可以使用此方法完成媒体播放开始之前可能需要的所有准备工作。
  • onControlRequest() - 向接收方设备发送特定播放命令。
  • onSetVolume() - 向接收方设备发送请求,以将播放音量设置为特定值。
  • onUpdateVolume() - 向接收方设备发送请求,以按照指定的音量修改播放音量。
  • onUnselect() - 当应用取消选择路由时调用此方法。
  • onRelease() - 当框架不再需要路由时调用,从而允许框架释放资源。

所有播放控制请求(音量更改除外)都会定向到 onControlRequest() 方法。您在实现此方法时,必须解析控件请求并相应地响应它们。下面是此方法的示例实现,其中,该实现会处理针对远程播放媒体路由的命令:

Kotlin

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

Java

private final class SampleRouteController extends
        MediaRouteProvider.RouteController {
    ...

    @Override
    public boolean onControlRequest(Intent intent, ControlRequestCallback callback) {

        String action = intent.getAction();

        if (intent.hasCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)) {
            boolean success = false;
            if (action.equals(MediaControlIntent.ACTION_PLAY)) {
                success = handlePlay(intent, callback);
            } else if (action.equals(MediaControlIntent.ACTION_ENQUEUE)) {
                success = handleEnqueue(intent, callback);
            } else if (action.equals(MediaControlIntent.ACTION_REMOVE)) {
                success = handleRemove(intent, callback);
            } else if (action.equals(MediaControlIntent.ACTION_SEEK)) {
                success = handleSeek(intent, callback);
            } else if (action.equals(MediaControlIntent.ACTION_GET_STATUS)) {
                success = handleGetStatus(intent, callback);
            } else if (action.equals(MediaControlIntent.ACTION_PAUSE)) {
                success = handlePause(intent, callback);
            } else if (action.equals(MediaControlIntent.ACTION_RESUME)) {
                success = handleResume(intent, callback);
            } else if (action.equals(MediaControlIntent.ACTION_STOP)) {
                success = handleStop(intent, callback);
            } else if (action.equals(MediaControlIntent.ACTION_START_SESSION)) {
                success = handleStartSession(intent, callback);
            } else if (action.equals(MediaControlIntent.ACTION_GET_SESSION_STATUS)) {
                success = handleGetSessionStatus(intent, callback);
            } else if (action.equals(MediaControlIntent.ACTION_END_SESSION)) {
                success = handleEndSession(intent, callback);
            }

            Log.d(TAG, sessionManager.toString());
            return success;
        }
        return false;
    }
    ...
}

请务必注意,MediaRouteProvider.RouteController 类旨在充当媒体播放设备的 API 封装容器。此类中的方法的实现完全依赖于接收设备提供的编程接口。

示例代码

MediaRouter 示例展示了如何创建自定义媒体路由提供程序。