gst/rtpmanager/rtpjitterbuffer.h

   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
  20 #ifndef __RTP_JITTER_BUFFER_H__
  21 #define __RTP_JITTER_BUFFER_H__
  22
  23 #include <gst/gst.h>
  24 #include <gst/rtp/gstrtcpbuffer.h>
  25
  26 typedef struct _RTPJitterBuffer RTPJitterBuffer;
  27 typedef struct _RTPJitterBufferClass RTPJitterBufferClass;
  28 typedef struct _RTPJitterBufferItem RTPJitterBufferItem;
  29
  30 #define RTP_TYPE_JITTER_BUFFER             (rtp_jitter_buffer_get_type())
  31 #define RTP_JITTER_BUFFER(src)             (G_TYPE_CHECK_INSTANCE_CAST((src),RTP_TYPE_JITTER_BUFFER,RTPJitterBuffer))
  32 #define RTP_JITTER_BUFFER_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass),RTP_TYPE_JITTER_BUFFER,RTPJitterBufferClass))
  33 #define RTP_IS_JITTER_BUFFER(src)          (G_TYPE_CHECK_INSTANCE_TYPE((src),RTP_TYPE_JITTER_BUFFER))
  34 #define RTP_IS_JITTER_BUFFER_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass),RTP_TYPE_JITTER_BUFFER))
  35 #define RTP_JITTER_BUFFER_CAST(src)        ((RTPJitterBuffer *)(src))
  36
  37 /**
  38  * RTPJitterBufferMode:
  39  * @RTP_JITTER_BUFFER_MODE_NONE: don't do any skew correction, outgoing
  40  *    timestamps are calculated directly from the RTP timestamps. This mode is
  41  *    good for recording but not for real-time applications.
  42  * @RTP_JITTER_BUFFER_MODE_SLAVE: calculate the skew between sender and receiver
  43  *    and produce smoothed adjusted outgoing timestamps. This mode is good for
  44  *    low latency communications.
  45  * @RTP_JITTER_BUFFER_MODE_BUFFER: buffer packets between low/high watermarks.
  46  *    This mode is good for streaming communication.
  47  * @RTP_JITTER_BUFFER_MODE_SYNCED: sender and receiver clocks are synchronized,
  48  *    like #RTP_JITTER_BUFFER_MODE_SLAVE but skew is assumed to be 0. Good for
  49  *    low latency communication when sender and receiver clocks are
  50  *    synchronized and there is thus no clock skew.
  51  * @RTP_JITTER_BUFFER_MODE_LAST: last buffer mode.
  52  *
  53  * The different buffer modes for a jitterbuffer.
  54  */
  55 typedef enum {
  56   RTP_JITTER_BUFFER_MODE_NONE    = 0,
  57   RTP_JITTER_BUFFER_MODE_SLAVE   = 1,
  58   RTP_JITTER_BUFFER_MODE_BUFFER  = 2,
  59   /* FIXME 3 is missing because it was used for 'auto' in jitterbuffer */
  60   RTP_JITTER_BUFFER_MODE_SYNCED  = 4,
  61   RTP_JITTER_BUFFER_MODE_LAST
  62 } RTPJitterBufferMode;
  63
  64 #define RTP_TYPE_JITTER_BUFFER_MODE (rtp_jitter_buffer_mode_get_type())
  65 GType rtp_jitter_buffer_mode_get_type (void);
  66
  67 #define RTP_JITTER_BUFFER_MAX_WINDOW 512
  68 /**
  69  * RTPJitterBuffer:
  70  *
  71  * A JitterBuffer in the #RTPSession
  72  */
  73 struct _RTPJitterBuffer {
  74   GObject        object;
  75
  76   GQueue         packets;
  77
  78   RTPJitterBufferMode mode;
  79
  80   GstClockTime   delay;
  81
  82   /* for buffering */
  83   gboolean          buffering;
  84   guint64           low_level;
  85   guint64           high_level;
  86
  87   /* for calculating skew */
  88   gboolean       need_resync;
  89   GstClockTime   base_time;
  90   GstClockTime   base_rtptime;
  91   GstClockTime   media_clock_base_time;
  92   guint32        clock_rate;
  93   GstClockTime   base_extrtp;
  94   GstClockTime   prev_out_time;
  95   guint64        ext_rtptime;
  96   guint64        last_rtptime;
  97   gint64         window[RTP_JITTER_BUFFER_MAX_WINDOW];
  98   guint          window_pos;
  99   guint          window_size;
 100   gboolean       window_filling;
 101   gint64         window_min;
 102   gint64         skew;
 103   gint64         prev_send_diff;
 104   gboolean       buffering_disabled;
 105
 106   GMutex         clock_lock;
 107   GstClock      *pipeline_clock;
 108   GstClock      *media_clock;
 109   gulong         media_clock_synced_id;
 110   guint64        media_clock_offset;
 111
 112   gboolean       rfc7273_sync;
 113 };
 114
 115 struct _RTPJitterBufferClass {
 116   GObjectClass   parent_class;
 117 };
 118
 119 #define IS_DROPABLE(it) (((it)->type == ITEM_TYPE_BUFFER) || ((it)->type == ITEM_TYPE_LOST))
 120 #define ITEM_TYPE_BUFFER        0
 121 #define ITEM_TYPE_LOST          1
 122 #define ITEM_TYPE_EVENT         2
 123 #define ITEM_TYPE_QUERY         3
 124
 125 /**
 126  * RTPJitterBufferItem:
 127  * @data: the data of the item
 128  * @next: pointer to next item
 129  * @prev: pointer to previous item
 130  * @type: the type of @data, used freely by caller
 131  * @dts: input DTS
 132  * @pts: output PTS
 133  * @seqnum: seqnum, the seqnum is used to insert the item in the
 134  *   right position in the jitterbuffer and detect duplicates. Use -1 to
 135  *   append.
 136  * @count: amount of seqnum in this item
 137  * @rtptime: rtp timestamp
 138  * @data_free: Function to free @data (optional)
 139  *
 140  * An object containing an RTP packet or event. First members of this structure
 141  * copied from GList so they can be inserted into lists without doing more
 142  * allocations.
 143  */
 144 struct _RTPJitterBufferItem {
 145   /* a GList */
 146   gpointer data;
 147   GList *next;
 148   GList *prev;
 149
 150   /* item metadata */
 151   guint type;
 152   GstClockTime dts;
 153   GstClockTime pts;
 154   guint seqnum;
 155   guint count;
 156   guint rtptime;
 157
 158   GDestroyNotify free_data;
 159 };
 160
 161 GType rtp_jitter_buffer_get_type (void);
 162
 163 /* managing lifetime */
 164 RTPJitterBuffer*      rtp_jitter_buffer_new              (void);
 165
 166 RTPJitterBufferMode   rtp_jitter_buffer_get_mode         (RTPJitterBuffer *jbuf);
 167 void                  rtp_jitter_buffer_set_mode         (RTPJitterBuffer *jbuf, RTPJitterBufferMode mode);
 168
 169 GstClockTime          rtp_jitter_buffer_get_delay        (RTPJitterBuffer *jbuf);
 170 void                  rtp_jitter_buffer_set_delay        (RTPJitterBuffer *jbuf, GstClockTime delay);
 171
 172 void                  rtp_jitter_buffer_set_clock_rate   (RTPJitterBuffer *jbuf, guint32 clock_rate);
 173 guint32               rtp_jitter_buffer_get_clock_rate   (RTPJitterBuffer *jbuf);
 174
 175 void                  rtp_jitter_buffer_set_media_clock  (RTPJitterBuffer *jbuf, GstClock * clock, guint64 clock_offset);
 176 void                  rtp_jitter_buffer_set_pipeline_clock (RTPJitterBuffer *jbuf, GstClock * clock);
 177
 178 gboolean              rtp_jitter_buffer_get_rfc7273_sync (RTPJitterBuffer *jbuf);
 179 void                  rtp_jitter_buffer_set_rfc7273_sync (RTPJitterBuffer *jbuf, gboolean rfc7273_sync);
 180
 181 void                  rtp_jitter_buffer_reset_skew       (RTPJitterBuffer *jbuf);
 182
 183 gboolean              rtp_jitter_buffer_append_event      (RTPJitterBuffer * jbuf, GstEvent * event);
 184 gboolean              rtp_jitter_buffer_append_query      (RTPJitterBuffer * jbuf, GstQuery * query);
 185 gboolean              rtp_jitter_buffer_append_lost_event (RTPJitterBuffer * jbuf, GstEvent * event,
 186                                                            guint16 seqnum, guint lost_packets);
 187 gboolean              rtp_jitter_buffer_append_buffer     (RTPJitterBuffer * jbuf, GstBuffer * buf,
 188                                                            GstClockTime dts, GstClockTime pts,
 189                                                            guint16 seqnum, guint rtptime,
 190                                                            gboolean * duplicate, gint * percent);
 191
 192 void                  rtp_jitter_buffer_disable_buffering (RTPJitterBuffer *jbuf, gboolean disabled);
 193
 194 RTPJitterBufferItem * rtp_jitter_buffer_peek             (RTPJitterBuffer *jbuf);
 195 RTPJitterBufferItem * rtp_jitter_buffer_pop              (RTPJitterBuffer *jbuf, gint *percent);
 196
 197 void                  rtp_jitter_buffer_flush            (RTPJitterBuffer *jbuf,
 198                                                           GFunc free_func, gpointer user_data);
 199
 200 gboolean              rtp_jitter_buffer_is_buffering     (RTPJitterBuffer * jbuf);
 201 void                  rtp_jitter_buffer_set_buffering    (RTPJitterBuffer * jbuf, gboolean buffering);
 202 gint                  rtp_jitter_buffer_get_percent      (RTPJitterBuffer * jbuf);
 203
 204 guint                 rtp_jitter_buffer_num_packets      (RTPJitterBuffer *jbuf);
 205 guint32               rtp_jitter_buffer_get_ts_diff      (RTPJitterBuffer *jbuf);
 206
 207 void                  rtp_jitter_buffer_get_sync         (RTPJitterBuffer *jbuf, guint64 *rtptime,
 208                                                           guint64 *timestamp, guint32 *clock_rate,
 209                                                           guint64 *last_rtptime);
 210
 211 GstClockTime          rtp_jitter_buffer_calculate_pts    (RTPJitterBuffer * jbuf, GstClockTime dts, gboolean estimated_dts,
 212                                                           guint32 rtptime, GstClockTime base_time, gint gap,
 213                                                           gboolean is_rtx);
 214
 215 gboolean              rtp_jitter_buffer_can_fast_start   (RTPJitterBuffer * jbuf, gint num_packet);
 216
 217 gboolean              rtp_jitter_buffer_is_full          (RTPJitterBuffer * jbuf);
 218
 219 void                  rtp_jitter_buffer_free_item        (RTPJitterBufferItem * item);
 220
 221 #endif /* __RTP_JITTER_BUFFER_H__ */