Conditional Output

Product(s)
Video Cloud
Role(s)
API Developer
Task(s)
Add Videos/Assets
Topic(s)
Ingest Profiles
API(s)
Ingest Profiles API

In this topic, you will learn how to create conditional outputs in a custom ingest profile by skipping renditions if the source file doesn't meet certain conditions.

Limitations

Why skip renditions?

Skipping renditions is useful if the source videos you ingest vary widely in quality. This is often case, for example, for news organizations that use video captured by phones or other devices in the field.

Without conditional outputs, the Dynamic Ingest system will created exactly as many renditions as are specified in the profile.

For example, let's say you ingest a low-quality video (video bitrate around 820 kbps) using a profile that includes the following unconditional video renditions.

Video Renditions
Format Audio Bitrate Video Bitrate
mp4 64 450
mp4 96 900
mp4 128 1700
HLS 64 450
HLS 96 700
HLS 96 900
HLS 96 1200
HLS 128 1700
HLS 128 2000

The resulting renditions in Studio would look something like this:

Renditions for Low Quality Video
Renditions for Low Quality Video

Note that the last three (highlighted) HLS renditions are identical in bitrate, and that the bitrate is only marginally higher than the next best HLS rendition. Also note that the difference in the bitrates for two best MP4 renditions is small. The reason for this is that transcoding can never improve on the bitrate of the source, and the source here had an average bitrate of around 800 kbps, so renditions with higher specified bitrates end up with something in that range (you'll see small differences because of different ways that average bitrate is calculated for segmented and non-segmented video formats).

The last four renditions in the set, then, are essentially redundant, offering little if any improvement in quality over the "lower-quality" renditions, but they are created and stored anyway. This can be prevented by using conditional outputs that prevent a rendition from being generated if the source doesn't match the quality criteria you specify.

Implementation

You can add a skip object to some of the renditions. The skip object contains one or more conditions, and if these conditions are not met, the rendition will not be created.

Notes on usage

  1. An ingest profile must include at least one non-skippable rendition - if you try to create a profile in which all renditions are skippable, you will receive an error.
  2. You must insure that at least one rendition is created for every content type. For example:
    • If you create both audio-only and video renditions, you must have a non-skippable rendition for each
    • If you use DRM, you must have a non-skippable rendition for each format that works with that DRM type (Smooth, HLS, DASH, etc.)

Syntax

The syntax for the skip object you can add to a rendition specification is as follows:

"skip": {
    "condition1": "value1",
    "condition2": 1300,
    ...etc
}

Example

"renditions": [
    {
      "media_type": "video",
      "reference_id": "ts1",
      "format": "ts",
      "type": "segmented",
      "audio_codec": "aac",
      "audio_bitrate": 96,
      "video_bitrate": 1200.
      "video_codec": "h264",
      "keyframe_rate": 0.5,
      "max_frame_rate": 30,
      "width": 1280,
      "height": 720,
      "h264_profile": "main",
      "skip": {
          "min_video_bitrate": 1000,
          "min_size": "640x360"
        }
    },
    ... etc
]

For the profile (fragment) above, the rendition shown will be created only if the source video has a video bitrate of at least 1000 kbps and a frame size of at least 640px x 360px.

Skip fields

Below are the fields (conditions) that can be used in the skip object:

Skip Fields
property type description default
min_audio_bitrate integer the minimum audio bitrate that the source must have (kbps) null
max_audio_bitrate integer the maximum audio bitrate that the source must have (kbps) null
min_video_bitrate integer the minimum video bitrate that the source must have (kbps) null
max_video_bitrate integer the maximum video bitrate that the source must have (kbps) null
require_audio boolean the source must include an audio track null
require_video boolean the source must include a video track null
min_size string of the form "widthxheight" (e.g. "400x225") the source must be at least this resolution null
max_size string of the form "widthxheight" (e.g. "1920x1080") the source must be at most this resolution null