Questa pagina è stata tradotta dall'API Cloud Translation.

Guida alla migrazione di AndroidX Media3

Le app che attualmente utilizzano la libreria com.google.android.exoplayer2 e androidx.media autonoma devono eseguire la migrazione in androidx.media3. Utilizza lo script di migrazione per eseguire la migrazione dei file di build Gradle, dei file sorgente Java e Kotlin e dei file di layout XML da ExoPlayer 2.19.1 ad AndroidX Media3 1.1.1.

Panoramica

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

Perché eseguire la migrazione a Jetpack Media3

È la nuova home page di ExoPlayer, mentre com.google.android.exoplayer2 non è più disponibile.
Accedi all'API Player per tutti i componenti/processi con MediaBrowser/MediaController.
Utilizza le funzionalità estese delle API MediaSession e 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 compatibili con i media (MediaBrowserCompat/MediaControllerCompat/MediaMetadataCompat)

API Media per la migrazione ad AndroidX Media3

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

Prerequisiti

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 iniziare. Se per qualche motivo non vuoi farlo, crea una copia di backup del progetto prima di iniziare la migrazione.
Aggiornare la tua app
- Ti consigliamo di aggiornare il progetto in modo che utilizzi la versione più recente della libreria ExoPlayer e di rimuovere eventuali chiamate ai metodi deprecati. Se intendi utilizzare lo script per la migrazione, devi associare la versione a cui stai eseguendo l'aggiornamento a quella 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 supporti le dipendenze aggiornate descritte sopra. Ad esempio:
  - 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 asterix (*) e utilizza istruzioni di importazione complete: elimina le istruzioni di importazione con caratteri jolly e utilizza Android Studio per importare le istruzioni complete (F2 - Alt/Enter, F2 - Alt/Enter, ...).
- Esegui la migrazione da com.google.android.exoplayer2.PlayerView a com.google.android.exoplayer2.StyledPlayerView. Questa operazione è necessaria perché non esiste un equivalente a com.google.android.exoplayer2.PlayerView in AndroidX Media3.

Migrazione di ExoPlayer con supporto script

Lo script facilita il passaggio da com.google.android.exoplayer2 alla nuova struttura di pacchetti e moduli in androidx.media3. Lo script applica alcuni controlli di convalida al progetto e stampa avvisi se la convalida non va a buon fine. In caso contrario, applica le mappature di classi e pacchetti rinominati nelle risorse di un progetto Gradle Android 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

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"
```
Rendi eseguibile lo script:
```
chmod 744 media3-migration.sh
```
Esegui lo script con --help per scoprire di più sulle opzioni.
Esegui lo script con -l per elencare il set di file selezionati per la migrazione (utilizza -f per forzare l'elenco senza avvisi):
```
./media3-migration.sh -l -f /path/to/gradle/project/root
```
Esegui lo script con -m per mappare pacchetti, classi e moduli a Media3. Se esegui lo script con l'opzione -m, le modifiche verranno applicate ai file selezionati.
- 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 forzata con il 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

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

Verifica in che modo lo script ha modificato il codice: utilizza uno strumento per le differenze e risolvi potenziali problemi (valuta la possibilità di segnalare un bug se ritieni che lo script abbia un problema generale introdotto senza trasferire l'opzione -f).
Crea il progetto: utilizza ./gradlew clean build oppure in Android Studio scegli File > Sincronizza progetto con i file Gradle, poi Crea > Pulisci progetto e infine Crea > Ricrea progetto (monitora la build nella scheda "Crea - Output build" di Android Studio.

Passaggi successivi consigliati:

Risolvere l'opzione di attivazione per gli errori relativi all'utilizzo di API instabili.
Sostituisci le chiamate API ritirate: utilizza l'API sostitutiva suggerita. Tieni il puntatore sopra l'avviso in Android Studio e consulta il JavaDoc del simbolo deprecato per scoprire cosa usare al posto di una determinata chiamata.
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 era responsabile della sincronizzazione dello stato del player con lo stato della sessione e della ricezione dei comandi dai controller che richiedevano la delega ai metodi del player appropriati. Con AndroidX Media3, MediaSession esegue direttamente questa operazione senza richiedere un connettore.

Rimuovi tutti i riferimenti e l'utilizzo di MediaSessionConnector: se hai utilizzato lo script automatico per eseguire la migrazione delle classi e dei pacchetti ExoPlayer, è probabile che lo script abbia lasciato il codice in uno stato non compilabile per quanto riguarda MediaSessionConnector che non può essere risolto. Android Studio ti mostra il codice non funzionante quando provi a creare o avviare l'app.
Nel file build.gradle in cui gestisci le dipendenze, aggiungi una dipendenza di implementazione al modulo di sessione AndroidX Media3 e rimuovi la dipendenza precedente:
```
implementation "androidx.media3:media3-session:1.3.1"
```
Sostituisci MediaSessionCompat con androidx.media3.session.MediaSession.
Nel sito del codice in cui hai creato la versione precedente di MediaSessionCompat, usa androidx.media3.session.MediaSession.Builder per creare una MediaSession. Supera il giocatore per costruire lo strumento per la creazione di sessioni.

Nota: se la tua app utilizza un player diverso da ExoPlayer, devi avere un'implementazione Player personalizzata che puoi trasferire al MediaSession che aggrega il player. Forniremo ulteriori indicazioni su un'implementazione di Player minima che funzioni insieme all'implementazione della sessione multimediale.
```
val player = ExoPlayer.Builder(context).build()
mediaSession = MediaSession.Builder(context, player)
    .setSessionCallback(MySessionCallback())
    .build()
```
Nota: puoi intercettare qualsiasi chiamata di metodo a Player aggregandola a un elementoForwardingPlayer(player).
(Facoltativo) Implementa MySessionCallback come richiesto dalla tua app. Se vuoi consentire ai controller di aggiungere elementi multimediali al player, implementa MediaSession.Callback.onAddMediaItems(). Utilizza vari metodi dell'API attuali ed legacy che aggiungono elementi multimediali al player per la riproduzione in modo compatibile con le versioni precedenti. Sono inclusi i metodi MediaController.set/addMediaItems() del controller Media3 e i metodi TransportControls.prepareFrom*/playFrom* dell'API legacy. Puoi trovare un'implementazione di esempio di onAddMediaItems nella PlaybackService dell'app demo della sessione.
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 rilasciare la sessione multimediale prima di crearne una nuova con lo stesso ID. Media3 genera un'eccezione se un'app sta divulgando un'istanza di sessione.

Funzionalità di `MediaSessionConnector` in Media3

La seguente tabella mostra le API Media3 che gestiscono le funzionalità precedentemente implementate in MediaSessionConnector.

MediaSessionConnector	AndroidX Media3
`CustomActionProvider`	`MediaSession.Callback.onCustomCommand()/ MediaSession.setCustomLayout()`
`PlaybackPreparer`	`MediaSession.Callback.onAddMediaItems()` (`prepare()` è 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 la sua superclasse MediaSessionService forniscono una buona introduzione all'API e al modello di programmazione asincrona del servizio.

MediaLibraryService è compatibile con le versioni precedenti di MediaBrowserService. Un'app client che utilizza MediaBrowserCompat o MediaControllerCompat continua a funzionare senza modifiche al codice quando si connette a un MediaLibraryService. Per un client, è trasparente se la tua app utilizza un MediaLibraryService o un MediaBrowserServiceCompat precedente.

Diagramma dei componenti dell'app con servizio, attività e app esterne. — **Figura 1**: panoramica del componente App multimediale

Affinché la compatibilità con le versioni precedenti funzioni, devi registrare entrambe le interfacce di servizio con il tuo servizio in AndroidManifest.xml. In questo modo un client 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>

Nel file build.gradle in cui gestisci le dipendenze, aggiungi una dipendenza di implementazione al modulo di sessione AndroidX Media3 e rimuovi la dipendenza precedente:
```
implementation "androidx.media3:media3-session:1.3.1"
```
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, l'API più ampia che il servizio offre ai clienti rimane la stessa. Pertanto, è probabile che un'app possa conservare la maggior parte della logica necessaria per implementare MediaBrowserService e adattarla al nuovo MediaLibraryService.

Le principali differenze rispetto alla versione precedente MediaBrowserServiceCompat sono le seguenti:
- Implementa i metodi del ciclo di vita dei servizi: i metodi che devono essere sottoposti a override nel servizio stesso sono onCreate/onDestroy, in cui un'app alloca/rilascia la sessione della libreria, il player e altre risorse. Oltre ai metodi del ciclo di vita dei servizi standard, un'app deve eseguire l'override di onGetSession(MediaSession.ControllerInfo) per restituire il valore MediaLibrarySession creato in onCreate.
- Implementa MediaLibraryService.MediaLibrarySessionCallback: la creazione di una sessione richiede un MediaLibraryService.MediaLibrarySessionCallback che implementa gli effettivi metodi dell'API dominio. Pertanto, invece di eseguire l'override dei metodi API del servizio legacy, eseguirai l'override dei metodi di MediaLibrarySession.Callback.
  
  Il callback viene quindi utilizzato per creare MediaLibrarySession:
```
mediaLibrarySession =
      MediaLibrarySession.Builder(this, player, MySessionCallback())
         .build()
```
  Puoi trovare l'API completa di MediaLibrarySessionCallback nella documentazione dell'API.
- Implementazione di MediaSession.Callback.onAddMediaItems(): il callback onAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>) gestisce vari metodi dell'API attuali e legacy che aggiungono elementi multimediali al player per riprodurli in modo compatibile con le versioni precedenti. Sono inclusi i metodi MediaController.set/addMediaItems() del controller Media3 e i metodi TransportControls.prepareFrom*/playFrom* dell'API legacy. Puoi trovare un'implementazione di esempio del callback nella PlaybackService dell'app demo della sessione.
- AndroidX Media3 utilizza androidx.media3.common.MediaItem anziché MediaBrowserCompat.MediaItem e MediaMetadataCompat. Le parti del tuo codice legate alle classi legacy devono essere modificate di conseguenza o mappate al MediaItem di Media3.
- Il modello di programmazione asincrono generale è cambiato in Futures, in contrasto con l'approccio rimovibile Result di MediaBrowserServiceCompat. L'implementazione del servizio può restituire un elemento ListenableFuture asincrono invece di scollegare un risultato o restituire un valore futuro immediato per restituire direttamente un valore.

Rimuovi PlayerNotificationManager

Il MediaLibraryService supporta automaticamente le notifiche multimediali e la PlayerNotificationManager può essere rimossa quando si utilizza un MediaLibraryService o MediaSessionService.

Un'app può personalizzare la notifica impostando una MediaNotification.Provider personalizzata in onCreate() che sostituisce DefaultMediaNotificationProvider. MediaLibraryService si occupa quindi di avviare il servizio in primo piano, come richiesto.

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

Esegui la migrazione del codice client utilizzando un MediaBrowser

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

È possibile creare un MediaBrowser e attendere la connessione al servizio:

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

Consulta Controllo della riproduzione nelle sessioni multimediali per scoprire come creare un MediaController per il controllo della riproduzione in background.

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 delle nostre nuove garanzie di compatibilità binaria. Se non hai bisogno di una rigorosa compatibilità binaria, questi errori possono essere eliminati in modo sicuro con un'annotazione @OptIn.

Premessa

Né ExoPlayer v1 né v2 fornivano rigide garanzie sulla compatibilità binaria della libreria tra versioni successive. La superficie dell'API ExoPlayer è molto ampia per quanto riguarda la progettazione, per consentire alle app di personalizzare quasi ogni aspetto della riproduzione. Le versioni successive di ExoPlayer avrebbero occasionalmente introdotto rinominazioni dei simboli o altre modifiche che provocano un errore (ad es. nuovi metodi obbligatori nelle interfacce). Nella maggior parte dei casi questi malfunzionamenti sono stati mitigati introducendo il nuovo simbolo, oltre a ritirare il vecchio simbolo per alcune versioni, per concedere agli sviluppatori il tempo necessario per eseguire la migrazione dei loro utilizzi, ma non è sempre stato possibile.

Queste modifiche che provocano un errore hanno causato due problemi per gli utenti delle librerie ExoPlayer v1 e v2:

Un upgrade alla versione di ExoPlayer potrebbe interrompere la compilazione del codice.
Un'app che dipendeva da ExoPlayer sia direttamente sia tramite una libreria intermedia doveva garantire che entrambe le dipendenze fossero la stessa versione, altrimenti le incompatibilità binarie potrebbero causare arresti anomali di runtime.

Miglioramenti in Media3

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

Dopo la migrazione da ExoPlayer v2 a Media3, potresti notare molti errori di Lint dell'API instabili. Potrebbe sembrare che Media3 sia "meno stabile" di ExoPlayer v2. Questo non è il caso. Le parti "instabili" dell'API Media3 hanno lo stesso livello di stabilità dell'intera superficie dell'API ExoPlayer v2 e le garanzie della superficie stabile dell'API Media3 non sono disponibili in ExoPlayer v2. La differenza sta semplicemente nel fatto che ora un errore di lint indica i diversi livelli di stabilità.

Gestire gli errori di lint dell'API instabile

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

API deprecate

Potresti notare che le chiamate alle API deprecate vengono segnalate 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.

Screenshot: come visualizzare JavaDoc con un'alternativa al metodo deprecato — **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