Scaling videos and images using the fit property

Understanding how to fit images and videos within different frames and layouts is crucial when editing or displaying them on digital platforms. Different fit types help avoid unintended effects like stretching, pixelation, and unwanted cropping.

This guide will explain the fit property and the different types of fit for images and videos. You will also learn how to apply different fit types using the Shotstack Edit API.

About Shotstack and the Edit API

Shotstack is a cloud-based video automation platform. With Shotstack's API, you can quickly and easily edit and render dynamic videos at scale. In this article, we'll use the Edit API to apply various fit types to an example video. This article presumes you have some basic knowledge of using the Edit API and already have an account set up and an API key.

What are fit types?

Fit types determine how an image or video scales and aligns within the bounds of a frame or specified dimensions. Selecting the right fit type can help make your media assets more visually appealing. And this can in turn improve user experience.

Fit types are a common concept and can be seen in CSS with the object-fit property and the Node.js Sharp image library, among many others.

The right fit can make or break the visual impact of your content. It pays to understand each one and know when it's fitting to use them.

Shotstack fit types for videos and images

The Shotstack Edit API has its own implementation of fit types that apply to both images and videos. This guide highlights the four main types, each with an example to give you an idea of how it works. To help you appreciate the differences, we'll apply it to the same video and observe the effect.

Original video without fit applied

The following video is what we will use for the examples:

This is the source footage before it is edited using the Shotstack video editing API. It's original dimensions are 1080px wide by 720px high.

Crop

The crop fit type enlarges your asset to fill the target space while keeping its original aspect ratio. If your asset's dimensions do not match the target area, it will display only the part of the asset that fits within the area. It will not show any excess outside of the target area.

This fit type can help you adhere to keeping a standard size for your assets. The JSON below shows an example of applying the crop fit to an image. If you are not familiar with submitting video edits to Shotstack, you can follow this Hello World guide and just replace the JSON.

{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "video",
                            "src": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/night-sky.mp4"
                        },
                        "start": 0,
                        "length": 10,
                        "fit": "crop"
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "mp4",
        "size": {
            "width": 720,
            "height": 720
        }
    }
}

The JSON above renders a square video (720px x 720px) so that you can see the effect more clearly. Here is how the edited video looks:

As you can see from the image above, the "crop" fit type only shows what can fit into the square (720 x 720 pixels in this case). Any part of the video that doesn't fit within the square is cropped. Crop is also the default fit type.

Cover

The cover fit type stretches your video or image to fill the target area. It doesn't matter the dimension of the target area, this fit type will ensure that your asset takes up all the available space. This means it may end up changing the asset's original aspect ratio and even distort and stretch it to make sure it fills the whole space.

Below is an example of a JSON edit that applies a cover fit to a video.

{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "video",
                            "src": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/night-sky.mp4"
                        },
                        "start": 0,
                        "length": 10,
                        "fit": "cover"
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "mp4",
        "size": {
            "width": 720,
            "height": 720
        }
    }
}

Here is the result:

In the case of cover, it shows the whole video. If you look closely, the video is squashed slightly to make it fit into the square space of 720 pixels by 720 pixels. The reason is because the original video is rectangular. Without squashing the image, it cannot fit within the available square space.

Contain

The contain fit type ensures your asset fits within the space without cropping parts of it. It maintains the aspect ratio but might adjust the size.

Unlike cover, the contain fit type may leave empty spaces around the asset and not fill up the entire target area. It's these empty spaces that preserve the asset from distortion. This effect is known as letterboxing, when the space is at the top and bottom, and pillarboxing when at the side.

It is common to see this approach taken when fitting vertical video filmed on a mobile phone used in a widescreen video.

Below is an example of a JSON that applies the contain fit type to an image.

{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "video",
                            "src": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/night-sky.mp4"
                        },
                        "start": 0,
                        "length": 10,
                        "fit": "contain"
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "mp4",
        "size": {
            "width": 720,
            "height": 720
        }
    }
}

The rendered video:

The contain fit example above maintains the same aspect ratio as the original video. But it's scaled down to fit within the square. And because of that, it creates a letterbox effect with empty space (top and bottom) around the asset.

None

As the name suggests, the none fit type preserves your image or video's original dimensions. It's ideal for situations where you don't want to distort the assets in any way. For example, when using logos or icons.

The JSON example below shows you an example of applying a none fit to a video.

{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "video",
                            "src": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/night-sky.mp4"
                        },
                        "start": 0,
                        "length": 10,
                        "fit": "none"
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "mp4",
        "size": {
            "width": 720,
            "height": 720
        }
    }
}

The final output video:

This video appears similar to using the crop fit type, but if you were to inspect the video more closely you would see that the pixel dimensions are exactly the same as the original video and no resizing has been applied.

Working with logos and icons in videos

To include logos and icons in your edit, it's best to resize them to the exact size you want them to appear in your videos. And then set the fit to none. This gives you much sharper images as PNGs can look pixelated or blurry when scaled in videos. You can resize images to the exact size before using them or you can use our Ingest API to resize your images to a specific size.

Conclusion

In this guide, we have provided an overview of the effects the various fit types have on videos and images. You now know the differences between crop, cover, contain, and none. And this will help you know which one will be more appropriate in different scenarios.