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

# Dart media transformations

After you or your users have uploaded media assets to Cloudinary, you can deliver them via dynamic URLs. You can include instructions in your dynamic URLs that tell Cloudinary to transform your assets using a set of transformation actions. All transformations are performed automatically in the cloud and your transformed assets are automatically optimized before they are routed through a fast CDN to the end user for optimal user experience.

For example, you can resize and crop, add overlay images or concatenate videos, blur or pixelate faces, apply a large variety of special effects and filters, and apply settings to optimize your media and to deliver them responsively.

Cloudinary's Dart SDK simplifies the generation of transformation URLs for easy embedding of assets in your Dart application. You can use the [Dart reference](https://cloudinary.com/documentation/sdks/js/transformation-builder/index.html) to find all available transformations, syntax and examples.

## Syntax Overview
The Cloudinary Dart SDK provides a simple and enhanced developer experience:

* When compiled to the final delivery URL, each action represents a different [transformation component](image_transformations#chained_transformations).
* It allows discovering the available options from within your development environment, and ensures that only options that are supported can be used together.

![Flutter syntax overview](https://cloudinary-res.cloudinary.com/image/upload/v1669202165/docs/sdk/dart_syntax.png "with_url:false, with_code: false, width: 600px")

* **Action Group**: An `Action Group` represents a directive to Cloudinary on how to transform a specific aspect of an asset (e.g., `adjust`, `effect` or `resize`).
* **Action**: The `Action` defines the specific Action to apply (e.g., `adjust(Adjust.replaceColor())`, `effect(Effect.blur())` or `resize(Resize.crop())`). 
* **Qualifier**: `Qualifiers` further define how to apply an Action (e.g., `tolerance` qualifies the `adjust(Adjust.replaceColor())` Action with a value of `tolerance(17)`). Some Actions also have a required qualifier which is then given as part of the action method (e.g., `adjust(Adjust.replaceColor(Color.gold()))` to specify the color to apply).

The output of each `Action` is a complete transformation component (separated by slashes) in the URL. For example, the syntax example above would generate a URL similar to the following:

```
https://res.cloudinary.com/demo/image/upload/e_replace_color:gold:17/mypic.jpg
```

### Supported action groups
Most transformations can be passed as parameters that follow Cloudinary's new action based syntax. You can discover all supported parameters by using the enhanced code autocomplete feature. Enter the `Action Group` that you'd like to use and all supported `Actions` in that group and their syntax will be displayed. Once you choose an `Action`, its supported `Qualifiers` will be displayed.

The following `Action Groups` are currently supported:

* `adjust`: Consists of `Actions` that make subtle changes and improvements to the asset, such as `brightness` and `opacity`.
* `border`: Draws a border around your asset.
* `delivery`: Enables you to set quality, format, and DPR settings for delivering your assets.
* `effect`: Allows you to add special effects to your images (`cartoonify`, `blur`, and `pixilate`) and videos (`boomerang` and `loop`).
* `addTransformation`: Enables you to pass a transformation directly as a [string](#passing_transformations_as_strings).
* `resize`: Provides many options for resizing and cropping assets, including padding, scaling, fitting, adding a specific height and width, specifying gravity, and more. 
* `rotate`: Provides settings for rotating your assets.
* `roundCorners`: Rounds the corners of the asset. Depending on your specifications, the effect ranges from subtle rounding to a fully rounded circle or oval shape.

> **NOTE**:
>
> When you add an action, the required `import` statement is inserted automatically, with the exception of: 

> * `border`: Manually add the `import 'package:cloudinary_url_gen/transformation/border.dart' as border;` import statement to differentiate Cloudinary's `border` class from Dart's.

> * `adjust` with `replaceColor`: Manually add the `import 'package:cloudinary_url_gen/transformation/color.dart';` import statement.

### Passing transformations as strings

Most transformations can be passed as parameters using the action based syntax. However, some transformations can only be passed as strings. 
* Use the autocomplete feature to find out which transformations are supported for the new action based syntax. 
* See the [Transformation URL API reference](transformation_reference) for a comprehensive listing of all available transformations and the syntax to use when passing them as strings. 
* Pass the string transformation via the `addTransformation()` [Action Group](#syntax_overview).  

The following example shows a resized image. An overlay is applied to it using  transformations passed as a string: 
```dart
(cloudinary.image('sample')
  ..transformation(Transformation()
    ..resize(Resize.crop()
      ..gravity(Gravity.autoGravity())
      ..height(1.0)
      ..x(30)
      ..y(20)
      ..aspectRatio(1.5))
    ..addTransformation('l_cloudinary_icon/fl_layer_apply,g_north_east,w_0.2,x_30,y_20,o_70,fl_relative')))
  .toString();

// Output: 'https://res.cloudinary.com/demo/image/upload/c_crop,g_auto,ar_1,h_1.0/l_cloudinary_icon/fl_layer_apply,g_north_east,w_0.2,x_30,y_20,o_70,fl_relative/sunset_shoes.jpg'
```

## Deliver and transform images

You can deliver your media using direct URL-building directives, and then add them to your image or video view.

### Direct URL building

To build an image, video, or non-media file URL, use the `cloudinary.image`, `cloudinary.video` or `cloudinary.raw` helper methods. 

```dart
(cloudinary.raw('sample_spreadsheet.xls')).toString();

// Output: "https://res.cloudinary.com/demo/raw/upload/sample_spreadsheet.xls"
```

When building image or video URLs, you can add transformations as shown in the example below:

```dart
(cloudinary.image('sample')
  ..transformation(Transformation()
    ..resize(Resize.fill()
      ..width(100)
      ..height(150))))
  .toString();

// Output: "https://res.cloudinary.com/demo/image/upload/c_fill,h_150,w_100/sample"
```

### Applying named transformations
You can pre-define a set of transformations and assign them a [name](image_transformations#named_transformations). Then, you can simply apply that entire set of transformations to URLs by referencing their name. This shortens complex transformation URLs and makes it easy to reuse transformations on multiple assets.

You can create and manage named transformations via the API or in the console UI using the [Transformation Builder](https://console.cloudinary.com/app/image/transformation_builder).

Let's say you have a named transformation called `fun_effects` that contains the `cartoonify` and `outline` effects, as well as a `pad` resize transformation with a `height` parameter of 300px.  

These transformations can then be automatically applied when building a URL:

```dart
(cloudinary.image('actor.jpg')
  ..transformation(Transformation()
    ..namedTransformation('fun_effects')))
  .toString();
  
// Output: https://res.cloudinary.com/demo/image/upload/t_fun_effects/actor.jpg
```

### Combining transformations
Cloudinary supports powerful transformations. You can even combine multiple transformations together as part of a single transformation request, e.g. crop an image and add a border. In certain cases you may want to perform additional transformations on the result of the previous transformation request.

To support multiple transformations in a transformation URL, you can include multiple transformation components, each separated by a '/'. Each transformation component is applied to the result of the previous one. In Dart, applying multiple transformations is achieved by simply adding the next `Action` to the transformation. The following example first fills the image within a 250px square, then rounds the result to a circle, and finally delivers the image in the optimal transparent format:
![3 chained transformations applied to an image](https://res.cloudinary.com/demo/image/upload/ar_1.0,c_fill,w_250/r_max/f_auto/livingroom-yellow-chair.png "disable_all_tab:true, frameworks:dart")

```dart
cloudinary.image('livingroom-yellow-chair.png').transformation(Transformation()
	.resize(Resize.fill().width(250)
.aspectRatio('1.0'))
	.roundCorners(RoundCorners.max())
	.delivery(Delivery.format(
	Format.auto())));
```

The following example applies 4 chained transformations: fill to a 250*400px portrait, then rotate the result by 20 degrees, then add a brown outline to the rotated image, and optimize the resulting image to deliver with the best compression that gives good visual quality and in the optimal transparent format:

![4 chained transformations applied to an image](https://res.cloudinary.com/demo/image/upload/c_fill,h_400,w_250/a_20/e_outline,co_brown/q_auto/f_auto/kitchen-island.png "thumb:h_350,dpr_2, height:350, disable_all_tab:true, frameworks:dart")

```dart
cloudinary.image('kitchen-island.png').transformation(Transformation()
	.resize(Resize.fill().width(250)
.height(400))
	.rotate(Rotate.byAngle(20))
	.effect(Effect.outline()
	.color(Color.BROWN)
	)
	.delivery(Delivery.quality(
	Quality.auto()))
	.delivery(Delivery.format(
	Format.auto())));
```

## Apply common image transformations

This section provides an overview and examples of the following commonly used image transformation features, along with links to more detailed documentation on these features:

* [Resizing and cropping](#resizing_and_cropping)
* [Converting to another image format](#converting_to_another_image_format)
* [Applying image effects and filters](#applying_image_effects_and_filters)
* [Adding text and image overlays](#adding_text_and_image_overlays)
* [Image optimizations](#image_optimizations)

Keep in mind that this section is only intended to introduce you to the basics of using image transformations with Dart. 

For comprehensive explanations of how to implement a wide variety of transformations, see [Image transformations](image_transformations).
For a full list of all supported image transformations and their usage, see the [Transformation URL API Reference](transformation_reference).

### Resizing and cropping

There are a variety of different ways to resize and/or crop your images, and to control the area of the image that is preserved during a crop. 

```dart
(cloudinary.image('brown_sheep')
  ..transformation(Transformation()
    ..resize(Resize.fill()
      ..width(750)
      ..height(750)
      ..gravity(Gravity().focusOn([FocusOn.faces])))))
  .toString();
```

Original image

Fill cropping with 'faces' gravity

You can also use automatic gravity to determine what to keep in the crop automatically.

```dart
(cloudinary.image('brown_sheep')
  ..transformation(Transformation()
    ..resize(Resize.fill()
      ..width(240)
      ..height(300)
      ..gravity(Gravity.autoGravity()))))
  .toString();
```

Original image

Fill cropping with 'auto' gravity

For details on all resizing and cropping options, see [resizing and cropping images](resizing_and_cropping).

### Converting to another image format

You can deliver any image uploaded to Cloudinary in essentially any image format. There are three main ways to convert and deliver in another format:

* Specify the image's [public ID](cloudinary_glossary#public_id) with the desired extension. 
* Explicitly set the desired format using the `Delivery.format()` action. 
* Use the `Format.auto` Qualifier to instruct Cloudinary to deliver the image in the most optimized format for each browser that requests it.

For example:

1\. Deliver a .jpg file in .png format: 

```dart
(cloudinary.image('sample')
  ..transformation(Transformation()
    ..delivery(Delivery.format(Format.png))))
  .toString();
```

2\. Let Cloudinary select the optimal format for each browser. For example, in Chrome, this image may deliver in **.avif** or **.webp** format (depending on your product environment setup):

```dart
(cloudinary.image('cloud_castle')
  ..transformation(Transformation()
    ..delivery(Delivery.format(Format.auto))))
  .toString();
```

The above code generates a URL with the `f_auto` parameter:

![Let Cloudinary select the optimal format to deliver for each browser.](https://res.cloudinary.com/demo/image/upload/f_auto/q_auto/c_scale,w_350/f_auto/cloud_castle.jpg "thumb: w_350,dpr_2, width:350, with_code:false, with_url:false, popup:true")

For more details, see:

* [Delivering images in different formats](image_transformations#delivering_in_a_different_format)
* [Automatic format selection (f_auto)](image_optimization#automatic_format_selection_f_auto)
* [Tips and considerations for using f_auto](image_optimization#tips_and_considerations_for_using_f_auto)

### Applying image effects and filters

You can select from a large range of image effects, enhancements, and filters to apply to your images. The available effects include a variety of color balance and level effects, tinting, blurring, pixelating, sharpening, automatic improvement effects, artistic filters, distortion and shape changing effects, outlines, backgrounds, shadows, and more.

For example, the code below applies a cartoonify effect and an outline effect, rounds the corners, adds a border, and then pads the image to a width of 300 pixels.

```dart
// Add this statement manually when specifying `border`:
import 'package:cloudinary_url_gen/transformation/border.dart' as border;

(cloudinary.image('actor.jpg')
  ..transformation(Transformation()
    ..effect(Effect.cartoonify())
    ..effect(Effect.outline()
      ..color(Color.lightBlue())
      ..width(100))
    ..roundCorners(RoundCorners.max())
    ..border(border.Border.solid(4, Color.black()))
    ..resize(Resize.pad()
      ..width(300))))
  .toString();
```

![An image with several transformation effects](https://res.cloudinary.com/demo/image/upload/e_cartoonify/r_max/e_outline:100,co_lightblue/b_lightblue,w_300,c_pad/actor.jpg "thumb: w_300,dpr_2, width:300, with_code:false, with_url:false, popup:true")

For more details on the available image effects and filters, see [Visual image effects and enhancements](effects_and_artistic_enhancements).

### Adding text and image overlays

You can add images and text as overlays on your main image. You can apply the same types of transformations on your overlay images as you can with any image and you can use gravity settings or x and y coordinates to control the location of the overlays. You can also apply a variety of transformations on text, such as color, font, size, rotation, and more.

For example, the code below overlays a couple's photo on a mug image. The overlay photo is cropped using face detection with adjusted color saturation and a vignette effect applied. The word love is added in a brown, fancy font and placed to fit the design.  Additionally, the final image is cropped and the corners are rounded.

![An image with many transformations and overlays applied](https://res.cloudinary.com/demo/image/upload/w_400,h_250,c_fill,g_south/l_nice_couple,w_1.3,h_1.3,g_faces,c_crop,fl_region_relative/e_saturation:50/e_vignette/fl_layer_apply,w_100,r_max,g_center,y_15,x_-20/l_text:Cookie_23_bold:Love,co_rgb:744700/fl_layer_apply,x_-23,y_50/c_crop,w_300,h_250,x_30/r_60/coffee_cup.png "disable_all_tab: true, frameworks:dart, with_url:false")

```dart
cloudinary.image('coffee_cup.png').transformation(Transformation()
	.addTransformation("w_400,h_250,c_fill,g_south/l_nice_couple,w_1.3,h_1.3,g_faces,c_crop,fl_region_relative/e_saturation:50/e_vignette/fl_layer_apply,w_100,r_max,g_center,y_15,x_-20/l_text:Cookie_23_bold:Love,co_rgb:744700/fl_layer_apply,x_-23,y_50/c_crop,w_300,h_250,x_30/r_60"));
```

### Image optimizations

By default, Cloudinary automatically performs certain optimizations on all transformed images. There are also a number of additional features that enable you to further optimize the images you use in your application. These include optimizations to image quality, format, and size, among others.

For example, you can use the `auto` value for the `Format` and `Quality` attributes to automatically deliver the image in the format and quality that minimize file size while meeting the required quality level. In addition, resize the image to make it even lighter. Below, these parameters are applied, resulting in a 25.66 KB AVIF file (in Chrome) instead of a 1.34 MB JPG with no visible change in quality. 

![Efficient file size optimization using auto format and auto quality features](https://res.cloudinary.com/demo/image/upload/w_500/f_auto,q_auto/pond_reflect.jpg "disable_all_tab: true, with_url:false, frameworks:dart")

```dart
cloudinary.image('pond_reflect.jpg').transformation(Transformation()
	.resize(Resize.scale().width(500))
	.delivery(Delivery.format(
	Format.auto()))
	.delivery(Delivery.quality(
	Quality.auto())));
```

For an in-depth review of the many ways you can optimize your images, see [Image optimization](image_optimization).

## Apply common video transformations

This section provides an overview and examples of the following commonly used video transformation features, along with links to more detailed documentation on these features:

* [Resizing and cropping videos](#resizing_and_cropping_videos)
* [Concatenating videos](#concatenating_videos)
* [Trimming videos](#trimming_videos)
* [Adding video overlays](#adding_video_overlays)
* [Adding video effects](#adding_video_effects)

Keep in mind that this section is only intended to introduce you to the basics of using video transformations with Dart. 

For a full list of all supported video transformations and their usage, see the [Transformation URL API Reference](transformation_reference).

For comprehensive explanations of how to implement a wide variety of transformations, see [Video transformations](video_manipulation_and_delivery).

### Resizing and cropping videos

There are a variety of different ways to resize and/or crop your videos, and to control the area of the video that is preserved during a crop. The following examples:

* crop the video to a height of 800px and a width of 750px in a specified area starting at 200px from the left and 450px from the top.
* resize the video to a height of 320px and width of 480px while padding the extra space with the original asset blurred playing in the background to preserve the original aspect ratio.

```dart
(cloudinary.video('play_time')
  ..transformation(Transformation()
    ..resize(Resize.crop()
      ..x(200)
      ..y(450))))
  .toString();

// Output: https://res.cloudinary.com/demo/video/upload/c_crop,h_800,w_750/x_200,y_450/v1/play_time
```

```dart
(cloudinary.video('play_time')
  ..transformation(Transformation()
    ..effect(Effect.blur()..strength(400))
    ..resize(Resize.pad()
      ..height(320)
      ..width(480))))
  .toString();

// Output: https://res.cloudinary.com/demo/video/upload/b_blurred:400/c_pad,h_320,w_480/v1/play_time
```

  
    
    
    
  
Original video

  
    
    
    
  
Keep centered<code>c_crop,x_200,y_450

  
    
    
    
  
Pad with blurred video<code>b_blurred:400/c_pad,h_320,w_480

For all the ways in which a video can be cropped, see the parameters under the [c (crop)](transformation_reference#c_crop_resize) section of the _Transformation URL Reference_ that are marked as supported for video.

For details on all resizing and cropping options, see [Resizing and cropping videos](video_resizing_and_cropping).

### Concatenating videos

You can concatenate videos with a variety of options, including concatenating only a portion of the videos, concatenating a video at the beginning or end of another, creating custom transitions between concatenated videos, and concatenating an image to a video.

The following example shows two videos shortened to 5 seconds each ([du_5.0](transformation_reference#du_duration)), the main video starting with an offset of 1 second ([so_1](transformation_reference#so_start_offset)), with both videos uniformly resized ([c_fill,h_300,w_450](transformation_reference#c_fill)) and concatenated ([fl_splice](transformation_reference#fl_splice)):

```dart
(cloudinary.video('horse_race')
  ..transformation(Transformation()
    ..resize(Resize.fill()
      ..height(300)
      ..width(450))
    ..addTransformation('du_5.0,so_1/fl_splice,l_video:swimming_race/c_fill,h_300,w_450/du_5.0/fl_layer_apply')))
  .toString();

// Output: https://res.cloudinary.com/demo/video/upload/c_fill,h_300,w_450/du_5.0,so_1/fl_splice,l_video:swimming_race/c_fill,h_300,w_450/du_5.0/fl_layer_apply/v1/horse_race
```

  
    
    
    
  

For a detailed description of how to concatenate videos, see the [splice](transformation_reference#fl_splice) parameter of the [fl_flag](transformation_reference#fl_flag) section of the _Transformation URL Reference_.

For details on all the ways in which you can concatenate videos, see [Concatenating media](video_trimming_and_concatenating#concatenating_media).

### Trimming videos

When trimming your videos, you can determine when to start trimming, when to stop, and / or the duration of the trimmed video. 

The following example shows trimming a video to the section that starts at 3.5 seconds ([so_3.5](transformation_reference#so_start_offset)) with a duration of 5 seconds ([du_5](transformation_reference#du_duration)):

```dart
(cloudinary.video('dog_mirror')
  ..transformation(Transformation()
    ..resize(Resize.scale()
      ..width(450))
    ..addTransformation('du_5.0,so_3.5')))
  .toString();

// Output: https://res.cloudinary.com/demo/video/upload/c_scale,w_450/du_5.0,so_3.5/v1/dog_mirror
```

  
    
    
    
  

For all the ways in which a video can be trimmed, see the [so (start_offset)](transformation_reference#so_start_offset), [du (duration)](transformation_reference#du_duration), [eo (end_offset)](transformation_reference#eo_end_offset) parameters the _Transformation URL Reference_ that are marked as supported for video.

For more details on trimming videos, see [Trimming videos](video_trimming_and_concatenating#trimming_videos).

### Adding video overlays

You can add video, text, or image overlays onto your videos.

The following example shows one video scaled down ([c_scale,w_80](transformation_reference#c_scale)) and placed in the north-east corner ([g_north_east](transformation_reference#g_gravity)) as an overlay ([l_video:exercise2](transformation_reference#l_video)), starting 3 seconds after the main video starts playing ([so_3](transformation_reference#so_start_offset)):

```dart
(cloudinary.video('dog_mirror')
  ..transformation(Transformation()
    ..resize(Resize.scale()
      ..width(300))
    ..addTransformation('l_video:exercise2/c_fit,w_80/bo_2px_solid_blue/fl_layer_apply,g_north_east,so_2.0')))
  .toString();

// Output: https://res.cloudinary.com/demo/video/upload/c_scale,w_300/l_video:exercise2/c_fit,w_80/bo_2px_solid_blue/fl_layer_apply,g_north_east,so_2.0/v1/exercise1
```

  
    
    
    
  

For all the ways in which you can add video overlays, see the parameters under the [l (layer)](transformation_reference#l_layer) section of the _Transformation URL Reference_ that are marked as supported for video.

For more details on video overlays, see [Placing layers on videos](video_layers).

### Adding video effects

You can select from a large variety of video effects, enhancements, and filters to apply to your video. The available effects include speed, direction, and looping control, adding a progress indicator overlay, different transparency settings, AI generated preview, a variety of color balance and level effects, blurring, fading, and automatic improvement effects.

The following example shows a video that fades in and out `Effect.fadeIn(2000)`, `Effect.fadeOut(4000)`, loops twice `Effect.loop(2)`, and has a vignette filter applied `Effect.vignette().strength(50)`:

```dart
(cloudinary.video('dog_garden')
  ..transformation(Transformation()
    ..resize(Resize.scale()
      ..width(400))
    ..addTransformation('du_10.0')
    ..effect(Effect.vignette().strength(50))
    ..effect(Effect.fadeIn(2000))
    ..effect(Effect.fadeOut(4000))
    ..effect(Effect.loop(2))))
  .toString();

// Output: https://res.cloudinary.com/demo/video/upload/c_scale,w_400/du_10.0/e_vignette:50/e_fade:2000/e_fade:-4000/e_loop:2/v1/dog_garden
```

![Vignette effect](https://res.cloudinary.com/demo/video/upload/w_400/du_10/e_vignette:50/e_fade:2000/e_fade:-4000/e_loop:2/v1/dog_garden "with_code: false")

For all video effects, see the parameters under the [e (effect)](transformation_reference#e_effect) section of the _Transformation URL Reference_ that are marked as supported for video.

For an in-depth review of all the available video effects, see [Video Effects](video_effects_and_enhancements).