HTMLTrackElement.readyState — Eigenschaft · JavaScript-Referenz

Signatur

HTMLTrackElement.readyState

Beschreibung

Die schreibgeschützte Eigenschaft readyState eines HTMLTrackElement zeigt an, wie weit die zugehörige Textspur (etwa eine WebVTT-Untertiteldatei) geladen ist. Der Wert ist eine der folgenden Ganzzahlen, die auch als statische Konstanten auf HTMLTrackElement verfügbar sind:

0 – HTMLTrackElement.NONE: Die Textspur wurde noch nicht angefordert, die Cues sind nicht geladen.
1 – HTMLTrackElement.LOADING: Die Datei wird gerade geladen und verarbeitet. Es können schon einzelne Cues vorhanden sein.
2 – HTMLTrackElement.LOADED: Die Textspur ist vollständig geladen und alle Cues stehen bereit.
3 – HTMLTrackElement.ERROR: Laden oder Verarbeiten ist fehlgeschlagen, z. B. wegen eines Netzwerk- oder CORS-Fehlers oder ungültigem WebVTT.

Nützlich ist die Eigenschaft, wenn du Cues per Skript auswerten willst, etwa für ein eigenes Untertitel-Overlay, ein durchsuchbares Transkript oder eine Kapitelnavigation. Bevor du auf track.track.cues zugreifst, solltest du prüfen, ob readyState === HTMLTrackElement.LOADED ist. Falls nicht, wartest du auf das load-Event des <track>-Elements.

Wichtig: Browser laden eine Textspur meist erst, wenn sie gebraucht wird, also wenn ihr mode auf "showing" oder "hidden" steht. Eine Spur mit mode = "disabled" bleibt oft dauerhaft bei NONE.

Rückgabewert

Typ

number

Beschreibung

0 (NONE), 1 (LOADING), 2 (LOADED) oder 3 (ERROR).

Beispiele

Ladezustand als lesbaren Text ausgeben

// HTML: <video src="film.mp4"><track id="de" kind="subtitles" src="de.vtt" srclang="de" default></video>
const trackEl = document.querySelector('#de');

const zustaende = {
  [HTMLTrackElement.NONE]: 'nicht geladen',
  [HTMLTrackElement.LOADING]: 'lädt …',
  [HTMLTrackElement.LOADED]: 'geladen',
  [HTMLTrackElement.ERROR]: 'Fehler'
};

console.log(`Untertitel: ${zustaende[trackEl.readyState]}`);

Untertitel: lädt …

Auf geladene Cues warten (Promise-Helfer)

const warteAufTrack = (trackEl) => new Promise((resolve, reject) => {
  if (trackEl.readyState === HTMLTrackElement.LOADED) return resolve(trackEl.track);
  if (trackEl.readyState === HTMLTrackElement.ERROR) return reject(new Error('Track konnte nicht geladen werden'));

  trackEl.addEventListener('load', () => resolve(trackEl.track), { once: true });
  trackEl.addEventListener('error', () => reject(new Error('Track konnte nicht geladen werden')), { once: true });

  // Laden anstoßen, ohne Untertitel sichtbar zu machen
  if (trackEl.track.mode === 'disabled') trackEl.track.mode = 'hidden';
});

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

try {
  const textTrack = await warteAufTrack(trackEl);
  console.log(`Anzahl Cues: ${textTrack.cues.length}`);
} catch (err) {
  console.error(err.message);
}

Anzahl Cues: 42

Transkript aus einer Kapitelspur bauen

const kapitelEl = document.querySelector('track[kind="chapters"]');
const liste = document.querySelector('#kapitel');
const video = document.querySelector('video');

const baueListe = () => {
  for (const cue of kapitelEl.track.cues) {
    const li = document.createElement('li');
    li.textContent = cue.text; // textContent statt innerHTML: kein XSS
    li.addEventListener('click', () => { video.currentTime = cue.startTime; });
    liste.append(li);
  }
};

kapitelEl.track.mode = 'hidden';
if (kapitelEl.readyState === HTMLTrackElement.LOADED) {
  baueListe();
} else {
  kapitelEl.addEventListener('load', baueListe, { once: true });
}

// Wichtig · Fallstricke

Lazy Loading: Solange der mode der Spur "disabled" ist, laden die meisten Browser die Datei gar nicht, und readyState bleibt 0. Setze track.mode = "hidden", wenn du Cues auslesen willst, ohne sie anzuzeigen.
Race Condition: Prüfe zuerst readyState und registriere erst danach den load-Listener. Ist die Spur schon geladen, wird das Event nicht erneut ausgelöst.
CORS: Liegen Video und VTT-Datei auf verschiedenen Origins, braucht das <video>-Element das Attribut crossorigin und der Server passende CORS-Header. Sonst endet die Spur mit ERROR (3).
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird still ignoriert bzw. wirft im Strict Mode einen TypeError.
Nicht verwechseln mit HTMLMediaElement.readyState: Dort gibt es andere Werte (0–4), die sich auf die Mediendaten beziehen.
Browser-Unterstützung: in allen modernen Browsern vorhanden (Chrome, Edge, Firefox, Safari), aber nicht im Internet Explorer.

Siehe auch

HTMLTrackElement.default HTMLTrackElement.kind HTMLTrackElement.label HTMLTrackElement.src HTMLTrackElement.srclang