VideoFrame.colorSpace — Eigenschaft · JavaScript-Referenz

Signatur

VideoFrame.colorSpace

Beschreibung

Die Eigenschaft colorSpace eines VideoFrame gibt ein VideoColorSpace-Objekt zurück. Es beschreibt, wie die Pixeldaten des Frames zu verstehen sind: welche Primärfarben gelten (primaries, z. B. "bt709" oder "bt2020"), welche Transferfunktion genutzt wird (transfer, z. B. "srgb", "pq", "hlg"), welche Matrix YUV in RGB umrechnet (matrix, z. B. "bt709", "bt470bg") und ob der volle Wertebereich verwendet wird (fullRange).

Diese Angaben brauchst du, wenn du Frames selbst weiterverarbeitest, etwa beim Rendern mit WebGL/WebGPU oder bei eigener YUV→RGB-Umrechnung. Auch zum Erkennen von HDR-Inhalten (PQ/HLG mit BT.2020) oder zum Weiterreichen der Farbinformation an einen VideoEncoder ist sie wichtig.

Der Wert wird beim Erzeugen des Frames festgelegt: entweder vom Decoder aus den Metadaten des Datenstroms oder über die Option colorSpace im Konstruktor new VideoFrame(data, init). Einzelne Felder können null sein, wenn der Farbraum nicht bekannt ist.

Rückgabewert

Typ

VideoColorSpace

Beschreibung

Ein Objekt mit den schreibgeschützten Eigenschaften primaries, transfer, matrix (jeweils string | null) und fullRange (boolean | null) sowie der Methode toJSON().

Beispiele

Farbraum eines Frames aus einem Canvas auslesen

const canvas = new OffscreenCanvas(320, 240);
const ctx = canvas.getContext('2d');
ctx.fillStyle = 'tomato';
ctx.fillRect(0, 0, 320, 240);

const frame = new VideoFrame(canvas, { timestamp: 0 });
console.log(frame.colorSpace.toJSON());
frame.close();

{ primaries: "bt709", transfer: "iec61966-2-1", matrix: "rgb", fullRange: true }

Farbraum beim Erzeugen aus Rohdaten festlegen

const width = 4, height = 2;
// I420: Y-Ebene + U/V-Ebene mit halber Auflösung
const data = new Uint8Array(width * height * 1.5).fill(128);

const frame = new VideoFrame(data, {
  format: 'I420',
  codedWidth: width,
  codedHeight: height,
  timestamp: 0,
  colorSpace: {
    primaries: 'bt709',
    transfer: 'bt709',
    matrix: 'bt709',
    fullRange: false
  }
});

const { primaries, matrix, fullRange } = frame.colorSpace;
console.log(primaries, matrix, fullRange);
frame.close();

bt709 bt709 false

HDR-Frames im Decoder erkennen

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

const decoder = new VideoDecoder({
  output: (frame) => {
    if (isHdr(frame.colorSpace)) {
      console.log('HDR-Frame:', frame.colorSpace.transfer);
    } else {
      console.log('SDR-Frame');
    }
    frame.close();
  },
  error: (e) => console.error('Decoder-Fehler:', e)
});

decoder.configure({ codec: 'vp09.02.10.10', codedWidth: 1920, codedHeight: 1080 });
// Danach decoder.decode(new EncodedVideoChunk({...})) aufrufen

HDR-Frame: pq

// Wichtig · Fallstricke

Einzelne Felder können null sein, wenn Decoder oder Quelle keine Farbinformationen liefern – prüfe vor der Verwendung und lege ggf. sinnvolle Standardwerte fest (meist BT.709 für SDR).
Das zurückgegebene VideoColorSpace ist schreibgeschützt. Um den Farbraum zu ändern, musst du einen neuen Frame mit new VideoFrame(frame, { colorSpace }) anlegen.
Nach frame.close() solltest du nicht mehr auf den Frame zugreifen. Kopiere benötigte Werte vorher, z. B. mit colorSpace.toJSON().
Die Angabe ist nur beschreibend: Browser wandeln Pixeldaten nicht automatisch um. Beim Zeichnen in ein Canvas kann trotzdem eine Umwandlung nach sRGB stattfinden, HDR-Informationen gehen dabei unter Umständen verloren.
Kompatibilität: Die WebCodecs API steht nur in sicheren Kontexten (HTTPS) zur Verfügung, auch in Workern. Firefox unterstützt sie erst ab Version 130, in Safari ist sie teilweise eingeschränkt. Prüfe die Unterstützung mit 'VideoFrame' in globalThis.

Siehe auch

PreferenceManager.colorScheme VideoFrame.codedRect VideoFrame.format VideoFrame.codedWidth VideoFrame.flip