Signatur
Beschreibung
Die Eigenschaft track der Schnittstelle HTMLTrackElement ist schreibgeschützt. Sie liefert das TextTrack-Objekt, das der Browser für ein <track>-Element anlegt. Darüber steuerst du die eigentliche Textspur, also Untertitel, Beschreibungen, Kapitel oder Metadaten, aus JavaScript heraus.
Das TextTrack-Objekt ist dasselbe, das auch in HTMLMediaElement.textTracks steht. Mit track.mode blendest du Untertitel ein ("showing"), lädst sie nur, ohne sie anzuzeigen ("hidden"), oder schaltest sie ab ("disabled"). Über track.cues und track.activeCues liest du die einzelnen WebVTT-Einträge aus. Mit dem Ereignis cuechange reagierst du auf Wechsel während der Wiedergabe.
Wichtig: Der Browser lädt die Cues erst, wenn der Modus der Spur nicht "disabled" ist, zum Beispiel bei gesetztem default-Attribut oder bei mode = "hidden". Ob das Laden fertig ist, zeigen HTMLTrackElement.readyState und das load-Ereignis am <track>-Element.
Rückgabewert
TextTrack-Objekt des <track>-Elements. Seine Eigenschaften kind, label und language kommen aus den Attributen des Elements. Die Eigenschaft liefert immer dasselbe Objekt zurück.Beispiele
Untertitel per Knopfdruck ein- und ausschalten
// HTML:
// <video id="film" src="film.mp4" controls>
// <track id="de" kind="subtitles" srclang="de" label="Deutsch" src="film.de.vtt">
// </video>
// <button id="toggle">Untertitel</button>
const trackEl = document.getElementById('de');
const textTrack = trackEl.track;
document.getElementById('toggle').addEventListener('click', () => {
textTrack.mode = textTrack.mode === 'showing' ? 'disabled' : 'showing';
console.log(`${textTrack.label}: ${textTrack.mode}`);
});Cues nach dem Laden auslesen
const trackEl = document.querySelector('track[kind="chapters"]');
// Spur laden, ohne sie anzuzeigen
trackEl.track.mode = 'hidden';
trackEl.addEventListener('load', () => {
const cues = Array.from(trackEl.track.cues);
cues.forEach((cue) => {
console.log(`${cue.startTime.toFixed(1)}s – ${cue.text}`);
});
});Aktuellen Untertitel in eigenem Element anzeigen
const trackEl = document.querySelector('#film track');
const ausgabe = document.getElementById('untertitel');
const { track } = trackEl;
// Laden, aber nicht nativ darstellen
track.mode = 'hidden';
track.addEventListener('cuechange', () => {
const aktiv = track.activeCues?.[0];
ausgabe.textContent = aktiv ? aktiv.text : '';
});Eigenschaften der Spur prüfen
const trackEl = document.createElement('track');
trackEl.kind = 'captions';
trackEl.srclang = 'en';
trackEl.label = 'English';
document.querySelector('video').append(trackEl);
console.log(trackEl.track instanceof TextTrack);
console.log(trackEl.track.kind, trackEl.track.language, trackEl.track.label);
console.log(trackEl.track === trackEl.track);// Wichtig · Fallstricke
- Schreibgeschützt:
trackEl.track = …hat keine Wirkung und wirft im strikten Modus einenTypeError. Ändern lassen sich nur die Eigenschaften des zurückgegebenen Objekts, etwamode. - Cues fehlen: Solange
modeauf"disabled"steht, lädt der Browser die VTT-Datei nicht.track.cuesist dannnull. Setze vor dem Auslesenmode = "hidden"oder"showing"und warte auf dasload-Ereignis. - CORS: VTT-Dateien von einer anderen Herkunft brauchen am Medienelement das Attribut
crossoriginund passende CORS-Header auf dem Server. Sonst schlägt das Laden fehl und am<track>wird das Ereigniserrorausgelöst. - Sicherheit:
cue.textkann WebVTT-Markup enthalten. Gib den Text in eigenen Oberflächen mittextContentaus, nicht mitinnerHTML, damit kein XSS möglich ist. - Kompatibilität: Wird in allen modernen Browsern unterstützt. Im Internet Explorer gab es die Eigenschaft ab Version 10, aber nur eingeschränkt.