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.

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.

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

• By defining named transformations that you can include in your optimization profiles 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 quality and automatic responsive resizing, called auto_format_auto_quality_responsive_width^*. Media delivered with this transformation is automatically optimized for format, quality and size.

Another automatic feature that you may want to use is 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 within your named transformation, where you can specify any of the supported transformations in URL syntax.

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, 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)

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 or custom transformation.

Custom transformation: w_responsive (see full syntax details).

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 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, lfill, fill_pad, thumb and 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:

Using the automatic format feature (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 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 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> in a custom transformation, 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)

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 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 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 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).
   • Crop: The crop option uses the 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 on the most visually interesting part of the image, rather than the center.
     
   • Resize: The resize option performs a simple scale. If the specified dimensions change the aspect ratio of the original media, then the image or video may be stretched or shrunk.
7. Click Save.

Manually create auto_format_auto_quality_responsive_width

While 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 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.

If you have already served media through the optimization profile, you need to invalidate the cache for those assets so that new requests will use the new transformation.

Custom transformations

To create a custom transformation:

1. Select the Transformations tab in your Media Optimizer console.
2. Click New Advanced Transformation from the Add New drop-down.

   

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, using any of the supported transformations. See Custom transformation example.
5. Click Save.

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.

Editing a named transformation

To edit a named transformation:

1. Select the Transformations tab in your Media Optimizer console.
2. Click the Edit transformation icon for the transformation you want to edit.

   

3. Make the required changes and click Save.

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 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 API endpoint.

For example:

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.

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.

Supported image formats

The following image formats are supported by Media Optimizer:

Supported video formats

The following video formats are supported by Media Optimizer:

Supported audio formats

The following audio formats are supported by Media Optimizer:

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 DAM, 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.