How to Configure FFmpeg SRT Keep-Alive Packets

This article explains how to configure keep-alive behavior and manage connection timeouts when streaming via Secure Reliable Transport (SRT) using FFmpeg. You will learn how SRT handles heartbeat packets natively over UDP, which FFmpeg URL parameters govern connection persistence, and how to structure your streaming commands to prevent drops across NATs and stateful firewalls.

How SRT Handles Keep-Alive Packets

Unlike TCP, which relies on standard TCP keep-alive probes, SRT operates over UDP and includes an integrated control messaging layer. When an SRT connection is established, the sender and receiver continuously exchange control signals (such as ACKs, NAKs, and heartbeat packets). If no media payload is currently being transmitted, SRT automatically transmits internal control packets at regular intervals (typically every 1,000 milliseconds) to verify the link and keep stateful NAT firewalls from terminating the UDP mapping.

In FFmpeg, these settings are not passed via generic -keepalive flags; instead, they are configured as query parameters appended directly to the SRT destination URL.

Key Parameters for SRT Keep-Alive and Connection Management

When sending an SRT stream with FFmpeg, use the following parameters to adjust keep-alive thresholds, timeouts, and idle peer detection:

  • peeridle: Sets the peer idle timeout in milliseconds. If the endpoint receives no packets—neither media data nor SRT control/keep-alive packets—for this duration, the connection is marked as broken and closed. The default is 5000 (5 seconds). Setting this to a higher value (such as 10000 or 15000) prevents premature disconnects during intermittent network stalls.
  • conntimeo: Sets the connection timeout in milliseconds for the initial handshake before aborting. The default is typically 3000 ms for caller mode.
  • timeout: Sets the I/O operation timeout in microseconds. If data reading or writing blocks for longer than this duration, FFmpeg will exit.

Configuring the FFmpeg Command

To apply keep-alive and idle-detection settings, append the parameters as standard query parameters to the SRT URI. Always wrap the entire output URL in quotes to prevent shell interpretation of the & character.

Caller Mode (Broadcasting to a Remote Ingest)

Use this configuration when pushing a stream to a remote server or media gateway:

ffmpeg -re -i input.mp4 -c:v libx264 -preset veryfast -c:a aac -f mpegts \
  "srt://target-server.com:9000?mode=caller&peeridle=10000&conntimeo=5000"

In this command:

  • mode=caller directs FFmpeg to initiate the connection.
  • peeridle=10000 instructs SRT to wait 10 seconds without any inbound data or keep-alive packets before declaring the peer dead.
  • conntimeo=5000 gives the connection handshake 5 seconds to complete.

Listener Mode (Waiting for an Inbound Connection)

If FFmpeg is running as an ingest listener waiting for an incoming SRT feed, set the mode to listener:

ffmpeg -i "srt://0.0.0.0:9000?mode=listener&peeridle=10000" \
  -c copy -f mpegts output.ts

Keeping State Across Aggressive Firewalls

While SRT sends automated heartbeat packets when idle, some aggressive network firewalls or cloud NAT gateways close inactive UDP states rapidly if bandwidth drops to zero. If you experience disconnections during periods where no video is being encoded:

  1. Lower latency buffers if necessary: Match latency values across sender and receiver to avoid buffer underruns misinterpreted as idle disconnects (e.g., &latency=200000 for 200ms).
  2. Ensure uninterrupted transport: Use constant bitrate (CBR) encoding with fixed GOP structures (-g 60 -keyint_min 60) to maintain a steady flow of payload packets alongside SRT's internal control packets.