rtp_transport.h File Reference

An RTP data transport. More...

#include <smolrtsp/droppable.h>
#include <smolrtsp/transport.h>
#include <stdbool.h>
#include <stdint.h>
#include <datatype99.h>
#include <slice99.h>
#include <smolrtsp/priv/compiler_attrs.h>

Include dependency graph for rtp_transport.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct SmolRTSP_RtpTransport	SmolRTSP_RtpTransport
	An RTP data transport.

Functions
	datatype99 (SmolRTSP_RtpTimestamp,(SmolRTSP_RtpTimestamp_Raw, uint32_t),(SmolRTSP_RtpTimestamp_SysClockUs, uint64_t))
	An RTP timestamp.
SmolRTSP_RtpTransport *	SmolRTSP_RtpTransport_new (SmolRTSP_Transport t, uint8_t payload_ty, uint32_t clock_rate) SMOLRTSP_PRIV_MUST_USE
	Creates a new RTP transport from the underlying level-4 protocol t.
SmolRTSP_RtpTransport *	SmolRTSP_RtpTransport_new_with_ssrc (SmolRTSP_Transport t, uint8_t payload_ty, uint32_t clock_rate, uint32_t ssrc) SMOLRTSP_PRIV_MUST_USE
	Like SmolRTSP_RtpTransport_new but uses an explicit SSRC instead of a randomly generated one.
SmolRTSP_RtpTransport *	SmolRTSP_RtpTransport_new_with_ssrc_ts_base (SmolRTSP_Transport t, uint8_t payload_ty, uint32_t clock_rate, uint32_t ssrc, uint64_t ts_base_us)
	As SmolRTSP_RtpTransport_new_with_ssrc, with the media clock's origin given rather than drawn at random.
int	SmolRTSP_RtpTransport_send_packet (SmolRTSP_RtpTransport *self, SmolRTSP_RtpTimestamp ts, bool marker, U8Slice99 payload_header, U8Slice99 payload) SMOLRTSP_PRIV_MUST_USE
	Sends an RTP packet.
	declImplExtern99 (SmolRTSP_Droppable, SmolRTSP_RtpTransport)
	Implements SmolRTSP_Droppable_IFACE for SmolRTSP_RtpTransport.
bool	SmolRTSP_RtpTransport_is_full (SmolRTSP_RtpTransport *self)
uint32_t	smolrtsp_rtp_ts_from_sys_clock_us (uint64_t time_us, uint32_t clock_rate, uint64_t ts_base_us) SMOLRTSP_PRIV_MUST_USE
	Maps a system-clock instant to the RTP timestamp a transport of clock_rate would put on a packet stamped with it, offset by ts_base_us.
uint32_t	SmolRTSP_RtpTransport_ts_from_sys_clock_us (const SmolRTSP_RtpTransport *self, uint64_t time_us) SMOLRTSP_PRIV_MUST_USE
	As smolrtsp_rtp_ts_from_sys_clock_us, with self's own clock rate and timestamp base.
uint32_t	SmolRTSP_RtpTransport_ssrc (SmolRTSP_RtpTransport *self) SMOLRTSP_PRIV_MUST_USE
	Returns the Synchronization Source (SSRC) identifier used by self on every RTP packet it sends.
uint32_t	SmolRTSP_RtpTransport_pkt_count (SmolRTSP_RtpTransport *self) SMOLRTSP_PRIV_MUST_USE
	Returns the total number of RTP data packets successfully transmitted by self since it was created.
uint32_t	SmolRTSP_RtpTransport_octet_count (SmolRTSP_RtpTransport *self) SMOLRTSP_PRIV_MUST_USE
	Returns the total number of payload octets (i.e., not including the RTP header or padding) successfully transmitted by self since it was created.
uint32_t	SmolRTSP_RtpTransport_last_rtp_ts (SmolRTSP_RtpTransport *self) SMOLRTSP_PRIV_MUST_USE
	Returns the RTP timestamp (already in the wire/clock-rate domain) that was placed in the most recently transmitted RTP packet's header.

Detailed Description

An RTP data transport.

Function Documentation

datatype99()

datatype99	(	SmolRTSP_RtpTimestamp	,
		(SmolRTSP_RtpTimestamp_Raw, uint32_t)	,
		(SmolRTSP_RtpTimestamp_SysClockUs, uint64_t)
	)

An RTP timestamp.

Variants

• Raw – The value to be assigned to SmolRTSP_RtpHeader.timestamp without further conversion.
• SysClockUs – The timestamp value in microseconds derived from a system clock (e.g., clock_gettime). It should be used when a raw timestamp cannot be computed, as typically occurs with real-time video.

See Datatype99 for the macro usage.

declImplExtern99()

declImplExtern99	(	SmolRTSP_Droppable	,
		SmolRTSP_RtpTransport
	)

Implements SmolRTSP_Droppable_IFACE for SmolRTSP_RtpTransport.

See Interface99 for the macro usage.

smolrtsp_rtp_ts_from_sys_clock_us()

uint32_t smolrtsp_rtp_ts_from_sys_clock_us	(	uint64_t	time_us,
		uint32_t	clock_rate,
		uint64_t	ts_base_us
	)

Maps a system-clock instant to the RTP timestamp a transport of clock_rate would put on a packet stamped with it, offset by ts_base_us.

This is the conversion SmolRTSP_RtpTransport_send_packet applies to #SmolRTSP_RtpTimestamp_SysClockUs, exported because a sender has other things to say about the same instant — an RTCP Sender Report's RTP timestamp above all — and they have to land on the identical value. A second copy of the arithmetic drifts from this one the moment either is touched, and a report that disagrees with its own stream by even a few milliseconds is worse than none.

ts_base_us shifts the whole media clock. RFC 3550 §5.1 wants the initial timestamp to be random rather than to expose the sender's clock. The shift is applied in the microsecond domain, before the rate is applied, so that streams given the same base still map wall time through one origin — which is what a sender needs to say anything coherent about two of its own streams at once.

SmolRTSP_RtpTransport_last_rtp_ts()

uint32_t SmolRTSP_RtpTransport_last_rtp_ts

(

SmolRTSP_RtpTransport *

self

)

Returns the RTP timestamp (already in the wire/clock-rate domain) that was placed in the most recently transmitted RTP packet's header.

Zero if no packet has been transmitted yet.

Maps to the "RTP timestamp" field of an RTCP Sender Report (RFC 3550 §6.4.1) — the SR must carry an RTP timestamp in the same domain as the data packets so a receiver can correlate the SR's NTP/RTP pair against frames. Using a separately-computed rtp_ts (e.g. "ticks since SETUP") yields wall-clock estimates that drift by the gap between the two clock origins.

Precondition

self != NULL

SmolRTSP_RtpTransport_new()

SmolRTSP_RtpTransport * SmolRTSP_RtpTransport_new	(	SmolRTSP_Transport	t,
		uint8_t	payload_ty,
		uint32_t	clock_rate
	)

Creates a new RTP transport from the underlying level-4 protocol t.

Parameters

[in]	t	The level-4 protocol (such as TCP or UDP).
[in]	payload_ty	The RTP payload type. The list of payload types is available here: https://en.wikipedia.org/wiki/RTP_payload_formats.
[in]	clock_rate	The RTP clock rate of payload_ty (HZ).

Precondition

t.self && t.vptr

The rand PRNG must be set up via srand.

SmolRTSP_RtpTransport_new_with_ssrc()

SmolRTSP_RtpTransport * SmolRTSP_RtpTransport_new_with_ssrc	(	SmolRTSP_Transport	t,
		uint8_t	payload_ty,
		uint32_t	clock_rate,
		uint32_t	ssrc
	)

Like SmolRTSP_RtpTransport_new but uses an explicit SSRC instead of a randomly generated one.

Useful when the caller needs the RTP stream's SSRC to match an externally-chosen identifier — e.g. an RTCP Sender Report constructed elsewhere, or a multi-stream pipeline that pins SSRCs by configuration.

The plain SmolRTSP_RtpTransport_new is equivalent to calling this with (uint32_t)rand() as the SSRC.

Parameters

[in]	t	The level-4 protocol (such as TCP or UDP).
[in]	payload_ty	The RTP payload type.
[in]	clock_rate	The RTP clock rate of payload_ty (Hz).
[in]	ssrc	The SSRC identifier to use for every RTP packet.

Precondition

t.self && t.vptr

SmolRTSP_RtpTransport_new_with_ssrc_ts_base()

SmolRTSP_RtpTransport * SmolRTSP_RtpTransport_new_with_ssrc_ts_base	(	SmolRTSP_Transport	t,
		uint8_t	payload_ty,
		uint32_t	clock_rate,
		uint32_t	ssrc,
		uint64_t	ts_base_us
	)

As SmolRTSP_RtpTransport_new_with_ssrc, with the media clock's origin given rather than drawn at random.

Every timestamp derived from a system clock is shifted by ts_base_us before it is scaled. A sender that has to relate two of its own streams — an anchor that names an instant in both, a report built from a paired measurement — passes the same base to all of them, and then one wall-clock instant maps through one origin. SmolRTSP_RtpTransport_new and SmolRTSP_RtpTransport_new_with_ssrc draw an independent base each, which is what RFC 3550 §5.1 asks for and what a lone stream wants.

A shared base is not a synchronisation mechanism for the receiver: the two streams still wrap their 32 bits at their own rates, and RFC 3550 gives receivers RTCP sender reports for that job.

Passing a base is also how a caller gets an origin that is unpredictable to somebody watching the stream. The random one the other constructors draw comes from rand(), the same sequence the SSRC does, so it is worth exactly as much as the caller's seeding of it — which for anything the base is meant to conceal is unlikely to be enough.

A #SmolRTSP_RtpTimestamp_Raw timestamp is never shifted: it is by definition the value to put on the wire.

SmolRTSP_RtpTransport_octet_count()

uint32_t SmolRTSP_RtpTransport_octet_count

(

SmolRTSP_RtpTransport *

self

)

Returns the total number of payload octets (i.e., not including the RTP header or padding) successfully transmitted by self since it was created.

Maps to the "sender's octet count" field of an RTCP Sender Report (RFC 3550 §6.4.1).

Precondition

self != NULL

SmolRTSP_RtpTransport_pkt_count()

uint32_t SmolRTSP_RtpTransport_pkt_count

(

SmolRTSP_RtpTransport *

self

)

Returns the total number of RTP data packets successfully transmitted by self since it was created.

Maps to the "sender's packet count" field of an RTCP Sender Report (RFC 3550 §6.4.1).

Precondition

self != NULL

SmolRTSP_RtpTransport_send_packet()

int SmolRTSP_RtpTransport_send_packet	(	SmolRTSP_RtpTransport *	self,
		SmolRTSP_RtpTimestamp	ts,
		bool	marker,
		U8Slice99	payload_header,
		U8Slice99	payload
	)

Sends an RTP packet.

Parameters

[out]	self	The RTP transport for sending this packet.
[in]	ts	The RTP timestamp for this packet.
[in]	marker	The RTP marker flag.
[in]	payload_header	The payload header. Can be U8Slice99_empty().
[in]	payload	The payload data.

Precondition

self != NULL

Returns

-1 if an I/O error occurred and sets errno appropriately, 0 on success.

SmolRTSP_RtpTransport_ssrc()

uint32_t SmolRTSP_RtpTransport_ssrc

(

SmolRTSP_RtpTransport *

self

)

Returns the Synchronization Source (SSRC) identifier used by self on every RTP packet it sends.

Useful when constructing an RTCP Sender Report (see SmolRTSP_RtcpSr in <smolrtsp/types/rtcp.h>) that needs to carry the matching SSRC so receivers can pair the SR with the RTP stream per RFC 3550 §6.4.1.

Precondition

self != NULL

SmolRTSP_RtpTransport_ts_from_sys_clock_us()

uint32_t SmolRTSP_RtpTransport_ts_from_sys_clock_us	(	const SmolRTSP_RtpTransport *	self,
		uint64_t	time_us
	)

As smolrtsp_rtp_ts_from_sys_clock_us, with self's own clock rate and timestamp base.

Precondition

self != NULL