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

# Video gravity for crops


[resize-and-crop-modes-link]:video_resizing_and_cropping#resize_and_crop_modes
[fill-mode-link]:video_crop_modes#fill

The `gravity` parameter (`g` in URLs) controls which part of a video to keep when cropping. By default, Cloudinary keeps the center of the video. This page covers compass positions, face detection, and AI-powered automatic gravity (`g_auto`).

**See full syntax**: [g (gravity)](transformation_reference#g_gravity) in the _Transformation Reference_.

## Compass positions

The basic gravity value is specified by giving a compass direction to include: `north_east`, `north`, `north_west`, `west`, `south_west`, `south`, `south_east`, `east`, or `center` (the default value). The compass direction represents a location in the video, for example, `north_east` represents the top right corner.
  
For example, [fill][fill-mode-link] a 250-pixel square with the {variable:mediaName3} video while retaining the aspect ratio:

* Original video: ![Original image](https://res.cloudinary.com/demo/image/upload/docs/livingroom3.jpg "thumb: w_500, width:500")

```nodejs
cloudinary.image("docs/livingroom3.jpg")
```

```react
new CloudinaryImage("docs/livingroom3.jpg");
```

```vue
new CloudinaryImage("docs/livingroom3.jpg");
```

```angular
new CloudinaryImage("docs/livingroom3.jpg");
```

```js
new CloudinaryImage("docs/livingroom3.jpg");
```

```python
CloudinaryImage("docs/livingroom3.jpg").image()
```

```php
(new ImageTag('docs/livingroom3.jpg'));
```

```java
cloudinary.url().transformation(new Transformation().imageTag("docs/livingroom3.jpg");
```

```ruby
cl_image_tag("docs/livingroom3.jpg")
```

```csharp
cloudinary.Api.UrlImgUp.BuildImageTag("docs/livingroom3.jpg")
```

```dart
cloudinary.image('docs/livingroom3.jpg').transformation(Transformation());
```

```swift
imageView.cldSetImage(cloudinary.createUrl().generate("docs/livingroom3.jpg")!, cloudinary: cloudinary)
```

```android
MediaManager.get().url().transformation(new Transformation().generate("docs/livingroom3.jpg");
```

```flutter
cloudinary.image('docs/livingroom3.jpg').transformation(Transformation());
```

```kotlin
cloudinary.image {
	publicId("docs/livingroom3.jpg") 
}.generate()
```

```jquery
$.cloudinary.image("docs/livingroom3.jpg")
```

```react_native
new CloudinaryImage("docs/livingroom3.jpg");
``` ![Original video](https://res.cloudinary.com/demo/video/upload/guy_woman_mobile.mp4 "thumb: w_500, width:500")

```nodejs
cloudinary.video("guy_woman_mobile")
```

```react
new CloudinaryVideo("guy_woman_mobile.mp4");
```

```vue
new CloudinaryVideo("guy_woman_mobile.mp4");
```

```angular
new CloudinaryVideo("guy_woman_mobile.mp4");
```

```js
new CloudinaryVideo("guy_woman_mobile.mp4");
```

```python
CloudinaryVideo("guy_woman_mobile").video()
```

```php
(new VideoTag('guy_woman_mobile.mp4'));
```

```java
cloudinary.url().transformation(new Transformation().videoTag("guy_woman_mobile");
```

```ruby
cl_video_tag("guy_woman_mobile")
```

```csharp
cloudinary.Api.UrlVideoUp.BuildVideoTag("guy_woman_mobile")
```

```dart
cloudinary.video('guy_woman_mobile.mp4').transformation(Transformation());
```

```swift
cloudinary.createUrl().setResourceType("video").generate("guy_woman_mobile.mp4")
```

```android
MediaManager.get().url().transformation(new Transformation().resourceType("video").generate("guy_woman_mobile.mp4");
```

```flutter
cloudinary.video('guy_woman_mobile.mp4').transformation(Transformation());
```

```kotlin
cloudinary.video {
	publicId("guy_woman_mobile.mp4") 
}.generate()
```

```jquery
$.cloudinary.video("guy_woman_mobile")
```

```react_native
new CloudinaryVideo("guy_woman_mobile.mp4");
```
* With gravity set to east: ![Image filled to a width and height of 250 pixels with east gravity](https://res.cloudinary.com/demo/image/upload/c_fill,g_east,h_250,w_250/docs/livingroom3.jpg "width:250")

```nodejs
cloudinary.image("docs/livingroom3.jpg", {gravity: "east", height: 250, width: 250, crop: "fill"})
```

```react
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryImage("docs/livingroom3.jpg").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("east"))
);
```

```vue
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryImage("docs/livingroom3.jpg").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("east"))
);
```

```angular
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryImage("docs/livingroom3.jpg").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("east"))
);
```

```js
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryImage("docs/livingroom3.jpg").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("east"))
);
```

```python
CloudinaryImage("docs/livingroom3.jpg").image(gravity="east", height=250, width=250, crop="fill")
```

```php
use Cloudinary\Transformation\Resize;
use Cloudinary\Transformation\Gravity;
use Cloudinary\Transformation\Compass;

(new ImageTag('docs/livingroom3.jpg'))
	->resize(Resize::fill()->width(250)
->height(250)
	->gravity(
	Gravity::compass(
	Compass::east()))
	);
```

```java
cloudinary.url().transformation(new Transformation().gravity("east").height(250).width(250).crop("fill")).imageTag("docs/livingroom3.jpg");
```

```ruby
cl_image_tag("docs/livingroom3.jpg", gravity: "east", height: 250, width: 250, crop: "fill")
```

```csharp
cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("east").Height(250).Width(250).Crop("fill")).BuildImageTag("docs/livingroom3.jpg")
```

```dart
cloudinary.image('docs/livingroom3.jpg').transformation(Transformation()
	.resize(Resize.fill().width(250)
.height(250)
	.gravity(
	Gravity.compass(
	Compass.east()))
	));
```

```swift
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("east").setHeight(250).setWidth(250).setCrop("fill")).generate("docs/livingroom3.jpg")!, cloudinary: cloudinary)
```

```android
MediaManager.get().url().transformation(new Transformation().gravity("east").height(250).width(250).crop("fill")).generate("docs/livingroom3.jpg");
```

```flutter
cloudinary.image('docs/livingroom3.jpg').transformation(Transformation()
	.resize(Resize.fill().width(250)
.height(250)
	.gravity(
	Gravity.compass(
	Compass.east()))
	));
```

```kotlin
cloudinary.image {
	publicId("docs/livingroom3.jpg")
	 resize(Resize.fill() { width(250)
 height(250)
	 gravity(
	Gravity.compass(
	Compass.east()))
	 }) 
}.generate()
```

```jquery
$.cloudinary.image("docs/livingroom3.jpg", {gravity: "east", height: 250, width: 250, crop: "fill"})
```

```react_native
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryImage("docs/livingroom3.jpg").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("east"))
);
``` ![Video filled to a width and height of 250 pixels with east gravity](https://res.cloudinary.com/demo/video/upload/c_fill,g_east,h_250,w_250/guy_woman_mobile.mp4 "width:250")

```nodejs
cloudinary.video("guy_woman_mobile", {gravity: "east", height: 250, width: 250, crop: "fill"})
```

```react
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("guy_woman_mobile.mp4").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("east"))
);
```

```vue
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("guy_woman_mobile.mp4").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("east"))
);
```

```angular
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("guy_woman_mobile.mp4").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("east"))
);
```

```js
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("guy_woman_mobile.mp4").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("east"))
);
```

```python
CloudinaryVideo("guy_woman_mobile").video(gravity="east", height=250, width=250, crop="fill")
```

```php
use Cloudinary\Transformation\Resize;
use Cloudinary\Transformation\Gravity;
use Cloudinary\Transformation\Compass;

(new VideoTag('guy_woman_mobile.mp4'))
	->resize(Resize::fill()->width(250)
->height(250)
	->gravity(
	Gravity::compass(
	Compass::east()))
	);
```

```java
cloudinary.url().transformation(new Transformation().gravity("east").height(250).width(250).crop("fill")).videoTag("guy_woman_mobile");
```

```ruby
cl_video_tag("guy_woman_mobile", gravity: "east", height: 250, width: 250, crop: "fill")
```

```csharp
cloudinary.Api.UrlVideoUp.Transform(new Transformation().Gravity("east").Height(250).Width(250).Crop("fill")).BuildVideoTag("guy_woman_mobile")
```

```dart
cloudinary.video('guy_woman_mobile.mp4').transformation(Transformation()
	.resize(Resize.fill().width(250)
.height(250)
	.gravity(
	Gravity.compass(
	Compass.east()))
	));
```

```swift
cloudinary.createUrl().setResourceType("video").setTransformation(CLDTransformation().setGravity("east").setHeight(250).setWidth(250).setCrop("fill")).generate("guy_woman_mobile.mp4")
```

```android
MediaManager.get().url().transformation(new Transformation().gravity("east").height(250).width(250).crop("fill")).resourceType("video").generate("guy_woman_mobile.mp4");
```

```flutter
cloudinary.video('guy_woman_mobile.mp4').transformation(Transformation()
	.resize(Resize.fill().width(250)
.height(250)
	.gravity(
	Gravity.compass(
	Compass.east()))
	));
```

```kotlin
cloudinary.video {
	publicId("guy_woman_mobile.mp4")
	 resize(Resize.fill() { width(250)
 height(250)
	 gravity(
	Gravity.compass(
	Compass.east()))
	 }) 
}.generate()
```

```jquery
$.cloudinary.video("guy_woman_mobile", {gravity: "east", height: 250, width: 250, crop: "fill"})
```

```react_native
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("guy_woman_mobile.mp4").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("east"))
);
```
* With gravity set to west: ![Image filled to a width and height of 250 pixels with west gravity](https://res.cloudinary.com/demo/image/upload/c_fill,g_west,h_250,w_250/docs/livingroom3.jpg "width:250")

```nodejs
cloudinary.image("docs/livingroom3.jpg", {gravity: "west", height: 250, width: 250, crop: "fill"})
```

```react
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryImage("docs/livingroom3.jpg").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("west"))
);
```

```vue
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryImage("docs/livingroom3.jpg").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("west"))
);
```

```angular
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryImage("docs/livingroom3.jpg").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("west"))
);
```

```js
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryImage("docs/livingroom3.jpg").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("west"))
);
```

```python
CloudinaryImage("docs/livingroom3.jpg").image(gravity="west", height=250, width=250, crop="fill")
```

```php
use Cloudinary\Transformation\Resize;
use Cloudinary\Transformation\Gravity;
use Cloudinary\Transformation\Compass;

(new ImageTag('docs/livingroom3.jpg'))
	->resize(Resize::fill()->width(250)
->height(250)
	->gravity(
	Gravity::compass(
	Compass::west()))
	);
```

```java
cloudinary.url().transformation(new Transformation().gravity("west").height(250).width(250).crop("fill")).imageTag("docs/livingroom3.jpg");
```

```ruby
cl_image_tag("docs/livingroom3.jpg", gravity: "west", height: 250, width: 250, crop: "fill")
```

```csharp
cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("west").Height(250).Width(250).Crop("fill")).BuildImageTag("docs/livingroom3.jpg")
```

```dart
cloudinary.image('docs/livingroom3.jpg').transformation(Transformation()
	.resize(Resize.fill().width(250)
.height(250)
	.gravity(
	Gravity.compass(
	Compass.west()))
	));
```

```swift
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("west").setHeight(250).setWidth(250).setCrop("fill")).generate("docs/livingroom3.jpg")!, cloudinary: cloudinary)
```

```android
MediaManager.get().url().transformation(new Transformation().gravity("west").height(250).width(250).crop("fill")).generate("docs/livingroom3.jpg");
```

```flutter
cloudinary.image('docs/livingroom3.jpg').transformation(Transformation()
	.resize(Resize.fill().width(250)
.height(250)
	.gravity(
	Gravity.compass(
	Compass.west()))
	));
```

```kotlin
cloudinary.image {
	publicId("docs/livingroom3.jpg")
	 resize(Resize.fill() { width(250)
 height(250)
	 gravity(
	Gravity.compass(
	Compass.west()))
	 }) 
}.generate()
```

```jquery
$.cloudinary.image("docs/livingroom3.jpg", {gravity: "west", height: 250, width: 250, crop: "fill"})
```

```react_native
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryImage("docs/livingroom3.jpg").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("west"))
);
``` ![Video filled to a width and height of 250 pixels with west gravity](https://res.cloudinary.com/demo/video/upload/c_fill,g_west,h_250,w_250/guy_woman_mobile.mp4 "width:250")

```nodejs
cloudinary.video("guy_woman_mobile", {gravity: "west", height: 250, width: 250, crop: "fill"})
```

```react
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("guy_woman_mobile.mp4").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("west"))
);
```

```vue
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("guy_woman_mobile.mp4").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("west"))
);
```

```angular
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("guy_woman_mobile.mp4").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("west"))
);
```

```js
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("guy_woman_mobile.mp4").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("west"))
);
```

```python
CloudinaryVideo("guy_woman_mobile").video(gravity="west", height=250, width=250, crop="fill")
```

```php
use Cloudinary\Transformation\Resize;
use Cloudinary\Transformation\Gravity;
use Cloudinary\Transformation\Compass;

(new VideoTag('guy_woman_mobile.mp4'))
	->resize(Resize::fill()->width(250)
->height(250)
	->gravity(
	Gravity::compass(
	Compass::west()))
	);
```

```java
cloudinary.url().transformation(new Transformation().gravity("west").height(250).width(250).crop("fill")).videoTag("guy_woman_mobile");
```

```ruby
cl_video_tag("guy_woman_mobile", gravity: "west", height: 250, width: 250, crop: "fill")
```

```csharp
cloudinary.Api.UrlVideoUp.Transform(new Transformation().Gravity("west").Height(250).Width(250).Crop("fill")).BuildVideoTag("guy_woman_mobile")
```

```dart
cloudinary.video('guy_woman_mobile.mp4').transformation(Transformation()
	.resize(Resize.fill().width(250)
.height(250)
	.gravity(
	Gravity.compass(
	Compass.west()))
	));
```

```swift
cloudinary.createUrl().setResourceType("video").setTransformation(CLDTransformation().setGravity("west").setHeight(250).setWidth(250).setCrop("fill")).generate("guy_woman_mobile.mp4")
```

```android
MediaManager.get().url().transformation(new Transformation().gravity("west").height(250).width(250).crop("fill")).resourceType("video").generate("guy_woman_mobile.mp4");
```

```flutter
cloudinary.video('guy_woman_mobile.mp4').transformation(Transformation()
	.resize(Resize.fill().width(250)
.height(250)
	.gravity(
	Gravity.compass(
	Compass.west()))
	));
```

```kotlin
cloudinary.video {
	publicId("guy_woman_mobile.mp4")
	 resize(Resize.fill() { width(250)
 height(250)
	 gravity(
	Gravity.compass(
	Compass.west()))
	 }) 
}.generate()
```

```jquery
$.cloudinary.video("guy_woman_mobile", {gravity: "west", height: 250, width: 250, crop: "fill"})
```

```react_native
import { fill } from "@cloudinary/url-gen/actions/resize";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("guy_woman_mobile.mp4").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(compass("west"))
);
```
## Automatic gravity for video crops (g_auto)

Apply automatic content-aware gravity by cropping your video with either the [fill](video_crop_modes#fill) or [fill pad](video_crop_modes#fill_pad) crop modes and setting the `gravity` transformation parameter to `auto` (`g_auto` in URLs).

For example, to crop this video to a square aspect ratio whilst keeping the ship as the main focus throughout, using the `fill` crop mode:

![ship.mp4 cropped with a square aspect ratio and automatic gravity](https://res.cloudinary.com/demo/video/upload/ar_1:1,c_fill,g_auto,w_300/ship.mp4)

```nodejs
cloudinary.video("ship", {aspect_ratio: "1:1", gravity: "auto", width: 300, crop: "fill"})
```

```react
import { fill } from "@cloudinary/url-gen/actions/resize";
import { ar1X1 } from "@cloudinary/url-gen/qualifiers/aspectRatio";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("ship.mp4").resize(
  fill()
    .width(300)
    .aspectRatio(ar1X1())
    .gravity(autoGravity())
);
```

```vue
import { fill } from "@cloudinary/url-gen/actions/resize";
import { ar1X1 } from "@cloudinary/url-gen/qualifiers/aspectRatio";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("ship.mp4").resize(
  fill()
    .width(300)
    .aspectRatio(ar1X1())
    .gravity(autoGravity())
);
```

```angular
import { fill } from "@cloudinary/url-gen/actions/resize";
import { ar1X1 } from "@cloudinary/url-gen/qualifiers/aspectRatio";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("ship.mp4").resize(
  fill()
    .width(300)
    .aspectRatio(ar1X1())
    .gravity(autoGravity())
);
```

```js
import { fill } from "@cloudinary/url-gen/actions/resize";
import { ar1X1 } from "@cloudinary/url-gen/qualifiers/aspectRatio";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("ship.mp4").resize(
  fill()
    .width(300)
    .aspectRatio(ar1X1())
    .gravity(autoGravity())
);
```

```python
CloudinaryVideo("ship").video(aspect_ratio="1:1", gravity="auto", width=300, crop="fill")
```

```php
use Cloudinary\Transformation\Resize;
use Cloudinary\Transformation\AspectRatio;
use Cloudinary\Transformation\Gravity;

(new VideoTag('ship.mp4'))
	->resize(Resize::fill()->width(300)
	->aspectRatio(
	AspectRatio::ar1X1())
	->gravity(
	Gravity::autoGravity())
	);
```

```java
cloudinary.url().transformation(new Transformation().aspectRatio("1:1").gravity("auto").width(300).crop("fill")).videoTag("ship");
```

```ruby
cl_video_tag("ship", aspect_ratio: "1:1", gravity: "auto", width: 300, crop: "fill")
```

```csharp
cloudinary.Api.UrlVideoUp.Transform(new Transformation().AspectRatio("1:1").Gravity("auto").Width(300).Crop("fill")).BuildVideoTag("ship")
```

```dart
cloudinary.video('ship.mp4').transformation(Transformation()
	.resize(Resize.fill().width(300)
	.aspectRatio(
	AspectRatio.ar1X1())
	.gravity(
	Gravity.autoGravity())
	));
```

```swift
cloudinary.createUrl().setResourceType("video").setTransformation(CLDTransformation().setAspectRatio("1:1").setGravity("auto").setWidth(300).setCrop("fill")).generate("ship.mp4")
```

```android
MediaManager.get().url().transformation(new Transformation().aspectRatio("1:1").gravity("auto").width(300).crop("fill")).resourceType("video").generate("ship.mp4");
```

```flutter
cloudinary.video('ship.mp4').transformation(Transformation()
	.resize(Resize.fill().width(300)
	.aspectRatio(
	AspectRatio.ar1X1())
	.gravity(
	Gravity.autoGravity())
	));
```

```kotlin
cloudinary.video {
	publicId("ship.mp4")
	 resize(Resize.fill() { width(300)
	 aspectRatio(
	AspectRatio.ar1X1())
	 gravity(
	Gravity.autoGravity())
	 }) 
}.generate()
```

```jquery
$.cloudinary.video("ship", {aspect_ratio: "1:1", gravity: "auto", width: 300, crop: "fill"})
```

```react_native
import { fill } from "@cloudinary/url-gen/actions/resize";
import { ar1X1 } from "@cloudinary/url-gen/qualifiers/aspectRatio";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("ship.mp4").resize(
  fill()
    .width(300)
    .aspectRatio(ar1X1())
    .gravity(autoGravity())
);
```

### How automatic gravity works for videos

Automatic gravity selection is an advanced AI feature that ensures that the most interesting areas are selected as the main focus throughout the duration of each video, allowing you to adjust the size or aspect ratio to fit all of your requirements. When using this feature, each video is analyzed to find the optimal region. As the optimal region of the video may be moving from frame to frame, the cropped area adjusts accordingly while still smoothly transitioning from frame to frame.

You can optionally fine-tune the behavior of the automatic cropping algorithm to instruct it to focus on [faces](#auto_cropping_videos_to_focus_on_faces) or specific [objects](#auto_cropping_videos_to_focus_on_a_specified_object) within a video.

There are several benefits to using AI auto-gravity for videos:

* Saves time and effort by eliminating the need for manual cropping of each frame
* Improves the visual quality of the video by making it appear more focused and professional
* Makes videos more engaging by allowing the viewer to focus on the important parts of the video
* Optimizes a video for different screen sizes, such as smartphones, tablets, and computer screens
* Reduces the file size of the video, making it easier to upload and share

> **TIP**:
>
> :title=Notes and tips

> * The automatic cropping algorithm analyzes the entire video to determine the areas to focus on, which means it can take several seconds or minutes, depending on the length of the original video (an `HTTP 423` error will be returned until the analysis is complete). Therefore, it's recommended to generate the transformation [eagerly](eager_and_incoming_transformations#eager_transformations) during upload or using an [explicit](image_upload_api_reference#explicit_method) method call for existing videos, along with an `eager_notification_url` parameter to notify your application when the content-aware cropping transformation is ready for delivery.

> * Once a video has been analyzed by the automatic cropping algorithm, any subsequent transformations happen on the fly as usual. This includes adjusting the size and aspect ratio.

> * You can only use automatic gravity once per transformation and not within a layer.

> * Automatic cropping isn't currently supported for [incoming transformations](eager_and_incoming_transformations#incoming_transformations).

> * You can add the [getinfo](transformation_reference#fl_getinfo) flag (`fl_getinfo in URLs`) in your transformation to return the proposed `g_auto` cropping results, including confidence scores in JSON, instead of delivering the transformed video. You can then integrate the g_auto results into an external workflow.

> * There are [special transformation counts](transformation_counts#video_ai) for videos using `g_auto`.

> * If you are using our [Asia Pacific data center](admin_api#alternative_data_centers_and_endpoints_premium_feature), you currently can't apply `g_auto` to videos.

### Using fill_pad with automatic gravity

In some cases, you may find that cropping to a different aspect ratio cuts out interesting parts of the content. If this is the case, consider using the [fill pad](video_crop_modes#fill_pad) crop mode with automatic cropping, which uses padding where necessary to keep more of the interesting content in the crop.

For example, using `c_fill_pad` on this rollercoaster video automatically adjusts the aspect ratio and padding to keep the two people in the frame as much as possible (click any video to see all three videos running simultaneously):

  
    
    
    
  
Original video (click to play)

![c_fill_pad video example with automatic cropping](https://res.cloudinary.com/demo/video/upload/ar_1.0,c_fill_pad,g_auto,w_400/docs/Roller_Coaster.mp4 "with_image:false")

```nodejs
cloudinary.video("docs/Roller_Coaster", {aspect_ratio: "1.0", gravity: "auto", width: 400, crop: "fill_pad"})
```

```react
import { fillPad } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("docs/Roller_Coaster.mp4").resize(
  fillPad()
    .width(400)
    .aspectRatio("1.0")
    .gravity(autoGravity())
);
```

```vue
import { fillPad } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("docs/Roller_Coaster.mp4").resize(
  fillPad()
    .width(400)
    .aspectRatio("1.0")
    .gravity(autoGravity())
);
```

```angular
import { fillPad } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("docs/Roller_Coaster.mp4").resize(
  fillPad()
    .width(400)
    .aspectRatio("1.0")
    .gravity(autoGravity())
);
```

```js
import { fillPad } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("docs/Roller_Coaster.mp4").resize(
  fillPad()
    .width(400)
    .aspectRatio("1.0")
    .gravity(autoGravity())
);
```

```python
CloudinaryVideo("docs/Roller_Coaster").video(aspect_ratio="1.0", gravity="auto", width=400, crop="fill_pad")
```

```php
use Cloudinary\Transformation\Resize;
use Cloudinary\Transformation\Gravity;

(new VideoTag('docs/Roller_Coaster.mp4'))
	->resize(Resize::fillPad()->width(400)
->aspectRatio(1.0)
	->gravity(
	Gravity::autoGravity())
	);
```

```java
cloudinary.url().transformation(new Transformation().aspectRatio("1.0").gravity("auto").width(400).crop("fill_pad")).videoTag("docs/Roller_Coaster");
```

```ruby
cl_video_tag("docs/Roller_Coaster", aspect_ratio: "1.0", gravity: "auto", width: 400, crop: "fill_pad")
```

```csharp
cloudinary.Api.UrlVideoUp.Transform(new Transformation().AspectRatio("1.0").Gravity("auto").Width(400).Crop("fill_pad")).BuildVideoTag("docs/Roller_Coaster")
```

```dart
cloudinary.video('docs/Roller_Coaster.mp4').transformation(Transformation()
	.resize(Resize.fillPad().width(400)
.aspectRatio('1.0')
	.gravity(
	Gravity.autoGravity())
	));
```

```swift
cloudinary.createUrl().setResourceType("video").setTransformation(CLDTransformation().setAspectRatio("1.0").setGravity("auto").setWidth(400).setCrop("fill_pad")).generate("docs/Roller_Coaster.mp4")
```

```android
MediaManager.get().url().transformation(new Transformation().aspectRatio("1.0").gravity("auto").width(400).crop("fill_pad")).resourceType("video").generate("docs/Roller_Coaster.mp4");
```

```flutter
cloudinary.video('docs/Roller_Coaster.mp4').transformation(Transformation()
	.resize(Resize.fillPad().width(400)
.aspectRatio('1.0')
	.gravity(
	Gravity.autoGravity())
	));
```

```kotlin
cloudinary.video {
	publicId("docs/Roller_Coaster.mp4")
	 resize(Resize.fillPad() { width(400)
 aspectRatio(1.0F)
	 gravity(
	Gravity.autoGravity())
	 }) 
}.generate()
```

```jquery
$.cloudinary.video("docs/Roller_Coaster", {aspect_ratio: "1.0", gravity: "auto", width: 400, crop: "fill_pad"})
```

```react_native
import { fillPad } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";

new CloudinaryVideo("docs/Roller_Coaster.mp4").resize(
  fillPad()
    .width(400)
    .aspectRatio("1.0")
    .gravity(autoGravity())
);
```

  
    
    
    
  
c_fill

  
    
    
    
  
c_fill_pad


### Auto-cropping videos to focus on faces

By default, the automatic cropping algorithm uses a gaze prediction algorithm to identify the most interesting areas of the video. To adjust the algorithm that's used and detect a single face or multiple faces, specify the focal preference. The available options are:

* `g_auto:face`: Focuses the crop on the largest face detected in the video.
* `g_auto:faces`: Focuses the crop on all the detected faces in the video.

The examples below show the difference between the two face detection options (click any video to see all three videos running simultaneously):

  
    
    
    
  
Original video (click to play)

![Walking talking video cropped to faces](https://res.cloudinary.com/demo/video/upload/ar_3:4,c_fill,g_auto:faces,h_300/docs/walking_talking "with_image:false")

```nodejs
cloudinary.image("docs/walking_talking", {aspect_ratio: "3:4", gravity: "auto:faces", height: 300, crop: "fill", resource_type: "video"})
```

```react
import { fill } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";
import { focusOn } from "@cloudinary/url-gen/qualifiers/autoFocus";
import { faces } from "@cloudinary/url-gen/qualifiers/focusOn";

new CloudinaryImage("docs/walking_talking")
  .resize(
    fill()
      .height(300)
      .aspectRatio("3:4")
      .gravity(autoGravity().autoFocus(focusOn(faces())))
  )
  .setAssetType("video");
```

```vue
import { fill } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";
import { focusOn } from "@cloudinary/url-gen/qualifiers/autoFocus";
import { faces } from "@cloudinary/url-gen/qualifiers/focusOn";

new CloudinaryImage("docs/walking_talking")
  .resize(
    fill()
      .height(300)
      .aspectRatio("3:4")
      .gravity(autoGravity().autoFocus(focusOn(faces())))
  )
  .setAssetType("video");
```

```angular
import { fill } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";
import { focusOn } from "@cloudinary/url-gen/qualifiers/autoFocus";
import { faces } from "@cloudinary/url-gen/qualifiers/focusOn";

new CloudinaryImage("docs/walking_talking")
  .resize(
    fill()
      .height(300)
      .aspectRatio("3:4")
      .gravity(autoGravity().autoFocus(focusOn(faces())))
  )
  .setAssetType("video");
```

```js
import { fill } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";
import { focusOn } from "@cloudinary/url-gen/qualifiers/autoFocus";
import { faces } from "@cloudinary/url-gen/qualifiers/focusOn";

new CloudinaryImage("docs/walking_talking")
  .resize(
    fill()
      .height(300)
      .aspectRatio("3:4")
      .gravity(autoGravity().autoFocus(focusOn(faces())))
  )
  .setAssetType("video");
```

```python
CloudinaryVideo("docs/walking_talking").image(aspect_ratio="3:4", gravity="auto:faces", height=300, crop="fill")
```

```php
use Cloudinary\Transformation\Resize;
use Cloudinary\Transformation\Gravity;
use Cloudinary\Transformation\AutoFocus;
use Cloudinary\Transformation\FocusOn;

(new ImageTag('docs/walking_talking'))
	->resize(Resize::fill()->height(300)
->aspectRatio("3:4")
	->gravity(
	Gravity::autoGravity()
	->autoFocus(
	AutoFocus::focusOn(
	FocusOn::faces()))
	)
	)
	->assetType("video");
```

```java
cloudinary.url().transformation(new Transformation().aspectRatio("3:4").gravity("auto:faces").height(300).crop("fill")).resourceType("video").imageTag("docs/walking_talking");
```

```ruby
cl_image_tag("docs/walking_talking", aspect_ratio: "3:4", gravity: "auto:faces", height: 300, crop: "fill", resource_type: "video")
```

```csharp
cloudinary.Api.UrlVideoUp.Transform(new Transformation().AspectRatio("3:4").Gravity("auto:faces").Height(300).Crop("fill")).BuildImageTag("docs/walking_talking")
```

```dart
cloudinary.image('docs/walking_talking').transformation(Transformation()
	.resize(Resize.fill().height(300)
.aspectRatio("3:4")
	.gravity(
	Gravity.autoGravity()
	.autoFocus(
	AutoFocus.focusOn(
	FocusOn.faces()))
	)
	)
	.setAssetType("video"));
```

```swift
cloudinary.createUrl().setResourceType("video").setTransformation(CLDTransformation().setAspectRatio("3:4").setGravity("auto:faces").setHeight(300).setCrop("fill")).generate("docs/walking_talking")
```

```android
MediaManager.get().url().transformation(new Transformation().aspectRatio("3:4").gravity("auto:faces").height(300).crop("fill")).resourceType("video").generate("docs/walking_talking");
```

```flutter
cloudinary.image('docs/walking_talking').transformation(Transformation()
	.resize(Resize.fill().height(300)
.aspectRatio("3:4")
	.gravity(
	Gravity.autoGravity()
	.autoFocus(
	AutoFocus.focusOn(
	FocusOn.faces()))
	)
	)
	.setAssetType("video"));
```

```kotlin
cloudinary.image {
	publicId("docs/walking_talking")
	 resize(Resize.fill() { height(300)
 aspectRatio("3:4")
	 gravity(
	Gravity.autoGravity() {
	 autoFocus(
	AutoFocus.focusOn(
	FocusOn.faces()))
	 })
	 })
	 assetType("video") 
}.generate()
```

```jquery
$.cloudinary.image("docs/walking_talking", {aspect_ratio: "3:4", gravity: "auto:faces", height: 300, crop: "fill", resource_type: "video"})
```

```react_native
import { fill } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";
import { focusOn } from "@cloudinary/url-gen/qualifiers/autoFocus";
import { faces } from "@cloudinary/url-gen/qualifiers/focusOn";

new CloudinaryImage("docs/walking_talking")
  .resize(
    fill()
      .height(300)
      .aspectRatio("3:4")
      .gravity(autoGravity().autoFocus(focusOn(faces())))
  )
  .setAssetType("video");
```

  
    
    
    
  
g_auto:faces

  
    
    
    
  
g_auto:face


### Auto-cropping videos to focus on a specified object

To adjust the automatic cropping algorithm so that instead of focusing on the most interesting areas of the video it focuses on a specific object, use `g_auto:<object>`.

Compare the following videos, where you can see the original, the first cropped one using `g_auto` and the second cropped one using `g_auto:ball` (click any video to see all three videos running simultaneously):

  
    
    
    
  
Original video (click to play)

![Football video cropped to the ball](https://res.cloudinary.com/demo/video/upload/ar_1,c_fill,g_auto:ball,h_305/docs/football "with_image:false")

```nodejs
cloudinary.image("docs/football", {aspect_ratio: "1", gravity: "auto:ball", height: 305, crop: "fill", resource_type: "video"})
```

```react
import { fill } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";
import { focusOn } from "@cloudinary/url-gen/qualifiers/autoFocus";

new CloudinaryImage("docs/football")
  .resize(
    fill()
      .height(305)
      .aspectRatio("1.0")
      .gravity(autoGravity().autoFocus(focusOn("ball")))
  )
  .setAssetType("video");
```

```vue
import { fill } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";
import { focusOn } from "@cloudinary/url-gen/qualifiers/autoFocus";

new CloudinaryImage("docs/football")
  .resize(
    fill()
      .height(305)
      .aspectRatio("1.0")
      .gravity(autoGravity().autoFocus(focusOn("ball")))
  )
  .setAssetType("video");
```

```angular
import { fill } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";
import { focusOn } from "@cloudinary/url-gen/qualifiers/autoFocus";

new CloudinaryImage("docs/football")
  .resize(
    fill()
      .height(305)
      .aspectRatio("1.0")
      .gravity(autoGravity().autoFocus(focusOn("ball")))
  )
  .setAssetType("video");
```

```js
import { fill } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";
import { focusOn } from "@cloudinary/url-gen/qualifiers/autoFocus";

new CloudinaryImage("docs/football")
  .resize(
    fill()
      .height(305)
      .aspectRatio("1.0")
      .gravity(autoGravity().autoFocus(focusOn("ball")))
  )
  .setAssetType("video");
```

```python
CloudinaryVideo("docs/football").image(aspect_ratio="1", gravity="auto:ball", height=305, crop="fill")
```

```php
use Cloudinary\Transformation\Resize;
use Cloudinary\Transformation\Gravity;
use Cloudinary\Transformation\AutoFocus;

(new ImageTag('docs/football'))
	->resize(Resize::fill()->height(305)
->aspectRatio(1.0)
	->gravity(
	Gravity::autoGravity()
	->autoFocus(
	AutoFocus::focusOn("ball"))
	)
	)
	->assetType("video");
```

```java
cloudinary.url().transformation(new Transformation().aspectRatio("1").gravity("auto:ball").height(305).crop("fill")).resourceType("video").imageTag("docs/football");
```

```ruby
cl_image_tag("docs/football", aspect_ratio: "1", gravity: "auto:ball", height: 305, crop: "fill", resource_type: "video")
```

```csharp
cloudinary.Api.UrlVideoUp.Transform(new Transformation().AspectRatio("1").Gravity("auto:ball").Height(305).Crop("fill")).BuildImageTag("docs/football")
```

```dart
cloudinary.image('docs/football').transformation(Transformation()
	.resize(Resize.fill().height(305)
.aspectRatio('1.0')
	.gravity(
	Gravity.autoGravity()
	.autoFocus(
	AutoFocus.focusOn("ball"))
	)
	)
	.setAssetType("video"));
```

```swift
cloudinary.createUrl().setResourceType("video").setTransformation(CLDTransformation().setAspectRatio("1").setGravity("auto:ball").setHeight(305).setCrop("fill")).generate("docs/football")
```

```android
MediaManager.get().url().transformation(new Transformation().aspectRatio("1").gravity("auto:ball").height(305).crop("fill")).resourceType("video").generate("docs/football");
```

```flutter
cloudinary.image('docs/football').transformation(Transformation()
	.resize(Resize.fill().height(305)
.aspectRatio('1.0')
	.gravity(
	Gravity.autoGravity()
	.autoFocus(
	AutoFocus.focusOn("ball"))
	)
	)
	.setAssetType("video"));
```

```kotlin
cloudinary.image {
	publicId("docs/football")
	 resize(Resize.fill() { height(305)
 aspectRatio(1.0F)
	 gravity(
	Gravity.autoGravity() {
	 autoFocus(
	AutoFocus.focusOn("ball"))
	 })
	 })
	 assetType("video") 
}.generate()
```

```jquery
$.cloudinary.image("docs/football", {aspect_ratio: "1", gravity: "auto:ball", height: 305, crop: "fill", resource_type: "video"})
```

```react_native
import { fill } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";
import { focusOn } from "@cloudinary/url-gen/qualifiers/autoFocus";

new CloudinaryImage("docs/football")
  .resize(
    fill()
      .height(305)
      .aspectRatio("1.0")
      .gravity(autoGravity().autoFocus(focusOn("ball")))
  )
  .setAssetType("video");
```

  
    
    
    
  
g_auto

  
    
    
    
  
g_auto:ball

If the specified object isn't found in the video, the algorithm falls back to the default automatic cropping algorithm.

#### Supported objects for video g_auto:\<object\>

The set of supported objects that you can use with `g_auto:<object>` are from the [Large Vocabulary Instance Segmentation](https://www.lvisdataset.org/) (lvis) model, which contains thousands of general objects. Start typing the name of an object or category in the search box below to find an object to use:

> **NOTES**:
>
> * If there are many instances of the same object in a frame, the algorithm prioritizes the most prominent specified object.

> * You can add an 's' to any of the objects to prioritize all of the objects. For example, `g_auto:birds` tries to keep all birds in the frame, whereas `g_auto:bird` focuses on the most prominent bird.

> * Currently, `g_auto:<object>` isn't available to accounts that use [alternative data centers](admin_api#alternative_data_centers_and_endpoints_premium_feature).

### Comparison with default gravity

Below is a comparison between the original video of a dog catching a frisbee, and the same video with the aspect ratio inverted. The left video was cropped using default center gravity and the other using automatic gravity focusing on the dog. Watch how the auto cropped (right-hand) video keeps the main subject (the dog) in view at all times, even as it moves across the frame in the original video.

Click any video below to see the comparison in action or use our [automatic cropping demo](https://demo.cloudinary.com/video-compare/) to try it on a variety of samples or on your own videos.

  
    
    
    
  
Original video (click to play)

  
    
    
    
  
Default crop(Center gravity)

  
    
    
    
  
g_auto:dog


#### Sample app: Changing source based on orientation

You could also use automatic cropping to show the correct video depending on the device orientation. If the user lands on the page whilst browsing in portrait orientation, you could set the HTML5 video source to a vertical video that Cloudinary automatically crops. If the user switches to landscape, then the source reverts back to the original landscape video. The sample app below shows a very simple example of how you could do this. Use the "Change Orientation" button to simulate rotating a device, or try it out on mobile. Notice that this time, the portrait orientation uses `g_auto`, rather than `g_auto:dog`.

Watch the sample app switch between portrait and landscape video sources:

Explore the app on [GitHub](https://github.com/cloudinary-devs/video-orientation-switch-cropping-demo).
> **TIP**: Enjoy interactive learning? Check out more [sample apps](code_explorers)!

> **READING**:
>
> * [Video crop modes](video_crop_modes): Detailed examples of `fill`, `fill_pad`, and `crop` modes, plus cropping videos with non-standard DAR.

> * [Video resize modes](video_resize_modes): Detailed examples of `scale`, `fit`, `limit`, `pad`, and `lpad`, including pad with blurred background.

> * [Device pixel ratio (DPR)](video_resize_modes#set_device_pixel_ratio_dpr): Deliver video at the right resolution for different devices.