HTMLMediaElement.getStartDate() — Methode · JavaScript-Referenz

Signatur

HTMLMediaElement.prototype.getStartDate()

Beschreibung

Die Methode getStartDate() von HTMLMediaElement liefert den sogenannten Timeline Offset eines Mediums als Date-Objekt. Das ist das reale Datum mit Uhrzeit, das der Medienposition 0 entspricht. So lässt sich die Medienzeitachse (currentTime in Sekunden) mit der echten Uhrzeit verknüpfen.

Gebraucht wird das vor allem bei Live-Streams und Aufzeichnungen mit Zeitstempel, etwa bei HLS-Streams mit dem Tag #EXT-X-PROGRAM-DATE-TIME, bei Überwachungskameras, Sportübertragungen oder Fernsehmitschnitten. Wenn man den Rückgabewert und currentTime addiert, erhält man die echte Uhrzeit des gerade gezeigten Bildes. Damit kann man zum Beispiel eine Uhr einblenden oder Ereignisse zeitlich zuordnen.

Enthält das Medium keine Datumsangabe, gibt die Methode laut Spezifikation ein Date mit dem Wert NaN zurück („Invalid Date“). Der Timeline Offset steht frühestens fest, wenn die Metadaten geladen sind. Die Methode sollte man daher erst nach dem Ereignis loadedmetadata aufrufen.

Jeder Aufruf erzeugt ein neues Date-Objekt. Wenn man dieses Objekt verändert, ändert sich am Medienelement nichts.

Rückgabewert

Typ

Date

Beschreibung

Ein neues Date-Objekt mit dem Datum und der Uhrzeit, die der Medienposition 0 entsprechen. Ist kein Timeline Offset bekannt, ist sein Wert NaN (getTime() liefert NaN).

Beispiele

Unterstützung prüfen und Startdatum auslesen

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

if (typeof video.getStartDate !== 'function') {
  console.log('getStartDate() wird nicht unterstützt');
} else {
  video.addEventListener('loadedmetadata', () => {
    const start = video.getStartDate();
    if (Number.isNaN(start.getTime())) {
      console.log('Medium hat kein Startdatum');
    } else {
      console.log('Start:', start.toISOString());
    }
  });
}

Start: 2024-05-12T18:00:00.000Z

Echte Uhrzeit bei einem Live-Stream (HLS) einblenden

const video = document.querySelector('#live');
const clock = document.querySelector('#clock');
const fmt = new Intl.DateTimeFormat('de-DE', { timeStyle: 'medium' });

const getWallClock = (media) => {
  const start = media.getStartDate?.();
  if (!start || Number.isNaN(start.getTime())) return null;
  return new Date(start.getTime() + media.currentTime * 1000);
};

video.addEventListener('timeupdate', () => {
  const now = getWallClock(video);
  clock.textContent = now ? fmt.format(now) : '–';
});

#clock zeigt z. B. "20:14:37"

Zu einer bestimmten Uhrzeit springen

const seekToDate = (media, targetDate) => {
  const start = media.getStartDate();
  const offset = (targetDate.getTime() - start.getTime()) / 1000;
  if (Number.isNaN(offset)) throw new Error('Kein Timeline Offset vorhanden');
  media.currentTime = Math.max(0, offset);
};

const video = document.querySelector('video');
video.addEventListener('loadedmetadata', () => {
  // Zum Anpfiff um 20:45 Uhr springen
  seekToDate(video, new Date('2024-05-12T20:45:00+02:00'));
});

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Safari (macOS und iOS) unterstützt die Methode verlässlich. Chrome, Edge und Firefox kennen sie nicht. Deshalb immer vorher prüfen, ob es sie gibt, z. B. mit typeof video.getStartDate === 'function' oder video.getStartDate?.(). In Browsern ohne native HLS-Unterstützung liest man EXT-X-PROGRAM-DATE-TIME besser mit einer Bibliothek wie hls.js aus.
Invalid Date statt null: Fehlt die Datumsangabe, gibt die Methode ein Date mit dem Wert NaN zurück. Das Objekt ist trotzdem „truthy“. Deshalb mit Number.isNaN(date.getTime()) prüfen.
Zeitpunkt des Aufrufs: Vor loadedmetadata steht meist noch kein Wert fest. Bei Live-Streams kann sich der Offset während der Wiedergabe ändern, zum Beispiel wenn die Playlist neu geladen wird. Bei Bedarf also erneut abfragen.
Einheiten: currentTime ist in Sekunden angegeben, Date.getTime() in Millisekunden. Beim Rechnen umrechnen.

Siehe auch

Date HTMLFieldSetElement.reportValidity() HTMLMediaElement.setSinkId() HTMLMediaElement.canPlayType() HTMLMediaElement.addTextTrack()