How to Use FFmpeg streamselect Filter

This article provides a practical guide on how to use the FFmpeg streamselect filter to dynamically switch between multiple input video streams. You will learn the fundamental syntax of the filter, how to execute scheduled stream switches at specific timestamps using the sendcmd filter, and how to handle live, interactive switching.

Understanding the streamselect Filter

The streamselect filter takes a specified number of inputs and routes one or more of them to the output. By default, it outputs the stream index specified by the map parameter.

The basic syntax is:

streamselect=inputs=N:map=X

In a static configuration, the following command routes only the second input (1) to the output:

ffmpeg -i input0.mp4 -i input1.mp4 -filter_complex "[0:v][1:v]streamselect=inputs=2:map=1[out]" -map "[out]" output.mp4

Dynamic Switching Using sendcmd

To switch streams dynamically during processing, you must pair streamselect with the sendcmd filter. The sendcmd filter sends commands to other filters at designated timestamps.

Method 1: Using an Inline Command

For simple, predetermined switches, you can pass the switching command directly inside the filtergraph:

ffmpeg -i input0.mp4 -i input1.mp4 -filter_complex \
"[0:v][1:v]sendcmd=c='5.0 streamselect map 1; 10.0 streamselect map 0',streamselect=inputs=2:map=0[out]" \
-map "[out]" output.mp4

How it works: 1. map=0: The video starts by playing input0.mp4. 2. 5.0 streamselect map 1: At the 5-second mark, the filter switches the output to the second input (input1.mp4). 3. 10.0 streamselect map 0: At the 10-second mark, the filter switches back to input0.mp4.

Method 2: Using a Command File

For complex scenarios with multiple switch points, define the schedule in a separate text file (e.g., commands.txt):

5.0 streamselect map 1;
10.0 streamselect map 0;
15.0 streamselect map 1;

Run the FFmpeg command pointing to this file:

ffmpeg -i input0.mp4 -i input1.mp4 -filter_complex \
"[0:v][1:v]sendcmd=f=commands.txt,streamselect=inputs=2:map=0[out]" \
-map "[out]" output.mp4

Dynamic Switching in Real-Time (Live Streams)

For live broadcasts where you need to switch streams interactively, you can control the streamselect filter using the ZMQ (ZeroMQ) filter. ZMQ allows you to send control messages to FFmpeg during runtime over a network socket.

  1. Start FFmpeg with the ZMQ filter:
ffmpeg -i input0.mp4 -i input1.mp4 -filter_complex \
"[0:v][1:v]zmq,streamselect=inputs=2:map=0[out]" \
-map "[out]" -f mpegts udp://localhost:1234
  1. Send a switch command from your terminal or application: Using a ZMQ sending utility (like tools/zmqsend provided in the FFmpeg source code), you can switch the stream instantly:
echo "Parsed_streamselect_1 map 1" | zmqsend

Technical Considerations