Dodaj elementy sterujące odtwarzaniem w aplikacji

Aplikacja odtwarzająca multimedia wymaga elementów interfejsu użytkownika do wyświetlania multimediów i sterowania odtwarzaniem. Biblioteka Media3 zawiera moduł interfejsu użytkownika, który zawiera wiele komponentów interfejsu. Aby utworzyć zależność od modułu interfejsu użytkownika, dodaj tę zależność:

Kotlin

implementation("androidx.media3:media3-ui:1.4.1")

Groovy

implementation "androidx.media3:media3-ui:1.4.1"

Najważniejszym elementem jest PlayerView, czyli widok odtwarzania multimediów. PlayerView wyświetla film, obrazy, napisy i okładkę albumu podczas odtwarzania, a także elementy sterujące odtwarzaniem.

PlayerView ma metodę setPlayer dołączania i odłączania (przez przekazywanie null) instancji odtwarzacza.

PlayerView

PlayerView może służyć do odtwarzania filmów, obrazów i dźwięku. W przypadku odtwarzania wideo renderuje ona filmy i napisy, a w przypadku obrazów – bitmapy. Może też wyświetlać elementy graficzne zawarte w metadanych plików audio. Możesz go umieścić w plikach układu tak samo jak każdy inny komponent UI. Na przykład pole PlayerView może być uwzględnione w tym pliku XML:

<androidx.media3.ui.PlayerView
    android:id="@+id/player_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:show_buffering="when_playing"
    app:show_shuffle_button="true"/>

Fragment kodu powyżej pokazuje, że PlayerView zawiera kilka atrybutów. Za pomocą tych atrybutów możesz dostosować zachowanie widoku, a także jego wygląd i wygląd. Większość z tych atrybutów ma odpowiednie metody settera, których można używać do dostosowywania widoku w czasie wykonywania. W dokumentacji Javadoc dotyczącej klasy PlayerView znajdziesz więcej informacji o tych atrybutach i metodach settera.

Gdy widok zostanie zadeklarowany w pliku układu, można go wyszukać w metodie onCreate aktywności:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView = findViewById(R.id.player_view)
}

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  // ...
  playerView = findViewById(R.id.player_view);
}

Po zainicjowaniu odtwarzacza można go dołączyć do widoku, wywołując funkcję setPlayer:

Kotlin

// Instantiate the player.
val player = ExoPlayer.Builder(context).build()
// Attach player to the view.
playerView.player = player
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()

Java

// Instantiate the player.
player = new ExoPlayer.Builder(context).build();
// Attach player to the view.
playerView.setPlayer(player);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();

Wybieranie typu powierzchni

Atrybut surface_type elementu PlayerView pozwala ustawić typ powierzchni używanej do odtwarzania filmu. Oprócz wartości spherical_gl_surface_view (która jest wartością specjalną dla odtwarzania filmów sferycznych) i video_decoder_gl_surface_view (która służy do renderowania filmów za pomocą rendererów rozszerzeń) dozwolone wartości to surface_view, texture_view i none. Jeśli widok służy tylko do odtwarzania dźwięku, należy użyć none, aby uniknąć tworzenia powierzchni, ponieważ może to być kosztowne.

Jeśli widok służy do odtwarzania zwykłego filmu, należy użyć parametru surface_view lub texture_view. SurfaceView ma szereg zalet w porównaniu z TextureView w przypadku odtwarzania filmów:

• znacznie obniżyć zużycie energii na wielu urządzeniach;
• Dokładniejsze ustalanie czasu wyświetlania klatek, co zapewnia płynniejsze odtwarzanie filmów.
• Obsługa wyjścia wideo HDR o wyższej jakości na urządzeniach, które obsługują tę funkcję.
• Obsługa bezpiecznego wyjścia podczas odtwarzania treści chronionych przez DRM.
• Możliwość renderowania treści wideo w pełnej rozdzielczości wyświetlacza na urządzeniach z Androidem TV, które powiększają warstwę interfejsu użytkownika.

Dlatego, jeśli to możliwe, preferuj opcję SurfaceView zamiast TextureView. TextureView należy używać tylko wtedy, gdy SurfaceView nie spełnia Twoich potrzeb. Przykładem jest płynne wyświetlanie animacji lub przewijanie powierzchni wideo w wersjach Androida 7.0 (interfejs API na poziomie 24) i starszych, jak opisano w uwagach poniżej. W tym przypadku zalecamy używanie TextureView tylko wtedy, gdy SDK_INT jest mniejsza niż 24 (Android 7.0), a w przeciwnym razie SurfaceView.

Uwaga: renderowanie SurfaceView nie było prawidłowo zsynchronizowane z animowanymi widokami do Androida 7.0 (poziom API 24). W wcześniejszych wersjach mogło to powodować niepożądane efekty, gdy SurfaceView był umieszczany w przewijanym kontenerze lub był poddawany animacji. Efekty te obejmowały m.in. niewielkie opóźnienie wyświetlania treści oraz wyświetlanie obrazu w kolorze czarnym podczas animacji. Aby uzyskać płynną animację lub przewijanie filmu w wersjach Androida starszych niż 7.0, należy użyć TextureView zamiast SurfaceView.

Uwaga: cykl życia powierzchni SurfaceView jest powiązany z widocznością widoku, a cykl życia powierzchni TextureView – z dołączeniem i odłączeniem okna. Dlatego w interfejsach z przewijaniem, które używają SurfaceView, rozpoczęcie odtwarzania może zająć więcej czasu, ponieważ powierzchnia wyjściowa staje się dostępna nieco później. Od Androida 14 aplikacja PlayerView używa SurfaceView.setSurfaceLifecycle(SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT), aby uniknąć takiego zachowania. Jeśli Twoja aplikacja używa bezpośrednio SurfaceView (bez PlayerView), możesz włączyć ten tryb. W wersjach starszych niż Android 14 można obejść problem z niszczeniem powierzchni, przenosząc widoki poza ekran podczas ich ponownego wykorzystania.

Uwaga: niektóre urządzenia z Androidem TV wyświetlają warstwę interfejsu użytkownika w rozdzielczości niższej niż pełna rozdzielczość ekranu, a następnie zwiększają ją do wyświetlenia dla użytkownika. Na przykład warstwa interfejsu użytkownika może działać w rozdzielczości 1080p na urządzeniu Android TV z ekranem 4K. Na takich urządzeniach do renderowania treści w pełnej rozdzielczości wyświetlacza należy użyć SurfaceView. Pełna rozdzielczość wyświetlacza (w bieżącym trybie wyświetlania) może być pobierana za pomocą zapytania Util.getCurrentDisplayModeSize. Rozdzielczość warstwy interfejsu użytkownika można sprawdzić za pomocą interfejsu API Display.getSize na Androidzie.

Korzystanie z krzyżałka na Androidzie TV

Pilot Android TV ma panel sterujący, który wysyła polecenia jako zdarzenia klawisza w urządzeniu dispatchKeyEvent(KeyEvent).Activity Te elementy muszą zostać przeniesione do widoku odtwarzacza:

Kotlin

override fun dispatchKeyEvent(event: KeyEvent?): Boolean{
  return playerView.dispatchKeyEvent(event!!) || super.dispatchKeyEvent(event)
}

Java

@Override
public boolean dispatchKeyEvent(KeyEvent event) {
  return playerView.dispatchKeyEvent(event) || super.dispatchKeyEvent(event);
}

Żądanie skupienia na widoku odtwarzacza jest ważne dla nawigacji elementów sterujących odtwarzaniem i pomijania reklam. Zastanów się, czy chcesz skoncentrować się na onCreate w ramach Activity:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView.requestFocus()
  // ...
}

Java

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...
    playerView.requestFocus();
    // ...
}

Jeśli używasz Compose na Androidzie TV, musisz umożliwić skupienie na elemencie AndroidView i przekazać zdarzenie, przekazując parametr modyfikatora do elementu AndroidView:

AndroidView(
  modifier = modifier
    .focusable()
    .onKeyEvent { playerView.dispatchKeyEvent(it.nativeKeyEvent) },
  factory = { playerView }
)

Zastępowanie rysunków

Uwaga: nie gwarantujemy, że funkcje dostosowania opisane w następującej sekcji będą działać w przyszłych wersjach biblioteki. Identyfikatory zasobów mogą zmienić nazwę lub niektóre z nich mogą zostać całkowicie usunięte. Wskazuje na to fakt, że identyfikatory zasobów są oznaczone jako „prywatne”.

PlayerView używa PlayerControlView do wyświetlania elementów sterujących odtwarzaniem i paska postępu. Obiekty graficzne używane przez PlayerControlView mogą zostać zastąpione przez obiekty graficzne o tych samych nazwach zdefiniowanych w aplikacji. Aby zobaczyć listę elementów rysowanych kontrolera, które można zastąpić, zajrzyj do dokumentacji PlayerControlView w języku Javadoc.

Dalsze dostosowywanie

Jeśli wymagane jest dostosowanie wykraczające poza opisaną powyżej funkcjonalność, oczekujemy, że deweloperzy aplikacji wdrożą własne komponenty UI zamiast korzystać z tych udostępnianych przez moduł UI Media3.