O framework do roteador de mídia do Android permite que os fabricantes ativem a reprodução nos dispositivos
usando uma interface padronizada chamada MediaRouteProvider.
Um provedor de rota define uma interface comum para abrir mídia em um dispositivo receptor, possibilitando
a reprodução de mídia no seu equipamento usando qualquer app Android compatível com rotas
de mídia.
Este guia discute como criar um provedor de rota de mídia para um dispositivo receptor e disponibilizá-lo
para outros aplicativos de reprodução de mídia executados no Android. Para usar essa API, você
precisa conhecer as principais classes
MediaRouteProvider,
MediaRouteProviderDescriptor e
RouteController.
Visão geral
O framework do roteador de mídia do Android permite que desenvolvedores de apps de música e fabricantes de dispositivos de reprodução de mídia
se conectem usando uma API e uma interface do usuário comuns. Os desenvolvedores de apps que
implementam uma interface MediaRouter podem se conectar ao
framework e reproduzir conteúdo em dispositivos que participam do framework do roteador de mídia. Os fabricantes de dispositivos de reprodução de mídia podem participar do framework publicando um MediaRouteProvider que permite que outros aplicativos se conectem e reproduzam mídia nos dispositivos receptores. A Figura 1 ilustra como um app se conecta a um dispositivo receptor
pelo framework do roteador de mídia.
Figura 1. Visão geral de como as classes de provedor de rota de mídia fornecem comunicação de um app de música para um dispositivo receptor.
Quando você cria um provedor de rota de mídia para seu dispositivo receptor, ele serve para as seguintes finalidades:
- Descreva e publique os recursos do dispositivo receptor para que outros apps possam descobri-lo e usar os recursos de reprodução dele.
- Encapsule a interface de programação do dispositivo receptor e os mecanismos de transporte de comunicação para tornar o dispositivo compatível com o framework do roteador de mídia.
Distribuição de provedores de roteamento
Um provedor de rota de mídia é distribuído como parte de um app Android. Seu provedor de rota pode ser
disponibilizado para outros apps estendendo
MediaRouteProviderService ou envolvendo sua implementação de
MediaRouteProvider com seu próprio serviço e declarando um filtro
de intent para o provedor de rota de mídia. Essas etapas permitem que outros apps descubram e usem
sua rota de mídia.
Observação: o app que contém o provedor de rota de mídia também pode incluir uma interface MediaRouter para o provedor de rota, mas isso não é obrigatório.
Biblioteca de suporte MediaRouter
As APIs do roteador de mídia são definidas na biblioteca MediaRouter do AndroidX. É necessário adicionar essa biblioteca ao projeto de desenvolvimento do app. Para mais informações sobre como adicionar bibliotecas de suporte ao seu projeto, consulte Configuração da biblioteca de suporte.
Atenção: use a implementação AndroidX
do framework do roteador de mídia.
Não use o pacote android.media mais antigo.
Criar um serviço de provedor
O framework do roteador de mídia precisa ser capaz de descobrir e se conectar ao seu provedor de rota de mídia
para permitir que outros aplicativos usem sua rota. Para fazer isso, o framework do roteador de mídia
procura apps que declarem uma ação de intent do provedor de rota de mídia. Quando outro app quer se
conectar ao seu provedor, o framework precisa ser capaz de invocá-lo e se conectar a ele. Portanto, o provedor
precisa ser encapsulado em um Service.
O exemplo de código abaixo mostra a declaração de um serviço de provedor de rota de mídia e o filtro de intent em um manifesto, o que permite que ele seja descoberto e usado pelo framework do roteador de mídia:
<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 exemplo de manifesto declara um serviço que une as classes reais do provedor de roteamento de mídia.
O framework do roteador de mídia do Android oferece a
classe MediaRouteProviderService para uso como um wrapper de serviço para
provedores de rota de mídia. O exemplo de código abaixo demonstra como usar essa classe
wrapper:
class SampleMediaRouteProviderService : MediaRouteProviderService() { override fun onCreateMediaRouteProvider(): MediaRouteProvider { return SampleMediaRouteProvider(this) } }
Especificar recursos de roteamento
Os apps que se conectam ao framework do roteador de mídia podem descobrir sua rota de mídia pelas declarações de manifesto do app, mas também precisam conhecer os recursos das rotas de mídia que você está fornecendo. As rotas de mídia podem ser de tipos diferentes e ter recursos diferentes, e outros apps precisam ser capazes de descobrir esses detalhes para determinar se são compatíveis com sua rota.
O framework do roteador de mídia permite definir e publicar os recursos do seu trajeto de mídia
usando objetos IntentFilter, MediaRouteDescriptor e um MediaRouteProviderDescriptor. Esta seção explica como usar essas
classes para publicar os detalhes da sua rota de mídia para outros apps.
Categorias de roteamento
Como parte da descrição programática do provedor de rota de mídia, é necessário especificar se o provedor é compatível com reprodução remota, saída secundária ou ambas. Estas são as categorias de rota fornecidas pelo framework do roteador de mídia:
CATEGORY_LIVE_AUDIO— Saída de áudio para um dispositivo de saída secundário, como um sistema de música sem fio.CATEGORY_LIVE_VIDEO— Saída de vídeo para um dispositivo de saída secundário, como dispositivos de display sem fio.CATEGORY_REMOTE_PLAYBACK: reproduz vídeo ou áudio em um dispositivo separado que processa a recuperação, a decodificação e a reprodução de mídia, como dispositivos Chromecast.
Para incluir essas configurações em uma descrição da rota de mídia, insira-as em
um objeto IntentFilter, que será adicionado posteriormente a um
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) } } }
Se você especificar a intent CATEGORY_REMOTE_PLAYBACK, também precisará definir quais tipos de mídia e
controles de mídia são compatíveis com seu provedor de rota de mídia. A próxima seção descreve como
especificar essas configurações para seu dispositivo.
Tipos de mídia e protocolos
Um provedor de rota de mídia para um dispositivo de reprodução remota precisa especificar os tipos de mídia e os protocolos de transferência
com que ele é compatível. Especifique essas configurações usando a classe IntentFilter
e os métodos addDataScheme() e
addDataType() desse objeto. O
snippet de código abaixo demonstra como definir um filtro de intent para oferecer suporte à reprodução de vídeo
remota usando http, https e o protocolo de streaming em tempo real (RTSP, na sigla em inglês):
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 mídia
Um provedor de rota de mídia que oferece reprodução remota precisa especificar os tipos de controles de mídia com suporte. Estes são os tipos de controle gerais que o roteamento de mídia pode oferecer:
- Controles de mídia, como reproduzir, pausar, voltar e avançar.
- Recursos de fila, que permitem que o app de envio adicione e remova itens de uma playlist mantida pelo dispositivo receptor.
- Recursos de sessão, que impedem que os apps de envio interfiram uns nos outros. Para isso, o dispositivo receptor fornece um ID de sessão ao app solicitante e, em seguida, verifica esse ID em cada solicitação de controle de mídia subsequente.
O exemplo de código a seguir demonstra como criar um filtro de intent para oferecer suporte aos controles de mídia básicos da rota de mídia:
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 mais informações sobre as intents de controle de mídia disponíveis, consulte a
classe MediaControlIntent.
MediaRouteProviderDescriptor
Depois de definir os recursos da rota de mídia usando objetos IntentFilter, você pode criar um objeto descritor para publicação no
framework do roteador de mídia do Android. Esse objeto descritor contém as especificações dos recursos da rota de mídia para que outros aplicativos possam determinar como interagir com ela.
O exemplo de código a seguir demonstra como adicionar os filtros de intent criados anteriormente a um
MediaRouteProviderDescriptor e definir o descritor para uso pelo
framework do roteador de mídia:
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 mais informações sobre as configurações de descritor disponíveis, consulte a documentação de referência
de MediaRouteDescriptor e MediaRouteProviderDescriptor.
Controlar roteamentos
Quando um aplicativo se conecta ao seu provedor de rota de mídia, ele recebe comandos de reprodução
pelo framework do roteador de mídia enviados à sua rota por outros apps. Para processar essas
solicitações, é necessário fornecer uma implementação de uma classe MediaRouteProvider.RouteController, que processa os comandos
e lida com a comunicação real com o dispositivo receptor.
O framework do roteador de mídia chama o método onCreateRouteController()
do provedor de rota para receber uma instância dessa classe e, em seguida, encaminha as solicitações para ela.
Estes são os principais métodos da classe MediaRouteProvider.RouteController, que você precisa implementar para
seu provedor de rota de mídia:
onSelect()— Chamado quando um aplicativo seleciona sua rota para reprodução. Use esse método para fazer qualquer trabalho de preparação que possa ser necessário antes do início da reprodução de mídia.onControlRequest(): envia comandos de reprodução específicos para o dispositivo receptor.onSetVolume(): envia uma solicitação ao dispositivo receptor para definir o volume de reprodução como um valor específico.onUpdateVolume(): envia uma solicitação ao dispositivo receptor para modificar o volume de reprodução em um valor especificado.onUnselect(): chamado quando um aplicativo cancela a seleção de um roteamento.onRelease(): chamado quando a rota não é mais necessária para o framework, permitindo que ele libere os recursos.
Todas as solicitações de controle de mídia, exceto as mudanças de volume, são direcionadas ao método
onControlRequest(). Sua implementação desse método precisa analisar as solicitações de controle e responder a elas
adequadamente. Veja um exemplo de implementação desse método que processa comandos para uma
rota de mídia de reprodução 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 } } // ... }
É importante entender que a classe MediaRouteProvider.RouteController serve como um wrapper
para a API do seu equipamento de reprodução de mídia. A implementação dos métodos nessa classe depende
totalmente da interface programática fornecida pelo dispositivo receptor.
Exemplo de código
O exemplo de MediaRouter mostra como criar um provedor de rota de mídia personalizado.