Group PJMED_RTCP¶

group PJMED_RTCP

RTCP format and session management.

PJMEDIA implements subsets of RTCP specification (RFC 3550) to monitor the quality of the real-time media (audio/video) transmission. In addition to the standard quality monitoring and reporting with RTCP SR and RR types, PJMEDIA’s RTCP implementation is able to report extended statistics for incoming streams, such as packet duplications, reorder, discarded, and loss period (to distinguish between random and burst loss).

The bidirectional media quality statistic is represented with pjmedia_rtcp_stat structure.

When application uses the stream interface (see Streams), application may retrieve the RTCP statistic by calling pjmedia_stream_get_stat() function.

Functions

void pjmedia_rtcp_session_setting_default(pjmedia_rtcp_session_setting *settings)¶

Initialize RTCP session setting.

Parameters: settings – The RTCP session setting to be initialized.

void pjmedia_rtcp_init_stat(pjmedia_rtcp_stat *stat)¶

Initialize bidirectional RTCP statistics.

Parameters: stat – The bidirectional RTCP statistics.

void pjmedia_rtcp_init(pjmedia_rtcp_session *session, char *name, unsigned clock_rate, unsigned samples_per_frame, pj_uint32_t ssrc)¶

Initialize RTCP session.

Parameters

session – The session
name – Optional name to identify the session (for logging purpose).
clock_rate – Codec clock rate in samples per second.
samples_per_frame – Average number of samples per frame.
ssrc – The SSRC used in to identify the session.

void pjmedia_rtcp_init2(pjmedia_rtcp_session *session, const pjmedia_rtcp_session_setting *settings)¶

Initialize RTCP session.

Parameters

session – The session
settings – The RTCP session settings.

pj_status_t pjmedia_rtcp_get_ntp_time(const pjmedia_rtcp_session *sess, pjmedia_rtcp_ntp_rec *ntp)¶

Utility function to retrieve current NTP timestamp.

Parameters

sess – RTCP session.
ntp – NTP record.

Returns

PJ_SUCCESS on success.

void pjmedia_rtcp_fini(pjmedia_rtcp_session *session)¶

Deinitialize RTCP session.

Parameters: session – The session.

void pjmedia_rtcp_rx_rtp(pjmedia_rtcp_session *session, unsigned seq, unsigned ts, unsigned payload)¶

Call this function everytime an RTP packet is received to let the RTCP session do its internal calculations.

Parameters

session – The session.
seq – The RTP packet sequence number, in host byte order.
ts – The RTP packet timestamp, in host byte order.
payload – Size of the payload.

void pjmedia_rtcp_rx_rtp2(pjmedia_rtcp_session *session, unsigned seq, unsigned ts, unsigned payload, pj_bool_t discarded)¶

Call this function everytime an RTP packet is received to let the RTCP session do its internal calculations.

Parameters

session – The session.
seq – The RTP packet sequence number, in host byte order.
ts – The RTP packet timestamp, in host byte order.
payload – Size of the payload.
discarded – Flag to specify whether the packet is discarded.

void pjmedia_rtcp_tx_rtp(pjmedia_rtcp_session *session, unsigned ptsize)¶

Call this function everytime an RTP packet is sent to let the RTCP session do its internal calculations.

Parameters

session – The session.
ptsize – The payload size of the RTP packet (ie packet minus RTP header) in bytes.

void pjmedia_rtcp_rx_rtcp(pjmedia_rtcp_session *session, const void *rtcp_pkt, pj_size_t size)¶

Call this function when an RTCP packet is received from remote peer. This RTCP packet received from remote is used to calculate the end-to- end delay of the network.

Parameters

session – RTCP session.
rtcp_pkt – The received RTCP packet.
size – Size of the incoming packet.

void pjmedia_rtcp_build_rtcp(pjmedia_rtcp_session *session, void **rtcp_pkt, int *len)¶

Build a RTCP packet to be transmitted to remote RTP peer. This will create RTCP Sender Report (SR) or Receiver Report (RR) depending on whether the endpoint has been transmitting RTP since the last interval. Note that this function will reset the interval counters (such as the ones to calculate fraction lost) in the session.

Parameters

session – The RTCP session.
rtcp_pkt – Upon return, it will contain pointer to the RTCP packet, which can be RTCP SR or RR.
len – Upon return, it will indicate the size of the RTCP packet.

pj_status_t pjmedia_rtcp_build_rtcp_sdes(pjmedia_rtcp_session *session, void *buf, pj_size_t *length, const pjmedia_rtcp_sdes *sdes)¶

Build an RTCP SDES (source description) packet. This packet can be appended to other RTCP packets, e.g: RTCP RR/SR, to compose a compound RTCP packet.

Parameters

session – The RTCP session.
buf – The buffer to receive RTCP SDES packet.
length – On input, it will contain the buffer length. On output, it will contain the generated RTCP SDES packet length.
sdes – The source description, see pjmedia_rtcp_sdes.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_rtcp_build_rtcp_bye(pjmedia_rtcp_session *session, void *buf, pj_size_t *length, const pj_str_t *reason)¶

Build an RTCP BYE packet. This packet can be appended to other RTCP packets, e.g: RTCP RR/SR, to compose a compound RTCP packet.

Parameters

session – The RTCP session.
buf – The buffer to receive RTCP BYE packet.
length – On input, it will contain the buffer length. On output, it will contain the generated RTCP BYE packet length.
reason – Optional, the BYE reason.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_rtcp_enable_xr(pjmedia_rtcp_session *session, pj_bool_t enable)¶

Call this function if RTCP XR needs to be enabled/disabled in the RTCP session.

Parameters

session – The RTCP session.
enable – Enable/disable RTCP XR.

Returns

PJ_SUCCESS on success.

struct pjmedia_rtcp_sr¶: #include <rtcp.h>
RTCP sender report.

struct pjmedia_rtcp_rr¶: #include <rtcp.h>
RTCP receiver report.

struct pjmedia_rtcp_common¶: #include <rtcp.h>
RTCP common header.

struct pjmedia_rtcp_sr_pkt¶: #include <rtcp.h>
This structure declares default RTCP packet (SR) that is sent by pjmedia. Incoming RTCP packet may have different format, and must be parsed manually by application.

struct pjmedia_rtcp_rr_pkt¶: #include <rtcp.h>
This structure declares RTCP RR (Receiver Report) packet.

struct pjmedia_rtcp_sdes¶: #include <rtcp.h>
RTCP SDES structure.

struct pjmedia_rtcp_ntp_rec¶: #include <rtcp.h>
NTP time representation.

struct pjmedia_rtcp_stream_stat¶: #include <rtcp.h>
Unidirectional RTP stream statistics.

struct pjmedia_rtcp_stat¶: #include <rtcp.h>
Bidirectional RTP stream statistics.

struct pjmedia_rtcp_session¶: #include <rtcp.h>
RTCP session is used to monitor the RTP session of one endpoint. There should only be one RTCP session for a bidirectional RTP streams.

struct pjmedia_rtcp_session_setting¶: #include <rtcp.h>
RTCP session settings.