HTMLTrackElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLTrackElement extends HTMLElement

Beschreibung

Das Interface HTMLTrackElement steht für ein HTML-<track>-Element. Es wird als Kindelement von <video> oder <audio> verwendet und verweist auf eine zeitgesteuerte Textdatei, meistens im Format WebVTT (.vtt). Typische Einsatzzwecke sind Untertitel, Hörgeschädigten-Untertitel, Audiodeskriptionen, Kapitelmarken und maschinenlesbare Metadaten.

Neben den geerbten Eigenschaften von HTMLElement bietet das Interface folgende Eigenschaften:

kind: Art der Spur – "subtitles" (Standard), "captions", "descriptions", "chapters" oder "metadata".
src: URL der Spurdatei.
srclang: Sprache der Spur als BCP-47-Code, z. B. "de".
label: Für Menschen lesbarer Titel, den der Browser im Untertitelmenü anzeigt.
default: Boolescher Wert; legt fest, dass diese Spur standardmäßig aktiviert wird.
readyState (nur lesbar): Ladezustand – 0 (NONE), 1 (LOADING), 2 (LOADED), 3 (ERROR). Die gleichnamigen Konstanten liegen auch auf HTMLTrackElement.
track (nur lesbar): Das zugehörige TextTrack-Objekt mit mode, cues und activeCues.

Das Element löst die Ereignisse load (Datei geladen und geparst) und error (Laden bzw. Parsen fehlgeschlagen) aus. Die eigentliche Steuerung der Anzeige erfolgt über trackElement.track.mode ("disabled", "hidden", "showing"). Mit dem cuechange-Ereignis des TextTrack lassen sich z. B. eigene Untertitel-Darstellungen oder synchronisierte Transkripte bauen.

Rückgabewert

Typ

HTMLTrackElement

Beschreibung

Instanzen bekommt man über document.createElement("track") oder durch Abfrage eines vorhandenen <track>-Elements, z. B. mit querySelector.

Beispiele

Untertitelspur dynamisch erzeugen und einbinden

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

const track = document.createElement('track');
track.kind = 'subtitles';
track.label = 'Deutsch';
track.srclang = 'de';
track.src = '/media/film.de.vtt';
track.default = true;

track.addEventListener('load', () => {
  console.log('Geladen, Anzahl Cues:', track.track.cues.length);
});
track.addEventListener('error', () => {
  console.error('Untertitel konnten nicht geladen werden');
});

video.append(track);
// Anzeige explizit aktivieren
track.track.mode = 'showing';

Geladen, Anzahl Cues: 42

Zwischen Sprachen umschalten

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

const setSubtitleLanguage = (lang) => {
  for (const el of video.querySelectorAll('track[kind="subtitles"]')) {
    el.track.mode = el.srclang === lang ? 'showing' : 'disabled';
  }
};

document.querySelector('#lang').addEventListener('change', (e) => {
  setSubtitleLanguage(e.target.value);
});

setSubtitleLanguage('en');

Eigene Untertitel-Anzeige per cuechange

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

// 'hidden': Cues werden verarbeitet, aber nicht vom Browser gezeichnet
trackEl.track.mode = 'hidden';

trackEl.track.addEventListener('cuechange', () => {
  const cues = [...trackEl.track.activeCues];
  box.textContent = cues.map((cue) => cue.text).join('\n');
});

Ladezustand prüfen

const trackEl = document.querySelector('track');

const states = {
  [HTMLTrackElement.NONE]: 'NONE',
  [HTMLTrackElement.LOADING]: 'LOADING',
  [HTMLTrackElement.LOADED]: 'LOADED',
  [HTMLTrackElement.ERROR]: 'ERROR'
};

console.log(states[trackEl.readyState]);

LOADED

// Wichtig · Fallstricke

Lazy Loading: Browser laden die VTT-Datei meist erst dann, wenn die Spur aktiv ist (mode ist "hidden" oder "showing") oder default gesetzt ist. Solange sie nicht aktiv ist, ist track.cues null und load wird nicht ausgelöst.
CORS: Liegt die VTT-Datei auf einer anderen Herkunft (Origin), muss das Medienelement das Attribut crossorigin haben und der Server passende CORS-Header senden. Sonst schlägt das Laden mit error fehl.
MIME-Typ: Der Server sollte text/vtt ausliefern. Die Datei muss mit WEBVTT beginnen, das alte SRT-Format wird nicht unterstützt.
Pro Medienelement darf nur eine Spur je kind-Gruppe default sein. Bei kind="subtitles" ist srclang Pflicht.
Das Attribut src nachträglich zu ändern, lädt die Spur in manchen Browsern nicht zuverlässig neu. Besser ein neues <track>-Element erzeugen.
Safari auf dem iPhone zeigt Untertitel im Vollbild mit dem nativen Player an. Eigene Darstellungen über mode = "hidden" greifen dort nicht.
Der Text von Cues kann Markup enthalten. Für eigene Anzeigen textContent statt innerHTML verwenden, um XSS zu vermeiden.

Siehe auch

HTMLAreaElement HTMLBRElement HTMLBaseElement HTMLDataElement HTMLHRElement