TextTrack.activeCues — Eigenschaft · JavaScript-Referenz

Signatur

TextTrack.activeCues

Beschreibung

Die schreibgeschützte Eigenschaft activeCues der Schnittstelle TextTrack gibt ein TextTrackCueList-Objekt zurück. Es enthält alle Cues der Spur, deren Zeitbereich (startTime bis endTime) die aktuelle Wiedergabeposition des zugehörigen <video>- oder <audio>-Elements einschließt. Überlappen sich mehrere Cues zeitlich, sind alle gleichzeitig enthalten.

Gebraucht wird die Eigenschaft vor allem dann, wenn du Untertitel, Kapitelmarken oder Metadaten selbst darstellen willst, statt die eingebaute Anzeige des Browsers zu nutzen: etwa für eigene Untertitel-Layouts, interaktive Transkripte oder synchronisierte Inhalte über kind="metadata". Meistens liest man activeCues im Event cuechange der Spur aus. Dieses Event wird immer dann ausgelöst, wenn sich die Menge der aktiven Cues ändert.

Wichtig: Die Liste wird nur gefüllt, wenn der mode der Spur "showing" oder "hidden" ist. Im Modus "disabled" gibt die Eigenschaft null zurück. Soll der Browser selbst nichts anzeigen, du die Cues aber auswerten willst, setzt du den Modus auf "hidden".

Rückgabewert

Typ

TextTrackCueList | null

Beschreibung

Eine Live-Liste der aktuell aktiven TextTrackCue-Objekte (in der Praxis meist VTTCue). Hat die Spur den Modus "disabled", ist der Wert null.

Beispiele

Eigene Untertitel-Anzeige über cuechange

// HTML: <video id="player" src="film.mp4" controls>
//         <track kind="subtitles" src="de.vtt" srclang="de" default>
//       </video>
//       <div id="untertitel"></div>
const video = document.getElementById('player');
const ausgabe = document.getElementById('untertitel');
const spur = video.textTracks[0];

// Browser-Anzeige ausblenden, Cues aber weiter auswerten
spur.mode = 'hidden';

spur.addEventListener('cuechange', () => {
  const aktive = spur.activeCues;
  // textContent statt innerHTML, um XSS aus VTT-Dateien zu vermeiden
  ausgabe.textContent = Array.from(aktive ?? [])
    .map((cue) => cue.text)
    .join('\n');
});

Aktive Cues zu einem Zeitpunkt protokollieren

const video = document.querySelector('video');
const spur = video.addTextTrack('captions', 'Deutsch', 'de');
spur.mode = 'hidden';

spur.addCue(new VTTCue(0, 5, 'Hallo und willkommen!'));
spur.addCue(new VTTCue(3, 8, '[Musik setzt ein]'));

video.currentTime = 4;
video.addEventListener('seeked', () => {
  // activeCues wird asynchron aktualisiert – daher auf cuechange warten
  spur.addEventListener('cuechange', () => {
    for (const cue of spur.activeCues) {
      console.log(`${cue.startTime}–${cue.endTime}: ${cue.text}`);
    }
  }, { once: true });
});

0–5: Hallo und willkommen! 3–8: [Musik setzt ein]

Kapitelanzeige mit kind="chapters"

const video = document.querySelector('video');
const kapitelSpur = Array.from(video.textTracks)
  .find((t) => t.kind === 'chapters');

if (kapitelSpur) {
  kapitelSpur.mode = 'hidden';
  kapitelSpur.oncuechange = () => {
    const cue = kapitelSpur.activeCues?.[0];
    document.title = cue ? `Kapitel: ${cue.text}` : 'Video';
  };
}

// Wichtig · Fallstricke

Modus beachten: Bei mode = "disabled" (der Standard für Spuren ohne default) ist activeCues null. Nutze deshalb optionale Verkettung (?.) oder ?? [].
Timing: Die Liste wird während der Wiedergabe aktualisiert, nicht sofort beim Setzen von currentTime. Lies sie im Event cuechange aus und nicht direkt nach einem Sprung.
Live-Liste: Die TextTrackCueList ist kein Array. Mit Array.from() machst du daraus eines, dann stehen map/filter zur Verfügung. Die Liste ist iterierbar und lässt sich über den Index oder getCueById() ansprechen.
Sicherheit: Der Text von Cues stammt aus externen VTT-Dateien. Füge ihn nicht ungeprüft per innerHTML ein (XSS-Gefahr). Nutze textContent oder VTTCue.getCueAsHTML().
CORS: <track>-Dateien von fremden Origins werden nur geladen, wenn das Medienelement das Attribut crossorigin hat und der Server passende CORS-Header sendet. Andernfalls bleibt die Liste leer.
Die Eigenschaft wird von allen modernen Browsern unterstützt. VTTCue fehlte in alten Edge-Versionen (EdgeHTML), dort gab es nur TextTrackCue.

Siehe auch

TextTrack TextTrack.cues TextTrack.mode TextTrackCueList HTMLMediaElement.textTracks