overlay video filter within the -vf argument. This powerful tool allows you to position a static image or another video stream over your primary footage with precise control over coordinates, timing, and blending modes, enabling everything from simple watermarks to complex visual compositions directly in the command line.
Basic Overlay Syntax
The core of this operation relies on theoverlay filter. To use it, you must provide two inputs: the main video stream and the image file to be overlaid. The basic structure involves specifying the input files with -i flags and then chaining the filter into the output command.
For example, if you have a video file named input.mp4 and an image file named logo.png, the command structure looks like this:
ffmpeg -i input.mp4 -i logo.png -filter_complex "overlay=x:y" output.mp4x and y represent the horizontal and vertical coordinates where the top-left corner of the image will appear. If you omit these values, FFmpeg defaults to placing the image at the top-left corner (0,0). It is crucial to use -filter_complex instead of -vf when dealing with multiple inputs, as standard video filters cannot handle more than one input stream natively without complex graphing.
Positioning the Image
Precise placement is often required for professional-looking results. You can specify exact pixel values for thex and y parameters. For instance, to place a logo 10 pixels from the right edge and 10 pixels from the bottom edge, you would calculate the coordinates based on the video resolution. However, FFmpeg offers dynamic expressions that make this easier.
You can use variables such as w (width of the overlay) and W (width of the main video) to create relative positions. To center the image horizontally, you can use the expression (W-w)/2. To keep it at the top vertically, you simply set y=0.
A common use case is placing a watermark in the bottom-right corner. The command would look like this:
ffmpeg -i input.mp4 -i logo.png -filter_complex "overlay=W-w-10:H-h-10" output.mp4W-w-10 calculates the distance from the left edge by taking the total width minus the logo width minus 10 pixels of padding. Similarly, H-h-10 handles the vertical positioning. This approach ensures the logo stays correctly positioned regardless of the video's resolution, provided the aspect ratio remains consistent.
Controlling Timing and Duration
By default, the overlay appears throughout the entire duration of the video. If you need the image to appear only during specific timestamps, you can use theenable option within the filter. This allows you to define start and stop times using time expressions.
For example, to show the logo only between the 5-second mark and the 10-second mark, you would modify the filter string:
ffmpeg -i input.mp4 -i logo.png -filter_complex "overlay=enable=between(t\,5\,10)" output.mp4\). This feature is particularly useful for adding temporary notifications, subtitles, or animated elements that should not persist for the whole clip.
Handling Transparency and Alpha Channels
Most modern overlays are PNG files with alpha channels, allowing for transparent backgrounds. FFmpeg handles this automatically if the output codec supports transparency, such as WebM or MOV with specific codecs. However, sometimes you may need to explicitly manage the alpha channel or blend mode. If your image has a solid background that you want to remove or blend, you might need additional preprocessing steps. But for standard PNG overlays, ensuring the input image has an alpha channel is sufficient. Theoverlay filter respects the alpha information, compositing the non-transparent parts of the image onto the underlying video frame.
For more advanced blending, such as making the logo semi-transparent, you can adjust the opacity. While the basic overlay filter does not have a direct opacity parameter, you can chain it with other filters or use expressions to modulate the alpha value. Alternatively, pre-processing the image with tools like ImageMagick before feeding it into FFmpeg is a common workflow for complex graphical adjustments.
Common Pitfalls and Troubleshooting
One frequent error occurs when users try to use-vf with multiple inputs. As mentioned earlier, -vf applies to a single input stream. When combining a video and an image, you must use -filter_complex. Another issue arises with incorrect coordinate calculations, leading to the image being cut off or placed outside the visible area. Always verify the resolution of both the source video and the overlay image.
Additionally, if the output file is significantly larger than expected, check the encoding settings. Using high bitrates or lossless codecs for the final output can increase file size dramatically. For web distribution, consider using H.264 with a reasonable CRF (Constant Rate Factor) setting to balance quality and file size.
For related techniques involving text overlays, you might find our guide on FFmpeg Textbox Padding using boxborderw useful for refining how textual elements interact with video frames. Proper padding and border settings can enhance readability and aesthetic appeal, similar to how image overlays contribute to the overall composition.
Frequently Asked Questions
Why is my overlay appearing in the wrong position?
This usually happens because the default coordinates are set to 0,0 (top-left), or because the resolution of the overlay image differs significantly from the video. Use dynamic expressions like W-w to ensure the position scales correctly with the video dimensions.
Can I overlay a video on top of another video?
Yes, the overlay filter works with two video streams just as well as a video and an image. You simply provide two -i video inputs and apply the filter to combine them into a single output stream.
How do I make the overlay fade in and out?
You can achieve fading effects by animating the opacity using the enable option combined with time-based expressions. For smoother animations, consider using the xfade filter or pre-rendering the transparency changes in external software.
What if my output video has no audio?
When using -filter_complex, FFmpeg does not automatically copy audio streams from the first input. You must explicitly add the -map 0:a flag to include the original audio track in your final output file.
Does the overlay affect the video bitrate?
The overlay itself does not change the target bitrate, but adding complex visual elements can increase the encoding difficulty. This may result in slightly higher bitrate requirements to maintain the same perceived quality, especially if the overlay contains fine details or motion.