Interfejs odtwarzacza

Odtwarzacz to komponent aplikacji, który umożliwia odtwarzanie elementów multimedialnych. Interfejs Media3 Player określa funkcje, które zwykle obsługuje odtwarzacz. Obejmuje to:

• wpływać na elementy sterujące odtwarzaniem, takie jak odtwarzanie, wstrzymywanie i przewijanie;
• odpytywanie o właściwości aktualnie odtwarzanych multimediów, np. pozycję odtwarzania;
• zarządzanie playlistą lub kolejką elementów multimedialnych,
• konfigurowanie właściwości odtwarzania, takich jak odtwarzanie losowe, powtarzanie, szybkość i głośność;
• Renderowanie filmu na ekranie

Media3 udostępnia też implementację interfejsu Player o nazwie ExoPlayer.

Wskazówka: jeśli chcesz wdrożyć aplikację odtwarzacza multimediów za pomocą ExoPlayera, zapoznaj się z przewodnikiem Tworzenie podstawowej aplikacji odtwarzacza multimediów za pomocą Media3 ExoPlayer.

wspólny interfejs między komponentami,

Interfejs Player implementuje kilka komponentów w Media3, na przykład:

Komponent	Opis i uwagi dotyczące zachowania
ExoPlayer	Interfejs API odtwarzacza multimediów i domyślna implementacja interfejsu Player.
MediaController	Wchodzi w interakcję z urządzeniem MediaSession, aby wysyłać polecenia odtwarzania. Jeśli Player i MediaSession znajdują się w Service oddzielnym od Activity lub Fragment, w którym znajduje się interfejs odtwarzacza, możesz przypisać MediaController jako odtwarzacz do komponentu interfejsu, takiego jak PlayerView lub Player Composable. Wywołania metod odtwarzania i playlisty są wysyłane do Player przez MediaSession.
MediaBrowser	Oprócz funkcji oferowanych przez MediaController współdziała z MediaLibrarySession, aby przeglądać dostępne treści multimedialne.
SimpleBasePlayer	Implementacja Player, która ogranicza liczbę metod do zaimplementowania do minimum. Przydatne, gdy używasz niestandardowego odtwarzacza, który chcesz połączyć z MediaSession.
ForwardingSimpleBasePlayer	Podklasa SimpleBasePlayer, która przekazuje operacje odtwarzania do innego obiektu Player, umożliwiając jednocześnie takie same dostosowania zachowania jak SimpleBasePlayer. Użyj tej klasy, aby pominąć lub zmodyfikować określone operacje odtwarzania.
RemoteCastPlayer	Implementacja Player do sterowania odtwarzaniem w zdalnej aplikacji odbiornika Cast.
CastPlayer	Implementacja Player do sterowania odtwarzaniem lokalnym i zdalnym Cast.

Chociaż MediaSession nie implementuje interfejsu Player, wymaga Player podczas tworzenia. Jego celem jest zapewnienie dostępu do Player z innych procesów lub wątków.

Architektura odtwarzania Media3

Jeśli masz dostęp do obiektu Player, wywołaj jego metody bezpośrednio, aby wydawać polecenia odtwarzania. Możesz przekazywać informacje o odtwarzaniu i przyznawać źródłom zewnętrznym uprawnienia do sterowania odtwarzaniem, implementując MediaSession. Te źródła zewnętrzne implementują interfejs MediaController, który ułatwia łączenie się z sesją multimedialną i wysyłanie żądań poleceń odtwarzania.

Podczas odtwarzania multimediów w tle sesja multimedialna i odtwarzacz muszą znajdować się w MediaSessionService lub MediaLibraryService, które działają jako usługa na pierwszym planie. Dzięki temu możesz oddzielić odtwarzacz od Activity w aplikacji, która zawiera UI z elementami sterującymi odtwarzaniem. Może to wymagać użycia kontrolera multimediów.

Ilustracja 1. Interfejs Player odgrywa kluczową rolę w architekturze Media3.

Stan odtwarzacza

Stan odtwarzacza multimedialnego implementującego interfejs Player składa się głównie z 4 kategorii informacji:

1. Stan odtwarzania
   • Pobierz za pomocą getPlaybackState().
   • Wartości stanu zdefiniowane przez interfejs to STATE_IDLE, STATE_BUFFERING, STATE_READY i STATE_ENDED.
2. Playlista z elementami multimedialnymi
   • Sekwencja instancji MediaItem do odtworzenia.
   • Pobieranie za pomocą getCurrentTimeline()
   • Instancje Player mogą udostępniać metody operacji na playliście, takie jak dodawanie lub usuwanie elementu MediaItem, oraz metody ułatwiające, takie jak getCurrentMediaItem().
3. Właściwości odtwarzania/wstrzymywania, takie jak:
   • playWhenReady: wskazuje, czy użytkownik chce, aby multimedia były odtwarzane, gdy jest to możliwe, czy też mają pozostać wstrzymane.
   • Przyczyna wstrzymania odtwarzania: wskazanie przyczyny wstrzymania odtwarzania (jeśli dotyczy), nawet jeśli playWhenReady to true
   • isPlaying: wskazuje, czy odtwarzacz aktualnie odtwarza treści. Wartość będzie wynosić true tylko wtedy, gdy stan odtwarzania to STATE_READY, playWhenReady to true, a odtwarzanie nie jest wstrzymane.
4. Pozycja odtwarzania, w tym:
   • Current media item index: indeks bieżącego elementu multimedialnego MediaItem na playliście.
   • isPlayingAd: informacja o tym, czy wstawiona reklama jest odtwarzana.
   • Bieżąca pozycja odtwarzania: bieżąca pozycja odtwarzania w bieżącym elemencie MediaItem lub wstawionej reklamie.

Interfejs Player umożliwia też dostęp do dostępnych ścieżek, metadanych multimediów, szybkości odtwarzania, głośności i innych właściwości pomocniczych odtwarzania.

Uwaga: instancje Player nie muszą obsługiwać wszystkich funkcji interfejsu. Możesz sprawdzić dostępne polecenia, aby dowiedzieć się, która funkcja jest obsługiwana i którą metodę można wywołać.

Sprawdzanie zmian

Użyj Player.Listener, aby monitorować zmiany w Player. Szczegółowe informacje o tworzeniu i używaniu detektora znajdziesz w dokumentacji ExoPlayera dotyczącej zdarzeń odtwarzacza.

Pamiętaj, że interfejs detektora nie zawiera żadnych wywołań zwrotnych do śledzenia normalnego postępu odtwarzania. Aby stale monitorować postęp odtwarzania, np. w celu skonfigurowania paska postępu, należy sprawdzać bieżącą pozycję w odpowiednich odstępach czasu.

Kotlin

fun checkPlaybackPosition(delayMs: Long): Boolean =
  handler.postDelayed(
    {
      val currentPosition = player.currentPosition
      // Update UI based on currentPosition
      checkPlaybackPosition(delayMs)
    },
    delayMs,
  )
Player.kt

Java

boolean checkPlaybackPosition(long delayMs) {
  return handler.postDelayed(
      () -> {
        long currentPosition = player.getCurrentPosition();
        // Update UI based on currentPosition
        checkPlaybackPosition(delayMs);
      },
      delayMs);
}
Player.java

sterować odtwarzaniem.

Interfejs Player oferuje wiele sposobów manipulowania stanem i sterowania odtwarzaniem:

• Podstawowe elementy sterujące odtwarzaniem, takie jak play(), pause(), prepare() i stop().
• Operacje na playlistach, takie jak addMediaItem() lub removeMediaItem().
• Przewijanie, aby zmienić bieżący element lub pozycję.
• ustawiać tryby powtarzania i tryb odtwarzania losowego,
• Zaktualizuj ustawienia wyboru ścieżki.
• Ustaw szybkość odtwarzania.

Uwaga: instancje Player nie muszą obsługiwać wszystkich funkcji interfejsu. Możesz sprawdzić dostępne polecenia, aby dowiedzieć się, która funkcja jest obsługiwana i którą metodę można wywołać.

Niestandardowe implementacje Player

Aby utworzyć odtwarzacz niestandardowy, możesz rozszerzyć klasę SimpleBasePlayer zawartą w Media3. Ta klasa zapewnia podstawową implementację interfejsu Player, aby ograniczyć do minimum liczbę metod, które musisz zaimplementować.

Zacznij od zastąpienia metody getState(). Ta metoda powinna po wywołaniu wypełniać bieżący stan gracza, w tym:

• Zestaw dostępnych poleceń
• właściwości odtwarzania, np. czy odtwarzacz powinien rozpocząć odtwarzanie, gdy stan odtwarzania to STATE_READY, indeks aktualnie odtwarzanego elementu multimedialnego i pozycję odtwarzania w bieżącym elemencie;

Kotlin

class CustomPlayer(looper: Looper) : SimpleBasePlayer(looper) {
  override fun getState(): State {
    return State.Builder()
      .setAvailableCommands(Commands.EMPTY) // Set which playback commands the player can handle
      // Configure additional playback properties
      .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
      .setCurrentMediaItemIndex(0)
      .setContentPositionMs(0)
      .build()
  }
}
Player.kt

Java

private static final class CustomPlayer extends SimpleBasePlayer {
  public CustomPlayer(Looper looper) {
    super(looper);
  }

  @Override
  protected State getState() {
    return new State.Builder()
        .setAvailableCommands(Commands.EMPTY) // Set which playback commands the player can handle
        // Configure additional playback properties
        .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
        .setCurrentMediaItemIndex(0)
        .setContentPositionMs(0)
        .build();
  }
}
Player.java

SimpleBasePlayer wymusi utworzenie State z prawidłową kombinacją wartości stanu. Będzie też obsługiwać detektory i informować je o zmianach stanu. Jeśli chcesz ręcznie wywołać aktualizację stanu, wywołaj metodę invalidateState().

Oprócz metody getState() musisz zaimplementować tylko metody używane w przypadku poleceń, które odtwarzacz deklaruje jako dostępne. Znajdź metodę modułu obsługi, którą można zastąpić, odpowiadającą funkcji, którą chcesz zaimplementować. Możesz na przykład zastąpić metodę handleSeek(), aby obsługiwać operacje takie jak COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM i COMMAND_SEEK_TO_NEXT_MEDIA_ITEM.

Modyfikowanie implementacji Player

Zamiast tworzyć całkowicie niestandardowy element Player, możesz użyć ForwardingSimpleBasePlayer, aby zmodyfikować stan i zachowanie istniejącego elementu Player. Więcej informacji znajdziesz w przewodniku na stronie Dostosowywanie.

Wskazówka: podczas pisania testów Robolectric lub testów UI dla komponentów, które akceptują Player, użyj FakePlayer w media3-test-utils zamiast implementować niestandardowy kod testowy lub pozorować Player. Więcej informacji znajdziesz w artykule o testowaniu komponentów interfejsu i aplikacji za pomocą FakePlayer.