Exit on network or other failure when recording an RTSP stream

How do I prevent FFmpeg from exiting prematurely when recording an RTSP stream due to network instability?

To prevent FFmpeg from exiting on network failure, you must increase the input timeout and enable retry mechanisms. Use the -rtsp_transport tcp flag to switch to TCP for reliable delivery, set -reconnect 1 to automatically attempt reconnection after a drop, and configure -timeout or -stimeout with appropriate values to handle temporary latency without aborting the process.

Recording an RTSP (Real Time Streaming Protocol) stream using FFmpeg is a common task for surveillance, broadcasting, and media archiving. However, network fluctuations are inevitable, and by default, FFmpeg may exit immediately if it encounters a brief interruption or packet loss. This behavior disrupts long-term recordings and requires manual intervention. The solution lies in configuring specific flags that instruct FFmpeg to tolerate transient errors and recover automatically. By adjusting transport protocols and timeout settings, you can ensure a robust recording pipeline that survives minor network hiccups.

Switching to TCP Transport

RTSP defaults to UDP (User Datagram Protocol) for transporting media data because it is faster and has lower overhead. However, UDP does not guarantee delivery; if packets are lost due to congestion, the stream quality degrades, or the connection drops entirely. Switching to TCP forces FFmpeg to use a connection-oriented protocol that ensures all data packets arrive in order and without loss. While this introduces slightly more latency, it significantly improves stability over unreliable networks. To enforce TCP transport, add the -rtsp_transport tcp option to your FFmpeg command. This should be placed before the input URL. For example:

ffmpeg -rtsp_transport tcp -i rtsp://user:pass@ip_address/stream -c copy output.mp4

This simple change often resolves immediate disconnection issues caused by UDP packet drops. If you are experiencing issues with other streaming tools, such as those mentioned in our guide on Streaming RTSP URL Video Using Node.js: Troubleshooting FFmpeg Errors, ensuring the underlying transport layer is stable is often the first step in debugging.

Enabling Automatic Reconnection

Even with TCP, network interfaces can go down temporarily, or the server might restart. Instead of crashing, FFmpeg can be configured to wait and retry the connection. The -reconnect flag enables this behavior. Setting it to 1 tells FFmpeg to automatically reconnect if the stream breaks. You can also control how long FFmpeg waits between retries and the maximum delay using additional parameters. The syntax is -reconnect_delay_max <seconds>. For instance, to allow FFmpeg to try reconnecting every second for up to 60 seconds, you would use:

ffmpeg -reconnect 1 -reconnect_delay_max 60 -i rtsp://... output.mp4

This feature is crucial for unattended recordings where human intervention is not possible. It transforms a fragile script into a resilient service capable of handling intermittent connectivity issues.

Configuring Timeout Settings

Timeouts define how long FFmpeg waits for data before giving up. There are two main types of timeouts relevant here: -timeout and -stimeout. The -timeout flag sets the maximum time, in microseconds, that FFmpeg will wait for input from the network before exiting. The default value is often quite low (5,000,000 microseconds or 5 seconds). If the network lags for more than five seconds, FFmpeg assumes the stream is dead and exits. Increasing this value prevents premature termination during brief network stalls. The -stimeout flag specifically controls the socket timeout for establishing the initial connection. If you are connecting to a remote server across a wide area network, a longer socket timeout may be necessary to account for high latency during the handshake phase. For a robust setup, consider setting these values to higher thresholds, such as 30 seconds (30,000,000 microseconds):

ffmpeg -timeout 30000000 -stimeout 30000000 -i rtsp://... output.mp4

Be cautious not to set these too high, as you may want FFmpeg to exit if the stream is genuinely offline rather than just slow. Balancing these values depends on your specific network environment.

Handling Packet Loss and Buffering

In some cases, simply increasing timeouts is not enough. Network jitter can cause buffers to overflow or underflow, leading to decoding errors that crash the encoder. Adding buffer options can help mitigate this. The -buffer_size flag allows you to specify the size of the input buffer in bytes. A larger buffer can absorb bursts of network traffic better. Additionally, if you are muxing audio and video, timing issues can arise. As discussed in Muxing AC3 with x264, timing & seeking challenges, proper synchronization is key. When recording RTSP streams, ensure that the container format supports the timestamps correctly. Using -fflags +genpts can help generate missing presentation timestamps, which might prevent errors related to non-monotonous DTS values, similar to issues found when transcoding MP4 to RTSP as seen in FFmpeg transcode MP4 to RTSP result in Non-monotonous DTS.

Testing Your Configuration

Before deploying to production, test your configuration with simulated network interruptions. Tools like tc (traffic control) on Linux can simulate packet loss and latency. Monitor the FFmpeg logs for any "Connection reset" or "Timeout" messages. If the stream recovers smoothly after the simulated disruption, your configuration is likely solid. Always verify that the output file remains valid and playable after a recovery event.

Frequently Asked Questions

What happens if the RTSP server goes down permanently?

If the server goes down permanently, FFmpeg will continue to retry until it hits the -reconnect_delay_max limit. Once that limit is reached, FFmpeg will exit with an error code. You should monitor the exit status of your FFmpeg process to trigger alerts or alternative actions if the stream fails completely.

Can I use UDP instead of TCP for lower latency?

Yes, but UDP is much less stable. If you choose UDP, you must rely heavily on -reconnect and increased timeouts to handle packet loss. However, UDP will not recover lost packets, so you may experience visual artifacts or gaps in the recording even if the connection stays alive.

Why does my recorded file have black frames after a network drop?

Black frames often occur because the decoder loses synchronization with the stream headers. Using -fflags +genpts and ensuring the container format writes correct timestamps can minimize this. Additionally, switching to TCP helps maintain stream integrity, reducing the likelihood of such desynchronization events.

Is there a way to record only the video and not the audio?

Yes, you can disable audio recording by adding -an to your command line arguments. This reduces bandwidth usage and storage requirements, which can indirectly improve stability on constrained networks by lowering the load on the network interface.

How do I log FFmpeg errors to a file for troubleshooting?

You can redirect FFmpeg's standard error output to a file using shell redirection. For example, appending 2>&1 > ffmpeg.log to your command will save both standard output and error messages to ffmpeg.log. This is invaluable for diagnosing why a stream failed after the fact.