How to Use the FFmpeg Movie Filter

The FFmpeg movie source filter allows you to import external audio or video streams directly into an existing filtergraph. This guide provides a straightforward tutorial on how to use the movie filter, explaining its syntax, key parameters, and practical use cases such as overlaying watermarks, creating picture-in-picture effects, and working with audio.

Understanding the Movie Filter Syntax

Unlike standard FFmpeg inputs declared with -i, the movie filter loads a file from within the video (-vf) or audio (-af) filtergraph.

The basic syntax is:

movie=filename [output_label]

To use it in a command, you define the movie source, give its output stream a label, and then link it to another filter (such as overlay).

Practical Examples

1. Overlaying an Image (Watermark)

One of the most common uses of the movie filter is adding a logo or watermark to a video.

ffmpeg -i input.mp4 -vf "movie=logo.png [watermark]; [in][watermark] overlay=10:10 [out]" output.mp4
  • movie=logo.png [watermark]: Loads logo.png and labels the stream as [watermark].
  • [in][watermark] overlay=10:10 [out]: Takes the main input video ([in]) and overlays the [watermark] stream 10 pixels from the top and left.

2. Picture-in-Picture (Video over Video)

You can also overlay a secondary video onto your main video. You can chain filters (like scale) directly to the imported movie stream.

ffmpeg -i main_video.mp4 -vf "movie=pip_video.mp4, scale=320:240 [pip]; [in][pip] overlay=main_w-overlay_w-10:10" output.mp4
  • movie=pip_video.mp4, scale=320:240 [pip]: Loads the secondary video, scales it to 320x240 pixels, and labels it [pip].
  • overlay=main_w-overlay_w-10:10: Positions the scaled video in the top-right corner, 10 pixels from the edge.

3. Seeking to a Specific Time

If you only want to use a specific portion of the imported movie file, you can use the seekpoint parameter.

ffmpeg -i input.mp4 -vf "movie=clip.mp4:seekpoint=30 [clip]; [in][clip] overlay=0:0" output.mp4
  • seekpoint=30: Instructs FFmpeg to start reading the clip.mp4 file from the 30-second mark.

4. Selecting a Specific Stream

If your source file contains multiple video or audio streams, you can specify which stream to import using the stream index (si) parameter.

ffmpeg -i input.mp4 -vf "movie=multi_track.mkv:si=1 [second_track]; [in][second_track] overlay=0:0" output.mp4
  • si=1: Imports the second video stream (index 1) from the container file instead of the default first stream (index 0).

Important Considerations

  • Hardware Acceleration: The movie filter decodes the specified file in software. If you require hardware-accelerated decoding, it is generally better to use multiple -i inputs and -filter_complex instead.
  • Audio and Video Sync: When using the movie filter for video, the audio track of the imported file is ignored unless you specifically configure an audio filtergraph (-af) using the amovie filter to handle the audio stream.