DataCue.type — Eigenschaft · JavaScript-Referenz

Signatur

DataCue.type

Beschreibung

Die Eigenschaft type einer DataCue sagt, wie der Inhalt von value zu verstehen ist. Ein DataCue ist ein Cue für beliebige zeitgesteuerte Metadaten in einem TextTrack vom Typ "metadata". Das können ID3-Tags aus einem HLS-Stream sein, QuickTime-Metadaten oder eigene Daten der Anwendung wie Kapitelmarken, Werbe-Marker oder Positionsdaten.

Da value jeden beliebigen Wert enthalten kann, braucht man type als Unterscheidungsmerkmal. Mehrere Metadaten-Formate können in derselben Spur liegen, und anhand von type wählt die Anwendung die passende Verarbeitung. Bei Cues, die der Browser aus dem Medium erzeugt, ist der Wert ein festgelegter Bezeichner, etwa "org.id3", "com.apple.quicktime.udta", "com.apple.quicktime.mdta" oder "com.apple.itunes". Bei selbst erzeugten Cues übergibt man den Typ als viertes Argument an den Konstruktor new DataCue(startTime, endTime, value, type).

Die Eigenschaft ist schreibgeschützt. Den Typ legt man beim Erzeugen fest, danach lässt er sich nicht mehr ändern. Für eigene Daten empfiehlt sich ein eindeutiger Bezeichner in umgekehrter Domain-Schreibweise wie "com.example.chapter", damit er nicht mit den Typen des Browsers kollidiert.

Rückgabewert

Typ

string

Beschreibung

Bezeichner für den Typ oder das Schema der Daten in value. Wurde im Konstruktor kein Typ übergeben, ist es ein leerer String "".

Beispiele

Eigene Kapitelmarken mit Typ anlegen und auslesen

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

const cue = new DataCue(0, 30, { title: 'Einleitung' }, 'com.example.chapter');
track.addCue(cue);

console.log(cue.type);
console.log(cue.value.title);

com.example.chapter Einleitung

ID3-Metadaten aus einem HLS-Stream nach Typ filtern

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.type !== 'org.id3') continue;
      // value ist bei ID3 ein Objekt mit key/data (WebKit)
      console.log(`ID3 ${cue.value.key}:`, cue.value.data);
    }
  });
});

ID3 TIT2: Morgennachrichten

Verarbeitung je nach Typ verteilen (mit Feature-Erkennung)

const handlers = {
  'com.example.chapter': (v) => console.log('Kapitel:', v.title),
  'com.example.ad': (v) => console.log('Werbung startet:', v.id),
};

const handleCue = (cue) => {
  const handler = handlers[cue.type];
  handler ? handler(cue.value) : console.warn('Unbekannter Typ:', cue.type);
};

if ('DataCue' in window) {
  handleCue(new DataCue(10, 15, { id: 'spot-42' }, 'com.example.ad'));
} else {
  console.log('DataCue wird nicht unterstützt');
}

Werbung startet: spot-42

// Wichtig · Fallstricke

Kompatibilität: DataCue ist eine experimentelle WICG-Spezifikation. Zuverlässig verfügbar ist sie nur in Safari/WebKit. Vor der Verwendung mit 'DataCue' in window prüfen und für andere Browser eine Alternative vorsehen, z. B. VTTCue mit JSON in text.
Schreibgeschützt: Eine Zuweisung an cue.type hat keine Wirkung und wirft im Strict Mode einen TypeError.
Ohne das vierte Konstruktor-Argument ist type ein leerer String. Bei selbst erzeugten Cues daher immer einen Typ angeben.
Die Typ-Bezeichner und der Aufbau von value bei Cues, die der Browser erzeugt (z. B. "org.id3"), hängen von der Implementierung ab. Deshalb den Inhalt von value vorsichtig auswerten.
Metadaten aus fremden Streams sind nicht vertrauenswürdig. Inhalte aus value nie ungeprüft per innerHTML ins DOM schreiben, sonst droht XSS.
Die ältere WebKit-Eigenschaft data (ein ArrayBuffer) ist veraltet. Stattdessen value zusammen mit type verwenden.

Siehe auch

CSSRule.type DataCue.value VTTCue.line VTTCue.size VTTCue.text