Przewodnik po migracji na AndroidaX Media3

Aplikacje, które obecnie korzystają z samodzielnej biblioteki com.google.android.exoplayer2 i androidx.media, powinny przejść na androidx.media3. Użyj skryptu migracji, aby przenieść pliki kompilacji Gradle, pliki źródłowe Java i Kotlin oraz pliki układu XML z ExoPlayera 2.19.1 do AndroidX Media3 1.1.1.

Przegląd

Zanim rozpoczniesz migrację, zapoznaj się z poniższymi sekcjami, aby dowiedzieć się więcej o korzyściach płynących z nowych interfejsów API, interfejsach API do migracji oraz wymaganiach, które powinien spełniać projekt aplikacji.

Dlaczego warto przejść na Jetpack Media3

• To nowe miejsce dla ExoPlayera, a com.google.android.exoplayer2 został wycofany.
• Uzyskaj dostęp do interfejsu Player API w różnych komponentach i procesach za pomocą MediaBrowser/MediaController.
• Użyj rozszerzonych możliwości interfejsu API MediaSession i MediaController.
• Rozgłaszaj możliwości odtwarzania za pomocą szczegółowej kontroli dostępu.
• Uprość aplikację, usuwając MediaSessionConnector i PlayerNotificationManager.
• Zgodność wsteczna z interfejsami API klienta media-compat (MediaBrowserCompat/MediaControllerCompat/MediaMetadataCompat)

Interfejsy Media API do przeniesienia do AndroidX Media3

• ExoPlayer i jego rozszerzenia
  Obejmuje to wszystkie moduły starszego projektu ExoPlayer z wyjątkiem modułu mediasession, który został wycofany. Aplikacje lub moduły zależne od pakietów w com.google.android.exoplayer2 można przenieść za pomocą skryptu migracji.
• MediaSessionConnector (w zależności od pakietów androidx.media.* w androidx.media:media:1.4.3+)
  Usuń MediaSessionConnector i użyj androidx.media3.session.MediaSession.
• MediaBrowserServiceCompat (w zależności od pakietów androidx.media.* w androidx.media:media:1.4.3+)
  Przenieś podklasy androidx.media.MediaBrowserServiceCompat do androidx.media3.session.MediaLibraryService i kod używający MediaBrowserCompat.MediaItem do androidx.media3.common.MediaItem.
• MediaBrowserCompat (w zależności od pakietów android.support.v4.media.* w androidx.media:media:1.4.3+)
  Przenieś kod klienta za pomocą MediaBrowserCompat lub MediaControllerCompat, aby używać androidx.media3.session.MediaBrowser z androidx.media3.common.MediaItem.

Wymagania wstępne

1. Sprawdzanie, czy projekt jest objęty kontrolą źródła

   Upewnij się, że możesz łatwo cofnąć zmiany wprowadzone przez narzędzia do migracji oparte na skryptach. Jeśli nie masz jeszcze projektu w systemie kontroli kodu źródłowego, teraz jest dobry moment, aby go dodać. Jeśli z jakiegoś powodu nie chcesz tego robić, przed rozpoczęciem migracji utwórz kopię zapasową projektu.

2. Aktualizowanie aplikacji

   • Zalecamy zaktualizowanie projektu, aby używał najnowszej wersji biblioteki ExoPlayer, i usunięcie wszystkich wywołań wycofanych metod. Jeśli chcesz użyć skryptu do migracji, musisz dopasować wersję, do której przeprowadzasz aktualizację, do wersji obsługiwanej przez skrypt.

   • Zwiększ wartość compileSdkVersion aplikacji do co najmniej 32.

   • Uaktualnij Gradle i wtyczkę Android Studio do obsługi Gradle do najnowszej wersji, która działa ze zaktualizowanymi zależnościami wymienionymi powyżej. Na przykład:

     • Wersja wtyczki Androida do obsługi Gradle: 7.1.0
     • Wersja Gradle: 7.4

   • Zastąp wszystkie instrukcje importu z symbolami wieloznacznymi, które używają gwiazdki (*), i użyj w pełni kwalifikowanych instrukcji importu: usuń instrukcje importu z symbolami wieloznacznymi i użyj Android Studio, aby zaimportować w pełni kwalifikowane instrukcje (F2 – Alt/Enter, F2 – Alt/Enter…).

   • Migracja z com.google.android.exoplayer2.PlayerView do com.google.android.exoplayer2.StyledPlayerView. Jest to konieczne, ponieważ w AndroidX Media3 nie ma odpowiednika com.google.android.exoplayer2.PlayerView.

Migracja ExoPlayera z obsługą skryptów

Skrypt ułatwia przejście z com.google.android.exoplayer2 na nową strukturę pakietów i modułów w androidx.media3. Skrypt przeprowadza weryfikację projektu i wyświetla ostrzeżenia, jeśli się ona nie powiedzie. W przeciwnym razie stosuje mapowania klas i pakietów o zmienionych nazwach w zasobach projektu Gradle na Androida napisanego w języku Java lub 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

Korzystanie ze skryptu migracji

1. Pobierz skrypt migracji z tagu projektu ExoPlayer na GitHubie odpowiadającego wersji, do której zaktualizowano aplikację:

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

2. Dodaj do skryptu możliwość wykonywania:

   chmod 744 media3-migration.sh
   

3. Uruchom skrypt z --help, aby dowiedzieć się więcej o opcjach.

4. Uruchom skrypt z parametrem -l, aby wyświetlić listę plików wybranych do migracji (użyj parametru -f, aby wymusić wyświetlenie listy bez ostrzeżeń):

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

5. Uruchom skrypt z parametrem -m, aby zmapować pakiety, klasy i moduły na Media3. Uruchomienie skryptu z opcją -m spowoduje zastosowanie zmian do wybranych plików.

   • Zatrzymaj przy błędzie walidacji bez wprowadzania zmian

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

   • Wymuszone wykonanie

   Jeśli skrypt wykryje naruszenie wymagań wstępnych, migrację można wymusić za pomocą flagi -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

Po uruchomieniu skryptu z opcją -m wykonaj te czynności ręcznie:

1. Sprawdź, jak skrypt zmienił Twój kod: użyj narzędzia do porównywania i rozwiąż potencjalne problemy (jeśli uważasz, że skrypt ma ogólny problem, który został wprowadzony bez przekazania opcji -f, rozważ zgłoszenie błędu).
2. Skompiluj projekt: użyj ./gradlew clean build lub w Android Studio wybierz Plik > Synchronizuj projekt z plikami Gradle, a następnie Skompiluj > Wyczyść projekt i Skompiluj > Skompiluj ponownie projekt (możesz monitorować kompilację na karcie „Kompilacja – dane wyjściowe kompilacji” w Android Studio).

Zalecane dalsze kroki:

1. Rozwiąż problem z wyrażeniem zgody na błędy dotyczące korzystania z niestabilnych interfejsów API.
2. Zastąp wycofane wywołania interfejsu API: użyj sugerowanego zastępczego interfejsu API. Najedź wskaźnikiem na ostrzeżenie w Android Studio i zapoznaj się z dokumentacją JavaDoc wycofanego symbolu, aby dowiedzieć się, czego użyć zamiast danego wywołania.
3. Posortuj instrukcje importu: otwórz projekt w Android Studio, a następnie kliknij prawym przyciskiem myszy węzeł folderu pakietu w przeglądarce projektu i wybierz Optimize imports (Zoptymalizuj importy) w pakietach zawierających zmienione pliki źródłowe.

Zastąp MediaSessionConnector tekstem androidx.media3.session.MediaSession

W starszej wersji MediaSessionCompat MediaSessionConnector odpowiadał za synchronizowanie stanu odtwarzacza ze stanem sesji i odbieranie poleceń z kontrolerów, które wymagały przekazania do odpowiednich metod odtwarzacza. W AndroidX Media3 robi to bezpośrednio MediaSession, bez konieczności używania oprogramowania sprzęgającego.

1. Usuń wszystkie odwołania do MediaSessionConnector i jego użycie: jeśli do migracji klas i pakietów ExoPlayera użyto automatycznego skryptu, prawdopodobnie pozostawił on kod w stanie uniemożliwiającym kompilację z powodu błędu MediaSessionConnector, którego nie można rozwiązać. Android Studio wyświetli uszkodzony kod, gdy spróbujesz skompilować lub uruchomić aplikację.

2. W pliku build.gradle, w którym przechowujesz zależności, dodaj zależność implementacji do modułu sesji AndroidX Media3 i usuń starszą zależność:

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

3. Zastąp MediaSessionCompat wartością androidx.media3.session.MediaSession.

4. W witrynie z kodem, w której utworzono starszą wersję MediaSessionCompat, użyj androidx.media3.session.MediaSession.Builder, aby utworzyć MediaSession. Przekaż odtwarzacz, aby utworzyć kreator sesji.

   Kotlin

   val player = ExoPlayer.Builder(context).build()
   mediaSession = MediaSession.Builder(context, player).setCallback(MySessionCallback()).build()
   MigrationGuide.kt

   Java

   ExoPlayer player = new ExoPlayer.Builder(context).build();
   mediaSession =
       new MediaSession.Builder(context, player).setCallback(new MySessionCallback()).build();
   MigrationGuide.java

5. Zaimplementuj MySessionCallback zgodnie z wymaganiami aplikacji. Jest to opcjonalne. Jeśli chcesz zezwolić kontrolerom na dodawanie elementów multimedialnych do odtwarzacza, zaimplementuj MediaSession.Callback.onAddMediaItems(). Obsługuje różne bieżące i starsze metody interfejsu API, które dodają elementy multimedialne do odtwarzacza w celu odtwarzania w sposób zgodny wstecznie. Obejmuje to metody MediaController.set/addMediaItems() kontrolera Media3 oraz metody TransportControls.prepareFrom*/playFrom* starszego interfejsu API. Przykładową implementację onAddMediaItems znajdziesz w PlaybackService aplikacji demonstracyjnej sesji.

6. Zwolnij sesję multimedialną w miejscu w kodzie, w którym sesja została zniszczona przed migracją:

   Kotlin

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

   Java

   if (mediaSession != null) {
     mediaSession.getPlayer().release();
     mediaSession.release();
     mediaSession = null;
   }
   MigrationGuide.java

Funkcja MediaSessionConnector w Media3

W tabeli poniżej znajdziesz interfejsy Media3 API, które obsługują funkcje wcześniej implementowane w MediaSessionConnector.

Przenieś MediaBrowserService do: MediaLibraryService

AndroidX Media3 wprowadza MediaLibraryService, który zastępuje MediaBrowserServiceCompat. JavaDoc klasy MediaLibraryService i jej klasy nadrzędnej MediaSessionService zawiera dobre wprowadzenie do interfejsu API i asynchronicznego modelu programowania usługi.

MediaLibraryService jest zgodny wstecznie z MediaBrowserService. Aplikacja kliencka, która używa MediaBrowserCompat lub MediaControllerCompat, nadal działa bez zmian w kodzie podczas nawiązywania połączenia z MediaLibraryService. Dla klienta nie ma znaczenia, czy Twoja aplikacja używa MediaLibraryService czy starszej wersji MediaBrowserServiceCompat.

1. Aby zapewnić zgodność wsteczną, musisz zarejestrować oba interfejsy usługi w usłudze w AndroidManifest.xml. Dzięki temu klient znajdzie Twoją usługę za pomocą wymaganego interfejsu usługi:

   <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. W pliku build.gradle, w którym przechowujesz zależności, dodaj zależność implementacji do modułu sesji AndroidX Media3 i usuń starszą zależność:

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

3. Zmień usługę, aby dziedziczyła z MediaLibraryService zamiast MediaBrowserService. Jak wspomniano wcześniej, MediaLibraryService jest zgodny ze starszą wersją MediaBrowserService. W związku z tym szerszy interfejs API, który usługa oferuje klientom, pozostaje taki sam. Dlatego aplikacja może zachować większość logiki wymaganej do wdrożenia MediaBrowserService i dostosować ją do nowego MediaLibraryService.

   Główne różnice w porównaniu ze starszą wersją MediaBrowserServiceCompat:

   • Zaimplementuj metody cyklu życia usługi: metody, które należy zastąpić w samej usłudze, to onCreate/onDestroy, gdzie aplikacja przydziela/zwalnia sesję biblioteki, odtwarzacz i inne zasoby. Oprócz standardowych metod cyklu życia usługi aplikacja musi zastąpić metodę onGetSession(MediaSession.ControllerInfo), aby zwracać obiekt MediaLibrarySession utworzony w metodzie onCreate.

   • Zaimplementuj MediaLibraryService.MediaLibrarySessionCallback: utworzenie sesji wymaga obiektu MediaLibraryService.MediaLibrarySessionCallback, który implementuje metody interfejsu API rzeczywistej domeny. Zamiast zastępować metody interfejsu API starszej usługi, zastąpisz metody MediaLibrarySession.Callback.

     Wywołanie zwrotne jest następnie używane do utworzenia obiektu MediaLibrarySession:

     Kotlin

     mediaLibrarySession = MediaLibrarySession.Builder(context, player, MySessionCallback()).build()
     MigrationGuide.kt

     Java

     mediaLibrarySession =
         new MediaLibrarySession.Builder(context, player, new MySessionCallback()).build();
     MigrationGuide.java

     W dokumentacji interfejsu API znajdziesz pełny interfejs API MediaLibrarySessionCallback.

   • Implementacja MediaSession.Callback.onAddMediaItems(): onAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>) wywołanie zwrotne obsługuje różne bieżące i starsze metody interfejsu API, które dodają elementy multimedialne do odtwarzacza w celu odtwarzania w sposób zgodny wstecznie. Obejmuje to metody MediaController.set/addMediaItems() kontrolera Media3 oraz metody TransportControls.prepareFrom*/playFrom* starszego interfejsu API. Przykładową implementację wywołania zwrotnego znajdziesz w PlaybackService aplikacji demonstracyjnej sesji.

   • AndroidX Media3 używa androidx.media3.common.MediaItem zamiast MediaBrowserCompat.MediaItem i MediaMetadataCompat. Części kodu powiązane ze starszymi klasami należy odpowiednio zmienić lub zmapować na Media3 MediaItem.

   • Ogólny model programowania asynchronicznego zmienił się na Futures, w przeciwieństwie do odłączanego podejścia Result w MediaBrowserServiceCompat. Implementacja usługi może zwracać asynchroniczny obiekt ListenableFuture zamiast odłączać wynik lub zwracać natychmiastowy obiekt Future, aby bezpośrednio zwrócić wartość.

Usuwanie PlayerNotificationManager

MediaLibraryService automatycznie obsługuje powiadomienia multimedialne, a PlayerNotificationManager można usunąć, gdy używasz MediaLibraryService lub MediaSessionService.

Aplikacja może dostosować powiadomienie, ustawiając niestandardowy element MediaNotification.Provider w onCreate(), który zastępuje DefaultMediaNotificationProvider. MediaLibraryService zajmie się wtedy uruchomieniem usługi na pierwszym planie zgodnie z wymaganiami.

Zastępując metodę MediaLibraryService.updateNotification(), aplikacja może przejąć pełną kontrolę nad publikowaniem powiadomień i uruchamianiem/zatrzymywaniem usługi na pierwszym planie zgodnie z potrzebami.

Migracja kodu klienta za pomocą klasy MediaBrowser

W AndroidX Media3 MediaBrowser implementuje interfejsy MediaController/Player i może służyć do sterowania odtwarzaniem multimediów oraz przeglądania biblioteki multimediów. Jeśli w starszej wersji trzeba było utworzyć MediaBrowserCompat i MediaControllerCompat, możesz zrobić to samo, używając tylko MediaBrowser w Media3.

Można utworzyć obiekt MediaBrowser i poczekać na nawiązanie połączenia z usługą:

scope.launch {
  val sessionToken = SessionToken(context, ComponentName(context, "MusicService"))
  browser =
    MediaBrowser.Builder(context, sessionToken)
      .setListener(BrowserListener())
      .buildAsync()
      .await()
}
MigrationGuide.kt

SessionToken sessionToken =
    new SessionToken(context, new ComponentName(context, "MusicService"));
ListenableFuture<MediaBrowser> browserFuture =
    new MediaBrowser.Builder(context, sessionToken)
        .setListener(new BrowserListener())
        .buildAsync();
MigrationGuide.java

Zapoznaj się z artykułem Sterowanie odtwarzaniem w sesji multimedialnej, aby dowiedzieć się, jak utworzyć MediaController do sterowania odtwarzaniem w tle.

Dalsze kroki i czyszczenie

Błędy niestabilnego interfejsu API

Po przejściu na Media3 mogą pojawić się błędy linta dotyczące niestabilnego użycia interfejsu API. Te interfejsy API są bezpieczne w użyciu, a błędy linta są efektem ubocznym naszych nowych gwarancji zgodności plików binarnych. Jeśli nie potrzebujesz ścisłej zgodności binarnej, możesz bezpiecznie pominąć te błędy, używając adnotacji @OptIn.

Tło

Ani ExoPlayer v1, ani ExoPlayer v2 nie gwarantowały zgodności binarnej biblioteki między kolejnymi wersjami. Interfejs ExoPlayer API jest bardzo rozbudowany, aby umożliwić aplikacjom dostosowywanie niemal każdego aspektu odtwarzania. W kolejnych wersjach ExoPlayera czasami wprowadzano zmiany nazw symboli lub inne zmiany powodujące niezgodność (np. nowe wymagane metody w interfejsach). W większości przypadków te problemy zostały rozwiązane przez wprowadzenie nowego symbolu i wycofanie starego symbolu w kilku wersjach, aby dać deweloperom czas na przeniesienie ich zastosowań, ale nie zawsze było to możliwe.

Te zmiany powodujące niezgodność spowodowały 2 problemy u użytkowników bibliotek ExoPlayer w wersji 1 i 2:

1. Uaktualnienie do wersji ExoPlayer może spowodować, że kod przestanie się kompilować.
2. Aplikacja, która korzystała z ExoPlayera zarówno bezpośrednio, jak i za pomocą biblioteki pośredniej, musiała mieć pewność, że obie zależności są w tej samej wersji. W przeciwnym razie niezgodności binarne mogłyby powodować awarie w czasie działania.

Ulepszenia w Media3

Media3 gwarantuje zgodność binarną w przypadku podzbioru interfejsu API. Części, które nie gwarantują zgodności binarnej, są oznaczone symbolem @UnstableApi. Aby wyraźnie to zaznaczyć, użycie niestabilnych symboli interfejsu API generuje błąd analizy, chyba że są one oznaczone adnotacją @OptIn.

Po przejściu z ExoPlayera v2 na Media3 możesz zobaczyć wiele błędów linta związanych z niestabilnym interfejsem API. Może to sprawiać wrażenie, że Media3 jest „mniej stabilny” niż ExoPlayer v2. Tak nie jest. „Niestabilne” części interfejsu Media3 API mają ten sam poziom stabilności co cały interfejs ExoPlayer v2 API, a gwarancje stabilnego interfejsu Media3 API nie są w ogóle dostępne w ExoPlayer v2. Różnica polega na tym, że błąd linta informuje teraz o różnych poziomach stabilności.

Obsługa błędów analizy kodu niestabilnego interfejsu API

Szczegółowe informacje o tym, jak dodawać adnotacje @OptIn do użycia niestabilnych interfejsów API w językach Java i Kotlin, znajdziesz w sekcji dotyczącej rozwiązywania problemów z błędami analizy statycznej.

Wycofane interfejsy API

Możesz zauważyć, że wywołania wycofanych interfejsów API są przekreślone w Android Studio. Zalecamy zastąpienie takich wywołań odpowiednią alternatywą. Najedź kursorem na symbol, aby wyświetlić dokumentację JavaDoc, która wskazuje, którego interfejsu API należy użyć zamiast tego.

Przykładowy kod i aplikacje demonstracyjne

• Aplikacja demonstracyjna sesji AndroidX Media3 (na urządzenia mobilne i WearOS)
  • Działania niestandardowe
  • Powiadomienie interfejsu systemu, MediaButton/BT
  • Elementy sterujące odtwarzaniem za pomocą Asystenta Google
• UAMP: Android Media Player (gałąź media3) (urządzenia mobilne, AutomotiveOS)
  • Powiadomienie interfejsu systemu, MediaButton/BT, wznowienie odtwarzania
  • Elementy sterujące odtwarzaniem za pomocą Asystenta Google/Wear OS
  • AutomotiveOS: polecenie niestandardowe i logowanie