TextTrack.mode — Eigenschaft · JavaScript-Referenz

Signatur

TextTrack.mode

Beschreibung

Die Eigenschaft mode eines TextTrack-Objekts legt fest, ob eine Textspur eines <video>- oder <audio>-Elements aktiv ist und ob der Browser ihre Cues anzeigt. Sie lässt sich lesen und schreiben. Damit baust du zum Beispiel eigene Untertitel-Menüs oder verarbeitest Metadaten-Spuren mit JavaScript.

Es gibt drei mögliche Werte:

"disabled": Die Spur ist inaktiv. Der Browser lädt keine Cues, zeigt nichts an und löst keine cuechange-Events aus.
"hidden": Die Spur ist aktiv, und Cues werden geladen. activeCues wird laufend aktualisiert, und Events werden ausgelöst. Der Browser zeigt aber nichts an. Dieser Modus eignet sich für eigene Darstellungen, Transkripte oder metadata-Spuren.
"showing": Die Spur ist aktiv, und der Browser zeigt die Cues an (bei subtitles und captions). Bei chapters kann der Browser sie in seiner Oberfläche nutzen. metadata-Spuren zeigt er nie an.

Der Standardwert ist in der Regel "disabled". Eine Ausnahme ist ein <track>-Element mit dem Attribut default: Seine Spur startet als "showing" (bei Untertiteln) bzw. "hidden" (z. B. bei Kapiteln). Auf die Spuren eines Medienelements greifst du über HTMLMediaElement.textTracks zu. Die Spur eines einzelnen <track>-Elements erreichst du über HTMLTrackElement.track.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	"disabled" \| "hidden" \| "showing"	"disabled"	Neuer Modus beim Schreiben. Ungültige Zeichenfolgen werden stillschweigend ignoriert, der alte Wert bleibt dann erhalten.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Modus als Zeichenfolge: "disabled", "hidden" oder "showing".

Beispiele

Untertitel in einer bestimmten Sprache einschalten

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

const zeigeUntertitel = (sprache) => {
  for (const track of video.textTracks) {
    if (track.kind !== 'subtitles' && track.kind !== 'captions') continue;
    // Nur die gewünschte Sprache anzeigen, alle anderen abschalten
    track.mode = track.language === sprache ? 'showing' : 'disabled';
  }
};

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

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

Eigene Untertitel-Darstellung im Modus "hidden"

const video = document.querySelector('video');
const ausgabe = document.querySelector('#untertitel');
const track = video.textTracks[0];

// Aktiv, aber ohne native Anzeige, damit cuechange ausgelöst wird
track.mode = 'hidden';

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

Untertitel-Umschalter per Button

const video = document.querySelector('video');
const button = document.querySelector('#cc-button');

button.addEventListener('click', () => {
  const track = [...video.textTracks].find(t => t.kind === 'subtitles');
  if (!track) return;
  track.mode = track.mode === 'showing' ? 'disabled' : 'showing';
  button.setAttribute('aria-pressed', String(track.mode === 'showing'));
  console.log('Untertitel:', track.mode);
});

Untertitel: showing

Metadaten-Spur für Kapitelmarken auswerten

const trackEl = document.querySelector('track[kind="metadata"]');
const track = trackEl.track;

track.mode = 'hidden'; // Cues laden lassen

trackEl.addEventListener('load', () => {
  for (const cue of track.cues) {
    console.log(`${cue.startTime}s → ${cue.text}`);
  }
});

0s → Intro 42.5s → Hauptteil

// Wichtig · Fallstricke

Cues fehlen bei "disabled": Solange eine Spur deaktiviert ist, liefern track.cues und track.activeCues meist null. Wer Cues per Skript lesen will, muss vorher mindestens "hidden" setzen.
Ungültige Werte: Eine Zuweisung wie track.mode = 'on' wirft keinen Fehler. Sie wird einfach ignoriert. Frühere Implementierungen nutzten numerische Konstanten (0, 1, 2). Diese sind veraltet und werden nicht mehr unterstützt.
Mehrere Spuren gleichzeitig: Der Browser verhindert nicht zuverlässig, dass mehrere Untertitel-Spuren auf "showing" stehen. Deaktiviere die übrigen Spuren selbst, wenn du eine Spur einschaltest.
Browser-Oberfläche: Wählt der Nutzer im nativen Untertitel-Menü eine Spur, ändert der Browser mode von sich aus. Reagieren kannst du darauf über das change-Event von video.textTracks.
Styling: Die native Anzeige passt du mit dem Pseudo-Element ::cue an. Safari auf iOS stellt Untertitel im Vollbild-Player teils nach eigenen Regeln dar.
CORS: Liegen die WebVTT-Dateien auf einem anderen Origin, braucht das Medienelement das Attribut crossorigin, und der Server muss passende CORS-Header senden. Sonst werden keine Cues geladen, egal welcher Modus gesetzt ist.

Siehe auch

TextTrack TextTrack.activeCues TextTrack.cues HTMLMediaElement.textTracks HTMLTrackElement.track