Mediensitzung verwenden

Mediensitzungen bieten eine universelle Art der Interaktion mit einem Audio- oder Videoplayer. Wenn Android darüber informiert wird, dass in einer App Medien abgespielt werden, können Wiedergabesteuerungen an die App delegiert werden. Durch die Integration in die Mediensitzung kann eine App die Medienwiedergabe extern bewerben und Wiedergabebefehle von externen Quellen empfangen. Das können physische Tasten (z. B. die Wiedergabetaste an einem Headset oder die Fernbedienung eines Fernsehers) oder indirekte Befehle (z. B. eine Anweisung für eine Pause an Google Assistant) sein. Die Mediensitzung delegiert diese Befehle dann an die Anwendung, die sie auf den Mediaplayer anwendet, von dem der Ursprung der Befehle transparent ist.

Eine Mediensitzung befindet sich neben dem von ihr verwalteten Player. Sie sollten eine Mediensitzung in der Methode onCreate() der Aktivität oder des Dienstes erstellen und initialisieren, zu der die Mediensitzung und der zugehörige Player gehören.

Hinweis: Zum Schreiben einer Medien-App empfiehlt es sich, die media-compat-Bibliothek zu verwenden. Auf dieser Seite bezeichnet der Begriff "Mediensitzung" eine Instanz von MediaSessionCompat und "Medien-Controller" eine Instanz von MediaControllerCompat.

Mediensitzung initialisieren

Eine neu erstellte Mediensitzung hat keine Funktionen. Sie müssen die Sitzung initialisieren, indem Sie die folgenden Schritte ausführen:

• Flags festlegen, damit die Mediensitzung Callbacks von Mediencontrollern und Medienschaltflächen erhalten kann.
• Erstellen und initialisieren Sie eine Instanz von PlaybackStateCompat und weisen Sie sie der Sitzung zu. Da sich der Wiedergabestatus während der Sitzung ändert, empfehlen wir, das 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 weiter unten).

Sie sollten eine Mediensitzung in der Methode onCreate() der Aktivität oder des Dienstes, zu dem die Sitzung gehört, erstellen und initialisieren.

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

Hinweis :Bei der Einbindung der ExoPlayer MediaSession-Erweiterung müssen Sie keine eigene MediaSessionCompat.Callback implementieren. MediaSessionConnector ordnet den Player-Status der Mediensitzung zu und delegiert die von der Mediensitzung empfangenen Ereignisse.

Wiedergabestatus und Metadaten beibehalten

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

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

• Der Transportstatus (z. B. ob der Player eine Wiedergabe ausführt/puffert/puffert, siehe getState())
• Ein Fehlercode und optional eine Fehlermeldung, falls zutreffend. Weitere Informationen finden Sie unter getErrorCode() und im Abschnitt Status und Fehler unten.
• Die Position des Spielers
• Die gültigen Controller-Aktionen, die im aktuellen Status verarbeitet werden können

Die Klasse MediaMetadataCompat beschreibt das wiedergegebene Material:

• Name des Künstlers, Albums und Titels
• Die Titeldauer
• Albumcover zur Anzeige auf dem Sperrbildschirm. Das Bild ist eine Bitmap mit einer maximalen Größe von 320 × 320 dp. Wenn sie größer ist, wird sie verkleinert.
• Eine Instanz von ContentUris, die auf eine größere Version der Grafik 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, müssen Sie für jede Klasse den entsprechenden Builder (PlaybackStateCompat.Builder() oder MediaMetadataCompat.Builder()) verwenden und dann die neue Instanz durch Aufrufen von setPlaybackState() oder setMetaData() an die Mediensitzung übergeben. Um den gesamten Arbeitsspeicherverbrauch durch diese häufigen Vorgänge zu reduzieren, empfiehlt es sich, die Builder einmal zu erstellen und während der gesamten Lebensdauer der Sitzung wiederzuverwenden.

Status und Fehler

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

Wenn die Wiedergabe unterbrochen wird, sollte ein schwerwiegender Fehler auftreten: Setzen Sie den Transportstatus auf STATE_ERROR und geben Sie einen zugehörigen Fehler mit setErrorMessage(int, CharSequence) an. Solange die Wiedergabe durch den Fehler blockiert wird, sollte PlaybackState weiterhin STATE_ERROR und den Fehler melden.

Ein nicht schwerwiegender Fehler tritt auf, wenn Ihre App eine Anfrage nicht verarbeiten kann, aber weiterspielen kann: Der Transport bleibt in einem „normalen“ Zustand (z. B. STATE_PLAYING), aber PlaybackState enthält einen Fehlercode. Wenn beispielsweise der letzte Titel wiedergegeben wird und der Nutzer anfordert, zum nächsten Titel zu springen, kann die Wiedergabe fortgesetzt werden. Sie sollten jedoch einen neuen PlaybackState mit dem Fehlercode ERROR_CODE_END_OF_QUEUE erstellen und dann setPlaybackState() aufrufen. An die Sitzung angehängte Mediencontroller erhalten den Callback onPlaybackStateChanged() und erklären dem Nutzer, was passiert ist. Ein nicht schwerwiegender Fehler sollte nur einmal gemeldet werden, wenn er auftritt. Bei der nächsten Aktualisierung der Sitzung wird der PlaybackState nicht noch einmal mit dem gleichen nicht schwerwiegenden Fehler zurückgegeben (es sei denn, der Fehler trat als Antwort auf eine neue Anfrage auf).

Sperrbildschirm bei 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 Mediensteuerelemente und Artwork angezeigt werden. Das Verhalten variiert je nach Android-Version.

Albumcover

Unter Android 4.0 (API-Level 14) bis Android 10 (API-Level 29) wird im Hintergrund des Sperrbildschirms Ihr Albumcover angezeigt. Dies gilt jedoch nur, wenn die Metadaten der Mediensitzung eine Hintergrund-Bitmap enthalten.

Steuerelemente für Verkehrsmittel

Unter Android 4.0 (API-Level 14) bis Android 4.4 (API-Level 19): Wenn eine Mediensitzung aktiv ist und die Metadaten der Mediensitzung eine Hintergrund-Bitmap enthalten, werden auf dem Sperrbildschirm automatisch die Transportsteuerung angezeigt.

Ab Android 5.0 (API-Level 21) bietet das System keine Transportsteuerung auf dem Sperrbildschirm. Stattdessen sollten Sie eine MediaStyle-Benachrichtigung verwenden, um die Transportsteuerung anzuzeigen.

Benutzerdefinierte Aktionen hinzufügen

Medienanwendungen können benutzerdefinierte Aktionen definieren, z. B. „Mag ich“, „Mag ich“ oder 30 Sekunden zurückspulen. Mit einer benutzerdefinierten Aktion sollte ein völlig neues Verhalten implementiert werden. Verwende keine benutzerdefinierte Aktion, um eine der in WiedergabeStateCompat definierten Standardaktionen der Transportsteuerung zu ersetzen.

Benutzerdefinierte Aktionen mit addCustomAction() hinzufügen. Das folgende Beispiel zeigt, wie Sie ein Steuerelement für eine „Mag ich“-Aktion hinzufügen:

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 unter Universal Music Player.

Sie antworten 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 finden Sie unter Universal Music Player.

Rückrufe für Mediensitzungen

Die wichtigsten Callback-Methoden für Mediensitzungen sind onPlay(), onPause() und onStop(). Hier fügst du den Code zur Steuerung deines Players hinzu.

Da Sie den Callback der Sitzung zur Laufzeit (in onCreate()) instanziieren und festlegen, kann Ihre App alternative Callbacks definieren, die unterschiedliche Player verwenden, und je nach Gerät und/oder Systemebene die entsprechende Callback-/Spieler-Kombination auswählen. Sie können den Player ändern, ohne den Rest der App zu ändern. Beispielsweise können Sie ExoPlayer verwenden, wenn Sie Android 4.1 (API-Level 16) oder höher verwenden, und MediaPlayer auf älteren Systemen verwenden.

Callbacks steuern nicht nur den Player und die Statusübergänge der Mediensitzung, sondern aktivieren und deaktivieren auch Funktionen Ihrer App und steuern die Interaktion mit anderen Apps und der Gerätehardware. (siehe Audioausgabe steuern).

Die Implementierung der Callback-Methoden für Mediensitzungen hängt von der Struktur Ihrer Anwendung ab. Die Verwendung von Callbacks in Audio-Apps und Video-Apps wird auf den separaten Seiten beschrieben.