Signatur
Beschreibung
Ein TextTrackCue (in der Praxis meist ein VTTCue) steht für einen einzelnen Untertitel-, Kapitel- oder Metadaten-Eintrag mit Start- und Endzeit. Über cue.track kommt man vom einzelnen Cue zurück zur Textspur (TextTrack), die ihn enthält. Dort findet man zum Beispiel kind, label, language und mode.
Nützlich ist das vor allem in Ereignis-Handlern: Bei enter und exit eines Cues oder beim Durchlaufen von activeCues sieht man direkt, aus welcher Spur der Cue stammt, etwa aus den deutschen Untertiteln oder aus einer Kapitel-Spur. So muss man keine eigene Zuordnungstabelle führen.
Welchen Wert die Eigenschaft hat, hängt von der Zuordnung ab. Solange ein Cue nur mit new VTTCue(...) erzeugt, aber noch nicht per TextTrack.addCue() eingefügt wurde, ist track gleich null. Nach addCue() zeigt die Eigenschaft auf die jeweilige Spur. Nach removeCue() ist sie wieder null.
Rückgabewert
TextTrack-Objekt, zu dem der Cue gehört, oder null, wenn der Cue keiner Spur zugeordnet ist.Beispiele
Zuordnung vor und nach addCue()
const video = document.querySelector('video');
const track = video.addTextTrack('subtitles', 'Deutsch', 'de');
track.mode = 'showing';
const cue = new VTTCue(0, 4, 'Willkommen zum Video!');
console.log(cue.track); // noch keiner Spur zugeordnet
track.addCue(cue);
console.log(cue.track === track);
console.log(cue.track.label);
track.removeCue(cue);
console.log(cue.track);Herkunft aktiver Cues beim cuechange-Ereignis anzeigen
const video = document.querySelector('video');
for (const t of video.textTracks) {
t.mode = 'hidden'; // Cues laden und Ereignisse auslösen, ohne sie anzuzeigen
t.addEventListener('cuechange', (event) => {
for (const cue of event.target.activeCues) {
const { kind, language, label } = cue.track;
console.log(`[${kind}/${language}] ${label}: ${cue.text}`);
}
});
}Beim enter-Ereignis eines Cues nach Spurtyp unterscheiden
const video = document.querySelector('video');
const chapters = video.addTextTrack('chapters', 'Kapitel', 'de');
chapters.mode = 'hidden';
const cue = new VTTCue(10, 60, 'Kapitel 2: Installation');
cue.addEventListener('enter', () => {
if (cue.track?.kind === 'chapters') {
document.title = cue.text;
}
});
chapters.addCue(cue);// Wichtig · Fallstricke
- Nur lesbar: Wenn man
cue.trackeinen Wert zuweist, passiert nichts. Im strikten Modus löst die Zuweisung einenTypeErroraus. Einer anderen Spur ordnet man einen Cue mitremoveCue()und anschließendaddCue()auf der Zielspur zu. - Kann
nullsein: Vor dem Zugriff auf Eigenschaften der Spur mit optionaler Verkettung prüfen (cue.track?.kind). - Ruft man
addCue()für einen Cue auf, der schon zu einer anderen Spur gehört, wird er dort automatisch entfernt. Ein Cue gehört also immer zu höchstens einer Spur. - Cues aus einer
<track>-Datei stehen erst zur Verfügung, wenn die Spur geladen ist und ihrmodenicht"disabled"ist. Bei"disabled"isttrack.cuesgleichnull. - Kompatibilität: Chrome, Edge, Firefox und Safari unterstützen die Eigenschaft seit vielen Jahren. Sie steht nicht in Web Workern und nicht in Node.js zur Verfügung.