Esta página foi traduzida pela API Cloud Translation.

Ativar controle de reprodução

Para ativar a reprodução de mídia no Android Auto e no Android Automotive OS (AAOS), implemente controles de reprodução registrando uma sessão de mídia e processando os métodos de callback dela. Esta página explica a:

Registre um objeto MediaSessionCompat no serviço de navegador de mídia.
Implemente métodos MediaSessionCompat.Callback para responder às solicitações de reprodução do usuário.
Configure ações de reprodução padrão e personalizadas.
Defina o estado inicial de reprodução da sessão de mídia.
Adicione ícones para indicar o formato de áudio.
Criar links com base em itens de mídia em reprodução.

O Android Auto e o AAOS enviam comandos de controle de reprodução por meio do MediaSessionCompat para seu serviço. Registre uma sessão e implemente os métodos de callback associados.

Registrar uma sessão de mídia

No método onCreate do seu serviço de navegação de mídia, crie uma instância de MediaSessionCompat e chame setSessionToken para registrar a sessão de mídia. Este snippet de código mostra como criar e registrar uma sessão de mídia:

Kotlin

override fun onCreate() {
    super.onCreate()
    ...
    // Start a new MediaSession.
    val session = MediaSessionCompat(this, "session tag").apply {
        // Set a callback object that implements MediaSession.Callback
        // to handle play control requests.
        setCallback(MyMediaSessionCallback())
    }
    sessionToken = session.sessionToken
    ...
}

Java

public void onCreate() {
    super.onCreate();
    ...
    // Start a new MediaSession.
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

    // Set a callback object that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

Ao criar o objeto de sessão de mídia, você define um objeto de callback usado para processar solicitações de controle de mídia. Crie esse objeto de callback fornecendo uma implementação da classe MediaSessionCompat.Callback para o app. A próxima seção discute como implementar esse objeto.

Implementar comandos de reprodução

Quando um usuário solicita a reprodução de um item de mídia no seu app, o Android Automotive OS e o Android Auto usam a classe MediaSessionCompat.Callback no objeto MediaSessionCompat recebido do serviço de navegação de mídia do app. Quando um usuário quer controlar a reprodução de conteúdo, como pausar a reprodução ou pular para a próxima faixa, o Android Auto e o Android Automotive OS invocam um dos métodos de callback do objeto.

Para gerenciar a reprodução de conteúdo, seu app precisa estender a classe abstrata MediaSessionCompat.Callback e implementar os métodos compatíveis.

Implemente cada um dos métodos de callback que fazem sentido para o tipo de conteúdo oferecido pelo seu app:

onPrepare: O AAOS invoca esse método quando a fonte de mídia muda.
onPlay: Invocado quando o usuário seleciona a opção de reproduzir sem escolher um item específico. O app vai precisar abrir o conteúdo padrão ou, se a reprodução tiver sido pausada com onPause, o app vai retomá-la.

Observação: não é recomendado que seu app comece automaticamente a tocar músicas quando o Android Automotive OS ou o Android Auto se conectarem ao serviço de navegação de mídia. Para saber mais, consulte Configurar o PlaybackState inicial.
onPlayFromMediaId: Invocado quando o usuário escolhe reproduzir um item específico. O método recebe o ID que o serviço de navegação de mídia atribuiu ao item de mídia na hierarquia de conteúdo.
onPlayFromSearch: Invocado quando o usuário escolhe reproduzir a partir de uma consulta de pesquisa. O app precisa fazer uma escolha apropriada com base na string de pesquisa que foi transmitida.
onPause: Invocado quando o usuário decide pausar a reprodução.
onSkipToNext: Invocado quando o usuário decide pular para o próximo item.
onSkipToPrevious: Invocado quando o usuário decide pular para o item anterior.
onStop: Invocado quando o usuário decide parar a reprodução. Substitua esses métodos no seu app para fornecer o resultado escolhido. Não é necessário implementar um método se a finalidade dele não for compatível com o app. Por exemplo, se o app fizer uma transmissão ao vivo, como uma esportiva, não será necessário implementar onSkipToNext. Em vez disso, use a implementação padrão de onSkipToNext.

Seu app não precisa de nenhuma lógica especial para reproduzir o conteúdo pelos alto-falantes do carro. Quando o app recebe uma solicitação para reproduzir conteúdo, ele toca o áudio da mesma forma que o conteúdo é reproduzido pelos alto-falantes do smartphone ou fones de ouvido do usuário. O Android Auto e o AAOS enviam automaticamente o conteúdo de áudio ao sistema do carro para tocar nos alto-falantes do carro.

Para saber mais sobre como tocar conteúdo de áudio, consulte Visão geral do Media Player, Visão geral do app de áudio e a Visão geral do ExoPlayer.

Definir ações de reprodução padrão

O Android Auto e o AAOS mostram controles de mídia com base nas ações ativadas no objeto PlaybackStateCompat. Por padrão, seu app precisa ser compatível com as seguintes ações:

O app também pode oferecer suporte às ações abaixo caso elas sejam relevantes para o conteúdo:

Além disso, você pode criar uma fila de reprodução para mostrar ao usuário. Para fazer isso, chame os métodos setQueue e setQueueTitle, ative a ação ACTION_SKIP_TO_QUEUE_ITEM e defina o callback onSkipToQueueItem.

Além disso, adicione suporte ao ícone Tocando agora, que é um indicador do que está sendo reproduzido. Para fazer isso, chame o método setActiveQueueItemId e transmita o ID do item em reprodução na fila. É necessário atualizar setActiveQueueItemId sempre que houver uma mudança na fila.

O Android Auto e o AAOS mostram botões para cada ação ativada e para a fila de reprodução. Quando os usuários clicam nesses botões, o sistema invoca o callback correspondente de MediaSessionCompat.Callback.

Reservar espaço não utilizado

O Android Auto e o AAOS reservam espaço na interface para as ações ACTION_SKIP_TO_PREVIOUS e ACTION_SKIP_TO_NEXT. Se o app não oferecer suporte a uma dessas funções, o Android Auto e o AAOS usarão o espaço para mostrar as ações personalizadas que você criar.

Se você não quiser preencher esses espaços com ações personalizadas, poderá reservá-los para que o Android Auto e o AAOS deixem o espaço em branco sempre que o app não oferecer suporte à função correspondente.

Para fazer isso, chame o método setExtras com um pacote de extras que contenha constantes correspondentes às funções reservadas. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT corresponde a ACTION_SKIP_TO_NEXT e SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV corresponde a ACTION_SKIP_TO_PREVIOUS. Use essas constantes como chaves no pacote e use o booleano true como valores.

Configurar o PlaybackState inicial

À medida que o Android Auto e o AAOS se comunicam com o serviço de navegação de mídia, a sessão de mídia informa o status da reprodução do conteúdo usando PlaybackStateCompat.

Não é recomendado que o app comece a tocar músicas automaticamente quando o AAOS ou o Android Auto se conectarem ao serviço de navegação de mídia. Em vez disso, o Android Auto e o AAOS precisam retomar ou iniciar a reprodução com base no estado do carro ou nas ações do usuário.

Para isso, configure o PlaybackStateCompat inicial da sessão de mídia como STATE_STOPPED, STATE_PAUSED, STATE_NONE ou STATE_ERROR.

As sessões de mídia no Android Auto e no AAOS duram apenas o tempo da viagem, portanto, os usuários iniciam e interrompem essas sessões com frequência. Para promover uma experiência contínua entre viagens, monitore o estado anterior da sessão do usuário para que, quando o app de música receber uma solicitação de retomada, o usuário possa continuar de onde parou (por exemplo, o último item de mídia reproduzido, o PlaybackStateCompat e a fila).

Adicionar ações de reprodução personalizadas

Você pode adicionar ações de reprodução personalizadas para mostrar mais ações com suporte do seu app de música. Se o espaço permitir (e você não o reservar), o Android adicionará as ações personalizadas aos controles de transporte. Caso contrário, as ações personalizadas vão aparecer no menu Flutuante. O Android mostra as ações personalizadas na ordem em que você as adiciona ao PlaybackStateCompat.

Use-as para oferecer um comportamento diferente das ações padrão. Não as use para substituir ou duplicar ações padrão.

Para adicionar ações personalizadas, use o método addCustomAction na classe PlaybackStateCompat.Builder. Este snippet de código mostra como adicionar uma ação personalizada a "Iniciar um canal de rádio":

Kotlin

val customActionExtras = Bundle()
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO)

stateBuilder.addCustomAction(
    PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon // or R.drawable.media3_icon_radio
    ).run {
        setExtras(customActionExtras)
        build()
    }
)

Java

Bundle customActionExtras = new Bundle();
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO);

stateBuilder.addCustomAction(
    new PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon) // or R.drawable.media3_icon_radio
    .setExtras(customActionExtras)
    .build());

Para conferir um exemplo mais detalhado, consulte o método setCustomAction (link em inglês) no app de exemplo Universal Android Music Player no GitHub. Depois de criar sua ação personalizada, a sessão de mídia poderá responder às ações substituindo o método onCustomAction.

Este snippet de código mostra como o app pode responder a uma ação "Iniciar um canal de rádio":

Kotlin

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA -> {
            ...
        }
    }
}

Java

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_START_RADIO_FROM_MEDIA.equals(action)) {
        ...
    }
}

Para saber mais, consulte o método onCustomAction no app de exemplo Universal Android Music Player no GitHub (link em inglês).

Criar ícones para ações personalizadas

Cada ação personalizada que você cria requer um ícone.

Se a descrição desse ícone corresponder a uma das constantes CommandButton.ICON_, defina o valor inteiro para a chave EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT dos extras da ação personalizada. Em sistemas compatíveis, isso substitui o recurso de ícone transmitido para CustomAction.Builder, permitindo que os componentes do sistema renderizem de forma consistente sua ação e outras ações de reprodução.

Também é necessário especificar um recurso de ícone. Os apps de carros podem ser executados em diferentes tamanhos e densidades de tela. Portanto, os ícones que você fornece precisam ser drawables vetoriais. Use um drawable vetorial para dimensionar recursos sem perder detalhes. Um drawable vetorial pode alinhar bordas e cantos a limites de pixels em resoluções menores.

Se uma ação personalizada for com estado (se ela ativar ou desativar uma configuração de reprodução), forneça ícones diferentes para os diferentes estados. Assim, os usuários vão notar uma mudança quando selecionarem a ação.

Oferecer estilos alternativos de ícones para ações desativadas

Quando uma ação personalizada não estiver disponível para o contexto atual, troque o ícone da ação personalizada por um ícone alternativo que mostre a ação como desativada.

Indicar formato de áudio

Para indicar que a mídia em reprodução usa um formato de áudio especial, é possível especificar ícones renderizados em carros com suporte a esse recurso. Você pode definir KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI e KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI no pacote de extras do item de mídia em reprodução (transmitido para MediaSession.setMetadata). Defina ambos os extras para acomodar os diferentes layouts.

Além disso, você pode definir o extra KEY_IMMERSIVE_AUDIO para informar aos OEMs de carro que esse é um áudio imersivo. Eles precisam ter muito cuidado ao decidir se vão aplicar efeitos de áudio que possam interferir no conteúdo imersivo.

Adicionar links do item em reprodução

Você pode configurar o item de mídia em reprodução para que as legendas, a descrição ou ambos sejam links para outros itens de mídia. Isso permite que o usuário acesse rapidamente itens relacionados. Por exemplo, ele pode pular para outras músicas do mesmo artista ou para outros episódios de um podcast. Se o carro tiver suporte a esse recurso, os usuários poderão tocar no link para navegar até esse conteúdo.

Para adicionar links, configure os metadados KEY_SUBTITLE_LINK_MEDIA_ID (para vincular da legenda) ou KEY_DESCRIPTION_LINK_MEDIA_ID (para vincular da descrição). Para mais detalhes, consulte a documentação de referência desses campos de metadados.

Ativar controle de reprodução Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Registrar uma sessão de mídia

Kotlin

Java

Implementar comandos de reprodução

Definir ações de reprodução padrão

Reservar espaço não utilizado

Configurar o PlaybackState inicial

Adicionar ações de reprodução personalizadas

Kotlin

Java

Kotlin

Java

Criar ícones para ações personalizadas

Oferecer estilos alternativos de ícones para ações desativadas

Indicar formato de áudio

Adicionar links do item em reprodução

Ativar controle de reprodução