HTMLTrackElement.kind — Eigenschaft · JavaScript-Referenz

Signatur

HTMLTrackElement.kind

Beschreibung

Die Eigenschaft kind spiegelt das HTML-Attribut kind eines <track>-Elements wider. Sie legt fest, wofür der verknüpfte WebVTT-Texttrack gedacht ist und wie der Browser ihn behandelt: ob er als Untertitel angezeigt, als Kapitelliste angeboten oder nur als unsichtbare Metadaten für Skripte bereitgestellt wird.

Erlaubte Werte sind:

"subtitles" – Übersetzung bzw. Transkription der Dialoge für Zuschauer, die den Ton hören, aber die Sprache nicht verstehen (Standardwert).
"captions" – Untertitel für Hörgeschädigte, inkl. Geräusche und Sprecherangaben.
"descriptions" – Textbeschreibungen des Bildinhalts, gedacht für Sprachausgabe (Screenreader).
"chapters" – Kapitelmarken zur Navigation im Medium.
"metadata" – Daten für Skripte; werden vom Browser nie angezeigt.

Es handelt sich um ein aufgezähltes Attribut: Fehlt das Attribut, liefert die Eigenschaft "subtitles"; steht ein ungültiger Wert im Attribut, liefert sie "metadata". Beim Schreiben wird der übergebene String unverändert ins Attribut übernommen. Die zugehörige TextTrack-Instanz (trackElement.track) stellt denselben Wert über die schreibgeschützte Eigenschaft TextTrack.kind bereit.

Parameter

Name	Typ	Default	Beschreibung
$wert (beim Setzen)	string	"subtitles"	Einer der Werte `"subtitles"`, `"captions"`, `"descriptions"`, `"chapters"` oder `"metadata"`. Groß-/Kleinschreibung wird beim Lesen ignoriert.

Rückgabewert

Typ

string

Beschreibung

Der normalisierte Track-Typ in Kleinbuchstaben. "subtitles", wenn das Attribut fehlt; "metadata", wenn das Attribut einen ungültigen Wert enthält.

Beispiele

Art aller Tracks eines Videos auslesen

// <video id="film"> mit mehreren <track>-Kindern
const video = document.querySelector('#film');

for (const trackEl of video.querySelectorAll('track')) {
  console.log(`${trackEl.label} (${trackEl.srclang}): ${trackEl.kind}`);
}

Deutsch (de): subtitles English CC (en): captions Kapitel (de): chapters

Standardwert und ungültige Werte

const track = document.createElement('track');
console.log(track.kind);          // Attribut fehlt

track.setAttribute('kind', 'CAPTIONS');
console.log(track.kind);          // wird normalisiert

track.setAttribute('kind', 'untertitel');
console.log(track.kind);          // ungültiger Wert

subtitles captions metadata

Metadaten-Track dynamisch hinzufügen und per Skript auswerten

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

const trackEl = document.createElement('track');
trackEl.kind = 'metadata';        // wird nie angezeigt
trackEl.src = '/media/werbung-marker.vtt';
trackEl.default = true;           // sorgt dafür, dass der Track geladen wird
video.append(trackEl);

trackEl.track.mode = 'hidden';    // Cues aktiv, aber unsichtbar
trackEl.track.addEventListener('cuechange', (event) => {
  const cue = event.target.activeCues[0];
  if (cue) console.log('Marker erreicht:', cue.text);
});

Marker erreicht: werbung-start

Nur Barrierefreiheits-Untertitel aktivieren

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

for (const trackEl of video.querySelectorAll('track')) {
  // Nur captions anzeigen, alle anderen sichtbaren Tracks deaktivieren
  if (trackEl.kind === 'captions') {
    trackEl.track.mode = 'showing';
  } else if (trackEl.kind === 'subtitles') {
    trackEl.track.mode = 'disabled';
  }
}

// Wichtig · Fallstricke

Fehlendes vs. ungültiges Attribut: Ein Tippfehler wie kind="subtitle" führt nicht zum Standardwert "subtitles", sondern zu "metadata". Der Track wird dann stillschweigend nicht angezeigt, ein häufiger Grund für „unsichtbare“ Untertitel.
Beim Setzen findet keine Validierung statt: trackEl.kind = 'foo' wirft keinen Fehler, beim Lesen erhält man danach "metadata".
TextTrack.kind (über trackEl.track) ist schreibgeschützt. Die Art lässt sich nur über das Element bzw. dessen Attribut ändern.
Die eingebauten Player der Browser zeigen "descriptions" und "chapters" kaum oder gar nicht an. Für Kapitelmenüs oder Audiodeskriptionen braucht man meist eigene Oberflächen, die die Cues selbst auswerten.
Bei subtitles ist srclang Pflicht, damit der Browser den Track richtig zuordnen kann.
Tracks von anderen Origins laden nur mit passenden CORS-Headern und dem Attribut crossorigin am <video>/<audio>-Element.
Kompatibilität: Die Eigenschaft wird von allen modernen Browsern unterstützt, im Internet Explorer ab Version 10.

Siehe auch

HTMLTrackElement.src HTMLTrackElement.label HTMLTrackElement.track HTMLTrackElement.srclang HTMLTrackElement.default