FFmpeg Movie Filter: Read Video Inside Filtergraph

This guide explains how to use the movie source filter in FFmpeg to read external video and audio files directly inside a filtergraph. You will learn the basic syntax, see practical examples of overlaying videos, and understand how to manage streams within complex filter chains.

What is the FFmpeg Movie Filter?

The movie filter is a source filter in FFmpeg that opens a media file and injects its video streams directly into a filtergraph. Unlike the standard -i command-line option which defines inputs globally, the movie filter allows you to load files on the fly within your filter configurations. This is highly useful for complex video editing tasks like picture-in-picture overlays, watermarking, and dynamic transitions.

Basic Syntax

The simplest syntax to load a video file is:

movie=filename

You can specify options such as the stream index, starting time, or format. The general syntax with options is:

movie=filename:seek_point=0:streams=dv+da
  • seek_point (or sp): The point in seconds to start reading from.
  • streams (or s): Specifies which streams to import (e.g., v for video, a for audio, or dv+da for default video and audio).
  • stream_index (or si): Selects a specific stream by index.

Practical Examples

1. Picture-in-Picture (Overlaying a Video)

To overlay an external video file (overlay.mp4) onto a background video (background.mp4) using the video filter (-vf) graph:

ffmpeg -i background.mp4 -vf "movie=overlay.mp4, scale=320:-1 [over]; [in][over] overlay=10:10 [out]" output.mp4
  • movie=overlay.mp4: Loads the external video file.
  • scale=320:-1: Resizes the loaded video.
  • [over]: Labels the scaled video stream.
  • [in][over] overlay: Overlays the scaled movie on top of the main input ([in]).

2. Loading Video in a Complex Filtergraph

If you are generating a blank background using virtual input devices and want to insert a video, you can use -filter_complex:

ffmpeg -f lavfi -i "color=color=black:size=1920x1080:duration=10" -filter_complex "movie=input.mp4 [vid]; [0:v][vid] overlay=x=10:y=10" output.mp4

3. Handling Audio with amovie

The movie filter has an audio-equivalent sibling called amovie. Use this filter when you need to load an audio file inside an audio filtergraph:

ffmpeg -i input.mp4 -af "amovie=background_music.mp3 [bg]; [in][bg] amix=inputs=2" output.mp4

Escaping Special Characters

Because colons (:) are used as option separators in FFmpeg filtergraphs, paths containing drive letters (like C:\video.mp4 on Windows) or special characters must be properly escaped.

To escape a path, wrap the filename in single quotes and escape the colon with a backslash:

movie='C\:/path/to/video.mp4'