Visão geral do MediaRouteProvider

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.