Signatur
Beschreibung
Die Eigenschaft metadata der Schnittstelle MediaSession legt fest, welche Informationen der Browser und das Betriebssystem zum laufenden Medium anzeigen. Gemeint sind z. B. die Mediensteuerung auf dem Sperrbildschirm, Benachrichtigungen unter Android, das Medien-Overlay in Windows und macOS, Bluetooth-Kopfhörer oder die Anzeige im Auto.
Der Wert ist entweder ein MediaMetadata-Objekt mit den Feldern title, artist, album und artwork (ein Array aus Bildbeschreibungen mit src, sizes und type) oder null. Bei null zeigt der Browser Standardangaben an, meist den Seitentitel und das Favicon.
Setzen Sie metadata jedes Mal neu, wenn ein anderer Titel startet, etwa in einer Wiedergabeliste oder bei einem Podcast-Player. Am besten geschieht das im play-Ereignis des <audio>- oder <video>-Elements oder direkt vor play(). Die Metadaten werden meist zusammen mit Aktions-Handlern über setActionHandler() verwendet, damit Hardware-Medientasten funktionieren.
Rückgabewert
MediaMetadata-Objekt oder null, wenn keine Metadaten gesetzt sind. Die Eigenschaft ist beschreibbar.Beispiele
Metadaten für einen Song setzen
if ('mediaSession' in navigator) {
navigator.mediaSession.metadata = new MediaMetadata({
title: 'Morgenrot',
artist: 'Die Beispielband',
album: 'Erste Platte',
artwork: [
{ src: '/cover-96.png', sizes: '96x96', type: 'image/png' },
{ src: '/cover-512.png', sizes: '512x512', type: 'image/png' }
]
});
console.log(navigator.mediaSession.metadata.title);
}Metadaten in einer Wiedergabeliste aktualisieren
const playlist = [
{ title: 'Folge 1: Einstieg', src: '/pod/1.mp3', cover: '/pod/1.jpg' },
{ title: 'Folge 2: Vertiefung', src: '/pod/2.mp3', cover: '/pod/2.jpg' }
];
const audio = document.querySelector('audio');
let index = 0;
const playTrack = async (i) => {
const track = playlist[i];
audio.src = track.src;
if ('mediaSession' in navigator) {
navigator.mediaSession.metadata = new MediaMetadata({
title: track.title,
artist: 'Programmierung-Podcast',
artwork: [{ src: track.cover, sizes: '512x512', type: 'image/jpeg' }]
});
}
await audio.play();
};
if ('mediaSession' in navigator) {
navigator.mediaSession.setActionHandler('nexttrack', () => {
index = (index + 1) % playlist.length;
playTrack(index);
});
}
document.querySelector('#start').addEventListener('click', () => playTrack(0));Metadaten zurücksetzen und einzelne Felder ändern
const session = navigator.mediaSession;
// Nur den Titel ändern, ohne ein neues Objekt anzulegen
if (session.metadata) {
session.metadata.title = 'Live-Stream (Pause)';
}
// Beim Beenden der Wiedergabe auf die Standardanzeige zurückfallen
document.querySelector('audio').addEventListener('ended', () => {
session.metadata = null;
console.log(session.metadata);
});// Wichtig · Fallstricke
- Funktionsprüfung: Prüfen Sie vorher mit
'mediaSession' in navigator, ob die API vorhanden ist. Ältere Browser und manche WebViews kennen wedernavigator.mediaSessionnochMediaMetadata. - Sicherer Kontext: Die API steht nur über HTTPS bzw.
localhostzur Verfügung. - Anzeige nur bei aktiver Wiedergabe: Die Metadaten erscheinen erst, wenn tatsächlich hörbares Audio oder Video läuft. Stummgeschaltete oder zu kurze Medien (in Chrome unter etwa 5 Sekunden) lösen oft keine Anzeige aus.
- Artwork: Relative URLs werden beim Setzen gegen die Dokument-URL aufgelöst. Geben Sie mehrere Größen an (z. B. 96–512 px), damit das Betriebssystem eine passende auswählen kann. Ungültige URLs lösen einen
TypeErroraus. - Kopie des Arrays:
metadata.artworkliefert ein eingefrorenes Array. Um das Cover zu ändern, weisen Sieartworkein neues Array zu, statt das bestehende zu verändern. - Jede Seite (bzw. jedes Frame) hat eine eigene Mediensitzung. Welche davon das System anzeigt, entscheidet der Browser.