FFmpeg Overlay: Adding Looping Videos or Animated Materials

In video production, we often need to overlay a looping video or animation onto the main video, such as adding looping logo animations, watermark effects, decorative elements, or special effects. FFmpeg, as a powerful video processing tool, can achieve this functionality through filter combinations, but correctly handling the timestamps of looping videos is the key.

This article will provide a detailed explanation of how to correctly implement video overlay looping effects using FFmpeg's movie filter and setpts parameter, suitable for various video creation and post-production scenarios.

Basic Principles

The key to implementing looping video overlays in FFmpeg lies in:

Using the movie filter to load overlay materials
Correctly setting timestamps to support looping
Using the overlay filter to overlay the materials onto the main video

The most important technique: Using setpts=N/FRAME_RATE/TB instead of the common setpts=PTS-STARTPTS to handle the timestamps of looping videos.

Basic Command Example

ffmpeg -i "main_video.mp4" -af "pan=stereo|c0=FL|c1=FR,volume=1.5" \
    -vf "movie=overlay_video.mp4:loop=0,setpts=N/FRAME_RATE/TB,hue=s=0[bg];[in]scale=iw/2:-1,pad=iw+20:ih+20:10:10:color=yellow[m]; [bg][m]overlay=shortest=1:x=(W-w)/2:y=(H-h)/2[out]" \
    -c:v libx264 output_video.mp4

Parameter Explanation

movie Filter Parameters

movie=overlay_video.mp4: Specifies the video file to overlay
:loop=0: Sets the loop mode, 0 means infinite loop
Other optional values:
- 1: Play once (no loop)
- n: Loop n times

setpts Parameter

setpts=N/FRAME_RATE/TB: This is the key to correctly handling timestamps for looping videos
- N: Current frame number
- FRAME_RATE: Frame rate
- TB: Timebase unit

Important note: Many tutorials use setpts=PTS-STARTPTS, but this method causes timestamp errors when looping videos, preventing proper looping.

overlay Parameters

shortest=1: Stop processing when the shortest input ends (prevents infinite looping)
x=(W-w)/2: Horizontally center the overlay
y=(H-h)/2: Vertically center the overlay

Practical Examples

1. Adding a Looping Logo Animation Watermark

ffmpeg -i main_video.mp4 \
    -vf "movie=logo_animation.webm:loop=0,setpts=N/FRAME_RATE/TB[logo];[in][logo]overlay=shortest=1:x=W-w-10:y=10[out]" \
    -c:v libx264 -c:a copy output_watermarked_video.mp4

This command adds a looping logo animation to the top right corner of the main video.

2. Adding a Looping Background Effect

ffmpeg -i foreground_video.mp4 \
    -vf "movie=background_animation.mp4:loop=0,setpts=N/FRAME_RATE/TB[bg];[bg][in]overlay=shortest=1:x=(W-w)/2:y=(H-h)/2[out]" \
    -c:v libx264 -c:a copy output_video.mp4

This command overlays the foreground video on top of a looping background animation.

3. Adding Multiple Looping Elements

ffmpeg -i main_video.mp4 \
    -vf "movie=decoration1.webm:loop=0,setpts=N/FRAME_RATE/TB[d1]; \
         movie=decoration2.webm:loop=0,setpts=N/FRAME_RATE/TB[d2]; \
         [in][d1]overlay=shortest=1:x=10:y=10[temp]; \
         [temp][d2]overlay=shortest=1:x=W-w-10:y=H-h-10[out]" \
    -c:v libx264 -c:a copy output_video.mp4

This command simultaneously adds two looping decorative elements, positioned in the top left and bottom right corners.

Advanced Applications: Adjusting Overlay Materials

Adjusting Transparency

ffmpeg -i main_video.mp4 \
    -vf "movie=overlay_video.mp4:loop=0,setpts=N/FRAME_RATE/TB,format=rgba,colorchannelmixer=aa=0.5[overlay]; \
         [in][overlay]overlay=shortest=1:x=10:y=10[out]" \
    -c:v libx264 -c:a copy output_video.mp4

This command sets the transparency of the overlay video to 50%.

Adjusting Size and Position

ffmpeg -i main_video.mp4 \
    -vf "movie=overlay_video.mp4:loop=0,setpts=N/FRAME_RATE/TB,scale=320:-1[overlay]; \
         [in][overlay]overlay=shortest=1:x=W-w-20:y=H-h-20[out]" \
    -c:v libx264 -c:a copy output_video.mp4

This command scales the overlay video to a width of 320 pixels and positions it in the bottom right corner.

Common Issues and Solutions

Issue 1: Video Processing Never Ends

Solution: Make sure to add the shortest=1 parameter to the overlay filter, so that processing ends when the shortest input stream ends.

Issue 2: Looping Video Not Synchronized or Stuttering

Solution: Try using setpts=N/(FRAME_RATE*TB) instead of setpts=N/FRAME_RATE/TB, or adjust the frame rate to match both videos.

Issue 3: Problems When Overlaying GIF Animations

Solution: For GIF files, you can use the following command:

ffmpeg -i main_video.mp4 \
    -ignore_loop -1 -i animation.gif \
    -filter_complex "[1:v]setpts=N/FRAME_RATE/TB[gif];[0:v][gif]overlay=shortest=1:x=10:y=10[out]" \
    -map "[out]" -map 0:a -c:v libx264 -c:a copy output_video.mp4

Controlling GIF Loop Count with FFmpeg

References: