Last updated: Sep-02-2024
Cloudinary supports conditional transformations for videos, where a transformation is only applied if a specified condition is met, for example, if a video's width is greater than 300 pixels, apply a certain transformation.
See also: Conditional transformations for images.
Specifying conditions
To specify a condition to be met before applying a transformation, use the if
parameter (also if
in URLs). The if
parameter accepts a string value detailing the condition to evaluate, and is specified in the URL in the following format:
if_<video characteristic>_<operator>_<video characteristic value>
Where:
-
video characteristic
: The video parameter representing the characteristic to evaluate, for examplew
(orwidth
in SDKs). -
operator
: The comparison operator for the comparison, for examplelt
for 'less than' (or<
in SDKs). -
video characteristic value
: A hard coded value to check against, a supported user-defined variable containing a value to check against, or a different video characteristic you want to compare to.For example, if you only want to apply a transformation to non-square videos, you could check if the width characteristic of your video is not equal to its height characteristic:
if_w_ne_h
- Specify strings for a characteristic sub-element or value surrounded by
! !
. For example,if_ if_ctx:!productType!_eq_!shoes!
. - You can check whether a string characteristic currently has no value using
!!
.
For example:if some-condition_eq_!!
See examples below.
Supported video characteristics
Characteristic | Description |
---|---|
w |
(also width in SDKs) The asset's current width. |
iw |
The asset's initial width. |
h |
(also height in SDKs) The asset's current height. |
ih |
The asset's initial height. |
ar |
(also aspect_ratio in SDKs) The aspect ratio of the asset. The compared value can be either decimal (e.g., 1.5) or a ratio (e.g., 3:4). |
iar |
The asset's initial aspect ratio. |
ctx |
A contextual metadata value assigned to an asset. |
md |
A structured metadata value assigned to an asset. |
tags |
The set of tags assigned to the asset. |
du |
(also duration in SDKs) The current duration of the video. |
idu |
The video's initial duration. |
Supported operators
URL | SDK symbol | Description |
---|---|---|
eq |
= |
Equal to |
ne |
!= |
Not equal to |
lt |
< |
Less than |
gt |
> |
Greater than |
lte |
<= |
Less than or equal to |
gte |
>= |
Greater than or equal to |
in |nin
|
in |nin
|
Included in | Not included in Compares a set of strings against another set of strings. See Using the in and nin operators for examples. |
When working with the Cloudinary SDKs, you can specify the condition using the SDK characteristic names and operator symbols, or you can specify it using the URL format. For example, both of the following are valid:
- { if: "w_gt_1000"},...
- { if: "width > 1000"},...
Using the in and nin operators
The in
and nin
operators compare two sets of strings. The :
delimiter between strings denotes AND.
String sets can include tags, contextual metadata or structured metadata values, for example:
- To determine if
sale
andin_stock
are present in the tags of a particular asset, use:if_!sale:in_stock!_in_tags
. - To determine if the key named
color
exists in the contextual metadata of a particular asset, use:if_!color!_in_ctx
. - To determine if a structured metadata field with external ID,
color-id
, has been set for a particular asset, use:if_!color-id!_in_md
. - To determine if a list value with external ID,
green-id
, has been selected from a multiple-selection structured metadata field with external ID,colors-id
, for a particular asset, use:if_!green-id!_in_md:!colors-id!
.
Supported conditional video transformation parameters and flags
-
All video transformation parameters can be assigned in conditions except:
- You cannot assign transformation parameters for the
format
,fetch_format
,color_space
,delay
,video_codec
,audio_codec
,start_offset
,end_offset
, orduration
parameters. - The
angle
parameter cannot be set toignore
.
- You cannot assign transformation parameters for the
Only the following flags are supported inside conditional video transformations:
layer_apply
,relative
,attachment
,awebp
Notes
- For the
w
,h
, andar
parameters, the values refer to the current video status in the transformation chain (i.e., if transformations have already been applied to the video), whileiw
,ih
,iar
always refer to the original video. -
dpr
is not supported as a conditional transformation with thear
characteristic. Additionally,w
andh
are supported withdpr
as long as they are still equal toiw
orih
when the condition is evaluated. Ifdpr
is specified in the transformation as a whole, and one of the conditional branches includes a resizing transformation, you need to specify a resize transformation in all the other branches too. - The
ar
(aspect ratio) parameter should be compared using 'greater than' or 'less than' rather than with 'equals'. This is because the width and height values are given as integers and not floating point values, leading to an "almost exact" calculated aspect ratio. - Contextual metadata values are always stored as strings, even if the value is numeric, therefore you cannot use the
lt
,gt
,lte
andgte
operators to compare contextual metadata values numerically. You can, however, use these operators with numeric structured metadata values - see an example. - You can test whether or not a variable has been defined using the parameters
if_isdef_$<variable name>
andif_isndef_$<variable name>
(see Testing whether a variable has been defined).
Specifying transformations for a condition
The transformation for a condition should be specified between the condition component and an if_end
component in the format:
if_condition/transformation/if_end
For example:
if_ar_lt_1.0/b_darkorange,c_pad,h_300,w_500/if_end
In the following examples, both videos are scaled to a width of 500px. Afterwards, the identical conditional padded-resize transformation shown above is applied to both videos. However, since the condition applies only for portrait videos (those with an aspect ratio less than 1.0) the resizing and padding is applied only to the parrot
video below:
Transformation URLs technically support defining both the condition and a single resulting transformation inside a single transformation component (without the need for a closing end_if
). However, to avoid ambiguity, the best practice is to always use if
and if_end
components in your URL as shown above.
- Some SDKs require this separation and automatically generate URLs in the
if...end_if
format. - A named transformation cannot be placed in the same transformation component as its condition (e.g.,
if_w_eq_h,t_trans
is not supported) and must be specified using theif...if_end
format. - If you do include both the
if
condition and the resulting transformation parameters within a single component of the URL, theif
condition is evaluated first, regardless of its location within the component and (only) when the condition is true, all transformation parameters specified in that component are applied.
Conditions with chained transformations
You can apply multiple chained transformations to your condition by including the entire chained transformation in between the if
and if_end
components.
The example below checks whether the video asset's tags include a 'cloudinary' tag. Only in that case, a chained transformation including an image overlay (Cloudinary logo) and a text overlay ('By Cloudinary') are applied. If 'cloudinary' is not one of the tags, no image or text overlay is applied.
Note that this example also includes a scale-down transformation before the beginning of the conditional transformation and a duration trim after the end of the conditional transformation. Those transformations are applied regardless of the true or false result of the condition.
Multiple AND | OR conditions
You can specify multiple conditions to evaluate by joining the conditions with 'AND' or 'OR' conjunction operators.
The example below checks whether the video's aspect ratio is larger than a standard mobile portrait orientation AND if it has a large width. Only in this case, it crops the video to a portrait orientation with a width of 500. If the video already has a portrait orientation (condition 1 is false) or if the original width is less than 500 (condition 2 is false), the conditional transformation is ignored and the video is delivered in its original shape and size.
if...end_if
chained components in the URL.Else branch transformations
You can specify a transformation that is applied in the case that the initial condition is evaluated as false (and hence the transformations associated with the condition are not applied), by using the if_else
parameter to specify this fallback transformation.
For example, the following conditional transformation checks whether a video's aspect ratio is close to the desired aspect ratio, if it is close, then when the video is resized, any necessary padding is black. But if the aspect ratio is much smaller (for example, if it is a square or portrait video), then a blurred video padding is added.
In cases where the if
condition is not in the preceding transformation component, then the if_else
parameter also acts as an if_end
parameter: all chained transformation components until the one with if_else
are only applied if the previous condition holds true. Multiple conditional transformations can also be applied by adding an if_end
parameter to the last transformation component in the chain, and to avoid ambiguity, the component with the if_else
parameter should not have additional transformation instructions.
For example, if the video is shorter than or equal to 10 seconds, fade in for one second and fade out for one second, else if the video is longer than 10 seconds, fade in for two seconds and fade out for two seconds:
Conditional transformation examples
-
Conditional text overlay based on width: This example limits a video size to a width of 300 pixels using the
limit
crop mode, and then uses a conditional transformation to add a text caption only to videos whose initial width was wider than 300 and were scaled down (if_iw_gt_300
): -
Conditional resize based on a contextual metadata value: This example resizes a video to a 200*200 square video if it has a contextual metadata key named 'productType' with the value 'shoes'.
-
Conditional image overlay based on tags: This example adds a sale icon to a product video if both the strings 'sale' and 'in_stock' are among the tags assigned to the video:
* Conditional image overlay based on structured metadata value: This example adds a sale icon to a product video if the stock level of the product is less than 50 (as determined by the value of the numeric structured metadata field with external ID, stock-level
, here set as 30):
tags
, ctx
or md
parameters, 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.