DataCue.value — Eigenschaft · JavaScript-Referenz

Signatur

DataCue.value

Beschreibung

Die Eigenschaft DataCue.value enthält die eigentlichen Daten eines DataCue. Ein solcher Cue ist ein zeitgesteuerter Eintrag in einer TextTrack der Art "metadata". Anders als ein VTTCue, der Untertiteltext enthält, kann value jeden beliebigen JavaScript-Wert aufnehmen, zum Beispiel ein Objekt, ein Array, eine Zeichenkette oder einen ArrayBuffer.

Typische Einsatzfälle sind Zeitmetadaten in Videostreams: ID3-Tags in HLS-Streams, Werbemarker (SCTE-35), Kapitel- oder Produktinformationen und Synchronisationspunkte für Inhalte, die zusätzlich zum Video angezeigt werden. Welches Format die Daten haben, steht in der Eigenschaft DataCue.type, zum Beispiel "org.id3". Anhand von type weiß die Anwendung, wie sie value auslesen muss.

Cues, die der Browser selbst aus dem Medienstrom erzeugt, befüllt er automatisch. Safari liefert ID3-Frames zum Beispiel als Objekt mit Feldern wie key, data und info. Eigene Cues erstellen Sie mit new DataCue(startTime, endTime, value, type). Den Wert können Sie später durch direkte Zuweisung ändern.

Rückgabewert

Typ

any

Beschreibung

Die Nutzdaten des Cues. Das kann ein beliebiger Wert sein, etwa ein Objekt, eine Zeichenkette, eine Zahl oder ein ArrayBuffer. Die Eigenschaft ist beschreibbar.

Beispiele

Eigenen Metadaten-Cue mit Objekt-Nutzlast anlegen

const video = document.querySelector('video');
const track = video.addTextTrack('metadata', 'Kapitel');

if ('DataCue' in window) {
  const cue = new DataCue(10, 20, { kapitel: 'Einleitung', id: 1 }, 'de.example.kapitel');
  track.addCue(cue);
  console.log(cue.value.kapitel);
} else {
  console.log('DataCue wird nicht unterstützt');
}

Einleitung

Beim Abspielen aktive Metadaten auswerten (cuechange)

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

track.addCue(new DataCue(5, 8, { produkt: 'Kamera X', preis: 499 }, 'de.example.produkt'));

track.addEventListener('cuechange', () => {
  for (const cue of track.activeCues) {
    if (cue.type === 'de.example.produkt') {
      const { produkt, preis } = cue.value;
      console.log(`Jetzt im Bild: ${produkt} für ${preis} €`);
    }
  }
});

Jetzt im Bild: Kamera X für 499 € (bei Sekunde 5)

ID3-Metadaten eines HLS-Streams in Safari lesen

const video = document.querySelector('video');

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' && cue.value) {
        // Safari: { key: 'TXXX', info: '...', data: '...' }
        console.log(cue.value.key, cue.value.data);
      }
    }
  });
});

TXXX {"event":"werbung-start"}

Nutzlast nachträglich ändern

const cue = new DataCue(0, 5, 'Entwurf', 'text/plain');
cue.value = { status: 'final', version: 2 };
console.log(cue.value.status);

final

// Wichtig · Fallstricke

Kompatibilität: DataCue ist experimentell und wird im WICG-Entwurf „DataCue“ spezifiziert. Nur WebKit/Safari unterstützt es zuverlässig. Chromium und Firefox kennen die Schnittstelle nicht. Prüfen Sie die Unterstützung daher immer vorher mit 'DataCue' in window und sehen Sie für andere Browser einen Ersatzweg vor, zum Beispiel einen VTTCue mit JSON-Text in text.
Ältere WebKit-Versionen hatten zusätzlich die Eigenschaft data, die einen ArrayBuffer enthält. Diese Eigenschaft ist veraltet. Verwenden Sie value.
Wie der Wert aufgebaut ist, hängt vom type ab. Prüfen Sie deshalb cue.type, bevor Sie value auslesen. Vom Browser erzeugte ID3-Objekte können je nach Browserversion unterschiedlich aufgebaut sein.
cuechange-Ereignisse gibt es nur, wenn der Track im Modus "hidden" oder "showing" ist. Im Standardmodus "disabled" wird kein Ereignis ausgelöst.
Metadaten aus fremden Streams sind nicht vertrauenswürdig. Fügen Sie Inhalte aus value nie ungeprüft per innerHTML in die Seite ein, sonst droht XSS. Verwenden Sie stattdessen textContent.

Siehe auch

DataCue DataCue.type TextTrackCue VTTCue TextTrack.addCue() TextTrack.activeCues