VideoColorSpace.transfer — Eigenschaft · JavaScript-Referenz

Signatur

get VideoColorSpace.transfer

Beschreibung

VideoColorSpace.transfer gibt an, mit welcher Transferfunktion (auch „Gammakurve“ oder OETF/EOTF) die Helligkeitswerte eines Videos kodiert sind. Diese Funktion legt fest, wie lineares Licht in digitale Codewerte umgerechnet wird und umgekehrt. Nur wenn sie richtig ausgewertet wird, erscheinen Helligkeit und Kontrast bei Anzeige, Umkodierung oder Weiterverarbeitung (z. B. in WebGL/WebGPU) korrekt.

Mögliche Werte (Enum VideoTransferCharacteristics):

"bt709": Transferfunktion nach ITU-R BT.709 (übliches SDR-HD-Video).
"smpte170m": SMPTE 170M bzw. BT.601 (SD-Video, NTSC/PAL).
"iec61966-2-1": sRGB-Kurve nach IEC 61966-2-1 (typisch für Bildschirm- und Webinhalte).
"linear": lineare Transferfunktion.
"pq": Perceptual Quantizer nach SMPTE ST 2084 (HDR10, Dolby Vision).
"hlg": Hybrid Log-Gamma nach ARIB STD-B67 (HDR im Rundfunk).
null: Der Wert ist nicht bekannt oder wurde nicht angegeben.

Die Eigenschaft begegnet dir meist über VideoFrame.colorSpace nach dem Dekodieren mit einem VideoDecoder oder nach dem Erzeugen eines VideoFrame aus einer Kamera- bzw. Canvas-Quelle. Selbst setzen kannst du den Wert nur über das Dictionary, das du an den Konstruktor new VideoColorSpace() übergibst, oder über das Feld colorSpace in einer VideoDecoderConfig bzw. im VideoFrame-Init.

Rückgabewert

Typ

string | null

Beschreibung

Einer der Werte "bt709", "smpte170m", "iec61966-2-1", "linear", "pq", "hlg" oder null, wenn die Transferfunktion unbekannt ist.

Beispiele

VideoColorSpace erzeugen und transfer auslesen

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

console.log(colorSpace.transfer);

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

bt709 null

HDR-Inhalt in dekodierten Frames erkennen

const isHdrTransfer = (transfer) => transfer === 'pq' || transfer === 'hlg';

const decoder = new VideoDecoder({
  output: (frame) => {
    const { transfer } = frame.colorSpace;
    if (isHdrTransfer(transfer)) {
      console.log(`HDR-Frame erkannt (${transfer}) – Tone-Mapping nötig`);
    } else {
      console.log(`SDR-Frame (${transfer ?? 'unbekannt'})`);
    }
    frame.close(); // Speicher sofort freigeben
  },
  error: (err) => console.error('Dekodierfehler:', err)
});

decoder.configure({
  codec: 'vp09.02.10.10', // VP9 Profil 2, 10 Bit
  codedWidth: 1920,
  codedHeight: 1080,
  colorSpace: { primaries: 'bt2020', transfer: 'pq', matrix: 'bt2020-ncl', fullRange: false }
});

HDR-Frame erkannt (pq) – Tone-Mapping nötig

Farbraum eines Canvas-Frames serialisieren

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

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

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

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie colorSpace.transfer = 'pq' hat keine Wirkung und wirft im Strict Mode einen TypeError. Wenn du einen anderen Wert brauchst, erzeugst du ein neues VideoColorSpace-Objekt.
Auf null prüfen: Viele Container und Streams liefern keine Farbinformationen mit. Dann ist transfer null. Setze in diesem Fall einen sinnvollen Standardwert, z. B. "bt709" für HD-Video.
Metadaten, keine Umrechnung: Die Eigenschaft beschreibt die Pixeldaten nur, sie verändert sie nicht. Tone-Mapping von "pq"/"hlg" auf SDR musst du selbst umsetzen (z. B. per WebGL/WebGPU-Shader).
Nicht jeder Wert wird überall unterstützt: "linear", "pq" und "hlg" kamen später in die Spezifikation. Ältere Browser werfen bei unbekannten Enum-Werten im Konstruktor einen TypeError.
Kompatibilität: Die WebCodecs API ist nur in sicheren Kontexten (HTTPS) verfügbar, im Fenster und in Dedicated Workern. Die Unterstützung (Chromium 94+, Safari 16.4+, Firefox 130+) prüfst du am besten mit 'VideoColorSpace' in globalThis.

Siehe auch

VideoColorSpace.fullRange VideoColorSpace.matrix VideoColorSpace.primaries VideoTrack.label VideoFrame.duration