gst/rtpmanager/rtpjitterbuffer.c

   1 /* GStreamer
   2  * Copyright (C) <2007> Wim Taymans <wim.taymans@gmail.com>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  17  * Boston, MA 02110-1301, USA.
  18  */
  19 #include <string.h>
  20 #include <stdlib.h>
  21
  22 #include <gst/rtp/gstrtpbuffer.h>
  23 #include <gst/rtp/gstrtcpbuffer.h>
  24
  25 #include "rtpjitterbuffer.h"
  26
  27 GST_DEBUG_CATEGORY_STATIC (rtp_jitter_buffer_debug);
  28 #define GST_CAT_DEFAULT rtp_jitter_buffer_debug
  29
  30 #define MAX_WINDOW      RTP_JITTER_BUFFER_MAX_WINDOW
  31 #define MAX_TIME        (2 * GST_SECOND)
  32
  33 /* signals and args */
  34 enum
  35 {
  36   LAST_SIGNAL
  37 };
  38
  39 enum
  40 {
  41   PROP_0
  42 };
  43
  44 /* GObject vmethods */
  45 static void rtp_jitter_buffer_finalize (GObject * object);
  46
  47 GType
  48 rtp_jitter_buffer_mode_get_type (void)
  49 {
  50   static GType jitter_buffer_mode_type = 0;
  51   static const GEnumValue jitter_buffer_modes[] = {
  52     {RTP_JITTER_BUFFER_MODE_NONE, "Only use RTP timestamps", "none"},
  53     {RTP_JITTER_BUFFER_MODE_SLAVE, "Slave receiver to sender clock", "slave"},
  54     {RTP_JITTER_BUFFER_MODE_BUFFER, "Do low/high watermark buffering",
  55         "buffer"},
  56     {0, NULL, NULL},
  57   };
  58
  59   if (!jitter_buffer_mode_type) {
  60     jitter_buffer_mode_type =
  61         g_enum_register_static ("RTPJitterBufferMode", jitter_buffer_modes);
  62   }
  63   return jitter_buffer_mode_type;
  64 }
  65
  66 /* static guint rtp_jitter_buffer_signals[LAST_SIGNAL] = { 0 }; */
  67
  68 G_DEFINE_TYPE (RTPJitterBuffer, rtp_jitter_buffer, G_TYPE_OBJECT);
  69
  70 static void
  71 rtp_jitter_buffer_class_init (RTPJitterBufferClass * klass)
  72 {
  73   GObjectClass *gobject_class;
  74
  75   gobject_class = (GObjectClass *) klass;
  76
  77   gobject_class->finalize = rtp_jitter_buffer_finalize;
  78
  79   GST_DEBUG_CATEGORY_INIT (rtp_jitter_buffer_debug, "rtpjitterbuffer", 0,
  80       "RTP Jitter Buffer");
  81 }
  82
  83 static void
  84 rtp_jitter_buffer_init (RTPJitterBuffer * jbuf)
  85 {
  86   jbuf->packets = g_queue_new ();
  87   jbuf->mode = RTP_JITTER_BUFFER_MODE_SLAVE;
  88
  89   rtp_jitter_buffer_reset_skew (jbuf);
  90 }
  91
  92 static void
  93 rtp_jitter_buffer_finalize (GObject * object)
  94 {
  95   RTPJitterBuffer *jbuf;
  96
  97   jbuf = RTP_JITTER_BUFFER_CAST (object);
  98
  99   rtp_jitter_buffer_flush (jbuf);
 100   g_queue_free (jbuf->packets);
 101
 102   G_OBJECT_CLASS (rtp_jitter_buffer_parent_class)->finalize (object);
 103 }
 104
 105 /**
 106  * rtp_jitter_buffer_new:
 107  *
 108  * Create an #RTPJitterBuffer.
 109  *
 110  * Returns: a new #RTPJitterBuffer. Use g_object_unref() after usage.
 111  */
 112 RTPJitterBuffer *
 113 rtp_jitter_buffer_new (void)
 114 {
 115   RTPJitterBuffer *jbuf;
 116
 117   jbuf = g_object_new (RTP_TYPE_JITTER_BUFFER, NULL);
 118
 119   return jbuf;
 120 }
 121
 122 /**
 123  * rtp_jitter_buffer_get_mode:
 124  * @jbuf: an #RTPJitterBuffer
 125  *
 126  * Get the current jitterbuffer mode.
 127  *
 128  * Returns: the current jitterbuffer mode.
 129  */
 130 RTPJitterBufferMode
 131 rtp_jitter_buffer_get_mode (RTPJitterBuffer * jbuf)
 132 {
 133   return jbuf->mode;
 134 }
 135
 136 /**
 137  * rtp_jitter_buffer_set_mode:
 138  * @jbuf: an #RTPJitterBuffer
 139  * @mode: a #RTPJitterBufferMode
 140  *
 141  * Set the buffering and clock slaving algorithm used in the @jbuf.
 142  */
 143 void
 144 rtp_jitter_buffer_set_mode (RTPJitterBuffer * jbuf, RTPJitterBufferMode mode)
 145 {
 146   jbuf->mode = mode;
 147 }
 148
 149 GstClockTime
 150 rtp_jitter_buffer_get_delay (RTPJitterBuffer * jbuf)
 151 {
 152   return jbuf->delay;
 153 }
 154
 155 void
 156 rtp_jitter_buffer_set_delay (RTPJitterBuffer * jbuf, GstClockTime delay)
 157 {
 158   jbuf->delay = delay;
 159   jbuf->low_level = (delay * 15) / 100;
 160   /* the high level is at 90% in order to release packets before we fill up the
 161    * buffer up to the latency */
 162   jbuf->high_level = (delay * 90) / 100;
 163
 164   GST_DEBUG ("delay %" GST_TIME_FORMAT ", min %" GST_TIME_FORMAT ", max %"
 165       GST_TIME_FORMAT, GST_TIME_ARGS (jbuf->delay),
 166       GST_TIME_ARGS (jbuf->low_level), GST_TIME_ARGS (jbuf->high_level));
 167 }
 168
 169
 170 /**
 171  * rtp_jitter_buffer_reset_skew:
 172  * @jbuf: an #RTPJitterBuffer
 173  *
 174  * Reset the skew calculations in @jbuf.
 175  */
 176 void
 177 rtp_jitter_buffer_reset_skew (RTPJitterBuffer * jbuf)
 178 {
 179   jbuf->base_time = -1;
 180   jbuf->base_rtptime = -1;
 181   jbuf->base_extrtp = -1;
 182   jbuf->clock_rate = -1;
 183   jbuf->ext_rtptime = -1;
 184   jbuf->last_rtptime = -1;
 185   jbuf->window_pos = 0;
 186   jbuf->window_filling = TRUE;
 187   jbuf->window_min = 0;
 188   jbuf->skew = 0;
 189   jbuf->prev_send_diff = -1;
 190   jbuf->prev_out_time = -1;
 191   GST_DEBUG ("reset skew correction");
 192 }
 193
 194 static void
 195 rtp_jitter_buffer_resync (RTPJitterBuffer * jbuf, GstClockTime time,
 196     GstClockTime gstrtptime, guint64 ext_rtptime, gboolean reset_skew)
 197 {
 198   jbuf->base_time = time;
 199   jbuf->base_rtptime = gstrtptime;
 200   jbuf->base_extrtp = ext_rtptime;
 201   jbuf->prev_out_time = -1;
 202   jbuf->prev_send_diff = -1;
 203   if (reset_skew) {
 204     jbuf->window_filling = TRUE;
 205     jbuf->window_pos = 0;
 206     jbuf->window_min = 0;
 207     jbuf->window_size = 0;
 208     jbuf->skew = 0;
 209   }
 210 }
 211
 212 static guint64
 213 get_buffer_level (RTPJitterBuffer * jbuf)
 214 {
 215   GstBuffer *high_buf = NULL, *low_buf = NULL;
 216   guint64 level;
 217   GList *find;
 218
 219   /* first first buffer with timestamp */
 220   find = g_queue_peek_head_link (jbuf->packets);
 221   while (find) {
 222     high_buf = find->data;
 223     if (GST_BUFFER_TIMESTAMP (high_buf) != -1)
 224       break;
 225
 226     high_buf = NULL;
 227     find = g_list_next (find);
 228   }
 229
 230   find = g_queue_peek_tail_link (jbuf->packets);
 231   while (find) {
 232     low_buf = find->data;
 233     if (GST_BUFFER_TIMESTAMP (low_buf) != -1)
 234       break;
 235
 236     low_buf = NULL;
 237     find = g_list_previous (find);
 238   }
 239
 240   if (!high_buf || !low_buf || high_buf == low_buf) {
 241     level = 0;
 242   } else {
 243     guint64 high_ts, low_ts;
 244
 245     high_ts = GST_BUFFER_TIMESTAMP (high_buf);
 246     low_ts = GST_BUFFER_TIMESTAMP (low_buf);
 247
 248     if (high_ts > low_ts)
 249       level = high_ts - low_ts;
 250     else
 251       level = 0;
 252
 253     GST_LOG_OBJECT (jbuf,
 254         "low %" GST_TIME_FORMAT " high %" GST_TIME_FORMAT " level %"
 255         G_GUINT64_FORMAT, GST_TIME_ARGS (low_ts), GST_TIME_ARGS (high_ts),
 256         level);
 257   }
 258   return level;
 259 }
 260
 261 static void
 262 update_buffer_level (RTPJitterBuffer * jbuf, gint * percent)
 263 {
 264   gboolean post = FALSE;
 265   guint64 level;
 266
 267   level = get_buffer_level (jbuf);
 268   GST_DEBUG ("buffer level %" GST_TIME_FORMAT, GST_TIME_ARGS (level));
 269
 270   if (jbuf->buffering) {
 271     post = TRUE;
 272     if (level > jbuf->high_level) {
 273       GST_DEBUG ("buffering finished");
 274       jbuf->buffering = FALSE;
 275     }
 276   } else {
 277     if (level < jbuf->low_level) {
 278       GST_DEBUG ("buffering started");
 279       jbuf->buffering = TRUE;
 280       post = TRUE;
 281     }
 282   }
 283   if (post) {
 284     gint perc;
 285
 286     if (jbuf->buffering && (jbuf->high_level != 0)) {
 287       perc = (level * 100 / jbuf->high_level);
 288       perc = MIN (perc, 100);
 289     } else {
 290       perc = 100;
 291     }
 292
 293     if (percent)
 294       *percent = perc;
 295
 296     GST_DEBUG ("buffering %d", perc);
 297   }
 298 }
 299
 300 /* For the clock skew we use a windowed low point averaging algorithm as can be
 301  * found in Fober, Orlarey and Letz, 2005, "Real Time Clock Skew Estimation
 302  * over Network Delays":
 303  * http://www.grame.fr/Ressources/pub/TR-050601.pdf
 304  * http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.102.1546
 305  *
 306  * The idea is that the jitter is composed of:
 307  *
 308  *  J = N + n
 309  *
 310  *   N   : a constant network delay.
 311  *   n   : random added noise. The noise is concentrated around 0
 312  *
 313  * In the receiver we can track the elapsed time at the sender with:
 314  *
 315  *  send_diff(i) = (Tsi - Ts0);
 316  *
 317  *   Tsi : The time at the sender at packet i
 318  *   Ts0 : The time at the sender at the first packet
 319  *
 320  * This is the difference between the RTP timestamp in the first received packet
 321  * and the current packet.
 322  *
 323  * At the receiver we have to deal with the jitter introduced by the network.
 324  *
 325  *  recv_diff(i) = (Tri - Tr0)
 326  *
 327  *   Tri : The time at the receiver at packet i
 328  *   Tr0 : The time at the receiver at the first packet
 329  *
 330  * Both of these values contain a jitter Ji, a jitter for packet i, so we can
 331  * write:
 332  *
 333  *  recv_diff(i) = (Cri + D + ni) - (Cr0 + D + n0))
 334  *
 335  *    Cri    : The time of the clock at the receiver for packet i
 336  *    D + ni : The jitter when receiving packet i
 337  *
 338  * We see that the network delay is irrelevant here as we can elliminate D:
 339  *
 340  *  recv_diff(i) = (Cri + ni) - (Cr0 + n0))
 341  *
 342  * The drift is now expressed as:
 343  *
 344  *  Drift(i) = recv_diff(i) - send_diff(i);
 345  *
 346  * We now keep the W latest values of Drift and find the minimum (this is the
 347  * one with the lowest network jitter and thus the one which is least affected
 348  * by it). We average this lowest value to smooth out the resulting network skew.
 349  *
 350  * Both the window and the weighting used for averaging influence the accuracy
 351  * of the drift estimation. Finding the correct parameters turns out to be a
 352  * compromise between accuracy and inertia.
 353  *
 354  * We use a 2 second window or up to 512 data points, which is statistically big
 355  * enough to catch spikes (FIXME, detect spikes).
 356  * We also use a rather large weighting factor (125) to smoothly adapt. During
 357  * startup, when filling the window, we use a parabolic weighting factor, the
 358  * more the window is filled, the faster we move to the detected possible skew.
 359  *
 360  * Returns: @time adjusted with the clock skew.
 361  */
 362 static GstClockTime
 363 calculate_skew (RTPJitterBuffer * jbuf, guint32 rtptime, GstClockTime time,
 364     guint32 clock_rate)
 365 {
 366   guint64 ext_rtptime;
 367   guint64 send_diff, recv_diff;
 368   gint64 delta;
 369   gint64 old;
 370   gint pos, i;
 371   GstClockTime gstrtptime, out_time;
 372   guint64 slope;
 373
 374   ext_rtptime = gst_rtp_buffer_ext_timestamp (&jbuf->ext_rtptime, rtptime);
 375
 376   if (jbuf->last_rtptime != -1 && ext_rtptime == jbuf->last_rtptime)
 377     return jbuf->prev_out_time;
 378
 379   gstrtptime = gst_util_uint64_scale_int (ext_rtptime, GST_SECOND, clock_rate);
 380
 381   /* keep track of the last extended rtptime */
 382   jbuf->last_rtptime = ext_rtptime;
 383
 384   if (jbuf->clock_rate != clock_rate) {
 385     if (jbuf->clock_rate == -1) {
 386       GST_DEBUG ("Clock rate changed from %" G_GUINT32_FORMAT " to %"
 387           G_GUINT32_FORMAT, jbuf->clock_rate, clock_rate);
 388     } else {
 389       GST_WARNING ("Clock rate changed from %" G_GUINT32_FORMAT " to %"
 390           G_GUINT32_FORMAT, jbuf->clock_rate, clock_rate);
 391     }
 392     jbuf->base_time = -1;
 393     jbuf->base_rtptime = -1;
 394     jbuf->clock_rate = clock_rate;
 395     jbuf->prev_out_time = -1;
 396     jbuf->prev_send_diff = -1;
 397   }
 398
 399   /* first time, lock on to time and gstrtptime */
 400   if (G_UNLIKELY (jbuf->base_time == -1)) {
 401     jbuf->base_time = time;
 402     jbuf->prev_out_time = -1;
 403     GST_DEBUG ("Taking new base time %" GST_TIME_FORMAT, GST_TIME_ARGS (time));
 404   }
 405   if (G_UNLIKELY (jbuf->base_rtptime == -1)) {
 406     jbuf->base_rtptime = gstrtptime;
 407     jbuf->base_extrtp = ext_rtptime;
 408     jbuf->prev_send_diff = -1;
 409     GST_DEBUG ("Taking new base rtptime %" GST_TIME_FORMAT,
 410         GST_TIME_ARGS (gstrtptime));
 411   }
 412
 413   if (G_LIKELY (gstrtptime >= jbuf->base_rtptime))
 414     send_diff = gstrtptime - jbuf->base_rtptime;
 415   else if (time != -1) {
 416     /* elapsed time at sender, timestamps can go backwards and thus be smaller
 417      * than our base time, take a new base time in that case. */
 418     GST_WARNING ("backward timestamps at server, taking new base time");
 419     rtp_jitter_buffer_resync (jbuf, time, gstrtptime, ext_rtptime, FALSE);
 420     send_diff = 0;
 421   } else {
 422     GST_WARNING ("backward timestamps at server but no timestamps");
 423     send_diff = 0;
 424     /* at least try to get a new timestamp.. */
 425     jbuf->base_time = -1;
 426   }
 427
 428   GST_DEBUG ("extrtp %" G_GUINT64_FORMAT ", gstrtp %" GST_TIME_FORMAT ", base %"
 429       GST_TIME_FORMAT ", send_diff %" GST_TIME_FORMAT, ext_rtptime,
 430       GST_TIME_ARGS (gstrtptime), GST_TIME_ARGS (jbuf->base_rtptime),
 431       GST_TIME_ARGS (send_diff));
 432
 433   /* we don't have an arrival timestamp so we can't do skew detection. we
 434    * should still apply a timestamp based on RTP timestamp and base_time */
 435   if (time == -1 || jbuf->base_time == -1)
 436     goto no_skew;
 437
 438   /* elapsed time at receiver, includes the jitter */
 439   recv_diff = time - jbuf->base_time;
 440
 441   /* measure the diff */
 442   delta = ((gint64) recv_diff) - ((gint64) send_diff);
 443
 444   /* measure the slope, this gives a rought estimate between the sender speed
 445    * and the receiver speed. This should be approximately 8, higher values
 446    * indicate a burst (especially when the connection starts) */
 447   if (recv_diff > 0)
 448     slope = (send_diff * 8) / recv_diff;
 449   else
 450     slope = 8;
 451
 452   GST_DEBUG ("time %" GST_TIME_FORMAT ", base %" GST_TIME_FORMAT ", recv_diff %"
 453       GST_TIME_FORMAT ", slope %" G_GUINT64_FORMAT, GST_TIME_ARGS (time),
 454       GST_TIME_ARGS (jbuf->base_time), GST_TIME_ARGS (recv_diff), slope);
 455
 456   /* if the difference between the sender timeline and the receiver timeline
 457    * changed too quickly we have to resync because the server likely restarted
 458    * its timestamps. */
 459   if (ABS (delta - jbuf->skew) > GST_SECOND) {
 460     GST_WARNING ("delta - skew: %" GST_TIME_FORMAT " too big, reset skew",
 461         GST_TIME_ARGS (ABS (delta - jbuf->skew)));
 462     rtp_jitter_buffer_resync (jbuf, time, gstrtptime, ext_rtptime, TRUE);
 463     send_diff = 0;
 464     delta = 0;
 465   }
 466
 467   pos = jbuf->window_pos;
 468
 469   if (G_UNLIKELY (jbuf->window_filling)) {
 470     /* we are filling the window */
 471     GST_DEBUG ("filling %d, delta %" G_GINT64_FORMAT, pos, delta);
 472     jbuf->window[pos++] = delta;
 473     /* calc the min delta we observed */
 474     if (G_UNLIKELY (pos == 1 || delta < jbuf->window_min))
 475       jbuf->window_min = delta;
 476
 477     if (G_UNLIKELY (send_diff >= MAX_TIME || pos >= MAX_WINDOW)) {
 478       jbuf->window_size = pos;
 479
 480       /* window filled */
 481       GST_DEBUG ("min %" G_GINT64_FORMAT, jbuf->window_min);
 482
 483       /* the skew is now the min */
 484       jbuf->skew = jbuf->window_min;
 485       jbuf->window_filling = FALSE;
 486     } else {
 487       gint perc_time, perc_window, perc;
 488
 489       /* figure out how much we filled the window, this depends on the amount of
 490        * time we have or the max number of points we keep. */
 491       perc_time = send_diff * 100 / MAX_TIME;
 492       perc_window = pos * 100 / MAX_WINDOW;
 493       perc = MAX (perc_time, perc_window);
 494
 495       /* make a parabolic function, the closer we get to the MAX, the more value
 496        * we give to the scaling factor of the new value */
 497       perc = perc * perc;
 498
 499       /* quickly go to the min value when we are filling up, slowly when we are
 500        * just starting because we're not sure it's a good value yet. */
 501       jbuf->skew =
 502           (perc * jbuf->window_min + ((10000 - perc) * jbuf->skew)) / 10000;
 503       jbuf->window_size = pos + 1;
 504     }
 505   } else {
 506     /* pick old value and store new value. We keep the previous value in order
 507      * to quickly check if the min of the window changed */
 508     old = jbuf->window[pos];
 509     jbuf->window[pos++] = delta;
 510
 511     if (G_UNLIKELY (delta <= jbuf->window_min)) {
 512       /* if the new value we inserted is smaller or equal to the current min,
 513        * it becomes the new min */
 514       jbuf->window_min = delta;
 515     } else if (G_UNLIKELY (old == jbuf->window_min)) {
 516       gint64 min = G_MAXINT64;
 517
 518       /* if we removed the old min, we have to find a new min */
 519       for (i = 0; i < jbuf->window_size; i++) {
 520         /* we found another value equal to the old min, we can stop searching now */
 521         if (jbuf->window[i] == old) {
 522           min = old;
 523           break;
 524         }
 525         if (jbuf->window[i] < min)
 526           min = jbuf->window[i];
 527       }
 528       jbuf->window_min = min;
 529     }
 530     /* average the min values */
 531     jbuf->skew = (jbuf->window_min + (124 * jbuf->skew)) / 125;
 532     GST_DEBUG ("delta %" G_GINT64_FORMAT ", new min: %" G_GINT64_FORMAT,
 533         delta, jbuf->window_min);
 534   }
 535   /* wrap around in the window */
 536   if (G_UNLIKELY (pos >= jbuf->window_size))
 537     pos = 0;
 538   jbuf->window_pos = pos;
 539
 540 no_skew:
 541   /* the output time is defined as the base timestamp plus the RTP time
 542    * adjusted for the clock skew .*/
 543   if (jbuf->base_time != -1) {
 544     out_time = jbuf->base_time + send_diff;
 545     /* skew can be negative and we don't want to make invalid timestamps */
 546     if (jbuf->skew < 0 && out_time < -jbuf->skew) {
 547       out_time = 0;
 548     } else {
 549       out_time += jbuf->skew;
 550     }
 551     /* check if timestamps are not going backwards, we can only check this if we
 552      * have a previous out time and a previous send_diff */
 553     if (G_LIKELY (jbuf->prev_out_time != -1 && jbuf->prev_send_diff != -1)) {
 554       /* now check for backwards timestamps */
 555       if (G_UNLIKELY (
 556               /* if the server timestamps went up and the out_time backwards */
 557               (send_diff > jbuf->prev_send_diff
 558                   && out_time < jbuf->prev_out_time) ||
 559               /* if the server timestamps went backwards and the out_time forwards */
 560               (send_diff < jbuf->prev_send_diff
 561                   && out_time > jbuf->prev_out_time) ||
 562               /* if the server timestamps did not change */
 563               send_diff == jbuf->prev_send_diff)) {
 564         GST_DEBUG ("backwards timestamps, using previous time");
 565         out_time = jbuf->prev_out_time;
 566       }
 567     }
 568     if (time != -1 && out_time + jbuf->delay < time) {
 569       /* if we are going to produce a timestamp that is later than the input
 570        * timestamp, we need to reset the jitterbuffer. Likely the server paused
 571        * temporarily */
 572       GST_DEBUG ("out %" GST_TIME_FORMAT " + %" G_GUINT64_FORMAT " < time %"
 573           GST_TIME_FORMAT ", reset jitterbuffer", GST_TIME_ARGS (out_time),
 574           jbuf->delay, GST_TIME_ARGS (time));
 575       rtp_jitter_buffer_resync (jbuf, time, gstrtptime, ext_rtptime, TRUE);
 576       out_time = time;
 577       send_diff = 0;
 578     }
 579   } else
 580     out_time = -1;
 581
 582   jbuf->prev_out_time = out_time;
 583   jbuf->prev_send_diff = send_diff;
 584
 585   GST_DEBUG ("skew %" G_GINT64_FORMAT ", out %" GST_TIME_FORMAT,
 586       jbuf->skew, GST_TIME_ARGS (out_time));
 587
 588   return out_time;
 589 }
 590
 591 /**
 592  * rtp_jitter_buffer_insert:
 593  * @jbuf: an #RTPJitterBuffer
 594  * @buf: a buffer
 595  * @time: a running_time when this buffer was received in nanoseconds
 596  * @clock_rate: the clock-rate of the payload of @buf
 597  * @max_delay: the maximum lateness of @buf
 598  * @tail: TRUE when the tail element changed.
 599  *
 600  * Inserts @buf into the packet queue of @jbuf. The sequence number of the
 601  * packet will be used to sort the packets. This function takes ownerhip of
 602  * @buf when the function returns %TRUE.
 603  * @buf should have writable metadata when calling this function.
 604  *
 605  * Returns: %FALSE if a packet with the same number already existed.
 606  */
 607 gboolean
 608 rtp_jitter_buffer_insert (RTPJitterBuffer * jbuf, GstBuffer * buf,
 609     GstClockTime time, guint32 clock_rate, gboolean * tail, gint * percent)
 610 {
 611   GList *list;
 612   guint32 rtptime;
 613   guint16 seqnum;
 614   GstRTPBuffer rtp = { NULL };
 615
 616   g_return_val_if_fail (jbuf != NULL, FALSE);
 617   g_return_val_if_fail (buf != NULL, FALSE);
 618
 619   gst_rtp_buffer_map (buf, GST_MAP_READ, &rtp);
 620
 621   seqnum = gst_rtp_buffer_get_seq (&rtp);
 622
 623   /* loop the list to skip strictly smaller seqnum buffers */
 624   for (list = jbuf->packets->head; list; list = g_list_next (list)) {
 625     guint16 qseq;
 626     gint gap;
 627     GstRTPBuffer rtpb = { NULL };
 628
 629     gst_rtp_buffer_map (GST_BUFFER_CAST (list->data), GST_MAP_READ, &rtpb);
 630     qseq = gst_rtp_buffer_get_seq (&rtpb);
 631     gst_rtp_buffer_unmap (&rtpb);
 632
 633     /* compare the new seqnum to the one in the buffer */
 634     gap = gst_rtp_buffer_compare_seqnum (seqnum, qseq);
 635
 636     /* we hit a packet with the same seqnum, notify a duplicate */
 637     if (G_UNLIKELY (gap == 0))
 638       goto duplicate;
 639
 640     /* seqnum > qseq, we can stop looking */
 641     if (G_LIKELY (gap < 0))
 642       break;
 643   }
 644
 645   rtptime = gst_rtp_buffer_get_timestamp (&rtp);
 646   /* rtp time jumps are checked for during skew calculation, but bypassed
 647    * in other mode, so mind those here and reset jb if needed.
 648    * Only reset if valid input time, which is likely for UDP input
 649    * where we expect this might happen due to async thread effects
 650    * (in seek and state change cycles), but not so much for TCP input */
 651   if (GST_CLOCK_TIME_IS_VALID (time) &&
 652       jbuf->mode != RTP_JITTER_BUFFER_MODE_SLAVE &&
 653       jbuf->base_time != -1 && jbuf->last_rtptime != -1) {
 654     GstClockTime ext_rtptime = jbuf->ext_rtptime;
 655
 656     ext_rtptime = gst_rtp_buffer_ext_timestamp (&ext_rtptime, rtptime);
 657     if (ext_rtptime > jbuf->last_rtptime + 3 * clock_rate ||
 658         ext_rtptime + 3 * clock_rate < jbuf->last_rtptime) {
 659       /* reset even if we don't have valid incoming time;
 660        * still better than producing possibly very bogus output timestamp */
 661       GST_WARNING ("rtp delta too big, reset skew");
 662       rtp_jitter_buffer_reset_skew (jbuf);
 663     }
 664   }
 665
 666   switch (jbuf->mode) {
 667     case RTP_JITTER_BUFFER_MODE_NONE:
 668     case RTP_JITTER_BUFFER_MODE_BUFFER:
 669       /* send 0 as the first timestamp and -1 for the other ones. This will
 670        * interpollate them from the RTP timestamps with a 0 origin. In buffering
 671        * mode we will adjust the outgoing timestamps according to the amount of
 672        * time we spent buffering. */
 673       if (jbuf->base_time == -1)
 674         time = 0;
 675       else
 676         time = -1;
 677       break;
 678     case RTP_JITTER_BUFFER_MODE_SLAVE:
 679     default:
 680       break;
 681   }
 682   /* do skew calculation by measuring the difference between rtptime and the
 683    * receive time, this function will retimestamp @buf with the skew corrected
 684    * running time. */
 685   time = calculate_skew (jbuf, rtptime, time, clock_rate);
 686   GST_BUFFER_PTS (buf) = time;
 687   GST_BUFFER_DTS (buf) = time;
 688
 689   /* It's more likely that the packet was inserted in the front of the buffer */
 690   if (G_LIKELY (list))
 691     g_queue_insert_before (jbuf->packets, list, buf);
 692   else
 693     g_queue_push_tail (jbuf->packets, buf);
 694
 695   /* buffering mode, update buffer stats */
 696   if (jbuf->mode == RTP_JITTER_BUFFER_MODE_BUFFER)
 697     update_buffer_level (jbuf, percent);
 698   else
 699     *percent = -1;
 700
 701   /* tail was changed when we did not find a previous packet, we set the return
 702    * flag when requested. */
 703   if (G_LIKELY (tail))
 704     *tail = (list == NULL);
 705
 706   gst_rtp_buffer_unmap (&rtp);
 707
 708   return TRUE;
 709
 710   /* ERRORS */
 711 duplicate:
 712   {
 713     gst_rtp_buffer_unmap (&rtp);
 714     GST_WARNING ("duplicate packet %d found", (gint) seqnum);
 715     return FALSE;
 716   }
 717 }
 718
 719 /**
 720  * rtp_jitter_buffer_pop:
 721  * @jbuf: an #RTPJitterBuffer
 722  * @percent: the buffering percent
 723  *
 724  * Pops the oldest buffer from the packet queue of @jbuf. The popped buffer will
 725  * have its timestamp adjusted with the incomming running_time and the detected
 726  * clock skew.
 727  *
 728  * Returns: a #GstBuffer or %NULL when there was no packet in the queue.
 729  */
 730 GstBuffer *
 731 rtp_jitter_buffer_pop (RTPJitterBuffer * jbuf, gint * percent)
 732 {
 733   GstBuffer *buf;
 734
 735   g_return_val_if_fail (jbuf != NULL, NULL);
 736
 737   buf = g_queue_pop_tail (jbuf->packets);
 738
 739   /* buffering mode, update buffer stats */
 740   if (jbuf->mode == RTP_JITTER_BUFFER_MODE_BUFFER)
 741     update_buffer_level (jbuf, percent);
 742   else
 743     *percent = -1;
 744
 745   return buf;
 746 }
 747
 748 /**
 749  * rtp_jitter_buffer_peek:
 750  * @jbuf: an #RTPJitterBuffer
 751  *
 752  * Peek the oldest buffer from the packet queue of @jbuf. Register a callback
 753  * with rtp_jitter_buffer_set_tail_changed() to be notified when an older packet
 754  * was inserted in the queue.
 755  *
 756  * Returns: a #GstBuffer or %NULL when there was no packet in the queue.
 757  */
 758 GstBuffer *
 759 rtp_jitter_buffer_peek (RTPJitterBuffer * jbuf)
 760 {
 761   GstBuffer *buf;
 762
 763   g_return_val_if_fail (jbuf != NULL, NULL);
 764
 765   buf = g_queue_peek_tail (jbuf->packets);
 766
 767   return buf;
 768 }
 769
 770 /**
 771  * rtp_jitter_buffer_flush:
 772  * @jbuf: an #RTPJitterBuffer
 773  *
 774  * Flush all packets from the jitterbuffer.
 775  */
 776 void
 777 rtp_jitter_buffer_flush (RTPJitterBuffer * jbuf)
 778 {
 779   GstBuffer *buffer;
 780
 781   g_return_if_fail (jbuf != NULL);
 782
 783   while ((buffer = g_queue_pop_head (jbuf->packets)))
 784     gst_buffer_unref (buffer);
 785 }
 786
 787 /**
 788  * rtp_jitter_buffer_is_buffering:
 789  * @jbuf: an #RTPJitterBuffer
 790  *
 791  * Check if @jbuf is buffering currently. Users of the jitterbuffer should not
 792  * pop packets while in buffering mode.
 793  *
 794  * Returns: the buffering state of @jbuf
 795  */
 796 gboolean
 797 rtp_jitter_buffer_is_buffering (RTPJitterBuffer * jbuf)
 798 {
 799   return jbuf->buffering;
 800 }
 801
 802 /**
 803  * rtp_jitter_buffer_set_buffering:
 804  * @jbuf: an #RTPJitterBuffer
 805  * @buffering: the new buffering state
 806  *
 807  * Forces @jbuf to go into the buffering state.
 808  */
 809 void
 810 rtp_jitter_buffer_set_buffering (RTPJitterBuffer * jbuf, gboolean buffering)
 811 {
 812   jbuf->buffering = buffering;
 813 }
 814
 815 /**
 816  * rtp_jitter_buffer_get_percent:
 817  * @jbuf: an #RTPJitterBuffer
 818  *
 819  * Get the buffering percent of the jitterbuffer.
 820  *
 821  * Returns: the buffering percent
 822  */
 823 gint
 824 rtp_jitter_buffer_get_percent (RTPJitterBuffer * jbuf)
 825 {
 826   gint percent;
 827   guint64 level;
 828
 829   if (G_UNLIKELY (jbuf->high_level == 0))
 830     return 100;
 831
 832   level = get_buffer_level (jbuf);
 833   percent = (level * 100 / jbuf->high_level);
 834   percent = MIN (percent, 100);
 835
 836   return percent;
 837 }
 838
 839 /**
 840  * rtp_jitter_buffer_num_packets:
 841  * @jbuf: an #RTPJitterBuffer
 842  *
 843  * Get the number of packets currently in "jbuf.
 844  *
 845  * Returns: The number of packets in @jbuf.
 846  */
 847 guint
 848 rtp_jitter_buffer_num_packets (RTPJitterBuffer * jbuf)
 849 {
 850   g_return_val_if_fail (jbuf != NULL, 0);
 851
 852   return jbuf->packets->length;
 853 }
 854
 855 /**
 856  * rtp_jitter_buffer_get_ts_diff:
 857  * @jbuf: an #RTPJitterBuffer
 858  *
 859  * Get the difference between the timestamps of first and last packet in the
 860  * jitterbuffer.
 861  *
 862  * Returns: The difference expressed in the timestamp units of the packets.
 863  */
 864 guint32
 865 rtp_jitter_buffer_get_ts_diff (RTPJitterBuffer * jbuf)
 866 {
 867   guint64 high_ts, low_ts;
 868   GstBuffer *high_buf, *low_buf;
 869   guint32 result;
 870   GstRTPBuffer rtp = { NULL };
 871
 872   g_return_val_if_fail (jbuf != NULL, 0);
 873
 874   high_buf = g_queue_peek_head (jbuf->packets);
 875   low_buf = g_queue_peek_tail (jbuf->packets);
 876
 877   if (!high_buf || !low_buf || high_buf == low_buf)
 878     return 0;
 879
 880   gst_rtp_buffer_map (high_buf, GST_MAP_READ, &rtp);
 881   high_ts = gst_rtp_buffer_get_timestamp (&rtp);
 882   gst_rtp_buffer_unmap (&rtp);
 883   gst_rtp_buffer_map (low_buf, GST_MAP_READ, &rtp);
 884   low_ts = gst_rtp_buffer_get_timestamp (&rtp);
 885   gst_rtp_buffer_unmap (&rtp);
 886
 887   /* it needs to work if ts wraps */
 888   if (high_ts >= low_ts) {
 889     result = (guint32) (high_ts - low_ts);
 890   } else {
 891     result = (guint32) (high_ts + G_MAXUINT32 + 1 - low_ts);
 892   }
 893   return result;
 894 }
 895
 896 /**
 897  * rtp_jitter_buffer_get_sync:
 898  * @jbuf: an #RTPJitterBuffer
 899  * @rtptime: result RTP time
 900  * @timestamp: result GStreamer timestamp
 901  * @clock_rate: clock-rate of @rtptime
 902  * @last_rtptime: last seen rtptime.
 903  *
 904  * Calculates the relation between the RTP timestamp and the GStreamer timestamp
 905  * used for constructing timestamps.
 906  *
 907  * For extended RTP timestamp @rtptime with a clock-rate of @clock_rate,
 908  * the GStreamer timestamp is currently @timestamp.
 909  *
 910  * The last seen extended RTP timestamp with clock-rate @clock-rate is returned in
 911  * @last_rtptime.
 912  */
 913 void
 914 rtp_jitter_buffer_get_sync (RTPJitterBuffer * jbuf, guint64 * rtptime,
 915     guint64 * timestamp, guint32 * clock_rate, guint64 * last_rtptime)
 916 {
 917   if (rtptime)
 918     *rtptime = jbuf->base_extrtp;
 919   if (timestamp)
 920     *timestamp = jbuf->base_time + jbuf->skew;
 921   if (clock_rate)
 922     *clock_rate = jbuf->clock_rate;
 923   if (last_rtptime)
 924     *last_rtptime = jbuf->last_rtptime;
 925 }