Smartphones brought about the era of filming videos in a vertical orientation, where the video is taller than it is wide. This works fine when viewed on another smartphone. But the TV in most peoples homes, laptops and desktop PC's are still in widescreen format.
When you need to display a vertical video on a widescreen display, you either need to zoom in on the footage and crop the top and bottom, or contain the footage so everything fits. But this results in empty areas down the left and right sides, an undesirable effect known as pillarboxing.
A very common approach to make the footage look more interesting is to fill the empty space with a blurred and scaled copy of the vertical video. This is sometimes called an "echo" or echo pillarboxing.
You might have seen this approach used on the news or sporting videos where users have recorded user generated content on their phones but needs to be broadcast or streamed in 16:9 widescreen.
In this guide, you will learn how to use the Shotstack Edit API to re-create the echo pillarbox effect and how you might automate it if you are handling hundreds or thousands of user generated vertical videos.
About Shotstack and the Edit API
Shotstack is a cloud-based video editing platform that provides developers with a set of APIs to automate video editing tasks. You can easily integrate Shotstack into your applications or media automation workflows and generate dynamic videos at scale.
One of the APIs is the Edit API which we will use in this guide to create a blurred version of the video to fill the sides and position the vertical video on top.
Requirements
To follow along with this guide, you will need the following:
- A Shotstack API Key. Get one when you sign up for a free account.
- Basic understanding of using the command line to run curl requests.
How to blur the sides of a vertical video using an API
The following is the vertical video we will use for the example in this guide:
https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/abstract-liquids.mp4In a real world use case the vertical video would likely by UGC footage shot by an amateur spectator or witness to an event. For this example we are just using an abstract video to demonstrate the effect.
Create the JSON blurred background video template
Create a new blur.json file. Copy and save the JSON below to the file you created.
{
"timeline": {
"background": "#ffffff",
"tracks": [
{
"clips": [
{
"asset": {
"type": "video",
"src": "{{ VERTICAL_VIDEO }}"
},
"start": 0,
"length": "auto",
"fit": "contain"
}
]
},
{
"clips": [
{
"asset": {
"type": "video",
"src": "{{ VERTICAL_VIDEO }}"
},
"start": 0,
"length": "auto",
"filter": "blur",
"scale": 1.78,
"opacity": 0.75
}
]
}
]
},
"output": {
"format": "mp4",
"size": {
"width": 1280,
"height": 720
}
},
"merge": [
{
"find": "VERTICAL_VIDEO",
"replace": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/abstract-liquids.mp4"
}
]
}The JSON includes a VERTICAL_VIDEO placeholder with the URL of our vertical video stored in S3. There are two clips which will both use this URL.
The first clip sets the fit property to contain. This will force the entire video to fit to the bounds of the output video which has a wide 16:9 aspect ratio and dimensions of 1280px x 720px.
The second clip sets the filter property to blur and the scale property to 1.78. This will scale the video to fill the background and apply a blur effect to it.
The scale value is calculated by dividing the width of the output video by the width of the vertical video. In this case, the output video width is 1280px and the vertical video width is 720px. So the scale value is 1280 / 720 = 1.78.
Call the Edit API with the blur.json payload
Navigate to the directory with the blur.json file. Make a POST request to the Edit API by running the command below.
Make sure to replace SHOTSTACK_API_KEY with your own sandbox API key.
curl -X POST \
-H "Content-Type: application/json" \
-H "x-api-key: SHOTSTACK_API_KEY" \
-d @blur.json \
https://api.shotstack.io/edit/stage/renderIf the request is successful, you will get a response like the following.
{
"success": true,
"message": "Created",
"response": {
"message": "Render Successfully Queued",
"id": "7dce86f4-c504-4286-b990-500300c0e006"
}
}Copy the value of response.id. We'll use it in the next step to check the render status of the video.
Check the status of the video render
Run the command below to get the render status of the video. Be sure to replace SHOTSTACK_API_KEY and RESPONSE_ID with your API key and the response.id you copied from the previous step.
curl -X GET \
-H "Content-Type: application/json" \
-H "x-api-key: SHOTSTACK_API_KEY" \
https://api.shotstack.io/stage/render/RESPONSE_ID?data=falseYou should see a response like the one below. It's going to include a response.status value. If the value is equal to done, then the render is complete. Otherwise, wait for a few seconds and make the same GET request again.
{
"success": true,
"message": "OK",
"response": {
"id": "7dce86f4-c504-4286-b990-500300c0e006",
"owner": "irwdtighyk",
"plan": "sandbox",
"status": "done",
"error": "",
"duration": 8.48,
"billable": 8.48,
"renderTime": 12339.96,
"url": "https://shotstack-api-stage-output.s3-ap-southeast-2.amazonaws.com/irwdtighyk/7dce86f4-c504-4286-b990-500300c0e006.mp4",
"poster": null,
"thumbnail": null,
"created": "2024-05-12T12:46:33.800Z",
"updated": "2024-05-12T12:46:59.545Z"
}
}When the render is done, the response will also include a response.url value with our final video:
As you can see the background is scaled and blurred to fill the sides of the video. The vertical video is contained in the center.
We have achieved the echo pillarbox effect!
You can now build on this simple template and add text, overlays, intro and outros to create a re-usable UGC pillarbox template for your news or sports broadcasts and streams, YouTube channels and workflows.
Become an Automated Video Editing Pro
Every month we share articles like this one to keep you up to speed with automated video editing.
