Signatur
Beschreibung
Die Eigenschaft matrix eines VideoColorSpace-Objekts gibt an, mit welchen Matrixkoeffizienten die Luma- und Chroma-Werte (Y, U, V) eines Videobilds in RGB-Werte umgerechnet werden. Die Koeffizienten stammen aus Standards wie ITU-R BT.709 (HD), BT.601 (SD, hier "bt470bg" bzw. "smpte170m") oder BT.2020 (UHD/HDR).
Mögliche Werte sind:
"rgb"– Identitätsmatrix, die Daten liegen schon als RGB vor"bt709"– ITU-R BT.709, üblich bei HD-Video"bt470bg"– ITU-R BT.470 System B/G (entspricht BT.601 für PAL/SECAM)"smpte170m"– SMPTE 170M (entspricht BT.601 für NTSC)"bt2020-ncl"– ITU-R BT.2020, nicht konstante Luminanz (UHD/HDR)null– nicht angegeben oder unbekannt
Du brauchst die Eigenschaft vor allem, wenn du mit der WebCodecs API dekodierte VideoFrame-Objekte selbst weiterverarbeitest – etwa in einem WebGL- oder WebGPU-Shader, der YUV-Ebenen manuell nach RGB konvertiert. Mit falschen Koeffizienten bekommst du leichte, aber sichtbare Farbstiche, typischerweise zu grüne oder zu rote Hauttöne.
Der Wert wird beim Erzeugen über das Konstruktor-Dictionary festgelegt (new VideoColorSpace({ matrix: "bt709" })) oder vom Decoder aus den Metadaten des Bitstroms übernommen. Danach kannst du ihn nicht mehr ändern.
Rückgabewert
null, wenn sie nicht festgelegt sind.Beispiele
Farbraum erstellen und Matrix auslesen
const colorSpace = new VideoColorSpace({
primaries: 'bt709',
transfer: 'bt709',
matrix: 'bt709',
fullRange: false
});
console.log(colorSpace.matrix);
console.log(colorSpace.toJSON());
// Ohne Angabe ist der Wert null
console.log(new VideoColorSpace().matrix);Matrix eines dekodierten VideoFrame prüfen
const decoder = new VideoDecoder({
output: (frame) => {
const { matrix, fullRange } = frame.colorSpace;
console.log(`Matrix: ${matrix ?? 'unbekannt'}, Full Range: ${fullRange}`);
frame.close(); // Speicher sofort freigeben
},
error: (err) => console.error('Decoder-Fehler:', err)
});
decoder.configure({
codec: 'avc1.64001f',
codedWidth: 1280,
codedHeight: 720
});
// Danach: decoder.decode(new EncodedVideoChunk({ ... }))YUV→RGB-Koeffizienten für einen Shader wählen
// Kr- und Kb-Werte der jeweiligen Standards
const LUMA_COEFFS = {
bt709: { kr: 0.2126, kb: 0.0722 },
bt470bg: { kr: 0.299, kb: 0.114 },
smpte170m: { kr: 0.299, kb: 0.114 },
'bt2020-ncl': { kr: 0.2627, kb: 0.0593 }
};
const getCoefficients = (colorSpace, height) => {
let matrix = colorSpace.matrix;
if (matrix === 'rgb') return null; // keine Umrechnung nötig
// Heuristik bei fehlender Angabe: HD -> BT.709, SD -> BT.601
if (matrix === null) matrix = height >= 720 ? 'bt709' : 'smpte170m';
return LUMA_COEFFS[matrix];
};
const cs = new VideoColorSpace({ matrix: 'bt2020-ncl' });
console.log(getCoefficients(cs, 2160));
console.log(getCoefficients(new VideoColorSpace(), 480));// Wichtig · Fallstricke
- Schreibgeschützt: Eine Zuweisung wie
colorSpace.matrix = 'bt709'hat keine Wirkung und wirft im Strict Mode einenTypeError. Wenn du einen anderen Wert brauchst, erzeuge ein neuesVideoColorSpace-Objekt. nullimmer abfangen: Viele Streams geben keine Farbmetadaten mit. Lege dann selbst einen Standardwert fest, üblich ist BT.709 bei HD und BT.601 bei SD.- Ungültige Werte: Ein unbekannter String im Konstruktor-Dictionary führt zu einem
TypeError, weil der Wert ein WebIDL-Enum ist. - Nicht mit
primariesverwechseln:matrixlegt nur die YUV→RGB-Umrechnung fest. Den Farbumfang bestimmtprimaries, die Gammakurvetransfer. Ob der Wertebereich begrenzt (16–235) oder voll ist, steht infullRange. - Kompatibilität: Die Eigenschaft gehört zur WebCodecs API. Diese gibt es nur in sicheren Kontexten (HTTPS), und zwar im Fenster und in Dedicated Workern. Chromium-Browser unterstützen sie ab Version 94, Safari ab 16.4 und Firefox erst seit neueren Versionen (ab 130). Prüfe die Unterstützung vorher mit
'VideoColorSpace' in globalThis.