How to Overlay an Animated Gif on a Video using FFmpeg

A common operation in FFmpeg is overlaying an animated asset on top of a video. Why would you want to do this? One common pattern is needing to add an animated watermark on a video - this might be a company logo, or some kind of animation.

Examples

Overlaying a static PNG

In a previous article we discussed how to overlay static images.

You can read that article here.

In this article we will focus on overlaying an animated gif which uses a similar process, but with a few important tweaks.

Overlaying an animated gif

Assuming that you have a video named video.mp4 and an animated gif named animated.gif - the FFmpeg command to overlay the gif on the video is as follows:

ffmpeg -y -i video.mp4 -stream_loop -1 -i animated.gif -filter_complex [0]overlay=x=0:y=0:shortest=1[out] -map [out] -map 0:a? test.mp4

This will overlay the gif at the top left corner. The important part here is the command -stream_loop -1 which loops the gif infinitely over the video.

You also need to use the shortest=1 flag, otherwise the FFmpeg process will render infinitely.

It is also possible to change the size of the gif overlay if you need to, using the ffmpeg scale command as part of the filter_complex block.

Use the Bannerbear API

If you need an easy way to apply GIF overlays then you can try using the Bannerbear API.

It's a REST API that makes some of these types of common FFmpeg operations much more simple, so that you don't have to worry about cropping / scaling / timestamping. It's also highly scalable so you don't have to worry about managing cloud FFmpeg instances - it's all done for you :)

From our Knowledge Base

Here is some further reading from our knowledge base: Can I overlay an animated gif logo on my Bannerbear video templates?