To overlay PNG credits onto a video using FFmpeg, you must use the
overlay filter with explicit input labels to ensure correct positioning. This method allows you to place static or animated images over your source footage without re-encoding the entire video if filters are not used, though compositing requires encoding. By specifying the X and Y coordinates precisely, you can align text or logos exactly where needed in the frame.
Understanding the Overlay Filter Syntax
The core of this operation relies on the
overlay video filter. A common mistake is providing only the position values without referencing the specific input stream that contains the PNG image. The syntax requires you to label your inputs so FFmpeg knows which stream is the base video and which is the overlay. You assign labels using the
-map command or by ordering inputs carefully, but the most robust method involves explicit labeling in the filter chain.
When constructing the command, you start with the base video file followed by the PNG image file. The filter expression then references these inputs. For example, if your base video is input 0 and your PNG credit is input 1, the filter string will look like
overlay=main_w-overlay_w:main_h-overlay_h. This formula places the overlay at the bottom-right corner of the main video. It is critical to include the full expression; omitting the label reference or the coordinate calculation often results in errors or incorrect placement.
Step-by-Step Command Construction
To create a functional command, follow this logical sequence. First, identify your source video and the PNG file containing your credits. Ensure the PNG has an alpha channel if you want transparent backgrounds, as this prevents black boxes around your text. Next, construct the FFmpeg command line.
Here is a basic structure for placing credits in the bottom center of the video:
ffmpeg -i input.mp4 -i credits.png -filter_complex "overlay=(main_w-overlay_w)/2:(main_h-overlay_h)" -c:a copy output.mp4
In this command,
-i input.mp4 defines the primary video stream.
-i credits.png defines the secondary image stream. The
-filter_complex flag allows for multiple inputs and outputs, which is necessary for compositing two different sources. Inside the quotes,
overlay=... specifies the position. The expressions
(main_w-overlay_w)/2 calculate the horizontal center, while
(main_h-overlay_h) positions it at the very bottom. Finally,
-c:a copy ensures the audio from the original video is passed through unchanged, saving time and preserving quality.
If you need the credits to fade in and out, you can add the
fade filter to the PNG input before the overlay. However, for simple static overlays, the direct overlay filter is sufficient and less prone to configuration errors. Always test with a short segment first to verify the coordinates match your visual expectations.
Handling Transparency and Alpha Channels
One of the most frequent issues when overlaying PNGs is dealing with transparency. If your PNG does not have an alpha channel, the background will appear as solid black or white, obscuring parts of your video. To check if your PNG supports transparency, you can inspect its properties or use FFmpeg’s own analysis tools. If you are generating the PNG from another format, ensure the export settings preserve the alpha channel.
For instance, if you are converting a HEVC video with alpha to a PNG sequence, you might encounter issues with color spaces. As noted in our guide on troubleshooting
HEVC with Alpha MOV to PNG Conversion, improper pixel format handling can strip transparency. When using the overlay filter, FFmpeg expects both streams to share compatible pixel formats. If they do not, you may need to insert a
format=yuva420p filter before the overlay to ensure the alpha channel is processed correctly.
This step is crucial for professional-looking credits. Without proper alpha handling, even perfectly positioned text will look amateurish due to harsh borders. Always verify the output visually, zooming in to check for jagged edges or missing transparency around the text glyphs.
Positioning Strategies for Different Layouts
Different credit sequences require different positioning. While bottom-center is standard for end credits, top-left might be better for watermarks or opening titles. You can adjust the X and Y coordinates dynamically using mathematical expressions within the overlay filter.
For top-left alignment, use
overlay=10:10 to place the image 10 pixels from the left and top edges. For top-right, use
overlay=main_w-overlay_w-10:10. These expressions automatically adjust if the video resolution changes, making them more robust than hard-coded pixel values. This adaptability is essential when distributing videos across platforms with varying aspect ratios.
Additionally, consider the duration of the overlay. If your credits scroll, you will need to animate the Y coordinate over time using functions like
t (time) in the filter expression. However, for static PNG files, fixed positions are simpler and more reliable. Avoid complex animations unless necessary, as they increase processing time and potential points of failure.
Common Pitfalls and Debugging
Errors in FFmpeg commands often stem from syntax mistakes or mismatched inputs. If you receive an error about "Invalid arguments," check your overlay syntax closely. Ensure that parentheses are balanced and that variable names like
main_w are spelled correctly. Another common issue is forgetting to map the audio stream. If you omit
-c:a copy, FFmpeg might re-encode the audio, leading to sync issues or quality loss.
Also, remember that the order of inputs matters. The first
-i is the main video, and subsequent inputs are overlays. Mixing this up will result in the video being overlaid on the PNG, which is usually not the desired effect. If you are unsure about the pixel format compatibility, adding a
format=yuva420p filter to the overlay stream can often resolve black screen issues during rendering.
For more advanced scenarios involving color accuracy, refer to our article on
Converting PNG to MOV with Exact Colors, as color space mismatches can sometimes affect how overlays blend with the base video. Proper debugging ensures a smooth workflow and high-quality final output.
Frequently Asked Questions
Why is my PNG overlay showing a black background?
This usually happens because the PNG lacks an alpha channel or the pixel formats between the video and image are incompatible. Ensure your PNG was saved with transparency enabled and consider adding a format filter to match the video's pixel format before overlaying.
Can I overlay multiple PNG images simultaneously?
Yes, you can chain multiple overlay filters in the filter_complex string. Each additional overlay requires its own input and a unique filter label to distinguish it from others in the chain.
How do I make the credits scroll vertically?
To scroll, you need to animate the Y coordinate using the time variable
t in the overlay expression. For example,
overlay=0:t*10 moves the image down by 10 pixels per second. This requires careful timing to match the duration of your music or video.
What if the overlay covers important parts of the video?
Adjust the X and Y coordinates to move the overlay away from key content. Use expressions like
main_w-overlay_w-10 for right alignment or
10 for left alignment to keep safe zones clear.
Does using the overlay filter slow down rendering?
Yes, compositing adds computational load because FFmpeg must process each frame to blend the layers. Using hardware acceleration flags like
-hwaccel cuda can help mitigate performance drops during encoding.