TextTrackCue.id — Eigenschaft · JavaScript-Referenz

Signatur

TextTrackCue.id

Beschreibung

Die Eigenschaft id der Schnittstelle TextTrackCue enthält den Bezeichner einer einzelnen Cue, also eines Untertitel-, Kapitel- oder Metadaten-Eintrags innerhalb eines TextTrack. Sie ist lesbar und beschreibbar. Ist kein Bezeichner gesetzt, ist ihr Wert ein leerer String.

Bei Cues aus einer WebVTT-Datei entspricht id der optionalen Kennungszeile direkt über der Zeitangabe (zum Beispiel intro vor 00:00:01.000 --> 00:00:04.000). Bei Cues, die per JavaScript mit new VTTCue() erzeugt werden, legst du die Kennung selbst fest.

In der Praxis brauchst du id vor allem, um bestimmte Cues wiederzufinden, etwa mit track.cues.getCueById("kapitel-2"). Außerdem kannst du damit Cues im cuechange-Handler auseinanderhalten oder Kapitelmarken mit Einträgen einer Bedienoberfläche verknüpfen. Der Browser erzwingt keine Eindeutigkeit. Wenn du Cues über ihre Kennung ansprechen willst, musst du selbst darauf achten, dass jede Kennung nur einmal vorkommt.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Nur beim Setzen: der neue Bezeichner der Cue. Andere Werte werden in einen String umgewandelt.

Rückgabewert

Typ

string

Beschreibung

Der Bezeichner der Cue. Ist keiner gesetzt, ist es ein leerer String "".

Beispiele

Cue mit Kennung erzeugen und wiederfinden

const video = document.querySelector("video");
const track = video.addTextTrack("chapters", "Kapitel", "de");
track.mode = "hidden";

const cue = new VTTCue(0, 30, "Einleitung");
cue.id = "kapitel-1";
track.addCue(cue);

const gefunden = track.cues.getCueById("kapitel-1");
console.log(gefunden.text, gefunden.startTime);

Einleitung 0

Aktive Cue im cuechange-Handler erkennen

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

track.addEventListener("cuechange", () => {
  for (const cue of track.activeCues) {
    console.log(`Aktiv: ${cue.id || "(ohne ID)"} – ${cue.text}`);
  }
});

Aktiv: intro – Willkommen!

Kapitelnavigation aus Cue-IDs aufbauen

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

trackEl.addEventListener("load", () => {
  const { cues } = trackEl.track;
  for (const cue of cues) {
    const btn = document.createElement("button");
    btn.textContent = cue.text;
    btn.dataset.cueId = cue.id;
    btn.addEventListener("click", () => {
      video.currentTime = cues.getCueById(btn.dataset.cueId).startTime;
    });
    nav.append(btn);
  }
});
trackEl.track.mode = "hidden";

// Wichtig · Fallstricke

Keine Eindeutigkeit garantiert: Mehrere Cues dürfen dieselbe id haben. getCueById() liefert dann nur die erste passende Cue.
Cues erst nach dem Laden verfügbar: track.cues ist null, solange der mode "disabled" ist. Setze ihn auf "hidden" oder "showing" und warte auf das load-Ereignis des <track>-Elements.
Eine WebVTT-Kennung darf keine Zeilenumbrüche und keine Zeichenfolge --> enthalten.
Wenn du die id nachträglich änderst, wird die Cue nicht neu angezeigt. Das Ändern hat keinen sichtbaren Effekt.
Kompatibilität: wird von allen modernen Browsern unterstützt. TextTrackCue selbst ist abstrakt. Konkrete Instanzen erzeugst du mit VTTCue.

Siehe auch

ImageTrack.selected TextTrackCue.track TextTrackCue.endTime TextTrackCue.startTime TextTrackCue.pauseOnExit