Medienbenachrichtigungen und Wiedergabesteuerung mit der Media Session API anpassen

Unter anderem erfahren Sie, wie Sie die Integration mit Hardware-Medientasten und die Anpassung von Medienbenachrichtigungen vornehmen.

François Beaufort

Mit der Media Session API können Nutzer sehen, was gerade in ihrem Browser wiedergegeben wird, und die Wiedergabe steuern, ohne zur Seite zurückzukehren, auf der sie gestartet wurde. Webentwickler können diese Funktion durch Metadaten in benutzerdefinierten Medienbenachrichtigungen, Medienereignissen wie Wiedergabe, Pause, Suchen und Ändern der Tracks sowie Videokonferenzereignisse wie Mikrofon stummschalten/Stummschaltung aufheben, Kamera ein- und ausschalten und auflegen. Diese Anpassungen sind in verschiedenen Kontexten verfügbar, z. B. in Mediahubs auf Computern, in Medienbenachrichtigungen auf Mobilgeräten und sogar auf Wearables. Diese Anpassungen werden in diesem Artikel beschrieben.

Media Session API

Die Media Session API bietet mehrere Vorteile und Funktionen:

• Hardware-Medientasten werden unterstützt.
• Medienbenachrichtigungen können auf Mobilgeräten, Computern und gekoppelten Wearables angepasst werden.
• Der Media Hub ist auf Computern verfügbar.
• Die Mediensteuerung auf dem Sperrbildschirm ist auf ChromeOS und auf Mobilgeräten verfügbar.
• Steuerelemente für das Bild-im-Bild-Fenster sind für die Audiowiedergabe, Videokonferenzen und Präsentationen verfügbar.
• Die Assistant-Integration ist auf Mobilgeräten verfügbar.

Einige dieser Punkte werden anhand von Beispielen veranschaulicht.

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

Beispiel 2:Wenn sich Nutzer einen Podcast im Web anhören, während ihr Gerätebildschirm gesperrt ist, können sie dennoch in den Mediensteuerelementen des Sperrbildschirms auf das Symbol „Zurückspringen“ klicken, damit Webentwickler die Wiedergabezeit um einige Sekunden zurückstellen.

Beispiel 3: Wenn Nutzer Tabs haben, auf denen Audio wiedergegeben wird, können sie die Wiedergabe auf dem Computer ganz einfach über den Mediahub beenden, damit Webentwickler den Status löschen können.

Beispiel 4:Wenn sich Nutzer in einem Videoanruf befinden, können sie im Bild-im-Bild-Fenster die Ein/Aus-Schaltfläche zum Ein-/Ausschalten des Mikrofons drücken, um zu verhindern, dass die Website Mikrofondaten empfängt.

Dies geschieht über zwei verschiedene Schnittstellen: die MediaSession- und die MediaMetadata-Schnittstelle. Mit der ersten können Nutzer die Wiedergabe steuern. Zweitens: Sie müssen MediaSession mitteilen, was gesteuert werden soll.

Das Bild unten zeigt zur Veranschaulichung, wie diese Oberflächen sich auf bestimmte Mediensteuerungen beziehen, in diesem Fall eine Medienbenachrichtigung auf einem Mobilgerät.

Nutzer darüber informieren, was gerade gespielt wird

Wenn auf einer Website Audio oder Video abgespielt wird, erhalten Nutzer automatisch Medienbenachrichtigungen, entweder im Benachrichtigungs-Tray auf Mobilgeräten oder im Medienhub auf dem Computer. Der Browser versucht, geeignete Informationen anzuzeigen, indem er den Titel des Dokuments und das größte Symbolbild verwendet, das er finden kann. Mit der Media Session API ist es möglich, die Medienbenachrichtigung mit umfangreicheren Medienmetadaten wie Titel, Künstlername, Albumname und Artwork anzupassen (siehe unten).

Chrome fordert den „vollständigen“ Audiofokus an, um nur dann Medienbenachrichtigungen anzuzeigen, wenn die Mediendauer mindestens 5 Sekunden beträgt. So werden Benachrichtigungen nicht bei nebensächlichen Geräuschen wie Klingeln angezeigt.

// 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.
}

Wenn die Wiedergabe endet, müssen Sie die Mediensitzung nicht „freigeben“, da die Benachrichtigung automatisch verschwindet. Beachte aber, dass navigator.mediaSession.metadata verwendet wird, wenn die nächste Wiedergabe beginnt. Daher ist es wichtig, sie zu aktualisieren, wenn sich die Quelle der Medienwiedergabe ändert, damit in der Medienbenachrichtigung relevante Informationen angezeigt werden.

Bei den Medienmetadaten gibt es einige Dinge zu beachten.

• Das Artwork-Array für Benachrichtigungen unterstützt Blob-URLs und Daten-URLs.
• Wenn kein Artwork definiert ist und es ein Symbolbild (mit <link rel=icon> angegeben) in der gewünschten Größe gibt, wird es in Medienbenachrichtigungen verwendet.
• Die Zielgröße für das Artwork von Benachrichtigungen in Chrome für Android beträgt 512x512. Bei Low-End-Geräten ist es 256x256.
• Das title-Attribut des HTML-Medienelements wird im macOS-Widget „Aktuell wiedergegeben“ verwendet.
• Wenn die Medienressource eingebettet ist (z. B. in einem iFrame), müssen die Informationen der 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>

Du kannst den Medienmetadaten auch Informationen zu einzelnen Kapiteln hinzufügen, z. B. den Titel des Abschnitts, seinen Zeitstempel und ein Screenshot-Bild. So können Nutzer die Inhalte der Medien aufrufen.

navigator.mediaSession.metadata = new MediaMetadata({
  // title, artist, album, artwork, ...
  chapterInfo: [{
    title: 'Chapter 1',
    startTime: 0,
    artwork: [
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  }, {
    title: 'Chapter 2',
    startTime: 42,
    artwork: [
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  }]
});

Nutzern die Möglichkeit geben, die Wiedergabe zu 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 bei Ereignissen werden Aktionen implementiert, indem Handler für ein geeignetes 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.

Da einige Aktionen für 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 Deaktivieren eines Handlers für Mediensitzungen ist einfach, indem man ihn auf null setzt.

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 Festlegung bleiben Handler für Mediensitzungen-Aktionen während der Medienwiedergabe bestehen. Das ähnelt dem Ereignis-Listener-Muster, mit der Ausnahme, dass beim Bearbeiten eines Ereignisses das Standardverhalten des Browsers beendet wird und dies als Signal verwendet wird, dass die Website die Medienaktion unterstützt. Daher werden die Steuerelemente für Medienaktionen nur angezeigt, wenn der richtige Action-Handler festgelegt ist.

Wiedergabe/Pause

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

Das Symbol „Wiedergabe/Pause“ wird immer in einer Medienbenachrichtigung angezeigt und die zugehörigen Medienereignisse werden automatisch vom Browser verarbeitet. Wenn Sie das Standardverhalten überschreiben möchten, verarbeiten Sie die Medienaktionen „Wiedergabe“ und „Pause“ wie unten gezeigt.

Der Browser kann beispielsweise beim Suchen oder Laden einer Website davon ausgehen, dass keine Medien abgespielt werden. In diesem Fall kannst du dieses Verhalten überschreiben, indem du navigator.mediaSession.playbackState auf "playing" oder "paused" festlegst. So bleibt die Website-Benutzeroberfläche mit den Steuerelementen für Medienbenachrichtigungen synchronisiert.

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 vorn beginnen möchte, wenn die Medienwiedergabe einen Anfang hat, oder zum vorherigen Element in der Playlist wechseln möchte, wenn die Medienwiedergabe eine 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 springen möchte, sofern die Medienwiedergabe eine Playlist enthält.

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

Beenden

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

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

Vorwärts / rückwärts springen

Die Aktion "seekbackward" gibt an, dass der Nutzer die Medienwiedergabezeit um einen kurzen Zeitraum zurückspulen möchte, während "seekforward" angibt, dass er die Medienwiedergabezeit um einen kurzen Zeitraum vorspulen möchte. In beiden Fällen bedeutet „kurze Zeit“ einige Sekunden.

Der im Aktions-Handler angegebene Wert seekOffset gibt die Zeit in Sekunden an, um die die Medienwiedergabezeit verschoben wird. Ist kein Wert angegeben (z. B. undefined), müssen Sie eine vernünftige 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 eine bestimmte Zeit verschieben möchte.

Der im Action-Handler angegebene Wert für seekTime ist die Zeit in Sekunden, zu der die Medienwiedergabe fortgesetzt werden soll.

Der im Action-Handler angegebene boolesche Wert fastSeek ist „wahr“, wenn die Aktion mehrmals als Teil einer Sequenz 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

Um die Position der Medienwiedergabe in einer Benachrichtigung richtig anzuzeigen, müssen Sie wie unten gezeigt den Positionsstatus zu einem geeigneten Zeitpunkt festlegen. Der Positionierungsstatus ist eine Kombination aus der Wiedergabegeschwindigkeit, der Dauer und der aktuellen Zeit.

Die Dauer muss angegeben und positiv sein. Die Position muss positiv sein und kleiner als die Dauer. 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();
});

Sie können den Positionsstatus ganz einfach auf null zurücksetzen.

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

Aktionen für Videokonferenzen

Wenn der Nutzer den Videoanruf in einem Bild-im-Bild-Fenster öffnet, werden im Browser möglicherweise Steuerelemente für das Mikrofon und die Kamera sowie für das Auflegen angezeigt. Wenn der Nutzer darauf klickt, werden die Aktionen für Videokonferenzen unten auf der Website ausgeführt. Ein Beispiel finden Sie im Beispiel für Videokonferenzen.

Mikrofon ein-/ausschalten

Die Aktion "togglemicrophone" gibt an, dass der Nutzer das Mikrofon stummschalten oder die Stummschaltung aufheben möchte. Die setMicrophoneActive(isActive)-Methode 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 aktivieren oder deaktivieren

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

let isCameraActive = false;

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

Beenden

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

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

Aktionen für die Präsentation von Folien

Wenn der Nutzer seine Folienpräsentation in einem Bild-im-Bild-Fenster öffnet, werden im Browser möglicherweise Steuerelemente zum Wechseln der Folien angezeigt. 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.

Zurück

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

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

Weiter

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

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

Beispiele

Hier findest du einige Media Session-Beispiele mit der Blender Foundation und der Arbeit von Jan Morgenstern.

Ressourcen

• Media Session Spec: wicg.github.io/mediasession
• Probleme mit der Spezifikation: github.com/WICG/mediasession/issues
• Chrome-Fehler: crbug.com