> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# Media Optimizer transformations

Cloudinary's Media Optimizer is for targeted Enterprise organizations and simplifies the process to optimize and deliver high-quality media with high performance, low latency and massive scalability. 
> **The Media Optimizer documentation includes:**:
>
> **Guides**

> * [Quick starts](media_optimizer_quickstart)

> * [Configuration](media_optimizer_configuration)

> * [Dashboard](media_optimizer_dashboard)

> * [Reports](media_optimizer_reports)

> * [Transformations](media_optimizer_transformations)
> **References**

> * [Media Optimizer API](media_optimizer_api)

> * [Transformation reference](media_optimizer_transformation_reference)
This page covers Media Optimizer transformations, which provide the ability to transform your media on the fly, optimizing how it is delivered to your end users to achieve the best visually engaging experience.

## Transformations overview

In Cloudinary terminology, a **transformation** is an instruction to change a media file in some way. For example, the format of the media, its type of compression, its dimensions or its visual appearance. In Media Optimizer, transformations never affect the media source itself. They are performed on the fly, and the transformed media is cached for fast delivery. 

Transformations take the form of parameters that can be chained together, so one **transformation** can change the media in more than one way.
See all the [transformations that Media Optimizer supports](#supported_transformations). 

Using Media Optimizer, you can apply transformations to your media in two different ways:

* By defining [named transformations](#creating_a_named_transformation) that you can include in your [optimization profiles](#assigning_a_transformation_to_an_optimization_profile) as default (base) transformations. All media using a certain optimization profile then gets transformed in the same way.
* By adding transformation parameters as a query string to your delivery URLs, for example: `https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg?tx=w_500,h_500,c_fit`. This allows you to apply specific transformations to individual images or videos in addition to the ones applied through the optimization profile.

Media Optimizer comes with a default named transformation that specifies [automatic format](#automatic_format), [automatic quality](#automatic_quality) and [automatic responsive resizing](#automatic_responsive_resizing), called `auto_format_auto_quality_responsive_width`*. Media delivered with this transformation is automatically optimized for format, quality and size.

> **NOTE**:
>
> * If you don't see `auto_format_auto_quality_responsive_width` in your list of named transformations you can [manually create this transformation](#manually_create_auto_format_auto_quality_responsive_width), or simply use `auto_format_auto_quality` until [automatic responsive resizing](#automatic_responsive_resizing) is rolled out to all accounts.

Another automatic feature that you may want to use is [automatic cropping](#automatic_cropping). You can enable this setting when creating a named transformation and choosing to crop your images to the dimensions that you specify.

You can also create [custom transformations](#custom_transformations) within your named transformation, where you can specify any of the [supported transformations](#supported_transformations) in [URL syntax](media_optimizer_transformation_reference). 

### Resizing and cropping
Responsive design and art direction generally requires displaying images and videos  at a variety of sizes, often much smaller than the original.

If you deliver full size images and videos and rely on browser-side resizing (using CSS or HTML width and height attributes), users are forced to download unnecessarily large files. Therefore, images and videos  should always be delivered from the server at their final size.

When you use any of the Cloudinary [resizing transformations](media_optimizer_transformation_reference#c_crop_resize), the sizing (scaling/cropping) is performed on the server side, and the asset is always delivered to the browser at the requested size.

### Automatic responsive resizing (Early Access)

> **INFO**:
>
> **Automatic responsive resizing** is currently in Early Access. Some implementation details may change before the official release. We invite you to share any feedback via our [support team](https://support.cloudinary.com/hc/en-us/requests/new).

You can configure Media Optimizer to scale down images and videos automatically if they exceed the maximum width set for the type of viewing device. This saves bandwidth and speeds up delivery times.

The default maximum width is 828 pixels for smartphone devices and 1920 pixels for other devices, including desktops, laptops and tablets, but you can change these defaults when creating or editing a [basic transformation](#basic_transformations) or [custom transformation](#custom_transformations).  

Custom transformation: `w_responsive` (see [full syntax details](media_optimizer_transformation_reference#w_responsive)).

![Responsive width conceptual diagram](https://demo-mo-docs.mo.cloudinary.net/cld-docs-assets/assets/images/responsive-width.png?tx=c_scale,w_550/dpr_2.0 " width: 550, popup: true")

### Automatic cropping

Currently, Media Optimizer supports automatic cropping only for images.
Cloudinary's intelligent gravity selection capabilities ensure that the most interesting areas of each image are selected as the main focus for the requested crop, not only for photos with faces, but for any content type. Each image is analyzed individually to find the optimal region to include while cropping. Automatically detected faces (or other elements) are, by default, given higher priority while analyzing the image content.
You apply automatic content-aware gravity by setting the `gravity` transformation parameter to `auto` ([g_auto](media_optimizer_transformation_reference#g_auto) in URL syntax). If no gravity is specified in a crop, the image is cropped around its center.

Automatic cropping is supported for the [fill](media_optimizer_transformation_reference#c_fill), [lfill](media_optimizer_transformation_reference#c_lfill), [fill_pad](media_optimizer_transformation_reference#c_fill_pad), [thumb](media_optimizer_transformation_reference#c_thumb) and [crop](media_optimizer_transformation_reference#c_crop) modes.

Here are some examples of using automatic cropping:

Custom transformation: `c_fill,g_auto,h_300,w_200`

Original

Automatic fill

Custom transformation: `c_thumb,g_auto,h_150,w_150`

Original

Automatic thumbnail

Custom transformation: `c_crop,g_auto,h_200,w_200`

Original

Automatic crop 

### Automatic format

There are many formats for encoding images and videos, with some formats better than others at compression and reducing the file size without impairing visual quality. Since different browsers support different image and video formats and codecs, the best solution to optimize delivery time and save bandwidth is to deliver the best format according to the browser used by each of your visitors.

For example, see how the size of this image and video changes according to their formats:

Format | Size
---|---
AVIF | 14.6 KB
GIF | 98.0 KB
JPEG | 33.5 KB
JPEG XR | 17.3 KB
PNG | 190.0 KB
WebP | 16.1 KB

[//]: # ( When MO-402 is fixed, used this for the poster image: "demo-mo-docs.mo.cloudinary.net/cld-docs-assets/assets/videos/dog.mp4?tx=c_scale,w_500/f_jpg")

  
    
    
    
  

Format | Size
---|---
MP4 (H.264)| 821 KB
MP4 (HEVC) | 520 KB
WebM (VP9) | 482 KB

Using the automatic format feature ([f_auto](media_optimizer_transformation_reference#f_auto) in URL syntax), Media Optimizer makes the decision about the best format to deliver based on the requesting browser.  For images, if [automatic quality](#automatic_quality) is used in conjunction with automatic format, other factors are taken into account in addition to the requesting browser, such as the content of the image. 

### Automatic quality

Cloudinary's intelligent quality and encoding algorithm analyzes each image or video to decide on the best quality compression level and optimal encoding settings based on the media content and viewing browser, in order to produce the best visual quality while minimizing the file size.

The automatic quality feature ([q_auto](media_optimizer_transformation_reference#q_auto) in URL syntax) can be used to perform automatic quality encoding. Further control of the automatic quality selection is supported as follows:

* `q_auto` - The optimal balance between file size and visual quality. By default, this is the same as q_auto:good.
* `q_auto:best` - Less aggressive algorithm. Generates bigger files with potentially better visual quality.
* `q_auto:good` - Ensures a relatively small file size with good visual quality. Example of a target audience: stock media sites that display images and videos with a high visual quality.
* `q_auto:eco` - More aggressive algorithm, which results in smaller files of slightly lower visual quality. Example of a target audience: popular sites and social networks with a huge amount of traffic.
* `q_auto:low` - Most aggressive algorithm, which results in the smallest files of low visual quality. Example of a target audience: sites using thumbnail preview videos that then link to higher quality videos.

In addition to the automatic levels of quality, Media Optimizer lets you specify more fine-grained levels, using the URL syntax [q_\<quality level\>](media_optimizer_transformation_reference#q_quality_level) in a [custom transformation](#custom_transformations), where `<quality level>` is a value from 1 to 100. 

Examples of the resulting file size when encoding a photograph, using various regular and automatic quality parameter values:

Original (569KB)

q_80 (80.3KB)

q_auto:best (65.9KB)

q_auto:good (56.9KB)

q_auto:eco (45.0KB)

q_auto:low (35.0KB)

> **TIP**: If you don't specify a quality transformation in your optimization profile, the default quality settings in your [Console Settings](media_optimizer#account_settings) are applied when using any other transformation.

## Creating a named transformation

A named transformation is a set of image transformations that has been given a custom name for easy reference.

### Basic transformations

To create a basic named transformation:

1. Select the [Transformations](https://console.cloudinary.com/console/mo/transformations) tab in your Media Optimizer console.
2. Click **Add New**.
3. Enter a name for the transformation following these guidelines:
   * Must contain valid UTF8 characters only
   * Must not contain more than 1024 characters
   * Must not contain any of these characters: `\`, `/`, `?`, `&`, `#`, `%`, `.`, `,`, ``
4. Choose whether to include [auto format](#automatic_format) in the transformation. This option allows Cloudinary to analyze the content of the media and select the best format to deliver based on the user's browser.
5. Select the level of quality. The higher the quality, the higher the file size. Use one of the [auto quality](#automatic_quality) values to let Cloudinary determine the level of compression or encoding to apply.
6. Select whether to crop or resize the media. Choose from:
   * **Max width**: The size of the delivered media is limited to the specified maximum width, which differs for desktop devices (including laptops and tablets) and mobile devices (smartphones). If the original media exceeds the specified width, it is scaled down. See [Automatic responsive resizing (Early Access)](#automatic_responsive_resizing_early_access).
   * **Crop**: The crop option uses the [fill](media_optimizer_transformation_reference#c_fill) cropping mode to fill the specified dimensions, either by scaling up or down. If the requested aspect ratio is different than the original, cropping will occur on the dimension that exceeds the requested size after scaling. Enable smart crop to [automatically focus](#automatic_cropping) on the most visually interesting part of the image, rather than the center.  
   * **Resize**: The resize option performs a simple [scale](media_optimizer_transformation_reference#c_scale). If the specified dimensions change the aspect ratio of the original media, then the image or video may be stretched or squashed.
7. Click **Save**.

![Basic transformation form](https://demo-mo-docs.mo.cloudinary.net/cld-docs-assets/assets/images/automatic_everything.png?tx=c_scale,w_400/dpr_2.0 " width: 400, popup: true")

#### Manually create auto_format_auto_quality_responsive_width

While [automatic responsive resizing](#automatic_responsive_resizing) is in Early Access, you may not see the named transformation,  `auto_format_auto_quality_responsive_width`.  If you want to try out this transformation you can create it yourself, following the instructions in [Basic transformations](#basic_transformations) with the following settings:

* **Transformation name**: `auto_format_auto_quality_responsive_width`
* **Format**: `Auto`
* **Quality**: `Auto: good`
* **Resize**: `Max width`
* **Desktop**: `1920`
* **Mobile**: `828`

Then, select this transformation as the **Base transformation** in your [optimization profile](#assigning_a_transformation_to_an_optimization_profile).

If you have already served media through the optimization profile, you need to [invalidate the cache for those assets](media_optimizer_configuration#invalidate_cached_assets) so that new requests will use the new transformation.

### Custom transformations

To create a custom transformation:

1. Select the [Transformations](https://console.cloudinary.com/console/mo/transformations) tab in your Media Optimizer console.
2. Click **New Advanced Transformation** from the **Add New** drop-down. 
![New advanced transformation option](https://demo-mo-docs.mo.cloudinary.net/cld-docs-assets/assets/images/new_advanced_transformation.png?tx=c_scale,w_200/dpr_2.0 "width: 200, popup: true")
3. Enter a name for the transformation following these guidelines:
   * Must contain valid UTF8 characters only
   * Must not contain more than 1024 characters
   * Must not contain any of these characters: `\`, `/`, `?`, `&`, `#`, `%`, `.`, `,`, ``
4. In the **Transformation String** field, define a custom transformation in [URL syntax](media_optimizer_transformation_reference), using any of the [supported transformations](#supported_transformations). See [Custom transformation example](#custom_transformation_example).
5. Click **Save**.

![Custom transformation form](https://demo-mo-docs.mo.cloudinary.net/cld-docs-assets/assets/images/custom_transformation.png?tx=c_scale,w_400/dpr_2.0 "width: 400, popup: true")

#### Custom transformation example

To resize all media to fit a space of 150 x 150 pixels, with black padding, and deliver with automatic format and quality, type: `b_black,c_pad,h_150,w_150/f_auto/q_auto`.

![People walking](https://demo-mo-docs.mo.cloudinary.net/custom/cld-docs-assets/assets/images/people-walking.jpg "with_code: false, with_url: false")

[//]: # ( When MO-402 is fixed, used this for the poster image: "demo-mo-docs.mo.cloudinary.net/custom/cld-docs-assets/assets/videos/dog.mp4?tx=f_jpg")

  
  
  

## Editing a named transformation

To edit a named transformation:

1. Select the [Transformations](https://console.cloudinary.com/console/mo/transformations) tab in your Media Optimizer console.
1. Click the **Edit transformation** icon for the transformation you want to edit.
  ![Edit option for a named transformation](https://demo-mo-docs.mo.cloudinary.net/cld-docs-assets/assets/images/edit_transformation.png?tx=c_scale,w_700/dpr_2.0 "width: 700, popup: true")
1. Make the required changes and click **Save**.

> **INFO**: When you change a named transformation, assets that have already been delivered using the old transformation settings are not updated unless you [invalidate these assets on the cache](media_optimizer_configuration#invalidate_cached_assets).

## Assigning a transformation to an optimization profile

To set the default (base) transformation of an optimization profile, assign a named transformation to the optimization profile as follows:

1. Select the [Configuration](https://console.cloudinary.com/console/mo/configuration) tab in your Media Optimizer console.
2. Either select an existing optimization profile and select **Edit** from the kebab menu, or create a new optimization profile by clicking **Add New**.
3. Select the transformation from the **Base transformation** drop-down.
4. Enter any other required settings and click **Save**. 

## Transforming large assets

Some assets are too large to be transformed on the fly. You can see the limits that apply to your account on the right of your **Console Settings**:

* Maximum online image manipulation size
* Maximum online video manipulation size

If an image or video exceeds these limits, it can still be optimized through Media Optimizer, but the transformed version needs to be created in advance using the [cache_warm_up](media_optimizer_api#cache_warm_up) API endpoint.

For example:

```
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/mycloud/cache_warm_up -X POST --data 'url=https://mycloud.mo.cloudinary.net/videos/large_video.mp4?tx=t_complex'
```

## Supported transformations

The following table shows all the transformations that are supported by Media Optimizer. These let you specify your own optimization behaviors and are generally used when you want to optimize different sets of assets in different ways. 

You can find full syntax details and examples of each transformation in the [Media Optimizer transformation reference](media_optimizer_transformation_reference).

Transformation | Description 
---|---
ac (audio codec) | Sets the audio codec used in a video.
ar (aspect ratio) | Sets the desired aspect ratio of an asset.
b (background) | Applies a background to empty or transparent areas.**Note:** `b_auto` is not supported.
br (bitrate) | Controls the video bitrate.
c (crop/resize) | Changes the size of the delivered asset according to the requested dimensions.
cs (color space) | Controls the color space used for the delivered image or video. **Note:** `cmyk` is not supported.
dl (delay) | Controls the time delay between the frames of a delivered animated image. 
dpr (DPR) | Sets the device pixel ratio (DPR) for the delivered image or video.
e_loop | Loops a video or animated image the specified number of times.
e_sharpen | Applies a sharpening filter to an image.
f (format)| Converts and delivers an asset in the specified format (see [Supported media formats](#supported_media_formats)).Use `f_auto` to deliver the asset in the optimal format for the requesting browser.
fl_getinfo | Returns metadata of both the input asset and the transformed output asset in JSON instead of delivering a transformed image.
fl_ignore_aspect_ratio | When only one dimension is specified with `c_scale`, only that dimension is changed if this flag is specified.
fl_progressive | Delivers an image using the progressive (interlaced) format.  
fps (FPS) | Controls the frames per second of a video. 
g (gravity) | Determines which part of an asset to focus on, and thus which part of the asset to keep, when any part of the asset is cropped.Use `g_auto` to automatically identify the most interesting regions in an image. **Note:** `g_auto` is not supported for video using Media Optimizer.
h (height) | Sets the desired height of an asset.
if (if condition) | Applies a transformation only if a specified condition is met.
q (quality) | Controls the quality of the delivered asset.Use `q_auto` to deliver an asset with an automatically determined level of quality. 
t (named transformation) | Applies a pre-defined named transformation to an asset.
vc (video codec) | Sets a specific video codec to use to encode a video.Use `vc_auto` to select the best codec based on the output format automatically.
w (width) | Sets the desired width of an asset.**Note:** `w_auto` is not supported.
x, y (x & y coordinates) | Adjusts the starting location or offset of the corresponding transformation action.
z (zoom) | Controls how much of the original image surrounding the face to keep when using face detection.
$ (variable) | Defines and assigns values to user defined variables, so you can use the variables as values for other parameters.

### Supported media formats

Media Optimizer lets you specify the format in which to deliver your media. The `format` parameter (`f` in URL syntax) can take the value of any of the extensions shown in the tables below. To let Media Optimizer determine the best format to deliver, use [automatic format](#automatic_format).

#### Supported image formats

The following image formats are supported by Media Optimizer:

Format | Extensions
--- | --- | --- | --- 
animated GIF | .gif 
animated PNG | .png 
animated WebP | .webp
AVIF | .avif 
EPS (Encapsulated PostScript) |	.ps, .ept, .eps, .eps3
GIF | .gif 
HEIF | .heif, .heic 
JPEG | .jpg, .jpe, .jpeg 
JPEG XR (JPEG eXtended Range) | .wdp, .jxr, .hdp 
PNG  | .png 
SVG | .svg 
WebP | .webp 

#### Supported video formats

The following video formats are supported by Media Optimizer:

Format | Extensions | Default Codec
--- | --- | ---
MOV | mov | h264
MKV (Matroska Multimedia Container) | mkv | 
MP4 | mp4 | h264
OGV (Ogg Video) | ogv | 
WebM | webm | VP9

#### Supported audio formats

The following audio formats are supported by Media Optimizer:

Format | Extensions 
--- | --- 
AAC (Advanced Audio Coding) | aac 
AIFF (Audio Interchange File Format) | aiff 
M4A | m4a 
MP3 (MPEG-3) | mp3 
OGG | ogg 
WAV (Waveform Audio File Format) | wav

## Handling of raw formats

Any files that are not detected as image, video or audio are treated by Media Optimizer as 'raw' files. This means they are delivered 'as is', without any optimizing. 

Unlike in Programmable Media and Assets, where PDFs are considered to be image types, in Media Optimizer, PDFs are considered to be raw files. PDFs are delivered with content-type: `application/pdf` so they are handled by browsers in the usual way. 

> **READING**:
>
> :no-icon :title=Important note for free accounts
> To reduce the chances of malware or other potentially harmful files being distributed via Media Optimizer, the following file formats are, by default, blocked for delivery for **free** accounts:

> * **zip**, **rar**, **tagz**, and other archive formats

> * **pdf**
> If you are on a Free plan and need to deliver files in these formats, you can navigate to the **Security** page of the **Console Settings** and select to **Allow delivery of PDF and ZIP files**. Additionally, these delivery limitations are removed when you upgrade to a [paid plan](https://cloudinary.com/pricing#pricing-content-2).