DataCue — Schnittstelle · JavaScript-Referenz

Signatur

interface DataCue extends TextTrackCue

Beschreibung

Die Schnittstelle DataCue erweitert TextTrackCue um beliebige Nutzdaten. Anders als VTTCue ist sie nicht für sichtbare Untertitel gedacht, sondern für Metadaten: Ein Cue hat eine Start- und Endzeit sowie einen frei wählbaren Wert (value) und eine Typkennung (type). Solche Cues liegen typischerweise in einem TextTrack der Art "metadata" und werden nie dargestellt.

Es gibt zwei typische Einsatzfälle:

Selbst erzeugte Cues: Du hängst eigene Daten an Zeitpunkte eines Videos, etwa Kapitelinfos, Quiz-Einblendungen, Produkt-Links oder Analytics-Marker. Über das Ereignis cuechange bzw. enter/exit reagierst du während der Wiedergabe darauf.
Metadaten aus dem Medienstrom: Der Browser macht eingebettete Metadaten zugänglich, z. B. ID3-Tags in HLS-Streams (type "org.id3") oder emsg-Boxen in MPEG-DASH/CMAF. Das wird unter anderem für serverseitig eingefügte Werbung (SCTE-35) oder Live-Titelinformationen genutzt.

Die Schnittstelle erbt von TextTrackCue die Eigenschaften id, startTime, endTime, pauseOnExit und track sowie die Ereignisse enter und exit. Neu hinzu kommen value (beliebiger Wert) und type (Zeichenkette zur Einordnung der Daten).

Parameter

Name	Typ	Default	Beschreibung
$startTime Pflicht	number		Startzeit des Cues in Sekunden, bezogen auf die Medien-Zeitleiste.
$endTime Pflicht	number		Endzeit des Cues in Sekunden. Für unbegrenzte Cues kann in neueren Implementierungen `Infinity` angegeben werden.
$value Pflicht	any		Die angehängten Daten – beliebiger Wert (Objekt, String, `ArrayBuffer` …). Später über `cue.value` lesbar und änderbar.
$type	string	""	Kennung für die Art der Daten, z. B. `"org.id3"` oder eine eigene Kennung wie `"com.example.chapter"`. Hilft, verschiedene Metadatenquellen auseinanderzuhalten.

Rückgabewert

Typ

DataCue

Beschreibung

Der Konstruktor new DataCue(startTime, endTime, value, type) liefert einen neuen Cue, der mit TextTrack.addCue() einer Spur hinzugefügt werden kann.

Beispiele

Funktionsprüfung und Cue erzeugen

if ('DataCue' in window) {
  const cue = new DataCue(5, 10, { kapitel: 'Einleitung' }, 'com.example.chapter');
  console.log(cue.startTime, cue.endTime, cue.type, cue.value.kapitel);
} else {
  console.log('DataCue wird nicht unterstützt – Fallback auf VTTCue mit JSON');
}

5 10 com.example.chapter Einleitung

Eigene Metadaten-Spur mit cuechange auswerten

const video = document.querySelector('video');
const track = video.addTextTrack('metadata', 'Produkte');
track.mode = 'hidden'; // Ereignisse auslösen, aber nichts anzeigen

const produkte = [
  { start: 12, ende: 20, daten: { name: 'Sneaker', url: '/shop/sneaker' } },
  { start: 45, ende: 55, daten: { name: 'Rucksack', url: '/shop/rucksack' } }
];

for (const { start, ende, daten } of produkte) {
  track.addCue(new DataCue(start, ende, daten, 'com.example.product'));
}

const box = document.querySelector('#produkt-hinweis');
track.addEventListener('cuechange', () => {
  const [aktiv] = track.activeCues;
  box.textContent = aktiv ? `Jetzt im Video: ${aktiv.value.name}` : '';
});

ID3-Metadaten aus einem HLS-Stream lesen (Safari)

const video = document.querySelector('video');
video.src = 'https://example.com/live/stream.m3u8';

video.textTracks.addEventListener('addtrack', ({ track }) => {
  if (track.kind !== 'metadata') return;
  track.mode = 'hidden';

  track.addEventListener('cuechange', () => {
    for (const cue of track.activeCues) {
      if (cue instanceof DataCue && cue.type === 'org.id3') {
        // value hat z. B. die Form { key: 'TIT2', data: 'Songtitel' }
        console.log(`${cue.value.key}: ${cue.value.data}`);
      }
    }
  });
});

TIT2: Songtitel

Cue mit enter/exit und nachträglichem Entfernen

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

const quiz = new DataCue(30, 31, { frage: 'Was ist ein Closure?' }, 'com.example.quiz');
quiz.pauseOnExit = true; // Video hält am Ende des Cues an

const onEnter = () => console.log('Quiz:', quiz.value.frage);
quiz.addEventListener('enter', onEnter);
track.addCue(quiz);

// Später: Quiz wieder entfernen
const entferneQuiz = () => {
  quiz.removeEventListener('enter', onEnter);
  track.removeCue(quiz);
};

Quiz: Was ist ein Closure?

// Wichtig · Fallstricke

Browser-Kompatibilität: DataCue ist experimentell und basiert auf einem WICG-Entwurf. Vollständig verfügbar ist sie vor allem in Safari/WebKit (dort auch für native HLS-ID3-Metadaten). In Chromium- und Firefox-Versionen fehlt sie meist oder ist nur hinter Flags aktiv. Prüfe immer mit 'DataCue' in window und nimm als Fallback einen VTTCue, dessen text JSON enthält.

Ältere WebKit-Versionen hatten zusätzlich die veraltete Eigenschaft data (ArrayBuffer) und einen Konstruktor new DataCue(start, end, arrayBuffer). Verwende in neuem Code value.
Der mode der Spur muss "hidden" oder "showing" sein, sonst gibt es keine cuechange-Ereignisse und activeCues bleibt leer. Bei Metadaten-Spuren ist "hidden" sinnvoll.
cuechange wird nicht bildgenau ausgelöst (Takt von timeupdate, etwa alle 15–250 ms). Für sehr kurze Cues können Ereignisse ausfallen, wenn die Wiedergabe springt.
Die Struktur von value bei Metadaten aus dem Stream (z. B. org.id3) hängt vom Browser ab. Vorsicht bei Daten aus fremden Streams: Niemals ungeprüft per innerHTML einfügen (XSS), sondern textContent nutzen.
Mit Media Source Extensions (hls.js, dash.js) erzeugt der Browser keine Stream-Cues selbst – diese Bibliotheken lesen die Metadaten aus und legen die Cues selbst an.

Siehe auch

VTTCue Cache Attr CSSValue Fence