TextTrackCue.startTime — Eigenschaft · JavaScript-Referenz

Signatur

TextTrackCue.startTime

Beschreibung

Die Eigenschaft startTime des Interfaces TextTrackCue gibt als Gleitkommazahl in Sekunden an, ab wann ein Cue aktiv wird. Ein Cue ist etwa eine Untertitelzeile, ein Kapitelmarker oder ein Metadateneintrag. Der Wert bezieht sich auf die Zeitleiste des zugehörigen <video>- oder <audio>-Elements, also auf dieselbe Skala wie HTMLMediaElement.currentTime.

Die Eigenschaft lässt sich lesen und schreiben. Wenn du sie änderst, verschiebt sich der Cue sofort, und der Browser berechnet die aktiven Cues des Tracks (TextTrack.activeCues) neu. Das eignet sich gut, um Untertitel zu synchronisieren (etwa alle Cues um einen festen Versatz verschieben), um Kapitelmarken live zu bearbeiten oder um Cues aus eigenen Datenquellen per Skript zu erzeugen.

In der Praxis arbeitet man meist mit der Unterklasse VTTCue. Ihr Konstruktor new VTTCue(startTime, endTime, text) setzt die Startzeit direkt. startTime gehört zusammen mit endTime, id, track und pauseOnExit zur Basis-Schnittstelle TextTrackCue.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	number		Beim Setzen: die neue Startzeit in Sekunden (Gleitkommazahl, z. B. `12.5`), bezogen auf den Anfang der Medien-Zeitleiste.

Rückgabewert

Typ

number

Beschreibung

Die Startzeit des Cues in Sekunden als double.

Beispiele

Cue erzeugen und Startzeit auslesen

const video = document.querySelector('video');
const track = video.addTextTrack('subtitles', 'Deutsch', 'de');
track.mode = 'showing';

const cue = new VTTCue(2.5, 6, 'Willkommen zum Tutorial!');
track.addCue(cue);

console.log(cue.startTime);

2.5

Alle Untertitel um einen Versatz verschieben

const shiftCues = (track, offset) => {
  // Array-Kopie, da TextTrackCueList eine Live-Liste ist
  for (const cue of Array.from(track.cues)) {
    // Zuerst endTime anpassen, damit endTime nie kleiner als startTime wird
    if (offset > 0) {
      cue.endTime += offset;
      cue.startTime += offset;
    } else {
      cue.startTime = Math.max(0, cue.startTime + offset);
      cue.endTime = Math.max(cue.startTime, cue.endTime + offset);
    }
  }
};

const video = document.querySelector('video');
const track = video.textTracks[0];
track.mode = 'hidden'; // Cues werden geladen, aber nicht angezeigt
shiftCues(track, 1.2);  // Untertitel kommen 1,2 s später
console.log(track.cues[0].startTime);

z. B. 3.7 (vorher 2.5)

Kapitelnavigation: zum Start eines Cues springen

const video = document.querySelector('video');
const chapters = Array.from(video.textTracks)
  .find((t) => t.kind === 'chapters');
chapters.mode = 'hidden';

video.addEventListener('loadedmetadata', () => {
  const list = document.querySelector('#kapitel');
  for (const cue of Array.from(chapters.cues ?? [])) {
    const btn = document.createElement('button');
    btn.textContent = `${cue.startTime.toFixed(0)} s – ${cue.text}`;
    btn.addEventListener('click', () => {
      video.currentTime = cue.startTime;
      video.play();
    });
    list.append(btn);
  }
});

// Wichtig · Fallstricke

Einheit ist Sekunden, nicht Millisekunden. Die WebVTT-Zeitangabe 00:01:02.500 entspricht 62.5.
cues ist null, solange der Track den Modus "disabled" hat. Setze track.mode auf "hidden" oder "showing", bevor du auf die Startzeiten zugreifst. Bei <track>-Elementen musst du außerdem warten, bis die Datei geladen ist (Ereignis load).
Die Spezifikation verbietet nicht, dass startTime größer als endTime ist. Ein solcher Cue wird aber nie aktiv. Passe beide Werte deshalb in der richtigen Reihenfolge an.
Wenn du startTime änderst, ordnet der Browser die Cue-Liste neu, denn sie ist nach Startzeit sortiert. Beim Iterieren über eine Live-TextTrackCueList können sich dadurch Indizes verschieben. Kopiere die Liste vorher mit Array.from().
Kompatibilität: Chrome, Firefox, Safari und Edge unterstützen die Eigenschaft seit Jahren. Einen direkten Konstruktor für TextTrackCue gibt es nicht. Verwende VTTCue.

Siehe auch

MediaTrackConstraints.sampleSize TextTrackCue.endTime TextTrackCue.track TextTrackCue.id TextTrackCue.pauseOnExit