Para usar el framework de MediaRouter en tu app, debes obtener una instancia del objeto MediaRouter y adjuntar un objeto MediaRouter.Callback para escuchar los eventos de enrutamiento.
El contenido que se envía a través de una ruta de medios pasa por el MediaRouteProvider asociado a la ruta (excepto en algunos casos especiales, como un dispositivo de salida Bluetooth). En la Figura 1, se proporciona una vista de alto nivel de las clases que se usan para enrutar contenido entre dispositivos.
Figura 1: Descripción general de las clases clave de routers de contenido multimedia que utilizan las apps
Nota: Si quieres que tu app admita dispositivos Google Cast, debes usar el SDK de Cast y compilar tu app como remitente de Cast. Sigue las instrucciones de la documentación de Cast en lugar de usar el framework de MediaRouter directamente.
El botón de ruta de contenido multimedia
Las apps para Android deben usar un botón de ruta de contenido multimedia para controlar el enrutamiento de este tipo de contenido. El framework de MediaRouter proporciona una interfaz estándar para el botón, lo que ayuda a los usuarios a reconocer y usar el enrutamiento cuando está disponible. Por lo general, el botón de ruta de acceso de contenido multimedia se coloca en el lado derecho de la barra de acciones de la app, como se muestra en la Figura 2.
Figura 2: Botón de ruta de contenido multimedia en la barra de acciones
Cuando el usuario presiona el botón de ruta de contenido multimedia, las rutas disponibles aparecen en una lista, como se muestra en la figura 3.
Figura 3: Una lista de las rutas de contenido multimedia disponibles, que se muestra después de presionar el botón de ruta de contenido multimedia
Sigue estos pasos para crear un botón de ruta de contenido multimedia:
- Usa una AppCompatActivity
- Define el elemento de menú del botón de la ruta de contenido multimedia.
- Crea un MediaRouteSelector.
- Agrega el botón de ruta de contenido multimedia a la barra de acciones.
- Crea y administra los métodos de MediaRouter.Callback en el ciclo de vida de tu actividad.
En esta sección, se describen los primeros cuatro pasos. En la siguiente sección, se describen los métodos de devolución de llamada.
Usa una AppCompatActivity
Cuando usas el framework del router de contenido multimedia en una actividad, debes extender
la actividad desde AppCompatActivity y, luego, importar el
paquete androidx.appcompat.app. Debes agregar las bibliotecas de compatibilidad androidx.appcompat:appcompat y androidx.mediarouter:mediarouter a tu proyecto de desarrollo de apps. Para obtener más información sobre cómo agregar bibliotecas de compatibilidad a tu proyecto, consulta Cómo comenzar a usar Android Jetpack.
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.
Define el elemento de menú del botón de la ruta de contenido multimedia
Crea un archivo xml en el que se defina un elemento de menú para el botón de la ruta de contenido multimedia.
La acción del elemento debería ser de la clase MediaRouteActionProvider.
A continuación, se muestra un archivo de ejemplo:
<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>
Crea un MediaRouteSelector
Las rutas que aparecen en el menú del botón de la ruta de contenido multimedia están determinadas por un MediaRouteSelector.
Extiende tu actividad desde AppCompatActivity y compila el selector cuando se cree la actividad llamando a MediaRouteSelector.Builder desde el método onCreate(), como se muestra en la siguiente muestra de código. Ten en cuenta que el selector se guarda en una variable de clase y que los tipos de ruta permitidos se especifican agregando objetos 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() } }
Para la mayoría de las aplicaciones, el único
tipo de ruta necesario es CATEGORY_REMOTE_PLAYBACK. Este tipo de ruta trata el dispositivo que ejecuta tu app como un control remoto.
El dispositivo receptor conectado controla toda la recuperación, la decodificación y la reproducción de datos de contenido.
Así es como funcionan las apps que admiten Google Cast, como Chromecast.
Algunos fabricantes ofrecen compatibilidad con una opción de enrutamiento especial denominada "salida secundaria". Con este enrutamiento, tu app multimedia recupera, renderiza y transmite video o música directamente a la pantalla o las bocinas del dispositivo receptor remoto seleccionado.
Usa la salida secundaria para enviar contenido a sistemas de música o pantallas de video inalámbricos. Para habilitar el descubrimiento y la selección de estos dispositivos, debes agregar las categorías de control CATEGORY_LIVE_AUDIO o CATEGORY_LIVE_VIDEO al MediaRouteSelector. Además, debes crear y controlar tu propio diálogo de Presentation.
Agrega el botón de ruta de contenido multimedia a la barra de acciones
Si ya definiste el menú de ruta de contenido multimedia y MediaRouteSelector, puedes agregar el botón de ruta de contenido multimedia a una actividad.
Anula el método onCreateOptionsMenu() para cada una de tus actividades para agregar un menú de opciones.
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 }
Para obtener más información sobre cómo implementar la barra de acciones en tu app, consulta la guía para desarrolladores sobre la barra de acciones.
También puedes agregar un botón de ruta de acceso de contenido multimedia como un MediaRouteButton en cualquier vista. Debes adjuntar un MediaRouteSelector al botón usando el método setRouteSelector(). Consulta la lista de tareas de diseño de Google Cast para obtener lineamientos sobre cómo incorporar el botón de ruta de acceso de contenido multimedia en tu aplicación.
Devoluciones de llamada de MediaRouter
Todas las apps que se ejecutan en el mismo dispositivo comparten una sola instancia de MediaRouter y sus rutas (filtradas por app con el MediaRouteSelector de la app). Cada actividad se comunica con MediaRouter
a través de su propia implementación de los métodos
MediaRouter.Callback. El MediaRouter llama a los métodos de devolución de llamada cada vez que el usuario selecciona, cambia o desconecta una ruta.
Existen varios métodos en la devolución de llamada que puedes anular para recibir información sobre los eventos de enrutamiento. Como mínimo, tu implementación de la clase MediaRouter.Callback debe anular onRouteSelected() y onRouteUnselected().
Como MediaRouter es un recurso compartido, tu aplicación debe administrar sus devoluciones de llamada de MediaRouter en respuesta a las devoluciones de llamada del ciclo de vida de la actividad habituales:
- Cuando se crea la actividad (
onCreate(Bundle)), toma un puntero alMediaRoutery mantenlo durante todo el ciclo de vida de la app. - Adjunta devoluciones de llamada a MediaRouter cuando la actividad se vuelva visible (
onStart()) y desconéctalas cuando se oculte (onStop()).
En la siguiente muestra de código, se indica cómo crear y guardar el objeto de devolución de llamada, cómo obtener una instancia de MediaRouter y cómo administrar las devoluciones de llamada.
Ten en cuenta el uso de la marca CALLBACK_FLAG_REQUEST_DISCOVERY cuando adjuntes las devoluciones de llamada en onStart().
Esto permite que tu MediaRouteSelector actualice la lista de rutas disponibles del botón de ruta de acceso de contenido multimedia.
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() } // ... }
El framework del router de contenido multimedia también proporciona una clase MediaRouteDiscoveryFragment, que se encarga de agregar y quitar la devolución de llamada para una actividad.
Nota: Si escribes una app de reproducción de música y quieres que reproduzca música mientras está en segundo plano, debes compilar un Service para la reproducción y llamar al framework del router de contenido multimedia desde las devoluciones de llamada del ciclo de vida del servicio.
Cómo controlar una ruta de reproducción remota
Cuando seleccionas una ruta de reproducción remota, tu app funciona como un control remoto. El dispositivo que se encuentra en el otro extremo de la ruta controla todas las funciones de recuperación, decodificación y reproducción de datos de contenido. Los controles de la IU de tu app se comunican con el dispositivo receptor a través de un objeto RemotePlaybackClient.
La clase RemotePlaybackClient proporciona métodos adicionales para administrar la reproducción de contenido. A continuación, se incluyen algunos de los métodos de reproducción clave de la clase RemotePlaybackClient:
play(): Reproduce un archivo multimedia específico, indicado por unUri.pause(): Pausa la pista de contenido multimedia que se está reproduciendo.resume(): Continúa reproduciendo la pista actual después de un comando de pausa.seek(): Se mueve a una posición específica en la pista actual.release(): Desconecta la app del dispositivo de reproducción remoto.
Puedes usar estos métodos para adjuntar acciones a los controles de reproducción que proporcionas en tu app. La mayoría de estos métodos también te permiten incluir un objeto de devolución de llamada para que puedas supervisar el progreso de la tarea de reproducción o la solicitud de control.
La clase RemotePlaybackClient también admite la puesta en cola de varios elementos multimedia para la reproducción y la administración de la cola de contenido multimedia.
Código de muestra
En los ejemplos de BasicMediaRouter y MediaRouter para Android, se muestra aún más el uso de la API de MediaRouter.