new MediaMetadata() — Methode · JavaScript-Referenz

Signatur

new MediaMetadata(metadata)

Beschreibung

Der Konstruktor MediaMetadata() erzeugt ein Objekt mit Metadaten zum Medium, das gerade abgespielt wird. Weist man es navigator.mediaSession.metadata zu, zeigt der Browser die Angaben außerhalb der Webseite an: in den Mediensteuerungen des Betriebssystems, auf dem Sperrbildschirm von Mobilgeräten, in Benachrichtigungen, auf Smartwatches oder in der Medienleiste des Browsers.

Alle Angaben sind optional. Übergeben wird ein Objekt mit title, artist, album und artwork. artwork ist ein Array von Bildbeschreibungen (src, sizes, type). Der Browser wählt daraus das Bild, das für die jeweilige Anzeige am besten passt. Deshalb lohnt es sich, mehrere Auflösungen anzugeben, z. B. 96×96 bis 512×512.

Einsatzzweck sind Musik-Player, Podcast-Apps, Hörbuch- und Video-Anwendungen. Ändert sich der Titel (z. B. beim Wechsel in einer Playlist), erzeugt man ein neues MediaMetadata-Objekt und weist es wieder zu. Alternativ ändert man die Eigenschaften des bestehenden Objekts direkt. Meist kombiniert man das mit navigator.mediaSession.setActionHandler(), damit die Tasten „Weiter“, „Zurück“ und „Pause“ auf der Systemebene funktionieren.

Parameter

Name	Typ	Default	Beschreibung
$metadata	object	{}	Optionales Objekt mit folgenden Eigenschaften: `title` (`string`, Standard `""`): Titel des Mediums. `artist` (`string`, Standard `""`): Interpret, Urheber oder Autor. `album` (`string`, Standard `""`): Album oder Sammlung. `artwork` (`Array<{src: string, sizes?: string, type?: string}>`, Standard `[]`): Cover-Bilder. `src` ist eine URL (auch relativ), `sizes` z. B. `"512x512"`, `type` ein MIME-Typ wie `"image/png"`. `chapterInfo` (experimentell, nur Chromium): Kapitelangaben.

Rückgabewert

Typ

MediaMetadata

Beschreibung

Ein neues MediaMetadata-Objekt. Seine Eigenschaften title, artist, album und artwork lassen sich lesen und ändern. Die src-Werte in artwork werden dabei in absolute URLs aufgelöst.

Beispiele

Metadaten für einen Song setzen

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

if ('mediaSession' in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Sommerregen',
    artist: 'Die Beispiele',
    album: 'Referenz-Hits',
    artwork: [
      { src: '/covers/sommer-96.png', sizes: '96x96', type: 'image/png' },
      { src: '/covers/sommer-256.png', sizes: '256x256', type: 'image/png' },
      { src: '/covers/sommer-512.png', sizes: '512x512', type: 'image/png' }
    ]
  });
}

// Muss meist durch eine Nutzeraktion ausgelöst werden
document.querySelector('#play').addEventListener('click', () => audio.play());

Playlist mit Weiter/Zurück-Tasten des Systems

const playlist = [
  { title: 'Intro', artist: 'Band A', album: 'Live', src: '/audio/intro.mp3', cover: '/img/a.jpg' },
  { title: 'Finale', artist: 'Band B', album: 'Studio', src: '/audio/finale.mp3', cover: '/img/b.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;
  await audio.play();

  navigator.mediaSession.metadata = new MediaMetadata({
    title: track.title,
    artist: track.artist,
    album: track.album,
    artwork: [{ src: track.cover, sizes: '512x512', type: 'image/jpeg' }]
  });
};

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

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

Standardwerte und aufgelöste URLs prüfen

const meta = new MediaMetadata({
  title: 'Folge 42',
  artwork: [{ src: 'cover.png' }]
});

console.log(meta.title);
console.log(meta.artist === '');
console.log(meta.artwork[0].src); // absolute URL

// Eigenschaften lassen sich nachträglich ändern
meta.artist = 'Tech-Podcast';
console.log(meta.artist);

Folge 42 true https://example.com/cover.png Tech-Podcast

// Wichtig · Fallstricke

Feature-Erkennung: Vorher mit 'mediaSession' in navigator prüfen. Ältere Browser kennen MediaMetadata nicht, der Aufruf wirft dort einen ReferenceError.
Nur sichtbar bei aktiver Wiedergabe: Die Metadaten erscheinen meist erst, wenn ein <audio>- oder <video>-Element wirklich abspielt. Viele Browser verlangen außerdem eine Mindestlänge (Chrome auf Android z. B. etwa 5 Sekunden).
Sicherer Kontext: Die Media Session API ist nur über HTTPS (oder localhost) zuverlässig verfügbar.
Fehler: Eine ungültige URL in artwork[].src löst einen TypeError aus. Cover-Bilder von fremden Domains müssen für den Browser ladbar sein.
Kein Nutzen ohne Zuweisung: Das Objekt allein bewirkt nichts. Es muss navigator.mediaSession.metadata zugewiesen werden.
chapterInfo ist experimentell und bislang nur in Chromium-Browsern verfügbar.

Siehe auch

new DOMMatrix() new MediaStream() new VRFrameData() new AudioData() new ImageData()