Overlays in video
A comprehensive guide that covers how you can add images, text, subtitles, and videos over a base video.
Overlay
In ImageKit, you can add images, text, subtitles, and videos over a base video using layers. Skip to the relevant section to understand with a quick example:
Layers
A layer is a special kind of transformation that allows you to modify the overlay itself and express its position in relation to the parent.
Syntax of layers
A layer starts with l-<type>
and ends with l-end
. All the positional and transformation parameters of that layer are between l-<type>
and l-end
and only apply to that layer and not the parent base asset.
type
can be image
, text
, video
or subtitles
.
For example, in the following URL, we are adding a logo image logo.png
on top of a base video, i.e. sample-video.mp4
. However, we applied width (w-10
) and rotation (rt-90
) transformations on this overlay logo image before placing it on the base video. Transformations w-300,h-300
are applied to sample-video.mp4
.
Here the parent base video has one layer inside it. A layer can also nest another layer.
Input of layer
The input of the layer can be specified using i
or ie
(base64 encoded) parameter. In case both i
and ie
is present, i
is ignored. The base64 string should be made URL safe to ensure that all padding characters(=) are included correctly. In Javascript, a function like encodeURIComponent()
can be used for this.
Position of layer
The position of the layer can be controlled using the following parameters. The position of the layer is always relative to the immediate parent. For instance, the parent is the base video in the above example, and the logo image is the nested layer.
The position of subtitles cannot be controlled at this point.
Parameter | Description |
---|---|
lx |
|
ly |
|
lfo | Position of the layer in relative terms e.g. |
lso | Start time of the base video in seconds when the layer should appear. It accepts a positive number upto two decimal e.g. 20 or 20.50 |
ldu | Duration in seconds during which layer should appear on the base video. It accepts a positive number upto two decimal e.g. 20 or 20.50 |
leo | End time of the base video when this layer should disappear. In case both |
Transformation of layer
You can apply transformations to the layer as you would otherwise. However, any transformation parameter inside the layer is only applicable to that layer and not the parent.
However, different types of layers support different types of transformations which are covered in respective sections.
Transformations inside a layer can be chained together to achieve the desired outcome.
Nesting of layers
A layer can have a nested layer up to 3 levels.
For example, in the below URL, i-inner.png
is rendered on the top-left corner of i-outer.png
using the lfo-top_left
parameter.
Add images over video
You can add an image over a base video using image layer (l-image
).
Usage
You can also control the position of image overlay using these positional parameters.
Input (i
or ie
) for l-image
can be JPG, PNG, WEBP, TIFF or GIF files.
When GIF file is used in image layer, the 1st frame of the GIF is used as a static image. For animated GIF you can use video layer (l-video
).
Animated-WebP and animated-PNG (apng
) are not supported in Imagekit's video API.
Transformation of image overlay
ImageKit supports many image transformation parameters, however inside a layer, you can apply the following transformations to the image overlay before it is placed on the base video. You can chain the transformations one after other to achieve the desired outcome.
Parameter | Description |
---|---|
Width of overlay image. It can also accept arithmetic expressions such as | |
Height of overlay image. It can also accept arithmetic expressions such as | |
Aspect ratio of overlay image. It can also accept arithmetic expressions such as | |
Cropping method. Accepts | |
Crop mode. Supports | |
Relative focus area used during cropping. Accpets | |
This adds a border to the overlay image. It accepts two parameters - the width of the border and the color of the border in format | |
It is used to specify the background color in RGB Hex Code (e.g. FF0000) or an RGBA Code (e.g. FFAABB50) that must be used for the image. If you specify an 8 character background, the last two characters must be a number between 00 and 99 , which is used to indicate the opacity level of the background. | |
It is used to control the radius of the corner. To get a circle or oval shape, set the value to | |
It is used to specify the degree by which the overlay image must be rotated. |
Add text over video
You can add any text string over a base video using the following example.
Usage syntax
You can also control the position of text overlay using these positional parameters.
Transformation of text overlay
Following transformation parameters are supported on the text inside a layer.
Parameter | Description |
---|---|
w | Width of the whole text layer. It can also accept arithmetic expressions such as |
fs | Font size. It can also accept arithmetic expressions such as |
ff | Font family |
co | Color |
ia | Inner alignment. Accepts |
pa | Padding. It can also accept arithmetic expressions such as |
al | Alpha |
tg | Typography |
It is used to specify the background color in RGB Hex Code (e.g. FF0000) or an RGBA Code (e.g. FFAABB50) that must be used for the video. If you specify an 8 character background, the last two characters must be a number between 00 and 99 , which is used to indicate the opacity level of the background. | |
It is used to control the radius of the corner. To get a circle or oval shape, set the value to |
Add video over video
You can add video or GIF over a base video using video layer (l-video
).
Usage
You can also control the position of video overlay using these positional parameters.
All supported video formats & GIF can be used a input (i
or ie
) for video layer.
Animated-WebP and animated-PNG (apng
) are not supported in Imagekit's video API.
Transformation of video overlay
You can transform the layer video using any supported video transformation parameter in ImageKit except sr
.
Add solid color blocks over video
You can add solid color blocks over a base video using the following example.
Usage syntax
You can also control the position of solid color blocks using these positional parameters.
Transformation of solid color blocks overlay
Following transformation parameters are supported on the solid color block overlay inside a layer.
Parameter | Description |
---|---|
w | Width of solid color block. It can also accept arithmetic expressions such as |
h | Height of solid color block. It can also accept arithmetic expressions such as |
It is used to specify the color of the block in RGB Hex Code (e.g. | |
al | It is used to specify the transparency level of the overlaid solid color layer. Supports integers from |
It is used to control the radius of the corner. To get a circle or oval shape, set the value to |
If both bg
and al
are set in a single transformation and bg
has an alpha component, then that value is used to set solid color background transparency. Otherwise, al
value is used. If bg
is set to a standard color name (e.g. blue
), then the al
value is ignored. Read more here
Add subtitles over a video
You can add subtitles over a base video using the following example.
Usage syntax
The position of subtitles cannot be controlled.
Transformation of subtitles overlay
Transformation of subtitles are not supported.
Last updated