How to Add Watermark to HLS Stream Using FFMPEG

Adding a watermark to an HLS stream with FFmpeg requires precise filtergraph syntax and proper segment handling. This guide details the correct overlay commands, avoiding deprecated flags like -strict experimental. You will learn to position logos accurately using valid arithmetic expressions for coordinates. The process ensures your watermarked video segments remain compatible with standard players while maintaining stream integrity during live or recorded ingestion.

Preparing the Watermark Asset

Before invoking FFmpeg, ensure your watermark image is in a supported format such as PNG with transparency. The image should be relatively small compared to the target video resolution to avoid obscuring content. Common dimensions are 100x100 pixels or similar. If your source video is 1920x1080, a large watermark might look disproportionate. You can use ImageMagick or any graphic editor to resize the asset beforehand. The file path must be accessible to the user running the FFmpeg command. Storing the logo in the same directory as your script simplifies relative path references. Avoid using complex vector formats that FFmpeg might struggle to decode quickly during real-time processing. A static PNG is the most reliable choice for low-latency streaming workflows.

Constructing the Filtergraph

The core of this operation lies in the -vf (video filter) parameter. You need to combine the main video input with the watermark image using the overlay filter. The basic syntax is overlay=x:y, where x and y define the top-left corner of the watermark. To center the watermark, you must calculate these values dynamically. A common mistake is using invalid syntax like (W-w)/2:H-h. Division has higher precedence than colon separation in some parsers, or simply lacks necessary parentheses. The correct expression uses explicit grouping: overlay=(W-w)/2:(H-h)/2. Here, W and H are the input video width and height, while w and h are the overlay image dimensions. This ensures the logo stays centered regardless of resolution changes. If you prefer bottom-right placement, use overlay=W-w-10:H-h-10. This adds a 10-pixel margin from the edges. Always test the filtergraph on a short clip before applying it to a full HLS pipeline. Incorrect syntax will cause FFmpeg to exit with an error code, halting the stream creation immediately. Do not rely on trial and error in production environments. Verify the coordinate math manually if the visual output is misaligned.

Handling HLS Segment Duration

When generating HLS streams, segment duration affects how frequently the manifest updates and how clients buffer data. Standard practice often involves segments between 2 and 10 seconds. However, for specific archival or long-form content, longer durations may be required. Refer to our guide on Creating HLS Segments with a Duration of 200 Seconds if you need extended segment lengths. For typical live streaming, keep segments short to reduce latency. Use the -hls_time flag to set this value. For example, -hls_time 4 creates four-second segments. Combine this with -hls_list_size 0 to create an infinite playlist if needed, or a fixed number for VOD. Ensure the segment duration aligns with your CDN caching policies. Too short segments increase manifest overhead; too long ones delay recovery from packet loss.

Complete Command Structure

A robust command integrates the input source, the filtergraph, and the HLS output parameters. Avoid deprecated flags entirely. Modern FFmpeg versions handle experimental features automatically when appropriate. The following structure demonstrates a complete workflow:

ffmpeg -i input.mp4 -i logo.png \
-filter_complex "overlay=(W-w)/2:(H-h)/2" \
-c:v libx264 -preset fast -crf 23 \
-c:a aac -b:a 128k \
-hls_time 4 \
-hls_playlist_type event \
output.m3u8

In this example, -filter_complex allows multiple inputs and outputs. The -c:v libx264 encoder ensures broad compatibility. The -crf 23 setting provides a good balance between quality and file size. Adjust the bitrate based on your network constraints. The audio codec aac is standard for HLS. If your input has no audio, remove the audio encoding lines. Always check the FFmpeg version documentation for available options. Newer versions may support additional filters like drawtext for dynamic text overlays, but overlay remains best for static images.

Troubleshooting Common Issues

If the stream fails to play, check the console output for filter errors. The most frequent issue is incorrect coordinate syntax. Remember to enclose division operations in parentheses. Another problem arises if the watermark image format is unsupported. Convert it to PNG if necessary. Latency spikes can occur if the segment duration is mismatched with the keyframe interval. Set -g (GOP size) to match or exceed the segment duration. For instance, if segments are 4 seconds, set -g 100 at 25 fps. This prevents cutting frames in the middle of a segment. Also, monitor CPU usage. Real-time filtering can be resource-intensive. If the system drops frames, lower the preset speed or reduce the overlay complexity. Consider using hardware acceleration with -hwaccel flags if available on your server. FFmpeg Watermark and HLS Stream: How to Add Watermarks to HLS Video Streams provides additional context on integrating these techniques into larger broadcasting pipelines. Understanding the interplay between encoding settings and filter performance is crucial for stable delivery.

Frequently Asked Questions

Why does my watermark appear blurry?

Blurry watermarks usually result from scaling artifacts or low-resolution source images. Ensure your logo PNG is high enough resolution for the target video size. If you scale down significantly, the detail loss becomes visible. Try using a larger source image and letting FFmpeg scale it down during the overlay process rather than pre-scaling poorly.

Can I add multiple watermarks?

Yes, you can chain multiple overlay filters in the -filter_complex graph. Label each input and output stage carefully. For example, [0:v][1:v]overlay=10:10[wm1];[wm1][2:v]overlay=W-w-10:H-h-10[out]. This applies one logo top-left and another bottom-right. Each step requires careful label management to avoid reference errors in the filterchain.

Does the watermark affect stream latency?

Adding a filter increases CPU load, which can indirectly raise latency if the encoder falls behind. However, simple overlay operations are generally lightweight. If you notice increased delay, optimize by using faster encoding presets like -preset ultrafast or moving to hardware-accelerated encoding. Monitor the sync status between audio and video timestamps.

How do I make the watermark semi-transparent?

Use the format=rgba option in the overlay filter if your logo lacks alpha channel handling issues. Alternatively, adjust the opacity in your image editor before uploading. FFmpeg's overlay filter respects the alpha channel of PNG images natively. If you need dynamic opacity, you can use the colorchannelmixer filter, but pre-processing is simpler and more efficient.

What happens if the input video resolution changes?

Using dynamic coordinates like (W-w)/2 handles resolution changes automatically. The watermark will reposition itself to stay centered relative to the new dimensions. Static coordinates will drift or go off-screen. Always prefer dynamic expressions for streaming workflows where resolution switching might occur due to adaptive bitrate streaming requirements.