Wiedergabesteuerung zur App hinzufügen

Eine App, in der Medien wiedergegeben werden, benötigt Benutzeroberflächenkomponenten zum Anzeigen von Medien und zum Steuern der Wiedergabe. Die Media3-Bibliothek enthält ein UI-Modul mit einer Reihe von UI-Komponenten. Wenn Sie vom UI-Modul abhängig sein möchten, fügen Sie die folgende Abhängigkeit hinzu:

Kotlin

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

Groovy

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

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

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

PlayerView

PlayerView kann sowohl für die Video-, Bild- als auch die Audiowiedergabe verwendet werden. Bei der Videowiedergabe werden Video und Untertitel gerendert, bei der Bildwiedergabe Bitmaps und es kann Artwork angezeigt werden, das als Metadaten in Audiodateien enthalten ist. Sie können sie wie jede andere UI-Komponente in Ihre Layoutdateien einfügen. Ein PlayerView kann beispielsweise in das folgende XML-Element eingefügt werden:

<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 bietet. Mit diesen Attributen können Sie das Verhalten und das Erscheinungsbild der Ansicht anpassen. Die meisten dieser Attribute haben entsprechende Setzermethoden, mit denen sich die Ansicht zur Laufzeit anpassen lässt. In der Javadoc-Datei für PlayerView werden diese Attribute und Setzermethoden ausführlicher beschrieben.

Nachdem die Ansicht in der Layoutdatei deklariert wurde, kann sie in der onCreate-Methode der Aktivität abgerufen 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);
}

Nachdem ein Player initialisiert wurde, kann er der Ansicht durch Aufrufen von setPlayer hinzugefügt 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äche auswählen

Mit dem surface_type-Attribut von PlayerView können Sie 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 Wiedergabe von sphärischen Videos) und video_decoder_gl_surface_view (für das Video-Rendering mit Erweiterungs-Renderern) sind surface_view, texture_view und none zulässig. Wenn die Ansicht nur für die Audiowiedergabe gedacht ist, sollte none verwendet werden, um das Erstellen einer Oberfläche zu vermeiden, da dies teuer sein kann.

Wenn die Ansicht für die normale Videowiedergabe gedacht ist, sollte surface_view oder texture_view verwendet werden. SurfaceView bietet im Vergleich zu TextureView einige Vorteile bei der Videowiedergabe:

• Wesentlich geringerer Stromverbrauch bei vielen Geräten.
• Genaueres Frame-Timing für eine flüssigere Videowiedergabe
• Unterstützung für eine höhere Qualität der HDR-Videoausgabe auf kompatiblen Geräten.
• Unterstützung für sichere Ausgabe bei der Wiedergabe von DRM-geschützten Inhalten
• Die Möglichkeit, Videoinhalte in der vollen Auflösung des Displays auf Android TV-Geräten zu rendern, die die UI-Ebene hochskalieren.

SurfaceView sollte daher nach Möglichkeit TextureView vorgezogen werden. TextureView sollte nur verwendet werden, wenn SurfaceView nicht Ihren Anforderungen entspricht. Ein Beispiel hierfür sind flüssige Animationen oder das Scrollen der Videooberfläche vor Android 7.0 (API-Level 24), wie in den folgenden Hinweisen beschrieben. In diesem Fall sollten Sie TextureView nur verwenden, wenn SDK_INT kleiner als 24 (Android 7.0) ist, andernfalls SurfaceView.

Hinweis :Das SurfaceView-Rendering wurde erst mit Android 7.0 (API-Level 24) richtig mit den Ansichtsanimationen synchronisiert. In früheren Releases konnte dies zu unerwünschten Effekten führen, wenn ein SurfaceView in einen scrollbaren Container eingefügt oder animiert wurde. Dazu gehörten unter anderem Verzögerungen beim Einblenden des Inhalts der Ansicht und das Schwarzwerden der Ansicht bei einer Animation. Um eine flüssige Animation oder ein flüssiges Scrollen von Videos vor Android 7.0 zu ermöglichen, ist es daher erforderlich, TextureView anstelle von SurfaceView zu verwenden.

Hinweis: Der Lebenszyklus der Oberfläche einer SurfaceView ist an die Sichtbarkeit der Ansicht gebunden, während der Lebenszyklus der Oberfläche einer TextureView an das An- und Abhängen des Fensters gebunden ist. Daher kann es bei scrollbaren UIs, in denen SurfaceView verwendet wird, länger dauern, bis die Wiedergabe gestartet wird, da die Ausgabefläche etwas später verfügbar ist. Ab Android 14 verwendet PlayerView SurfaceView.setSurfaceLifecycle(SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT), um dieses Verhalten zu vermeiden. Wenn Ihre App SurfaceView direkt (ohne PlayerView) verwendet, sollten Sie diesen Modus aktivieren. Vor Android 14 können Sie das Problem umgehen, indem Sie Ansichten beim Wiederverwenden aus dem Display heraus verschieben.

Hinweis :Auf einigen Android TV-Geräten wird die Benutzeroberfläche mit einer Auflösung ausgeführt, die niedriger als die volle Auflösung des Displays ist. Diese wird dann für die Darstellung für den Nutzer hochskaliert. So kann die UI-Ebene beispielsweise mit 1080p auf einem Android TV-Gerät mit 4K-Display ausgeführt werden. Auf solchen Geräten muss SurfaceView verwendet werden, um Inhalte in der vollen Auflösung des Displays zu rendern. Die volle Auflösung des Displays (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.

D-Pad-Navigation auf Android TV

Die Android TV-Fernbedienung hat ein D-Pad, über das Befehle gesendet werden, die als Schlüsselereignis an dispatchKeyEvent(KeyEvent) von Activity gesendet werden. Diese müssen an die Playeransicht 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 Wiedergabeansicht ist wichtig, um die Wiedergabesteuerung zu bedienen und Anzeigen zu überspringen. Sie können den Fokus in onCreate des 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 Sie Compose auf Android TV verwenden, müssen Sie die AndroidView so konfigurieren, dass sie fokussierbar ist. Außerdem müssen Sie das Ereignis delegieren, indem Sie den Modifikatorparameter entsprechend an die AndroidView übergeben:

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 auch in zukünftigen Versionen der Bibliothek funktionieren. Die Namen der Ressourcen-IDs können sich ändern oder einige werden möglicherweise vollständig gelöscht. Das wird durch die Kennzeichnung der Ressourcen-IDs als „privat“ angezeigt.

In PlayerView werden die Wiedergabesteuerung und der Fortschrittsbalken mit PlayerControlView angezeigt. Die von PlayerControlView verwendeten Drawables können durch Drawables mit denselben Namen überschrieben werden, die in Ihrer Anwendung definiert sind. Eine Liste der Drawables für Steuerelemente, die überschrieben werden können, finden Sie in der Javadoc-Datei für PlayerControlView.

Weitere Anpassungen

Wenn eine darüber hinausgehende Anpassung erforderlich ist, gehen wir davon aus, dass App-Entwickler ihre eigenen UI-Komponenten implementieren, anstatt die vom UI-Modul von Media3 bereitgestellten zu verwenden.