ChapterInformation.artwork — Eigenschaft · JavaScript-Referenz

Signatur

ChapterInformation.artwork

Beschreibung

Die schreibgeschützte Eigenschaft artwork der Schnittstelle ChapterInformation gehört zur Media Session API. Sie liefert die Bilder, die zu einem einzelnen Kapitel einer Mediendatei gehören, etwa ein Vorschaubild oder Cover für jeden Abschnitt eines Podcasts, Hörbuchs oder langen Videos.

ChapterInformation-Objekte legt man nicht direkt an. Der Browser erzeugt sie, wenn man einem MediaMetadata-Objekt über die Option chapterInfo eine Kapitelliste übergibt. Danach kann man die Kapitel über navigator.mediaSession.metadata.chapterInfo auslesen. Jedes Kapitel hat die Eigenschaften title, startTime und artwork.

Jeder Eintrag im Array ist ein MediaImage-Objekt mit diesen Feldern:

src: absolute URL des Bildes (der Browser löst relative Angaben auf)
sizes: Größenangabe wie "96x96" oder "512x512" (optional, Standard ist ein leerer String)
type: MIME-Typ, z. B. "image/png" (optional, Standard ist ein leerer String)

Das Betriebssystem oder der Browser kann diese Bilder in Mediensteuerungen anzeigen, zum Beispiel in Sperrbildschirm-Widgets, Benachrichtigungen oder Kapitelübersichten. Welches Bild in welcher Größe erscheint, entscheidet die Plattform.

Rückgabewert

Typ

ReadonlyArray<MediaImage>

Beschreibung

Ein eingefrorenes (FrozenArray) Array von Objekten der Form { src: string, sizes: string, type: string }. Wurden für das Kapitel keine Bilder angegeben, ist das Array leer.

Beispiele

Kapitel mit Bildern festlegen und auslesen

// Metadaten für einen Podcast mit Kapiteln setzen
if ('mediaSession' in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Folge 42: Web-APIs im Alltag',
    artist: 'programmierung.net Podcast',
    artwork: [{ src: '/img/cover-512.png', sizes: '512x512', type: 'image/png' }],
    chapterInfo: [
      {
        title: 'Einleitung',
        startTime: 0,
        artwork: [{ src: '/img/kap1-96.png', sizes: '96x96', type: 'image/png' }]
      },
      {
        title: 'Media Session API',
        startTime: 180,
        artwork: [
          { src: '/img/kap2-96.png', sizes: '96x96', type: 'image/png' },
          { src: '/img/kap2-256.png', sizes: '256x256', type: 'image/png' }
        ]
      }
    ]
  });

  const [, kapitel2] = navigator.mediaSession.metadata.chapterInfo;
  console.log(kapitel2.artwork.length);
  console.log(kapitel2.artwork[1].sizes);
}

2 256x256

Alle Kapitelbilder für eine eigene Kapitelliste nutzen

const renderKapitelListe = (liste) => {
  const kapitel = navigator.mediaSession?.metadata?.chapterInfo ?? [];

  for (const { title, startTime, artwork } of kapitel) {
    const li = document.createElement('li');
    // Größtes verfügbares Bild wählen (sizes z. B. "256x256")
    const bild = [...artwork].sort(
      (a, b) => parseInt(b.sizes) - parseInt(a.sizes)
    )[0];

    if (bild) {
      const img = document.createElement('img');
      img.src = bild.src; // bereits absolute URL
      img.alt = '';
      li.append(img);
    }
    li.append(`${title} (${startTime}s)`);
    liste.append(li);
  }
};

renderKapitelListe(document.querySelector('#kapitel'));

Das Array ist schreibgeschützt und eingefroren

const [kapitel] = navigator.mediaSession.metadata.chapterInfo;

console.log(Object.isFrozen(kapitel.artwork));
console.log(kapitel.artwork[0].src);

// Neues Bild hinzufügen geht nicht:
try {
  'use strict';
  kapitel.artwork.push({ src: '/img/neu.png' });
} catch (e) {
  console.log(e instanceof TypeError);
}

true https://example.com/img/kap1-96.png true

// Wichtig · Fallstricke

Experimentell: ChapterInformation und MediaMetadata.chapterInfo gibt es bisher nur in Chromium-basierten Browsern. Vorher mit 'chapterInfo' in MediaMetadata.prototype prüfen, ob die Funktion vorhanden ist.
Nicht änderbar: artwork ist schreibgeschützt und das Array eingefroren. Um die Bilder zu ändern, muss man ein neues MediaMetadata-Objekt anlegen und es navigator.mediaSession.metadata zuweisen.
URLs werden aufgelöst: Relative src-Angaben werden gegen die Dokument-URL aufgelöst. Beim Auslesen bekommt man immer absolute URLs zurück. Ungültige URLs lösen schon beim Erzeugen von MediaMetadata einen TypeError aus.
Anzeige nicht garantiert: Ob und wie Kapitelbilder erscheinen, hängt vom Betriebssystem und vom Browser ab. Am besten mehrere Größen anbieten (z. B. 96, 256 und 512 Pixel).
Die Bilder werden wie normale Bildanfragen geladen. Für Bilder von fremden Domains gelten CSP-Regeln (img-src).

Siehe auch

ChapterInformation ChapterInformation.title ChapterInformation.startTime MediaMetadata MediaMetadata.chapterInfo MediaMetadata.artwork MediaSession