MediaSession.setActionHandler() — Methode · JavaScript-Referenz

Signatur

MediaSession.prototype.setActionHandler(type, callback)

Beschreibung

Mit navigator.mediaSession.setActionHandler() verbindest du die Mediensteuerung des Betriebssystems und Browsers mit deiner Web-App. Dazu zählen Medientasten auf der Tastatur, Sperrbildschirm-Steuerung auf Mobilgeräten, Bluetooth-Kopfhörer, Benachrichtigungen und die Mediensteuerung im Browser. Löst der Nutzer eine dieser Aktionen aus, ruft der Browser deinen Handler auf, statt ein Standardverhalten auszuführen.

Für jeden Aktionstyp gibt es genau einen Handler. Ein erneuter Aufruf mit demselben type ersetzt den bisherigen Handler, mit null entfernst du ihn wieder. Registrierst du einen Handler, blendet der Browser meist die passende Schaltfläche ein, etwa „Nächster Titel“. Ohne Handler wird sie ausgeblendet oder der Browser greift auf sein Standardverhalten zurück (z. B. Wiedergabe/Pause des aktiven <audio>- bzw. <video>-Elements).

Der Handler bekommt ein Detail-Objekt mit mindestens der Eigenschaft action. Bei seekto kommen seekTime und optional fastSeek dazu, bei seekbackward/seekforward optional seekOffset in Sekunden. Diese Methode verwendet man meist zusammen mit navigator.mediaSession.metadata (Titel, Interpret, Cover) und setPositionState(), damit die Fortschrittsanzeige stimmt.

Gültige Aktionstypen sind unter anderem: play, pause, stop, seekbackward, seekforward, seekto, previoustrack, nexttrack, skipad sowie für Videokonferenzen togglemicrophone, togglecamera, hangup, dazu previousslide/nextslide und enterpictureinpicture.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name der Medienaktion, z. B. `"play"`, `"pause"`, `"seekto"`, `"nexttrack"`. Kennt der Browser den Typ nicht, wird ein `TypeError` geworfen.
$callback Pflicht	((details: MediaSessionActionDetails) => void) \| null		Funktion, die beim Auslösen der Aktion aufgerufen wird. Sie erhält ein Objekt mit `action` und je nach Typ `seekTime`, `seekOffset` oder `fastSeek`. Mit `null` wird der Handler entfernt.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Grundlegende Wiedergabesteuerung für einen Audio-Player

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

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

  navigator.mediaSession.setActionHandler('play', async () => {
    await audio.play();
    navigator.mediaSession.playbackState = 'playing';
  });

  navigator.mediaSession.setActionHandler('pause', () => {
    audio.pause();
    navigator.mediaSession.playbackState = 'paused';
  });
}

Spulen mit seekto, seekbackward und seekforward

const audio = document.querySelector('audio');
const defaultSkip = 10; // Sekunden

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

navigator.mediaSession.setActionHandler('seekbackward', (details) => {
  audio.currentTime = Math.max(audio.currentTime - (details.seekOffset ?? defaultSkip), 0);
  updatePosition();
});

navigator.mediaSession.setActionHandler('seekforward', (details) => {
  audio.currentTime = Math.min(audio.currentTime + (details.seekOffset ?? defaultSkip), audio.duration);
  updatePosition();
});

navigator.mediaSession.setActionHandler('seekto', (details) => {
  if (details.fastSeek && 'fastSeek' in audio) {
    audio.fastSeek(details.seekTime);
  } else {
    audio.currentTime = details.seekTime;
  }
  updatePosition();
});

Playlist-Navigation und sicheres Registrieren nicht unterstützter Aktionen

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

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

const handlers = [
  ['previoustrack', () => playTrack(index - 1)],
  ['nexttrack', () => playTrack(index + 1)],
  ['stop', () => { audio.pause(); audio.currentTime = 0; }],
  ['skipad', () => console.log('Werbung übersprungen')]
];

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

// Beim letzten Titel die Schaltfläche "Weiter" ausblenden:
// navigator.mediaSession.setActionHandler('nexttrack', null);

Aktion "skipad" wird nicht unterstützt. (nur in Browsern ohne skipad-Unterstützung)

// Wichtig · Fallstricke

Unbekannte Aktionstypen werfen einen TypeError. Die unterstützten Aktionen unterscheiden sich je nach Browser (z. B. skipad, togglecamera, enterpictureinpicture). Registriere sie deshalb einzeln in einem try...catch.
Prüfe die Unterstützung vorher mit 'mediaSession' in navigator. Die API ist nur in sicheren Kontexten (HTTPS) zuverlässig verfügbar.
Die Steuerung erscheint meist erst, wenn tatsächlich Medien abgespielt werden, oft nur nach einer Nutzerinteraktion wegen der Autoplay-Richtlinien. Ein registrierter Handler allein blendet noch keine Bedienelemente ein.
Pro Aktion gibt es nur einen Handler. Ein neuer Aufruf überschreibt den alten, anders als bei addEventListener.
Setze nach eigenen Wiedergabeänderungen playbackState und setPositionState(), sonst passt die System-Anzeige nicht zum echten Zustand.
Auf iOS/Safari werden seekbackward/seekforward und previoustrack/nexttrack teilweise gegenseitig ausgeblendet. Es werden also nicht alle registrierten Aktionen gleichzeitig angezeigt.

Siehe auch

MediaSession.setMicrophoneActive() MediaSession.setPositionState() MediaSession.setCameraActive() MediaSession.setScreenshareActive() MediaKeySession.close()