Alexandre Lision | 8af73cb | 2013-12-10 14:11:20 -0500 | [diff] [blame^] | 1 | /* $Id$ */ |
| 2 | /* |
| 3 | * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) |
| 4 | * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> |
| 5 | * |
| 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. |
| 10 | * |
| 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. |
| 15 | * |
| 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 |
| 19 | */ |
| 20 | /* |
| 21 | * Based on implementation kindly contributed by Switchlab, Ltd. |
| 22 | */ |
| 23 | #ifndef __PJMEDIA_JBUF_H__ |
| 24 | #define __PJMEDIA_JBUF_H__ |
| 25 | |
| 26 | |
| 27 | /** |
| 28 | * @file jbuf.h |
| 29 | * @brief Adaptive jitter buffer implementation. |
| 30 | */ |
| 31 | #include <pjmedia/types.h> |
| 32 | |
| 33 | /** |
| 34 | * @defgroup PJMED_JBUF Adaptive jitter buffer |
| 35 | * @ingroup PJMEDIA_FRAME_OP |
| 36 | * @brief Adaptive de-jitter buffering implementation |
| 37 | * @{ |
| 38 | * |
| 39 | * This section describes PJMEDIA's implementation of de-jitter buffer. |
| 40 | * The de-jitter buffer may be set to operate in adaptive mode or fixed |
| 41 | * delay mode. |
| 42 | */ |
| 43 | |
| 44 | |
| 45 | PJ_BEGIN_DECL |
| 46 | |
| 47 | |
| 48 | /** |
| 49 | * Types of frame returned by the jitter buffer. |
| 50 | */ |
| 51 | typedef enum pjmedia_jb_frame_type |
| 52 | { |
| 53 | PJMEDIA_JB_MISSING_FRAME = 0, /**< No frame because it's missing */ |
| 54 | PJMEDIA_JB_NORMAL_FRAME = 1, /**< Normal frame is being returned */ |
| 55 | PJMEDIA_JB_ZERO_PREFETCH_FRAME = 2, /**< Zero frame is being returned |
| 56 | because JB is bufferring. */ |
| 57 | PJMEDIA_JB_ZERO_EMPTY_FRAME = 3 /**< Zero frame is being returned |
| 58 | because JB is empty. */ |
| 59 | } pjmedia_jb_frame_type; |
| 60 | |
| 61 | |
| 62 | /** |
| 63 | * Enumeration of jitter buffer discard algorithm. The jitter buffer |
| 64 | * continuously calculates the jitter level to get the optimum latency at |
| 65 | * any time and in order to adjust the latency, the jitter buffer may need |
| 66 | * to discard some frames. |
| 67 | */ |
| 68 | typedef enum pjmedia_jb_discard_algo |
| 69 | { |
| 70 | /** |
| 71 | * Jitter buffer should not discard any frame, except when the jitter |
| 72 | * buffer is full and a new frame arrives, one frame will be discarded |
| 73 | * to make space for the new frame. |
| 74 | */ |
| 75 | PJMEDIA_JB_DISCARD_NONE = 0, |
| 76 | |
| 77 | /** |
| 78 | * Only discard one frame in at least 200ms when the latency is considered |
| 79 | * much higher than it should be. When the jitter buffer is full and a new |
| 80 | * frame arrives, one frame will be discarded to make space for the new |
| 81 | * frame. |
| 82 | */ |
| 83 | PJMEDIA_JB_DISCARD_STATIC, |
| 84 | |
| 85 | /** |
| 86 | * The discard rate is dynamically calculated based on actual parameters |
| 87 | * such as jitter level and latency. When the jitter buffer is full and |
| 88 | * a new frame arrives, one frame will be discarded to make space for the |
| 89 | * new frame. |
| 90 | */ |
| 91 | PJMEDIA_JB_DISCARD_PROGRESSIVE |
| 92 | |
| 93 | } pjmedia_jb_discard_algo; |
| 94 | |
| 95 | |
| 96 | /** |
| 97 | * This structure describes jitter buffer state. |
| 98 | */ |
| 99 | typedef struct pjmedia_jb_state |
| 100 | { |
| 101 | /* Setting */ |
| 102 | unsigned frame_size; /**< Individual frame size, in bytes. */ |
| 103 | unsigned min_prefetch; /**< Minimum allowed prefetch, in frms. */ |
| 104 | unsigned max_prefetch; /**< Maximum allowed prefetch, in frms. */ |
| 105 | |
| 106 | /* Status */ |
| 107 | unsigned burst; /**< Current burst level, in frames */ |
| 108 | unsigned prefetch; /**< Current prefetch value, in frames */ |
| 109 | unsigned size; /**< Current buffer size, in frames. */ |
| 110 | |
| 111 | /* Statistic */ |
| 112 | unsigned avg_delay; /**< Average delay, in ms. */ |
| 113 | unsigned min_delay; /**< Minimum delay, in ms. */ |
| 114 | unsigned max_delay; /**< Maximum delay, in ms. */ |
| 115 | unsigned dev_delay; /**< Standard deviation of delay, in ms.*/ |
| 116 | unsigned avg_burst; /**< Average burst, in frames. */ |
| 117 | unsigned lost; /**< Number of lost frames. */ |
| 118 | unsigned discard; /**< Number of discarded frames. */ |
| 119 | unsigned empty; /**< Number of empty on GET events. */ |
| 120 | } pjmedia_jb_state; |
| 121 | |
| 122 | |
| 123 | /** |
| 124 | * The constant PJMEDIA_JB_DEFAULT_INIT_DELAY specifies default jitter |
| 125 | * buffer prefetch count during jitter buffer creation. |
| 126 | */ |
| 127 | #define PJMEDIA_JB_DEFAULT_INIT_DELAY 15 |
| 128 | |
| 129 | /** |
| 130 | * Opaque declaration for jitter buffer. |
| 131 | */ |
| 132 | typedef struct pjmedia_jbuf pjmedia_jbuf; |
| 133 | |
| 134 | |
| 135 | /** |
| 136 | * Create an adaptive jitter buffer according to the specification. If |
| 137 | * application wants to have a fixed jitter buffer, it may call |
| 138 | * #pjmedia_jbuf_set_fixed() after the jitter buffer is created. Also |
| 139 | * if application wants to alter the discard algorithm, which the default |
| 140 | * PJMEDIA_JB_DISCARD_PROGRESSIVE, it may call #pjmedia_jbuf_set_discard(). |
| 141 | * |
| 142 | * This function may allocate large chunk of memory to keep the frames in |
| 143 | * the buffer. |
| 144 | * |
| 145 | * @param pool The pool to allocate memory. |
| 146 | * @param name Name to identify the jitter buffer for logging |
| 147 | * purpose. |
| 148 | * @param frame_size The size of each frame that will be kept in the |
| 149 | * jitter buffer, in bytes. This should correspond |
| 150 | * to the minimum frame size supported by the codec. |
| 151 | * For example, a 10ms frame (80 bytes) would be |
| 152 | * recommended for G.711 codec. |
| 153 | * @param max_count Maximum number of frames that can be kept in the |
| 154 | * jitter buffer. This effectively means the maximum |
| 155 | * delay that may be introduced by this jitter |
| 156 | * buffer. |
| 157 | * @param ptime Indication of frame duration, used to calculate |
| 158 | * the interval between jitter recalculation. |
| 159 | * @param p_jb Pointer to receive jitter buffer instance. |
| 160 | * |
| 161 | * @return PJ_SUCCESS on success. |
| 162 | */ |
| 163 | PJ_DECL(pj_status_t) pjmedia_jbuf_create(pj_pool_t *pool, |
| 164 | const pj_str_t *name, |
| 165 | unsigned frame_size, |
| 166 | unsigned ptime, |
| 167 | unsigned max_count, |
| 168 | pjmedia_jbuf **p_jb); |
| 169 | |
| 170 | /** |
| 171 | * Set the jitter buffer to fixed delay mode. The default behavior |
| 172 | * is to adapt the delay with actual packet delay. |
| 173 | * |
| 174 | * @param jb The jitter buffer |
| 175 | * @param prefetch The fixed delay value, in number of frames. |
| 176 | * |
| 177 | * @return PJ_SUCCESS on success. |
| 178 | */ |
| 179 | PJ_DECL(pj_status_t) pjmedia_jbuf_set_fixed( pjmedia_jbuf *jb, |
| 180 | unsigned prefetch); |
| 181 | |
| 182 | |
| 183 | /** |
| 184 | * Set the jitter buffer to adaptive mode. |
| 185 | * |
| 186 | * @param jb The jitter buffer. |
| 187 | * @param prefetch The initial prefetch value to be applied to the |
| 188 | * jitter buffer. Setting this to other than 0 will |
| 189 | * activate prefetch buffering, a jitter buffer feature |
| 190 | * that each time it gets empty, it won't return a |
| 191 | * normal frame until its size reaches the number |
| 192 | * specified here. |
| 193 | * @param min_prefetch The minimum delay that must be applied to each |
| 194 | * incoming packets, in number of frames. |
| 195 | * @param max_prefetch The maximum allowable value for prefetch delay, |
| 196 | * in number of frames. |
| 197 | * |
| 198 | * @return PJ_SUCCESS on success. |
| 199 | */ |
| 200 | PJ_DECL(pj_status_t) pjmedia_jbuf_set_adaptive( pjmedia_jbuf *jb, |
| 201 | unsigned prefetch, |
| 202 | unsigned min_prefetch, |
| 203 | unsigned max_prefetch); |
| 204 | |
| 205 | |
| 206 | /** |
| 207 | * Set the jitter buffer discard algorithm. The default discard algorithm, |
| 208 | * set in jitter buffer creation, is PJMEDIA_JB_DISCARD_PROGRESSIVE. |
| 209 | * |
| 210 | * @param jb The jitter buffer. |
| 211 | * @param algo The discard algorithm to be used. |
| 212 | * |
| 213 | * @return PJ_SUCCESS on success. |
| 214 | */ |
| 215 | PJ_DECL(pj_status_t) pjmedia_jbuf_set_discard(pjmedia_jbuf *jb, |
| 216 | pjmedia_jb_discard_algo algo); |
| 217 | |
| 218 | |
| 219 | /** |
| 220 | * Destroy jitter buffer instance. |
| 221 | * |
| 222 | * @param jb The jitter buffer. |
| 223 | * |
| 224 | * @return PJ_SUCCESS on success. |
| 225 | */ |
| 226 | PJ_DECL(pj_status_t) pjmedia_jbuf_destroy(pjmedia_jbuf *jb); |
| 227 | |
| 228 | |
| 229 | /** |
| 230 | * Restart jitter. This function flushes all packets in the buffer and |
| 231 | * reset the internal sequence number. |
| 232 | * |
| 233 | * @param jb The jitter buffer. |
| 234 | * |
| 235 | * @return PJ_SUCCESS on success. |
| 236 | */ |
| 237 | PJ_DECL(pj_status_t) pjmedia_jbuf_reset(pjmedia_jbuf *jb); |
| 238 | |
| 239 | /** |
| 240 | * Put a frame to the jitter buffer. If the frame can be accepted (based |
| 241 | * on the sequence number), the jitter buffer will copy the frame and put |
| 242 | * it in the appropriate position in the buffer. |
| 243 | * |
| 244 | * Application MUST manage it's own synchronization when multiple threads |
| 245 | * are accessing the jitter buffer at the same time. |
| 246 | * |
| 247 | * @param jb The jitter buffer. |
| 248 | * @param frame Pointer to frame buffer to be stored in the jitter |
| 249 | * buffer. |
| 250 | * @param size The frame size. |
| 251 | * @param frame_seq The frame sequence number. |
| 252 | */ |
| 253 | PJ_DECL(void) pjmedia_jbuf_put_frame( pjmedia_jbuf *jb, |
| 254 | const void *frame, |
| 255 | pj_size_t size, |
| 256 | int frame_seq); |
| 257 | |
| 258 | /** |
| 259 | * Put a frame to the jitter buffer. If the frame can be accepted (based |
| 260 | * on the sequence number), the jitter buffer will copy the frame and put |
| 261 | * it in the appropriate position in the buffer. |
| 262 | * |
| 263 | * Application MUST manage it's own synchronization when multiple threads |
| 264 | * are accessing the jitter buffer at the same time. |
| 265 | * |
| 266 | * @param jb The jitter buffer. |
| 267 | * @param frame Pointer to frame buffer to be stored in the jitter |
| 268 | * buffer. |
| 269 | * @param size The frame size. |
| 270 | * @param bit_info Bit precise info of the frame, e.g: a frame may not |
| 271 | * exactly start and end at the octet boundary, so this |
| 272 | * field may be used for specifying start & end bit offset. |
| 273 | * @param frame_seq The frame sequence number. |
| 274 | * @param discarded Flag whether the frame is discarded by jitter buffer. |
| 275 | */ |
| 276 | PJ_DECL(void) pjmedia_jbuf_put_frame2( pjmedia_jbuf *jb, |
| 277 | const void *frame, |
| 278 | pj_size_t size, |
| 279 | pj_uint32_t bit_info, |
| 280 | int frame_seq, |
| 281 | pj_bool_t *discarded); |
| 282 | |
| 283 | /** |
| 284 | * Put a frame to the jitter buffer. If the frame can be accepted (based |
| 285 | * on the sequence number), the jitter buffer will copy the frame and put |
| 286 | * it in the appropriate position in the buffer. |
| 287 | * |
| 288 | * Application MUST manage it's own synchronization when multiple threads |
| 289 | * are accessing the jitter buffer at the same time. |
| 290 | * |
| 291 | * @param jb The jitter buffer. |
| 292 | * @param frame Pointer to frame buffer to be stored in the jitter |
| 293 | * buffer. |
| 294 | * @param size The frame size. |
| 295 | * @param bit_info Bit precise info of the frame, e.g: a frame may not |
| 296 | * exactly start and end at the octet boundary, so this |
| 297 | * field may be used for specifying start & end bit offset. |
| 298 | * @param frame_seq The frame sequence number. |
| 299 | * @param frame_ts The frame timestamp. |
| 300 | * @param discarded Flag whether the frame is discarded by jitter buffer. |
| 301 | */ |
| 302 | PJ_DECL(void) pjmedia_jbuf_put_frame3( pjmedia_jbuf *jb, |
| 303 | const void *frame, |
| 304 | pj_size_t size, |
| 305 | pj_uint32_t bit_info, |
| 306 | int frame_seq, |
| 307 | pj_uint32_t frame_ts, |
| 308 | pj_bool_t *discarded); |
| 309 | /** |
| 310 | * Get a frame from the jitter buffer. The jitter buffer will return the |
| 311 | * oldest frame from it's buffer, when it is available. |
| 312 | * |
| 313 | * Application MUST manage it's own synchronization when multiple threads |
| 314 | * are accessing the jitter buffer at the same time. |
| 315 | * |
| 316 | * @param jb The jitter buffer. |
| 317 | * @param frame Buffer to receive the payload from the jitter buffer. |
| 318 | * Application MUST make sure that the buffer has |
| 319 | * appropriate size (i.e. not less than the frame size, |
| 320 | * as specified when the jitter buffer was created). |
| 321 | * The jitter buffer only copied a frame to this |
| 322 | * buffer when the frame type returned by this function |
| 323 | * is PJMEDIA_JB_NORMAL_FRAME. |
| 324 | * @param p_frm_type Pointer to receive frame type. If jitter buffer is |
| 325 | * currently empty or bufferring, the frame type will |
| 326 | * be set to PJMEDIA_JB_ZERO_FRAME, and no frame will |
| 327 | * be copied. If the jitter buffer detects that frame is |
| 328 | * missing with current sequence number, the frame type |
| 329 | * will be set to PJMEDIA_JB_MISSING_FRAME, and no |
| 330 | * frame will be copied. If there is a frame, the jitter |
| 331 | * buffer will copy the frame to the buffer, and frame |
| 332 | * type will be set to PJMEDIA_JB_NORMAL_FRAME. |
| 333 | */ |
| 334 | PJ_DECL(void) pjmedia_jbuf_get_frame( pjmedia_jbuf *jb, |
| 335 | void *frame, |
| 336 | char *p_frm_type); |
| 337 | |
| 338 | /** |
| 339 | * Get a frame from the jitter buffer. The jitter buffer will return the |
| 340 | * oldest frame from it's buffer, when it is available. |
| 341 | * |
| 342 | * @param jb The jitter buffer. |
| 343 | * @param frame Buffer to receive the payload from the jitter buffer. |
| 344 | * @see pjmedia_jbuf_get_frame(). |
| 345 | * @param size Pointer to receive frame size. |
| 346 | * @param p_frm_type Pointer to receive frame type. |
| 347 | * @see pjmedia_jbuf_get_frame(). |
| 348 | * @param bit_info Bit precise info of the frame, e.g: a frame may not |
| 349 | * exactly start and end at the octet boundary, so this |
| 350 | * field may be used for specifying start & end bit offset. |
| 351 | */ |
| 352 | PJ_DECL(void) pjmedia_jbuf_get_frame2(pjmedia_jbuf *jb, |
| 353 | void *frame, |
| 354 | pj_size_t *size, |
| 355 | char *p_frm_type, |
| 356 | pj_uint32_t *bit_info); |
| 357 | |
| 358 | |
| 359 | /** |
| 360 | * Get a frame from the jitter buffer. The jitter buffer will return the |
| 361 | * oldest frame from it's buffer, when it is available. |
| 362 | * |
| 363 | * @param jb The jitter buffer. |
| 364 | * @param frame Buffer to receive the payload from the jitter buffer. |
| 365 | * @see pjmedia_jbuf_get_frame(). |
| 366 | * @param size Pointer to receive frame size. |
| 367 | * @param p_frm_type Pointer to receive frame type. |
| 368 | * @see pjmedia_jbuf_get_frame(). |
| 369 | * @param bit_info Bit precise info of the frame, e.g: a frame may not |
| 370 | * exactly start and end at the octet boundary, so this |
| 371 | * field may be used for specifying start & end bit offset. |
| 372 | * @param ts Frame timestamp. |
| 373 | * @param seq Frame sequence number. |
| 374 | */ |
| 375 | PJ_DECL(void) pjmedia_jbuf_get_frame3(pjmedia_jbuf *jb, |
| 376 | void *frame, |
| 377 | pj_size_t *size, |
| 378 | char *p_frm_type, |
| 379 | pj_uint32_t *bit_info, |
| 380 | pj_uint32_t *ts, |
| 381 | int *seq); |
| 382 | |
| 383 | |
| 384 | /** |
| 385 | * Peek a frame from the jitter buffer. The jitter buffer state will not be |
| 386 | * modified. |
| 387 | * |
| 388 | * @param jb The jitter buffer. |
| 389 | * @param offset Offset from the oldest frame to be peeked. |
| 390 | * @param frame Buffer to receive the payload from the jitter buffer. |
| 391 | * @see pjmedia_jbuf_get_frame(). |
| 392 | * @param size Pointer to receive frame size. |
| 393 | * @param p_frm_type Pointer to receive frame type. |
| 394 | * @see pjmedia_jbuf_get_frame(). |
| 395 | * @param bit_info Bit precise info of the frame, e.g: a frame may not |
| 396 | * exactly start and end at the octet boundary, so this |
| 397 | * field may be used for specifying start & end bit offset. |
| 398 | * @param ts Frame timestamp. |
| 399 | * @param seq Frame sequence number. |
| 400 | */ |
| 401 | PJ_DECL(void) pjmedia_jbuf_peek_frame(pjmedia_jbuf *jb, |
| 402 | unsigned offset, |
| 403 | const void **frame, |
| 404 | pj_size_t *size, |
| 405 | char *p_frm_type, |
| 406 | pj_uint32_t *bit_info, |
| 407 | pj_uint32_t *ts, |
| 408 | int *seq); |
| 409 | |
| 410 | |
| 411 | /** |
| 412 | * Remove frames from the jitter buffer. |
| 413 | * |
| 414 | * @param jb The jitter buffer. |
| 415 | * @param frame_cnt Number of frames to be removed. |
| 416 | * |
| 417 | * @return The number of frame successfully removed. |
| 418 | */ |
| 419 | PJ_DECL(unsigned) pjmedia_jbuf_remove_frame(pjmedia_jbuf *jb, |
| 420 | unsigned frame_cnt); |
| 421 | |
| 422 | /** |
| 423 | * Check if the jitter buffer is full. |
| 424 | * |
| 425 | * @param jb The jitter buffer. |
| 426 | * |
| 427 | * @return PJ_TRUE if it is full. |
| 428 | */ |
| 429 | PJ_DECL(pj_bool_t) pjmedia_jbuf_is_full(const pjmedia_jbuf *jb); |
| 430 | |
| 431 | |
| 432 | /** |
| 433 | * Get jitter buffer current state/settings. |
| 434 | * |
| 435 | * @param jb The jitter buffer. |
| 436 | * @param state Buffer to receive jitter buffer state. |
| 437 | * |
| 438 | * @return PJ_SUCCESS on success. |
| 439 | */ |
| 440 | PJ_DECL(pj_status_t) pjmedia_jbuf_get_state( const pjmedia_jbuf *jb, |
| 441 | pjmedia_jb_state *state ); |
| 442 | |
| 443 | |
| 444 | |
| 445 | PJ_END_DECL |
| 446 | |
| 447 | /** |
| 448 | * @} |
| 449 | */ |
| 450 | |
| 451 | #endif /* __PJMEDIA_JBUF_H__ */ |