new VideoColorSpace() — Methode · JavaScript-Referenz

Signatur

new VideoColorSpace(options)

Beschreibung

Der Konstruktor VideoColorSpace() gehört zur WebCodecs API und erstellt ein Objekt, das den Farbraum von Videodaten beschreibt. Dazu gehören vier Angaben: die Primärvalenzen (primaries), die Übertragungsfunktion (transfer), die Matrixkoeffizienten für die YUV↔RGB-Umrechnung (matrix) und die Angabe, ob der volle Wertebereich genutzt wird (fullRange).

Normalerweise erhält man ein VideoColorSpace-Objekt über VideoFrame.colorSpace. Den Konstruktor braucht man vor allem, um Farbraum-Informationen zu prüfen, zu vergleichen oder zu serialisieren, etwa um Metadaten aus einem Container (MP4, WebM) gezielt als Objekt abzubilden. Beim Erzeugen eines VideoFrame oder beim Konfigurieren eines VideoDecoder wird dagegen meist ein einfaches Objekt (VideoColorSpaceInit) übergeben.

Alle Eigenschaften der erzeugten Instanz sind schreibgeschützt. Nicht angegebene Felder erhalten den Wert null, was „unbekannt“ bedeutet. Mit toJSON() lässt sich das Objekt in ein einfaches Objekt umwandeln, das sich wiederum als colorSpace-Option weiterverwenden lässt.

Rückgabewert

Typ

VideoColorSpace

Beschreibung

Ein neues VideoColorSpace-Objekt mit schreibgeschützten Eigenschaften primaries, transfer, matrix und fullRange.

Beispiele

Standard-HD-Farbraum (BT.709) erzeugen

const rec709 = new VideoColorSpace({
  primaries: 'bt709',
  transfer: 'bt709',
  matrix: 'bt709',
  fullRange: false
});

console.log(rec709.primaries, rec709.transfer, rec709.matrix, rec709.fullRange);
console.log(JSON.stringify(rec709.toJSON()));

bt709 bt709 bt709 false {"primaries":"bt709","transfer":"bt709","matrix":"bt709","fullRange":false}

Leerer Farbraum – unbekannte Werte sind null

const unbekannt = new VideoColorSpace();
console.log(unbekannt.primaries, unbekannt.fullRange);

null null

Prüfen, ob ein decodierter Frame HDR-Inhalt enthält

const hdr10 = new VideoColorSpace({
  primaries: 'bt2020',
  transfer: 'pq',
  matrix: 'bt2020-ncl',
  fullRange: false
});

const istGleicherFarbraum = (a, b) =>
  a.primaries === b.primaries &&
  a.transfer === b.transfer &&
  a.matrix === b.matrix &&
  a.fullRange === b.fullRange;

const decoder = new VideoDecoder({
  output: (frame) => {
    if (istGleicherFarbraum(frame.colorSpace, hdr10)) {
      console.log('HDR10-Frame erkannt');
    }
    frame.close(); // Speicher freigeben!
  },
  error: (e) => console.error('Decoder-Fehler:', e)
});

HDR10-Frame erkannt

Farbraum an einen neuen VideoFrame übergeben

const canvas = new OffscreenCanvas(640, 360);
const ctx = canvas.getContext('2d');
ctx.fillStyle = 'teal';
ctx.fillRect(0, 0, 640, 360);

const srgb = new VideoColorSpace({
  primaries: 'bt709',
  transfer: 'iec61966-2-1',
  matrix: 'rgb',
  fullRange: true
});

// toJSON() liefert ein VideoColorSpaceInit-Objekt
const frame = new VideoFrame(canvas, { timestamp: 0, colorSpace: srgb.toJSON() });
console.log(frame.colorSpace.transfer);
frame.close();

iec61966-2-1

// Wichtig · Fallstricke

Kompatibilität: Teil der WebCodecs API; verfügbar in Chromium-Browsern ab Version 94, in Safari ab 16.4 und in Firefox ab 130. Vorher mit 'VideoColorSpace' in globalThis prüfen.
WebCodecs ist nur in einem sicheren Kontext (HTTPS oder localhost) verfügbar, sowohl im Fenster als auch in Dedicated Workern.
Ungültige Zeichenketten für primaries, transfer oder matrix lösen einen TypeError aus, weil es sich um WebIDL-Enums handelt.
Die Eigenschaften sind schreibgeschützt. Für einen geänderten Farbraum ein neues Objekt anlegen, z. B. new VideoColorSpace({ ...alt.toJSON(), fullRange: true }).
Der Farbraum beschreibt die Daten nur, er rechnet sie nicht um. Ein falsch angegebener Farbraum führt zu verfälschten Farben bei Darstellung oder Encodierung.
VideoColorSpace-Objekte haben keine Methode zum Vergleichen, deshalb die Felder einzeln prüfen oder die Ergebnisse von toJSON() vergleichen.

Siehe auch

new DOMPoint() new VideoFrame() new VideoDecoder() new VideoEncoder() new FileReaderSync()