Como usar uma sessão de mídia

As sessões de mídia oferecem uma maneira universal de interagir com um player de áudio ou vídeo. Ao informar ao Android que a mídia está sendo reproduzida em um app, os controles de mídia podem ser delegados ao app. A integração com a sessão de mídia permite que um app anuncie a reprodução de mídia externamente e receba comandos de reprodução de fontes externas. Essas fontes podem ser botões físicos (como o botão de reprodução em um fone de ouvido ou controle remoto da TV) ou comandos indiretos (como instruir "pausar" ao Google Assistente). A sessão de mídia delega esses comandos ao app, que os aplica ao player de mídia, para o qual é transparente de onde os comandos se originaram.

Uma sessão de mídia convive com o player que a gerencia. Crie e inicialize uma sessão de mídia no método onCreate() da atividade ou do serviço que possui a sessão de mídia e o player associado.

Inicializar a sessão de mídia

Uma sessão de mídia recém-criada não tem recursos. Para inicializar a sessão, siga estas etapas:

  • Defina sinalizações para que a sessão de mídia possa receber callbacks de controladores e botões de mídia.
  • Crie e inicialize uma instância de PlaybackStateCompat e atribua-a à sessão. O estado de reprodução muda ao longo da sessão, então recomendamos armazenar em cache o PlaybackStateCompat.Builder para reutilização.
  • Crie uma instância de MediaSessionCompat.Callback e atribua-a à sessão (mais informações sobre callbacks abaixo).

Crie e inicialize uma sessão de mídia no método onCreate() da atividade ou do serviço que possui a sessão.

Para que os botões de mídia funcionem quando o app for inicializado (ou interrompido), o PlaybackState precisa conter uma ação de reprodução correspondente à intent enviada pelo botão de mídia. Por isso, ACTION_PLAY é atribuído ao estado da sessão durante a inicialização. Para mais informações, consulte Como responder a botões de mídia.

Manter o estado de reprodução e os metadados

Há duas classes que representam o estado de uma sessão de mídia.

A classe PlaybackStateCompat descreve o estado operacional atual do player. Isso inclui:

  • O estado de transporte (se o player está reproduzindo/pausado/armazenando em buffer etc. Consulte getState())
  • Um código do erro e uma mensagem de erro opcional, quando aplicável. Consulte getErrorCode() e leia Estados e erros abaixo.
  • A posição do player
  • As ações válidas do controlador que podem ser processadas no estado atual

A classe MediaMetadataCompat descreve o material que está sendo reproduzido:

  • O nome do artista, álbum e faixa
  • A duração da faixa
  • Arte do álbum para exibição na tela de bloqueio. A imagem é um bitmap com um tamanho máximo de 320 x 320 dp (se for maior, ela será reduzida).
  • Uma instância de ContentUris que aponta para uma versão maior da arte.

O estado do player e os metadados podem mudar durante a vida útil de uma sessão de mídia. Sempre que o estado ou os metadados mudarem, use o builder correspondente para cada classe, PlaybackStateCompat.Builder() ou MediaMetadataCompat.Builder(), e transmita a nova instância para a sessão de mídia chamando setPlaybackState() ou setMetaData(). Para reduzir o consumo geral de memória dessas operações frequentes, é recomendável criar os builders uma vez e reutilizá-los durante toda a sessão.

Estados e erros

Observe que PlaybackState é um objeto que contém valores separados para o estado de reprodução da sessão (getState()) e, quando necessário, um código do erro associado (getErrorCode()). Os erros podem ser fatais ou não fatais:

Sempre que a reprodução for interrompida, gere um erro fatal: defina o estado de transporte como STATE_ERROR e especifique um erro associado com setErrorMessage(int, CharSequence). Enquanto a reprodução estiver bloqueada pelo erro, o PlaybackState vai continuar relatando STATE_ERROR e o erro.

Um erro não fatal ocorre quando o app não consegue processar uma solicitação, mas pode continuar a reprodução: o transporte permanece em um estado "normal" (como STATE_PLAYING), mas o PlaybackState contém um código do erro. Por exemplo, se a última música estiver tocando e o usuário solicitar que a próxima música seja tocada, a reprodução poderá continuar, mas você precisará criar um novo PlaybackState com o código do erro ERROR_CODE_END_OF_QUEUE e chamar setPlaybackState(). Os controladores de mídia anexados à sessão vão receber o callback onPlaybackStateChanged() e explicar ao usuário o que aconteceu. Um erro não fatal só deve ser relatado uma vez, no momento em que ocorre. Na próxima vez que a sessão atualizar o PlaybackState, não defina o mesmo erro não fatal novamente, a menos que o erro tenha ocorrido em resposta a uma nova solicitação.

Telas de bloqueio de sessão de mídia

A partir do Android 4.0 (nível 14 da API), o sistema pode acessar o estado de reprodução e os metadados de uma sessão de mídia. É assim que a tela de bloqueio pode mostrar controles de mídia e artes. O comportamento varia de acordo com a versão do Android.

Arte do álbum

Do Android 4.0 (nível 14 da API) ao Android 10 (nível 29 da API), o plano de fundo da tela de bloqueio mostra a arte do álbum, mas apenas se os metadados da sessão de mídia incluírem um bitmap de plano de fundo.

Controles de transporte

No Android 4.0 (nível 14 da API) até o Android 4.4 (nível 19 da API), quando uma sessão de mídia está ativa e os metadados dela incluem um bitmap de plano de fundo, a tela de bloqueio mostra automaticamente os controles de transporte.

No Android 5.0 (nível 21 da API) ou versões mais recentes, o sistema não oferece controles de transporte na tela de bloqueio. Em vez disso, use uma notificação MediaStyle para mostrar os controles de transporte.

Adicionar ações personalizadas

Os aplicativos de mídia podem definir ações personalizadas, como "gostei", "curtir" ou "voltar 30 segundos". Uma ação personalizada precisa implementar um comportamento totalmente novo. Não use uma ação personalizada para substituir uma das ações de controle de transporte padrão definidas em PlaybackStateCompat.

Adicione ações personalizadas com addCustomAction(). O exemplo a seguir mostra como adicionar um controle para uma ação de "gostei":

Kotlin

stateBuilder.addCustomAction(
        PlaybackStateCompat.CustomAction.Builder(
                CUSTOM_ACTION_THUMBS_UP,
                resources.getString(R.string.thumbs_up),
                thumbsUpIcon
        ).run {
            setExtras(customActionExtras)
            build()
        }
)

Java

stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
    CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
    .setExtras(customActionExtras)
    .build());

Consulte Universal Music Player para ver um exemplo completo.

Você responde à ação com onCustomAction().

Kotlin

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

Java

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

Consulte também Universal Music Player (link em inglês).

Callbacks de sessão de mídia

Os principais métodos de callback de sessão de mídia são onPlay(), onPause() e onStop(). É aqui que você adiciona o código que controla o player.

Como você instancia e define o callback da sessão no momento da execução (em onCreate()), seu app pode definir callbacks alternativos que usam players diferentes e escolher a combinação adequada de callback e player, dependendo do dispositivo e do nível do sistema. É possível mudar o player sem alterar o restante do app. Por exemplo, você pode usar o ExoPlayer (link em inglês) ao executar no Android 4.1 (nível 16 da API) ou mais recente e usar o MediaPlayer em sistemas anteriores.

Além de controlar o player e gerenciar as transições de estado da sessão de mídia, os callbacks também ativam e desativam recursos do app e controlam como ele interage com outros apps e com o hardware do dispositivo. Consulte Como controlar a saída de áudio.

A implementação dos métodos de callback da sessão de mídia depende da estrutura do app. Consulte as páginas separadas que descrevem como usar callbacks em apps de áudio e apps de vídeo, além de como os callbacks precisam ser implementados para cada tipo de app.