Overlay Weather Image on RTSP Stream Using FFmpeg

This article provides a step-by-step guide on how to capture a live RTSP camera feed, overlay a locally updated weather image onto the video in real-time, and output the processed stream using FFmpeg. You will learn the exact FFmpeg commands required to merge these sources, position the overlay, and ensure the image dynamically updates as local weather conditions change.

Prerequisites

To get started, you will need: 1. An RTSP Stream URL from your IP camera (e.g., rtsp://username:password@ip_address:554/stream). 2. FFmpeg installed on your system. 3. A transparent PNG weather image (e.g., weather.png) saved locally. To prevent stream buffering issues, keep the image dimensions reasonably small (e.g., 200x200 pixels).

The FFmpeg Command

To overlay a local image that updates in real-time onto an RTSP stream, run the following command in your terminal:

ffmpeg -rtsp_transport tcp -i "rtsp://username:password@ip_address:554/stream" \
-f image2 -loop 1 -reload 1 -i "weather.png" \
-filter_complex "[0:v][1:v] overlay=W-w-10:10 [out]" \
-map "[out]" \
-map 0:a? \
-c:v libx264 -preset ultrafast -tune zerolatency \
-c:a copy \
-f rtsp "rtsp://localhost:8554/live_output"

Command Breakdown

• -rtsp_transport tcp: Forces FFmpeg to use TCP instead of UDP for the RTSP stream. This prevents packet loss and video corruption.
• -i "rtsp://...": Defines the primary input (Input 0), which is your live camera feed.
• -f image2 -loop 1 -reload 1 -i "weather.png": Defines the secondary input (Input 1).
  • -loop 1 loops the image infinitely.
  • -reload 1 forces FFmpeg to reload the weather.png file from disk every time it loops. This allows an external weather script to overwrite weather.png with new weather graphics in real-time without restarting FFmpeg.
• -filter_complex "[0:v][1:v] overlay=W-w-10:10 [out]": This is the core filter. It takes the video from Input 0 ([0:v]) and overlays Input 1 ([1:v]) on top of it.
  • W-w-10 sets the X-coordinate (horizontal). W is the video width, w is the overlay width, and 10 is a 10-pixel padding from the right edge.
  • 10 sets the Y-coordinate (vertical), placing the overlay 10 pixels from the top edge.
• -map "[out]": Maps the filtered video to the output.
• -map 0:a?: Maps the audio from the camera stream to the output, if audio exists (the ? makes it optional so the command won’t fail if there is no audio).
• -c:v libx264 -preset ultrafast -tune zerolatency: Re-encodes the video stream to H.264. The ultrafast preset and zerolatency tuning minimize processing delay for live streaming.
• -c:a copy: Copies the audio stream directly without re-encoding to save CPU cycles.
• -f rtsp "rtsp://...": Specifies the output format and destination. You can output to an RTSP media server, an RTMP server (like YouTube/Twitch), or save it to a local file by replacing this with a file path like output.mp4.

Positioning the Weather Overlay

You can easily adjust the position of the weather image by changing the overlay coordinates in the -filter_complex flag:

• Top Left: overlay=10:10
• Top Right: overlay=W-w-10:10
• Bottom Left: overlay=10:H-h-10
• Bottom Right: overlay=W-w-10:H-h-10

(Note: W/H refer to the main video dimensions, while w/h refer to the overlay image dimensions).

Managing Real-Time Weather Updates

To keep the weather image current, set up a cron job or a Python script in the background that fetches local weather data from an API, generates a new weather.png graphic, and overwrites the existing file. Because of the -reload 1 flag, FFmpeg will automatically display the updated image on the stream within seconds of the file being replaced.