Medienbenachrichtigungen und Wiedergabesteuerung mit der Media Session API anpassen

Informationen zur Einbindung von Hardware-Medienschlüsseln, zum Anpassen von Medienbenachrichtigungen und mehr.

François Beaufort

Um Nutzer darüber zu informieren, was gerade in ihrem Browser abgespielt wird, und um sie zu steuern ohne zu der Seite zurückzukehren, auf der sie gestartet ist, wurde die Media Session API eingeführt. Sie ermöglicht es Webentwicklern, Metadaten in benutzerdefinierten Medienbenachrichtigungen, Medienereignissen wie Wiedergabe, Pause, Suchen, Nachverfolgen von Änderungen und Videokonferenzen, z. B. zum Stummschalten oder Aufheben der Stummschaltung Mikrofon, Kamera ein-/ausschalten und auflegen. Diese Anpassungen sind in verschiedenen Kontexten verfügbar, z. B. Desktop-Media-Hubs, Medienbenachrichtigungen auf Mobilgeräten und sogar auf Wearables. Ich werde diese Anpassungen diesem Artikel.

</ph>

Über die Media Session API

Die Media Session API bietet mehrere Vorteile und Funktionen:

• Hardware-Medienschlüssel werden unterstützt.
• Medienbenachrichtigungen werden auf Mobilgeräten, Computern und gekoppelten Wearables angepasst.
• Der Media Hub ist auf Computern verfügbar.
• Mediensteuerelemente für den Sperrbildschirm sind unter ChromeOS und auf Mobilgeräten verfügbar.
• Die Bild-im-Bild-Fenster-Steuerelemente sind für die Audiowiedergabe verfügbar, Videokonferenzen und Präsentationen.
• Die Assistant-Integration ist auf Mobilgeräten verfügbar.

Einige dieser Punkte werden anhand einiger Beispiele veranschaulicht.

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

Beispiel 2:Sie hören sich auf dem Gerät einen Podcast im Web an. Display gesperrt ist, können sie trotzdem auf die Schaltfläche zum Zurückspulen tippen. Symbol vom Schloss Bildschirmmediensteuerung, damit Webentwickler die Wiedergabezeit um einige Sekunden.

Beispiel 3: Wenn Nutzer Tabs haben, auf denen Audio wiedergegeben wird, können sie ganz einfach über den Media Hub auf dem Desktop wiedergeben, damit Webentwickler die Möglichkeit haben, ihren Zustand löschen.

Beispiel 4: Nutzer, die an einem Videoanruf teilnehmen, können die Ein/Aus-Schaltfläche Mikrofon“ im Bild-im-Bild-Fenster, um zu verhindern, dass die Website Mikrofondaten empfangen.

Dies geschieht über zwei verschiedene Schnittstellen: die MediaSession-Schnittstelle. und der MediaMetadata-Schnittstelle. Erstens können Nutzende steuern, gespielt wird. Zum anderen teilen Sie MediaSession mit, was gesteuert werden muss.

Im Bild unten sehen Sie, wie diese Oberflächen mit bestimmten Mediensteuerung, in diesem Fall eine Medienbenachrichtigung auf dem Mobilgerät.

</ph>

Nutzer darüber informieren, was gerade gespielt wird

Wenn eine Website Audio- oder Videoinhalte wiedergibt, erhalten Nutzer automatisch Medien in der Benachrichtigungsleiste auf Mobilgeräten oder im Media Hub auf Desktop-Computer. Der Browser versucht, die passenden Informationen anzuzeigen, indem er die Funktion Dokumenttitel und das größte Symbolbild, das es finden kann. Mit der Mediensitzung API können Sie die Medienbenachrichtigung mit Rich Media-Formaten Metadaten wie Titel, Name des Künstlers, Albumname und Artwork wie unten dargestellt.

Chrome fordert „vollständig“ an Audiofokus angezeigt werden, sodass Medienbenachrichtigungen nur angezeigt werden, Die Mediendauer beträgt mindestens 5 Sekunden. So werden Nebengeräusche wie Dings, werden keine Benachrichtigungen 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 beendet ist, musst du nichts weiter tun. Mediensitzung als verschwindet die Benachrichtigung automatisch. Beachten Sie, dass navigator.mediaSession.metadata wird verwendet, wenn die nächste Wiedergabe beginnt aber. Aus diesem Grund ist es wichtig, es zu aktualisieren, wenn die Medienwiedergabequelle um sicherzustellen, dass relevante Informationen in der Medienbenachrichtigung angezeigt werden.

Es gibt einige Dinge zu den Medienmetadaten zu beachten.

• Das Benachrichtigungs-Artwork-Array unterstützt Blob-URLs und Daten-URLs.
• Wenn kein Artwork definiert ist und ein Symbolbild (mit <link rel=icon> angegeben) in der gewünschten Größe vorhanden ist, wird es in Medienbenachrichtigungen verwendet.
• Die Zielgröße der Benachrichtigungsgrafik in Chrome für Android ist 512x512. Für Low-End-Geräten ist es 256x256.
• Das Attribut title des HTML-Medienelements wird in „Läuft gerade“ verwendet macOS-Widget.
• Wenn die Medienressource eingebettet ist (z. B. in einen iFrame), Media Session API -Informationen müssen 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 Screenshotbild. So können Nutzende durch die Inhalte 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' },
    ]
  }]
});

</ph>

Nutzer können festlegen, was abgespielt wird

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

</ph>

Da einige Aktionen für Mediensitzungen möglicherweise nicht unterstützt werden, empfehlen wir, verwenden Sie dabei den try…catch-Block.

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. Dies ähnelt dem Ereignis-Listener-Muster, außer dass ein Ereignis verarbeitet wird, bedeutet, dass der Browser kein Standardverhalten mehr ausführt und dies als signalisiert, dass die Website die Media-Aktion unterstützt. Die Steuerelemente für Medienaktionen wird nur angezeigt, wenn der richtige Aktions-Handler festgelegt ist.

</ph>

Wiedergabe / Pause

Die Aktion „"play"“ gibt an, dass der Nutzer die Medienwiedergabe fortsetzen möchte. während "pause" den Wunsch angibt, ihn vorübergehend anzuhalten.

Die Schaltfläche „Wiedergabe/Pause“ wird immer in Medienbenachrichtigungen angezeigt. Medienereignisse werden automatisch vom Browser verarbeitet. Standardeinstellung überschreiben „Play“ verwenden, und „Pause“ Medienaktionen wie unten dargestellt.

Der Browser stuft Websites möglicherweise so ein, dass keine Medien wiedergegeben werden, wenn sie nach oder geladen werden. Überschreiben Sie in diesem Fall dieses Verhalten, indem Sie navigator.mediaSession.playbackState bis "playing" oder "paused", um sicherzugehen und die Benutzeroberfläche der Website synchronisiert mit den Steuerelementen für Medienbenachrichtigungen.

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 die aktuelle Medienwiedergabe von Beginn an begonnen, oder zum vorherigen Element in der Playlist springen, 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 auf zum nächsten Element in der Playlist, wenn die Medienwiedergabe den Begriff einer Playlist enthält.

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

Beenden

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

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 Medien verschieben möchte. kurze Zeit zurückliegen, während "seekforward" darauf hinweist, um die Medienwiedergabezeit für einen kurzen Zeitraum zu verlängern. In beiden Fällen wird ein bedeutet eine kurze Zeitspanne, bedeutet einige Sekunden.

Der im Aktions-Handler angegebene Wert seekOffset ist die Zeit in Sekunden, die Medienwiedergabezeit um. Ist kein Wert angegeben (z. B. undefined), gilt Folgendes: sollten 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 einem bestimmten Zeitpunkt springen

Die Aktion „"seekto"“ gibt an, dass der Nutzer die Medienwiedergabe verschieben möchte zu einer bestimmten Zeit.

Der im Aktions-Handler angegebene Wert seekTime ist die Zeit in Sekunden, die Medienwiedergabezeit auf.

Der im Aktions-Handler angegebene boolesche Wert fastSeek ist „true“, wenn die Aktion mehrere Male als Teil einer Sequenz aufgerufen werden. Dies ist nicht der letzte Aufruf. in dieser Reihenfolge.

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

Die genaue Anzeige der Medienwiedergabeposition in einer Benachrichtigung ist ganz einfach wie unten gezeigt den Positionsstatus zu einem geeigneten Zeitpunkt festlegen. Die ist eine Kombination aus Wiedergaberate, Dauer und in der aktuellen Uhrzeit.

</ph>

Die Dauer muss positiv sein. Die Position muss positiv und kürzer 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 seinen Videoanruf in einem Bild-im-Bild-Fenster öffnet, wird das Symbol zeigt der Browser möglicherweise Steuerelemente für das Mikrofon und die Kamera sowie für das Auflegen an. Wenn der Nutzer darauf klickt, werden sie von der Website über das Video verarbeitet. Videokonferenzaktionen weiter unten. Ein Beispiel finden Sie unter Beispiel für Videokonferenzen.

</ph>

Mikrofon ein-/ausschalten

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

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 Funktion Kamera ein oder aus. Die Methode setCameraActive(isActive) gibt an, ob die 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);
});

Beenden

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

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

Aktionen für das Präsentieren von Folien

Wenn Nutzende ihre Präsentation in einem Bild-im-Bild-Fenster platzieren, zeigt der Browser möglicherweise Steuerelemente zum Navigieren durch Folien an. Wenn Nutzende werden sie von der Website über die Media Session API verarbeitet. Für eine Beispiel für eine Präsentation.

Zurück

Die Aktion "previousslide" gibt an, dass der Nutzer zum zur vorherigen Folie.

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

Weiter

Die Aktion "nextslide" gibt an, dass der Nutzer zur nächsten Folie wechseln möchte. wenn Sie Folien präsentieren.

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

Beispiele

Sehen Sie sich einige Media Sessions mit Blender Foundation und Jan Morgensterns Arbeit.

Ressourcen

• Spezifikationen für Mediensitzungen: wicg.github.io/mediasession
• Technische Probleme: github.com/WICG/mediasession/issues
• Fehler in Chrome: crbug.com