VideoColorSpace — Schnittstelle · JavaScript-Referenz

Signatur

interface VideoColorSpace

Beschreibung

VideoColorSpace fasst die vier Kenngrößen zusammen, mit denen Pixelwerte eines Videos richtig als Farben gedeutet werden: die Primärfarben (primaries), die Transferfunktion (transfer, also die Gamma- bzw. HDR-Kurve), die Matrixkoeffizienten (matrix) für die Umrechnung von YUV nach RGB und den Wertebereich (fullRange: voller Bereich 0–255 oder eingeschränkter „TV-Bereich“ 16–235).

Objekte dieser Schnittstelle begegnen dir vor allem als Eigenschaft VideoFrame.colorSpace dekodierter Frames. Außerdem kannst du Farbraum-Angaben in einem VideoDecoderConfig (Schlüssel colorSpace) oder beim Erzeugen eines VideoFrame aus Rohdaten übergeben. So überschreibst du fehlende oder falsche Angaben im Bitstrom. Das ist etwa bei HDR-Material (PQ/HLG, BT.2020) oder bei der Weiterverarbeitung in WebGL/WebGPU wichtig.

Alle Eigenschaften sind schreibgeschützt und können null sein, wenn der Wert unbekannt ist. Die Methode toJSON() liefert ein einfaches Objekt, das sich als Initialisierungswert (VideoColorSpaceInit) wiederverwenden oder protokollieren lässt.

primaries: "bt709", "bt470bg", "smpte170m", "bt2020", "smpte432" oder null
transfer: "bt709", "smpte170m", "iec61966-2-1" (sRGB), "linear", "pq", "hlg" oder null
matrix: "rgb", "bt709", "bt470bg", "smpte170m", "bt2020-ncl" oder null
fullRange: boolean oder null

Parameter

Name	Typ	Default	Beschreibung
$options	VideoColorSpaceInit	{}	Optionales Objekt mit den Schlüsseln `primaries`, `transfer`, `matrix` (jeweils String oder `null`) und `fullRange` (`boolean` oder `null`). Wird für den Konstruktor `new VideoColorSpace(options)` verwendet. Fehlende Schlüssel werden zu `null`.

Rückgabewert

Typ

VideoColorSpace

Beschreibung

Der Konstruktor liefert eine neue, unveränderliche VideoColorSpace-Instanz. toJSON() liefert ein VideoColorSpaceInit-Objekt mit denselben vier Werten.

Beispiele

Farbraum für HD-Video (BT.709) erzeugen

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

console.log(cs.primaries, cs.transfer, cs.matrix, cs.fullRange);
console.log(JSON.stringify(cs)); // nutzt toJSON()

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

Farbraum dekodierter Frames auslesen und HDR erkennen

const isHdr = (cs) => cs.transfer === 'pq' || cs.transfer === 'hlg';

const decoder = new VideoDecoder({
  output: (frame) => {
    const cs = frame.colorSpace;
    console.log('Farbraum:', cs.toJSON());
    if (isHdr(cs)) {
      console.log('HDR-Frame – Tone-Mapping nötig');
    }
    frame.close(); // Speicher sofort freigeben
  },
  error: (e) => console.error(e)
});

decoder.configure({ codec: 'vp09.00.10.08' });

Farbraum: { primaries: 'bt709', transfer: 'bt709', matrix: 'bt709', fullRange: false }

Farbraum im Decoder-Config vorgeben (HDR10)

const config = {
  codec: 'hvc1.2.4.L153.B0',
  codedWidth: 3840,
  codedHeight: 2160,
  colorSpace: {
    primaries: 'bt2020',
    transfer: 'pq',
    matrix: 'bt2020-ncl',
    fullRange: false
  }
};

const { supported } = await VideoDecoder.isConfigSupported(config);
console.log('HDR10 unterstützt:', supported);

HDR10 unterstützt: true

VideoFrame aus Rohdaten mit explizitem Farbraum

const width = 2, height = 2;
// RGBA-Pixel (4 Byte pro Pixel), komplett rot
const data = new Uint8Array(width * height * 4).map((_, i) => (i % 4 === 0 || i % 4 === 3) ? 255 : 0);

const frame = new VideoFrame(data, {
  format: 'RGBA',
  codedWidth: width,
  codedHeight: height,
  timestamp: 0,
  colorSpace: { primaries: 'bt709', transfer: 'iec61966-2-1', matrix: 'rgb', fullRange: true }
});

console.log(frame.colorSpace.transfer);
frame.close();

iec61966-2-1

// Wichtig · Fallstricke

Werte können null sein: Enthält der Bitstrom keine Farbinformationen, sind einzelne oder alle Eigenschaften null. Plane dann einen sinnvollen Standard ein, etwa BT.709 für HD oder SMPTE 170M für SD.
Unveränderlich: Die Eigenschaften sind schreibgeschützt. Für Änderungen erzeugst du mit new VideoColorSpace({ ...cs.toJSON(), fullRange: true }) ein neues Objekt.
Keine Farbkonvertierung: VideoColorSpace beschreibt die Daten nur und rechnet nichts um. Tone-Mapping oder YUV→RGB-Umrechnung musst du z. B. per WebGL/WebGPU selbst umsetzen, oder das Zeichnen auf ein Canvas übernimmt sie.
Unbekannte Enum-Werte im Konstruktor lösen einen TypeError aus.
Kompatibilität: Die Schnittstelle gehört zur WebCodecs API und steht nur in sicheren Kontexten (HTTPS) zur Verfügung, im Fenster und in Dedicated Workern. Unterstützt wird sie in Chromium ab Version 94, in Safari ab 16.4 und in Firefox ab 130. Prüfe die Verfügbarkeit mit 'VideoColorSpace' in globalThis.

Siehe auch

VideoFrame VideoFrame.colorSpace VideoDecoder VideoEncoder VideoDecoder.prototype.configure() EncodedVideoChunk