Skip to content

Source failover

A stream can have multiple sources. Sapsan monitors the active source, automatically switches to the next one when it degrades, and switches back when the primary recovers. This logic is called LSI (Live Source Input).

Multiple inputs

Inputs are listed in priority order — the first one is the primary:

streams:
  tv1:
    inputs:
    - udp:
        host: 239.0.0.1
        port: 5000
    - tshttp:
        url: http://backup-origin.example.com/tv1/mpegts

How switching works

Key properties of the algorithm that matter on air:

  • A source becomes active only when ready: it must deliver stream parameters (MediaInfo) and the first keyframe. Until then viewers keep receiving the current source.
  • Failback without a black screen: a recovered higher-priority input is probed in the background, and the switch happens only once it has delivered a keyframe.
  • A failed input reconnects with growing delays (reconnect_initial_delay → reconnect_delay_step → reconnect_max_delay); when all inputs are exhausted, rotation wraps back to the first.
  • A source whose bitrate exceeds max_bitrate is forcibly stopped.
  • Separate no-video and no-audio timeouts: lost audio with live video also counts as degradation.

Switching policy

The lsi section sets the stream-wide policy; source_options on a specific input overrides it:

streams:
  tv1:
    inputs:
    - udp: {host: 239.0.0.1, port: 5000}
    - udp:
        host: 239.0.0.2
        port: 5000
      source_options:
        source_timeout: 10
    lsi:
      source_timeout: 5
      video_timeout: 3
      audio_timeout: 3

Timeouts are in seconds. Main parameters (lsi and/or source_options):

Parameter Description
source_timeout, video_timeout, audio_timeout no-data/no-video/no-audio timeouts
max_bitrate source bitrate limit
reconnect_initial_delay, reconnect_delay_step, reconnect_max_delay reconnection policy
retry_limit, max_retry_timeout retry limits
recheck_secondary_inputs_interval how often to check whether a higher-priority input came back
allow_if, deny_if (source_options only) enable/disable an input via an external flag file

allow_if/deny_if let you control inputs externally without editing the config: an input is used only while the flag file allows it.

Fallback file (backup)

If all sources are down, a file is shown instead of a black screen (see how to prepare the file):

streams:
  tv1:
    inputs:
    - udp: {host: 239.0.0.1, port: 5000}
    lsi:
      backup:
        file: /storage/technical-difficulties.mp4
        timeout: 5

The fallback kicks in timeout seconds after the inputs fail (immediately if there are no inputs at all) and has its own audio_timeout/video_timeout.

Observability

Per stream: time on the primary and backup inputs, time with no data, retry counts, backup input validity, and a parameter divergence detector — if a backup input delivers different video parameters (making a seamless switch impossible), you see it in advance, before the incident. Per input: open/connect/start times and the last error. See monitoring.

Next steps