Introduction

Stream conditions allow you to add conditional logic in your encoding configuration. They ensure that your workflow can automatically adapt to different types of input files and streams.

This page lists the attributes and values available when attaching stream conditions to Stream resources through its conditions parameter.

Use the tutorial for more information on how to use stream conditions.

Condition object

A Condition has four parameters:

type

"CONDITION"
"AND"
"OR"

Set it to "CONDITION" to describe a single condition you want to provide. If you need more than one condition, please see the "Conjuction Object" section.

attribute

Indicates what aspect of the input is being checked

operator

Indicates the logical operation to perform between source value and expected value. Possible operators are

- "=="
- "!="
- "<="
- "<"
- ">"
- ">="

Note that if you use our SDKs, the operators are exposed through a ConditionOperator enumeration:

- "EQUAL" for "=="
- "NOT_EQUAL" for "!="
- "LESS_THAN_OR_EQUAL" for "<="
- "LESS_THAN" for "<"
- "GREATER_THAN" for ">"
- "GREATER_THAN_OR_EQUAL" for ">="

value

Allows you to state what value to compare against the value extracted from the input file or stream.

All values (including numbers and booleans) should be provided as strings and will be cast automatically into the appropriate type when the encoder performs the condition check.

Example

This condition checks if the total count of audio streams within an input file is greater than or equal to 2.

{
  type: "CONDITION",
  attribute: "AUDIOSTREAMCOUNT",
  operator: ">=",
  value: "2"
}

private static Stream createStream(
      Encoding encoding, Input input, String inputPath, CodecConfiguration codecConfiguration)
      throws BitmovinException {
    /*
		* See the full Example at, where you can add this Stream Condition at: 
    * https://github.com/bitmovin/bitmovin-api-sdk-examples/blob/main/java/src/main/java/DefaultManifests.java#L231
		*/
		
    Stream stream = new Stream();
    //...
  
    //Stream Condition - Only process this Stream if the input file has >= 2 audio tracks
    Condition audioStreamCountCondition = new Condition();
	  audioStreamCountCondition.setAttribute("AUDIOSTREAMCOUNT");
	  audioStreamCountCondition.setOperator(ConditionOperator.GREATER_THAN_OR_EQUAL);
    audioStreamCountCondition.setValue("2");
  
    stream.setConditions(audioStreamCountCondition);
  	
    //...
  	
    return bitmovinApi.encoding.encodings.streams.create(encoding.getId(), stream);
}

Conjunction Object

A Conjunction consists of two parameters:

type

"AND"
"OR"

conditions

Expect an array of condition objects that will be logically chained together based on conjunction object type.

Example

{
  type: "AND",
  conditions: [
  	{
      type: "CONDITION",
      attribute: "AUDIOSTREAMCOUNT",
      operator: ">=",
      value: "2"
    },
    {
      type: "CONDITION",
      attribute: "DURATION",
      operator: ">=",
      value: "30.56"
    }
  ]
}

private static Stream createStream(
      Encoding encoding, Input input, String inputPath, CodecConfiguration codecConfiguration)
      throws BitmovinException {
    /*
		* See the full Example at, where you can add this Stream Condition at: 
    * https://github.com/bitmovin/bitmovin-api-sdk-examples/blob/main/java/src/main/java/DefaultManifests.java#L231
		*/
		
    Stream stream = new Stream();
    //...
  
    //Stream Condition - Only process this Stream if the input file has >= 2 audio tracks
    Condition audioStreamCountCondition = new Condition();
	  audioStreamCountCondition.setAttribute("AUDIOSTREAMCOUNT");
	  audioStreamCountCondition.setOperator(ConditionOperator.GREATER_THAN_OR_EQUAL);
    audioStreamCountCondition.setValue("2");

    //Stream Condition - Only process this Stream if the duration of the input track is >= 30.56s
    Condition durationCondition = new Condition();
	  durationCondition.setAttribute("DURATION");
	  durationCondition.setOperator(ConditionOperator.GREATER_THAN_OR_EQUAL);
    durationCondition.setValue("30.56");

  	//Logically AND those two conditions and provide that to the Stream
    AndConjunction andConjunction = new AndConjunction();
    andConjunction.setConditions(
      Collections.singletonList(audioStreamCountCondition,durationCondition)
    );
  
  	//Add conditions to the Stream
    stream.setConditions(andConjunction);
  	
    //...
  	
    return bitmovinApi.encoding.encodings.streams.create(encoding.getId(), stream);
}

Extracted values

At times, you may find that the condition you configure does not seem to work. It may be that the file you are using does not conform to your expectations.

To troubleshoot this, you can verify the result of the analysis stage, by looking at the analysisDetails property of the Stream (or inputStreams.analysisDetails depending on your input configuration), which will be populated during the encoding.

We state below, for each attribute, which property in the analysisDetails object will reflect the value extracted from the source during analysis.

Note that the analysisDetails property is only available when you call the REST API directly, and is not currently exposed through the SDKs. You can for example use the REST client embedded in our API reference.

Input file

The following attributes are used to check the input file:

Video Stream

In addition to the above, the following attributes are only available when evaluating conditions against video streams. Extracted values are compared against the property of the appropriate item in the analysisDetails.videoStreams array

Audio Stream

The following attributes apply to audio input streams only. Extracted values are compared against the property of the appropriate item in the analysisDetails.audioStreams array