Guida alla migrazione di AndroidX Media3

App che attualmente utilizzano la versione autonoma com.google.android.exoplayer2 libreria e androidx.media devono eseguire la migrazione a androidx.media3. Utilizza le funzionalità di lo script di migrazione per eseguire la migrazione di file di build gradle, Java File sorgente Kotlin e file di layout XML di ExoPlayer 2.19.1 ad AndroidX Media3 1.1.1.

Panoramica

Prima di eseguire la migrazione, esamina le sezioni seguenti per scoprire di più sulla i vantaggi delle nuove API, le API di cui eseguire la migrazione e i prerequisiti che il progetto della tua app deve soddisfare.

Perché eseguire la migrazione a Jetpack Media3

• È la nuova dimora di ExoPlayer, mentre com.google.android.exoplayer2 è non più disponibile.
• Accedi all'API Player in tutti i componenti/processi con MediaBrowser/MediaController.
• Utilizza le funzionalità estese di MediaSession e API MediaController.
• Pubblicizza le funzionalità di riproduzione con il controllo dell'accesso granulare.
• Semplifica la tua app rimuovendo MediaSessionConnector e PlayerNotificationManager.
• Compatibile con le versioni precedenti con le API client media-compat (MediaBrowserCompat/MediaControllerCompat/MediaMetadataCompat)

API Media per la migrazione ad AndroidX Media3

• ExoPlayer e le sue estensioni
  Sono inclusi tutti i moduli del precedente progetto ExoPlayer, ad eccezione del Modulo mediasession non più disponibile. App o moduli a seconda è possibile eseguire la migrazione dei pacchetti in com.google.android.exoplayer2 con script di migrazione.
• MediaSessionConnector (a seconda del androidx.media.* pacchetti da androidx.media:media:1.4.3+)
  Rimuovi MediaSessionConnector e utilizza il androidx.media3.session.MediaSession.
• MediaBrowserServiceCompat (a seconda del androidx.media.* pacchetti da androidx.media:media:1.4.3+)
  Esegui la migrazione delle sottoclassi di androidx.media.MediaBrowserServiceCompat in androidx.media3.session.MediaLibraryService e codice utilizzando Da MediaBrowserCompat.MediaItem a androidx.media3.common.MediaItem.
• MediaBrowserCompat (a seconda del android.support.v4.media.* pacchetti da androidx.media:media:1.4.3+)
  Esegui la migrazione del codice client utilizzando MediaBrowserCompat o MediaControllerCompat per utilizzare androidx.media3.session.MediaBrowser con androidx.media3.common.MediaItem.

Prerequisiti

1. Assicurati che il progetto sia sotto il controllo del codice sorgente

   Assicurati di poter annullare facilmente le modifiche applicate dagli strumenti di migrazione basati su script. Se il tuo progetto non è ancora sotto il controllo del codice sorgente, è il momento giusto per cominciare. Se, per qualche motivo, non vuoi farlo, crea una del progetto prima di avviare la migrazione.

2. Aggiornare la tua app

   • Ti consigliamo di aggiornare il progetto in modo da utilizzare versione più recente della libreria ExoPlayer e rimuovi eventuali a metodi deprecati. Se intendi usa lo script per la migrazione, devi trovare una corrispondenza alla versione a cui stai eseguendo l'aggiornamento con la versione gestita dallo script.

   • Aumenta il valore di compileSdkVersion dell'app fino ad almeno 32.

   • Esegui l'upgrade di Gradle e del plug-in Gradle di Android Studio a una versione recente che funzioni con le dipendenze aggiornate di cui sopra. Per istanza:

     • Versione del plug-in Android Gradle: 7.1.0
     • Versione Gradle: 7.4

   • Sostituisci tutte le istruzioni di importazione con caratteri jolly che utilizzano un asterisco (*) e utilizza istruzioni di importazione complete: elimina il carattere jolly importare istruzioni e utilizzare Android Studio per importare i file istruzioni (F2 - Alt/Invio, F2 - Alt/Invio, ...).

   • Esegui la migrazione da com.google.android.exoplayer2.PlayerView a com.google.android.exoplayer2.StyledPlayerView. Questa operazione è necessaria perché non esiste una equivalente com.google.android.exoplayer2.PlayerView in AndroidX Media3.

Migrazione di ExoPlayer con supporto script

Lo script facilita il passaggio da com.google.android.exoplayer2 al nuovo struttura di pacchetti e moduli in androidx.media3. Lo script si applica alcuni controlli di convalida sul progetto e stampano avvisi se la convalida non va a buon fine. In caso contrario, applica le mappature delle classi e dei pacchetti rinominati nella risorse di un progetto Android Gradle scritto in Java o 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

Utilizzo dello script di migrazione

Avviso: lo script potrebbe mettere i file di build Gradle in uno stato inutilizzabile se il tuo le dichiarazioni delle dipendenze usano variabili o tecniche avanzate.

1. Scarica lo script di migrazione dal tag del progetto ExoPlayer su GitHub corrispondente alla versione a cui hai aggiornato l'app:

   curl -o media3-migration.sh \
     "https://raw.githubusercontent.com/google/ExoPlayer/r2.19.1/media3-migration.sh"
   

2. Rendi eseguibile lo script:

   chmod 744 media3-migration.sh
   

3. Esegui lo script con --help per scoprire di più sulle opzioni.

4. Esegui lo script con -l per elencare l'insieme di file selezionati per migrazione (utilizza -f per forzare la scheda senza avvisi):

   ./media3-migration.sh -l -f /path/to/gradle/project/root
   

5. Esegui lo script con -m per mappare pacchetti, classi e moduli a Media3. L'esecuzione dello script con l'opzione -m applicherà le modifiche allo script selezionato .

   • Interrompi all'errore di convalida senza apportare modifiche

   ./media3-migration.sh -m /path/to/gradle/project/root
   

   • Esecuzione forzata

   Se lo script rileva una violazione dei prerequisiti, la migrazione può essere forzato con il flag -f:

   ./media3-migration.sh -m -f /path/to/gradle/project/root
   

di Gemini Advanced.

Nota: puoi utilizzare il parametro -x per escludere un percorso dalla selezione per modificare.

 # 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

Completa questi passaggi manuali dopo aver eseguito lo script con l'opzione -m:

1. Controlla in che modo lo script ha modificato il codice: utilizza uno strumento di diff e correggi potenziali problemi (valuta la possibilità di segnalare un bug se ritieni che lo script abbia un problema generale introdotto senza passare l'opzione -f).
2. Crea il progetto: usa ./gradlew clean build o in Android Studio, seleziona File > Sincronizza il progetto con i file Gradle, quindi Crea > Pulisci il progetto e poi Crea > Ricrea il progetto (monitora la build nel 'Build - Output build' di Android Studio.

di Gemini Advanced.

Nota: in alcuni casi, lo script dovrebbe lasciare il progetto in uno stato che non si crea senza la migrazione manuale del codice. Lo script avvisa in merito e richiede l'opzione -f per forzarne l'esecuzione. Ad esempio, è questo il caso se un'app utilizza MediaSessionConnector e MediaSessionCompat. Consulta le prossima sezione per indicazioni su come eseguire la migrazione da MediaSessionConnector a Media3.

Passaggi successivi consigliati:

1. Risolvere l'opzione di attivazione per gli errori relativi all'utilizzo di API instabili.
2. Sostituisci le chiamate API ritirate: utilizza l'API sostitutiva suggerita. Tieni il puntatore sopra l'avviso in Android Studio e consulta il documento Java del simbolo deprecato per scoprire cosa usare al posto di una determinata chiamata.
3. Ordina le istruzioni di importazione: apri il progetto in Android Studio, quindi fai clic con il tasto destro del mouse sul nodo della cartella del pacchetto nel visualizzatore del progetto e scegli Ottimizza le importazioni per i pacchetti che contengono i file di origine modificati.

Sostituisci MediaSessionConnector con androidx.media3.session.MediaSession

Nel mondo precedente di MediaSessionCompat, MediaSessionConnector responsabile della sincronizzazione dello stato del player con lo stato della sessione e ricevere comandi dai controller che dovevano essere delegati i metodi del player. Con AndroidX Media3, MediaSession può fare direttamente senza richiedere un connettore.

1. Rimuovi tutti i riferimenti e l'utilizzo di MediaSessionConnector: se hai usato lo script automatico per eseguire la migrazione di classi e pacchetti ExoPlayer, quindi probabilmente ha lasciato il tuo codice in uno stato non compilabile riguardo lo MediaSessionConnector che non può essere risolto. Android Studio ti mostrano il codice non funzionante quando provi a creare o avviare l'app.

2. Nel file build.gradle in cui gestisci le dipendenze, aggiungi un la dipendenza dell'implementazione al modulo di sessione AndroidX Media3 e rimuovere la dipendenza legacy:

   implementation "androidx.media3:media3-session:1.4.0"
   

3. Sostituisci MediaSessionCompat con androidx.media3.session.MediaSession

4. Nel sito del codice in cui hai creato la versione precedente di MediaSessionCompat, usa androidx.media3.session.MediaSession.Builder per creare un MediaSession Supera il giocatore per costruire lo strumento per la creazione di sessioni.

   Nota: se la tua app usa un player diverso da ExoPlayer, devi ti serve un'implementazione Player personalizzata che puoi trasmettere MediaSession che sta eseguendo il wrapping del tuo player. Forniremo ulteriori indicazioni in merito a un'implementazione Player minima che funzioni insieme ai media dell'implementazione delle sessioni.

   val player = ExoPlayer.Builder(context).build()
   mediaSession = MediaSession.Builder(context, player)
       .setSessionCallback(MySessionCallback())
       .build()
   

   Nota: puoi intercettare qualsiasi chiamata al metodo Player racchiudendola in una ForwardingPlayer(player).

5. Implementa MySessionCallback come richiesto dalla tua app. Questa opzione è facoltativa. Se vuoi consentire ai controller di aggiungere elementi multimediali al player, implementare MediaSession.Callback.onAddMediaItems() Serve vari tipi di servizi metodi API precedenti che aggiungono elementi multimediali al player per la riproduzione in un compatibile con le versioni precedenti. È incluso il MediaController.set/addMediaItems() del controller Media3, come così come TransportControls.prepareFrom*/playFrom* dell'API legacy. Un'implementazione di esempio di onAddMediaItems può disponibile nella PlaybackService dell'app demo della sessione.

6. Rilascia la sessione multimediale nel sito del codice in cui hai eliminato la sessione prima della migrazione:

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

   Nota: è importante pubblicare la sessione multimediale prima di crearne una nuova con lo stesso ID. Media3 genera un'eccezione se un'app sta perdendo una sessione in esecuzione.

Funzionalità di MediaSessionConnector in Media3

La tabella seguente mostra le API Media3 che gestiscono la funzionalità implementato in precedenza in MediaSessionConnector.

MediaSessionConnector	AndroidX Media3
CustomActionProvider	MediaSession.Callback.onCustomCommand()/ MediaSession.setCustomLayout()
PlaybackPreparer	MediaSession.Callback.onAddMediaItems() (prepare() viene chiamato internamente)
QueueNavigator	ForwardingPlayer
QueueEditor	MediaSession.Callback.onAddMediaItems()
RatingCallback	MediaSession.Callback.onSetRating()
PlayerNotificationManager	DefaultMediaNotificationProvider/ MediaNotification.Provider

Esegui la migrazione di MediaBrowserService a MediaLibraryService

AndroidX Media3 introduce MediaLibraryService che sostituisce MediaBrowserServiceCompat. Il JavaDoc di MediaLibraryService e il suo super MediaSessionService forniscono una buona introduzione all'API e alla di programmazione asincrona del servizio.

MediaLibraryService è compatibile con le versioni precedenti MediaBrowserService. Un'app client che utilizza MediaBrowserCompat o MediaControllerCompat, continua a funzionare senza modifiche al codice durante la connessione a MediaLibraryService. Per un cliente, è trasparente se la tua app è utilizzando un'MediaLibraryService o una versione precedente di MediaBrowserServiceCompat.

Figura 1: panoramica del componente App multimediale

1. Affinché la compatibilità con le versioni precedenti funzioni, devi registrare entrambi i servizi interfacce con il tuo servizio in AndroidManifest.xml. In questo modo trova il tuo servizio tramite l'interfaccia richiesta:

   <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. Nel file build.gradle in cui gestisci le dipendenze, aggiungi un la dipendenza dell'implementazione dal modulo di sessione AndroidX Media3 e rimuovi la dipendenza precedente:

   implementation "androidx.media3:media3-session:1.4.0"
   

3. Modifica il servizio in modo che erediti da un MediaLibraryService anziché da MediaBrowserService Come detto in precedenza, MediaLibraryService è compatibile con la versione precedente MediaBrowserService. Di conseguenza, la più ampia API a cui appartiene il servizio ai clienti è la stessa. Quindi, è probabile che un'app possa mantenere gran parte della logica necessaria per implementare MediaBrowserService e adattarlo al nuovo MediaLibraryService.

   Le principali differenze rispetto alla versione precedente MediaBrowserServiceCompat sono i seguenti:

   • Implementare i metodi del ciclo di vita dei servizi:i metodi che devono da eseguire sul servizio stesso sono onCreate/onDestroy, dove l'app distribuisce/rilascia la sessione della raccolta, il player e altre Google Cloud. Oltre ai metodi standard del ciclo di vita dei servizi, un'app deve sostituire onGetSession(MediaSession.ControllerInfo) per restituire la MediaLibrarySession creata nel onCreate.

   • Implementazione di MediaLibraryService.MediaLibrarySessionCallback: creazione una sessione richiede MediaLibraryService.MediaLibrarySessionCallback che implementa gli effettivi metodi dell'API del dominio. Quindi, invece di eseguire l'override dei metodi API servizio precedente, eseguirai l'override dei metodi del MediaLibrarySession.Callback in alternativa.

     Il callback viene quindi utilizzato per creare MediaLibrarySession:

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

     Trovare l'API completa di MediaLibrarySessionCallback nell'API documentazione.

   • Implementare MediaSession.Callback.onAddMediaItems(): il callback onAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>) pubblicazioni vari metodi API attuali e precedenti che aggiungono elementi multimediali al player per la riproduzione in modo compatibile con le versioni precedenti. È incluso il MediaController.set/addMediaItems() del controller Media3, così come TransportControls.prepareFrom*/playFrom* dell'API legacy. Un'implementazione di esempio del callback disponibile nel PlaybackService dell'app demo della sessione.

   • AndroidX Media3 utilizza invece androidx.media3.common.MediaItem di MediaBrowserCompat.MediaItem e MediaMetadataCompat. Pezzi del codice legato alle classi legacy deve essere modificato di conseguenza oppure mappa al MediaItem di Media3.

   • Il modello di programmazione asincrono è cambiato in Futures in in contrasto con l'approccio rimovibile Result MediaBrowserServiceCompat. L'implementazione del servizio può restituire ListenableFuture asincrono anziché scollegare un risultato restituisce un futuro immediato per restituire direttamente un valore.

Rimuovi PlayerNotificationManager

Il MediaLibraryService supporta automaticamente le notifiche multimediali e il Puoi rimuovere PlayerNotificationManager se utilizzi MediaLibraryService o MediaSessionService.

Nota: le app che hanno come target il livello API 28 o versioni successive devono comunque richiedere il FOREGROUND_SERVICE autorizzazione.

Un'app può personalizzare la notifica impostando un'impostazione MediaNotification.Provider in onCreate() che sostituisce DefaultMediaNotificationProvider. Il MediaLibraryService si occupa quindi di avviando il servizio in primo piano come richiesto.

Se esegui l'override di MediaLibraryService.updateNotification(), un'app può prendere la piena proprietà della pubblicazione di una notifica e dell'avvio/arresto del servizio in in primo piano, se necessario.

Esegui la migrazione del codice client utilizzando un MediaBrowser

Con AndroidX Media3, un MediaBrowser implementa le MediaController/Player e può essere utilizzato per controllare la riproduzione di contenuti multimediali oltre alla loro navigazione libreria. Se dovessi creare un MediaBrowserCompat e un MediaControllerCompat nel mondo precedente, puoi fare lo stesso utilizzando solo MediaBrowser in Media3.

Nota: gli utenti di Kotlin possono dipendere da kotlin-coroutines-guava o androidx.concurrent nel file build.gradle per aggiungere il metodo di estensione. await alle ListenableFuture. Ciò rende l'API MediaBrowser più adatta in un metodo suspend.

È possibile creare un MediaBrowser e attendere la connessione al servizio in fase di creazione:

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)
}

Dai un'occhiata a Controllare la riproduzione nella sessione multimediale per scoprire come creare un MediaController per controllare la riproduzione nei sfondo.

Ulteriori passaggi e pulizia

Errori relativi all'API instabile

Dopo la migrazione a Media3, potresti visualizzare errori di lint relativi a utilizzi instabili dell'API. Queste API sono sicure da usare e gli errori di lint sono un effetto collaterale della nostra nuova di compatibilità binaria. Se non sono necessari requisiti binari compatibilità, questi errori possono essere eliminati in sicurezza con un @OptIn annotazione.

Premessa

Né ExoPlayer v1 né v2 fornivano rigide garanzie sulla compatibilità binaria della libreria tra versioni successive. La superficie dell'API ExoPlayer è molto di grandi dimensioni, per consentire alle app di personalizzare quasi ogni aspetto per riprodurre un video. Versioni successive di ExoPlayer a volte introducono simboli Rinominazioni o altre modifiche che provocano un errore (ad es. nuovi metodi obbligatori nelle interfacce). Nella nella maggior parte dei casi questi malfunzionamenti sono stati mitigati dall'introduzione del nuovo simbolo oltre a ritirare il vecchio simbolo per alcune versioni, per consentire agli sviluppatori per la migrazione dei loro utilizzi, ma non è sempre stato possibile.

Queste modifiche che provocavano due problemi per gli utenti di ExoPlayer v1 e le librerie v2:

1. Un upgrade alla versione di ExoPlayer potrebbe interrompere la compilazione del codice.
2. Un'app che dipendeva da ExoPlayer sia direttamente che tramite un sistema intermedio la libreria doveva garantire che entrambe le dipendenze avessero la stessa versione altrimenti le incompatibilità binarie potrebbero causare arresti anomali del runtime.

Miglioramenti in Media3

Media3 garantisce la compatibilità binaria per un sottoinsieme della piattaforma API. La parti che non garantiscono la compatibilità binaria sono contrassegnate con @UnstableApi Per chiarire questa distinzione, gli utilizzi delle I simboli delle API generano un errore di lint a meno che non siano annotati con @OptIn.

Dopo la migrazione da ExoPlayer v2 a Media3, potresti vedere molte API instabili errori di lint. Potrebbe sembrare che Media3 sia "meno stabile" rispetto a ExoPlayer v2. Questo non è il caso. "Instabile" parti dell'API Media3 hanno lo stesso livello di stabilità come l'intera superficie dell'API ExoPlayer v2 e le garanzie della superficie stabile dell'API Media3 non sono disponibili in ExoPlayer v2 al tutti. La differenza sta semplicemente nel fatto che un errore di lint ora ti avvisa del diverso livelli di stabilità.

Gestire gli errori di lint dell'API instabile

Consulta la sezione relativa alla risoluzione dei problemi relativi a questi errori di lint per i dettagli su come annota gli utilizzi di Java e Kotlin di API instabili con @OptIn.

API deprecate

Potresti notare che le chiamate alle API deprecate vengono barrate in Android Studio. Ti consigliamo di sostituire queste chiamate con un'alternativa appropriata. Passa il mouse sopra il simbolo per visualizzare il JavaDoc che indica quale API utilizzare.

Figura 3: la descrizione comando di JavaDoc in Android Studio suggerisce un'alternativa per qualsiasi simbolo deprecato.

Esempi di codice e app demo

• App demo della sessione AndroidX Media3 (dispositivi mobili e Wear OS)
  .
  • Azioni personalizzate
  • Notifica UI di sistema, MediaButton/BT
  • Controllo di riproduzione dell'Assistente Google
• UAMP: Android Media Player (branch media3) (dispositivi mobili, AutomotiveOS)
  .
  • Notifica UI di sistema, MediaButton/BT, ripresa della riproduzione
  • Controllo di riproduzione dell'Assistente Google/WearOS
  • AutomotiveOS: comando e accesso personalizzati