TextTrackCue: exit — Ereignis · JavaScript-Referenz

Signatur

cue.addEventListener("exit", handler)

Beschreibung

Ein TextTrackCue (in der Praxis meist ein VTTCue) beschreibt einen Zeitabschnitt einer Textspur, etwa eine Untertitelzeile, ein Kapitel oder einen Metadaten-Eintrag. Das Ereignis exit wird ausgelöst, sobald die aktuelle Wiedergabezeit des Medienelements den Bereich zwischen startTime und endTime verlässt. Das passiert am Ende des Cues, beim Zurückspulen vor den Start oder beim Springen an eine andere Stelle.

Es ist das Gegenstück zu enter. Du kannst es auf zwei Arten abonnieren: mit cue.addEventListener("exit", handler) oder über die Eigenschaft cue.onexit = handler. Das Ereignis ist ein einfaches Event ohne zusätzliche Daten. Es steigt nicht auf (kein Bubbling) und lässt sich nicht abbrechen. Den betroffenen Cue bekommst du über event.target.

Typische Einsätze sind eigene Untertitel- oder Overlay-Darstellungen, die beim Verlassen eines Cues wieder ausgeblendet werden, das Zurücksetzen hervorgehobener Kapitel und das Beenden von Aktionen, die über metadata-Spuren gesteuert werden, zum Beispiel Werbeeinblendungen oder Quiz-Fragen.

Wichtig: Cues einer Spur mit mode = "disabled" lösen keine Ereignisse aus. Wenn du Cues ohne die eingebaute Anzeige verarbeiten willst, setze mode auf "hidden".

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"exit"`.
$handler Pflicht	(event: Event) => void		Callback-Funktion, die beim Verlassen des Cues aufgerufen wird. `event.target` ist der betroffene `TextTrackCue`.
$options	boolean \| AddEventListenerOptions	false	Optionale Angaben wie `once`, `signal` oder `capture`, wie bei `addEventListener` üblich.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein einfaches Event-Objekt.

Beispiele

Eigenes Untertitel-Overlay mit enter/exit

const video = document.querySelector('video');
const overlay = document.querySelector('#untertitel');

const track = video.addTextTrack('subtitles', 'Deutsch', 'de');
track.mode = 'hidden'; // Ereignisse ja, eingebaute Anzeige nein

const cue = new VTTCue(2, 5, 'Hallo und willkommen!');
cue.addEventListener('enter', (e) => {
  overlay.textContent = e.target.text;
});
cue.addEventListener('exit', () => {
  overlay.textContent = '';
  console.log('Cue verlassen bei', video.currentTime.toFixed(2));
});
track.addCue(cue);

Cue verlassen bei 5.01

on-Property und Entfernen des Listeners

const video = document.querySelector('video');
const track = video.addTextTrack('metadata');
track.mode = 'hidden';

const werbung = new VTTCue(10, 20, JSON.stringify({ id: 'ad-1' }));

// Variante 1: on-Property
werbung.onexit = (e) => {
  const { id } = JSON.parse(e.target.text);
  console.log(`Einblendung ${id} beendet`);
};

// Variante 2: benannte Funktion, später wieder entfernbar
const protokoll = () => console.log('exit protokolliert');
werbung.addEventListener('exit', protokoll);
track.addCue(werbung);

// Nach dem ersten Mal nicht mehr protokollieren
setTimeout(() => werbung.removeEventListener('exit', protokoll), 30_000);

Einblendung ad-1 beendet exit protokolliert

Kapitel-Hervorhebung für alle Cues einer geladenen Spur

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

trackEl.addEventListener('load', () => {
  const track = trackEl.track;
  track.mode = 'hidden';
  for (const cue of track.cues) {
    const eintrag = document.querySelector(`[data-cue-id="${cue.id}"]`);
    cue.onenter = () => eintrag?.classList.add('aktiv');
    cue.onexit = () => eintrag?.classList.remove('aktiv');
  }
});

// Wichtig · Fallstricke

Spur-Modus: Steht track.mode auf "disabled" (Standard bei <track> ohne default), feuern weder enter noch exit. Setze mode auf "hidden" oder "showing".
Zeitliche Genauigkeit: Die Cue-Zeiten werden nur bei jedem Durchlauf der Zeitaktualisierung geprüft, also etwa alle 15–250 ms. Deshalb kann exit leicht nach endTime kommen. Für bildgenaue Steuerung eignet sich requestVideoFrameCallback() besser.
Springen und Zurückspulen: exit feuert auch, wenn du aus einem aktiven Cue herausspringst. Hast du den Cue beim Springen komplett übersprungen, gibt es weder enter noch exit. In diesem Fall hilft cuechange an der TextTrack.
Kein Bubbling: Das Ereignis erreicht die TextTrack nicht. Wenn du viele Cues zentral überwachen willst, nimm TextTrack: cuechange zusammen mit activeCues.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome, Edge, Firefox, Safari). In älteren Safari-Versionen gab es Unregelmäßigkeiten beim Auslösen nach dem Springen. Teste das also, wenn es wichtig ist.
Sicherheit: Wenn Cue-Texte aus externen VTT-Dateien kommen, gib sie mit textContent aus und nicht mit innerHTML, um XSS zu vermeiden.

Siehe auch

TextTrackCue: enter TextTrackCue VTTCue TextTrack: cuechange TextTrack.activeCues HTMLMediaElement.addTextTrack() EventSource: error