Getting started
Overview
Quickstart guides
Production checklist
Integration & migration
Connect external storage
Migrate to ImageKit
Image & video API
Transform and adapt
Image transformations
Video transformations
Resize and crop
Add overlays on videos
Common transformations
Audio transformations
Create video thumbnails
Trim videos
Adaptive bitrate streaming
Video webhook events
Arithmetic expressions
Optimize for web delivery
Core delivery features
DAM user guide
DAM overview
Sharing and collaboration
Embeddable ML widget
API overview
Introduction
API keys
Webhooks
API Reference
Account
Account management
Usage analytics
Sub-accounts

Add overlays on videos

A comprehensive guide that covers how you can add images, videos, text and subtitles as overlays on videos using ImageKit.

With ImageKit, you can add images, videos, text and subtitles over a video using layers. Skip to the relevant section to understand with a quick example:

Add images over video

You can add an image over a base video using the image layer (l-image).

Syntax for adding images over video

Copy
         URL endpoint         Base video                   Image layer
┌──────────────────────────┐┌────────────┐      ┌──────────────────────────────┐
https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,l-end

Input (i or ie) for l-image can be JPG, PNG, WEBP, TIFF, or GIF files.

For example, let's add ImageKit's logo over a base video.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-logo.png,l-end

Add images over video

Notes

  1. To overlay videos stored within a specific folder of your media library, use the complete video path where slashes (/) are replaced with @@. For example, if the overlay image is at
    https://ik.imagekit.io/demo/path/to/overlay.jpg, then it can be used as an overlay like:
    https://ik.imagekit.io/demo/base-video.mp4?tr=l-image,i-path@@to@@overlay.jpg,l-end
  2. When a GIF file is used in the image layer, the 1st frame of the GIF is used as a static image. For animated GIF, you can use video layer (l-video).

When a GIF file is used in the 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.

Control time & position of image overlay

You can control the image layer position using the lx and ly parameters. Learn more about positional parameters in layers.

For example, let's align the logo to the left of the video using lfo-left.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lfo-left,i-logo.png,l-end

Left align image layer

You can also use lso, leo, and ldu to control the time at which the overlay should start, end, and the duration of the overlay.

Let's add the logo at 3 seconds and remove it at 8 seconds using lso-3,leo-8.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-3,leo-8,i-logo.png,l-end

Add image layer at 3 seconds and remove at 8 seconds

Apply transformations on image overlay

Inside an image layer on the base video, you can apply these supported 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.

Let's resize the logo image to 100px width by adding w-100 inside the image layer.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-logo.png,w-100,l-end

Resize image layer

List of transformations supported on image overlay

ParameterDescription
wWidth of overlay image. It can also accept arithmetic expressions such as bw_div_2, or bw_sub_cw. Learn more about arithmetic expressions here.
hHeight of overlay image. It can also accept arithmetic expressions such as bh_div_2, or bh_sub_cw. Learn more about arithmetic expressions here.
arAspect ratio of overlay image. It can also accept arithmetic expressions such as iar_div_2, or bar. Learn more about arithmetic expressions here.
cCropping method. Accepts force, at_max, and at_least.
cmCrop mode. Supports extract and pad_resize.
foRelative focus area used during cropping. Accpets center, top, left, bottom, right, top_left, top_right, bottom_left and bottom_right.
bThis adds a border to the overlay image. It accepts two parameters - the width of the border and the color of the border in format b-<border-width>-<hex code>. It can also accept arithmetic expressions such as ih_div_20_red, or cw_mul_0.05_FF0000. Learn more about arithmetic expressions here.
bgIt 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. 00 represents an opacity level of 0.00, 01 represents opacity level 0.01, and so on.
rIt is used to control the radius of the corner. To get a circle or oval shape, set the value to max.
rtIt 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 l-text.

Syntax for adding text over video

Copy
         URL endpoint          Base video            Text layer
┌──────────────────────────┐┌──────────────┐    ┌──────────────────┐
https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,i-hello,l-end

For using special characters in the text, refer to example here.

Notes

  1. Plain text input longer than 2000 characters will be truncated.
  2. 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.
  3. Base64 encoded text input longer than 2500 characters will be truncated.

Let's add "Hello" text over a base video. We will also use fs-100,co-red to set the font size to 100 and color to red.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,i-hello,fs-100,co-red,l-end

Add text over video

Control time & position of text overlay

You can control text layer position using the lx and ly parameters. To change the direction, negative values are also supported by prefixing the value with 'N'.

Learn more about positional parameters in layers.

Let's align the text to the left of the video using lfo-left.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lfo-left,i-hello,fs-100,co-red,l-end

Left align text

We can use lso, leo, and ldu to control the time at which the overlay should start, end, and the duration of the overlay.

Let's add the text at 3 seconds and remove it at 8 seconds using lso-3,leo-8.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lso-3,leo-8,i-hello,fs-100,co-red,l-end

Add text at 3 seconds and remove at 8 seconds

Apply transformations on text overlay

You can control the width, font size, font family, color, inner alignment, padding, transparency level, typography, background color, and corner radius of the text overlay using these supported transformations parameters.

For example, let's add a white background with padding and a bigger font size.

You can add padding to the text overlay using the pa parameter. The padding can be controlled individually for each side using the CSS shorthand notation. Refer to text in image overlay for more examples.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,i-hello,fs-100,co-red,bg-FFFFFF,pa-20,l-end

Add text with background and padding

List of supported text transformations in text layers

ParameterDescription
wWidth of the whole text layer. It can also accept arithmetic expressions such as bw_div_2, or bw_mul_0.8. Learn more about arithmetic expressions here.
fsFont size. It can also accept arithmetic expressions such as bh_div_20, or bh_mul_0.05. Learn more about arithmetic expressions here.
ffIt is used to specify the font of the overlaid text on the image. You can choose any font from this list or use a custom font.
coIt is used to specify the color and transparency of the overlaid text on the image. It accepts RGB Hex Codes (e.g. FF0000), or RGBA Codes (e.g. FFAABB50), or color names (e.g. red). If you specify an 8-character background, the last two characters must be a number between 00 and 99, which indicate the opacity level of the background. 00 represents an opacity level of 0.00, 01 represents an opacity level of 0.01, and so on.
iaInner alignment. Accepts left, right and center. The default value is center.
paPadding. It can also accept arithmetic expressions such as bw_mul_0.05, or bw_mod_5. Learn more about arithmetic expressions here.
alAlpha
tgTypography. Supports bold b, italics i, and bold with italics b_i.
bgIt 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. 00 represents an opacity level of 0.00, 01 represents opacity level 0.01, and so on.
rIt is used to control the radius of the corner. To get a circle or oval shape, set the value to max.

Add video over video

You can add a video or a GIF over a base video using the video layer l-video.

Syntax for adding video over video

Copy
         URL endpoint         Base video                   Video layer
┌──────────────────────────┐┌────────────┐      ┌──────────────────────────────┐
https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,l-end

For example, let's overlay the video over itself. We are also resizing the video to 400px width so that the overlay effect is visible.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,l-end

Add video over video

Notes

  1. 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.
  2. For a nested path, replace / with @@.

Control time & position of video overlay

You can control video layer position using the lx and ly parameters. Learn more about positional parameters in layers.

For example, let's align the video to the left of the video using lfo-left.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,lfo-left,l-end

Left align video layer

You can also use lso, leo, and ldu to control at what time the overlay should start, end, and the duration of the overlay.

Let's add the video at 3 seconds and remove it at 8 seconds using lso-3,leo-8.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,lso-3,leo-8,i-sample-video.mp4,w-400,l-end

Add video at 3 seconds and remove at 8 seconds

Apply transformations on video overlay

You can transform the layered video using any supported video transformation parameter in ImageKit except sr.

Let's resize the video to 400px width by adding w-400 inside the video layer.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,l-end

Resize video layer

Add solid color blocks over video

You can add solid color blocks over a base video using the following example.

Syntax for adding solid color blocks over video

Copy
https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,l-end

Let's add a solid red color block over a base video.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,l-end

Add solid color block over video

Control time & position of solid color block overlay

You can control the position of the solid color block overlay using the lx and ly parameters. Learn more about positional parameters in layers.

For example, let's align the solid color block to the left of the video using lfo-left.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,lfo-left,w-500,l-end

Left align solid block

You can also use lso, leo, and ldu to control at what time the overlay should start, end, and the duration of the overlay.

Let's add the solid color block at 3 seconds and remove it at 8 seconds using lso-3,leo-8.

https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-3,leo-8,i-ik_canvas,bg-red,lfo-left,w-500,l-end

Add solid block at 3 seconds and remove at 8 seconds

Apply transformations on solid color block overlay

The following transformation parameters are supported on the solid color block overlay inside a layer.

ParameterDescription
wWidth of solid color block. It can also accept arithmetic expressions such as bw_div_2, or bw_mul_0.8. Learn more about arithmetic expressions here.
hHeight of solid color block. It can also accept arithmetic expressions such as bh_div_2, or bh_mul_0.8. Learn more about arithmetic expressions here.
bgIt is used to specify the color of the block in RGB Hex Code (e.g. FF0000), or an RGBA Code (e.g. FFAABB50), or a color name (e.g. red). If you specify an 8-character background, the last two characters must be a number between 00 and 99, which indicates the opacity level of the background. 00 represents an opacity level of 0.00, 01 represents an opacity level of 0.01, and so on.
alIt is used to specify the transparency level of the overlaid solid color layer. Supports integers from 1 to 9.
rIt is used to control the radius of the corner. To get a circle or oval shape, set the value to max.

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.

Add subtitles over a video

You can add subtitles over a base video using the following example.

Syntax for adding subtitles over video

Copy
https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,l-end

The position of subtitles cannot be controlled. We will soon add support for lfo parameter to control the relative position of subtitles.

Transformation of subtitles overlay

Transformation of subtitles is not supported. We will soon add support for the basic styling of subtitles.

Got any questions? Contact us - support@imagekit.io