TextTrack — Schnittstelle · JavaScript-Referenz

Signatur

interface TextTrack extends EventTarget

Beschreibung

Das Interface TextTrack gehört zur WebVTT-API und steht für eine einzelne Textspur eines Medienelements. Solche Spuren entstehen entweder deklarativ über ein <track>-Element (erreichbar über trackElement.track) oder programmatisch mit HTMLMediaElement.prototype.addTextTrack(). Alle Spuren eines Medienelements findet man in media.textTracks (eine TextTrackList).

Wichtige Eigenschaften sind kind ("subtitles", "captions", "descriptions", "chapters", "metadata"), label, language, id sowie mode, das steuert, ob die Spur "disabled", "hidden" (geladen, aber nicht angezeigt) oder "showing" ist. Über cues und activeCues erhält man alle bzw. die gerade aktiven Cues als TextTrackCueList.

Mit den Methoden addCue(cue) und removeCue(cue) lassen sich Cues (meist VTTCue-Objekte) dynamisch hinzufügen oder entfernen. Das Ereignis cuechange (auch als oncuechange) feuert, sobald sich die Menge der aktiven Cues ändert – ideal für eigene Untertitel-Darstellung, synchronisierte Transkripte oder zeitgesteuerte Metadaten (z. B. Kapitelmarken, Quiz-Einblendungen).

Typische Einsatzfälle: eigene Untertitel-Menüs bauen, Untertitel in einem eigenen Overlay rendern (Modus "hidden" + cuechange), Live-Untertitel aus einem WebSocket einspeisen oder Metadaten-Spuren zur Steuerung interaktiver Inhalte nutzen.

Parameter

Name	Typ	Default	Beschreibung
$kind	"subtitles"\|"captions"\|"descriptions"\|"chapters"\|"metadata"		Schreibgeschützt. Art der Spur; bei `addTextTrack()` Pflichtargument.
$label	string	""	Schreibgeschützt. Für Menschen lesbarer Name, z. B. `"Deutsch"`.
$language	string	""	Schreibgeschützt. BCP-47-Sprachcode, z. B. `"de"`.
$mode	"disabled"\|"hidden"\|"showing"	"disabled" (bzw. "hidden" bei addTextTrack)	Les- und schreibbar. Steuert Laden und Anzeige der Spur.
$cues / activeCues	TextTrackCueList\|null	null bei mode="disabled"	Schreibgeschützt. Alle bzw. aktuell aktiven Cues.
$addCue(cue) / removeCue(cue)	(cue: TextTrackCue) => void		Fügt einen Cue hinzu bzw. entfernt ihn. `removeCue` wirft `NotFoundError`, wenn der Cue nicht zur Spur gehört.

Rückgabewert

Typ

TextTrack

Beschreibung

Instanzen erhält man über media.textTracks[i], trackElement.track oder media.addTextTrack(kind, label, language). Kein öffentlicher Konstruktor.

Beispiele

Spur programmatisch erzeugen und Cues hinzufügen

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

// Neue Untertitelspur anlegen
const track = video.addTextTrack('subtitles', 'Deutsch', 'de');
track.mode = 'showing';

track.addCue(new VTTCue(0, 3, 'Willkommen zum Tutorial!'));
track.addCue(new VTTCue(3, 7, 'Heute geht es um TextTrack.'));

console.log(track.kind, track.label, track.cues.length);

subtitles Deutsch 2

Untertitel-Auswahl: nur eine Sprache anzeigen

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

const showLanguage = (lang) => {
  for (const track of video.textTracks) {
    if (track.kind !== 'subtitles') continue;
    track.mode = track.language === lang ? 'showing' : 'disabled';
  }
};

showLanguage('en');
console.log([...video.textTracks].map(t => `${t.language}:${t.mode}`));

["de:disabled", "en:showing"]

Eigenes Overlay mit cuechange rendern

const video = document.querySelector('video');
const overlay = document.querySelector('#untertitel');
const track = video.querySelector('track[srclang="de"]').track;

// Laden, aber nicht nativ anzeigen
track.mode = 'hidden';

const onCueChange = () => {
  const texts = [...(track.activeCues ?? [])].map(cue => cue.text);
  overlay.textContent = texts.join('\n');
};

track.addEventListener('cuechange', onCueChange);
// Alternativ: track.oncuechange = onCueChange;

// Später wieder abmelden:
// track.removeEventListener('cuechange', onCueChange);

Cues einer Spur entfernen

const track = document.querySelector('video').textTracks[0];
track.mode = 'hidden'; // sonst ist cues === null

// Rückwärts iterieren, da die Liste live ist
for (let i = track.cues.length - 1; i >= 0; i--) {
  track.removeCue(track.cues[i]);
}
console.log(track.cues.length);

// Wichtig · Fallstricke

Modus beachten: Bei mode = "disabled" sind cues und activeCues null, und cuechange feuert nicht. Für eigene Darstellung "hidden" verwenden.
Asynchrones Laden: Bei <track src> sind die Cues erst nach dem load-Ereignis des <track>-Elements verfügbar; vorher ist cues.length oft 0.
CORS: Liegen VTT-Dateien auf einer anderen Domain, braucht das Medienelement das Attribut crossorigin und der Server passende CORS-Header, sonst wird die Spur nicht geladen.
Keine Entfernung: Mit addTextTrack() erzeugte Spuren lassen sich nicht wieder entfernen – nur deaktivieren oder leeren.
Sicherheit: Cue-Texte beim eigenen Rendern mit textContent statt innerHTML einfügen, um XSS über manipulierte VTT-Dateien zu vermeiden.
Kompatibilität: In allen modernen Browsern unterstützt; VTTCue fehlt in sehr alten Edge-Versionen (dort TextTrackCue). Die Darstellung nativer Untertitel (Styling über ::cue) unterscheidet sich zwischen Browsern, besonders im iOS-Vollbild.

Siehe auch

TextTrackCue TextMetrics TextTrackList AudioTrack ImageTrack