Signatur
Beschreibung
Die Schnittstelle ChapterInformation gehört zur Media Session API. Sie steht für ein einzelnes Kapitel einer Audio- oder Videoressource, etwa einen Abschnitt in einem Podcast, ein Kapitel in einem Hörbuch oder einen Teil eines Lehrvideos. Jede Instanz hat drei schreibgeschützte Eigenschaften:
title(string): der Titel des Kapitels,startTime(number): der Startzeitpunkt in Sekunden, gerechnet vom Anfang der Medienressource,artwork(ReadonlyArray<MediaImage>): Vorschaubilder zum Kapitel, jeweils mitsrc,sizesundtype.
Einen eigenen Konstruktor gibt es nicht. Instanzen entstehen, wenn Sie beim Konstruktor new MediaMetadata() die Option chapterInfo als Array einfacher Objekte übergeben. Der Browser wandelt jedes dieser Objekte in eine ChapterInformation um. Lesen können Sie die Kapitel danach über navigator.mediaSession.metadata.chapterInfo.
Der Browser kann die Kapitel in seinen eigenen Mediensteuerungen anzeigen, etwa im Mediensteuerungs-Popup von Chrome oder auf dem Sperrbildschirm. Nutzer springen dann direkt zu einem Kapitel. Sinnvoll ist das vor allem bei langen Medien wie Podcasts, Hörbüchern, Vorträgen und Tutorials. Für den eigentlichen Sprung zu einer Position registrieren Sie einen Handler für die Aktion "seekto" mit navigator.mediaSession.setActionHandler().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $title | string | "" | Titel des Kapitels. Wird im Objekt für chapterInfo übergeben und ist danach als schreibgeschützte Eigenschaft lesbar. |
| $startTime | number | 0 | Startzeit des Kapitels in Sekunden ab Beginn der Medienressource. Der Wert darf nicht negativ sein. |
| $artwork | Array<{src: string, sizes?: string, type?: string}> | [] | Vorschaubilder für das Kapitel. src wird relativ zur Dokument-URL aufgelöst. sizes hat z. B. die Form "512x512", type ist ein MIME-Typ wie "image/png". |
Rückgabewert
title, startTime und artwork. Sie erhalten es als Element von MediaMetadata.chapterInfo.Beispiele
Kapitel für einen Podcast festlegen
const audio = document.querySelector('audio');
if ('mediaSession' in navigator) {
navigator.mediaSession.metadata = new MediaMetadata({
title: 'Folge 42: Moderne Web-APIs',
artist: 'programmierung.net Podcast',
artwork: [{ src: '/img/cover-512.png', sizes: '512x512', type: 'image/png' }],
chapterInfo: [
{ title: 'Intro', startTime: 0 },
{ title: 'Media Session API', startTime: 95,
artwork: [{ src: '/img/kap2.png', sizes: '256x256', type: 'image/png' }] },
{ title: 'Fragen der Hörer', startTime: 1240 }
]
});
}Kapitel auslesen und als Liste ausgeben
const chapters = navigator.mediaSession.metadata?.chapterInfo ?? [];
const format = (s) => `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, '0')}`;
for (const chapter of chapters) {
console.log(`${format(chapter.startTime)} ${chapter.title} (${chapter.artwork.length} Bild(er))`);
}Zum Kapitel springen und aktuelles Kapitel ermitteln
const audio = document.querySelector('audio');
// Sprünge aus der Browser-Steuerung (auch Kapitelklicks) umsetzen
navigator.mediaSession.setActionHandler('seekto', ({ seekTime, fastSeek }) => {
if (fastSeek && 'fastSeek' in audio) audio.fastSeek(seekTime);
else audio.currentTime = seekTime;
});
// Das Kapitel ermitteln, in dem die Wiedergabe gerade steht
const currentChapter = () => {
const list = navigator.mediaSession.metadata?.chapterInfo ?? [];
return [...list].reverse().find((c) => c.startTime <= audio.currentTime);
};
// Zur nächsten Kapitelmarke springen
navigator.mediaSession.setActionHandler('nexttrack', () => {
const list = navigator.mediaSession.metadata?.chapterInfo ?? [];
const next = list.find((c) => c.startTime > audio.currentTime);
if (next) audio.currentTime = next.startTime;
});
audio.addEventListener('timeupdate', () => {
document.title = currentChapter()?.title ?? 'Podcast';
});// Wichtig · Fallstricke
- Experimentell: Die Schnittstelle gibt es derzeit nur in Chromium-Browsern ab Version 124. Firefox und Safari unterstützen sie nicht. Dort wird die Option
chapterInfostillschweigend ignoriert, undmetadata.chapterInfoistundefined. Prüfen Sie das deshalb vorher, z. B. mit'chapterInfo' in MediaMetadata.prototype, oder verwenden Sie optionales Verketten. - Kein Konstruktor:
new ChapterInformation()löst einenTypeErroraus. Kapitel entstehen nur übernew MediaMetadata({ chapterInfo }). - Schreibgeschützt:
title,startTimeundartworklassen sich nachträglich nicht ändern, und daschapterInfo-Array ist eingefroren. Wenn sich Kapitel ändern, weisen Sie ein neuesMediaMetadata-Objekt zu. - Keine automatische Sortierung und kein automatischer Sprung: Übergeben Sie die Kapitel aufsteigend nach
startTime. Das Springen selbst müssen Sie über einen"seekto"-Handler umsetzen. Fehlt dieser, blendet der Browser die Kapitelnavigation womöglich nicht ein oder sie funktioniert nicht. - Ist eine
artwork-URL ungültig, wirft derMediaMetadata-Konstruktor einenTypeError. Bilder anderer Herkunft müssen für die Anzeige erreichbar sein. - Die Media Session API steht nur in einem sicheren Kontext (HTTPS) zur Verfügung.