</> programmierung.net
Start · Sprachen · JavaScript · Referenz · MediaMetadata.artwork

MediaMetadata.artwork

Eigenschaft

Liest oder setzt ein Array von Bildobjekten (<code>src</code>, <code>sizes</code>, <code>type</code>), das Betriebssystem und Browser als Cover-Grafik für die laufende Medienwiedergabe anzeigen.

seit JavaScript Baseline 2023: Chrome 73+, Edge 79+, Firefox 82+, Kategorie: webapi

Signatur

MediaMetadata.artwork

Beschreibung

Die Eigenschaft artwork des Interfaces MediaMetadata enthält eine Liste von Bildern, die zur aktuell abgespielten Datei gehören, etwa ein Album-Cover, ein Podcast-Logo oder ein Vorschaubild für ein Video. Diese Bilder erscheinen in den Mediensteuerungen des Systems: auf dem Sperrbildschirm von Android, im macOS-Kontrollzentrum, in den Windows-Medienbenachrichtigungen, auf Smartwatches oder in der Mediensteuerung des Browsers.

Jeder Eintrag ist ein einfaches Objekt mit den Feldern src (Pflichtfeld, URL des Bildes), sizes (optional, z. B. "96x96" oder "128x128 256x256") und type (optional, MIME-Typ wie "image/png"). Gibt man mehrere Größen an, kann der Browser bzw. das System die passendste Auflösung für die jeweilige Oberfläche auswählen.

Beim Lesen bekommt man ein eingefrorenes Array (Object.freeze) zurück, in dem die src-URLs bereits zu absoluten URLs aufgelöst sind. Wer die Bilder ändern will, weist deshalb ein neues Array zu. Einzelne Einträge direkt zu verändern, etwa mit push(), funktioniert nicht.

Normalerweise setzt man artwork gemeinsam mit title, artist und album im Konstruktor new MediaMetadata() und weist das Objekt dann navigator.mediaSession.metadata zu, sobald die Wiedergabe beginnt oder der Titel wechselt.

Parameter

Name Typ Default Beschreibung
$src Pflicht string URL des Bildes, relativ oder absolut. Relative URLs werden gegen die URL des Dokuments aufgelöst.
$sizes string "" Durch Leerzeichen getrennte Größenangaben im Format BreitexHöhe, z. B. "96x96 192x192". Entspricht dem sizes-Attribut von <link rel="icon">.
$type string "" MIME-Typ des Bildes, z. B. "image/png", "image/jpeg" oder "image/webp". Damit kann der Browser Formate überspringen, die er nicht unterstützt.

Rückgabewert

Typ
ReadonlyArray<{src: string, sizes: string, type: string}>
Beschreibung
Ein eingefrorenes Array von Bildobjekten. Die src-Werte sind absolute URLs, fehlende sizes/type werden zu leeren Strings ergänzt. Ohne gesetzte Bilder ist das Array leer ([]).

Beispiele

Cover-Grafik in mehreren Auflösungen setzen

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

audio.addEventListener('play', () => {
  if (!('mediaSession' in navigator)) return;

  navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Morgenrot',
    artist: 'Die Beispiele',
    album: 'Erste Schritte',
    artwork: [
      { src: '/covers/morgenrot-96.png',  sizes: '96x96',   type: 'image/png' },
      { src: '/covers/morgenrot-256.png', sizes: '256x256', type: 'image/png' },
      { src: '/covers/morgenrot-512.png', sizes: '512x512', type: 'image/png' }
    ]
  });
});

Artwork auslesen: absolute URLs und eingefrorenes Array

const meta = new MediaMetadata({
  title: 'Folge 42',
  artwork: [{ src: 'img/podcast.jpg' }]
});

console.log(meta.artwork[0]);
console.log(Object.isFrozen(meta.artwork));
{ src: 'https://example.com/img/podcast.jpg', sizes: '', type: '' } true

Artwork beim Titelwechsel austauschen

const playlist = [
  { title: 'Intro',  cover: '/covers/intro.webp' },
  { title: 'Finale', cover: '/covers/finale.webp' }
];

const updateArtwork = (track) => {
  const meta = navigator.mediaSession.metadata;
  if (!meta) return;
  meta.title = track.title;
  // Neues Array zuweisen – das alte ist eingefroren
  meta.artwork = [
    { src: track.cover, sizes: '512x512', type: 'image/webp' },
    { src: track.cover.replace('.webp', '.png'), sizes: '512x512', type: 'image/png' }
  ];
};

navigator.mediaSession.metadata = new MediaMetadata({ title: '' });
updateArtwork(playlist[1]);
console.log(navigator.mediaSession.metadata.artwork.length);
2

// Wichtig · Fallstricke

  • Nicht direkt verändern: Das gelesene Array ist eingefroren. meta.artwork.push(...) wirft im Strict Mode einen TypeError und schlägt sonst ohne Fehlermeldung fehl. Weise stattdessen immer ein neues Array zu.
  • Ungültige URLs: Lässt sich eine src nicht als URL auflösen, wirft der Konstruktor oder der Setter einen TypeError. Fehlt src ganz, gibt es ebenfalls einen TypeError.
  • Laden der Bilder: Browser oder System laden die Bilder selbst. Bilder von fremden Domains brauchen je nach Browser passende CORS-Header. Außerdem darf die Content-Security-Policy (img-src) die Quelle nicht blockieren, sonst bleibt die Cover-Fläche leer.
  • Größen: Empfehlenswert sind quadratische Bilder zwischen 96×96 und 512×512 Pixeln. Welche Größe tatsächlich angezeigt wird, entscheidet die Plattform.
  • Kompatibilität: Die Media Session API gibt es nur in sicheren Kontexten (HTTPS). Metadaten werden meist erst angezeigt, wenn tatsächlich Audio oder Video abgespielt wird. Prüfe vorher mit 'mediaSession' in navigator, ob die API vorhanden ist. Safari unterstützt sie erst ab Version 15.

Siehe auch

MediaMetadata.artist MediaMetadata.album MediaMetadata.title MediaMetadata.chapterInfo MediaStream.active
← Vorheriger Eintrag MediaMetadata.artist