HTMLTrackElement: cuechange — Ereignis · JavaScript-Referenz

Signatur

trackElement.addEventListener("cuechange", handler)

Beschreibung

Das Ereignis cuechange wird auf einem <track>-Element (HTMLTrackElement) ausgelöst, sobald sich die Menge der aktiven Cues des zugehörigen TextTrack ändert. Das passiert, wenn während der Wiedergabe ein Cue beginnt oder endet oder wenn der Nutzer an eine andere Stelle springt. Dasselbe Ereignis wird auch direkt auf dem TextTrack-Objekt (trackElement.track) ausgelöst.

Registrieren kann man es mit addEventListener("cuechange", handler) oder über die Eigenschaft oncuechange. Das Ereignis ist ein einfaches Event, steigt nicht auf (bubbelt nicht) und kann nicht abgebrochen werden. Welche Cues gerade aktiv sind, liest man im Handler aus event.target.track.activeCues (beim Track-Element) oder aus event.target.activeCues (beim TextTrack).

Typische Einsatzzwecke sind eigene Untertitel-Darstellungen (z. B. ein gestaltetes Overlay statt der Browser-Anzeige), synchronisierte Transkripte, Kapitelnavigation und das Auswerten von metadata-Tracks, mit denen man zeitgesteuert Inhalte der Seite ändert (etwa Folien, Produkthinweise oder Quiz-Fragen).

Wichtig: Cues werden nur geladen und aktiv, wenn der Track-Modus "showing" oder "hidden" ist. Bei "disabled" (Standard für nicht voreingestellte Tracks) feuert cuechange nicht.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"cuechange"`.
$handler Pflicht	(event: Event) => void		Callback, der bei jeder Änderung der aktiven Cues aufgerufen wird. `event.target` ist das `HTMLTrackElement` bzw. der `TextTrack`.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once`, `signal` oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event-Objekt ohne zusätzliche Eigenschaften.

Beispiele

Aktive Untertitel in eigenem Overlay anzeigen

// HTML: <video id="video" src="film.mp4" controls>
//         <track id="subs" kind="subtitles" src="de.vtt" srclang="de" default>
//       </video>
//       <div id="overlay"></div>
const trackEl = document.getElementById('subs');
const overlay = document.getElementById('overlay');

// Browser-Anzeige ausblenden, Cues aber weiterhin aktiv halten
trackEl.track.mode = 'hidden';

trackEl.addEventListener('cuechange', (event) => {
  const cues = event.target.track.activeCues;
  const text = Array.from(cues ?? [], (cue) => cue.text).join('\n');
  overlay.textContent = text;
  console.log('Aktive Cues:', cues?.length ?? 0);
});

Aktive Cues: 1 Aktive Cues: 0

Über die on-Property und direkt am TextTrack

const video = document.querySelector('video');
const track = video.textTracks[0];
track.mode = 'hidden';

// Variante 1: on-Property am TextTrack
track.oncuechange = () => {
  const cue = track.activeCues?.[0];
  if (cue) console.log(`[${cue.startTime.toFixed(1)}s] ${cue.text}`);
};

// Handler wieder entfernen
// track.oncuechange = null;

[3.0s] Hallo und willkommen!

Metadaten-Track steuert Folienwechsel, Listener wieder entfernen

// <track id="meta" kind="metadata" src="folien.vtt">
// Cue-Text z. B.: {"slide": 4}
const metaTrack = document.getElementById('meta');
metaTrack.track.mode = 'hidden';

const onCueChange = () => {
  for (const cue of metaTrack.track.activeCues ?? []) {
    const { slide } = JSON.parse(cue.text);
    document.querySelector('#folie').src = `folien/${slide}.png`;
    console.log('Wechsel zu Folie', slide);
  }
};

metaTrack.addEventListener('cuechange', onCueChange);

// Beim Verlassen der Präsentation aufräumen
document.getElementById('beenden').addEventListener('click', () => {
  metaTrack.removeEventListener('cuechange', onCueChange);
});

Wechsel zu Folie 4

// Wichtig · Fallstricke

Track-Modus beachten: Bei track.mode === "disabled" werden keine Cues geladen, und cuechange feuert nicht. Für eigene Darstellungen "hidden" setzen.
Das Ereignis sagt nur, dass sich etwas geändert hat. Welche Cues hinzugekommen oder weggefallen sind, muss man selbst über activeCues oder die enter- und exit-Ereignisse einzelner VTTCue-Objekte ermitteln.
activeCues kann null sein, solange der Track nicht geladen ist. Deshalb defensiv mit ?. bzw. ?? [] zugreifen.
Das Ereignis wird nicht exakt zum Zeitpunkt eines Cues ausgelöst, sondern im Rhythmus der Zeitaktualisierung der Wiedergabe (ähnlich timeupdate, meist alle 15–250 ms). Für bildgenaue Synchronisation ist es nicht geeignet.
Die Cue-Texte kommen aus externen WebVTT-Dateien. Nicht ungeprüft per innerHTML einfügen (XSS-Gefahr), sondern textContent oder cue.getCueAsHTML() verwenden.
WebVTT-Dateien von fremden Domains brauchen CORS und am Medienelement das Attribut crossorigin.
Browser-Kompatibilität: wird von allen modernen Browsern (Chrome, Firefox, Safari, Edge) unterstützt. In älteren Firefox-Versionen feuerte das Ereignis teils nur am TextTrack. Wer auf Nummer sicher gehen will, registriert am TextTrack.

Siehe auch

HTMLElement: change HTMLMediaElement: ratechange HTMLMediaElement: volumechange HTMLSlotElement: slotchange HTMLDialogElement: cancel