Overlaying an Image on a Video Using FFmpeg on Ubuntu

Album Cover: Flight of the Conchords

"She's so hot, she's making me sexist."
Flight of the Conchords / Boom

Posted on July 09, 2008 2:18 AM in Computers
Warning: This blog entry was written two or more years ago. Therefore, it may contain broken links, out-dated or misleading content, or information that is just plain wrong. Please read on with caution.

Last month I posted about generating video thumbnail storyboards on Ubuntu using, among other things, FFmpeg. Now that I have FFmpeg in my tool belt, I figured I'd see how hard (or easy) it is to overlay an image on a video using the tool. It turns out it's dead simple, as long as you're okay with utilizing a feature that has been deprecated.

FFmpeg's Video Hook Documentation is a great source for getting your feet wet with FFmpeg's -vhook option, which allows you to do a whole slew of different things with a video file. Since I was solely interested in overlaying an image like a JPG, GIF or PNG file on top of an existing video, I focused on the "Date and time stamp, security-camera style" example provided in the video hook documentation's imlib2.c section. I wasn't worried about including rendered text over the image, but simply overlaying the image by itself, so (borrowing some pieces from other examples that didn't work with video streams) I narrowed the required pieces down to the following:

ffmpeg -i input.avi -vhook 'vhook/imlib2.so -x 0 -y 0 -i overlay.png' output.avi

However, after attempting to run this command from the command line in Ubuntu, I was presented with the following error:

vhook/imlib2.so: cannot open shared object file: No such file or directory

It took a little tinkering, but I eventually found that the shared object file did indeed already exist in my Ubuntu installation. I simply needed to use an absolute path when referring to it in the -vhook call. That changed the FFmpeg call to the following:

ffmpeg -i input.avi -vhook '/usr/lib/vhook/imlib2.so -x 0 -y 0 -i overlay.png' output.avi

As noted in FFmpeg's Video Hook Documentation, the -vhook option has been deprecated, but it still appears to be working in the latest and greatest version of FFmpeg that I originally installed.

One other thing I should mention is that the -x and -y options specify where the upper-left corner of your overlay image should be placed on the input video. In my example, the image overlay would be placed in the upper-left corner of the video. With a setting like -x 0 -y 100 it would be placed at the far left of the video, but with its top-most edge 100 pixels down from the top of the video.

If you're looking for an easy way to overlay a picture or image on an existing video file, it really doesn't get any easier than this. I know I saw some examples of people attempting to do similar things on Windows as well, so it doesn't appear that this is limited to Ubuntu. At some point, it might be nice to find out what the non-deprecated approach to this particular problem is, but for the time being the -vhook approach is working just fine.


Keith on September 22, 2008 at 10:32 AM:

Hey Bernie,

Thanks for the tutorial. I was wondering what version of Ubuntu/ffmpeg are you using? I have the vhook library installed in the same place as you, but when I try the above command I get some error messages, and the resulting output movie is the same as the input. Did you have to go through any extra steps to get vhook supported?

Here is the error message that is outputted:

("***** Imlib2 Developer Warning ***** :
This program is calling the Imlib call:
With the parameter:
being NULL. Please fix your program.



Keith on September 22, 2008 at 10:33 AM:

p.s. Your site design and banner is absolute beautiful. All the way down to the comment boxes. :)


Bernie Zimmermann on September 23, 2008 at 11:56 PM:

Thanks for the compliment on my site design, Keith. As for the -vhook stuff, I didn't do anything special beyond what I documented here. However, do note that I wrote the following in my original post: "It turns out it's dead simple, as long as you're okay with utilizing a feature that has been deprecated."

It could very well be that the deprecation has actually gotten to the point where it no longer works in the latest version of Ubuntu. I haven't tried overlaying any images lately, so I can't say one way or another at the moment whether the feature is still working for me. If you happen to find a solution to the problem, though, please do share it here.


Keith on September 24, 2008 at 12:52 PM:

Hey Bernie,

I was able to get it working after some playing around. It turns out I was missing the "-i" parameter for the vhook command (I only had one for ffmpeg itself, and didn't realize it was used twice).

I also tried was able to get another alternative working, watermark.so. In case anyone wants to try it, the command I used was:

ffmpeg -i input.avi -vhook '/usr/lib/vhook/watermark.so -f watermark.gif -m1' -an out.avi

In this case, however, the watermark image should be the size of the movie itself. Also, it does some color thresholding (described in the documents), so you may have to play around with it a bit depending on the type of watermark you want to use. In a simple the case of a simple white on transparent logo such as what I'm using, the above should work fine.

Thanks again for the tutorial Bernie. :)

Take care,


Bernie Zimmermann on September 25, 2008 at 9:08 AM:

Glad to hear you got it working, Keith. Thanks for the additional information regarding watermarks, too.


eric on February 28, 2009 at 12:06 PM:

Thanks for this information.
It works really well.


Vareck on March 07, 2009 at 5:02 PM:

hey thanks for the tips. I'd been searching for days.
Btw your site looks soooo nice! You should consider something in graphic design. The first thing I thought when I loaded this site was "wow what a pleasant surprise", right after hitting bookmark ;-) nice design dude


Bernie Zimmermann on March 08, 2009 at 11:31 PM:

Thanks for the compliment, Vareck.


pleckie on August 27, 2010 at 9:30 AM:

vhook is dead in 10.04 LTS. Why? What has replaced it. An infernal mystery ensues.


roger on October 28, 2011 at 1:32 PM:

The links seem down...


high PR blog commenting service on September 03, 2016 at 1:24 AM:

I wish more writers of this kind of substance would take the time you did to look into and compose so well. I am exceptionally inspired with your vision and understanding.


auto followers instagram on September 10, 2016 at 1:11 AM:

I appreciate what you have done here. I like the part where you say you are doing this to give back yet I would expect by every one of the remarks this is working for you too.


buying followers on October 10, 2016 at 10:04 AM:

I appreciated your work very thanks buying followers|youtube viewer


Post Comments

If you feel like commenting on the above item, use the form below. Your email address will be used for personal contact reasons only, and will not be shown on this website.


Email Address:



Check this box if you hate spam.