HTMLMediaElement.currentTime — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.currentTime

Beschreibung

Die Eigenschaft currentTime gibt die aktuelle Wiedergabeposition eines Medienelements in Sekunden als number mit Nachkommastellen zurück, z. B. 12.345. Mit ihr baut man eigene Fortschrittsbalken und Zeitanzeigen, speichert die Position zum späteren Fortsetzen oder synchronisiert Untertitel, Animationen und andere Medien.

Wenn man currentTime einen Wert zuweist, springt die Wiedergabe an diese Stelle. Der Browser löst dabei nacheinander die Ereignisse seeking und seeked aus. Das Springen läuft asynchron: Der neue Wert lässt sich sofort auslesen, das passende Bild bzw. die Audiodaten stehen aber erst nach seeked bereit. Bei Streams ohne Byte-Range-Unterstützung (fehlender Header Accept-Ranges) kann das Springen fehlschlagen oder wieder bei 0 beginnen.

Laufende Änderungen des Werts während der Wiedergabe meldet das Ereignis timeupdate. Es feuert je nach Browser etwa alle 15–250 ms. Für flüssige Anzeigen kombiniert man currentTime mit requestAnimationFrame oder, bei Videos, mit requestVideoFrameCallback().

Parameter

Name	Typ	Default	Beschreibung
$value (Setter)	number		Neue Wiedergabeposition in Sekunden. Der Browser begrenzt den Wert auf den abspielbaren Bereich (`seekable`). Bei `NaN` oder `Infinity` wirft er einen `TypeError`.

Rückgabewert

Typ

number

Beschreibung

Aktuelle Wiedergabeposition in Sekunden als Gleitkommazahl. Vor dem Laden der Metadaten ist der Wert 0 bzw. die gesetzte Startposition.

Beispiele

Zeitanzeige im Format mm:ss aktualisieren

const video = document.querySelector('video');
const anzeige = document.querySelector('#zeit');

const format = (s) => {
  const min = Math.floor(s / 60);
  const sek = Math.floor(s % 60).toString().padStart(2, '0');
  return `${min}:${sek}`;
};

video.addEventListener('timeupdate', () => {
  anzeige.textContent = `${format(video.currentTime)} / ${format(video.duration || 0)}`;
});

z. B. "1:07 / 4:32"

Vor- und Zurückspulen um 10 Sekunden

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

const springe = (delta) => {
  const ziel = video.currentTime + delta;
  video.currentTime = Math.min(Math.max(ziel, 0), video.duration || ziel);
};

document.addEventListener('keydown', (e) => {
  if (e.key === 'ArrowRight') springe(10);
  if (e.key === 'ArrowLeft') springe(-10);
});

video.addEventListener('seeked', () => {
  console.log('Neue Position:', video.currentTime.toFixed(2));
});

Neue Position: 20.00

Wiedergabeposition speichern und fortsetzen

const video = document.querySelector('video');
const key = `pos:${video.currentSrc || video.src}`;

// Erst nach dem Laden der Metadaten springen
video.addEventListener('loadedmetadata', () => {
  const gespeichert = Number(localStorage.getItem(key));
  if (gespeichert > 0 && gespeichert < video.duration - 5) {
    video.currentTime = gespeichert;
  }
});

// Position gedrosselt sichern
let zuletzt = 0;
video.addEventListener('timeupdate', () => {
  if (Math.abs(video.currentTime - zuletzt) >= 5) {
    zuletzt = video.currentTime;
    localStorage.setItem(key, String(zuletzt));
  }
});

Fortschrittsbalken per Klick steuern

const audio = document.querySelector('audio');
const balken = document.querySelector('#fortschritt');

balken.addEventListener('click', (e) => {
  const rect = balken.getBoundingClientRect();
  const anteil = (e.clientX - rect.left) / rect.width;
  if (Number.isFinite(audio.duration)) {
    audio.currentTime = anteil * audio.duration;
  }
});

// Wichtig · Fallstricke

Zeitpunkt des Setzens: Wenn man currentTime vor loadedmetadata setzt, kann der Browser den Wert je nach Browser und Quelle ignorieren oder zurücksetzen. Zuverlässiger ist es, erst in loadedmetadata bzw. canplay zu springen.
Ungenaues Springen: Viele Browser springen zum nächsten Keyframe. Die tatsächliche Position kann deshalb leicht vom gesetzten Wert abweichen. Für schnelles, ungefähres Springen gibt es fastSeek(), das allerdings nicht überall unterstützt wird.
duration prüfen: Bei Livestreams ist duration Infinity, vor dem Laden NaN. Berechnungen wie anteil * duration sollte man daher mit Number.isFinite() absichern.
Genauigkeit und Datenschutz: Firefox rundet den Wert bei aktivem privacy.resistFingerprinting gröber. Für bildgenaue Synchronisation ist currentTime nicht geeignet, dafür gibt es requestVideoFrameCallback().
Server: Damit das Springen zuverlässig funktioniert, muss der Server HTTP-Range-Requests unterstützen (Antwortcode 206 Partial Content).
Browser-Kompatibilität: Die Eigenschaft wird von allen modernen Browsern unterstützt.

Siehe auch

HTMLMediaElement HTMLMediaElement.duration HTMLMediaElement.fastSeek() HTMLMediaElement.playbackRate HTMLMediaElement.seekable