NDI¶
media.ingest.ndi
Description¶
Sapsan receives video and audio from NDI sources on a local network. Connect directly to a media port or select the exact advertised name from the sender catalog. With decode: false, the server skips SpeedHQ decompression and passes compressed video downstream.
Configuration¶
Configure the stream through the central API. Stream configuration fragment:
streams:
- name: source1
inputs:
- ndi:
url: ndi://192.0.2.10:5961
transport: tcp
decode: false
Parameters¶
| Field | Description |
|---|---|
url |
ndi://host[:port], without path or credentials. |
source |
exact sender catalog name; omit for direct connection. |
transport |
selected transport. |
multicast_interface |
local IPv4 address for multicast membership. |
decode |
decompress SpeedHQ (default true); false preserves compressed frames. |
peer_timeout_ms |
data inactivity timeout. |
Transport options¶
-
TCP —
tcp, default. -
UDP unicast —
udp_unicast. -
UDP multicast —
udp_multicast. -
RUDP/QUIC —
rudp.
Control metadata uses TCP. Selecting UDP does not enable automatic fallback to TCP media.
Supported codecs¶
- SpeedHQ SHQ0
- SpeedHQ SHQ2
- SpeedHQ SHQ4
- SpeedHQ SHQ7
- SpeedHQ SHQ9
- PCM s16
- Float32 audio
SpeedHQ is compressed NDI video. With decode: false, the input passes those frames without decompression; with decode: true, it decodes them into uncompressed 8-bit YUV planes. PCM s16 and Float32 are uncompressed audio sample formats. NDI support does not imply support for H.264/HEVC from NDI HX.
Error handling¶
Input state and failure cause are available in stream statistics. Connection loss or missing frames uses the shared retry and failover mechanisms.
Applying changes¶
Apply changes through the central API. Changing the source address or format reopens capture and may interrupt ingest while connecting. Check input state and arriving frames afterwards.
Counters¶
bytes counts incoming bytes; video_frames and audio_frames count received frames. frames_dropped counts reassembly or queue losses. packets_lost counts lost UDP datagrams; packets_repeated counts repeats; fec_packets_recovered counts FEC recovery. quic_stream_retransmits and quic_stream_retransmit_bytes describe local outgoing QUIC retransmission, not incoming video loss.
The tables give exact protocol statistics field names, including event counters and current-value gauges. Zero fields may be omitted. API and Prometheus expose different projections; the full list is not necessarily present in one Admin API response. Detailed statistics depend on the counter license.
Common input totals: bytes, frames, errors, warnings. They aggregate protocol data and must not be added to protocol counters again.
Ndi¶
| Field | Type |
|---|---|
memory_bytes |
gauge |
bytes |
counter |
video_frames |
counter |
audio_frames |
counter |
metadata_frames |
counter |
errors_video_decoder |
counter |
errors_audio_decoder |
counter |
frames_dropped |
counter |
datagrams |
counter |
packets_lost |
counter |
packets_repeated |
counter |
repeated_bytes |
counter |
fec_packets_recovered |
counter |
fec_bytes |
counter |
quic_packets_lost |
counter |
quic_stream_retransmits |
counter |
quic_stream_retransmit_bytes |
counter |
quic_receive_queue_bytes |
gauge |
Other details¶
With decode: false, the next consumer must accept compressed SpeedHQ. Add transcoding to player codecs for HLS output. decode: true expands video into raw frames and increases CPU and memory load.