Color Space Filters

Video Format Converter

The vfc filter converts between various uncompressed YUV and RGB pixel formats. The filter supports the following properties:

Property	Type	Description
`OutputFormat`	string	The output pixel format as a four character code.
`MatrixCoefficients`	integer	Specifies the matrix coefficients used to convert the output between YUV and RGB. See Media Streams.
`VideoRange`	integer	Specifies the output video range. See Media Streams.
`ChromaSiting`	integer	Specifies the output chroma location. See Media Streams.
`ConversionStrategy`	integer	`1` Prefer quality over speed `2` Prefer speed over quality
`RoundingMode`	integer	Specifies the method used to round values to a lower bit depth. `0` Down `1` Up `2` Nearest `3` Dither

Video Color Space Converter

The vcsc filter uses a lookup table (LUT) to perform color space conversions. By default the filter generates an internal lookup table (LUT). The filter can also accept an external LUT in either CUBE or Lustre file format.

The filter supports the following LUT configurations:

a 1D LUT used to perform scaling or transfer function conversions
a 3D LUT required to perform tone mapping or color primary conversions
a 3D LUT with a 1D "pre-shapper" LUT used to linearize the RGB signals

The filter accepts either 4:4:4 RGB or 4:4:4 YUV formats. The internal LUT is computed based on the input format and will produce the same format on the output.

For an external LUT the user must ensure that the input color space and pixel format match the LUT requirements (since this information is not provided by the LUT file).

In the following example the pq2hlg.cube LUT file expects RGB input values and converts from PQ to HLG:

---
input:
  container:
  - name: input1
    video:
    - name: v1
      color_primaries: BT2020
      transfer_characteristics: PQ
      matrix_coefficients: BT2020
      video_range: narrow
output:
  container:
  - name: output1
    type: 'mov '
    video:
    - route:
        name: v1
      filter:
      - type: 'vfc '
        properties:
          OutputFormat: 'R64L'
          VideoRange: 1
      - type: 'vcsc'
        properties:
          LutFile: /pq2hlg.cube
          ColorPrimaries: 9
          TransferCharacteristics: 18
          VideoRange: 1
      - type: 'vfc '
        properties:
          OutputFormat: 'v216'
          MatrixCoefficients: 9
      encode:
        type: 'appr'
        properties:
          OutputFormat: 'apch'

{
  "input": {
    "container": [
      {
        "name": "input1",
        "video": [
          {
            "name": "v1",
            "color_primaries": "BT2020",
            "transfer_characteristics": "PQ",
            "matrix_coefficients": "BT2020",
            "video_range": "narrow"
          }
        ]
      }
    ]
  },
  "output": {
    "container": [
      {
        "name": "output1",
        "type": "mov ",
        "video": [
          {
            "route": {
              "name": "v1"
            },
            "filter": [
              {
                "type": "vfc ",
                "properties": {
                  "OutputFormat": "R64L",
                  "VideoRange": 1
                }
              },
              {
                "type": "vcsc",
                "properties": {
                  "LutFile": "/pq2hlg.cube",
                  "ColorPrimaries": 9,
                  "TransferCharacteristics": 18,
                  "VideoRange": 1
                }
              },
              {
                "type": "vfc ",
                "properties": {
                  "OutputFormat": "v216",
                  "MatrixCoefficients": 9
                }
              }
            ],
            "encode": {
              "type": "appr",
              "properties": {
                "OutputFormat": "apch"
              }
            }
          }
        ]
      }
    ]
  }
}

The composition performs the following:

overrides the input color space information to BT.2020 PQ.
converts the input to 16 bit RGB R64L.
converts the color space to BT.2020 HLG using the LUT file.
converts the output to 10 bit YUV v210 using the BT.2020 matrix coefficients.
encodes the output in Apple ProRes HQ format.

Property	Type	Description
`LutFile`	string	Path to a CUBE 3D LUT file.
`TableSize`	integer	Specifies the number of elements in each dimension of the lookup table.
`MatrixCoefficients`	integer	Specifies the matrix coefficients used to convert the output between YUV and RGB. See Media Streams.
`ColorPrimaries`	integer	Specifies the location (in XYZ space) of the red (R), green (G) and blue (B) color primaries and reference white point (W). See Media Streams.
`TransferCharacteristics`	integer	Specifies the the Opto-Electronic Transfer Function (OETF) used to convert between scene linear light levels and nonlinear component values. See Media Streams
`VideoRange`	integer	Specifies the range of signal values that represent the real component values in the normalized range of 0.0 (black) to 1.0 (peak white). See Media Streams.
`ReferenceBlackLevel`	number	Specifies the normalized signal value that represents 0% reflectivity.
`ReferenceWhiteLevel`	number	Specifies the normalized signal value that represents 100% reflectivity.
`EnableRangeCompression`	boolean	Enables compression (rather than clipping) of high dynamic range signals when converting to a lower dynamic range. Default is `true`.
`RangeCompressionRatio`	number	Specifies the compression ratio for Extended Reinhard dynamic range compression. Light levels above this value clipped. Light levels below this value are compressed into the legal range. Default value is `1.0`.
`RangeCompressionToe`	number	Specifies the normalized linear black level for Telestream dynamic range compression. Light levels above this value are linear. Light levels below this value are compressed into the legal range. Default value is `0.0`.
`RangeCompressionShoulder`	number	Specifies the normalized linear white level for Telestream dynamic range compression. Light levels below this value are linear. Light levels above this value are compressed into the legal range. Default value is `1.0`.
`ForceSceneReferencedConversion`	boolean	Disables application of an OOTF (optical to optical transfer function). Default value is `true`.
`GamutCoercionMode`	number	Specifies the method used to reduce gamut: `0` None `1` Clamp `2` Interpolate

For an example of a full API request payload, see External LUT Job Submission.

ColorFront Color Space Converter

The ColorFront(r) based color space conversion cfcs filter supports the following input color spaces:

BT2020 PQ
BT2020 HLG
BT709
P3D65 PQ
P3DCI ST428
XYZ ST428

The filter implements the following conifguration properties:

Property	Type	Description
ColorSpace	enum	Determines the output color space.
HdrAmount	number	Controls the strength of the tone mapping. A value of 0 produces an SDR output.
HdrSurround	number	Affects the highlight range to be boosted.

The filter supports the following output color space types:

Value	Color Space	Notes
0	BT2020 PQ	100 cd/m^2 (HDR10)
1	BT2020 PQ	100 cd/m^2
2	BT2020 HLG	1000 cd/m^2
3	BT2020 HLG	100 cd/m^2
4	BT709
5	P3DCI ST428
6	XYZ ST428

For example the following composition:

overrides the input color space to BT2020 PQ (YUV)
converts the input color space to BT2020 HLG (RGB) using the cfcs filter
converts the RGB to 16 bit narrow range BT2020 YUV using the vfc filter
encodes the output as ProRes 444

input:
  container:
  - name: input1
    video:
    - name: v1
      color_primaries: BT2020
      transfer_characteristics: PQ
      matrix_coefficients: BT2020
      video_range: narrow
output:
  container:
  - name: output1
    type: 'mov '
    video:
    - route:
        name: v1
      filter:
      - type: cfcs
        properties:
          ColorSpace: 2
      - type: 'vfc '
        properties:
          OutputFormat: y416
          MatrixCoefficients: 9
          VideoRange: 1
      encode:
        type: appr
        properties:
          OutputFormat: ap4x