Signatur
Beschreibung
Die schreibgeschützte Eigenschaft chapterInfo gehört zum Interface MediaMetadata der Media Session API. Sie gibt ein eingefrorenes Array von ChapterInformation-Objekten zurück. Jedes Objekt beschreibt ein Kapitel des Mediums über title (Kapitelname), startTime (Startzeit in Sekunden) und artwork (Array von Bildern im Format von MediaImage).
Der Browser kann diese Kapitel in seinen Mediensteuerungen anzeigen, etwa im Medien-Hub von Chrome, auf dem Sperrbildschirm oder in System-Overlays. Nutzer sehen dann, welches Kapitel gerade läuft, und können direkt zu einem Kapitel springen. Das ist vor allem bei Podcasts, Hörbüchern, Vorlesungen und langen Videos nützlich.
Gesetzt werden die Kapitel nur über den Konstruktor: Du übergibst new MediaMetadata({ chapterInfo: [...] }) und weist das Objekt anschließend navigator.mediaSession.metadata zu. Die Eigenschaft selbst kann man nicht überschreiben. Sollen sich die Kapitel ändern, erzeugst du ein neues MediaMetadata-Objekt.
Rückgabewert
ChapterInformation-Objekten mit den Eigenschaften title (string), startTime (number, Sekunden) und artwork (eingefrorenes Array von Bildobjekten mit src, sizes und type). Wurden keine Kapitel angegeben, ist das Array leer.Beispiele
Kapitel beim Erzeugen der Metadaten festlegen
if ('mediaSession' in navigator) {
navigator.mediaSession.metadata = new MediaMetadata({
title: 'Folge 42: Web-APIs im Alltag',
artist: 'programmierung.net Podcast',
artwork: [{ src: '/cover-512.png', sizes: '512x512', type: 'image/png' }],
chapterInfo: [
{ title: 'Intro', startTime: 0 },
{ title: 'Media Session API', startTime: 95,
artwork: [{ src: '/ch2.jpg', sizes: '320x180', type: 'image/jpeg' }] },
{ title: 'Fragen der Hörer', startTime: 1260 }
]
});
}Kapitel auslesen und Unterstützung prüfen
const meta = navigator.mediaSession?.metadata;
if (meta && 'chapterInfo' in meta) {
for (const { title, startTime } of meta.chapterInfo) {
const min = Math.floor(startTime / 60);
const sec = String(Math.floor(startTime % 60)).padStart(2, '0');
console.log(`${min}:${sec} ${title}`);
}
} else {
console.log('chapterInfo wird nicht unterstützt');
}Kapitel aus einer Liste bauen und Springen per seekto ermöglichen
const audio = document.querySelector('audio');
const chapters = [
{ title: 'Einleitung', startTime: 0 },
{ title: 'Hauptteil', startTime: 300 },
{ title: 'Fazit', startTime: 900 }
];
navigator.mediaSession.metadata = new MediaMetadata({
title: 'Vorlesung: Promises',
chapterInfo: chapters
});
// Klickt der Nutzer im Browser-UI auf ein Kapitel, kommt eine seekto-Aktion an
navigator.mediaSession.setActionHandler('seekto', ({ seekTime }) => {
audio.currentTime = seekTime;
});
// Eigenschaft ist schreibgeschützt und eingefroren
console.log(Object.isFrozen(navigator.mediaSession.metadata.chapterInfo));// Wichtig · Fallstricke
- Experimentell: Die Eigenschaft wird derzeit nur von Chromium-basierten Browsern unterstützt. Firefox und Safari kennen sie nicht. In nicht unterstützten Browsern wird die Option
chapterInfoim Konstruktor stillschweigend ignoriert. Prüfe die Unterstützung daher mit'chapterInfo' in MediaMetadata.prototype. - Schreibgeschützt: Eine Zuweisung wie
metadata.chapterInfo = [...]hat keine Wirkung und wirft im Strict Mode einenTypeError. Auch Array-Methoden wiepush()scheitern, weil das Array eingefroren ist. Für Änderungen legst du ein neuesMediaMetadata-Objekt an. startTimewird in Sekunden angegeben, nicht in Millisekunden. Die Kapitel sollten aufsteigend sortiert sein und innerhalb der Mediendauer liegen.- Ungültige Bild-URLs in
artworkwerfen beim Erzeugen einenTypeError. Relative URLs werden gegen die Dokument-URL aufgelöst. - Ob und wie Kapitel angezeigt werden, entscheidet der Browser bzw. das Betriebssystem. Die Anzeige ist nicht garantiert.