VideoColorSpace.fullRange — Eigenschaft · JavaScript-Referenz

Signatur

VideoColorSpace.fullRange

Beschreibung

Die schreibgeschützte Eigenschaft fullRange eines VideoColorSpace-Objekts gibt an, welchen Wertebereich die Luma- und Chroma-Werte (Helligkeit und Farbe) eines Videos nutzen. Bei true wird der volle Bereich verwendet, bei 8 Bit also 0–255 (sogenannter „PC-“ oder „JPEG-Range“). Bei false gilt der eingeschränkte Bereich (Limited/Studio/TV-Range), bei 8 Bit also 16–235 für Luma und 16–240 für Chroma.

Wichtig ist die Eigenschaft vor allem beim Arbeiten mit der WebCodecs API: VideoFrame.colorSpace und VideoDecoderConfig.colorSpace liefern ein VideoColorSpace-Objekt. Wer Rohdaten eines Frames mit VideoFrame.copyTo() ausliest und selbst nach RGB umrechnet (z. B. in einem WebGL-Shader), muss den Bereich kennen. Sonst wirken die Farben ausgewaschen (Limited-Daten als Full gelesen) oder zu kontrastreich mit abgeschnittenen Tiefen und Lichtern (Full-Daten als Limited gelesen).

Ist der Wert unbekannt, weil der Stream keine Angabe enthält, ist die Eigenschaft null. Den Wert legt man über das Dictionary fest, das man dem Konstruktor new VideoColorSpace(init) übergibt. Am fertigen Objekt lässt er sich nicht mehr ändern.

Rückgabewert

Typ

boolean | null

Beschreibung

true beim vollen Wertebereich, false beim eingeschränkten Bereich (Studio/TV). null, wenn der Wert nicht angegeben oder unbekannt ist.

Beispiele

VideoColorSpace erzeugen und fullRange auslesen

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

console.log(colorSpace.fullRange);

// Ohne Angabe ist der Wert unbekannt
const unknown = new VideoColorSpace({});
console.log(unknown.fullRange);

false null

Wertebereich eines dekodierten Frames prüfen

const decoder = new VideoDecoder({
  output: (frame) => {
    const range = frame.colorSpace.fullRange;
    const label = range === null
      ? 'unbekannt'
      : range ? 'voll (0–255)' : 'eingeschränkt (16–235)';
    console.log(`Frame ${frame.timestamp}: Wertebereich ${label}`);
    frame.close(); // Speicher sofort freigeben
  },
  error: (e) => console.error('Decoder-Fehler:', e)
});

decoder.configure({ codec: 'avc1.42E01E', codedWidth: 1280, codedHeight: 720 });
// ... anschließend EncodedVideoChunks mit decoder.decode(chunk) einspeisen

Frame 0: Wertebereich eingeschränkt (16–235)

Parameter für einen YUV→RGB-Shader bestimmen

// Liefert Offset und Skalierung für die Luma-Normalisierung (8 Bit)
const getLumaParams = (colorSpace) => {
  // Unbekannt: bei Videos ist Limited-Range der übliche Standard
  const full = colorSpace.fullRange ?? false;
  return full
    ? { offset: 0, scale: 1 / 255 }
    : { offset: 16 / 255, scale: 1 / (219 / 255) };
};

const params = getLumaParams(new VideoColorSpace({ fullRange: true }));
console.log(params);
// gl.uniform2f(lumaLocation, params.offset, params.scale);

{ offset: 0, scale: 0.00392156862745098 }

// Wichtig · Fallstricke

Auf null prüfen: null bedeutet „unbekannt“ und nicht false. Ein einfaches if (!cs.fullRange) behandelt beide Fälle gleich. Für Videos ist Limited-Range meist die richtige Annahme, für JPEG- oder Kamera-Quellen oft Full-Range.
Schreibgeschützt: Eine Zuweisung wie cs.fullRange = true hat keine Wirkung und wirft im Strict Mode einen TypeError. Wer einen anderen Wert braucht, erzeugt ein neues Objekt, z. B. mit new VideoColorSpace({ ...cs.toJSON(), fullRange: true }).
Automatische Umrechnung: Beim Zeichnen mit drawImage(), texImage2D() oder createImageBitmap() berücksichtigt der Browser den Bereich selbst. Manuell auswerten muss man ihn nur, wenn man Rohdaten über copyTo() ausliest.
Kompatibilität: Die Eigenschaft gehört zur WebCodecs API. Sie ist nur in sicheren Kontexten (HTTPS) verfügbar, außerdem in Dedicated Workern. Die Unterstützung vorher mit 'VideoColorSpace' in globalThis prüfen.

Siehe auch

VideoColorSpace VideoColorSpace.matrix VideoColorSpace.primaries VideoColorSpace.transfer VideoColorSpace.prototype.toJSON() VideoFrame.colorSpace