Medienbenachrichtigungen und Wiedergabesteuerung mit der Media Session API anpassen

Integrieren von Hardware-Medientasten, Anpassen von Medienbenachrichtigungen und mehr

Die Media Session API wurde eingeführt, damit Nutzer wissen, was gerade in ihrem Browser abgespielt wird, und sie steuern können, ohne zur Seite zurückzukehren, auf der sie gestartet wurde. Webentwickler können dies über Metadaten in benutzerdefinierten Medienbenachrichtigungen, Medienereignissen wie Wiedergabe, Pause, Suche, Titelwechsel sowie Videokonferenzereignisse wie Mikrofon stummschalten/Stummschaltung aufheben, Kamera ein-/ausschalten und auflegen. Diese Anpassungen sind in verschiedenen Kontexten verfügbar, z. B. in Desktop-Media-Hubs, Medienbenachrichtigungen auf Mobilgeräten und sogar auf Wearable-Geräten. Diese Anpassungen werden in diesem Artikel näher erläutert.

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 ist unter ChromeOS und auf Mobilgeräten verfügbar.
• Die Bild-im-Bild-Fenster sind für die Audiowiedergabe, Videokonferenzen und Präsentationen verfügbar.
• Assistant-Integration auf Mobilgeräten verfügbar.

Einige Beispiele veranschaulichen einige dieser Punkte.

Beispiel 1:Wenn Nutzer die Medientaste „Nächster Titel“ auf 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 Nutzer sich einen Podcast im Web anhören, während der Bildschirm ihres Geräts gesperrt ist, können sie trotzdem in der Mediensteuerung auf dem Sperrbildschirm auf das Symbol „Zurückspulen“ tippen. So können Webentwickler die Wiedergabezeit um einige Sekunden zurückstellen.

Beispiel 3:Wenn Nutzer Tabs haben, auf denen Audioinhalte wiedergegeben werden, können sie die Wiedergabe im Media Hub auf dem Computer 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.

Das erfolgt über zwei verschiedene Schnittstellen: die MediaSession-Schnittstelle und die MediaMetadata-Schnittstelle. Mit dem ersten können Nutzende die Wiedergabe steuern. Im zweiten Schritt teilen Sie MediaSession mit, was kontrolliert werden soll.

In der folgenden Abbildung wird veranschaulicht, wie diese Schnittstellen mit bestimmten Mediensteuerelementen zusammenhängen, in diesem Fall eine Medienbenachrichtigung auf einem Mobilgerät.

Nutzer darüber informieren, was gerade läuft

Wenn auf einer Website Audio- oder Videoinhalte abgespielt werden, erhalten Nutzer automatisch Medienbenachrichtigungen, entweder in der Benachrichtigungsleiste auf Mobilgeräten oder im Media Hub auf Computern. Der Browser versucht, die passenden 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 einen „vollständigen“ Audiofokus an, damit Medienbenachrichtigungen nur dann angezeigt werden, wenn die Mediendauer mindestens 5 Sekunden beträgt. Dadurch wird sichergestellt, dass zufällige Geräusche wie Töne nicht als Benachrichtigung 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 „veröffentlicht“ werden, da die Benachrichtigung automatisch ausgeblendet wird. Denken Sie daran, dass navigator.mediaSession.metadata beim Start der nächsten Wiedergabe verwendet wird. Aus diesem Grund ist es wichtig, sie zu aktualisieren, wenn sich die Medienwiedergabequelle ändert, damit in der Medienbenachrichtigung relevante Informationen angezeigt werden.

Bei den Metadaten der Medien gibt es einiges zu beachten.

• Das Array der Artwork-Benachrichtigung unterstützt Blob-URLs und Daten-URLs.
• Wenn kein Artwork definiert ist und ein Symbolbild (mit <link rel=icon> angegeben) in einer 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 HTML-Medienelements 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>

Du kannst den Medienmetadaten auch einzelne Kapitelinformationen hinzufügen, z. B. den Titel des Abschnitts, seinen Zeitstempel und einen Screenshot. So können Nutzende durch den Inhalt der Medien navigieren.

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' },
    ]
  }]
});

Nutzer steuern, was abgespielt wird

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 Ereignissen ähnlich und funktionieren auch sehr ähnlich. Genau 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 an einem Headset, einem anderen Remote-Gerät oder einer Tastatur drücken oder mit einer Medienbenachrichtigung interagieren.

Da einige Mediensitzungsaktionen 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 Einstellung eines Aktions-Handlers für Mediensitzungen ist so 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.`);
}

Handler für Mediensitzungsaktionen bleiben bei der Medienwiedergabe erhalten. Dies ähnelt dem Muster des Event-Listeners, mit der Ausnahme, dass die Verarbeitung eines Ereignisses dazu führt, dass der Browser kein Standardverhalten mehr ausführt und dies als Signal dafür verwendet, dass die Website die Mediaaktion unterstützt. Daher werden 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" angibt, dass er sie vorübergehend anhalten möchte.

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

Es kann sein, dass der Browser beim Suchen oder Laden einer Website keine Medien abspielt. Sie können das Verhalten überschreiben, indem Sie navigator.mediaSession.playbackState auf "playing" oder "paused" setzen. So wird dafür gesorgt, dass 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 sie einen Anfang hat, oder zum vorherigen Element in der Playlist wechseln möchte, wenn sie 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.
});

Aufnahme 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ückbewegen möchte, während "seekforward" angibt, dass die Medienwiedergabezeit um einen kurzen Zeitraum vorverlegt werden soll. In beiden Fällen bedeutet ein kurzer Zeitraum einige Sekunden.

Der im Aktions-Handler angegebene Wert seekOffset ist die Zeit in Sekunden, 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 im Aktions-Handler angegebene Wert seekTime ist die Zeit in Sekunden, auf die die Medienwiedergabezeit verschoben werden soll.

Der im Aktions-Handler angegebene boolesche Wert fastSeek 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

Um die Position der Medienwiedergabe in einer Benachrichtigung korrekt anzuzeigen, müssen Sie lediglich den Positionsstatus zum richtigen Zeitpunkt festlegen (siehe unten). Der Positionsstatus ist eine Kombination aus Medienwiedergaberate, Dauer und aktueller Zeit.

Die Dauer muss angegeben werden und 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 Setzen 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 entsprechendes Beispiel finden Sie im Beispiel für Videokonferenzen.

Mikrofon ein-/ausschalten

Mit der Aktion "togglemicrophone" wird angegeben, 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 betrachtet.

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 für Präsentationen

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 zum Präsentieren 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.
});

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.
});

Samples

Sehen Sie sich einige Beispiele aus Media Sessions mit der Blender Foundation und Jan Morgensterns Arbeit an.

Weitere Informationen

• Spezifikation für Mediasitzungen: wicg.github.io/mediasession
• Spezifikationsprobleme: github.com/WICG/mediasession/issues
• Chrome-Fehler: crbug.com