Overlaying an Image on a Video Using FFmpeg on Ubuntu

Album Cover: Eyes Open

"It's hard to argue when you won't stop making sense."
Snow Patrol / Hands Open

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


agen judi on March 18, 2017 at 12:59 PM:

Your blog has the same post as another author but i like your better


Manycam pro crack free download on March 18, 2017 at 10:18 PM:

Excellent blog here! Also your site loads up fast


السعودية on March 25, 2017 at 5:20 AM:

This is just the information I am finding everywhere. Thanks for your blog, I just subscribe your blog. This is a nice blog..


seo backlinks service on April 01, 2017 at 3:11 AM:

Merely a smiling visitant here to share the love (:, btw outstanding style.


David on April 01, 2017 at 5:52 AM:

You make so many great points here that I read your article a couple of times. Your views are in accordance with my own for the most part. This is great content for your readers.


designer backpacks for men on April 04, 2017 at 11:02 AM:

Offering wide collection of men designer bags made from high quality materials. Our bags made in Italy and we ship it for free to you.


زراعة on April 09, 2017 at 1:26 PM:

Pretty good post. I just stumbled upon your blog and wanted to say that I have really enjoyed reading your blog posts.


carding forum on April 23, 2017 at 11:22 AM:

Where else could I get that type of information written in such an ideal means?


designer leather briefcase on April 30, 2017 at 4:41 AM:

Offering wide collection of leather briefcases made in Italy.


csgo match betting on May 03, 2017 at 5:19 AM:

Bet on an outcome of events in Counter Strike:Global Offensive matches and earn coins for purchasing of skins in the Store.


eccmjxls on May 15, 2017 at 5:23 AM:
versace jeans on June 02, 2017 at 3:24 PM:

i like your website and the thme you picked is super. I will be back.


marathi actress on July 28, 2017 at 5:48 AM:

Excellent article. Very interesting to read. I really love to read such a nice article. Thanks! keep rocking.


where I can buy italian handbags on July 31, 2017 at 3:45 AM:

It might appear like numerous customers are investigating the group for various offers. That is a decent attempt as the shot is truly open inside here.


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.