Media Properties

You can use the Transform API to request media information for a container at a specific URL. See Probing a Container for details.

The probe results include the container type and the media properties for each video, audio or subtitle stream in the container. For example the media information for an MPEG-2 Program Stream m2ps container is shown below:

---
type: 'm2ps'
video:
- format: 'mp2v'
  width: 720
  height: 480
  pixel_aspect_ratio:
    numerator: 1
    denominator: 1
  sample_rate:
    numerator: 30000
    denominator: 1001
  field_order: bottom
audio:
- format: 'twos'
  channels: 2
  sample_rate:
    numerator: 48000
    denominator: 1152
  properties:
    LpcmTransport: DVDF

{
  "type": "m2ps",
  "video": [
    {
      "format": "mp2v",
      "width": 720,
      "height": 480,
      "pixel_aspect_ratio": {
        "numerator": 1,
        "denominator": 1
      },
      "frame_rate": {
        "numerator": 30000,
        "denominator": 1001
      },
      "field_order": "bottom"
    }
  ],
  "audio": [
    {
      "format": "twos",
      "channels": 2,
      "sample_rate": {
        "numerator": 48000,
        "denominator": 1152
      },
      "properties": {
        "LpcmTransport": "DVDF"
      }
    }
  ]
}

The format property is a four character code indicating the compressed (or uncompressed) format of a media stream. In the previous example the file contains an MPEG-2 video stream and a 16 bit (big endian) PCM audio stream.

See the Container reference for a list of the supported video, audio and subtitle formats.

See the Media Streams reference for a description of each media property.

Input Streams

In a composition an input stream inherits the media properties of the selected track. Properties specified on an input stream override the property values when they are missing or incorrect.

In the previous example the pixel_aspect_ratio is incorrect and should be 8:9 (resulting in display dimensions of 640 by 480). The composition below overrides the pixel aspect ratio:

---
input:
  container:
  - name: input1
    video:
    - name: v1
      pixel_aspect_ratio:
        numerator: 8
        denominator: 9
    audio:
    - name: a1

{
  "input": {
    "container": [
      {
        "name": "input1",
        "video": [
          {
            "name": "v1",
            "pixel_aspect_ratio": {
              "numerator": 8,
              "denominator": 9
            }
          }
        ],
        "audio": [
          {
            "name": "a1"
          }
        ]
      }
    ]
  }
}

Output Streams

An output stream inherits the media properties of the routed input stream. Properties specified on the output stream convert the property values when they are different than the input stream.

Continuing the previous example the composition below resizes the video by setting the width and height properties and changes the audio to 16 bit little endian swot format:

---
input:
  container:
  - name: input1
    video:
    - name: v1
      pixel_aspect_ratio:
        numerator: 8
        denominator: 9
    audio:
    - name: a1
output:
  container:
  - name: output1
    type: 'mov '
    video:
    - name: v1
      width: 320
      height: 240
    audio:
    - name: a1
      format: 'swot'

{
  "input": {
    "container": [
      {
        "name": "input1",
        "video": [
          {
            "name": "v1",
            "pixel_aspect_ratio": {
              "numerator": 8,
              "denominator": 9
            }
          }
        ],
        "audio": [
          {
            "name": "a1"
          }
        ]
      }
    ]
  },
  "output": {
    "container": [
      {
        "name": "output1",
        "type": "mov ",
        "video": [
          {
            "name": "v1",
            "width": 320,
            "height": 240
          }
        ],
        "audio": [
          {
            "name": "a1",
            "format": "swot"
          }
        ]
      }
    ]
  }
}

Common Properties

The section describes several properties that commonly need to be supplied, overridden or converted.

Media Language

The language property contains the ISO 639 language code for a media stream. The following composition provides the missing language codes for each input stream:

---
input:
  container:
  - name: input1
    audio:
    - name: a1
      language: eng
    - name: a2
      language: spa
    subtitle:
    - name: s1
      language: fra

{
  "input": {
    "container": [
      {
        "name": "input1",
        "audio": [
          {
            "name": "a1",
            "language": "eng"
          },
          {
            "name": "a2",
            "language": "spa"
          }
        ],
        "subtitle": [
          {
            "name": "s1",
            "language": "fra"
          }
        ]
      }
    ]
  }
}

Frame Structure

The field_order property indicates whether video frames are interlaced or progressive.

The following composition corrects the input stream field order (interlaced upper field first) and converts the output stream to progressive frames. The deinterlace operator specifies the weston three field de-interlacing algorithm.

---
input:
  container:
  - name: input1
    video:
    - name: v1
      field_order: upper
      deinterlace:
        method: weston
output:
  container:
  - name: output1
    type: 'mp4 '
    video:
    - name: v1
      field_order: progressive

{
  "input": {
    "container": [
      {
        "name": "input1",
        "video": [
          {
            "name": "v1",
            "field_order": "upper",
            "deinterlace": {
              "method": "weston"
            }
          }
        ]
      }
    ]
  },
  "output": {
    "container": [
      {
        "name": "output1",
        "type": "mp4 ",
        "video": [
          {
            "name": "v1",
            "field_order": "progressive"
          }
        ]
      }
    ]
  }
}

Color Space

The color space for a video stream is defined by the following properties:

The following composition forces the the input color space to narrow range BT.2100 PQ (HDR10) and converts the output color space to BT.2100 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:
    - name: v1
      transfer_characteristics: 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": [
          {
            "name": "v1",
            "transfer_characteristics": "HLG"
          }
        ]
      }
    ]
  }
}

Speaker Labels

The label array contains the speaker assignment for each audio channel in a stream.

The following composition provides the missing speaker labels for an input audio stream. Note that the channels property specifies the dimension of the label array.

---
input:
  container:
  - name: input1
    audio:
    - name: a1
      channels: 8
      label:
      - L
      - R
      - C
      - LFE
      - Ls
      - Rs
      - Lt
      - Rt

{
  "input": {
    "container": [
      {
        "name": "input1",
        "audio": [
          {
            "name": "a1",
            "channels": 8,
            "label": [
              "L",
              "R",
              "C",
              "LFE",
              "Ls",
              "Rs",
              "Lt",
              "Rt"
            ]
          }
        ]
      }
    ]
  }
}