| title | VideoColorSpace |
|---|---|
| description | Describes video color space including primaries, transfer function, and matrix coefficients |
| icon | palette |
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).
// 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
});Creates a new VideoColorSpace from initialization data.
new VideoColorSpace(init?: VideoColorSpaceInit)<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>
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.Returns a plain object representation of the color space, suitable for serialization.
colorSpace.toJSON(): VideoColorSpaceInitReturns: A VideoColorSpaceInit object containing all color space properties.
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.
const bt2020HDR10 = new VideoColorSpace({
primaries: 'bt2020',
transfer: 'pq',
matrix: 'bt2020-ncl',
fullRange: false
});Use for: 4K HDR content, Netflix, Apple TV+, streaming HDR.
const bt2020HLG = new VideoColorSpace({
primaries: 'bt2020',
transfer: 'hlg',
matrix: 'bt2020-ncl',
fullRange: false
});Use for: Broadcast HDR, live TV, SDR-compatible HDR.
const dciP3 = new VideoColorSpace({
primaries: 'smpte432',
transfer: 'iec61966-2-1', // sRGB
matrix: 'bt709',
fullRange: false
});Use for: Apple displays, wide-gamut SDR content.
const fullRangeRGB = new VideoColorSpace({
primaries: 'bt709',
transfer: 'iec61966-2-1',
matrix: 'rgb',
fullRange: true
});Use for: Screen capture, computer graphics, game footage.
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 VideoColorPrimaries =
| 'bt709' // BT.709 (SDR)
| 'bt470bg' // BT.470 BG (PAL)
| 'smpte170m' // SMPTE 170M (NTSC)
| 'bt2020' // BT.2020 (HDR)
| 'smpte432'; // DCI-P3type VideoTransferCharacteristics =
| 'bt709' // SDR gamma
| 'smpte170m' // NTSC gamma
| 'iec61966-2-1' // sRGB
| 'linear' // Linear light
| 'pq' // HDR10 (ST.2084)
| 'hlg'; // HLGtype VideoMatrixCoefficients =
| 'rgb' // No conversion
| 'bt709' // BT.709
| 'bt470bg' // BT.470 BG
| 'smpte170m' // SMPTE 170M
| 'bt2020-ncl'; // BT.2020 non-constant luminanceSpecify 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();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