Signatur
Beschreibung
Die Eigenschaft playbackState der MediaSession-Schnittstelle teilt dem Browser und dem Betriebssystem mit, ob die Medienwiedergabe der Seite gerade läuft oder pausiert ist. Anhand dieses Werts stellen die Mediensteuerungen des Systems (Sperrbildschirm, Benachrichtigungen, Media-Hub, Hardware-Medientasten) das passende Symbol dar, zum Beispiel Play oder Pause.
Zulässige Werte sind:
"none": Der Browser leitet den Zustand selbst ab, meist aus dem Zustand der<audio>- bzw.<video>-Elemente auf der Seite. Das ist der Standardwert."paused": Die Wiedergabe ist pausiert und kann fortgesetzt werden."playing": Die Wiedergabe läuft gerade.
Du brauchst diese Eigenschaft vor allem dann, wenn der Browser den Zustand nicht zuverlässig selbst erkennen kann, etwa bei der Wiedergabe über die Web Audio API, bei eigenen Playern mit mehreren Medienelementen oder bei gestreamten Inhalten, die über MediaSource gepuffert werden. Setze den Wert dann immer mit, wenn du in deinen Aktions-Handlern (setActionHandler("play"), setActionHandler("pause")) die Wiedergabe startest oder anhältst.
Das Setzen von playbackState startet oder stoppt die Wiedergabe nicht. Die Eigenschaft beschreibt nur den Zustand für die Systemoberfläche. Um die eigentliche Wiedergabe kümmerst du dich selbst.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | "none" | "paused" | "playing" | "none" | Neuer Wiedergabezustand beim Schreiben der Eigenschaft. Ungültige Zeichenketten werden stillschweigend ignoriert und nicht übernommen. |
Rückgabewert
Beispiele
Zustand mit Play/Pause-Handlern synchron halten
const audio = document.querySelector('audio');
if ('mediaSession' in navigator) {
navigator.mediaSession.setActionHandler('play', async () => {
await audio.play();
navigator.mediaSession.playbackState = 'playing';
});
navigator.mediaSession.setActionHandler('pause', () => {
audio.pause();
navigator.mediaSession.playbackState = 'paused';
});
}Zustand automatisch aus Medien-Events ableiten
const video = document.querySelector('video');
const syncState = () => {
if (!('mediaSession' in navigator)) return;
navigator.mediaSession.playbackState = video.paused ? 'paused' : 'playing';
console.log('Zustand:', navigator.mediaSession.playbackState);
};
video.addEventListener('play', syncState);
video.addEventListener('pause', syncState);
video.addEventListener('ended', syncState);Web-Audio-Player ohne Medienelement
const ctx = new AudioContext();
const togglePlayback = async () => {
if (ctx.state === 'running') {
await ctx.suspend();
navigator.mediaSession.playbackState = 'paused';
} else {
await ctx.resume();
navigator.mediaSession.playbackState = 'playing';
}
console.log(navigator.mediaSession.playbackState);
};
navigator.mediaSession.setActionHandler('play', togglePlayback);
navigator.mediaSession.setActionHandler('pause', togglePlayback);
document.querySelector('#toggle').addEventListener('click', togglePlayback);Ungültige Werte werden ignoriert
navigator.mediaSession.playbackState = 'paused';
navigator.mediaSession.playbackState = 'stopped'; // kein gültiger Wert
console.log(navigator.mediaSession.playbackState);// Wichtig · Fallstricke
- Nur beschreibend: Wenn du
playbackStatesetzt, ändert sich die tatsächliche Wiedergabe nicht. Hältst du den Wert nicht aktuell, zeigen die Systemsteuerungen falsche Symbole an. - Ungültige Werte wie
"stopped"lösen keinen Fehler aus. Die Zuweisung wird einfach ignoriert. - Kein eigener Zustand für „beendet“: Wenn die Wiedergabe endet, setzt du am besten
"paused"oder"none". - Die Mediensteuerung des Systems erscheint meist erst, nachdem die Seite tatsächlich hörbare Medien abgespielt hat. Das reine Setzen von
"playing"reicht dafür nicht. - Kompatibilität: Unterstützt in Chromium-Browsern (ab Chrome 73), Firefox 82+ und Safari 15+. Prüfe die Verfügbarkeit mit
'mediaSession' in navigator. Die API ist nur in sicheren Kontexten (HTTPS) garantiert verfügbar. Wie der Zustand dargestellt wird, hängt von Plattform und Betriebssystem ab.