1
/* $Id: rtcp_xr.h 3999 2012-03-30 07:10:13Z bennylp $ */
3
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
6
* This program is free software; you can redistribute it and/or modify
7
* it under the terms of the GNU General Public License as published by
8
* the Free Software Foundation; either version 2 of the License, or
9
* (at your option) any later version.
11
* This program is distributed in the hope that it will be useful,
12
* but WITHOUT ANY WARRANTY; without even the implied warranty of
13
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14
* GNU General Public License for more details.
16
* You should have received a copy of the GNU General Public License
17
* along with this program; if not, write to the Free Software
18
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20
#ifndef __PJMEDIA_RTCP_XR_H__
21
#define __PJMEDIA_RTCP_XR_H__
25
* @brief RTCP XR implementation.
28
#include <pjmedia/types.h>
36
* @defgroup PJMED_RTCP_XR RTCP Extended Report (XR) - RFC 3611
37
* @ingroup PJMEDIA_SESSION
38
* @brief RTCP XR extension to RTCP session
41
* PJMEDIA implements subsets of RTCP XR specification (RFC 3611) to monitor
42
* the quality of the real-time media (audio/video) transmission.
46
* Enumeration of report types of RTCP XR. Useful for user to enable varying
47
* combinations of RTCP XR report blocks.
50
PJMEDIA_RTCP_XR_LOSS_RLE = (1 << 0),
51
PJMEDIA_RTCP_XR_DUP_RLE = (1 << 1),
52
PJMEDIA_RTCP_XR_RCPT_TIMES = (1 << 2),
53
PJMEDIA_RTCP_XR_RR_TIME = (1 << 3),
54
PJMEDIA_RTCP_XR_DLRR = (1 << 4),
55
PJMEDIA_RTCP_XR_STATS = (1 << 5),
56
PJMEDIA_RTCP_XR_VOIP_METRICS = (1 << 6)
57
} pjmedia_rtcp_xr_type;
60
* Enumeration of info need to be updated manually to RTCP XR. Most info
61
* could be updated automatically each time RTP received.
64
PJMEDIA_RTCP_XR_INFO_SIGNAL_LVL = 1,
65
PJMEDIA_RTCP_XR_INFO_NOISE_LVL = 2,
66
PJMEDIA_RTCP_XR_INFO_RERL = 3,
67
PJMEDIA_RTCP_XR_INFO_R_FACTOR = 4,
68
PJMEDIA_RTCP_XR_INFO_MOS_LQ = 5,
69
PJMEDIA_RTCP_XR_INFO_MOS_CQ = 6,
70
PJMEDIA_RTCP_XR_INFO_CONF_PLC = 7,
71
PJMEDIA_RTCP_XR_INFO_CONF_JBA = 8,
72
PJMEDIA_RTCP_XR_INFO_CONF_JBR = 9,
73
PJMEDIA_RTCP_XR_INFO_JB_NOM = 10,
74
PJMEDIA_RTCP_XR_INFO_JB_MAX = 11,
75
PJMEDIA_RTCP_XR_INFO_JB_ABS_MAX = 12
76
} pjmedia_rtcp_xr_info;
79
* Enumeration of PLC types definitions for RTCP XR report.
82
PJMEDIA_RTCP_XR_PLC_UNK = 0,
83
PJMEDIA_RTCP_XR_PLC_DIS = 1,
84
PJMEDIA_RTCP_XR_PLC_ENH = 2,
85
PJMEDIA_RTCP_XR_PLC_STD = 3
86
} pjmedia_rtcp_xr_plc_type;
89
* Enumeration of jitter buffer types definitions for RTCP XR report.
92
PJMEDIA_RTCP_XR_JB_UNKNOWN = 0,
93
PJMEDIA_RTCP_XR_JB_FIXED = 2,
94
PJMEDIA_RTCP_XR_JB_ADAPTIVE = 3
95
} pjmedia_rtcp_xr_jb_type;
101
* This type declares RTCP XR Report Header.
103
typedef struct pjmedia_rtcp_xr_rb_header
105
pj_uint8_t bt; /**< Block type. */
106
pj_uint8_t specific; /**< Block specific data. */
107
pj_uint16_t length; /**< Block length. */
108
} pjmedia_rtcp_xr_rb_header;
111
* This type declares RTCP XR Receiver Reference Time Report Block.
113
typedef struct pjmedia_rtcp_xr_rb_rr_time
115
pjmedia_rtcp_xr_rb_header header; /**< Block header. */
116
pj_uint32_t ntp_sec; /**< NTP time, seconds part. */
117
pj_uint32_t ntp_frac; /**< NTP time, fractions part. */
118
} pjmedia_rtcp_xr_rb_rr_time;
122
* This type declares RTCP XR DLRR Report Sub-block
124
typedef struct pjmedia_rtcp_xr_rb_dlrr_item
126
pj_uint32_t ssrc; /**< receiver SSRC */
127
pj_uint32_t lrr; /**< last receiver report */
128
pj_uint32_t dlrr; /**< delay since last receiver
130
} pjmedia_rtcp_xr_rb_dlrr_item;
133
* This type declares RTCP XR DLRR Report Block
135
typedef struct pjmedia_rtcp_xr_rb_dlrr
137
pjmedia_rtcp_xr_rb_header header; /**< Block header. */
138
pjmedia_rtcp_xr_rb_dlrr_item item; /**< Block contents,
139
variable length list */
140
} pjmedia_rtcp_xr_rb_dlrr;
143
* This type declares RTCP XR Statistics Summary Report Block
145
typedef struct pjmedia_rtcp_xr_rb_stats
147
pjmedia_rtcp_xr_rb_header header; /**< Block header. */
148
pj_uint32_t ssrc; /**< Receiver SSRC */
149
pj_uint16_t begin_seq; /**< Begin RTP sequence reported */
150
pj_uint16_t end_seq; /**< End RTP sequence reported */
151
pj_uint32_t lost; /**< Number of packet lost in this
153
pj_uint32_t dup; /**< Number of duplicated packet in
155
pj_uint32_t jitter_min; /**< Minimum jitter in this interval */
156
pj_uint32_t jitter_max; /**< Maximum jitter in this interval */
157
pj_uint32_t jitter_mean; /**< Average jitter in this interval */
158
pj_uint32_t jitter_dev; /**< Jitter deviation in this
160
pj_uint32_t toh_min:8; /**< Minimum ToH in this interval */
161
pj_uint32_t toh_max:8; /**< Maximum ToH in this interval */
162
pj_uint32_t toh_mean:8; /**< Average ToH in this interval */
163
pj_uint32_t toh_dev:8; /**< ToH deviation in this interval */
164
} pjmedia_rtcp_xr_rb_stats;
167
* This type declares RTCP XR VoIP Metrics Report Block
169
typedef struct pjmedia_rtcp_xr_rb_voip_mtc
171
pjmedia_rtcp_xr_rb_header header; /**< Block header. */
172
pj_uint32_t ssrc; /**< Receiver SSRC */
173
pj_uint8_t loss_rate; /**< Packet loss rate */
174
pj_uint8_t discard_rate; /**< Packet discarded rate */
175
pj_uint8_t burst_den; /**< Burst density */
176
pj_uint8_t gap_den; /**< Gap density */
177
pj_uint16_t burst_dur; /**< Burst duration */
178
pj_uint16_t gap_dur; /**< Gap duration */
179
pj_uint16_t rnd_trip_delay;/**< Round trip delay */
180
pj_uint16_t end_sys_delay; /**< End system delay */
181
pj_uint8_t signal_lvl; /**< Signal level */
182
pj_uint8_t noise_lvl; /**< Noise level */
183
pj_uint8_t rerl; /**< Residual Echo Return Loss */
184
pj_uint8_t gmin; /**< The gap threshold */
185
pj_uint8_t r_factor; /**< Voice quality metric carried
186
over this RTP session */
187
pj_uint8_t ext_r_factor; /**< Voice quality metric carried
188
outside of this RTP session*/
189
pj_uint8_t mos_lq; /**< Mean Opinion Score for
191
pj_uint8_t mos_cq; /**< Mean Opinion Score for
192
Conversation Quality */
193
pj_uint8_t rx_config; /**< Receiver configuration */
194
pj_uint8_t reserved2; /**< Not used */
195
pj_uint16_t jb_nom; /**< Current delay by jitter
197
pj_uint16_t jb_max; /**< Maximum delay by jitter
199
pj_uint16_t jb_abs_max; /**< Maximum possible delay by
201
} pjmedia_rtcp_xr_rb_voip_mtc;
205
* Constant of RTCP-XR content size.
207
#define PJMEDIA_RTCP_XR_BUF_SIZE \
208
sizeof(pjmedia_rtcp_xr_rb_rr_time) + \
209
sizeof(pjmedia_rtcp_xr_rb_dlrr) + \
210
sizeof(pjmedia_rtcp_xr_rb_stats) + \
211
sizeof(pjmedia_rtcp_xr_rb_voip_mtc)
215
* This structure declares RTCP XR (Extended Report) packet.
217
typedef struct pjmedia_rtcp_xr_pkt
220
#if defined(PJ_IS_BIG_ENDIAN) && PJ_IS_BIG_ENDIAN!=0
221
unsigned version:2; /**< packet type */
222
unsigned p:1; /**< padding flag */
223
unsigned count:5; /**< varies by payload type */
224
unsigned pt:8; /**< payload type */
226
unsigned count:5; /**< varies by payload type */
227
unsigned p:1; /**< padding flag */
228
unsigned version:2; /**< packet type */
229
unsigned pt:8; /**< payload type */
231
unsigned length:16; /**< packet length */
232
pj_uint32_t ssrc; /**< SSRC identification */
235
pj_int8_t buf[PJMEDIA_RTCP_XR_BUF_SIZE];
236
/**< Content buffer */
237
} pjmedia_rtcp_xr_pkt;
243
* This structure describes RTCP XR statitic.
245
typedef struct pjmedia_rtcp_xr_stream_stat
248
pj_time_val update; /**< Time of last update. */
250
pj_uint32_t begin_seq; /**< Begin # seq of this interval. */
251
pj_uint32_t end_seq; /**< End # seq of this interval. */
252
unsigned count; /**< Number of packets. */
255
* Flags represent whether the such report is valid/updated
257
unsigned l:1; /**< Lost flag */
258
unsigned d:1; /**< Duplicated flag */
259
unsigned j:1; /**< Jitter flag */
260
unsigned t:2; /**< TTL or Hop Limit,
261
0=none, 1=TTL, 2=HL */
263
unsigned lost; /**< Number of packets lost */
264
unsigned dup; /**< Number of duplicated packets */
265
pj_math_stat jitter; /**< Jitter statistics (in usec) */
266
pj_math_stat toh; /**< TTL of hop limit statistics. */
270
pj_time_val update; /**< Time of last update. */
272
pj_uint8_t loss_rate; /**< Packet loss rate */
273
pj_uint8_t discard_rate; /**< Packet discarded rate */
274
pj_uint8_t burst_den; /**< Burst density */
275
pj_uint8_t gap_den; /**< Gap density */
276
pj_uint16_t burst_dur; /**< Burst duration */
277
pj_uint16_t gap_dur; /**< Gap duration */
278
pj_uint16_t rnd_trip_delay; /**< Round trip delay */
279
pj_uint16_t end_sys_delay; /**< End system delay */
280
pj_int8_t signal_lvl; /**< Signal level */
281
pj_int8_t noise_lvl; /**< Noise level */
282
pj_uint8_t rerl; /**< Residual Echo Return Loss */
283
pj_uint8_t gmin; /**< The gap threshold */
284
pj_uint8_t r_factor; /**< Voice quality metric carried
285
over this RTP session */
286
pj_uint8_t ext_r_factor; /**< Voice quality metric carried
287
outside of this RTP session*/
288
pj_uint8_t mos_lq; /**< Mean Opinion Score for
290
pj_uint8_t mos_cq; /**< Mean Opinion Score for
291
Conversation Quality */
292
pj_uint8_t rx_config; /**< Receiver configuration */
293
pj_uint16_t jb_nom; /**< Current delay by jitter
295
pj_uint16_t jb_max; /**< Maximum delay by jitter
297
pj_uint16_t jb_abs_max; /**< Maximum possible delay by
301
} pjmedia_rtcp_xr_stream_stat;
303
typedef struct pjmedia_rtcp_xr_stat
305
pjmedia_rtcp_xr_stream_stat rx; /**< Decoding direction statistics. */
306
pjmedia_rtcp_xr_stream_stat tx; /**< Encoding direction statistics. */
307
pj_math_stat rtt; /**< Round-trip delay stat (in usec)
308
the value is calculated from
310
} pjmedia_rtcp_xr_stat;
313
* Forward declaration of RTCP session
315
struct pjmedia_rtcp_session;
318
* RTCP session is used to monitor the RTP session of one endpoint. There
319
* should only be one RTCP session for a bidirectional RTP streams.
321
struct pjmedia_rtcp_xr_session
323
char *name; /**< Name identification. */
324
pjmedia_rtcp_xr_pkt pkt; /**< Cached RTCP XR packet. */
326
pj_uint32_t rx_lrr; /**< NTP ts in last RR received. */
327
pj_timestamp rx_lrr_time;/**< Time when last RR is received. */
328
pj_uint32_t rx_last_rr; /**< # pkt received since last
331
pjmedia_rtcp_xr_stat stat; /**< RTCP XR statistics. */
333
/* The reference sequence number is an extended sequence number
334
* that serves as the basis for determining whether a new 16 bit
335
* sequence number comes earlier or later in the 32 bit sequence
338
pj_uint32_t src_ref_seq;
339
pj_bool_t uninitialized_src_ref_seq;
341
/* This structure contains variables needed for calculating
347
pj_uint32_t loss_count;
348
pj_uint32_t discard_count;
357
unsigned ptime; /**< Packet time. */
358
unsigned frames_per_packet; /**< # frames per packet. */
360
struct pjmedia_rtcp_session *rtcp_session;
361
/**< Parent/RTCP session. */
364
typedef struct pjmedia_rtcp_xr_session pjmedia_rtcp_xr_session;
367
* Build an RTCP XR packet which contains one or more RTCP XR report blocks.
368
* There are seven report types as defined in RFC 3611.
370
* @param session The RTCP XR session.
371
* @param rpt_types Report types to be included in the packet, report types
372
* are defined in pjmedia_rtcp_xr_type, set this to zero
373
* will make this function build all reports appropriately.
374
* @param rtcp_pkt Upon return, it will contain pointer to the RTCP XR packet.
375
* @param len Upon return, it will indicate the size of the generated
378
PJ_DECL(void) pjmedia_rtcp_build_rtcp_xr( pjmedia_rtcp_xr_session *session,
380
void **rtcp_pkt, int *len);
383
* Call this function to manually update some info needed by RTCP XR to
384
* generate report which could not be populated directly when receiving
387
* @param session The RTCP XR session.
388
* @param info Info type to be updated, @see pjmedia_rtcp_xr_info.
391
PJ_DECL(pj_status_t) pjmedia_rtcp_xr_update_info(
392
pjmedia_rtcp_xr_session *session,
401
* This function is called internally by RTCP session when RTCP XR is enabled
402
* to initialize the RTCP XR session.
404
* @param session RTCP XR session.
405
* @param r_session RTCP session.
406
* @param gmin Gmin value (defined in RFC 3611), set to 0 for default (16).
407
* @param frames_per_packet
408
Number of frames per packet.
410
void pjmedia_rtcp_xr_init( pjmedia_rtcp_xr_session *session,
411
struct pjmedia_rtcp_session *r_session,
413
unsigned frames_per_packet);
416
* This function is called internally by RTCP session to destroy
417
* the RTCP XR session.
419
* @param session RTCP XR session.
421
void pjmedia_rtcp_xr_fini( pjmedia_rtcp_xr_session *session );
424
* This function is called internally by RTCP session when it receives
425
* incoming RTCP XR packets.
427
* @param session RTCP XR session.
428
* @param rtcp_pkt The received RTCP XR packet.
429
* @param size Size of the incoming packet.
431
void pjmedia_rtcp_xr_rx_rtcp_xr( pjmedia_rtcp_xr_session *session,
432
const void *rtcp_pkt,
436
* This function is called internally by RTCP session whenever an RTP packet
437
* is received or lost to let the RTCP XR session update its statistics.
438
* Data passed to this function is a result of analyzation by RTCP and the
439
* jitter buffer. Whenever some info is available, the value should be zero
440
* or more (no negative info), otherwise if info is not available the info
441
* should be -1 so no update will be done for this info in the RTCP XR session.
443
* @param session RTCP XR session.
444
* @param seq Sequence number of RTP packet.
445
* @param lost Info if this packet is lost.
446
* @param dup Info if this packet is a duplication.
447
* @param discarded Info if this packet is discarded
448
* (not because of duplication).
449
* @param jitter Info jitter of this packet.
450
* @param toh Info Time To Live or Hops Limit of this packet.
451
* @param toh_ipv4 Set PJ_TRUE if packet is transported over IPv4.
453
void pjmedia_rtcp_xr_rx_rtp( pjmedia_rtcp_xr_session *session,
459
int toh, pj_bool_t toh_ipv4);
462
* This function is called internally by RTCP session whenever an RTP
463
* packet is sent to let the RTCP XR session do its internal calculations.
465
* @param session RTCP XR session.
466
* @param ptsize Size of RTP payload being sent.
468
void pjmedia_rtcp_xr_tx_rtp( pjmedia_rtcp_xr_session *session,
478
#endif /* __PJMEDIA_RTCP_XR_H__ */