ChapterInformation.startTime — Eigenschaft · JavaScript-Referenz

Signatur

ChapterInformation.startTime

Beschreibung

Die schreibgeschützte Eigenschaft startTime der Schnittstelle ChapterInformation gibt an, an welcher Stelle der Wiedergabe ein Kapitel beginnt. Der Wert ist eine Zahl in Sekunden, gemessen ab dem Anfang des Mediums, und kann Nachkommastellen haben (z. B. 90.5).

ChapterInformation-Objekte werden nicht direkt erzeugt. Sie entstehen, wenn Sie beim Konstruktor new MediaMetadata() im Feld chapterInfo ein Array von Kapitel-Beschreibungen ({ title, startTime, artwork }) übergeben. Über navigator.mediaSession.metadata.chapterInfo erhalten Sie anschließend ein eingefrorenes Array mit ChapterInformation-Instanzen, deren startTime Sie auslesen können.

Der Browser kann die Kapitel in seinen Medien-Bedienelementen anzeigen, etwa in der globalen Mediensteuerung oder auf dem Sperrbildschirm. In Ihrem eigenen Code brauchen Sie startTime meist, um zu einem Kapitel zu springen (audio.currentTime = chapter.startTime) oder um aus der aktuellen Position das gerade laufende Kapitel zu bestimmen.

Rückgabewert

Typ

number

Beschreibung

Startzeit des Kapitels in Sekunden (Gleitkommazahl, ≥ 0). Fehlt im Initialisierungsobjekt die Angabe startTime, ist der Wert 0.

Beispiele

Kapitel anlegen und Startzeiten auslesen

const supportsChapters = 'mediaSession' in navigator &&
  'chapterInfo' in MediaMetadata.prototype;

if (supportsChapters) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Podcast #42: Web-APIs',
    artist: 'programmierung.net',
    chapterInfo: [
      { title: 'Intro', startTime: 0 },
      { title: 'Media Session API', startTime: 95.5 },
      { title: 'Fazit', startTime: 1720 }
    ]
  });

  for (const chapter of navigator.mediaSession.metadata.chapterInfo) {
    console.log(`${chapter.title}: ${chapter.startTime} s`);
  }
}

Intro: 0 s Media Session API: 95.5 s Fazit: 1720 s

Kapitel-Navigation für einen Audio-Player bauen

const audio = document.querySelector('audio');
const list = document.querySelector('#kapitel');

const formatTime = (s) =>
  `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, '0')}`;

const { chapterInfo } = navigator.mediaSession.metadata;

for (const chapter of chapterInfo) {
  const button = document.createElement('button');
  button.textContent = `${formatTime(chapter.startTime)} – ${chapter.title}`;
  button.addEventListener('click', () => {
    audio.currentTime = chapter.startTime; // zum Kapitelanfang springen
    audio.play();
  });
  list.append(button);
}

Aktuelles Kapitel anhand der Wiedergabeposition ermitteln

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

const getCurrentChapter = (time) => {
  const chapters = [...navigator.mediaSession.metadata.chapterInfo]
    .sort((a, b) => a.startTime - b.startTime);
  // letztes Kapitel, dessen Start vor oder auf der aktuellen Zeit liegt
  return chapters.findLast((c) => c.startTime <= time) ?? null;
};

audio.addEventListener('timeupdate', () => {
  const current = getCurrentChapter(audio.currentTime);
  if (current) {
    document.title = `▶ ${current.title}`;
  }
});

// Wichtig · Fallstricke

Experimentell: chapterInfo und ChapterInformation werden bisher nur von Chromium-basierten Browsern (Chrome, Edge) unterstützt. Firefox und Safari unterstützen die Media Session API zwar, aber keine Kapitel. Prüfen Sie die Unterstützung vorher, z. B. mit 'chapterInfo' in MediaMetadata.prototype.
Schreibgeschützt: Eine Zuweisung an chapter.startTime wird stillschweigend ignoriert (im Strict Mode gibt es einen TypeError). Wollen Sie Kapitel ändern, weisen Sie navigator.mediaSession.metadata ein neues MediaMetadata-Objekt zu.
Der Browser sortiert die Kapitel nicht und prüft auch nicht, ob sie zur Mediendauer passen. Sortieren Sie selbst nach startTime und achten Sie darauf, dass kein Wert größer als duration des Mediums ist.
Die Einheit ist Sekunden und nicht Millisekunden. Daher passt der Wert direkt zu HTMLMediaElement.currentTime.
Kapitel in den Browser-Bedienelementen erscheinen nur, wenn eine aktive Media Session läuft, das Medium also gerade abgespielt wird.

Siehe auch

ChapterInformation ChapterInformation.title ChapterInformation.artwork MediaMetadata.chapterInfo MediaMetadata MediaSession HTMLMediaElement.currentTime