Tworzenie podstawowej aplikacji odtwarzacza multimediów za pomocą Media3 ExoPlayer

Biblioteka Jetpack Media3 definiuje interfejs Player, który określa podstawowe funkcje odtwarzania plików wideo i audio. ExoPlayer to domyślna implementacja tego interfejsu w Media3. Zalecamy korzystanie z ExoPlayera, ponieważ zapewnia on kompleksowy zestaw funkcji, które obejmują większość przypadków użycia odtwarzania, i można go dostosować do obsługi dodatkowych przypadków użycia. ExoPlayer ukrywa też fragmentację urządzeń i systemów operacyjnych, dzięki czemu Twój kod działa spójnie w całym ekosystemie Androida. ExoPlayer obejmuje:

Na tej stronie znajdziesz najważniejsze etapy tworzenia aplikacji do odtwarzania. Więcej informacji znajdziesz w naszych pełnych przewodnikach po Media3 ExoPlayer.

Pierwsze kroki

Aby rozpocząć, dodaj zależność od modułów ExoPlayer, UI i Common biblioteki Jetpack Media3:

Kotlin

implementation("androidx.media3:media3-exoplayer:1.10.1")
implementation("androidx.media3:media3-ui:1.10.1")
implementation("androidx.media3:media3-common:1.10.1")

Dynamiczny

implementation "androidx.media3:media3-exoplayer:1.10.1"
implementation "androidx.media3:media3-ui:1.10.1"
implementation "androidx.media3:media3-common:1.10.1"

W zależności od przypadku użycia możesz też potrzebować dodatkowych modułów z Media3, np. exoplayer-dash, aby odtwarzać strumienie w formacie DASH.

Zastąp 1.10.1 preferowaną wersją biblioteki. Najnowszą wersję znajdziesz w informacjach o wersji.

Tworzenie odtwarzacza multimediów

W Media3 możesz użyć dołączonej implementacji interfejsu PlayerExoPlayer lub utworzyć własną implementację niestandardową.

Tworzenie odtwarzacza ExoPlayer

Najprostszy sposób utworzenia instancji ExoPlayer jest taki:

Kotlin

val player = ExoPlayer.Builder(context).build()

Java

ExoPlayer player = new ExoPlayer.Builder(context).build();

Odtwarzacz multimediów możesz utworzyć w metodzie cyklu życia onCreate() elementu Activity, Fragment lub Service, w którym się znajduje.

Builder zawiera szereg opcji dostosowywania, które mogą Cię zainteresować, takich jak:

Media3 udostępnia komponent interfejsu PlayerView, który możesz uwzględnić w pliku układu aplikacji. Ten komponent zawiera element PlayerControlView do sterowania odtwarzaniem, SubtitleView do wyświetlania napisów i Surface do renderowania wideo.

Przygotowywanie odtwarzacza

Dodawaj elementy multimedialne do playlisty, aby odtwarzać je za pomocą metod takich jak setMediaItem() i addMediaItem(). Następnie wywołaj funkcję prepare(), aby rozpocząć wczytywanie multimediów i uzyskać niezbędne zasoby.

Nie wykonuj tych czynności, zanim aplikacja nie znajdzie się na pierwszym planie. Jeśli odtwarzacz znajduje się w stanie Activity lub Fragment, oznacza to przygotowanie odtwarzacza w metodzie cyklu życia onStart() na poziomie interfejsu API 24 i wyższym lub w metodzie cyklu życia onResume() na poziomie interfejsu API 23 i niższym. W przypadku gracza, który jest w Service, możesz przygotować go w onCreate(). Przykład implementacji metod cyklu życia znajdziesz w ćwiczeniach z programowania dotyczących ExoPlayera.

Sterowanie odtwarzaczem

Po przygotowaniu odtwarzacza możesz sterować odtwarzaniem, wywołując metody odtwarzacza, takie jak:

Komponenty interfejsu, takie jak PlayerView lub PlayerControlView, będą odpowiednio aktualizowane po powiązaniu z odtwarzaczem.

Zwolnij odtwarzacz

Odtwarzanie może wymagać zasobów, które są dostępne w ograniczonej ilości, np. dekoderów wideo. Dlatego ważne jest, aby wywoływać metodę release() w odtwarzaczu, aby zwalniać zasoby, gdy odtwarzacz nie jest już potrzebny.

Jeśli odtwarzacz jest w stanie Activity lub Fragment, zwolnij go w metodzie cyklu życia onStop() na poziomie interfejsu API 24 lub wyższym albo w metodzie onPause() na poziomie interfejsu API 23 lub niższym. W przypadku zawodnika, który jest w Service, możesz go zwolnić w onDestroy(). Przykład implementacji metod cyklu życia znajdziesz w ćwiczeniach z programowania dotyczących odtwarzacza ExoPlayer.

Zarządzanie odtwarzaniem za pomocą sesji multimedialnej

Na Androidzie sesje multimedialne zapewniają standardowy sposób interakcji z odtwarzaczem multimediów w różnych procesach. Połączenie sesji multimedialnej z odtwarzaczem umożliwia przekazywanie informacji o odtwarzaniu multimediów źródłom zewnętrznym i otrzymywanie poleceń odtwarzania ze źródeł zewnętrznych, np. w celu integracji z systemowymi elementami sterującymi multimediami na urządzeniach mobilnych i urządzeniach z dużym ekranem.

Aby korzystać z sesji multimedialnych, dodaj zależność od modułu sesji Media3:

Kotlin

implementation("androidx.media3:media3-session:1.10.1")

Dynamiczny

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

Tworzenie sesji multimedialnej

Po zainicjowaniu odtwarzacza możesz utworzyć MediaSession w ten sposób:

Kotlin

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

Java

ExoPlayer player = new ExoPlayer.Builder(context).build();
MediaSession mediaSession = new MediaSession.Builder(context, player).build();

Media3 automatycznie synchronizuje stan Player ze stanem MediaSession. Działa to w przypadku każdej implementacji Player, w tym ExoPlayer, CastPlayer i implementacji niestandardowej.

Przyznawanie kontroli innym klientom

Aplikacje klienckie mogą implementować kontroler multimediów, aby sterować odtwarzaniem sesji multimedialnej. Aby otrzymywać te prośby, podczas tworzenia obiektu MediaSession ustaw obiekt callback.

Gdy kontroler ma się połączyć z sesją multimedialną, wywoływana jest metoda onConnect(). Na podstawie podanego obiektu ControllerInfo możesz zaakceptować lub odrzucić prośbę. Przykład znajdziesz w aplikacji demonstracyjnej sesji Media3.

Po nawiązaniu połączenia kontroler może wysyłać do sesji polecenia odtwarzania. Sesja przekazuje te polecenia do odtwarzacza. Polecenia odtwarzania i playlisty zdefiniowane w interfejsie Player są automatycznie obsługiwane przez sesję.

Inne metody wywołania zwrotnego umożliwiają obsługę np. żądań niestandardowych poleceń odtwarzania i modyfikowania playlisty. Te wywołania zwrotne również zawierają obiekt ControllerInfo, dzięki czemu możesz określać kontrolę dostępu w przypadku poszczególnych żądań.

Odtwarzanie multimediów w tle

Aby odtwarzać multimedia, gdy aplikacja nie jest na pierwszym planie (np. odtwarzać muzykę, audiobooki lub podcasty, nawet gdy użytkownik nie ma otwartej aplikacji), elementy Player i MediaSession powinny być umieszczone w usłudze na pierwszym planie. Media3 udostępnia w tym celu interfejs MediaSessionService.

Stosowanie dyrektywy MediaSessionService

Utwórz klasę, która rozszerza MediaSessionService, i utwórz instancję MediaSession w metodzie cyklu życia onCreate().

Kotlin

class PlaybackService : MediaSessionService() {
    private var mediaSession: MediaSession? = null

    // Create your Player and MediaSession in the onCreate lifecycle event
    override fun onCreate() {
        super.onCreate()
        val player = ExoPlayer.Builder(this).build()
        mediaSession = MediaSession.Builder(this, player).build()
    }

    // Remember to release the player and media session in onDestroy
    override fun onDestroy() {
        mediaSession?.run {
            player.release()
            release()
            mediaSession = null
        }
        super.onDestroy()
    }
}

Java

public class PlaybackService extends MediaSessionService {
    private MediaSession mediaSession = null;

    @Override
    public void onCreate() {
        super.onCreate();
        ExoPlayer player = new ExoPlayer.Builder(this).build();
        mediaSession = new MediaSession.Builder(this, player).build();
    }

    @Override
    public void onDestroy() {
        mediaSession.getPlayer().release();
        mediaSession.release();
        mediaSession = null;
        super.onDestroy();
    }
}

W pliku manifestu zadeklaruj klasę Service z filtrem intencji MediaSessionService i poproś o uprawnienia FOREGROUND_SERVICE do uruchamiania usługi na pierwszym planie:

<service
    android:name=".PlaybackService"
    android:foregroundServiceType="mediaPlayback"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaSessionService"/>
    </intent-filter>
</service>

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

Na koniec w utworzonej klasie zastąp metodę onGetSession(), aby kontrolować dostęp klientów do sesji multimedialnej. Wpisz MediaSession, aby zaakceptować prośbę o połączenie, lub null, aby ją odrzucić.

Kotlin

// This example always accepts the connection request
override fun onGetSession(
    controllerInfo: MediaSession.ControllerInfo
): MediaSession? = mediaSession

Java

@Override
public MediaSession onGetSession(MediaSession.ControllerInfo controllerInfo) {
  // This example always accepts the connection request
  return mediaSession;
}

Łączenie z interfejsem

Teraz, gdy sesja multimedialna jest oddzielona od Activity lub Fragment, w którym znajduje się interfejs odtwarzacza, możesz użyć MediaController, aby je połączyć.Service W metodzie onStart() w Activity lub Fragment w interfejsie utwórz SessionToken dla MediaSession, a następnie użyj SessionToken, aby utworzyć MediaController. Budowanie MediaController odbywa się asynchronicznie.

Kotlin

override fun onStart() {
  val sessionToken = SessionToken(this, ComponentName(this, PlaybackService::class.java))
  val controllerFuture = MediaController.Builder(this, sessionToken).buildAsync()
  controllerFuture.addListener(
    {
        // Call controllerFuture.get() to retrieve the MediaController.
        // MediaController implements the Player interface, so it can be
        // attached to the PlayerView UI component.
        playerView.setPlayer(controllerFuture.get())
      },
    MoreExecutors.directExecutor()
  )
}

Java

@Override
public void onStart() {
  SessionToken sessionToken =
    new SessionToken(this, new ComponentName(this, PlaybackService.class));
  ListenableFuture<MediaController> controllerFuture =
    new MediaController.Builder(this, sessionToken).buildAsync();
  controllerFuture.addListener(() -> {
    // Call controllerFuture.get() to retrieve the MediaController.
    // MediaController implements the Player interface, so it can be
    // attached to the PlayerView UI component.
    playerView.setPlayer(controllerFuture.get());
  }, MoreExecutors.directExecutor())
}

MediaController implementuje interfejs Player, więc możesz używać tych samych metod, takich jak play() i pause(), do sterowania odtwarzaniem. Podobnie jak w przypadku innych komponentów, pamiętaj, aby zwolnić MediaController, gdy nie jest już potrzebny w metodzie cyklu życia onStop() Activity, wywołując MediaController.releaseFuture().

Publikowanie powiadomienia

Usługi na pierwszym planie muszą publikować powiadomienie, gdy są aktywne. Usługa MediaSessionService automatycznie utworzy dla Ciebie MediaStyle powiadomienie w formie MediaNotification. Aby wyświetlić niestandardowe powiadomienie, utwórz obiekt MediaNotification.Provider z obiektem DefaultMediaNotificationProvider.Builder lub utwórz niestandardową implementację interfejsu dostawcy. Dodaj dostawcę do MediaSession za pomocą setMediaNotificationProvider.

Reklamowanie biblioteki treści

MediaLibraryService jest rozszerzeniem MediaSessionService, które umożliwia aplikacjom klienckim przeglądanie treści multimedialnych udostępnianych przez Twoją aplikację. Aplikacje klienckie implementują MediaBrowser, aby wchodzić w interakcję z MediaLibraryService.

Wdrażanie MediaLibraryService jest podobne do wdrażania MediaSessionService, z tą różnicą, że w onGetSession() należy zwracać MediaLibrarySession zamiast MediaSession. W porównaniu z MediaSession.CallbackMediaLibrarySession.Callback zawiera dodatkowe metody, które umożliwiają klientowi przeglądarki poruszanie się po treściach oferowanych przez usługę biblioteczną.

Podobnie jak w przypadku MediaSessionService, zadeklaruj MediaLibraryService w pliku manifestu i poproś o uprawnienie FOREGROUND_SERVICE do uruchamiania usługi na pierwszym planie:

<service
    android:name=".PlaybackService"
    android:foregroundServiceType="mediaPlayback"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaLibraryService"/>
        <action android:name="android.media.browse.MediaBrowserService"/>
    </intent-filter>
</service>

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

Powyższy przykład zawiera filtr intencji zarówno dla MediaLibraryService, jak i – na potrzeby zgodności wstecznej – starszego MediaBrowserService. Dodatkowy filtr intencji umożliwia aplikacjom klienckim korzystającym z interfejsu MediaBrowserCompat API rozpoznawanie Twojego Service.

MediaLibrarySession umożliwia udostępnianie biblioteki treści w strukturze drzewa z jednym poziomem głównym MediaItem. Każdy węzeł MediaItem w drzewie może mieć dowolną liczbę węzłów podrzędnych MediaItem. Możesz udostępniać inny poziom główny lub inne drzewo w zależności od żądania aplikacji klienckiej. Na przykład drzewo zwracane do klienta, który szuka listy rekomendowanych multimediów, może zawierać tylko węzeł głównyMediaItem i jeden poziom węzłów podrzędnychMediaItem, podczas gdy drzewo zwracane do innej aplikacji klienckiej może reprezentować bardziej kompletną bibliotekę treści.

Tworzenie MediaLibrarySession

MediaLibrarySession rozszerza interfejs MediaSession API, dodając interfejsy API do przeglądania treści. W porównaniu z wywołaniem zwrotnym MediaSession wywołanie zwrotne MediaLibrarySession dodaje takie metody jak:

  • onGetLibraryRoot() – gdy klient poprosi o główny węzeł MediaItem drzewa treści.
  • onGetChildren(), gdy klient zażąda elementów podrzędnych elementu MediaItem w drzewie treści.
  • onGetSearchResult() – gdy klient prosi o wyniki wyszukiwania z drzewa treści dla danego zapytania.

Odpowiednie metody wywołania zwrotnego będą zawierać obiekt LibraryParams z dodatkowymi sygnałami dotyczącymi typu drzewa treści, którym jest zainteresowana aplikacja kliencka.