Anwendungen, die derzeit die eigenständige Bibliothek com.google.android.exoplayer2
und androidx.media
verwenden, sollten zu androidx.media3
migriert werden. Mit dem Migrationsskript können Sie Gradle-Build-Dateien, Java- und Kotlin-Quelldateien sowie XML-Layoutdateien von ExoPlayer 2.19.1
zu AndroidX Media3 1.1.1
migrieren.
Übersicht
Lesen Sie vor der Migration die folgenden Abschnitte, um mehr über die Vorteile der neuen APIs, die zu migrierenden APIs und die Voraussetzungen zu erfahren, die das Projekt Ihrer Anwendung erfüllen muss.
Gründe für die Migration zu Jetpack Media3
- Dies ist das neue Zuhause von ExoPlayer.
com.google.android.exoplayer2
wurde jedoch eingestellt. - Greifen Sie mit
MediaBrowser
/MediaController
auf die Player API für verschiedene Komponenten/Prozesse zu. - Sie können die erweiterten Funktionen der
MediaSession
und derMediaController
API verwenden. - Werben Sie mit der detaillierten Zugriffssteuerung für Wiedergabefunktionen.
- Vereinfache deine App, indem du
MediaSessionConnector
undPlayerNotificationManager
entfernst. - Abwärtskompatibel mit medienkompatiblen Client-APIs (
MediaBrowserCompat
/MediaControllerCompat
/MediaMetadataCompat
)
Zu AndroidX Media3 zu migrierende Medien-APIs
- ExoPlayer und zugehörige Erweiterungen
Dazu gehören alle Module des alten ExoPlayer-Projekts mit Ausnahme des nicht mehr unterstützten mediasession-Moduls. Anwendungen oder Module, die von den Paketen incom.google.android.exoplayer2
abhängen, können mit dem Migrationsskript migriert werden. - MediaSessionConnector (abhängig von den
androidx.media.*
-Paketen vonandroidx.media:media:1.4.3+
)
EntferneMediaSessionConnector
und verwende stattdessen dasandroidx.media3.session.MediaSession
. - MediaBrowserServiceCompat (abhängig von den
androidx.media.*
-Paketen vonandroidx.media:media:1.4.3+
)
Migrieren Sie abgeleitete Klassen vonandroidx.media.MediaBrowserServiceCompat
zuandroidx.media3.session.MediaLibraryService
und programmieren Sie mitMediaBrowserCompat.MediaItem
zuandroidx.media3.common.MediaItem
. - MediaBrowserCompat (abhängig von den
android.support.v4.media.*
-Paketen vonandroidx.media:media:1.4.3+
)
Migrieren Sie den Clientcode mitMediaBrowserCompat
oderMediaControllerCompat
, umandroidx.media3.session.MediaBrowser
mitandroidx.media3.common.MediaItem
zu verwenden.
Voraussetzungen
Projekt mit Versionsverwaltung prüfen
Sorgen Sie dafür, dass sich von skriptbasierten Migrationstools übernommene Änderungen einfach rückgängig machen lassen. Wenn Ihr Projekt noch nicht der Versionsverwaltung unterliegt, ist jetzt ein guter Zeitpunkt, damit zu beginnen. Wenn Sie dies aus irgendeinem Grund nicht tun möchten, erstellen Sie eine Sicherungskopie des Projekts, bevor Sie mit der Migration beginnen.
App aktualisieren
Wir empfehlen, Ihr Projekt auf die neueste Version der ExoPlayer-Bibliothek zu aktualisieren und alle Aufrufe von verworfenen Methoden zu entfernen. Wenn Sie für die Migration das Skript verwenden möchten, müssen Sie die Version, auf die Sie aktualisieren, mit der Version abstimmen, die vom Skript verarbeitet wird.
Erhöhen Sie den Wert für compileSdkVersion Ihrer App auf mindestens 32.
Aktualisieren Sie Gradle und das Gradle-Plug-in von Android Studio auf eine aktuelle Version, die mit den oben beschriebenen aktualisierten Abhängigkeiten funktioniert. Beispiel:
- Android-Gradle-Plug-in-Version: 7.1.0
- Gradle-Version: 7.4
Ersetzen Sie alle Platzhalter-Importanweisungen, die ein Sternchen (*) verwenden, und verwenden Sie vollständig qualifizierte Importanweisungen: Löschen Sie die Platzhalter-Importanweisungen und verwenden Sie Android Studio, um die voll qualifizierten Anweisungen (F2 – Alt/Eingabetaste, F2 – Alt/Eingabetaste usw.) zu importieren.
Migrieren Sie von
com.google.android.exoplayer2.PlayerView
zucom.google.android.exoplayer2.StyledPlayerView
. Das ist erforderlich, da es in AndroidX Media3 kein Äquivalent fürcom.google.android.exoplayer2.PlayerView
gibt.
ExoPlayer mit Skriptunterstützung migrieren
Das Skript erleichtert das Verschieben von com.google.android.exoplayer2
zur neuen Paket- und Modulstruktur unter androidx.media3
. Das Skript wendet einige Validierungsprüfungen auf Ihr Projekt an und gibt Warnungen aus, wenn die Validierung fehlschlägt.
Andernfalls werden die Zuordnungen von umbenannten Klassen und Paketen in den Ressourcen eines Android-Gradle-Projekts in Java oder Kotlin angewendet.
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
Migrationsskript verwenden
Laden Sie das Migrationsskript aus dem Tag des ExoPlayer-Projekts auf GitHub herunter, das der Version entspricht, auf die Sie Ihre App aktualisiert haben:
curl -o media3-migration.sh \ "https://raw.githubusercontent.com/google/ExoPlayer/r2.19.1/media3-migration.sh"
Machen Sie das Skript ausführbar:
chmod 744 media3-migration.sh
Führen Sie das Skript mit
--help
aus, um mehr über die Optionen zu erfahren.Führen Sie das Skript mit
-l
aus, um die für die Migration ausgewählten Dateien aufzulisten. Verwenden Sie-f
, um die Auflistung ohne Warnungen zu erzwingen:./media3-migration.sh -l -f /path/to/gradle/project/root
Führen Sie das Skript mit
-m
aus, um Media3 Pakete, Klassen und Module zuzuordnen. Wenn Sie das Skript mit der Option-m
ausführen, werden Änderungen auf die ausgewählten Dateien angewendet.- Bei Validierungsfehler beenden, ohne Änderungen vorzunehmen
./media3-migration.sh -m /path/to/gradle/project/root
- Erzwungene Ausführung
Wenn das Skript einen Verstoß gegen die Voraussetzungen feststellt, kann die Migration mit dem Flag
-f
erzwungen werden:./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
Führen Sie diese manuellen Schritte aus, nachdem Sie das Skript mit der Option -m
ausgeführt haben:
- Prüfen, wie sich das Skript Ihren Code geändert hat: Verwenden Sie ein diff-Tool und beheben Sie potenzielle Probleme. Wenn Sie der Meinung sind, dass im Skript ein allgemeines Problem vorliegt, das aufgetreten ist, ohne die Option
-f
zu übergeben, können Sie einen Fehler melden. - Projekt erstellen: Verwende
./gradlew clean build
oder wähle in Android Studio Datei > Projekt mit Gradle-Dateien synchronisieren > Build > Projekt bereinigen und dann Build > Projekt neu erstellen aus. Überwache deinen Build in Android Studio auf dem Tab Build – Build Output.
Empfohlene weitere Schritte:
- Beheben Sie die Zustimmung für Fehler bei der Verwendung instabiler APIs.
- Verworfene API-Aufrufe ersetzen: Verwenden Sie die vorgeschlagene Ersatz-API. Halten Sie den Mauszeiger über die Warnung in Android Studio und konsultieren Sie das JavaDoc zum veralteten Symbol, um herauszufinden, was anstelle eines bestimmten Aufrufs verwendet werden sollte.
- Importanweisungen sortieren: Öffnen Sie das Projekt in Android Studio, klicken Sie dann mit der rechten Maustaste in der Projektansicht auf einen Paketordnerknoten und wählen Sie für die Pakete, die die geänderten Quelldateien enthalten, Importe optimieren aus.
MediaSessionConnector
durch androidx.media3.session.MediaSession
ersetzen
In der Legacy-MediaSessionCompat
-Umgebung war MediaSessionConnector
dafür zuständig, den Status des Spielers mit dem Status der Sitzung zu synchronisieren und Befehle von Controllern zu empfangen, die Delegierung an geeignete Spielermethoden mussten. Bei AndroidX Media3 erfolgt dies direkt von MediaSession
, ohne dass ein Connector erforderlich ist.
Entfernen Sie alle Verweise auf und die Verwendung von MediaSessionConnector:Wenn Sie das automatisierte Skript zum Migrieren von ExoPlayer-Klassen und -Paketen verwendet haben, hat das Skript Ihren Code wahrscheinlich in einem nicht kompilierbaren Zustand belassen, der die
MediaSessionConnector
betrifft, die nicht aufgelöst werden kann. In Android Studio wird der fehlerhafte Code angezeigt, wenn Sie versuchen, die App zu erstellen oder zu starten.Fügen Sie in der Datei
build.gradle
, in der Sie Ihre Abhängigkeiten verwalten, eine Implementierungsabhängigkeit zum AndroidX Media3-Sitzungsmodul hinzu und entfernen Sie die alte Abhängigkeit:implementation "androidx.media3:media3-session:1.3.1"
Ersetzen Sie
MediaSessionCompat
durchandroidx.media3.session.MediaSession
.Verwenden Sie auf der Codewebsite, auf der Sie den Legacy-
MediaSessionCompat
erstellt haben,androidx.media3.session.MediaSession.Builder
, um eineMediaSession
zu erstellen. Übergeben Sie den Player, um den Session Builder zu erstellen.val player = ExoPlayer.Builder(context).build() mediaSession = MediaSession.Builder(context, player) .setSessionCallback(MySessionCallback()) .build()
Implementieren Sie
MySessionCallback
gemäß den Anforderungen Ihrer App. Dies ist optional. Wenn du Controllern erlauben möchtest, dem Player Medienelemente hinzuzufügen, implementiereMediaSession.Callback.onAddMediaItems()
. Sie unterstützt verschiedene aktuelle und Legacy-API-Methoden, mit denen dem Player Medienelemente für die abwärtskompatible Wiedergabe hinzugefügt werden. Dazu gehören dieMediaController.set/addMediaItems()
-Methoden des Media3-Controllers und dieTransportControls.prepareFrom*/playFrom*
-Methoden der Legacy-API. Eine Beispielimplementierung vononAddMediaItems
findest du in derPlaybackService
der Sitzungsdemo-App.Geben Sie die Mediensitzung an der Codewebsite frei, an der Sie die Sitzung vor der Migration gelöscht haben:
mediaSession?.run { player.release() release() mediaSession = null }
MediaSessionConnector
-Funktion in Media3
Die folgende Tabelle zeigt die Media3 APIs, über die Funktionen verarbeitet werden, die zuvor in MediaSessionConnector
implementiert wurden.
MediaSessionConnector | AndroidX Media3 |
---|---|
CustomActionProvider |
MediaSession.Callback.onCustomCommand()/
MediaSession.setCustomLayout() |
PlaybackPreparer |
MediaSession.Callback.onAddMediaItems()
(prepare() wird intern aufgerufen)
|
QueueNavigator |
ForwardingPlayer |
QueueEditor |
MediaSession.Callback.onAddMediaItems() |
RatingCallback |
MediaSession.Callback.onSetRating() |
PlayerNotificationManager |
DefaultMediaNotificationProvider/
MediaNotification.Provider |
MediaBrowserService
zu MediaLibraryService
migrieren
Mit AndroidX Media3 wird MediaLibraryService
eingeführt, das MediaBrowserServiceCompat
ersetzt. Das JavaDoc von MediaLibraryService
und die zugehörige übergeordnete Klasse MediaSessionService
bieten eine gute Einführung in die API und das asynchrone Programmiermodell des Dienstes.
MediaLibraryService
ist abwärtskompatibel mit MediaBrowserService
. Eine Clientanwendung, die MediaBrowserCompat
oder MediaControllerCompat
verwendet, funktioniert weiterhin ohne Codeänderungen, wenn eine Verbindung zu einer MediaLibraryService
hergestellt wird. Bei einem Client ist es transparent, ob die Anwendung eine MediaLibraryService
- oder eine Legacy-MediaBrowserServiceCompat
verwendet.
Damit die Abwärtskompatibilität funktioniert, müssen Sie beide Dienstschnittstellen für Ihren Dienst in der
AndroidManifest.xml
registrieren. So findet ein Client Ihren Dienst über die erforderliche Dienstschnittstelle:<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>
Fügen Sie in der Datei
build.gradle
, in der Sie Ihre Abhängigkeiten verwalten, eine Implementierungsabhängigkeit zum AndroidX Media3-Sitzungsmodul hinzu und entfernen Sie die alte Abhängigkeit:implementation "androidx.media3:media3-session:1.3.1"
Ändern Sie den Dienst so, dass er von einer
MediaLibraryService
anstelle vonMediaBrowserService
übernimmt. Wie bereits erwähnt, ist derMediaLibraryService
mit dem Legacy-MediaBrowserService
kompatibel. Entsprechend bleibt die weiter gefasste API, die der Dienst den Kunden anbietet, unverändert. Daher ist es wahrscheinlich, dass eine Anwendung den Großteil der für die Implementierung vonMediaBrowserService
erforderlichen Logik beibehalten und an die neueMediaLibraryService
anpassen kann.Die Hauptunterschiede zum Legacy-
MediaBrowserServiceCompat
sind:Methoden des Dienstlebenszyklus implementieren:Die Methoden, die für den Dienst selbst überschrieben werden müssen, sind
onCreate/onDestroy
. Eine App weist die Bibliothekssitzung, den Player und andere Ressourcen zu oder gibt sie frei. Zusätzlich zu den standardmäßigen Methoden des Dienstlebenszyklus muss eine AnwendungonGetSession(MediaSession.ControllerInfo)
überschreiben, um das inonCreate
erstellteMediaLibrarySession
zurückzugeben.MediaLibraryService.MediaLibrarySessionCallback implementieren:Zum Erstellen einer Sitzung ist ein
MediaLibraryService.MediaLibrarySessionCallback
erforderlich, der die tatsächlichen Domain API-Methoden implementiert. Anstatt also die API-Methoden des Legacy-Dienstes zu überschreiben, überschreiben Sie stattdessen die Methoden desMediaLibrarySession.Callback
.Mit dem Callback wird dann das
MediaLibrarySession
erstellt:mediaLibrarySession = MediaLibrarySession.Builder(this, player, MySessionCallback()) .build()
Die vollständige API von MediaLibrarySessionCallback finden Sie in der API-Dokumentation.
MediaSession.Callback.onAddMediaItems()
implementieren: Der CallbackonAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>)
unterstützt verschiedene aktuelle und alte API-Methoden, mit denen dem Player Medienelemente für die abwärtskompatible Wiedergabe hinzugefügt werden. Dazu gehören dieMediaController.set/addMediaItems()
-Methoden des Media3-Controllers sowie dieTransportControls.prepareFrom*/playFrom*
-Methoden der Legacy-API. Eine Beispielimplementierung des Callbacks findest du in derPlaybackService
der Sitzungsdemo-App.AndroidX Media3 verwendet
androidx.media3.common.MediaItem
anstelle von MediaBrowserCompat.MediaItem und MediaMetadataCompat. Teile des Codes, die mit den Legacy-Klassen verknüpft sind, müssen entsprechend geändert oder stattdessen dem Media3-MediaItem
zugeordnet werden.Das allgemeine asynchrone Programmiermodell wurde in
Futures
geändert, im Gegensatz zum Ansatz für trennbareResult
vonMediaBrowserServiceCompat
. Ihre Dienstimplementierung kann ein asynchronesListenableFuture
zurückgeben, anstatt ein Ergebnis zu trennen, oder ein sofortiges Future zurückgeben, um einen Wert direkt zurückzugeben.
PlayerBenachrichtigungManager entfernen
MediaLibraryService
unterstützt Medienbenachrichtigungen automatisch und PlayerNotificationManager
kann bei Verwendung von MediaLibraryService
oder MediaSessionService
entfernt werden.
Eine App kann die Benachrichtigung anpassen, indem in onCreate()
ein benutzerdefiniertes MediaNotification.Provider
festgelegt wird, das DefaultMediaNotificationProvider
ersetzt. MediaLibraryService
startet dann den Dienst bei Bedarf im Vordergrund.
Durch das Überschreiben von MediaLibraryService.updateNotification()
kann eine Anwendung weiterhin die volle Verantwortung für das Posten einer Benachrichtigung übernehmen und den Dienst nach Bedarf im Vordergrund starten/beenden.
Clientcode mit einem MediaBrowser migrieren
Bei AndroidX Media3 implementiert ein MediaBrowser
die MediaController/Player
-Schnittstellen und kann nicht nur zum Durchsuchen der Medienbibliothek, sondern auch zur Steuerung der Medienwiedergabe verwendet werden. Wenn Sie ein MediaBrowserCompat
und ein MediaControllerCompat
in der Legacy-Umgebung erstellen mussten, können Sie dies ebenfalls tun, indem Sie nur die MediaBrowser
in Media3 verwenden.
Ein MediaBrowser
kann erstellt werden und wartet darauf, dass die Verbindung zum Dienst hergestellt wurde:
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)
}
Informationen zum Erstellen einer MediaController
zur Steuerung der Wiedergabe im Hintergrund finden Sie unter Wiedergabe in der Mediensitzung steuern.
Weitere Schritte und Bereinigung
Instabile API-Fehler
Nach der Migration zu Media3 können Lint-Fehler aufgrund instabiler API-Nutzung auftreten.
Die Verwendung dieser APIs ist sicher und die Lint-Fehler sind Nebenprodukt unserer neuen Binärkompatibilitätsgarantien. Wenn Sie keine strenge Binärkompatibilität benötigen, können diese Fehler mit einer @OptIn
-Annotation sicher unterdrückt werden.
Hintergrund
Weder ExoPlayer v1 noch v2 bietet strenge Garantien für die Binärkompatibilität der Bibliothek zwischen nachfolgenden Versionen. Die ExoPlayer API-Oberfläche ist von Grund auf sehr groß, damit Apps nahezu jeden Aspekt der Wiedergabe anpassen können. In nachfolgenden Versionen von ExoPlayer wurden gelegentlich Symbolumbenennungen oder andere funktionsgefährdende Änderungen eingeführt, z.B. neue erforderliche Methoden für Benutzeroberflächen. In den meisten Fällen wurden diese Fehler abgemildert, indem das neue Symbol zusammen mit dem alten Symbol für einige Versionen eingeführt wurde, um Entwicklern Zeit zu geben, ihre Nutzungen zu migrieren. Dies war jedoch nicht immer möglich.
Diese funktionsgefährdenden Änderungen führten bei Nutzern der ExoPlayer v1- und v2-Bibliotheken zu zwei Problemen:
- Ein Upgrade auf die ExoPlayer-Version kann dazu führen, dass der Code nicht mehr kompiliert wird.
- Eine Anwendung, die sowohl direkt als auch über eine Zwischenbibliothek von ExoPlayer abhängig war, musste sicherstellen, dass beide Abhängigkeiten dieselbe Version haben. Andernfalls konnten Inkompatibilitäten der Binärprogramme zu Laufzeitabstürzen führen.
Verbesserungen bei Media3
Media3 garantiert die Binärkompatibilität für einen Teil der API-Oberfläche. Die Teile, die die Binärkompatibilität nicht garantieren, sind mit @UnstableApi
gekennzeichnet. Zur Klarstellung dieser Unterscheidung erzeugen die Verwendung instabiler API-Symbole einen Lint-Fehler, sofern sie nicht mit @OptIn
annotiert sind.
Nach der Migration von ExoPlayer v2 zu Media3 können viele instabile API-Lint-Fehler auftreten. Dies kann den Anschein erwecken, als wäre Media3 „weniger stabil“ als ExoPlayer v2. Das ist nicht der Fall. Die „instabilen“ Teile der Media3 API haben dieselbe Stabilität wie die gesamte Oberfläche der ExoPlayer v2 API. Die Garantien für eine stabile Media3 API-Oberfläche sind in ExoPlayer v2 nicht verfügbar. Der Unterschied besteht darin, dass Sie jetzt durch einen Lint-Fehler auf die verschiedenen Stabilitätsstufen hingewiesen werden.
Instabile API-Lint-Fehler beheben
Sie haben zwei Möglichkeiten, um die instabilen API-Lint-Fehler zu handhaben:
- Verwenden Sie eine stabile API, mit der das gleiche Ergebnis erzielt wird.
Verwenden Sie weiterhin die instabile API und hat die Nutzung mit
@OptIn
annotiert.import androidx.annotation.OptIn import androidx.media3.common.util.UnstableApi @OptIn(UnstableApi::class) fun functionUsingUnstableApi() { // Do something useful. }
Es gibt auch eine
kotlin.OptIn
-Annotation, die nicht verwendet werden sollte. Zu diesem Zweck ist es wichtig, die Annotationandroidx.annotation.OptIn
zu verwenden.
Für ganze Pakete kann ein package-info.java
hinzugefügt werden:
@OptIn(markerClass = UnstableApi.class)
package name.of.your.package;
import androidx.annotation.OptIn;
import androidx.media3.common.util.UnstableApi;
Sie können ganze Projekte aktivieren, indem Sie den spezifischen Lint-Fehler in der lint.xml-Datei unterdrücken. Weitere Informationen finden Sie im JavaDoc zur UnstableApi-Annotation.
Eingestellte APIs
Möglicherweise stellen Sie fest, dass Aufrufe an eingestellte APIs in Android Studio durchgestrichen werden. Wir empfehlen, solche Aufrufe durch die entsprechende Alternative zu ersetzen. Bewegen Sie den Mauszeiger über das Symbol, um das JavaDoc anzuzeigen, das angibt, welche API stattdessen verwendet werden soll.
Codebeispiele und Demo-Apps
- AndroidX Media3-Session-Demo-App (Mobilgerät und Wear OS)
- Benutzerdefinierte Aktionen
- System-UI-Benachrichtigung, MediaButton/BT
- Wiedergabesteuerung mit Google Assistant
- UAMP: Android Media Player (zweig media3) (mobile, AutomotiveOS)
- System-UI-Benachrichtigung, MediaButton/BT, Wiederaufnahme der Wiedergabe
- Wiedergabesteuerung für Google Assistant/Wear OS
- AutomotiveOS: Benutzerdefinierter Befehl und Anmeldung