Diese Seite wurde von der Cloud Translation API übersetzt.

Medienbenachrichtigungen und Wiedergabesteuerung mit der Media Session API anpassen

Hier erfahren Sie unter anderem, wie Sie Hardware-Medientasten einbinden und Medienbenachrichtigungen anpassen.

François Beaufort

GitHub

Die Media Session API wurde eingeführt, damit Nutzer wissen, was gerade in ihrem Browser abgespielt wird, und sie steuern können, ohne zu der Seite zurückzukehren, auf der sie gestartet wurde. Webentwickler können dies durch Metadaten in benutzerdefinierten Medienbenachrichtigungen, Medienereignissen (z. B. Wiedergabe, Pause, Suche, Trackänderungen und Videokonferenzen wie Stummschalten/Lautschalten des Mikrofons, Ein-/Ausschalten der Kamera und Auflegen) anpassen. Diese Anpassungen sind in verschiedenen Kontexten verfügbar, z. B. in Medien-Hubs auf Desktop-Computern, Medienbenachrichtigungen auf Mobilgeräten und sogar auf Wearable-Geräten. Diese Anpassungen werden in diesem Artikel beschrieben.

Screenshots der Kontexte von Mediensitzungen. — Media Hub auf dem Computer, Medienbenachrichtigungen auf Mobilgeräten und auf einem Wearable-Gerät

Informationen zur Media Session API

Die Media Session API bietet mehrere Vorteile und Funktionen:

Hardware-Medientasten werden unterstützt.
Medienbenachrichtigungen werden auf Mobilgeräten, Computern und gekoppelten Wearable-Geräten angepasst.
Der Media-Hub ist auf Computern verfügbar.
Die Mediensteuerung auf dem Sperrbildschirm sind unter ChromeOS und auf Mobilgeräten verfügbar.
Die Bild-im-Bild-Fenstersteuerung ist für die Audiowiedergabe, für Videokonferenzen und für die Präsentation von Folien verfügbar.
Assistant-Integration auf Mobilgeräten ist verfügbar.

Unterstützte Browser

Quelle

Einige Beispiele veranschaulichen einige dieser Punkte.

Beispiel 1:Wenn Nutzer die Medientaste „Nächster Titel“ ihrer Tastatur drücken, können Webentwickler diese Nutzeraktion ausführen, unabhängig davon, ob der Browser im Vordergrund oder im Hintergrund ausgeführt wird.

Beispiel 2:Wenn sich Nutzer einen Podcast im Web anhören, während ihr Gerätebildschirm gesperrt ist, können sie weiterhin in den Mediensteuerelementen auf dem Sperrbildschirm auf das Symbol „Zurückspulen“ tippen. Webentwickler können die Wiedergabezeit dann um einige Sekunden zurückspulen.

Beispiel 3:Wenn Nutzer Tabs haben, auf denen Audioinhalte wiedergegeben werden, können sie die Wiedergabe über den Media Hub auf dem Computer ganz einfach beenden, damit Webentwickler ihren Status löschen können.

Beispiel 4:Wenn ein Nutzer an einem Videoanruf teilnimmt, kann er im Bild-im-Bild-Fenster das Mikrofon ein-/ausschalten, damit die Website keine Mikrofondaten erhält.

Dies erfolgt über zwei verschiedene Schnittstellen: die MediaSession-Schnittstelle und die MediaMetadata-Schnittstelle. Mit der ersten können Nutzende die Wiedergabe steuern. Die zweite ist, wie Sie MediaSession mitteilen, was kontrolliert werden soll.

Die folgende Abbildung zeigt, wie sich diese Schnittstellen auf bestimmte Mediensteuerelemente beziehen, in diesem Fall eine Medienbenachrichtigung auf einem Mobilgerät.

Abbildung der Benutzeroberflächen von Mediensitzungen — Aufbau einer Medienbenachrichtigung auf Mobilgeräten

Nutzer darüber informieren, was gerade läuft

Wenn eine Website Audio- oder Videoinhalte wiedergibt, erhalten Nutzer automatisch Medienbenachrichtigungen entweder in der Benachrichtigungsleiste auf Mobilgeräten oder im Media Hub auf dem Computer. Der Browser versucht, die passenden Informationen anzuzeigen. Dazu werden der Titel des Dokuments und das größte verfügbare Symbolbild verwendet. Mit der Media Session API ist es möglich, die Medienbenachrichtigung mit umfassenderen Medienmetadaten wie Titel, Künstlername, Albumname und Artwork anzupassen (siehe unten).

Chrome fordert einen „vollständigen“ Audiofokus an, um Medienbenachrichtigungen nur dann anzuzeigen, wenn die Mediendauer mindestens 5 Sekunden beträgt. Dadurch wird sichergestellt, dass bei Nebengeräuschen wie Dingen keine Benachrichtigungen angezeigt werden.

// After media (video or audio) starts playing
await document.querySelector("video").play();

if ("mediaSession" in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Never Gonna Give You Up',
    artist: 'Rick Astley',
    album: 'Whenever You Need Somebody',
    artwork: [
      { src: 'https://via.placeholder.com/96',   sizes: '96x96',   type: 'image/png' },
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/192', sizes: '192x192', type: 'image/png' },
      { src: 'https://via.placeholder.com/256', sizes: '256x256', type: 'image/png' },
      { src: 'https://via.placeholder.com/384', sizes: '384x384', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  });

  // TODO: Update playback state.
}

Nach dem Ende der Wiedergabe muss die Mediensitzung nicht mehr "freigegeben" werden, da die Benachrichtigung automatisch ausgeblendet wird. Denken Sie daran, dass navigator.mediaSession.metadata verwendet wird, wenn die nächste Wiedergabe beginnt. Aus diesem Grund ist es wichtig, sie zu aktualisieren, wenn sich die Medienwiedergabequelle ändert, damit relevante Informationen in der Medienbenachrichtigung angezeigt werden.

Bei den Medienmetadaten gibt es einiges zu beachten.

Das Array des Benachrichtigungs-Artwork unterstützt Blob-URLs und Daten-URLs.
Wenn kein Artwork definiert wurde und ein Symbolbild (angegeben durch <link rel=icon>) in der gewünschten Größe vorhanden ist, wird es in Medienbenachrichtigungen verwendet.
Die Zielgröße für das Artwork für Benachrichtigungen in Chrome für Android ist 512x512. Bei Low-End-Geräten ist es 256x256.
Das Attribut title des Media-HTML-Elements wird im macOS-Widget „Now Playing“ verwendet.
Wenn die Medienressource eingebettet ist (z. B. in einen iFrame), müssen die Informationen zur Media Session API aus dem eingebetteten Kontext festgelegt werden. Siehe Snippet unten.

<iframe id="iframe">
  <video>...</video>
</iframe>
<script>
  iframe.contentWindow.navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Never Gonna Give You Up',
    ...
  });
</script>

Wiedergabe durch Nutzer steuern

Eine Mediensitzungsaktion ist eine Aktion (z. B. „Wiedergabe“ oder „Pause“), die eine Website für Nutzer ausführen kann, wenn sie mit der aktuellen Medienwiedergabe interagieren. Aktionen sind Analog zu Ereignissen und funktionieren ähnlich wie Ereignisse. Wie Ereignisse werden auch Aktionen implementiert, indem Handler für ein entsprechendes Objekt festgelegt werden, in diesem Fall eine Instanz von MediaSession. Einige Aktionen werden ausgelöst, wenn Nutzer Tasten von einem Headset, einem anderen Remote-Gerät oder einer Tastatur drücken oder mit einer Medienbenachrichtigung interagieren.

Screenshot einer Medienbenachrichtigung in Windows 10. — Benutzerdefinierte Medienbenachrichtigungen unter Windows 10.

Da einige Aktionen von Mediensitzungen möglicherweise nicht unterstützt werden, wird empfohlen, beim Festlegen einen try…catch-Block zu verwenden.

const actionHandlers = [
  ['play',          () => { /* ... */ }],
  ['pause',         () => { /* ... */ }],
  ['previoustrack', () => { /* ... */ }],
  ['nexttrack',     () => { /* ... */ }],
  ['stop',          () => { /* ... */ }],
  ['seekbackward',  (details) => { /* ... */ }],
  ['seekforward',   (details) => { /* ... */ }],
  ['seekto',        (details) => { /* ... */ }],
  /* Video conferencing actions */
  ['togglemicrophone', () => { /* ... */ }],
  ['togglecamera',     () => { /* ... */ }],
  ['hangup',           () => { /* ... */ }],
  /* Presenting slides actions */
  ['previousslide', () => { /* ... */ }],
  ['nextslide',     () => { /* ... */ }],
];

for (const [action, handler] of actionHandlers) {
  try {
    navigator.mediaSession.setActionHandler(action, handler);
  } catch (error) {
    console.log(`The media session action "${action}" is not supported yet.`);
  }
}

Das Aufheben der Festlegung eines Action-Handlers für Mediensitzungen ist genauso einfach wie das Festlegen von null.

try {
  // Unset the "nexttrack" action handler at the end of a playlist.
  navigator.mediaSession.setActionHandler('nexttrack', null);
} catch (error) {
  console.log(`The media session action "nexttrack" is not supported yet.`);
}

Nach der Einrichtung bleiben Aktions-Handler für Mediensitzungen bei der Medienwiedergabe erhalten. Dies ähnelt dem Muster des Event-Listeners, außer dass die Verarbeitung eines Ereignisses bedeutet, dass der Browser kein Standardverhalten mehr ausführt und dies als Signal dafür verwendet, dass die Website die Medienaktion unterstützt. Daher werden Steuerelemente für Medienaktionen nur angezeigt, wenn der richtige Aktions-Handler festgelegt ist.

Screenshot des Widgets „Now Playing“ in macOS Big Sur. — „Now Playing“-Widget in macOS Big Sur.

Wiedergabe / Pause

Die Aktion "play" gibt an, dass der Nutzer die Medienwiedergabe fortsetzen möchte, während "pause" darauf hinweist, sie vorübergehend anzuhalten.

Das Symbol „Wiedergabe/Pause“ wird immer in Medienbenachrichtigungen angezeigt und die zugehörigen Medienereignisse werden automatisch vom Browser verarbeitet. Um das Standardverhalten zu überschreiben, verwenden Sie wie unten gezeigt die Medienaktionen „Wiedergabe“ und „Pause“.

Der Browser kann beispielsweise davon ausgehen, dass beim Suchen oder Laden keine Medien von einer Website abgespielt werden. In diesem Fall können Sie dieses Verhalten überschreiben, indem Sie navigator.mediaSession.playbackState auf "playing" oder "paused" setzen, damit die Website-UI mit den Steuerelementen für Medienbenachrichtigungen synchron bleibt.

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

navigator.mediaSession.setActionHandler('play', async () => {
  // Resume playback
  await video.play();
});

navigator.mediaSession.setActionHandler('pause', () => {
  // Pause active playback
  video.pause();
});

video.addEventListener('play', () => {
  navigator.mediaSession.playbackState = 'playing';
});

video.addEventListener('pause', () => {
  navigator.mediaSession.playbackState = 'paused';
});

Vorheriger Titel

Die Aktion "previoustrack" gibt an, dass der Nutzer entweder die aktuelle Medienwiedergabe von Anfang an starten möchte, wenn die Medienwiedergabe einen Anfang hat, oder zum vorherigen Element in der Playlist wechseln möchte, wenn die Medienwiedergabe das Konzept einer Playlist hat.

navigator.mediaSession.setActionHandler('previoustrack', () => {
  // Play previous track.
});

Nächster Titel

Die Aktion "nexttrack" gibt an, dass der Nutzer die Medienwiedergabe zum nächsten Element in der Playlist verschieben möchte, wenn die Medienwiedergabe das Konzept einer Playlist hat.

navigator.mediaSession.setActionHandler('nexttrack', () => {
  // Play next track.
});

Beenden

Die Aktion "stop" gibt an, dass der Nutzer die Medienwiedergabe beenden und den Status gegebenenfalls löschen möchte.

navigator.mediaSession.setActionHandler('stop', () => {
  // Stop playback and clear state if appropriate.
});

Vor-/Zurückspulen

Die Aktion "seekbackward" gibt an, dass der Nutzer die Medienwiedergabezeit um einen kurzen Zeitraum zurückversetzen möchte, während "seekforward" den Wunsch angibt, die Medienwiedergabezeit um einen kurzen Zeitraum nach vorne zu verschieben. In beiden Fällen bedeutet ein kurzer Zeitraum einige Sekunden.

Der Wert seekOffset im Aktions-Handler gibt die Zeit in Sekunden an, um die die Medienwiedergabezeit verschoben werden soll. Wenn sie nicht angegeben ist (z. B. undefined), sollten Sie eine sinnvolle Zeit verwenden (z. B. 10–30 Sekunden).

const video = document.querySelector('video');
const defaultSkipTime = 10; /* Time to skip in seconds by default */

navigator.mediaSession.setActionHandler('seekbackward', (details) => {
  const skipTime = details.seekOffset || defaultSkipTime;
  video.currentTime = Math.max(video.currentTime - skipTime, 0);
  // TODO: Update playback state.
});

navigator.mediaSession.setActionHandler('seekforward', (details) => {
  const skipTime = details.seekOffset || defaultSkipTime;
  video.currentTime = Math.min(video.currentTime + skipTime, video.duration);
  // TODO: Update playback state.
});

Zu einer bestimmten Zeit springen

Die Aktion "seekto" gibt an, dass der Nutzer die Medienwiedergabezeit auf einen bestimmten Zeitpunkt verschieben möchte.

Der Wert seekTime im Aktions-Handler gibt die Zeit in Sekunden an, auf die die Medienwiedergabezeit verschoben werden soll.

Der boolesche Wert fastSeek im Aktions-Handler ist „true“, wenn die Aktion im Rahmen einer Sequenz mehrmals aufgerufen wird und dies nicht der letzte Aufruf in dieser Sequenz ist.

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

navigator.mediaSession.setActionHandler('seekto', (details) => {
  if (details.fastSeek && 'fastSeek' in video) {
    // Only use fast seek if supported.
    video.fastSeek(details.seekTime);
    return;
  }
  video.currentTime = details.seekTime;
  // TODO: Update playback state.
});

Wiedergabeposition festlegen

Damit die Position der Medienwiedergabe in einer Benachrichtigung richtig angezeigt werden kann, müssen Sie lediglich den Positionsstatus zu einem geeigneten Zeitpunkt festlegen (siehe unten). Der Positionsstatus ist eine Kombination aus Medienwiedergaberate, Dauer und aktueller Zeit.

Screenshot der Mediensteuerelemente auf dem Sperrbildschirm in ChromeOS. — Mediensteuerelemente auf dem Sperrbildschirm unter ChromeOS

Die Dauer muss positiv sein. Die Position muss positiv und kleiner als die Dauer sein. Die Wiedergaberate muss größer als 0 sein.

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

function updatePositionState() {
  if ('setPositionState' in navigator.mediaSession) {
    navigator.mediaSession.setPositionState({
      duration: video.duration,
      playbackRate: video.playbackRate,
      position: video.currentTime,
    });
  }
}

// When video starts playing, update duration.
await video.play();
updatePositionState();

// When user wants to seek backward, update position.
navigator.mediaSession.setActionHandler('seekbackward', (details) => {
  /* ... */
  updatePositionState();
});

// When user wants to seek forward, update position.
navigator.mediaSession.setActionHandler('seekforward', (details) => {
  /* ... */
  updatePositionState();
});

// When user wants to seek to a specific time, update position.
navigator.mediaSession.setActionHandler('seekto', (details) => {
  /* ... */
  updatePositionState();
});

// When video playback rate changes, update position state.
video.addEventListener('ratechange', (event) => {
  updatePositionState();
});

Das Zurücksetzen des Positionsstatus ist so einfach wie das Festlegen auf null.

// Reset position state when media is reset.
navigator.mediaSession.setPositionState(null);

Aktionen für Videokonferenzen

Wenn der Nutzer seinen Videoanruf in einem Bild-im-Bild-Fenster platziert, werden im Browser möglicherweise Steuerelemente für das Mikrofon und die Kamera sowie zum Auflegen angezeigt. Wenn der Nutzer darauf klickt, werden sie von der Website über die unten aufgeführten Aktionen für Videokonferenzen verarbeitet. Ein Beispiel finden Sie unter Beispiel für Videokonferenzen.

Screenshot der Steuerelemente für Videokonferenzen in einem Bild-im-Bild-Fenster. — Steuerelemente für Videokonferenzen in einem Bild-im-Bild-Fenster

Mikrofon ein-/ausschalten

Die Aktion "togglemicrophone" gibt an, dass der Nutzer das Mikrofon stummschalten oder die Stummschaltung aufheben möchte. Die Methode setMicrophoneActive(isActive) teilt dem Browser mit, ob die Website das Mikrofon derzeit als aktiv betrachtet.

let isMicrophoneActive = false;

navigator.mediaSession.setActionHandler('togglemicrophone', () => {
  if (isMicrophoneActive) {
    // Mute the microphone.
  } else {
    // Unmute the microphone.
  }
  isMicrophoneActive = !isMicrophoneActive;
  navigator.mediaSession.setMicrophoneActive(isMicrophoneActive);
});

Kamera umschalten

Die Aktion "togglecamera" gibt an, dass der Nutzer die aktive Kamera ein- oder ausschalten möchte. Die Methode setCameraActive(isActive) gibt an, ob der Browser die Website als aktiv einstuft.

let isCameraActive = false;

navigator.mediaSession.setActionHandler('togglecamera', () => {
  if (isCameraActive) {
    // Disable the camera.
  } else {
    // Enable the camera.
  }
  isCameraActive = !isCameraActive;
  navigator.mediaSession.setCameraActive(isCameraActive);
});

Anruf beenden

Die Aktion "hangup" gibt an, dass der Nutzer einen Anruf beenden möchte.

navigator.mediaSession.setActionHandler('hangup', () => {
  // End the call.
});

Aktionen zum Einblenden von Folien

Wenn der Nutzer seine Präsentation in einem Bild-im-Bild-Fenster platziert, zeigt der Browser möglicherweise Steuerelemente zum Navigieren durch die Folien an. Wenn der Nutzer darauf klickt, werden sie von der Website über die Media Session API verarbeitet. Ein Beispiel finden Sie im Beispiel für die Präsentation von Folien.

Vorherige Folie

Die Aktion "previousslide" gibt an, dass der Nutzer bei der Präsentation zur vorherigen Folie zurückkehren möchte.

navigator.mediaSession.setActionHandler('previousslide', () => {
  // Show previous slide.
});

Unterstützte Browser

Nächste Folie

Die Aktion "nextslide" gibt an, dass der Nutzer bei der Präsentation zur nächsten Folie wechseln möchte.

navigator.mediaSession.setActionHandler('nextslide', () => {
  // Show next slide.
});

Unterstützte Browser

Samples

Sehen Sie sich einige Beispiele für Media Sessions mit der Blender Foundation und der Arbeit von Jan Morgenstern an.

Ein Screencast, der die Media Session API veranschaulicht.

Ressourcen

Spezifikation für die Mediensitzung: wicg.github.io/mediasession
Spezifikationsprobleme: github.com/WICG/mediasession/issues
Chrome-Programmfehler: crbug.com