User-defined variables and arithmetic video transformations

You can add arithmetic and/or user-defined variables to your transformations. These expressions are evaluated on the fly, enabling you to add an additional layer of sophistication and flexibility to your transformations.

• Arithmetic expressions enable you to assign values to a parameter or variable based on an arithmetic equation.
• User-defined variables enable you to keep value assignment separate from the transformation definition.

User-defined variables are especially valuable when used within named transformations. This enables complete separation of the transformation from the varying values used for delivery. This also makes it significantly easier to reuse common transformations for many assets, even when some specific adjustments must be made to the transformation depending on the specific asset or other data passed from another source.

You can achieve many complex transformation goals by using user-defined variables in conjunction with arithmetic expressions and conditional video transformations.

See also: Variable and arithmetic image transformations.

Arithmetic expressions

You can create arithmetic expressions by using arithmetic operators with numeric transformation parameters or user-defined variables.

The following example demonstrates using an arithmetic expression to define the final delivery width of the video to be 20% of the video's original width.

Supported arithmetic operators

User-defined variables - overview

To use user-defined variables in your transformations, you first declare and assign values to the variables you want to use. In later components of your chained transformation, you can use the variables as the values of your transformation parameters.

Variable naming

User-defined variables start with the $ sign, for example $newwidth. The name can include only alphanumeric characters and must begin with a letter.

Variable value types

Variables can be assigned a number value, string value, or they can take on the value of a numeric asset characteristic, such as iw (initial width) or du (duration).

When working with string values:

• String values are bounded by ! !.
• To assign the value of an existing contextual metadata key to a variable, use the syntax: ctx:!key_name!. When you set a transformation parameter to that variable, it gets the value of the specified contextual metdata key.
  
• To assign the value of a structured metadata ID to a variable, use the syntax: md:!external_id!. Be sure to use the external ID, not the label. When you set a transformation parameter to that variable, it gets the value of the specified metadata.

• You can provide several values in a string using a colon : as the delimiter. For example: !string1:string2:string3!. These multiple-value strings can be used:

  • as separators for public IDs with slashes when the variable will be used to control the public ID of an overlay.
  • for comparing multiple values when the variable will be used in conjunction with the _in_ or _nin_ conditional transformation comparison operators.
  • to specify RGB Hex values for the border, background or color parameters. For example: !rgb:008000!.

  
  When a variable that is defined as a string value and contains a colon, is passed to any other parameter, the colon is treated as a literal character.

Assigning values to variables

Use the underscore to assign a value to a variable. For example:

• $newwidth_200
• $newheight_iw
• $label_!sale!
• $stringset_!string1:string2!

To convert a string value to a numeric value, append _to_i for an integer, or _to_f for a float. For example, to assign the value of the contextual metadata key, breadth, to the variable $newwidth:

• as an integer, use the syntax: $newwidth_ctx:!breadth!_to_i
• as a float, use the syntax: $newwidth_ctx:!breadth!_to_f

If assigning structured metadata to a variable, and the metadata type is numeric, you do not need to specify _to_i. For example, if you have a number field with external ID, position, you can use the syntax: $newwidth_md:!position!. However, if it is a text field you still need to append _to_i or _to_f to convert it to an integer or float.

Using arithmetic expressions with variables

You can use arithmetic operators with numeric variables just as you do with numeric transformation parameters, or even in combination. Consider this example:

$small_150/$big_2_mul_$small/c_fill,h_$small_add_20,w_$big

• The $small variable is set to 150
• The $big variable is assigned the value of 2 times the $small variable
• The height parameter is set to use the value of $small plus 20
• The width parameter is set to use the value of $big

Variable types and supported parameters

You can use user-defined variables with videos to compare how the current value of a parameter relates to the assigned value of a user-defined variable, or you can transform your video by setting the value of a parameter with a variable.

Using variables to transform a video

The following example defines 2 variables: $mainvideowidth and $overlaywidth. The $overlaywidth is defined as 1/3 of the $mainvideowidth.

Using variables in video conditions

You can check the value of a video characteristic against a user-defined variable value within the IF part of conditional transformation.

For this purpose, you can use any parameter that is supported within conditional transformations.

In the example below, the conditional transformation checks whether the video has a certain tag. If it does, the video is delivered at a high quality level of 90. Otherwise, it's delivered at a low quality level of 30. The value of the tag that controls this behavior is declared using the $qualtag variable. In this case, only videos that are tagged as 'Pro' will be delivered with high quality.

The above transformation is running on kitten_fighting2, which has a tag value of 'Pro', and thus it's delivered with a quality value of 90. If you use the same transformation as above with the kitten_fighting video, which is identical, except without the 'Pro' tag, it's delivered with a low quality value of 30.

Expression evaluation order

Within a transformation component, condition (if) statements are evaluated first, then variable assignments, then transformations. Therefore:

• When an assignment is made in a conditional component, the assignment is evaluated only if the condition is true.

• Even if a transformation is specified before a variable assignment within the same URL component, the value is assigned before the transformation. For example, if you deliver a URL containing the following condition:
  if_w_gt_5,w_$x,$x_5
  Even though the variable x is assigned the value 5 only at the end of the transformation, that assignment will be applied first. Afterwards, the width transformation takes on the value (5) of the x variable.

However, the best practice is to separate conditions from results in separate URL components in the order you want them evaluated. For example: if_w_gt_5/$x_5/c_scale,w_$x/if_end, as explained in Conditional transformations.

Using variables with named transformations

By using variables to set the determining values of a condition, you could then define the conditional transformation as a named transformation that could be used with many video assets, and assign the variable value externally.

For example, you could set the named transformation highqual-if-tagged to a transformation similar to the one we used above for the kitten video: if_$qualtag_in_tags,q_80/if_else,q_50/w_$delwidth, and then use it to deliver any video, controlling both the quality and final delivery width by setting the relevant variable values. In this case, the quality condition is applied if the video has a tag set to important. Regardless of the tag, the delivery width will be 450px.