TextTrack.kind — Eigenschaft · JavaScript-Referenz

Signatur

TextTrack.kind

Beschreibung

Die Eigenschaft kind eines TextTrack-Objekts sagt aus, wofür der Track gedacht ist. Anhand dieser Art entscheidet der Browser, wie er den Track behandelt. Untertitel und Bildunterschriften (Captions) blendet er über dem Video ein. Kapitel und Metadaten zeigt er dagegen nicht an, sondern stellt sie nur per Skript bereit.

Mögliche Werte sind:

"subtitles": Übersetzung des Dialogs, etwa für Zuschauer, die die Sprache nicht verstehen.
"captions": Transkription des Dialogs mit Geräuschen und Sprecherhinweisen, gedacht für gehörlose und schwerhörige Menschen.
"descriptions": Textbeschreibung des Bildinhalts, gedacht für blinde Menschen oder Sprachausgabe.
"chapters": Kapitelmarken zur Navigation im Medium.
"metadata": Daten für Skripte, die der Browser nie anzeigt.

Der Wert wird beim Erzeugen des Tracks festgelegt und lässt sich danach nicht mehr ändern. Er stammt entweder aus dem kind-Attribut eines <track>-Elements oder aus dem ersten Argument von HTMLMediaElement.addTextTrack(). Man nutzt kind vor allem, um in video.textTracks gezielt Tracks zu finden, etwa alle Untertitel für ein eigenes Sprachmenü oder den Kapitel-Track für eine Kapitelnavigation.

Rückgabewert

Typ

"subtitles" | "captions" | "descriptions" | "chapters" | "metadata"

Beschreibung

Ein string, der die Art des Tracks angibt. Die Eigenschaft ist schreibgeschützt.

Beispiele

Alle Tracks eines Videos mit ihrer Art auflisten

// HTML: <video id="film" src="film.mp4">
//   <track kind="subtitles" src="de.vtt" srclang="de" label="Deutsch">
//   <track kind="chapters" src="kapitel.vtt" srclang="de" label="Kapitel">
// </video>
const video = document.getElementById('film');

for (const track of video.textTracks) {
  console.log(`${track.label}: ${track.kind}`);
}

Deutsch: subtitles Kapitel: chapters

Sprachmenü nur aus Untertiteln und Captions aufbauen

const video = document.querySelector('video');
const menu = document.querySelector('#untertitel-menue');

const sichtbareArten = new Set(['subtitles', 'captions']);

const tracks = [...video.textTracks].filter((t) => sichtbareArten.has(t.kind));

for (const track of tracks) {
  const button = document.createElement('button');
  button.textContent = `${track.label} (${track.kind === 'captions' ? 'CC' : 'UT'})`;
  button.addEventListener('click', () => {
    // Alle anderen ausblenden, den gewählten anzeigen
    tracks.forEach((t) => { t.mode = t === track ? 'showing' : 'disabled'; });
  });
  menu.append(button);
}

Metadaten-Track per Skript anlegen und auswerten

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

// kind wird beim Erzeugen festgelegt und ist danach unveränderlich
const metaTrack = video.addTextTrack('metadata', 'Werbemarken');
console.log(metaTrack.kind);

metaTrack.mode = 'hidden'; // Cues feuern Events, werden aber nicht angezeigt
metaTrack.addCue(new VTTCue(10, 12, JSON.stringify({ typ: 'werbung', id: 42 })));

metaTrack.addEventListener('cuechange', () => {
  const cue = metaTrack.activeCues[0];
  if (cue) console.log('Aktive Daten:', JSON.parse(cue.text));
});

metadata

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie track.kind = 'captions' wird stillschweigend ignoriert, im Strict Mode löst sie einen TypeError aus. Wer die Art ändern will, muss beim <track>-Element das Attribut über HTMLTrackElement.kind setzen oder einen neuen Track anlegen.
Standardwerte beim <track>-Element: Fehlt das Attribut kind, gilt "subtitles". Ein ungültiger Wert wird als "metadata" behandelt, der Track ist dann also unsichtbar. Das ist ein häufiger Grund, warum Untertitel „einfach nicht erscheinen".
addTextTrack(): Ein ungültiger kind-Wert löst hier einen TypeError aus. Anders als beim Attribut gibt es keinen Rückfall auf "metadata".
Barrierefreiheit: "captions" und "subtitles" sind nicht dasselbe. Für Menschen mit eingeschränktem Hörvermögen ist "captions" richtig, weil dieser Track auch Geräusche beschreibt.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Wie gut "descriptions" und "chapters" im nativen Player genutzt werden, unterscheidet sich stark von Browser zu Browser. Meist muss man diese Arten selbst per Skript auswerten.

Siehe auch

TextTrack TextTrack.mode TextTrack.label TextTrack.language HTMLTrackElement.kind HTMLMediaElement.addTextTrack() HTMLMediaElement.textTracks