Mediensitzung verwenden

Media Sessions bieten eine universelle Möglichkeit, mit einem Audio- oder Videoplayer zu interagieren. Wenn Android darüber informiert wird, dass Medien in einer App wiedergegeben werden, kann die Wiedergabesteuerung an die App delegiert werden. Durch die Integration in die Mediensitzung kann eine App die Medienwiedergabe extern bewerben und Wiedergabebefehle von externen Quellen empfangen. Bei diesen Quellen kann es sich um physische Tasten wie die Wiedergabetaste an einem Headset oder auf einer TV-Fernbedienung oder um indirekte Befehle wie der an Google Assistant gerichtete Sprachbefehl „Pausieren“ handeln. In der Media Session werden diese Befehle dann an die App delegiert, die sie auf den Mediaplayer anwendet. Für den Mediaplayer ist es transparent, woher die Befehle stammen.

Eine Media Session wird zusammen mit dem Player ausgeführt, den sie verwaltet. Sie sollten eine Media Session in der onCreate()-Methode der Aktivität oder des Dienstes erstellen und initialisieren, die die Media Session und den zugehörigen Player enthalten.

Mediensitzung initialisieren

Eine neu erstellte Mediensitzung hat keine Funktionen. Sie müssen die Sitzung mit den folgenden Schritten initialisieren:

  • Setze Flags, damit die Media Session Callbacks von Mediencontrollern und Medientasten empfangen kann.
  • Erstellen und initialisieren Sie eine Instanz von PlaybackStateCompat und weisen Sie sie der Sitzung zu. Der Wiedergabestatus ändert sich während der Sitzung. Wir empfehlen daher, die PlaybackStateCompat.Builder zur Wiederverwendung im Cache zu speichern.
  • Erstellen Sie eine Instanz von MediaSessionCompat.Callback und weisen Sie sie der Sitzung zu (weitere Informationen zu Callbacks finden Sie unten).

Sie sollten eine Media Session in der onCreate()-Methode der Aktivität oder des Dienstes erstellen und initialisieren, die bzw. der die Sitzung enthält.

Damit Medientasten funktionieren, wenn deine App neu initialisiert (oder beendet) wird, muss ihr PlaybackState eine Wiedergabeaktion enthalten, die dem Intent entspricht, den die Medientaste sendet. Aus diesem Grund wird ACTION_PLAY während der Initialisierung dem Sitzungsstatus zugewiesen. Weitere Informationen findest du unter Auf Medienschaltflächen reagieren.

Wiedergabestatus und Metadaten beibehalten

Es gibt zwei Klassen, die den Status einer Mediensitzung darstellen.

Die Klasse PlaybackStateCompat beschreibt den aktuellen Betriebszustand des Players. Dazu zählen:

  • Der Transportstatus (ob der Player gerade etwas wiedergibt, pausiert ist, zwischenspeichert usw.). Weitere Informationen findest du unter getState().
  • Ein Fehlercode und eine optionale Fehlermeldung, falls zutreffend. Weitere Informationen finden Sie unter getErrorCode() und Status und Fehler unten.
  • Die Spielerposition
  • Die gültigen Controller-Aktionen, die im aktuellen Status verarbeitet werden können

Die Klasse MediaMetadataCompat beschreibt das Material, das wiedergegeben wird:

  • Name des Künstlers, des Albums und des Titels
  • Die Dauer des Titels
  • Albumcover für die Anzeige auf dem Sperrbildschirm. Das Bild ist eine Bitmap mit einer maximalen Größe von 320 × 320 dp. Wenn es größer ist, wird es herunterskaliert.
  • Eine Instanz von ContentUris, die auf eine größere Version des Bildmaterials verweist

Der Player-Status und die Metadaten können sich im Laufe einer Mediensitzung ändern. Jedes Mal, wenn sich der Status oder die Metadaten ändern, musst du den entsprechenden Builder für jede Klasse (PlaybackStateCompat.Builder() oder MediaMetadataCompat.Builder()) verwenden und dann die neue Instanz an die Mediensitzung übergeben, indem du setPlaybackState() oder setMetaData() aufrufst. Um den Gesamtspeicherverbrauch durch diese häufigen Vorgänge zu reduzieren, empfiehlt es sich, die Builder einmal zu erstellen und sie während der gesamten Lebensdauer der Sitzung wiederzuverwenden.

Status und Fehler

PlaybackState ist ein Objekt, das separate Werte für den Wiedergabestatus der Sitzung (getState()) und, falls erforderlich, einen zugehörigen Fehlercode (getErrorCode()) enthält. Fehler können schwerwiegend oder nicht schwerwiegend sein:

Wenn die Wiedergabe unterbrochen wird, solltest du einen schwerwiegenden Fehler generieren: Setze den Transportstatus auf STATE_ERROR und gib einen zugehörigen Fehler mit setErrorMessage(int, CharSequence) an. Solange die Wiedergabe durch den Fehler blockiert wird, sollte der PlaybackState weiterhin STATE_ERROR und den Fehler melden.

Ein nicht schwerwiegender Fehler tritt auf, wenn deine App eine Anfrage nicht verarbeiten kann, aber die Wiedergabe fortsetzen kann: Der Transport bleibt in einem „normalen“ Zustand (z. B. STATE_PLAYING), aber der PlaybackState enthält einen Fehlercode. Wenn beispielsweise der letzte Titel abgespielt wird und der Nutzer zum nächsten Titel springen möchte, kann die Wiedergabe fortgesetzt werden. Du solltest jedoch ein neues PlaybackState mit dem Fehlercode ERROR_CODE_END_OF_QUEUE erstellen und dann setPlaybackState() aufrufen. Mit der Sitzung verbundene Medien-Controller erhalten den Callback onPlaybackStateChanged() und erklären dem Nutzer, was passiert ist. Ein nicht schwerwiegender Fehler sollte nur einmal gemeldet werden, wenn er auftritt. Wenn die Sitzung das nächste Mal die PlaybackState aktualisiert, legen Sie nicht noch einmal denselben nicht schwerwiegenden Fehler fest (es sei denn, der Fehler ist als Reaktion auf eine neue Anfrage aufgetreten).

Sperrbildschirme für Mediensitzungen

Ab Android 4.0 (API-Level 14) kann das System auf den Wiedergabestatus und die Metadaten einer Mediensitzung zugreifen. So können auf dem Sperrbildschirm die Mediensteuerung und Cover angezeigt werden. Das Verhalten variiert je nach Android-Version.

Albumcover

In Android 4.0 (API-Level 14) bis Android 10 (API-Level 29) wird im Hintergrund des Sperrbildschirms das Albumcover angezeigt, aber nur, wenn die Metadaten der Mediensitzung eine Hintergrund-Bitmap enthalten.

Transportsteuerung

In Android 4.0 (API-Level 14) bis Android 4.4 (API-Level 19) werden auf dem Sperrbildschirm automatisch Steuerelemente für die Medienwiedergabe angezeigt, wenn eine Mediensitzung aktiv ist und die Metadaten der Mediensitzung eine Hintergrund-Bitmap enthalten.

Unter Android 5.0 (API-Level 21) oder höher bietet das System keine Transportsteuerelemente auf dem Sperrbildschirm. Stattdessen solltest du eine MediaStyle-Benachrichtigung verwenden, um die Steuerelemente für die Wiedergabe anzuzeigen.

Benutzerdefinierte Aktionen hinzufügen

Medienanwendungen können benutzerdefinierte Aktionen definieren, z. B. „Daumen hoch“, „Gefällt mir“ oder „30 Sekunden zurückspulen“. Eine benutzerdefinierte Aktion sollte ein völlig neues Verhalten implementieren. Verwenden Sie keine benutzerdefinierte Aktion, um eine der in PlaybackStateCompat definierten Standardaktionen für die Wiedergabesteuerung zu ersetzen.

Benutzerdefinierte Aktionen mit addCustomAction() hinzufügen. Im folgenden Beispiel wird gezeigt, wie ein Steuerelement für eine „Mag ich“-Aktion hinzugefügt wird:

Kotlin

stateBuilder.addCustomAction(
        PlaybackStateCompat.CustomAction.Builder(
                CUSTOM_ACTION_THUMBS_UP,
                resources.getString(R.string.thumbs_up),
                thumbsUpIcon
        ).run {
            setExtras(customActionExtras)
            build()
        }
)

Java

stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
    CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
    .setExtras(customActionExtras)
    .build());

Ein vollständiges Beispiel findest du im Universal Music Player.

Sie reagieren auf die Aktion mit onCustomAction().

Kotlin

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_THUMBS_UP -> {
            ...
        }
    }
}

Java

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_THUMBS_UP.equals(action)) {
        ...
    }
}

Weitere Informationen findest du unter Universal Music Player.

Rückrufe für Mediensitzungen

Die wichtigsten Callback-Methoden für die Media Session sind onPlay(), onPause() und onStop(). Hier fügen Sie den Code hinzu, mit dem der Player gesteuert wird.

Da du den Callback der Sitzung zur Laufzeit (in onCreate()) instanziierst und festlegst, kann deine App alternative Callbacks definieren, die verschiedene Player verwenden, und je nach Gerät und Systemebene die entsprechende Kombination aus Callback und Player auswählen. Du kannst den Player ändern, ohne den Rest der App zu ändern. Du könntest beispielsweise ExoPlayer auf Android 4.1 (API-Level 16) oder höher und MediaPlayer auf früheren Systemen verwenden.

Neben der Steuerung des Players und der Verwaltung der Statusübergänge der Mediensitzung können Sie mit Callbacks auch Funktionen Ihrer App aktivieren und deaktivieren und die Interaktion mit anderen Apps und der Gerätehardware steuern. (Siehe Audioausgabe steuern).

Die Implementierung der Callback-Methoden für Mediensitzungen hängt von der Struktur deiner App ab. Auf den separaten Seiten, auf denen die Verwendung von Callbacks in Audio-Apps und Video-Apps beschrieben wird, wird auch erläutert, wie die Callbacks für die jeweilige App-Art implementiert werden sollten.