Wiedergabesteuerung zur App hinzufügen

Eine App, die Medien abspielt, benötigt Komponenten der Benutzeroberfläche zum Anzeigen von Medien und Steuern der Wiedergabe. Die Media3-Bibliothek enthält ein UI-Modul, das eine Reihe von UI-Komponenten enthält. Fügen Sie die folgende Abhängigkeit hinzu, um vom UI-Modul abhängig zu sein:

Kotlin

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

Cool

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

Die wichtigste Komponente ist PlayerView, eine Ansicht für die Medienwiedergabe. PlayerView zeigt während der Wiedergabe Videos, Untertitel und Albumcover sowie die Wiedergabesteuerung an.

PlayerView hat eine setPlayer-Methode zum Anhängen und Trennen von Spielerinstanzen durch Übergabe von null.

Player-Ansicht

PlayerView kann sowohl für die Video- als auch für die Audiowiedergabe verwendet werden. Er rendert Videos und Untertitel bei der Videowiedergabe und kann Artwork anzeigen, das als Metadaten in Audiodateien enthalten ist. Sie können sie wie jede andere UI-Komponente in Ihre Layoutdateien einfügen. Beispielsweise kann ein PlayerView in folgendem XML-Code enthalten sein:

<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"/>

Das Snippet oben zeigt, dass PlayerView mehrere Attribute hat. Mit diesen Attributen können Sie das Verhalten und das Design der Ansicht anpassen. Die meisten dieser Attribute haben entsprechende Setter-Methoden, mit denen die Ansicht während der Laufzeit angepasst werden kann. Im Javadoc zu PlayerView werden diese Attribute und Setter-Methoden ausführlicher aufgeführt.

Nachdem die Ansicht in der Layoutdatei deklariert wurde, kann sie in der onCreate-Methode der Aktivität gesucht werden:

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);
}

Wenn ein Player initialisiert wurde, kann er durch Aufrufen von setPlayer an die Ansicht angehängt werden:

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();

Oberflächentyp auswählen

Mit dem Attribut surface_type von PlayerView kannst du die Art der Oberfläche festlegen, die für die Videowiedergabe verwendet wird. Neben den Werten spherical_gl_surface_view (ein spezieller Wert für die sphärische Videowiedergabe) und video_decoder_gl_surface_view (für das Video-Rendering mit Erweiterungs-Renderern) sind die zulässigen Werte surface_view, texture_view und none. Wenn die Ansicht nur für die Audiowiedergabe vorgesehen ist, sollte none verwendet werden, damit keine Oberfläche erstellt werden muss, da dies teuer sein kann.

Wenn der Aufruf für die normale Videowiedergabe vorgesehen ist, sollten Sie surface_view oder texture_view verwenden. SurfaceView bietet gegenüber TextureView eine Reihe von Vorteilen bei der Videowiedergabe:

• Erheblich geringerer Stromverbrauch auf vielen Geräten.
• Genaueres Frame-Timing für eine flüssigere Videowiedergabe
• Unterstützung für eine höhere HDR-Videoausgabe auf kompatiblen Geräten.
• Unterstützung einer sicheren Ausgabe bei der Wiedergabe von DRM-geschützten Inhalten
• Die Möglichkeit, Videoinhalte auf Android TV-Geräten in voller Auflösung des Bildschirms zu rendern, wobei die UI-Ebene angepasst wird.

Daher sollte nach Möglichkeit SurfaceView gegenüber TextureView bevorzugt werden. TextureView sollte nur verwendet werden, wenn SurfaceView Ihre Anforderungen nicht erfüllt. Vor Android 7.0 (API-Level 24) sind beispielsweise flüssige Animationen oder Scrollen auf der Videooberfläche erforderlich, wie in den folgenden Hinweisen beschrieben. In diesem Fall wird empfohlen, TextureView nur dann zu verwenden, wenn SDK_INT kleiner als 24 ist (Android 7.0) und andernfalls SurfaceView.

Hinweis :Das Rendering von SurfaceView wurde erst ab Android 7.0 (API-Level 24) richtig mit Ansichtsanimationen synchronisiert. In früheren Releases konnte dies zu unerwünschten Effekten führen, wenn eine SurfaceView in einem scrollbaren Container platziert oder einer Animation unterzogen wurde. Zu diesen Effekten gehörten, dass der Inhalt der Ansicht etwas hinter der vorgesehenen Anzeige zurückbleibt und die Ansicht bei einer Animation schwarz wurde. Vor Android 7.0 ist es daher notwendig, TextureView statt SurfaceView zu verwenden, um ein flüssiges Animations- oder Scrollen von Videos zu erreichen.

Hinweis: Der Lebenszyklus einer SurfaceView-Oberfläche ist an die Sichtbarkeit der Ansicht gebunden, während der Lebenszyklus einer TextureView-Oberfläche mit dem Anbringen und Trennen eines Fensters verbunden ist. Daher kann das Starten der Wiedergabe in scrollbaren UIs, die SurfaceView verwenden, länger dauern, da die Ausgabeoberfläche etwas später verfügbar wird. Ab Android 14 verwendet PlayerView SurfaceView.setSurfaceLifecycle(SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT), um dieses Verhalten zu vermeiden. Wenn Ihre Anwendung SurfaceView direkt (ohne PlayerView) verwendet, sollten Sie diesen Modus aktivieren. Vor Android 14 war es möglich, die zerstörte Oberfläche zu umgehen, indem Ansichten beim Recyceln außerhalb des Bildschirms übersetzt werden.

Hinweis: Auf einigen Android TV-Geräten wird die UI-Ebene auf einigen Android TV-Geräten mit einer Auflösung ausgeführt, die niedriger als die volle Auflösung des Bildschirms ist, wodurch sie für die Präsentation für den Nutzer vergrößert wird. Die UI-Ebene kann beispielsweise auf einem Android TV mit 4K-Bildschirm mit 1080p ausgeführt werden. Auf solchen Geräten muss SurfaceView verwendet werden, um Inhalte in voller Auflösung des Bildschirms zu rendern. Die volle Auflösung des Bildschirms im aktuellen Anzeigemodus kann mit Util.getCurrentDisplayModeSize abgefragt werden. Die Auflösung der UI-Ebene kann mit der Display.getSize API von Android abgefragt werden.

Navigation über das Steuerkreuz bei Android TV

Die Fernbedienung von Android TV hat ein Steuerkreuz, mit dem Befehle gesendet werden, die als Schlüsselereignis an dispatchKeyEvent(KeyEvent) deiner Activity ankommen. Diese müssen an die Spieleransicht delegiert werden:

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);
}

Das Anfordern des Fokus für die Playeransicht ist wichtig, um die Wiedergabesteuerung zu steuern und Anzeigen zu überspringen. Sie können den Fokus in onCreate der Activity anfordern:

Kotlin

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

Java

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

Wenn du Compose auf Android TV verwendest, musst du AndroidView fokussierbar machen und das Ereignis delegieren, indem du den Modifikatorparameter entsprechend in die AndroidView übergibst:

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

Drawables überschreiben

Achtung :Wir können nicht garantieren, dass die im folgenden Abschnitt beschriebenen Anpassungen in zukünftigen Versionen der Bibliothek weiterhin funktionieren. Die Ressourcen-IDs können sich ändern oder werden vollständig gelöscht. Dies wird durch die als „privat“ gekennzeichneten Ressourcen-IDs angezeigt.

PlayerView verwendet PlayerControlView, um die Wiedergabesteuerung und die Fortschrittsanzeige anzuzeigen. Die von PlayerControlView verwendeten Drawables können von Drawables mit denselben Namen überschrieben werden, die in Ihrer Anwendung definiert sind. Eine Liste der Drawables für Steuerelemente, die überschrieben werden können, findest du in der Javadoc zu PlayerControlView.

Weitere Anpassungsmöglichkeiten

Wenn darüber hinaus Anpassungen erforderlich sind, erwarten wir, dass App-Entwickler ihre eigenen UI-Komponenten implementieren und nicht die über das UI-Modul von Media3 bereitgestellten Komponenten verwenden.