MediaMetadata — Schnittstelle · JavaScript-Referenz

Signatur

interface MediaMetadata

Beschreibung

MediaMetadata gehört zur Media Session API. Ein Objekt dieser Schnittstelle beschreibt das Medium, das gerade abgespielt wird. Weist man es navigator.mediaSession.metadata zu, zeigt die Plattform die Angaben außerhalb der Webseite an, zum Beispiel auf dem Sperrbildschirm von Android oder iOS, in der Mediensteuerung von Windows und macOS, auf Bluetooth-Kopfhörern, in Autoradios oder in der globalen Medienleiste von Chrome.

Das Objekt erzeugt man mit dem Konstruktor new MediaMetadata(init). Übergeben wird ein Objekt mit den Feldern title, artist, album und artwork. artwork ist ein Array von Bildbeschreibungen mit src, sizes und type. Die Plattform sucht sich daraus die passende Auflösung aus. Alle Eigenschaften lassen sich auch nach dem Erzeugen noch lesen und schreiben. Neuere Browser kennen zusätzlich chapterInfo für Kapitelmarken.

Einsetzen sollte man MediaMetadata in jeder Web-App, die Audio oder Video abspielt: Musik-Player, Podcast-Apps, Streaming-Seiten oder Web-Radios. Zusammen mit navigator.mediaSession.setActionHandler() für Wiedergabe, Pause und Titelwechsel wirkt die Web-App dann wie eine native Anwendung. Wichtig: Die Metadaten werden erst angezeigt, wenn tatsächlich ein Medienelement auf der Seite abspielt. Bei jedem Titelwechsel muss man ein neues Objekt zuweisen oder die Eigenschaften des vorhandenen Objekts ändern.

Parameter

Name	Typ	Default	Beschreibung
$init	object	{}	Objekt mit den Startwerten für die Metadaten (Konstruktor-Argument von `new MediaMetadata(init)`).
$init.title	string	""	Titel des Mediums, z. B. Songtitel oder Folgenname.
$init.artist	string	""	Interpret, Urheber oder Sprecher.
$init.album	string	""	Name des Albums, der Sammlung oder der Podcast-Reihe.
$init.artwork	Array<{src: string, sizes?: string, type?: string}>	[]	Liste von Cover-Bildern. `src` ist die Bild-URL, relativ zum Dokument aufgelöst. `sizes` gibt die Größe an, z. B. `"512x512"`. `type` ist der MIME-Typ, z. B. `"image/png"`.
$init.chapterInfo	Array<{title: string, startTime: number, artwork?: Array}>	[]	Experimentell (bisher nur Chromium): Kapitelmarken mit Titel und Startzeit in Sekunden.

Rückgabewert

Typ

MediaMetadata

Beschreibung

Neues MediaMetadata-Objekt mit den Eigenschaften title, artist, album und artwork. Man weist es navigator.mediaSession.metadata zu.

Beispiele

Metadaten für einen Song setzen

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

if ('mediaSession' in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Nachtfahrt',
    artist: 'Die Beispielband',
    album: 'Lichter der Stadt',
    artwork: [
      { src: '/covers/nachtfahrt-96.png', sizes: '96x96', type: 'image/png' },
      { src: '/covers/nachtfahrt-256.png', sizes: '256x256', type: 'image/png' },
      { src: '/covers/nachtfahrt-512.png', sizes: '512x512', type: 'image/png' }
    ]
  });
}

// Anzeige erscheint erst, wenn tatsächlich abgespielt wird
await audio.play();
console.log(navigator.mediaSession.metadata.title);

Nachtfahrt

Playlist-Player mit Titelwechsel und Action-Handlern

const playlist = [
  { title: 'Folge 1: Einstieg', artist: 'Code-Podcast', album: 'Staffel 1', src: '/audio/f1.mp3', cover: '/img/s1.jpg' },
  { title: 'Folge 2: Vertiefung', artist: 'Code-Podcast', album: 'Staffel 1', src: '/audio/f2.mp3', cover: '/img/s1.jpg' }
];
let index = 0;
const audio = new Audio();

const playTrack = async (i) => {
  index = (i + playlist.length) % playlist.length;
  const track = playlist[index];
  audio.src = track.src;
  navigator.mediaSession.metadata = new MediaMetadata({
    title: track.title,
    artist: track.artist,
    album: track.album,
    artwork: [{ src: track.cover, sizes: '512x512', type: 'image/jpeg' }]
  });
  await audio.play();
};

navigator.mediaSession.setActionHandler('play', () => audio.play());
navigator.mediaSession.setActionHandler('pause', () => audio.pause());
navigator.mediaSession.setActionHandler('previoustrack', () => playTrack(index - 1));
navigator.mediaSession.setActionHandler('nexttrack', () => playTrack(index + 1));

document.querySelector('#start').addEventListener('click', () => playTrack(0));

Vorhandene Metadaten nachträglich ändern

const meta = new MediaMetadata({ title: 'Live-Stream', artist: 'Web-Radio 42' });
navigator.mediaSession.metadata = meta;

// Später z. B. aus einem Server-Event: aktuellen Titel aktualisieren
const updateNowPlaying = ({ title, artist }) => {
  meta.title = title;
  meta.artist = artist;
  console.log(`${meta.artist} – ${meta.title}`);
};

updateNowPlaying({ title: 'Morgenrot', artist: 'Anna Beispiel' });
console.log(meta.artwork.length);

Anna Beispiel – Morgenrot 0

// Wichtig · Fallstricke

Feature-Erkennung: Vorher mit 'mediaSession' in navigator prüfen. Ältere Browser und manche WebViews kennen MediaMetadata nicht. Ohne Prüfung wirft der Konstruktor dort einen ReferenceError.
Anzeige nur bei aktiver Wiedergabe: Die Plattform zeigt die Metadaten erst, wenn ein <audio>- oder <video>-Element hörbar abspielt. Bei stummen oder sehr kurzen Clips (in Chrome unter etwa 5 Sekunden) wird oft gar nichts angezeigt.
Artwork: Die URLs werden beim Zuweisen relativ zur Dokument-URL aufgelöst. Stammen die Bilder von einer anderen Herkunft, können sie an CORS oder CSP (img-src) scheitern. Am besten mehrere Größen angeben (96 bis 512 px). Eine ungültige URL in src löst einen TypeError aus.
artwork ist eingefroren: Der Getter gibt ein eingefrorenes Array zurück. meta.artwork.push(...) funktioniert daher nicht. Stattdessen der Eigenschaft ein neues Array zuweisen.
Datenschutz: Die Angaben sind außerhalb des Browsers sichtbar, etwa auf dem Sperrbildschirm oder im Auto. Keine vertraulichen Inhalte in Titel oder Interpret schreiben.
chapterInfo ist experimentell und bisher nur in Chromium-Browsern verfügbar.

Siehe auch

Metadata MediaStream VRFrameData AudioData ImageData