Video gravity for crops

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) 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 a 250-pixel square with the video while retaining the aspect ratio:

• Original video:
• With gravity set to east:
• With gravity set to west:

Automatic gravity for video crops (g_auto)

Apply automatic content-aware gravity by cropping your video with either the fill or 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:

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 or specific objects 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

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

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

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

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 (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:

---

---

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 to try it on a variety of samples or on your own videos.

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.