Skip to content

Latest commit

 

History

History
435 lines (337 loc) · 11.8 KB

VideoColorSpace.mdx

File metadata and controls

435 lines (337 loc) · 11.8 KB
title VideoColorSpace
description Describes video color space including primaries, transfer function, and matrix coefficients
icon palette

VideoColorSpace

The VideoColorSpace class describes the color representation of video content. It specifies how color values should be interpreted, including the color gamut (primaries), brightness encoding (transfer), and YUV conversion (matrix).

This class follows the [W3C WebCodecs VideoColorSpace specification](https://www.w3.org/TR/webcodecs/#videocolorspace-interface).

Quick Example

```typescript SDR (BT.709) import { VideoColorSpace } from 'node-webcodecs';

// Standard Dynamic Range - web video, HD content const sdrColorSpace = new VideoColorSpace({ primaries: 'bt709', // Standard HD color gamut transfer: 'bt709', // SDR gamma curve matrix: 'bt709', // BT.709 YUV conversion fullRange: false // Limited range (16-235) });

console.log(sdrColorSpace.primaries); // 'bt709' console.log(sdrColorSpace.toJSON()); // Returns VideoColorSpaceInit object


```typescript HDR10 (BT.2020 + PQ)
import { VideoColorSpace } from 'node-webcodecs';

// High Dynamic Range - HDR10, 4K/8K content
const hdrColorSpace = new VideoColorSpace({
  primaries: 'bt2020',     // Wide color gamut
  transfer: 'pq',          // HDR10 Perceptual Quantizer
  matrix: 'bt2020-ncl',    // BT.2020 non-constant luminance
  fullRange: false         // Limited range
});

console.log(hdrColorSpace.transfer);  // 'pq'
import { VideoColorSpace } from 'node-webcodecs';

// Hybrid Log-Gamma - broadcast HDR
const hlgColorSpace = new VideoColorSpace({
  primaries: 'bt2020',     // Wide color gamut
  transfer: 'hlg',         // HLG transfer (backward compatible)
  matrix: 'bt2020-ncl',    // BT.2020 matrix
  fullRange: false
});

Constructor

Creates a new VideoColorSpace from initialization data.

new VideoColorSpace(init?: VideoColorSpaceInit)
Optional configuration object for the color space. Color primaries defining the color gamut (range of reproducible colors). See [Color Primaries](#color-primaries) table below.
<ParamField body="transfer" type="VideoTransferCharacteristics | null">
  Transfer function defining how brightness values are encoded.
  See [Transfer Characteristics](#transfer-characteristics) table below.
</ParamField>

<ParamField body="matrix" type="VideoMatrixCoefficients | null">
  Matrix coefficients for RGB to YUV conversion.
  See [Matrix Coefficients](#matrix-coefficients) table below.
</ParamField>

<ParamField body="fullRange" type="boolean | null">
  Whether to use full range (0-255) or limited range (16-235) for video levels.
  - `true` - Full range (0-255), used for computer graphics
  - `false` - Limited range (16-235), standard for broadcast video
</ParamField>

Properties

All properties are readonly after construction.

The color primaries defining the color gamut. Returns `null` if not specified. The transfer characteristics (gamma/EOTF) for brightness encoding. Returns `null` if not specified. The matrix coefficients for RGB-to-YUV conversion. Returns `null` if not specified. Whether full range (0-255) or limited range (16-235) is used. Returns `null` if not specified.

Methods

toJSON()

Returns a plain object representation of the color space, suitable for serialization.

colorSpace.toJSON(): VideoColorSpaceInit

Returns: A VideoColorSpaceInit object containing all color space properties.

```typescript const colorSpace = new VideoColorSpace({ primaries: 'bt2020', transfer: 'pq', matrix: 'bt2020-ncl', fullRange: false });

const json = colorSpace.toJSON(); // { // primaries: 'bt2020', // transfer: 'pq', // matrix: 'bt2020-ncl', // fullRange: false // }

// Use for VideoFrame or encoder configuration const frame = new VideoFrame(data, { format: 'RGBA', codedWidth: 1920, codedHeight: 1080, timestamp: 0, colorSpace: colorSpace.toJSON() });

</Accordion>

---

## Color Primaries

Color primaries define the color gamut (range of colors) that can be represented.

| Primary | Description | Use Case |
|---------|-------------|----------|
| `bt709` | BT.709 (Rec. 709) | SDR, HD video, web video |
| `bt2020` | BT.2020 (Rec. 2020) | HDR, 4K/8K, wide color gamut |
| `smpte432` | DCI-P3 | Digital cinema, Apple displays |
| `bt470bg` | BT.470 BG | Legacy PAL/SECAM |
| `smpte170m` | SMPTE 170M | Legacy NTSC |

<AccordionGroup>
  <Accordion title="BT.709 - Standard Definition">
    The standard for HD television and web video. Covers approximately 35% of visible colors.
    This is the default for most SDR content and should be used for web distribution.
  </Accordion>

  <Accordion title="BT.2020 - Wide Color Gamut">
    The standard for HDR and UHD content. Covers approximately 75% of visible colors.
    Required for HDR10 and HLG content. Use with `pq` or `hlg` transfer functions.
  </Accordion>

  <Accordion title="DCI-P3 - Digital Cinema">
    Used in digital cinema projection and Apple displays. Covers approximately 45% of visible colors.
    A middle ground between BT.709 and BT.2020.
  </Accordion>
</AccordionGroup>

---

## Transfer Characteristics

Transfer characteristics (also called EOTF - Electro-Optical Transfer Function) define how brightness values are encoded.

| Transfer | Description |
|----------|-------------|
| `bt709` | SDR gamma curve (~2.4) |
| `pq` | HDR10 Perceptual Quantizer (ST.2084) |
| `hlg` | Hybrid Log-Gamma for broadcast HDR |
| `linear` | Linear light (no gamma) |
| `iec61966-2-1` | sRGB (~2.2 gamma) |
| `smpte170m` | SMPTE 170M (NTSC gamma) |

<AccordionGroup>
  <Accordion title="BT.709 - SDR Standard">
    The standard gamma curve for SDR content. Uses approximately 2.4 gamma with a linear segment near black.
    Use for all standard web and broadcast video.
  </Accordion>

  <Accordion title="PQ (Perceptual Quantizer) - HDR10">
    The transfer function for HDR10 content (SMPTE ST.2084). Encodes absolute brightness up to 10,000 nits.
    Provides the best HDR quality but requires display calibration. Most common HDR format.
  </Accordion>

  <Accordion title="HLG (Hybrid Log-Gamma) - Broadcast HDR">
    A relative brightness encoding that is backward-compatible with SDR displays.
    Used primarily in broadcast (BBC, NHK). Simpler than PQ and degrades gracefully on SDR displays.
  </Accordion>

  <Accordion title="Linear - Raw Light Values">
    No gamma correction applied. Values represent linear light intensity.
    Used for compositing and color grading workflows, not for display.
  </Accordion>
</AccordionGroup>

---

## Matrix Coefficients

Matrix coefficients define how RGB values are converted to/from YUV color space.

| Matrix | Description | Use Case |
|--------|-------------|----------|
| `rgb` | No conversion (RGB) | RGB-only formats |
| `bt709` | BT.709 coefficients | SDR HD video |
| `bt2020-ncl` | BT.2020 non-constant luminance | HDR video |
| `bt470bg` | BT.470 BG | Legacy PAL |
| `smpte170m` | SMPTE 170M | Legacy NTSC |

<Note>
For HDR content, always use `bt2020-ncl` (non-constant luminance). The `bt2020-cl` (constant luminance) variant exists but is rarely used in practice.
</Note>

---

## Common Presets

### BT.709 SDR (Standard Web Video)

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

Use for: HD video, web streaming, YouTube, social media.

BT.2020 HDR10

const bt2020HDR10 = new VideoColorSpace({
  primaries: 'bt2020',
  transfer: 'pq',
  matrix: 'bt2020-ncl',
  fullRange: false
});

Use for: 4K HDR content, Netflix, Apple TV+, streaming HDR.

BT.2020 HLG

const bt2020HLG = new VideoColorSpace({
  primaries: 'bt2020',
  transfer: 'hlg',
  matrix: 'bt2020-ncl',
  fullRange: false
});

Use for: Broadcast HDR, live TV, SDR-compatible HDR.

DCI-P3 (Apple Devices)

const dciP3 = new VideoColorSpace({
  primaries: 'smpte432',
  transfer: 'iec61966-2-1',  // sRGB
  matrix: 'bt709',
  fullRange: false
});

Use for: Apple displays, wide-gamut SDR content.

Full Range RGB (Computer Graphics)

const fullRangeRGB = new VideoColorSpace({
  primaries: 'bt709',
  transfer: 'iec61966-2-1',
  matrix: 'rgb',
  fullRange: true
});

Use for: Screen capture, computer graphics, game footage.


VideoColorSpaceInit Interface

The initialization object used to construct a VideoColorSpace.

interface VideoColorSpaceInit {
  primaries?: VideoColorPrimaries | null;
  transfer?: VideoTransferCharacteristics | null;
  matrix?: VideoMatrixCoefficients | null;
  fullRange?: boolean | null;
}

All properties are optional. Unspecified properties default to null, meaning the value is unknown or unspecified.


Type Definitions

VideoColorPrimaries

type VideoColorPrimaries =
  | 'bt709'      // BT.709 (SDR)
  | 'bt470bg'    // BT.470 BG (PAL)
  | 'smpte170m'  // SMPTE 170M (NTSC)
  | 'bt2020'     // BT.2020 (HDR)
  | 'smpte432';  // DCI-P3

VideoTransferCharacteristics

type VideoTransferCharacteristics =
  | 'bt709'          // SDR gamma
  | 'smpte170m'      // NTSC gamma
  | 'iec61966-2-1'   // sRGB
  | 'linear'         // Linear light
  | 'pq'             // HDR10 (ST.2084)
  | 'hlg';           // HLG

VideoMatrixCoefficients

type VideoMatrixCoefficients =
  | 'rgb'         // No conversion
  | 'bt709'       // BT.709
  | 'bt470bg'     // BT.470 BG
  | 'smpte170m'   // SMPTE 170M
  | 'bt2020-ncl'; // BT.2020 non-constant luminance

Usage with VideoEncoder

Specify color space when encoding to ensure proper metadata in the output:

import { VideoEncoder, VideoFrame, VideoColorSpace } from 'node-webcodecs';

const encoder = new VideoEncoder({
  output: (chunk, metadata) => {
    console.log(`Encoded ${chunk.byteLength} bytes`);
  },
  error: (e) => console.error(e)
});

// Configure encoder with HDR color space
encoder.configure({
  codec: 'hevc_videotoolbox',
  width: 3840,
  height: 2160,
  bitrate: 25_000_000,
  colorSpace: {
    primaries: 'bt2020',
    transfer: 'pq',
    matrix: 'bt2020-ncl',
    fullRange: false
  }
});

// Create frame with matching color space
const frame = new VideoFrame(hdrData, {
  format: 'RGBA',
  codedWidth: 3840,
  codedHeight: 2160,
  timestamp: 0,
  colorSpace: {
    primaries: 'bt2020',
    transfer: 'pq',
    matrix: 'bt2020-ncl'
  }
});

encoder.encode(frame, { keyFrame: true });
frame.close();

See Also

Raw video frame with color space metadata Encode frames with color space configuration Complete guide to HDR video encoding Decode video with color space preservation