Signatur
Beschreibung
Die Eigenschaft endTime des Interfaces TextTrackCue ist ein number-Wert in Sekunden. Er legt fest, wann eine Cue (z. B. eine Untertitelzeile oder ein Kapitelmarker) endet. Gemessen wird ab dem Beginn der Medienzeitleiste des zugehörigen <video>- oder <audio>-Elements. Ist die Wiedergabeposition größer oder gleich endTime, gilt die Cue nicht mehr als aktiv und der Browser löst auf ihr das Ereignis exit aus.
Die Eigenschaft lässt sich lesen und schreiben. So kannst du Untertitel zur Laufzeit verschieben, verlängern oder kürzen, etwa um den Versatz einer WebVTT-Datei auszugleichen oder um Cues dynamisch zu erzeugen, zum Beispiel bei der Live-Transkription. In der Praxis arbeitest du meist mit der Unterklasse VTTCue, deren Konstruktor new VTTCue(startTime, endTime, text) den Wert direkt setzt.
Zusammen mit startTime bestimmt endTime das Zeitfenster, in dem die Cue in TextTrack.activeCues steht. Beachte, dass endTime nicht vor startTime liegen sollte, sonst wird die Cue nie aktiv.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | number | Beim Setzen: neue Endzeit in Sekunden (Gleitkommazahl, z. B. 12.5). Muss eine endliche Zahl sein. |
Rückgabewert
Beispiele
Endzeiten aller Cues einer Untertitelspur auslesen
const video = document.querySelector('video');
const track = video.textTracks[0];
track.mode = 'hidden'; // Cues laden, ohne sie anzuzeigen
video.addEventListener('loadedmetadata', () => {
for (const cue of track.cues) {
console.log(`${cue.startTime.toFixed(2)}s – ${cue.endTime.toFixed(2)}s: ${cue.text}`);
}
});Cue dynamisch erzeugen und Endzeit später verlängern
const video = document.querySelector('video');
const track = video.addTextTrack('subtitles', 'Deutsch', 'de');
track.mode = 'showing';
const cue = new VTTCue(1, 3, 'Achtung, gleich geht es los!');
track.addCue(cue);
console.log(cue.endTime);
// Text soll zwei Sekunden länger sichtbar bleiben
cue.endTime += 2;
console.log(cue.endTime);Zeitversatz einer ganzen Spur korrigieren
const shiftTrack = (track, offsetSeconds) => {
for (const cue of Array.from(track.cues)) {
// Erst endTime anpassen, damit bei positivem Versatz start <= end bleibt
cue.endTime = Math.max(0, cue.endTime + offsetSeconds);
cue.startTime = Math.max(0, cue.startTime + offsetSeconds);
}
};
const track = document.querySelector('video').textTracks[0];
track.mode = 'showing';
shiftTrack(track, 0.75); // Untertitel 0,75 s später anzeigenAuf das Ende einer Cue reagieren
const cue = new VTTCue(10, 12.5, 'Kapitel 1');
cue.addEventListener('exit', () => {
console.log(`Cue endete bei ${cue.endTime} s`);
});
const track = document.querySelector('video').addTextTrack('metadata');
track.mode = 'hidden';
track.addCue(cue);// Wichtig · Fallstricke
- Sichtbarkeit der Cues:
track.cuesistnull, solange der Modus der Spur"disabled"ist. Setzemodevorher auf"hidden"oder"showing". - Ungültige Werte: Wenn du
NaNoderInfinityzuweist, wirft der Browser einenTypeError. LiegtendTimevorstartTime, gibt es keinen Fehler, die Cue wird aber nie aktiv. - Genauigkeit: Das
exit-Ereignis und die Aktualisierung vonactiveCueshängen am Takt vontimeupdate(typischerweise alle 15–250 ms). Das Ende einer Cue wird also nicht auf die Millisekunde genau erkannt. - Reihenfolge beim Verschieben: Die Cue-Liste ist nach
startTimeundendTimesortiert. Nach einer Änderung sortiert der Browser sie neu, was beim Durchlaufen der Liste in einer Schleife zu übersprungenen Einträgen führen kann. Kopiere die Liste deshalb vorher mitArray.from(). - Kompatibilität: Wird von allen modernen Browsern unterstützt.
TextTrackCueselbst lässt sich nicht instanziieren, verwende dafürVTTCue. In älteren Versionen von Edge und IE hieß die KlasseTextTrackCueund hatte einen eigenen Konstruktor.