Conditional transformations

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.

This page covers the condition syntax and the video characteristics and operators you can use. To learn how to apply a transformation when a condition is met, see Specifying transformations for a condition. For multiple AND/OR conditions and else branches, see Advanced conditional transformations for video.

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 example w (or width in SDKs).
• operator: The comparison operator for the comparison, for example lt 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

See examples.

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 and in_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, or duration parameters.
  • The angle parameter cannot be set to ignore.

• Only the following flags are supported inside conditional video transformations:
  layer_apply, relative, attachment, awebp

Notes

• For the w, h, and ar parameters, the values refer to the current video status in the transformation chain (i.e., if transformations have already been applied to the video), while iw, ih, iar always refer to the original video.
• dpr is not supported as a conditional transformation with the ar characteristic. Additionally, w and h are supported with dpr as long as they are still equal to iw or ih when the condition is evaluated. If dpr 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 and gte 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> and if_isndef_$<variable name> (see Testing whether a variable has been defined).