Descripción general de MediaRouteProvider

El framework del router de contenido multimedia de Android permite que los fabricantes habiliten la reproducción en sus dispositivos a través de una interfaz estandarizada llamada MediaRouteProvider. Un proveedor de rutas define una interfaz común para reproducir contenido multimedia en un dispositivo receptor, lo que permite reproducir contenido multimedia en tu equipo desde cualquier aplicación para Android que admita rutas de contenido multimedia.

En esta guía, se explica cómo crear un proveedor de rutas de acceso de contenido multimedia para un dispositivo receptor y cómo ponerlo a disposición de otras aplicaciones de reproducción de contenido multimedia que se ejecutan en Android. Para usar esta API, debes conocer las clases clave MediaRouteProvider, MediaRouteProviderDescriptor y RouteController.

Descripción general

El framework del enrutador de contenido multimedia de Android permite que los desarrolladores de apps multimedia y los fabricantes de dispositivos de reproducción de contenido multimedia se conecten a través de una API y una interfaz de usuario comunes. Los desarrolladores de apps que implementan una interfaz MediaRouter pueden conectarse al framework y reproducir contenido en los dispositivos que participan en el framework del router de contenido multimedia. Los fabricantes de dispositivos de reproducción de contenido multimedia pueden participar en el framework publicando un MediaRouteProvider que permita que otras aplicaciones se conecten y reproduzcan contenido multimedia en los dispositivos receptores. En la Figura 1, se ilustra cómo una app se conecta a un dispositivo receptor a través del framework del router de contenido multimedia.

Figura 1: Descripción general de cómo las clases de proveedores de rutas de acceso de contenido multimedia proporcionan comunicación desde una app de contenido multimedia hasta un dispositivo receptor

Cuando compilas un proveedor de rutas de acceso de contenido multimedia para tu dispositivo receptor, el proveedor cumple con los siguientes propósitos:

  • Describe y publica las capacidades del dispositivo receptor para que otras apps puedan descubrirlo y usar sus funciones de reproducción.
  • Une la interfaz de programación del dispositivo receptor y sus mecanismos de transporte de comunicación para que el dispositivo sea compatible con el framework del router de contenido multimedia.

Distribución de proveedores de rutas

Un proveedor de rutas de medios se distribuye como parte de una app para Android. Puedes hacer que tu proveedor de rutas esté disponible para otras apps extendiendo MediaRouteProviderService o uniendo tu implementación de MediaRouteProvider con tu propio servicio y declarando un filtro de intents para el proveedor de rutas de medios. Estos pasos permiten que otras apps descubran y usen tu ruta de contenido multimedia.

Nota: La app que contiene el proveedor de rutas de medios también puede incluir una interfaz de MediaRouter para el proveedor de rutas, pero no es obligatorio.

Biblioteca de compatibilidad de MediaRouter

Las APIs de router de contenido multimedia se definen en la biblioteca de MediaRouter de AndroidX. Debes agregar esta biblioteca a tu proyecto de desarrollo de apps. Para obtener más información sobre cómo agregar bibliotecas de compatibilidad a tu proyecto, consulta Configuración de la biblioteca de compatibilidad.

Precaución: Asegúrate de usar la implementación de AndroidX del framework del router de contenido multimedia. No uses el paquete android.media más antiguo.

Cómo crear un servicio de proveedor

El framework del router de contenido multimedia debe poder descubrir tu proveedor de rutas de contenido multimedia y conectarse a él para permitir que otras aplicaciones usen tu ruta. Para ello, el framework del router de contenido multimedia busca apps que declaren una acción de intent del proveedor de rutas de contenido multimedia. Cuando otra app quiera conectarse a tu proveedor, el framework debe poder invocarlo y conectarse a él, por lo que tu proveedor debe estar encapsulado en un Service.

En el siguiente código de ejemplo, se muestra la declaración de un servicio de proveedor de rutas de medios y el filtro de intents en un manifiesto, lo que permite que el framework del router de medios lo descubra y lo use:

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

Este ejemplo de manifiesto declara un servicio que une las clases de proveedores de rutas de contenido multimedia reales. El framework del router multimedia de Android proporciona la clase MediaRouteProviderService para usarla como un wrapper de servicio para los proveedores de rutas de medios. En el siguiente código de ejemplo, se muestra cómo usar esta clase de wrapper:

class SampleMediaRouteProviderService : MediaRouteProviderService() {

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

Cómo especificar las capacidades de las rutas

Las apps que se conectan al framework del router de contenido multimedia pueden descubrir tu ruta de contenido multimedia a través de las declaraciones del manifiesto de tu app, pero también necesitan conocer las capacidades de las rutas de contenido multimedia que proporcionas. Las rutas de medios pueden ser de diferentes tipos y tener diferentes funciones, y otras apps deben poder descubrir estos detalles para determinar si son compatibles con tu ruta.

El framework del router de contenido multimedia te permite definir y publicar las capacidades de tu ruta de contenido multimedia a través de objetos IntentFilter, objetos MediaRouteDescriptor y un MediaRouteProviderDescriptor. En esta sección, se explica cómo usar estas clases para publicar los detalles de tu ruta de acceso de contenido multimedia para otras apps.

Categorías de rutas

Como parte de la descripción programática de tu proveedor de rutas de acceso de contenido multimedia, debes especificar si tu proveedor admite la reproducción remota, la salida secundaria o ambas. Estas son las categorías de rutas que proporciona el framework del router de contenido multimedia:

  • CATEGORY_LIVE_AUDIO — Salida de audio a un dispositivo de salida secundario, como un sistema de música inalámbrico.
  • CATEGORY_LIVE_VIDEO: Es la salida de video a un dispositivo de salida secundario, como los dispositivos de pantalla inalámbrica.
  • CATEGORY_REMOTE_PLAYBACK: Reproduce video o audio en un dispositivo independiente que controle la recuperación, la decodificación y la reproducción de contenido multimedia, como los dispositivos Chromecast.

Para incluir estos parámetros de configuración en una descripción de tu ruta de medios, insértalos en un objeto IntentFilter, que luego agregarás a un objeto 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)
        }
    }
}

Si especificas el intent CATEGORY_REMOTE_PLAYBACK, también debes definir qué tipos de contenido multimedia y controles de reproducción admite tu proveedor de rutas de medios. En la siguiente sección, se describe cómo especificar estos parámetros de configuración para tu dispositivo.

Tipos de contenido multimedia y protocolos

Un proveedor de rutas de acceso de contenido multimedia para un dispositivo de reproducción remota debe especificar los tipos de contenido multimedia y los protocolos de transferencia que admite. Especifica estos parámetros de configuración con la clase IntentFilter y los métodos addDataScheme() y addDataType() de ese objeto. En el siguiente fragmento de código, se muestra cómo definir un filtro de intents para admitir la reproducción remota de videos con HTTP, HTTPS y el protocolo de transmisión en tiempo real (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)
        }
    }
    // ...
}

Controles de reproducción

Un proveedor de rutas de acceso de contenido multimedia que ofrece reproducción remota debe especificar los tipos de controles multimedia que admite. A continuación, se enumeran los tipos generales de control que las rutas de contenido multimedia pueden proporcionar:

  • Controles de reproducción, como reproducción, pausa, retroceso y avance rápido.
  • Funciones de cola, que permiten que la app emisora agregue y quite elementos de una playlist que mantiene el dispositivo receptor
  • Funciones de sesión, que evitan que las apps emisoras interfieran entre sí, ya que el dispositivo receptor proporciona un ID de sesión a la app solicitante y, luego, verifica ese ID con cada solicitud de control de reproducción posterior.

En el siguiente ejemplo de código, se muestra cómo construir un filtro de intents para admitir controles de reproducción de rutas de medios básicos:

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

Para obtener más información sobre los intents de control de reproducción disponibles, consulta la clase MediaControlIntent.

MediaRouteProviderDescriptor

Después de definir las capacidades de tu ruta de acceso de contenido multimedia con objetos IntentFilter, puedes crear un objeto descriptor para publicarlo en el framework del router de contenido multimedia de Android. Este objeto descriptor contiene los detalles de las capacidades de tu ruta de medios para que otras aplicaciones puedan determinar cómo interactuar con ella.

En el siguiente ejemplo de código, se muestra cómo agregar los filtros de intents creados anteriormente a un MediaRouteProviderDescriptor y establecer el descriptor para que lo use el framework del router de medios:

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

Para obtener más información sobre la configuración de descriptores disponibles, consulta la documentación de referencia de MediaRouteDescriptor y MediaRouteProviderDescriptor.

Cómo controlar rutas

Cuando una aplicación se conecta a tu proveedor de rutas de acceso de contenido multimedia, este recibe comandos de reproducción a través del framework del router de contenido multimedia que otras apps envían a tu ruta de acceso. Para controlar estas solicitudes, debes proporcionar una implementación de una clase MediaRouteProvider.RouteController, que procese los comandos y controle la comunicación real con tu dispositivo receptor.

El framework del router de contenido multimedia llama al método onCreateRouteController() de tu proveedor de rutas para obtener una instancia de esta clase y, luego, le enruta las solicitudes. Estos son los métodos clave de la clase MediaRouteProvider.RouteController, que debes implementar para tu proveedor de rutas de medios:

  • onSelect() — Se llama cuando una aplicación selecciona tu ruta para la reproducción. Usa este método para realizar cualquier trabajo de preparación que se requiera antes de que comience la reproducción de contenido multimedia.
  • onControlRequest(): Envía comandos de reproducción específicos al dispositivo receptor.
  • onSetVolume(): Envía una solicitud al dispositivo receptor para establecer el volumen de reproducción en un valor específico.
  • onUpdateVolume(): Envía una solicitud al dispositivo receptor para que modifique el volumen de reproducción en una cantidad especificada.
  • onUnselect(): Se llama cuando una app anula la selección de una ruta.
  • onRelease(): Se llama cuando el framework ya no necesita la ruta, lo que le permite liberar sus recursos.

Todas las solicitudes de control de reproducción, excepto los cambios de volumen, se dirigen al método onControlRequest(). La implementación de este método debe analizar las solicitudes de control y responderlas de forma adecuada. A continuación, se muestra un ejemplo de implementación de este método que procesa comandos para una ruta de medios de reproducción remota:

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

Es importante comprender que la clase MediaRouteProvider.RouteController está diseñada para actuar como un wrapper de la API para tu equipo de reproducción de contenido multimedia. La implementación de los métodos en esta clase depende por completo de la interfaz programática que proporciona tu dispositivo receptor.

Código de muestra

En el ejemplo de MediaRouter, se muestra cómo crear un proveedor de rutas de acceso de contenido multimedia personalizado.