VideoColorSpace.primaries — Eigenschaft · JavaScript-Referenz

Signatur

VideoColorSpace.primaries

Beschreibung

Die Eigenschaft primaries eines VideoColorSpace-Objekts gibt an, welche Farbprimärvalenzen ein Video verwendet. Sie legt fest, wo im Farbraum die Grundfarben Rot, Grün und Blau sowie der Weißpunkt liegen. Daraus ergibt sich der Gamut, also die Menge aller Farben, die das Video darstellen kann.

Mögliche Werte sind:

"bt709": BT.709, der Standard für HD-Video und sRGB-nahe Inhalte
"bt470bg": BT.601 PAL/SECAM, ältere SD-Inhalte
"smpte170m": BT.601 NTSC, ältere SD-Inhalte
"bt2020": BT.2020, großer Gamut für UHD/HDR
"smpte432": DCI-P3 mit D65-Weißpunkt (Display P3)
null: Der Wert ist unbekannt oder nicht angegeben.

Meist liest man die Eigenschaft über VideoFrame.colorSpace aus. So erkennt man, ob ein dekodierter Frame zum Beispiel HDR-Inhalt mit großem Gamut enthält und vor der Darstellung auf einem Canvas eine Farbraumumrechnung nötig ist. Zusammen mit transfer, matrix und fullRange beschreibt primaries den Farbraum vollständig.

Rückgabewert

Typ

string | null

Beschreibung

Einer der Werte "bt709", "bt470bg", "smpte170m", "bt2020", "smpte432" oder null, wenn der Wert unbekannt ist.

Beispiele

VideoColorSpace erzeugen und primaries auslesen

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

console.log(colorSpace.primaries);

// Ohne Angabe ist der Wert null
const unbekannt = new VideoColorSpace();
console.log(unbekannt.primaries);

bt709 null

Farbraum eines Kamera-Frames prüfen

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();
const processor = new MediaStreamTrackProcessor({ track });
const reader = processor.readable.getReader();

const { value: frame } = await reader.read();
console.log('Primärvalenzen:', frame.colorSpace.primaries ?? 'unbekannt');
frame.close(); // Frame-Speicher sofort freigeben
track.stop();

Primärvalenzen: bt709

Großen Gamut (HDR) in einem VideoDecoder erkennen

const WIDE_GAMUT = new Set(['bt2020', 'smpte432']);

const decoder = new VideoDecoder({
  output: (frame) => {
    const { primaries } = frame.colorSpace;
    if (WIDE_GAMUT.has(primaries)) {
      console.log(`Großer Gamut erkannt (${primaries}) – Farbraum umrechnen`);
    }
    frame.close();
  },
  error: (e) => console.error(e)
});

decoder.configure({
  codec: 'vp09.02.10.10',
  colorSpace: { primaries: 'bt2020', transfer: 'pq', matrix: 'bt2020-ncl' }
});

Großer Gamut erkannt (bt2020) – Farbraum umrechnen

// Wichtig · Fallstricke

Die Eigenschaft ist nur lesbar. Eine Zuweisung wie colorSpace.primaries = 'bt2020' wird ignoriert und löst im Strict Mode einen TypeError aus. Wer einen anderen Wert braucht, erzeugt ein neues Objekt mit new VideoColorSpace({...}).
Ist der Wert null, heißt das nicht automatisch BT.709. Die Information fehlt dann einfach, etwa weil der Container keine Farbmetadaten enthält. Legen Sie in diesem Fall selbst einen sinnvollen Standardwert fest.
Die Eigenschaft beschreibt nur die Metadaten. Die Pixel werden dabei nicht umgerechnet. Wenn ein BT.2020-Frame ohne Umrechnung auf einem sRGB-Canvas landet, wirken die Farben blass.
Zur Kompatibilität: WebCodecs gibt es nur in sicheren Kontexten (HTTPS). Die API steht im Fenster und in Workern zur Verfügung. Firefox unterstützt sie erst ab Version 130 und nur auf dem Desktop. Prüfen Sie die Verfügbarkeit mit 'VideoColorSpace' in globalThis.
toJSON() liefert primaries zusammen mit den übrigen Farbraum-Feldern als einfaches Objekt. Das ist praktisch zum Loggen oder zum Weitergeben an VideoDecoder.configure().

Siehe auch

TextDecoderStream.writable VideoColorSpace.matrix VideoColorSpace.transfer VideoColorSpace.fullRange IDBCursor.primaryKey