Placing layers on videos

Cloudinary allows you to dynamically add layers to specific locations within your videos, where the new layers are added over the base video as overlays, and can also be easily transformed to suit your needs. There are multiple options for adding a new layer to a base video, either an asset uploaded to Cloudinary, a remote asset, or a text string.

Video layers can also be added as underlays instead, and there are special layer applications for using layers in combination with other Cloudinary transformations.

Here are examples of some popular use cases that you can accomplish using layers (combined with other transformations):

This page covers the layer syntax and the overlay types you can apply. To learn how to position layers, see Layer placement. For text options, see Text layer options. For transformations and relative sizing, see Transforming layers. For underlays, watermarking, and special effects, see Underlays, watermarking, and special effects.

Layer transormation syntax

In its most simple form, adding a layer over the base video takes following URL syntax:

The layer parameter is in its own URL component and starts the overlay definition (similar to an open bracket). The layer_apply flag is in a separate component that closes the definition (similar to a closing bracket) and instructs Cloudinary to place it.

You can enhance your layer both by controlling where and how it's placed on the base video using gravity, offset and other placement qualifiers, and by applying transformations to the layered asset, using the following general URL syntax.

Authenticated or private layers

You can add asset overlays that are set to authenticated or private by modifying the syntax:

Image overlays:

• For private image layers: l_private:<public_id of layer>
• For authenticated image layers: l_authenticated:<public_id of layer>

Video overlays:

• For private video layers: l_video:private:<public_id of layer>
• For authenticated video layers: l_video:authenticated:<public_id of layer>

Audio overlays:

• For private audio layers: l_audio:private:<public_id of layer>
• For authenticated audio layers: l_audio:authenticated:<public_id of layer>

Image overlays

The default overlay type is an image. For example, adding an overlay of a logo to a base video (l_docs:logo-semi-opaque/fl_layer_apply):

See full syntax: l_<image id> in the Transformation Reference.

Try it out: Layers.

See also: Fade overlays in and out.

Remote image overlays

Use a remote image (an image not stored in your Cloudinary product environment) as an overlay by adding the fetch (or url for some SDKs) property of the layer parameter ( l_fetch: in URLs) and the base64 encoded URL of the remote image.

The general URL syntax for adding a remote image as an overlay takes the following form:

For example, adding an overlay of the remote image https://res.cloudinary.com/demo/image/upload/logos/cloudinary_icon_white.png to the base video.

See full syntax: l_fetch in the Transformation Reference.

Video overlays

Add another video as an overlay over the base video by using the overlay video parameter (l_video: in URLs) and the public ID of a previously uploaded video (e.g. l_video:dog for a video with the public ID of dog).

You can enhance your layer both by controlling when the video overlay is displayed by using any combination of the 3 offset parameters (see Trimming videos for more information on the parameters and their possible values). You can also decide where and how it is placed on the base video using gravity, offset and other placement qualifiers, and by applying transformations to the layered asset, with the following general syntax.

For example, adding an overlay of a video that fades in after 2.5 seconds and fades out 7.5 seconds later. The overlay is also positioned with a gravity of 'south east' and scaled to a width of 500 pixels.

See full syntax: l_video in the Transformation Reference.

Audio overlays

Add an additional audio track over the existing video using the audio overlay parameter (l_audio in URLs) and the public ID of a video or audio file stored in your product environment.

If you supply a video as the overlay, only the audio track will be overlaid. The visual part is discarded.

You can add audio tracks alongside the existing audio, such as adding a voiceover or music. You can also control which parts of the layered audio file to play using the 3 timing offset parameters (see Trimming videos). You can also control the volume using the volume effect.

Here's an example of adding an MP3 music file with the public ID, electronic to the hourglass_timer base video:

It's also possible to remove or replace the existing audio track from the base video. To remove the existing audio track, set the audio codec to none (ac_none in URLs). You can then replace this with your own audio by adding it as an audio overlay as shown above.

Here's an example of replacing the original audio of the video with the electronic MP3 file and reducing the volume by 50%:

See full syntax: l_audio in the Transformation Reference.

See also: Mixing audio tracks, Defining alternate audio tracks.

Text overlays

Add a text overlay over the base video with the text property of the layer parameter ( l_text: in URLs). The parameter also requires specifying font family and size (separated with an underscore and followed by a colon), and the text string to display. The general URL syntax for adding a text layer takes the following form:

In addition to the required font and size styling values, you can optionally specify a variety of other CSS-like styling parameters and to further customize your text layers by specifying text color, adding line breaks, emojis and other special characters, and other text layer options.

Cloudinary first generates an image from the text definition and then overlays it like any other image overlay, and thus supports all the same transformations that any image overlay supports.

For example, to overlay the text string "Coffee" in the Arial font with a size of 80 pixels (l_text:Arial_80:Coffee/fl_layer_apply):

See full syntax: l_text in the Transformation Reference.

Try it out: Layers.

Timed text overlays

You can control when a text overlay appears and/or disappears by adding timing qualifiers to the text layer. Use one or more of the following as part of the layer_apply component:

• "so_ (start offset)
• eo_ (end offset)
• du_ (duration)."

Example: Four back-to-back labels, each visible for 4 seconds:

You can also use du_<time> instead of specifying both so_ and eo_. For full syntax, see so start offset, eo end offset, and du duration.

Subtitles

You can add subtitles to videos as an embedded layer based on SRT or WebVTT files that were previously uploaded to Cloudinary as raw files. To do this, use the subtitles: property of the overlay parameter ( l_subtitles: in URLs), followed by the public ID (including the .srt or .vtt extension).

For example, to overlay the subtitles in the outdoors.vtt file:

You can optionally include font and size settings (separated with an underscore) before the subtitles file name. For example, to overlay the subtitles in the outdoors.vtt file using the Arial font with a size of 20 pixels:

You can also control the color of the text by adding the color property (co in URLs) to change the fill color of the text, and adding the background property (b in URLs) to change the color of the text background. Colors can be set as an RGB hex triplet (e.g. b_rgb:3e2222), a 3 character RGB hex (e.g. co_rgb:777), a named color (e.g. b_green), or an RGB hex quadruplet, where the 4th value represents the opacity (e.g. b_rgb:3e222266).

For example, to overlay the subtitles in the outdoors.vtt file using the Arial font with a size of 40 pixels, in yellow text (FFFF00) with a black background:

Custom fonts for subtitles

In place of a universally available font name, you can specify the public ID of a custom font that you've uploaded to your product environment as a raw, authenticated file. Include the file extension (.ttf, .otf or .woff2) in the public ID.

For example, to overlay the subtitles in the outdoors.vtt file using the custom AlexBrush-Regular.ttf font at size 40, in white text on a black background:

For font upload requirements and other guidelines, see Custom fonts.

Subtitle positioning

You can use compass gravity positions (e.g., g_west, g_south_east, g_north) to control where subtitles appear on the video. Unlike most other layers, the default gravity for subtitles is south (bottom of the video) rather than center.

For example, to position subtitles at the top of the video:

See full syntax: l_subtitles in the Transformation Reference.