TextTrackCue: enter — Ereignis · JavaScript-Referenz

Signatur

cue.addEventListener("enter", handler)

Beschreibung

Das enter-Ereignis gehört zu TextTrackCue (und damit auch zu VTTCue). Es wird ausgelöst, sobald die aktuelle Wiedergabezeit eines <video>- oder <audio>-Elements in den Bereich zwischen startTime und endTime des Cues gelangt. Der Cue gehört dann zur Liste TextTrack.activeCues.

Du kannst den Handler mit cue.addEventListener("enter", handler) registrieren oder über die Eigenschaft cue.onenter = handler setzen. Das Ereignis ist ein einfaches Event ohne weitere Daten, bubbelt nicht und lässt sich nicht abbrechen. Welcher Cue gemeint ist, erfährst du über event.target.

Typische Einsatzfälle sind Aktionen, die an bestimmte Zeitpunkte gebunden sind: eigene Untertitel-Darstellung, Kapitelmarken, Quizfragen oder Einblendungen in interaktiven Videos, Analyse-Ereignisse oder Metadaten-Spuren (kind="metadata"), deren Inhalte (z. B. JSON im text eines VTTCue) per Skript ausgewertet werden. Das Gegenstück ist das Ereignis exit. Brauchst du nur allgemein Änderungen an den aktiven Cues einer Spur, ist TextTrack: cuechange meist praktischer.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"enter"`.
$handler Pflicht	(event: Event) => void		Callback, der beim Aktivwerden des Cues aufgerufen wird. `event.target` ist der betroffene `TextTrackCue`.
$options	boolean \| AddEventListenerOptions	false	Optionen 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

Einblendung mit addEventListener auslösen

const video = document.querySelector('video');
const track = video.addTextTrack('metadata', 'Einblendungen');
track.mode = 'hidden'; // Cues werden ausgewertet, aber nicht angezeigt

const cue = new VTTCue(5, 10, JSON.stringify({ hinweis: 'Jetzt 20 % Rabatt!' }));
cue.addEventListener('enter', (event) => {
  const { hinweis } = JSON.parse(event.target.text);
  console.log(`Cue aktiv ab ${event.target.startTime}s: ${hinweis}`);
});
track.addCue(cue);

Cue aktiv ab 5s: Jetzt 20 % Rabatt!

enter und exit über on-Properties koppeln

const video = document.querySelector('video');
const banner = document.querySelector('#kapitel');
const track = video.addTextTrack('chapters', 'Kapitel');
track.mode = 'hidden';

const kapitel = [
  [0, 30, 'Einleitung'],
  [30, 90, 'Installation'],
  [90, 150, 'Konfiguration']
];

for (const [start, ende, titel] of kapitel) {
  const cue = new VTTCue(start, ende, titel);
  cue.onenter = () => { banner.textContent = titel; };
  cue.onexit = () => { banner.textContent = ''; };
  track.addCue(cue);
}

Listener einmalig oder per AbortController entfernen

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

const cue = new VTTCue(12, 15, 'quiz-1');
const controller = new AbortController();

const zeigeQuiz = (event) => {
  video.pause();
  console.log('Quiz startet:', event.target.text);
};

// Nur beim ersten Erreichen auslösen, zusätzlich abbrechbar
cue.addEventListener('enter', zeigeQuiz, { once: true, signal: controller.signal });
track.addCue(cue);

// Später, z. B. wenn der Nutzer Quizfragen deaktiviert:
// controller.abort();  oder  cue.removeEventListener('enter', zeigeQuiz);

Quiz startet: quiz-1

// Wichtig · Fallstricke

Spurmodus: Ereignisse werden nur ausgelöst, wenn der TextTrack den Modus "hidden" oder "showing" hat. Bei "disabled" (Standard für viele <track>-Elemente ohne default) kommt kein enter an.
Timing ist ungenau: Die Prüfung läuft im Takt von timeupdate, also etwa alle 15–250 ms. Für bildgenaue Synchronisation reicht das nicht. Dafür eignet sich HTMLVideoElement.requestVideoFrameCallback().
Springen: Überspringt der Nutzer einen kurzen Cue beim Spulen komplett, feuern enter und exit trotzdem oft direkt nacheinander. Verlass dich also nicht darauf, dass der Cue sichtbar war.
Das Ereignis bubbelt nicht zum TextTrack oder Medienelement. Du musst den Listener direkt am Cue registrieren. Für alle Cues einer Spur ist cuechange einfacher.
Cues aus einer <track>-Datei stehen erst nach dem load-Ereignis des Track-Elements in track.cues bereit.
Kompatibilität: Chrome, Edge, Firefox und Safari unterstützen das Ereignis. VTTCue ist der konkret nutzbare Konstruktor, denn TextTrackCue selbst lässt sich nicht instanziieren.

Siehe auch

TextTrackCue: exit TextTrack: cuechange TextTrackCue VTTCue TextTrack.activeCues HTMLMediaElement.addTextTrack() Element: pointerenter