SDI source monitoring¶

media.probe.sdi

Sapsan monitors an SDI source during capture: it checks signal state, frame sequence, and timecode, and counts errors reported by the card driver. This helps distinguish source and cable problems, video standard changes, and losses between the card and the media pipeline.

SDI ingest covers connection and capture. This article focuses on diagnosing an input that is already configured. Analysis runs within the active pipeline; it does not require a separate process opening the same card port.

What is checked on every frame¶

The driver supplies Sapsan with a video frame and associated data. The input compares them with the capture state:

Line state — whether a signal is present and matches the capture format. The current state is checked, so a missed signal recovery notification should not leave the input in its previous state.
Frame sequence — gaps in the card's buffer sequence numbers identify frames lost before Sapsan receives them. The gap is also reflected in the video and audio timelines.
SDI line CRC — errors from frame metadata are accumulated if the card and driver provide this check.
ATC timecode — when timecode is enabled, the input checks whether the time of day is usable and whether its progression agrees with the frame sequence.
Ancillary data — recognized VANC packets and errors processing supported data are counted. Extraction capabilities are described under SDI ingest.

Receiving buffers from the card does not by itself prove that a usable signal is present. After a cable disconnects, the driver may continue supplying frames with an error flag. Sapsan accounts for this flag so that an input does not appear healthy solely because its frame count is increasing.

Line state and recovery¶

The current V4L2 input reports three states:

ok — the received frame has no line error flag. This does not assess picture or audio content.
no_signal — the driver reports that no signal is present.
wrong_standard — a signal is present, but the frame is flagged as erroneous for the current capture format.

To tolerate brief changes, the input waits for 500 ms of continuous error state before it stops passing frames to the media pipeline. If wrong_standard persists, capture reopens after 2 seconds. A driver signal change event may trigger an earlier restart when the standard is detected automatically.

If no frames arrive, capture restarts according to peer_timeout_ms. With automatic format detection, the input reports no_signal while waiting for a signal; if no signal appears within this timeout, the open attempt fails. With an explicit standard, this waiting stage is skipped. The default peer_timeout_ms is 30 000 ms. The general LSI mechanism manages retries and failover; its switching time is not the same as the 500 ms delay.

Standard changes and capture restarts are counted separately from source failures. An increase in restarts after switching a signal on a router requires a different interpretation from restarts caused by missing frames.

Timeline and timecode checks¶

The video timeline is derived from the frame sequence and the format's exact fractional frame rate. The audio timeline accounts for the number of audio samples. With timecode enabled, the input analyzes ATC and can anchor both timelines to source time. The date comes from the server clock because ATC contains time of day.

Configuration example through the central API:

streams:
  - name: studio
    inputs:
      - sdi:
          device: /dev/v4l/by-path/pci-0000:5e:00.0-video-index0
          timecode: true
          peer_timeout_ms: 30000

timecode is enabled by default. When false, capture continues, but ATC does not control the timeline and these timecode checks are not performed.

Anchoring requires a usable timecode:

Time of day — the difference from the server clock must not exceed 30 seconds. Synchronize the server clock; a counter starting at the beginning of the material or a timecode in another time zone may be rejected.
Fractional frame rate — 29.97 and 59.94 require drop-frame; timecode at 23.98 is not used for this anchoring.
Sequence — timecode must progress consistently with the frames. An isolated deviation does not change the timeline; a stable new offset over approximately one second of frames triggers re-anchoring.

Before the first successful anchor, a timeline without ATC is used, with subsequent alignment to the server clock. After anchoring, a missing timecode or a failed timecode check preserves the previous offset. Re-anchoring signals a timeline discontinuity to the media pipeline so that subsequent packaging accounts for the time change.

Timecode counter	Meaning
`timecode_missing`	Frames without ATC after successful anchoring. Before anchoring, a persistent absence of ATC does not increase this counter.
`timecode_rejected`	Unusable or inconsistent timecode: a corrupt value, unsuitable frame rate mode, frozen timecode, or unstable deviation.
`timecode_untrusted`	Timecode outside the trust window relative to the server clock.
`timecode_jumps`	Re-anchoring to a stable new offset.

API statistics¶

Request detailed statistics from the streamer capturing SDI:

curl -fsS -u "$ADMIN_USER:$ADMIN_PASSWORD" \
  http://streamer:8080/streamer/api-v4/streams/stats/studio \
  | jq '{name, inputs: [(.inputs // [])[] | select(.protocol == "sdi")], input}'

inputs is the list of sources. The following information is available for an SDI source:

Field	How to interpret it
`current`, `status`, `failure_cause`, `error`	Whether the source is selected, its overall state, and the failure cause.
`sdi_line_state`	Line state as a string; `ok` may be omitted from JSON.
`sdi_producer_restarts_total`	Cumulative capture restarts. The historical name `producer` does not imply a separate capture process.
`sdi_boundary_loss_total`	Losses detected from gaps in the card's buffer sequence numbers.
`sdi_capture`	Capture format accepted by the driver, before transcoding.

sdi_capture contains frame dimensions, the numeric FourCC pixel_format, bytes per line in stride, and the full-frame rate fps_num / fps_den. Optional video_bytes_per_second estimates the minimum DMA video data rate in bytes per second, excluding audio and PCIe overhead.

In the stream-level input section, sdi_datagrams_total counts frames received from the device. Despite its name, it is not a network datagram count. Zero-valued fields may be omitted. A missing statistics section must not be interpreted as a completed measurement with no errors.

Compact central statistics include source states but do not replace the streamer's detailed response. CRC and all timecode counters are not exposed in the API as a single input.sdi object; use metric export for them.

Metrics and timing measurements¶

The streamer's metric export is available at /streamer/api-v4/live-metrics with authentication. Export availability and detail depend on the counter license.

curl -fsS -u "$ADMIN_USER:$ADMIN_PASSWORD" \
  http://streamer:8080/streamer/api-v4/live-metrics \
  | rg '^stream_input_sdi_.*stream="studio"'

Prometheus series	Meaning
`stream_input_sdi_line_state`	Current state: `0` — `ok`, `1` — `no_signal`, `2` — `wrong_standard`.
`stream_input_sdi_datagrams_total`	Frames received from the device.
`stream_input_sdi_boundary_loss_total`	Frames lost according to buffer sequence numbers.
`stream_input_sdi_crc_errors_total`	Line CRC errors reported by the card.
`stream_input_sdi_producer_restarts_total`	All capture restarts.
`stream_input_sdi_producer_restarts_wrong_standard_total`	Restarts caused by the standard or a signal change event.
`stream_input_sdi_producer_restarts_silence_total`	Restarts caused by missing frames from the device.
`stream_input_sdi_timecode_missing_total`	ATC missing after anchoring.
`stream_input_sdi_timecode_rejected_total`	Rejected ATC.
`stream_input_sdi_timecode_untrusted_total`	ATC outside the clock trust window.
`stream_input_sdi_timecode_jumps_total`	Timeline re-anchoring based on ATC.

The shared line state vocabulary also includes late, duplicate, and invalid; the current V4L2 input does not detect these as three distinct signal defects. For some counters, a series appears only after an event, so a missing series does not confirm that the card supports the check.

The general source timing monitor also compares media arrival time with DTS before timestamp alignment. Stream statistics include source_timing_offset_ms and source_timing_jitter_ms, along with the bounds source_timing_offset_min_ms / source_timing_offset_max_ms. source_timing_offset_ms shows the current offset; jitter and offset bounds refer to the completed one-minute window. source_timing_input and source_timing_window_started_at identify the source and window start.

These measurements help reveal changes in lag and uneven media arrival in the software pipeline. They do not measure electrical SDI jitter. Checking every frame also does not mean that the API exports the history of every timestamp: it exposes state and aggregated results.

Interpreting results¶

Observation	What to check
`no_signal`	Source, cable, routing, and selected card input.
Standard-related restarts increase	Source switching, automatically detected format, and explicit `standard`.
Restarts due to missing frames increase	Driver and capture operation; correlate events with server logs.
`boundary_loss` increases	Losses detected through buffer sequence numbers: server load and the pipeline's ability to receive frames from the card in time. The counter alone does not identify the cause.
`crc_errors` increases	Input signal integrity as reported by the card. Zero does not confirm an error-free signal if the card does not provide CRC.
`timecode_untrusted` increases	Server clock synchronization and the purpose of the source timecode.
`timecode_rejected` or `timecode_jumps` increases	ATC generator configuration and stability, and source switching.

Compare counter increases over an interval, not just cumulative values. Correlate line state with actual frame arrival: zero losses on a stopped input do not mean the signal is healthy.

Diagnostics depend on the data provided by the driver. These indicators do not measure electrical SDI jitter, amplitude, or an eye diagram. Such measurements require a physical signal analyzer. ATC monitoring also does not check the picture for frozen frames or audio for silence.

For high-speed capture, separately account for 12G-SDI server and memory requirements. Assess the capture format and card-side losses before transcoding: lowering the output bitrate does not reduce the volume of incoming uncompressed frames.