FFmpeg Tee Muxer: Handle Connection Failures

When streaming to multiple destinations using FFmpeg's tee muxer, a network drop or connection failure on a single destination typically causes the entire FFmpeg process to terminate. This guide explains how to isolate output errors using the onfail slave option, ensuring that a broken endpoint does not interrupt other healthy streams or local recordings.

The onfail Option

By default, the tee muxer treats every output as critical. If writing to any slave fails, the muxer triggers a fatal error and terminates the command.

To override this, apply the onfail=ignore option to individual outputs within the tee definition. When configured, FFmpeg will log a failure for the broken output, close that specific stream, and continue processing and transmitting data to all remaining targets.

Basic Syntax and Example

Slave outputs in the tee muxer are separated by the pipe (|) character, with slave-specific options enclosed in square brackets ([...]).

Here is an example that streams to two RTMP endpoints and writes to a local file, ensuring that network failures on the remote streams do not kill the local recording:

ffmpeg -re -i input.mp4 \
  -c:v libx264 -c:a aac \
  -flags +global_header \
  -f tee \
  "[f=flv:onfail=ignore]rtmp://live1.example.com/app/stream1|[f=flv:onfail=ignore]rtmp://live2.example.com/app/stream2|[f=segment:segment_time=10]local_%03d.ts"

In this command:

• [f=flv:onfail=ignore] ensures that if either remote RTMP server disconnects or fails to acknowledge packets, FFmpeg drops that output and continues executing.
• The local segment output lacks the onfail=ignore flag, meaning FFmpeg will still exit if a local disk error occurs.

Important Limitations

1. No Automatic Reconnection: Setting onfail=ignore only prevents FFmpeg from crashing. It permanently closes the failed slave; it does not attempt to reconnect to that endpoint later in the session.
2. Escaping Characters: When using complex URLs containing special characters, query parameters, or colons inside slave definitions, enclose the slave string in quotes or escape characters properly according to your shell's requirements.