Last updated: Aug-03-2022
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.
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.
iw_mul_2_add_ih_mul_2 would give you the perimeter measurement of the initial asset by first multiplying both the initial width by 2 and the initial height by 2, and then adding these two products.
|operation||URL syntax||SDK syntax|
(to the power of)
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.
User-defined variables start with the
$ sign, for example
$newwidth. The name can include only alphanumeric characters and must begin with a letter.
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
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
_nin_conditional transformation comparison operators.
- to specify RGB Hex values for the
colorparameters. For example:
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.
Use the underscore to assign a value to a variable. For example:
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
- as an integer, use the syntax:
- as a float, use the syntax:
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_f to convert it to an integer or float.
You can use arithmetic operators with numeric variables just as you do with numeric transformation parameters, or even in combination. Consider this example:
$smallvariable is set to 150
$bigvariable is assigned the value of 2 times the
heightparameter is set to use the value of
widthparameter is set to use the value of
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.
The following example defines 2 variables:
$overlaywidth is defined as 1/3 of the
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.
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:
Even though the variable
xis assigned the value
5only at the end of the transformation, that assignment will be applied first. Afterwards, the
widthtransformation takes on the value (5) of the
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.
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.
mdparameters, their values are exposed publicly in the URL. If you want to prevent such values from being exposed, you can disable the Usage of tags/context/metadata in transformation URLs option in the Security Settings (enabled by default). When this setting is disabled, any URL that exposes tags, contextual metadata or structured metadata values will return an error.