Navigator.mediaSession — Eigenschaft · JavaScript-Referenz

Signatur

get Navigator.mediaSession

Beschreibung

Die schreibgeschützte Eigenschaft navigator.mediaSession gibt das zum aktuellen Dokument gehörende MediaSession-Objekt zurück. Darüber teilt eine Web-Anwendung dem Browser und dem Betriebssystem mit, was gerade abgespielt wird (Titel, Interpret, Album, Cover) und wie die Wiedergabe gesteuert werden kann.

Der Browser verwendet diese Informationen für Mediensteuerungen außerhalb der Seite, zum Beispiel für Benachrichtigungen auf dem Sperrbildschirm von Android, das Mediensteuerungs-Overlay in Windows und macOS, Medientasten auf der Tastatur, Bluetooth-Kopfhörer oder die Smartwatch. Mit setActionHandler() legt man fest, was bei „Wiedergabe“, „Pause“, „Nächster Titel“, „Spulen“ usw. passieren soll.

Die wichtigsten Bestandteile des zurückgegebenen Objekts:

metadata – ein MediaMetadata-Objekt mit title, artist, album und artwork.
playbackState – "none", "paused" oder "playing".
setActionHandler(action, handler) – registriert oder entfernt (mit null) einen Handler für eine Medienaktion.
setPositionState(state) – meldet Dauer, Position und Wiedergabegeschwindigkeit für Fortschrittsbalken.

Die Eigenschaft ist vor allem für Musik-, Podcast- und Video-Player sinnvoll, die eigene Steuerungen implementieren oder Wiedergabelisten verwalten. Sie hat keine Parameter, da es sich um einen reinen Getter handelt.

Rückgabewert

Typ

MediaSession

Beschreibung

Das MediaSession-Objekt des aktuellen Dokuments. Es wird bei jedem Zugriff dasselbe Objekt zurückgegeben.

Beispiele

Metadaten für den aktuellen Titel setzen

const audio = document.querySelector('audio');

if ('mediaSession' in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Morgenrot',
    artist: 'Die Beispielband',
    album: 'Erste Schritte',
    artwork: [
      { src: '/cover-96.png', sizes: '96x96', type: 'image/png' },
      { src: '/cover-512.png', sizes: '512x512', type: 'image/png' }
    ]
  });
}

await audio.play();
console.log(navigator.mediaSession.metadata.title);

Morgenrot

Aktions-Handler für eine Wiedergabeliste

const audio = document.querySelector('audio');
const playlist = ['/a.mp3', '/b.mp3', '/c.mp3'];
let index = 0;

const loadTrack = async (i) => {
  index = (i + playlist.length) % playlist.length;
  audio.src = playlist[index];
  await audio.play();
};

const handlers = {
  play: () => audio.play(),
  pause: () => audio.pause(),
  previoustrack: () => loadTrack(index - 1),
  nexttrack: () => loadTrack(index + 1),
  seekbackward: (d) => { audio.currentTime -= d.seekOffset ?? 10; },
  seekforward: (d) => { audio.currentTime += d.seekOffset ?? 10; },
  seekto: (d) => { audio.currentTime = d.seekTime; }
};

for (const [action, handler] of Object.entries(handlers)) {
  try {
    navigator.mediaSession.setActionHandler(action, handler);
  } catch {
    console.warn(`Aktion "${action}" wird nicht unterstützt.`);
  }
}

Wiedergabestatus und Position synchronisieren

const video = document.querySelector('video');
const session = navigator.mediaSession;

const updatePosition = () => {
  if (!Number.isFinite(video.duration)) return;
  session.setPositionState({
    duration: video.duration,
    playbackRate: video.playbackRate,
    position: video.currentTime
  });
};

video.addEventListener('play', () => { session.playbackState = 'playing'; });
video.addEventListener('pause', () => { session.playbackState = 'paused'; });
video.addEventListener('loadedmetadata', updatePosition);
video.addEventListener('seeked', updatePosition);
video.addEventListener('ratechange', updatePosition);

Handler wieder entfernen

// Beim Verlassen des Players Steuerung zurücksetzen
const resetMediaSession = () => {
  const session = navigator.mediaSession;
  ['play', 'pause', 'nexttrack', 'previoustrack'].forEach((action) => {
    try { session.setActionHandler(action, null); } catch {}
  });
  session.metadata = null;
  session.playbackState = 'none';
};

resetMediaSession();
console.log(navigator.mediaSession.playbackState);

none

// Wichtig · Fallstricke

Feature-Erkennung: Vor der Nutzung immer mit 'mediaSession' in navigator prüfen. Ältere Browser (z. B. Safari vor 15, Firefox vor 82) kennen die API nicht.
Nicht unterstützte Aktionen: setActionHandler() wirft einen TypeError, wenn der Browser eine Aktion (z. B. "skipad", "togglemicrophone", "enterpictureinpicture") nicht kennt. Deshalb jede Registrierung in try…catch einschließen.
Nur bei aktiver Wiedergabe sichtbar: Die Systemsteuerung erscheint meist erst, wenn ein <audio>- oder <video>-Element tatsächlich hörbar abspielt; stumme oder sehr kurze Medien (unter ca. 5 Sekunden) werden in Chrome ignoriert.
Sicherer Kontext: In einigen Browsern ist die API nur über HTTPS verfügbar.
setPositionState() wirft einen Fehler, wenn position größer als duration ist oder duration negativ bzw. NaN ist – etwa bei Livestreams (Infinity ist erlaubt).
Cover-Bilder in artwork unterliegen den normalen Ladebeschränkungen (CORS, CSP img-src); bieten Sie mehrere Größen an, damit das System die passende auswählen kann.
playbackState ändert die tatsächliche Wiedergabe nicht, sondern informiert nur den Browser. Er sollte zu den Ereignissen des Medienelements passen.

Siehe auch

Navigator Navigator.activeVRDisplays Navigator.audioSession Navigator.mediaDevices Navigator.appVersion