new DataCue() — Methode · JavaScript-Referenz

Signatur

new DataCue(startTime, endTime, value, type)

Beschreibung

Der Konstruktor DataCue() legt eine zeitgesteuerte Metadaten-Markierung (Cue) an. Anders als VTTCue, das nur Text für Untertitel enthält, kann ein DataCue einen beliebigen JavaScript-Wert tragen, zum Beispiel ein Objekt, einen String oder einen ArrayBuffer. Damit lassen sich Kapitelinformationen, Werbe-Marker, Geodaten oder Sportstatistiken exakt mit der Medienzeitleiste synchronisieren.

Der Cue wird über TextTrack.addCue() einer Textspur hinzugefügt, typischerweise einer Spur mit kind = "metadata", die mit HTMLMediaElement.addTextTrack() erzeugt wird. Sobald die Wiedergabezeit den Zeitraum des Cues erreicht, lösen der Cue die Events enter und exit und die Spur das Event cuechange aus.

Über den optionalen Parameter type gibt man an, welches Format der Wert hat, etwa "org.id3" für ID3-Tags oder einen eigenen Bezeichner wie "com.example.chapter". So kann der Code, der die Cues verarbeitet, verschiedene Arten von Metadaten auseinanderhalten.

Parameter

Name	Typ	Default	Beschreibung
$startTime Pflicht	number		Startzeit des Cues in Sekunden, bezogen auf die Medienzeitleiste.
$endTime Pflicht	number		Endzeit in Sekunden. Mit `Infinity` läuft der Cue bis zum Ende des Mediums (nicht begrenzter Cue).
$value Pflicht	any		Die Nutzdaten des Cues, ein beliebiger JavaScript-Wert (Objekt, String, `ArrayBuffer` …). Später lesbar über `DataCue.value`.
$type	string	""	Bezeichner für das Format von `value`, z. B. `"org.id3"` oder ein eigener Reverse-Domain-Name. Später lesbar über `DataCue.type`.

Rückgabewert

Typ

DataCue

Beschreibung

Ein neues DataCue-Objekt, das noch keiner Spur zugeordnet ist (track ist null), bis man es mit TextTrack.addCue() hinzufügt.

Beispiele

Cue anlegen und Eigenschaften auslesen

const cue = new DataCue(10, 20, { kapitel: 'Einleitung' }, 'com.example.chapter');

console.log(cue.startTime, cue.endTime);
console.log(cue.type);
console.log(cue.value.kapitel);

10 20 com.example.chapter Einleitung

Kapitelmarken mit einer Metadaten-Spur synchronisieren

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

const kapitel = [
  { start: 0, end: 30, titel: 'Intro' },
  { start: 30, end: 120, titel: 'Hauptteil' },
  { start: 120, end: Infinity, titel: 'Abspann' }
];

for (const k of kapitel) {
  track.addCue(new DataCue(k.start, k.end, { titel: k.titel }, 'com.example.chapter'));
}

track.addEventListener('cuechange', () => {
  const aktiv = track.activeCues[0];
  if (aktiv) {
    document.querySelector('#kapitel').textContent = aktiv.value.titel;
  }
});

Feature-Erkennung mit Fallback auf VTTCue

const erzeugeMetadatenCue = (start, ende, daten) => {
  if ('DataCue' in window) {
    return new DataCue(start, ende, daten, 'com.example.json');
  }
  // Fallback: Daten als JSON-Text in einem VTTCue speichern
  return new VTTCue(start, ende, JSON.stringify(daten));
};

const cue = erzeugeMetadatenCue(5, 8, { werbung: true });
const daten = 'value' in cue && typeof cue.value === 'object'
  ? cue.value
  : JSON.parse(cue.text);
console.log(daten.werbung);

true

// Wichtig · Fallstricke

Browser-Kompatibilität: DataCue ist ein experimenteller WICG-Entwurf und wird derzeit praktisch nur von Safari/WebKit unterstützt. Chrome und Firefox bieten den Konstruktor nicht an, deshalb immer mit 'DataCue' in window prüfen und einen Fallback (z. B. VTTCue mit JSON im Text) vorsehen.
Ältere WebKit-Versionen kannten eine veraltete Form mit ArrayBuffer als drittem Argument und der Eigenschaft data. Für neuen Code nur value und type verwenden.
Der Aufruf ohne new wirft einen TypeError.
Damit Cues Events auslösen, muss track.mode auf "hidden" oder "showing" stehen. Bei "disabled" (Standard bei manchen Spuren) passiert nichts.
Bei HLS-Streams erzeugt Safari für eingebettete ID3-Metadaten selbst DataCue-Objekte mit type = "org.id3". Diese liest man über video.textTracks aus, statt sie selbst anzulegen.

Siehe auch

DataCue TextTrackCue VTTCue TextTrack.prototype.addCue() HTMLMediaElement.prototype.addTextTrack() new BroadcastChannel()