Use FFmpeg amovie Filter to Read Audio

This article explains how to use the amovie source filter in FFmpeg to load and stream audio files directly from within a filtergraph. You will learn the basic syntax of the amovie filter, how to configure its parameters, and how to mix or overlay external audio onto an existing video stream without defining the audio file as a global input.

Understanding the amovie Filter

The amovie filter behaves similarly to the standard movie filter but is specifically tailored for audio streams. Instead of passing an audio file as a global input using -i, amovie acts as a source filter inside a complex filtergraph (-filter_complex). This is highly useful when you need to load audio dynamically or perform advanced mixing, looping, and routing within a single filter chain.

Basic Syntax

The most basic syntax to load an audio file inside a filtergraph is:

amovie=filename.mp3 [out]

This loads filename.mp3 and outputs it to a temporary label named [out], which can then be processed by subsequent filters.

Practical Examples

1. Overlaying Background Music onto a Video

To mix an external background audio file (background.wav) with the original audio of a video (video.mp4), you can use amovie inside -filter_complex alongside the amix filter:

ffmpeg -i video.mp4 -filter_complex "amovie=background.wav [bg]; [0:a][bg] amix=inputs=2:duration=first [aout]" -map 0:v -map "[aout]" output.mp4

In this command: * amovie=background.wav [bg] loads the audio file and labels the stream as [bg]. * [0:a][bg] amix=inputs=2:duration=first [aout] mixes the video’s original audio stream ([0:a]) and the loaded background audio stream ([bg]). The duration=first parameter ensures the output duration matches the original video. * -map 0:v and -map "[aout]" map the original video and the newly mixed audio to the final output file.

2. Looping the Audio File

If your background audio is shorter than your video, you can configure the amovie filter to loop the audio stream indefinitely by using the loop option:

ffmpeg -i video.mp4 -filter_complex "amovie=background.wav:loop=0 [bg]; [0:a][bg] amix=inputs=2:duration=first [aout]" -map 0:v -map "[aout]" output.mp4

Setting loop=0 enables infinite looping, while setting it to a specific integer (e.g., loop=3) loops the audio that specific number of times.

3. Selecting a Specific Audio Stream and Seeking

If the target audio file contains multiple streams, or if you want to start reading the audio from a specific timestamp, you can use the stream_index and seek_point options:

ffmpeg -i video.mp4 -filter_complex "amovie=multi_track.mka:seek_point=30:stream_index=1 [bg]; [0:a][bg] amix=inputs=2:duration=first [aout]" -map 0:v -map "[aout]" output.mp4