RTSP¶

media.ingest.rtsp

Description¶

Sapsan pulls video from IP cameras and other RTSP sources in client (pull) mode.

Configuration¶

Configure the stream through the central API. Stream configuration fragment:

streams:
  - name: cam1
    inputs:
    - rtsp:
        url: rtsp://admin:password@10.0.0.5:554/stream0
        peer_timeout_ms: 5000

Parameters¶

Parameter	Description
`url`	camera address; login and password go in the URL
`peer_timeout_ms`	source inactivity timeout after which the input is considered down
`via_agent`	ingest through a Peeklio agent (`agent://ID`) when the camera is behind NAT — see Peeklio gateway

Authentication¶

Basic and Digest are supported (with automatic fallback to Basic when the camera rejects Digest). Credentials come from the URL and are not sent to the camera in the clear when Digest is used.

Transport options¶

RTP/AVP/TCP (interleaved): media travels inside the RTSP TCP connection.

Supported codecs¶

The source SDP identifies the codec, but ingest also depends on how frames are packaged in RTP. The following formats have dedicated payload handling:

Codec	SDP / RTP name	Ingest conditions
H.264	`H264`	Reassembly of single NAL units, STAP-A aggregation packets and FU-A fragments
HEVC / H.265	`H265`, `HEVC`	Reassembly of single NAL units and FU fragments; AP aggregation packets are not unpacked by this input
AV1	`AV1`	Reassembly of temporal units from RTP packets; configuration comes from the stream sequence header
AAC	`MPEG4-GENERIC`	AAC-hbr packaging with AU headers; codec parameters are carried in the SDP `config`
AAC in LATM	`MP4A-LATM`	`cpresent=0`, with `StreamMuxConfig` in the SDP `config`; LATM packaging is removed during ingest
G.711 A-law	`PCMA`	Including static RTP payload type 8
G.711 μ-law	`PCMU`	Including static RTP payload type 0

Here, MPEG4-GENERIC and MP4A-LATM identify ways of carrying AAC over RTP, rather than two additional audio codecs. There is therefore no separate “MPEG-4 Audio” entry alongside AAC. The payload formats are specified in RFC 3640 and RFC 6416.

Other recognized media tracks use a limited mode: packet payloads are concatenated up to the RTP marker bit, without parsing codec-specific RTP headers. This applies to the following SDP names:

Opus: opus.
JPEG / MJPEG: JPEG.
VP9: VP9.
Linear PCM: L16.
MPEG Audio: MPA and MP3.
Uncompressed video: raw.

Compatibility depends on the source packaging and use of the marker bit. Recognizing an SDP name alone does not guarantee correct ingest of the standard RTP packetization for these formats. RTSP ingest does not recognize VP8, so it is not listed as a supported codec.

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¶

Changing url or via_agent restarts the source; changing only peer_timeout_ms applies in place.

Counters¶

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.

Rtsp¶

Field	Type
`bytes`	`counter`
`reads`	`counter`
`frames`	`counter`
`errors`	`counter`
`warnings`	`counter`
`broken_interleaved`	`counter`
`desync`	`counter`
`memory_bytes`	`gauge`

RtpChannel¶

Field	Type
`channel_id`	`label`
`rtp_packets`	`counter`
`rtcp_packets`	`counter`
`bytes`	`counter`
`frames`	`counter`
`pt_reject_count`	`counter`
`pt_reject_bytes`	`counter`
`ts_goes_backwards`	`counter`
`ts_jump_forward`	`counter`
`ts_stuck`	`counter`
`errors_dts_stuck`	`counter`
`sr_ts_stuck`	`counter`
`ts_stuck_restarts`	`counter`
`resync_sr`	`counter`
`marker_packets_count`	`counter`
`no_marker_mode_flag`	`gauge`
`errors_broken_payload`	`counter`
`errors_lost_packets`	`counter`
`errors_dropped_packets`	`counter`
`errors_late_packets`	`counter`
`errors_incomplete_frames`	`counter`
`nack_count`	`counter`
`onvif_buffer_overflow`	`counter`
`onvif_seq_gap`	`counter`
`onvif_marker_mismatch`	`counter`
`onvif_resync_dropped`	`counter`

Other details¶

Verification¶

Open http://server/streaming/v/cam1/index.m3u8 in a player or request a screenshot at http://server/streaming/live-preview-jpeg/cam1.