MEDIA GUIDES / Video effects

Mastering the Skill of Video Overlay

What if you could craft compelling video experiences by layering visuals, like how digital artists create rich, exciting visuals? Picture creating a refined marketing promotion that combines elegant product images with striking text overlays, a tutorial that smoothly leads users with helpful annotations, or an app function that impresses with lively, multi-layered effects–if you know how to overlay videos.

More than just eye candy, video overlays offer a way to create storytelling and stunning visuals. Developers can use powerful tools to precisely and efficiently merge, enhance, and deliver media, going beyond simple tasks.

In this article, we’ll explore how to overlay videos with Cloudinary, share some tips, and empower you to create captivating video experiences for your users.

In this article:

Using Video Overlays to Make an Impact

Video overlays are a powerful tool for developers working with dynamic content, helping reduce versioning needs and streamline asset reuse. They also open up opportunities for automation and personalization, especially when integrated into media pipelines.

Here are some common use cases for video overlays:

  • Branded elements: Add watermarks, logos, or taglines without re-exporting the entire video.
  • Dynamic subtitles and captions: Serve localized or accessibility-friendly text on the fly.
  • Interactive UI components: Embed buttons, links, or forms into video players for real-time engagement.
  • Informational layers: Show data overlays such as stats, names, or timestamps during playback.
  • Marketing customizations: Tailor videos for different platforms or audiences with specific overlays, like seasonal promotions or location-based offers.

How to Overlay Videos

Overlaying videos is a powerful way to enhance your content, whether you’re creating engaging tutorials, branded promotions, or dynamic social media posts. With Cloudinary Video, you can programmatically overlay videos, add effects, and customize them with ease—all through a few lines of code.

Step 1: Picking Your Videos

The foundation of a great video overlay starts with selecting the right assets. You’ll need at least two videos: a base video (the primary footage) and an overlay video (the layer that will appear on top). Choose videos that complement each other visually and thematically. Here are a few things to consider when picking your videos:

  • Resolution and Aspect Ratio: Ensure both videos have compatible dimensions to avoid awkward scaling.
  • Duration: The overlay video can be shorter than the base video, but plan how they’ll align in your final output.
  • Content Clarity: The overlay should enhance, not obscure, the base video. Or, in the case of watermarks, it should still be transparent enough so it doesn’t completely block important elements of the video.

For this tutorial, let’s assume we’re using a base video of a scenic landscape (public ID: glide-over-coastal-beach) and an overlay video of an hourglass (public ID: hourglass_timer), both from the Cloudinary demo cloud.

Step 2: Uploading the Selected Videos

Note: While this guide is using publicly available videos from the Cloudinary demo cloud, you will need to upload your own videos to the platform to use them.

Before you can overlay videos, they need to be hosted on Cloudinary. If you haven’t already, sign up for a free Cloudinary account. Once you’ve signed up, log in to your account and head over to the Programmable Media dashboard. Here click on the Go to API Keys button to get your cloud name, API key, and API secret. These credentials will allow you to upload and manipulate media programmatically.

Now, we need to upload our images to the Cloudinary cloud. Thankfully, Cloudinary provides us with the ability to upload our images via their API or through their website. For now, we will upload our videos via their API using Node.js.

Interested in learning more about what languages Cloudinary supports? You can find the documentation for all of our SKDs here.

We will begin by opening up our terminal and start by navigating to your project directory. Now install the Cloudinary SDK by running:

npm install cloudinary

Next, create a file called upload.js in your project directory and add the following code to set up your credentials:

const cloudinary = require('cloudinary').v2;

cloudinary.config({
  cloud_name: 'your_cloud_name',
  api_key: 'your_api_key',
  api_secret: 'your_api_secret'
});

Remember to replace your_cloud_name, your_api_key, your_api_secret with your actual Cloudinary credentials.

Now, let’s upload two videos to the Cloudinary cloud. To do this, we will begin by copy and pasting our videos into an assets folder in the project directory. Next, we will create a function called uploadVideos() to upload our videos to the cloud:

async function uploadVideos() {
  try {
    const baseVideo = await cloudinary.uploader.upload('path/to/glide-over-coastal-beach.mp4', {
      resource_type: 'video',
      public_id: 'glide-over-coastal-beach'
    });
    const overlayVideo = await cloudinary.uploader.upload('path/to/waving_person.mp4', {
      resource_type: 'video',
      public_id: hourglass_timer
    });
    console.log('Videos uploaded successfully:', baseVideo.url, overlayVideo.url);
  } catch (error) {
    console.error('Upload failed:', error);
  }
}

uploadVideos();

Here we use the cloudinary.uploader.upload() method to upload the videos to the cloud. The method takes the file path and options like resource_type: 'video' to specify the asset type and public_id to name it. This code uploads both videos asynchronously and logs their URLs upon success.

Finally, we run the script with node upload.js, so that our videos will be uploaded and be available in your Cloudinary Media Library for transformations.

Step 3: Arranging the Videos on a Timeline

Now that our videos have been uploaded, let’s begin arranging our videos before applying the overlay. Cloudinary doesn’t use a traditional timeline like video editing software. Instead, it applies transformations to layer videos dynamically via URL parameters or SDK methods.

To control the timing you can trim or offset the overlay video to align it with the base video. For this example, we will set the start offset to 2 seconds and the duration to 5 seconds, so that our overlay video starts at the 2-second mark and ends at the 7-second mark of the base video.

Now, let’s begin by creating a new file called overlay.js and configuring Cloudinary as before. Next, let’s use the Cloudinary URL helper to generate the base video URL:

const cloudinary = require('cloudinary').v2;

cloudinary.config({
  cloud_name: 'your_cloud_name',
  api_key: 'your_api_key',
  api_secret: 'your_api_secret'
});

const baseVideoUrl = cloudinary.url('glide-over-coastal-beach', {
  resource_type: 'video',
  transformation: [
    { width: 1280, height: 720, crop: 'fill' } // Resize base video
  ]
});
console.log('Base Video URL:', baseVideoUrl);

In this code, we use the cloudinary.url method to generate a delivery URL. We also use the transformation parameter to resize the base video to 1280×720 pixels using the fill crop mode to ensure it fits without distortion. The overlay’s timing will be adjusted in the next step.

Step 4: Adding Cool Overlay Effects

With the base video now ready, let’s overlay the hourglass video on top of our beach video. We will also add a fade-in effect to make it look smooth and professional. To do this, update your overlay.js file with the following code:

....
const overlayVideoUrl = cloudinary.url('glide-over-coastal-beach', {
  resource_type: 'video',
  transformation: [
    { width: 1280, height: 720, crop: 'fill' }, // Resize base video
    { overlay: 'video:hourglass_timer', width: 300, height: 300, start_offset: '2', duration: '5' }, // Overlay video
    { effect: 'fade:1000' }, // Fade-in effect for overlay
    { effect: 'fade:-1000'}, // Fade-out effect
    { flags: 'layer_apply', gravity: 'south_east' } // Apply the overlay
  ]
});
console.log('Overlay Video URL:', overlayVideoUrl);

Here, we first define the overlay as 'video:hourglass_timer' telling Cloudinary to use the hourglass video as the overlay. Next, we use the width and height parameters to resize the overlay to a smaller 300×300 square. We also define a position using the gravity parameter as 'south_east' to position the overlay in the bottom-right corner of the base video.

As mentioned before, we also use the start_offset and duration parameters to define the start and end of the overlay. Finally, we add an overlay effect using the effect parameter and define it as 'fade:1000' as well as 'fade:-1000'. This adds a 1-second fade-in effect along with a fadeout effect to the overlay for a polished look. Finally, the flags: 'layer_apply' applies the overlay transformation to the base video.

Here is what our video looks like:

Step 5: Saving and Sharing Your Video

Once you’re happy with how your overlaid video looks, it’s time to save it or share it with the world. Cloudinary lets you use the generated URL directly, but if you want to store the transformed video permanently, we can save it to your cloud.

To save the video, update your overlay.js file with this code:

const overlayVideoUrl = cloudinary.url('glide-over-coastal-beach', {
  resource_type: 'video',
  public_id: 'final_beach_hourglass_video',
  eager: [
    { width: 1280, height: 720, crop: 'fill' }, // Resize base video
    { overlay: 'video:hourglass_timer', width: 300, height: 300, start_offset: '2', duration: '5' }, // Overlay video
    { effect: 'fade:1000' }, // Fade-in effect for overlay
    { effect: 'fade:-1000'},
    { flags: 'layer_apply', gravity: 'south_east'} // Apply the overlay
  ]
});
console.log('Overlay Video URL:', overlayVideoUrl);

Here, we use the cloudinary.uploader.upload method again, but this time we pass the generated URL and the eager option. The eager parameter tells Cloudinary to pre-generate the transformed video and save it under the public ID final_beach_hourglass_video. Run this with node overlay.js, and you’ll get a permanent URL for your saved video.

To share it you can either download the video using the URL, or you can embed the URL in an HTML video tag:

<video controls>
  <source src="https://res.cloudinary.com/your_cloud_name/video/upload/.../final_beach_hourglass_video.mp4" type="video/mp4">
</video>

How Can I Add Text to My Video Overlay?

Adding text to your video overlay is a fantastic way to include titles, captions, or calls-to-action that grab your audience’s attention. With Cloudinary, you can overlay text programmatically, customizing its font, size, color, and position.

Like before, create a new file in your project directory and rename it as text-overlay.js. Again, start by setting up Cloudinary with your account credentials. Next, inside the overlay parameter, add in your text using the text option:

const textOverlayUrl = cloudinary.url('glide-over-coastal-beach', {
  resource_type: 'video',
  transformation: [
    { width: 1280, height: 720, crop: 'fill' }, // Resize base video
    { color: "#FFFFFF", overlay: { font_family: 'Roboto', font_size: 50, font_weight: 'bold', text: 'Coastal Countdown'}}, // Add text overlay
    { flags: 'layer_apply', gravity: 'center'} // Apply the text layer
  ]
});

console.log('Text Overlay URL:', textOverlayUrl);

Here we define the font as 'Roboto' and define a font size as 50. We also bold the text using the font_weight option. Next, we define the text to overlay as “Coastal Countdown”, define the text color as white for visibility against the video, and position it in the center of the video. Here is what our video looks like:

How Can I Overlay a Picture on a Video?

Overlaying a picture on your video is a great way to add branding, like a logo, or include a static element that ties into your content. With Cloudinary, this is just as easy as adding a video or text overlay. Let’s overlay a logo image onto our base video. This could be a sun icon or a custom brand mark to give your video a professional polish.

Now, let’s create a new file called image-overlay.js in your project directory. Next, simply define the overlay parameter with the public ID of the image you want to use. Here we will be using the cloudinary logo from the Cloudinary demo cloud:

const imageOverlayUrl = cloudinary.url('glide-over-coastal-beach', {
  resource_type: 'video',
  transformation: [
    { width: 1280, height: 720, crop: 'fill' }, // Resize base video
    { overlay: 'docs:logo-semi-opaque', width: 150, x: 30, y: 30}, // Add image overlay
    { flags: 'layer_apply', gravity: 'north_west'} // Apply the image layer
  ]
});
console.log('Image Overlay URL:', imageOverlayUrl);

Here is what our video looks like:

Tips to Get The Most From Your Overlays

A well-crafted overlay can elevate your project from functional to unforgettable, whether it’s for an app, website, or social campaign. Here are some tips to refine your overlays, optimize performance, and captivate your audience:

  • Sync Timing for Maximum Relevance: Timing is everything when overlaying videos. Use Cloudinary’s timeline controls to trigger overlays at precise moments. This ensures your overlay enhances the narrative without overwhelming viewers early on.
  • Optimize for Lightweight Delivery: Heavy overlays can slow down your app, frustrating users. Keep file sizes lean with Cloudinary’s automatic quality and format adjustments, serving optimized versions like WebP or VP9 where supported. This balances quality and speed, making it ideal for mobile users or high-traffic sites.
  • Blend Subtly with Opacity and Effects: Avoid overpowering the base video by dialing down opacity or adding smooth transitions. Cloudinary lets you tweak transparency or apply fade effects, keeping the focus on the main content while adding a professional touch. Subtle blending makes overlays feel integrated, not intrusive.

Ready to Impress with Video Overlays

Creating engaging user experiences is key, whether it’s a product launch, a tutorial, or a social media campaign—it’s more than just layering content. Enjoy seamless delivery and high performance while experimenting with timing, effects, and positioning via Cloudinary’s intuitive tools.

Cloudinary’s API and transformation magic make it easy to go from concept to deployment, whether you’re tweaking a single overlay or scaling up for a full app. Take the next step—sign up for a free Cloudinary account and start playing with their video overlay features today.

Learn more:

Creating Vertical Video for Social Media Using Cloudinary’s Smart Video Cropping

Smart Cropping Just Got Smarter

QUICK TIPS
Matthew Noyes
Cloudinary Logo Matthew Noyes

In my experience, here are tips that can help you better overlay videos for immersive, high-performance visual storytelling:

  1. Use video alpha channels for seamless layering
    For advanced effects like transparent overlays (logos, HUDs, UI elements), use WebM or ProRes 4444 videos with alpha channels. Cloudinary supports formats that preserve transparency, making your overlays appear natively composited instead of boxed.
  2. Preprocess overlay clips with FFmpeg for better control
    Before uploading overlays, trim or alpha-mask them using FFmpeg to remove black frames or create softer edges. This reduces the amount of transformation needed in Cloudinary and gives you pixel-perfect precision.
  3. Leverage chained eager transformations for multi-stage rendering
    Chain multiple transformations using Cloudinary’s eager transformations to create progressive layers—like animating a logo first, then fading in text. This minimizes runtime complexity and allows you to cache partial outputs.
  4. Automate dynamic overlays with metadata triggers
    Use video metadata (title, timecode, user tags) to auto-generate overlays. For instance, if a user uploads a video with a “VIP” tag, Cloudinary can apply a badge or special banner overlay dynamically using conditional presets.
  5. Overlay live data feeds via timed image sequences
    Simulate live data overlays (e.g., sports scores, chat bubbles) by generating timestamped images or GIFs that are overlaid frame-aligned using start_offset and duration. Automate this pipeline with a server-side job queue.
  6. Test overlay readability across devices with accessibility presets
    For text overlays, predefine accessible styles (e.g., high-contrast, shadowed, bold) and apply them conditionally based on screen size or device. This improves usability and ensures overlays remain legible on small or bright displays.
  7. Optimize playback with lower frame rate overlays
    Overlay videos don’t always need to match the base video’s FPS. Pre-render overlays at 15 or 24 fps when possible to reduce file size, especially if they’re decorative or UI-focused. It improves performance without visual sacrifice.
  8. Apply “mask” overlays to control background visibility
    Use grayscale or alpha mask videos to selectively reveal parts of the base video. This is perfect for spotlight effects, animated transitions, or gradual scene reveals—turning a flat video into a layered experience.
  9. Use flags: splice for smooth sequential transitions
    If you’re stitching multiple video overlays back-to-back (e.g., different promotional intros), flags: splice lets you merge them without visible cuts or glitches. It enables a fluid, broadcast-quality experience.
  10. Track transformations via webhook feedback loops
    Set up webhooks to monitor processing status, frame analysis, or transformation failures. This allows you to dynamically retry failed overlays, fine-tune transformation logic, or trigger follow-up processes in real-time.
Last updated: Apr 11, 2025