Guia de migração do AndroidX Media3

Os apps que usam a biblioteca independente com.google.android.exoplayer2 e o androidx.media precisam migrar para o androidx.media3. Use o script de migração para migrar arquivos de build do Gradle, arquivos de origem Java e Kotlin e arquivos de layout XML do ExoPlayer 2.19.1 para o AndroidX Media3 1.1.1.

Visão geral

Antes de migrar, leia as seções a seguir para saber mais sobre os benefícios das novas APIs, as APIs a serem migradas e os pré-requisitos que o projeto do seu app precisa atender.

Por que migrar para o Jetpack Media3

  • Ela é a nova casa do ExoPlayer, enquanto o com.google.android.exoplayer2 foi descontinuado.
  • Acesse a API Player em componentes/processos com MediaBrowser/MediaController.
  • Use os recursos avançados das APIs MediaSession e MediaController.
  • Anuncie recursos de reprodução com controle de acesso refinado.
  • Simplifique seu app removendo MediaSessionConnector e PlayerNotificationManager.
  • Compatibilidade com versões anteriores com APIs de cliente media-compat (MediaBrowserCompat/MediaControllerCompat/MediaMetadataCompat)

APIs de mídia para migrar para o AndroidX Media3

  • ExoPlayer e extensões
    Isso inclui todos os módulos do projeto ExoPlayer legado, exceto o módulo mediasession, que foi descontinuado. Apps ou módulos que dependem de pacotes em com.google.android.exoplayer2 podem ser migrados com o script de migração.
  • MediaSessionConnector (dependendo dos pacotes androidx.media.* de androidx.media:media:1.4.3+)
    Remova o MediaSessionConnector e use o androidx.media3.session.MediaSession.
  • MediaBrowserServiceCompat (dependendo dos pacotes androidx.media.* de androidx.media:media:1.4.3+)
    Migre subclasses de androidx.media.MediaBrowserServiceCompat para androidx.media3.session.MediaLibraryService e código usando MediaBrowserCompat.MediaItem para androidx.media3.common.MediaItem.
  • MediaBrowserCompat (dependendo dos pacotes android.support.v4.media.* de androidx.media:media:1.4.3+)
    Migre o código do cliente usando MediaBrowserCompat ou MediaControllerCompat para usar androidx.media3.session.MediaBrowser com androidx.media3.common.MediaItem.

Pré-requisitos

  1. Verifique se o projeto está sob controle de origem

    Verifique se é possível reverter facilmente as mudanças aplicadas pelas ferramentas de migração programadas. Se você ainda não tem seu projeto sob controle de origem, agora é um bom momento para começar. Se, por algum motivo, você não quiser fazer isso, crie uma cópia de backup do projeto antes de iniciar a migração.

  2. Atualizar o app

    • Recomendamos atualizar o projeto para usar a versão mais recente da biblioteca ExoPlayer e remover todas as chamadas para métodos descontinuados. Se você pretende usar o script para a migração, a versão para a qual você está atualizando precisa ser compatível com a versão processada pelo script.

    • Aumente a compileSdkVersion do seu app para pelo menos 32.

    • Faça upgrade do Gradle e do plug-in do Gradle do Android Studio para uma versão recente que funcione com as dependências atualizadas acima. Por exemplo:

      • Versão do plug-in do Android para Gradle: 7.1.0
      • Versão do Gradle: 7.4
    • Substitua todas as instruções de importação de caracteres curinga que usam um asterisco (*) por instruções de importação totalmente qualificadas: exclua as instruções de importação de caracteres curinga e use o Android Studio para importar as instruções totalmente qualificadas (F2 - Alt/Enter, F2 - Alt/Enter, ...).

    • Migrar de com.google.android.exoplayer2.PlayerView para com.google.android.exoplayer2.StyledPlayerView. Isso é necessário porque não há equivalente a com.google.android.exoplayer2.PlayerView no AndroidX Media3.

Migrar o ExoPlayer com suporte a scripts

O script facilita a migração de com.google.android.exoplayer2 para a nova estrutura de pacote e módulo em androidx.media3. O script aplica algumas verificações de validação no seu projeto e mostra avisos se a validação falhar. Caso contrário, ele aplica os mapeamentos de classes e pacotes renomeados nos recursos de um projeto do Android Gradle escrito em Java ou Kotlin.

usage: ./media3-migration.sh [-p|-c|-d|-v]|[-m|-l [-x <path>] [-f] PROJECT_ROOT]
 PROJECT_ROOT: path to your project root (location of 'gradlew')
 -p: list package mappings and then exit
 -c: list class mappings (precedence over package mappings) and then exit
 -d: list dependency mappings and then exit
 -l: list files that will be considered for rewrite and then exit
 -x: exclude the path from the list of file to be changed: 'app/src/test'
 -m: migrate packages, classes and dependencies to AndroidX Media3
 -f: force the action even when validation fails
 -v: print the exoplayer2/media3 version strings of this script
 -h, --help: show this help text

Como usar o script de migração

  1. Faça o download do script de migração na tag do projeto ExoPlayer no GitHub correspondente à versão para a qual você atualizou o app:

    curl -o media3-migration.sh \
      "https://raw.githubusercontent.com/google/ExoPlayer/r2.19.1/media3-migration.sh"
    
  2. Torne o script executável:

    chmod 744 media3-migration.sh
    
  3. Execute o script com --help para saber mais sobre as opções.

  4. Execute o script com -l para listar o conjunto de arquivos selecionados para migração (use -f para forçar a listagem sem avisos):

    ./media3-migration.sh -l -f /path/to/gradle/project/root
    
  5. Execute o script com -m para mapear pacotes, classes e módulos para a Media3. Executar o script com a opção -m vai aplicar mudanças aos arquivos selecionados.

    • Parar no erro de validação sem fazer mudanças
    ./media3-migration.sh -m /path/to/gradle/project/root
    
    • Execução forçada

    Se o script encontrar uma violação dos pré-requisitos, a migração poderá ser forçada com a flag -f:

    ./media3-migration.sh -m -f /path/to/gradle/project/root
    
 # list files selected for migration when excluding paths
 ./media3-migration.sh -l -x "app/src/test/" -x "service/" /path/to/project/root
 # migrate the selected files
 ./media3-migration.sh -m -x "app/src/test/" -x "service/" /path/to/project/root

Conclua estas etapas manuais depois de executar o script com a opção -m:

  1. Verifique como o script mudou seu código: use uma ferramenta de diff e corrija possíveis problemas. Considere registrar um bug se você achar que o script tem um problema geral que foi introduzido sem passar a opção -f.
  2. Crie o projeto: use ./gradlew clean build ou, no Android Studio, escolha File > Sync Project with Gradle Files, depois Build > Clean project e, por fim, Build > Rebuild project. Monitore a criação na guia 'Build - Build Output' do Android Studio.

Próximas etapas recomendadas:

  1. Resolva o aceite para erros relacionados ao uso de APIs instáveis.
  2. Substitua as chamadas de API descontinuadas: use a API de substituição sugerida. Mantenha o ponteiro sobre o aviso no Android Studio e consulte o JavaDoc do símbolo descontinuado para descobrir o que usar em vez de uma determinada chamada.
  3. Ordenar as instruções de importação: abra o projeto no Android Studio, clique com o botão direito do mouse em um nó de pasta de pacote no visualizador de projetos e escolha Otimizar importações nos pacotes que contêm os arquivos de origem alterados.

Substitua MediaSessionConnector por androidx.media3.session.MediaSession.

No mundo legado do MediaSessionCompat, o MediaSessionConnector era responsável por sincronizar o estado do player com o estado da sessão e receber comandos de controladores que precisavam de delegação para métodos de player adequados. Com o AndroidX Media3, isso é feito diretamente pelo MediaSession sem exigir um conector.

  1. Remova todas as referências e o uso de MediaSessionConnector:se você usou o script automatizado para migrar classes e pacotes do ExoPlayer, é provável que o script tenha deixado seu código em um estado não compilável em relação ao MediaSessionConnector que não pode ser resolvido. O Android Studio vai mostrar o código corrompido quando você tentar criar ou iniciar o app.

  2. No arquivo build.gradle em que você mantém as dependências, adicione uma dependência de implementação ao módulo de sessão do AndroidX Media3 e remova a dependência legada:

    implementation "androidx.media3:media3-session:1.7.1"
    
  3. Substitua o MediaSessionCompat por androidx.media3.session.MediaSession.

  4. No site do código em que você criou o MediaSessionCompat legado, use androidx.media3.session.MediaSession.Builder para criar um MediaSession. Transmita o jogador para construir o criador de sessões.

    val player = ExoPlayer.Builder(context).build()
    mediaSession = MediaSession.Builder(context, player)
        .setSessionCallback(MySessionCallback())
        .build()
    
  5. Implemente MySessionCallback conforme necessário para seu app. Isso é opcional. Se você quiser permitir que os controladores adicionem itens de mídia ao player, implemente MediaSession.Callback.onAddMediaItems(). Ele atende a vários métodos de API atuais e legados que adicionam itens de mídia ao player para reprodução de maneira compatível com versões anteriores. Isso inclui os métodos MediaController.set/addMediaItems() do controlador Media3, bem como os métodos TransportControls.prepareFrom*/playFrom* da API legada. Uma implementação de exemplo de onAddMediaItems pode ser encontrada no PlaybackService do app de demonstração da sessão.

  6. Libere a sessão de mídia no site do código em que você a destruiu antes da migração:

    mediaSession?.run {
      player.release()
      release()
      mediaSession = null
    }
    

Funcionalidade MediaSessionConnector na Media3

A tabela a seguir mostra as APIs Media3 que processam funcionalidades implementadas anteriormente em MediaSessionConnector.

MediaSessionConnectorAndroidX Media3
CustomActionProvider MediaSession.Callback.onCustomCommand()/ MediaSession.setMediaButtonPreferences()
PlaybackPreparer MediaSession.Callback.onAddMediaItems() (prepare() é chamado internamente)
QueueNavigator ForwardingSimpleBasePlayer
QueueEditor MediaSession.Callback.onAddMediaItems()
RatingCallback MediaSession.Callback.onSetRating()
PlayerNotificationManager DefaultMediaNotificationProvider/ MediaNotification.Provider

Migrar MediaBrowserService para MediaLibraryService

O AndroidX Media3 introduz o MediaLibraryService, que substitui o MediaBrowserServiceCompat. O JavaDoc de MediaLibraryService e da superclasse MediaSessionService oferece uma boa introdução à API e ao modelo de programação assíncrona do serviço.

O MediaLibraryService é compatível com versões anteriores do MediaBrowserService. Um app cliente que usa MediaBrowserCompat ou MediaControllerCompat continua funcionando sem mudanças no código ao se conectar a um MediaLibraryService. Para um cliente, é transparente se o app está usando um MediaLibraryService ou um MediaBrowserServiceCompat legado.

Diagrama de componentes do app com serviço, atividade e apps externos.
Figura 1: visão geral dos componentes do app de mídia
  1. Para que a compatibilidade com versões anteriores funcione, é necessário registrar as duas interfaces de serviço com seu serviço no AndroidManifest.xml. Assim, um cliente encontra seu serviço pela interface de serviço necessária:

    <service android:name=".MusicService" android:exported="true">
        <intent-filter>
            <action android:name="androidx.media3.session.MediaLibraryService"/>
            <action android:name="android.media.browse.MediaBrowserService" />
        </intent-filter>
    </service>
    
  2. No arquivo build.gradle em que você mantém as dependências, adicione uma dependência de implementação ao módulo de sessão do AndroidX Media3 e remova a dependência legada:

    implementation "androidx.media3:media3-session:1.7.1"
    
  3. Mude seu serviço para herdar de um MediaLibraryService em vez de MediaBrowserService Como dito anteriormente, o MediaLibraryService é compatível com o MediaBrowserService legado. Portanto, a API mais ampla que o serviço está oferecendo aos clientes ainda é a mesma. Portanto, é provável que um app possa manter a maior parte da lógica necessária para implementar o MediaBrowserService e adaptá-lo para o novo MediaLibraryService.

    As principais diferenças em comparação com o MediaBrowserServiceCompat legado são as seguintes:

    • Implemente os métodos de ciclo de vida do serviço:os métodos que precisam ser substituídos no próprio serviço são onCreate/onDestroy, em que um app aloca/libera a sessão da biblioteca, o player e outros recursos. Além dos métodos padrão de ciclo de vida do serviço, um app precisa substituir onGetSession(MediaSession.ControllerInfo) para retornar o MediaLibrarySession criado em onCreate.

    • Implemente MediaLibraryService.MediaLibrarySessionCallback:para criar uma sessão, é necessário um MediaLibraryService.MediaLibrarySessionCallback que implemente os métodos reais da API de domínio. Em vez de substituir os métodos da API do serviço legado, você vai substituir os métodos do MediaLibrarySession.Callback.

      O callback é usado para criar o MediaLibrarySession:

      mediaLibrarySession =
            MediaLibrarySession.Builder(this, player, MySessionCallback())
               .build()
      

      Encontre a API completa do MediaLibrarySessionCallback na documentação da API.

    • Implemente MediaSession.Callback.onAddMediaItems(): o callback onAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>) atende vários métodos de API atuais e legados que adicionam itens de mídia ao player para reprodução de maneira compatível com versões anteriores. Isso inclui os métodos MediaController.set/addMediaItems() do controlador Media3, além dos métodos TransportControls.prepareFrom*/playFrom* da API legada. Uma implementação de amostra do callback pode ser encontrada no PlaybackService do app de demonstração da sessão.

    • O AndroidX Media3 está usando androidx.media3.common.MediaItem em vez de MediaBrowserCompat.MediaItem e MediaMetadataCompat. As partes do seu código vinculadas às classes legadas precisam ser alteradas de acordo ou mapeadas para o MediaItem do Media3.

    • O modelo geral de programação assíncrona mudou para Futures em contraste com a abordagem Result separável do MediaBrowserServiceCompat. A implementação do serviço pode retornar um ListenableFuture assíncrono em vez de separar um resultado ou retornar um Future imediato para retornar um valor diretamente.

Remover PlayerNotificationManager

O MediaLibraryService oferece suporte a notificações de mídia automaticamente, e o PlayerNotificationManager pode ser removido ao usar um MediaLibraryService ou MediaSessionService.

Um app pode personalizar a notificação definindo um MediaNotification.Provider personalizado em onCreate() que substitui o DefaultMediaNotificationProvider. O MediaLibraryService cuida de iniciar o serviço em primeiro plano conforme necessário.

Ao substituir MediaLibraryService.updateNotification(), um app pode assumir totalmente a responsabilidade de postar uma notificação e iniciar/parar o serviço em primeiro plano conforme necessário.

Migrar código do cliente usando um MediaBrowser

Com o AndroidX Media3, um MediaBrowser implementa as interfaces MediaController/Player e pode ser usado para controlar a reprodução de mídia, além de navegar pela biblioteca de mídia. Se você precisasse criar um MediaBrowserCompat e um MediaControllerCompat no mundo legado, faça o mesmo usando apenas o MediaBrowser na Media3.

Um MediaBrowser pode ser criado e aguardar o estabelecimento da conexão com o serviço:

scope.launch {
    val sessionToken =
        SessionToken(context, ComponentName(context, MusicService::class.java)
    browser =
        MediaBrowser.Builder(context, sessionToken))
            .setListener(BrowserListener())
            .buildAsync()
            .await()
    // Get the library root to start browsing the library.
    root = browser.getLibraryRoot(/* params= */ null).await();
    // Add a MediaController.Listener to listen to player state events.
    browser.addListener(playerListener)
    playerView.setPlayer(browser)
}

Consulte Controlar a reprodução na sessão de mídia para saber como criar um MediaController para controlar a reprodução em segundo plano.

Outras etapas e limpeza

Erros de API instáveis

Depois de migrar para o Media3, talvez você veja erros de lint sobre usos instáveis da API. Essas APIs são seguras para uso, e os erros de lint são um subproduto das nossas novas garantias de compatibilidade binária. Se você não precisar de compatibilidade binária estrita, esses erros poderão ser suprimidos com segurança usando uma anotação @OptIn.

Contexto

Nem o ExoPlayer v1 nem o v2 ofereciam garantias estritas sobre a compatibilidade binária da biblioteca entre versões subsequentes. A superfície da API ExoPlayer é muito grande por design para permitir que os apps personalizem quase todos os aspectos da reprodução. Versões subsequentes do ExoPlayer ocasionalmente introduziam renomeações de símbolos ou outras mudanças incompatíveis (por exemplo, novos métodos obrigatórios em interfaces). Na maioria dos casos, essas falhas foram atenuadas com a introdução do novo símbolo e a descontinuação do antigo por algumas versões, para permitir que os desenvolvedores migrassem os usos. No entanto, isso nem sempre foi possível.

Essas mudanças incompatíveis resultaram em dois problemas para os usuários das bibliotecas ExoPlayer v1 e v2:

  1. Um upgrade da versão do ExoPlayer pode fazer com que o código pare de ser compilado.
  2. Um app que dependia do ExoPlayer diretamente e por uma biblioteca intermediária precisava garantir que ambas as dependências fossem da mesma versão. Caso contrário, incompatibilidades binárias poderiam resultar em falhas de execução.

Melhorias na Media3

O Media3 garante a compatibilidade binária para um subconjunto da plataforma de API. As partes que não garantem a compatibilidade binária são marcadas com @UnstableApi. Para deixar essa distinção clara, os usos de símbolos de API instáveis geram um erro de lint, a menos que sejam anotados com @OptIn.

Depois de migrar do ExoPlayer v2 para o Media3, talvez você veja muitos erros de lint de API instáveis. Isso pode fazer parecer que a Media3 é "menos estável" que o ExoPlayer v2. Esse não é o caso. As partes "instáveis" da API Media3 têm o mesmo nível de estabilidade que toda a superfície da API ExoPlayer v2, e as garantias da superfície da API Media3 estável não estão disponíveis no ExoPlayer v2. A diferença é que um erro do lint agora alerta sobre os diferentes níveis de estabilidade.

Processar erros instáveis de lint da API

Consulte a seção de solução de problemas sobre esses erros de lint para saber como anotar usos em Java e Kotlin de APIs instáveis com @OptIn.

APIs descontinuadas

Você pode notar que as chamadas para APIs descontinuadas estão tachadas no Android Studio. Recomendamos substituir essas chamadas pela alternativa adequada. Passe o cursor sobre o símbolo para ver o JavaDoc que informa qual API usar.

Captura de tela: como mostrar o JavaDoc com uma alternativa para o método descontinuado
Figura 3: a dica do JavaDoc no Android Studio sugere uma alternativa para qualquer símbolo descontinuado.

Exemplos de código e apps de demonstração