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.
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, dasPlaybackStateCompat.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.
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.