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.

void pjmedia_rtcp_update(pjmedia_rtcp_session *session, const pjmedia_rtcp_session_setting *settings)

Update RTCP session with the new settings. Note that any setting field that has a value of zero will not be updated.

Parameters:

  • session – The session

  • settings – The new RTCP session settings. Set a field to zero to leave it unchanged.

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.

Public Members

pj_uint32_t ntp_sec

NTP time, seconds part.

pj_uint32_t ntp_frac

NTP time, fractions part.

pj_uint32_t rtp_ts

RTP timestamp.

pj_uint32_t sender_pcount

Sender packet cound.

pj_uint32_t sender_bcount

Sender octet/bytes count.

struct pjmedia_rtcp_rr
#include <rtcp.h>

RTCP receiver report.

Public Members

pj_uint32_t ssrc

SSRC identification.

pj_uint32_t fract_lost

Fraction lost.

pj_uint32_t total_lost_2

Total lost, bit 0-7.

pj_uint32_t total_lost_1

Total lost, bit 8-15.

pj_uint32_t total_lost_0

Total lost, bit 16-23.

pj_uint32_t last_seq

Last sequence number.

pj_uint32_t jitter

Jitter.

pj_uint32_t lsr

Last SR.

pj_uint32_t dlsr

Delay since last SR.

struct pjmedia_rtcp_common
#include <rtcp.h>

RTCP common header.

Public Members

unsigned count

varies by payload type

unsigned p

padding flag

unsigned version

packet type

unsigned pt

payload type

unsigned length

packet length

pj_uint32_t ssrc

SSRC identification

struct pjmedia_rtcp_fb_common
#include <rtcp.h>

RTCP feedback common header.

Public Members

pj_uint32_t ssrc_src

SSRC media source

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.

Public Members

pjmedia_rtcp_common common

Common header.

pjmedia_rtcp_sr sr

Sender report.

pjmedia_rtcp_rr rr

variable-length list

struct pjmedia_rtcp_rr_pkt
#include <rtcp.h>

This structure declares RTCP RR (Receiver Report) packet.

Public Members

pjmedia_rtcp_common common

Common header.

pjmedia_rtcp_rr rr

variable-length list

struct pjmedia_rtcp_sdes
#include <rtcp.h>

RTCP SDES structure.

Public Members

pj_str_t cname

RTCP SDES type CNAME.

pj_str_t name

RTCP SDES type NAME.

pj_str_t email

RTCP SDES type EMAIL.

pj_str_t phone

RTCP SDES type PHONE.

pj_str_t loc

RTCP SDES type LOC.

pj_str_t tool

RTCP SDES type TOOL.

pj_str_t note

RTCP SDES type NOTE.

struct pjmedia_rtcp_ntp_rec
#include <rtcp.h>

NTP time representation.

Public Members

pj_uint32_t hi

High order 32-bit part.

pj_uint32_t lo

Lo order 32-bit part.

struct pjmedia_rtcp_stream_stat
#include <rtcp.h>

Unidirectional RTP stream statistics.

Public Members

pj_time_val update

Time of last update.

unsigned update_cnt

Number of updates (to calculate avg)

pj_uint32_t pkt

Total number of packets

pj_uint32_t bytes

Total number of payload/bytes

unsigned discard

Total number of discarded packets.

unsigned loss

Total number of packets lost

unsigned reorder

Total number of out of order packets

unsigned dup

Total number of duplicates packets

pj_math_stat loss_period

Loss period statistics (in usec)

unsigned burst

Burst/sequential packet lost detected

unsigned random

Random packet lost detected.

struct pjmedia_rtcp_stream_stat::[anonymous] loss_type

Types of loss detected.

pj_math_stat jitter

Jitter statistics (in usec)

struct pjmedia_rtcp_stat
#include <rtcp.h>

Bidirectional RTP stream statistics.

Public Members

pj_time_val start

Time when session was created

pjmedia_rtcp_stream_stat tx

Encoder stream statistics.

pjmedia_rtcp_stream_stat rx

Decoder stream statistics.

pj_math_stat rtt

Round trip delay statistic(in usec)

pj_uint32_t rtp_tx_last_ts

Last TX RTP timestamp.

pj_uint16_t rtp_tx_last_seq

Last TX RTP sequence.

pjmedia_rtcp_sdes peer_sdes

Peer SDES.

char peer_sdes_buf_[PJMEDIA_RTCP_RX_SDES_BUF_LEN]

Peer SDES buffer.

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.

Public Members

char *name

Name identification.

pjmedia_rtcp_sr_pkt rtcp_sr_pkt

Cached RTCP SR packet.

pjmedia_rtcp_rr_pkt rtcp_rr_pkt

Cached RTCP RR packet.

pjmedia_rtcp_fb_common rtcp_fb_com

Cached RTCP feedback common header packet.

pjmedia_rtp_seq_session seq_ctrl

RTCP sequence number control.

unsigned rtp_last_ts

Last timestamp in RX RTP pkt.

unsigned clock_rate

Clock rate of the stream

unsigned pkt_size

Avg pkt size, in samples.

unsigned dec_pkt_size

Decoding pkt size, in samples.

pj_uint32_t received

pkt received

pj_uint32_t exp_prior

pkt expected at last interval

pj_uint32_t rx_prior

pkt received at last interval

pj_int32_t transit

Rel transit time for prev pkt

pj_uint32_t jitter

Scaled jitter

pj_time_val tv_base

Base time, in seconds.

pj_timestamp ts_base

Base system timestamp.

pj_timestamp ts_freq

System timestamp frequency.

pj_uint32_t rtp_ts_base

Base RTP timestamp.

pj_uint32_t rx_lsr

NTP ts in last SR received

pj_timestamp rx_lsr_time

Time when last SR is received

pj_uint32_t peer_ssrc

Peer SSRC

pjmedia_rtcp_stat stat

Bidirectional stream stat.

struct pjmedia_rtcp_session_setting
#include <rtcp.h>

RTCP session settings.

Public Members

char *name

RTCP session name.

unsigned clock_rate

Sequence.

unsigned samples_per_frame

Timestamp.

unsigned dec_samples_per_frame

Timestamp.

pj_uint32_t ssrc

Sender SSRC.

pj_uint32_t rtp_ts_base

Base RTP timestamp.