Asterisk - The Open Source Telephony Project  GIT-master-a1fa8df
Data Structures | Typedefs | Enumerations | Functions
jitterbuf.h File Reference

jitterbuf: an application-independent jitterbuffer jitterbuf.c More...

Go to the source code of this file.

Data Structures

struct  jb_conf
 
struct  jb_frame
 
struct  jb_info
 
struct  jitterbuf
 

Macros

configuration constants
#define JB_HISTORY_SZ   500
 
#define JB_HISTORY_DROPPCT   3
 
#define JB_HISTORY_DROPPCT_MAX   4
 
#define JB_HISTORY_MAXBUF_SZ   JB_HISTORY_SZ * JB_HISTORY_DROPPCT_MAX / 100
 
#define JB_TARGET_EXTRA   40
 
#define JB_ADJUST_DELAY   40
 

Typedefs

typedef struct jb_conf jb_conf
 
typedef struct jb_frame jb_frame
 
typedef struct jb_info jb_info
 
typedef void(* jb_output_function_t) (const char *fmt,...)
 
typedef struct jitterbuf jitterbuf
 

Enumerations

enum  jb_frame_type { JB_TYPE_CONTROL, JB_TYPE_VOICE, JB_TYPE_VIDEO, JB_TYPE_SILENCE }
 
enum  jb_return_code {
  JB_OK, JB_EMPTY, JB_NOFRAME, JB_INTERP,
  JB_DROP, JB_SCHED
}
 

Functions

void jb_destroy (jitterbuf *jb)
 destroy jitterbuf More...
 
enum jb_return_code jb_get (jitterbuf *jb, jb_frame *frame, long now, long interpl)
 get a frame for time now (receiver's time) return value is one of JB_OK: You've got frame! JB_DROP: Here's an audio frame you should just drop. Ask me again for this time.. JB_NOFRAME: There's no frame scheduled for this time. JB_INTERP: Please interpolate an interpl-length frame for this time (either we need to grow, or there was a lost frame) JB_EMPTY: The jb is empty. More...
 
enum jb_return_code jb_getall (jitterbuf *jb, jb_frame *frameout)
 unconditionally get frames from jitterbuf until empty More...
 
enum jb_return_code jb_getinfo (jitterbuf *jb, jb_info *stats)
 get jitterbuf info: only "statistics" may be valid More...
 
int jb_is_late (jitterbuf *jb, long ts)
 Checks if the given time stamp is late. More...
 
jitterbufjb_new (void)
 new jitterbuf More...
 
long jb_next (jitterbuf *jb)
 when is the next frame due out, in receiver's time (0=EMPTY) This value may change as frames are added (esp non-audio frames) More...
 
enum jb_return_code jb_put (jitterbuf *jb, void *data, const enum jb_frame_type type, long ms, long ts, long now)
 queue a frame More...
 
void jb_reset (jitterbuf *jb)
 reset jitterbuf More...
 
enum jb_return_code jb_setconf (jitterbuf *jb, jb_conf *conf)
 set jitterbuf conf More...
 
void jb_setoutput (jb_output_function_t err, jb_output_function_t warn, jb_output_function_t dbg)
 

Detailed Description

jitterbuf: an application-independent jitterbuffer jitterbuf.c

Definition in file jitterbuf.h.

Macro Definition Documentation

◆ JB_ADJUST_DELAY

#define JB_ADJUST_DELAY   40

ms between growing and shrinking; may not be honored if jitterbuffer runs out of space

Definition at line 44 of file jitterbuf.h.

Referenced by _jb_get().

◆ JB_HISTORY_DROPPCT

#define JB_HISTORY_DROPPCT   3

what percentage of timestamps should we drop from the history when we examine it; this might eventually be something made configurable

Definition at line 36 of file jitterbuf.h.

Referenced by history_get().

◆ JB_HISTORY_DROPPCT_MAX

#define JB_HISTORY_DROPPCT_MAX   4

the maximum droppct we can handle (say it was configurable).

Definition at line 38 of file jitterbuf.h.

◆ JB_HISTORY_MAXBUF_SZ

#define JB_HISTORY_MAXBUF_SZ   JB_HISTORY_SZ * JB_HISTORY_DROPPCT_MAX / 100

the size of the buffer we use to keep the top and botton timestamps for dropping

Definition at line 40 of file jitterbuf.h.

Referenced by history_calc_maxbuf(), history_get(), and history_put().

◆ JB_HISTORY_SZ

#define JB_HISTORY_SZ   500

Number of historical timestamps to use in calculating jitter and drift

Definition at line 33 of file jitterbuf.h.

Referenced by history_calc_maxbuf(), history_get(), and history_put().

◆ JB_TARGET_EXTRA

#define JB_TARGET_EXTRA   40

amount of additional jitterbuffer adjustment

Definition at line 42 of file jitterbuf.h.

Referenced by jb_reset(), and jb_setconf().

Typedef Documentation

◆ jb_conf

typedef struct jb_conf jb_conf

◆ jb_frame

typedef struct jb_frame jb_frame

◆ jb_info

typedef struct jb_info jb_info

◆ jb_output_function_t

typedef void(* jb_output_function_t) (const char *fmt,...)

Definition at line 166 of file jitterbuf.h.

◆ jitterbuf

typedef struct jitterbuf jitterbuf

Enumeration Type Documentation

◆ jb_frame_type

Enumerator
JB_TYPE_CONTROL 

0

JB_TYPE_VOICE 

1

JB_TYPE_VIDEO 

2 - reserved

JB_TYPE_SILENCE 

3

Definition at line 57 of file jitterbuf.h.

57  {
58  /* frame types */
59  JB_TYPE_CONTROL, /*!< 0 */
60  JB_TYPE_VOICE, /*!< 1 */
61  JB_TYPE_VIDEO, /*!< 2 - reserved */
62  JB_TYPE_SILENCE /*!< 3 */
63 };

◆ jb_return_code

Enumerator
JB_OK 
JB_EMPTY 
JB_NOFRAME 
JB_INTERP 
JB_DROP 
JB_SCHED 

Definition at line 47 of file jitterbuf.h.

47  {
48  /* return codes */
49  JB_OK, /* 0 */
50  JB_EMPTY, /* 1 */
51  JB_NOFRAME, /* 2 */
52  JB_INTERP, /* 3 */
53  JB_DROP, /* 4 */
54  JB_SCHED /* 5 */
55 };

Function Documentation

◆ jb_destroy()

void jb_destroy ( jitterbuf jb)

destroy jitterbuf

Definition at line 99 of file jitterbuf.c.

References ast_free, jitterbuf::free, jb_dbg2, jb_frame::next, and NULL.

Referenced by AST_TEST_DEFINE(), jb_destroy_adaptive(), and pvt_destructor().

100 {
101  jb_frame *frame;
102  jb_dbg2("jb_destroy(%x)\n", jb);
103 
104  /* free all the frames on the "free list" */
105  frame = jb->free;
106  while (frame != NULL) {
107  jb_frame *next = frame->next;
108  ast_free(frame);
109  frame = next;
110  }
111 
112  /* free ourselves! */
113  ast_free(jb);
114 }
#define jb_dbg2(...)
Definition: jitterbuf.c:50
#define NULL
Definition: resample.c:96
jb_frame * free
Definition: jitterbuf.h:119
#define ast_free(a)
Definition: astmm.h:182
struct jb_frame * next
Definition: jitterbuf.h:104

◆ jb_get()

enum jb_return_code jb_get ( jitterbuf jb,
jb_frame frame,
long  now,
long  interpl 
)

get a frame for time now (receiver's time) return value is one of JB_OK: You've got frame! JB_DROP: Here's an audio frame you should just drop. Ask me again for this time.. JB_NOFRAME: There's no frame scheduled for this time. JB_INTERP: Please interpolate an interpl-length frame for this time (either we need to grow, or there was a lost frame) JB_EMPTY: The jb is empty.

Definition at line 785 of file jitterbuf.c.

References _jb_get(), jitterbuf::info, JB_DROP, JB_INTERP, JB_OK, jb_warn, jb_info::last_voice_ms, jb_frame::ms, and jb_frame::ts.

Referenced by __get_from_jb(), AST_TEST_DEFINE(), and jb_get_adaptive().

786 {
787  enum jb_return_code ret = _jb_get(jb, frameout, now, interpl);
788 #if 0
789  static int lastts=0;
790  int thists = ((ret == JB_OK) || (ret == JB_DROP)) ? frameout->ts : 0;
791  jb_warn("jb_get(%x,%x,%ld) = %d (%d)\n", jb, frameout, now, ret, thists);
792  if (thists && thists < lastts) jb_warn("XXXX timestamp roll-back!!!\n");
793  lastts = thists;
794 #endif
795  if (ret == JB_INTERP)
796  frameout->ms = jb->info.last_voice_ms;
797 
798  return ret;
799 }
jb_return_code
Definition: jitterbuf.h:47
jb_info info
Definition: jitterbuf.h:108
long last_voice_ms
Definition: jitterbuf.h:90
static enum jb_return_code _jb_get(jitterbuf *jb, jb_frame *frameout, long now, long interpl)
Definition: jitterbuf.c:550
#define jb_warn(...)
Definition: jitterbuf.c:43

◆ jb_getall()

enum jb_return_code jb_getall ( jitterbuf jb,
jb_frame frameout 
)

unconditionally get frames from jitterbuf until empty

Definition at line 801 of file jitterbuf.c.

References JB_NOFRAME, JB_OK, and queue_getall().

Referenced by AST_TEST_DEFINE(), complete_transfer(), jb_empty_and_reset_adaptive(), jb_remove_adaptive(), and pvt_destructor().

802 {
803  jb_frame *frame;
804  frame = queue_getall(jb);
805 
806  if (!frame) {
807  return JB_NOFRAME;
808  }
809 
810  *frameout = *frame;
811  return JB_OK;
812 }
static jb_frame * queue_getall(jitterbuf *jb)
Definition: jitterbuf.c:454

◆ jb_getinfo()

enum jb_return_code jb_getinfo ( jitterbuf jb,
jb_info stats 
)

get jitterbuf info: only "statistics" may be valid

Definition at line 815 of file jitterbuf.c.

References history_get(), jitterbuf::info, and JB_OK.

Referenced by ast_cli_netstats(), AST_TEST_DEFINE(), construct_rr(), handle_cli_iax2_show_channels(), and log_jitterstats().

816 {
817 
818  history_get(jb);
819 
820  *stats = jb->info;
821 
822  return JB_OK;
823 }
jb_info info
Definition: jitterbuf.h:108
static void history_get(jitterbuf *jb)
Definition: jitterbuf.c:295

◆ jb_is_late()

int jb_is_late ( jitterbuf jb,
long  ts 
)

Checks if the given time stamp is late.

Definition at line 846 of file jitterbuf.c.

References jb_info::current, jitterbuf::info, and jb_info::next_voice_ts.

Referenced by jb_is_late_adaptive().

847 {
848  return ts + jb->info.current < jb->info.next_voice_ts;
849 }
jb_info info
Definition: jitterbuf.h:108
long next_voice_ts
Definition: jitterbuf.h:89
long current
Definition: jitterbuf.h:86

◆ jb_new()

jitterbuf* jb_new ( void  )

new jitterbuf

Definition at line 86 of file jitterbuf.c.

References ast_calloc, jb_dbg2, jb_reset(), and NULL.

Referenced by AST_TEST_DEFINE(), jb_create_adaptive(), and new_iax().

87 {
88  jitterbuf *jb;
89 
90  if (!(jb = ast_calloc(1, sizeof(*jb))))
91  return NULL;
92 
93  jb_reset(jb);
94 
95  jb_dbg2("jb_new() = %x\n", jb);
96  return jb;
97 }
#define jb_dbg2(...)
Definition: jitterbuf.c:50
#define NULL
Definition: resample.c:96
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:204
void jb_reset(jitterbuf *jb)
reset jitterbuf
Definition: jitterbuf.c:72

◆ jb_next()

long jb_next ( jitterbuf jb)

when is the next frame due out, in receiver's time (0=EMPTY) This value may change as frames are added (esp non-audio frames)

Definition at line 767 of file jitterbuf.c.

References jb_info::conf, jb_info::current, jitterbuf::frames, history_get(), jitterbuf::info, JB_LONGMAX, jb_info::last_adjustment, jb_info::next_voice_ts, queue_next(), jb_info::silence_begin_ts, jb_info::target, and jb_conf::target_extra.

Referenced by __get_from_jb(), AST_TEST_DEFINE(), jb_next_adaptive(), and update_jbsched().

768 {
769  if (jb->info.silence_begin_ts) {
770  if (jb->frames) {
771  long next = queue_next(jb);
772  history_get(jb);
773  /* shrink during silence */
774  if (jb->info.target - jb->info.current < -jb->info.conf.target_extra)
775  return jb->info.last_adjustment + 10;
776  return next + jb->info.target;
777  }
778  else
779  return JB_LONGMAX;
780  } else {
781  return jb->info.next_voice_ts;
782  }
783 }
long silence_begin_ts
Definition: jitterbuf.h:91
jb_frame * frames
Definition: jitterbuf.h:118
#define JB_LONGMAX
Definition: jitterbuf.c:40
long last_adjustment
Definition: jitterbuf.h:92
jb_info info
Definition: jitterbuf.h:108
long target_extra
Definition: jitterbuf.h:70
jb_conf conf
Definition: jitterbuf.h:74
long target
Definition: jitterbuf.h:87
static long queue_next(jitterbuf *jb)
Definition: jitterbuf.c:398
long next_voice_ts
Definition: jitterbuf.h:89
static void history_get(jitterbuf *jb)
Definition: jitterbuf.c:295
long current
Definition: jitterbuf.h:86

◆ jb_put()

enum jb_return_code jb_put ( jitterbuf jb,
void *  data,
const enum jb_frame_type  type,
long  ms,
long  ts,
long  now 
)

queue a frame

data=frame data, timings (in ms): ms=length of frame (for voice), ts=ts (sender's time) now=now (in receiver's time) return value is one of JB_OK: Frame added. Last call to jb_next() still valid JB_DROP: Drop this frame immediately JB_SCHED: Frame added. Call jb_next() to get a new time for the next frame

Definition at line 525 of file jitterbuf.c.

References check_resync(), jb_info::frames_in, history_put(), jitterbuf::info, jb_dbg2, JB_DROP, JB_OK, JB_SCHED, JB_TYPE_VOICE, queue_put(), and jb_info::resync_offset.

Referenced by jb_put_adaptive(), schedule_delivery(), test_jb_late_frame_insertion(), test_jb_lost_frame_insertion(), test_jb_nominal_frame_insertion(), test_jb_out_of_order_frame_insertion(), test_jb_overflow_frame_insertion(), and test_jb_resynch_frame_insertion().

526 {
527  long delay = now - (ts - jb->info.resync_offset);
528  jb_dbg2("jb_put(%x,%x,%ld,%ld,%ld)\n", jb, data, ms, ts, now);
529 
530  if (check_resync(jb, ts, now, ms, type, &delay)) {
531  return JB_DROP;
532  }
533 
534  if (type == JB_TYPE_VOICE) {
535  /* presently, I'm only adding VOICE frames to history and drift calculations; mostly because with the
536  * IAX integrations, I'm sending retransmitted control frames with their awkward timestamps through */
537  history_put(jb, ts, now, ms, delay);
538  }
539 
540  jb->info.frames_in++;
541 
542  /* if put into head of queue, caller needs to reschedule */
543  if (queue_put(jb,data,type,ms,ts)) {
544  return JB_SCHED;
545  }
546  return JB_OK;
547 }
static const char type[]
Definition: chan_ooh323.c:109
#define jb_dbg2(...)
Definition: jitterbuf.c:50
long frames_in
Definition: jitterbuf.h:77
static int history_put(jitterbuf *jb, long ts, long now, long ms, long delay)
Definition: jitterbuf.c:163
static int queue_put(jitterbuf *jb, void *data, const enum jb_frame_type type, long ms, long ts)
Definition: jitterbuf.c:337
jb_info info
Definition: jitterbuf.h:108
long resync_offset
Definition: jitterbuf.h:95
static int check_resync(jitterbuf *jb, long ts, long now, long ms, const enum jb_frame_type type, long *delay)
Definition: jitterbuf.c:116

◆ jb_reset()

void jb_reset ( jitterbuf jb)

reset jitterbuf

Note
The jitterbuffer should be empty before you call this, otherwise you will leak queued frames, and some internal structures

Definition at line 72 of file jitterbuf.c.

References jb_info::conf, jb_info::current, jitterbuf::free, jitterbuf::info, JB_TARGET_EXTRA, jb_info::silence_begin_ts, jb_info::target, and jb_conf::target_extra.

Referenced by complete_transfer(), jb_empty_and_reset_adaptive(), and jb_new().

73 {
74  /* only save settings and free list */
75  jb_conf s = jb->info.conf;
76  jb_frame *fr = jb->free;
77  memset(jb, 0, sizeof(*jb));
78  jb->info.conf = s;
79  jb->free = fr;
80 
81  /* initialize length, using the default value */
83  jb->info.silence_begin_ts = -1;
84 }
#define JB_TARGET_EXTRA
Definition: jitterbuf.h:42
long silence_begin_ts
Definition: jitterbuf.h:91
jb_frame * free
Definition: jitterbuf.h:119
jb_info info
Definition: jitterbuf.h:108
long target_extra
Definition: jitterbuf.h:70
jb_conf conf
Definition: jitterbuf.h:74
long target
Definition: jitterbuf.h:87
long current
Definition: jitterbuf.h:86

◆ jb_setconf()

enum jb_return_code jb_setconf ( jitterbuf jb,
jb_conf conf 
)

set jitterbuf conf

Definition at line 825 of file jitterbuf.c.

References jb_info::conf, jb_info::current, jitterbuf::info, JB_OK, JB_TARGET_EXTRA, jb_conf::max_contig_interp, jb_conf::max_jitterbuf, jb_conf::resync_threshold, jb_info::target, and jb_conf::target_extra.

Referenced by AST_TEST_DEFINE(), jb_create_adaptive(), and new_iax().

826 {
827  /* take selected settings from the struct */
828 
829  jb->info.conf.max_jitterbuf = conf->max_jitterbuf;
832 
833  /* -1 indicates use of the default JB_TARGET_EXTRA value */
834  jb->info.conf.target_extra = ( conf->target_extra == -1 )
836  : conf->target_extra
837  ;
838 
839  /* update these to match new target_extra setting */
840  jb->info.current = jb->info.conf.target_extra;
841  jb->info.target = jb->info.conf.target_extra;
842 
843  return JB_OK;
844 }
long max_jitterbuf
Definition: jitterbuf.h:67
#define JB_TARGET_EXTRA
Definition: jitterbuf.h:42
long resync_threshold
Definition: jitterbuf.h:68
jb_info info
Definition: jitterbuf.h:108
long target_extra
Definition: jitterbuf.h:70
jb_conf conf
Definition: jitterbuf.h:74
long target
Definition: jitterbuf.h:87
long current
Definition: jitterbuf.h:86
long max_contig_interp
Definition: jitterbuf.h:69

◆ jb_setoutput()

void jb_setoutput ( jb_output_function_t  err,
jb_output_function_t  warn,
jb_output_function_t  dbg 
)

Definition at line 55 of file jitterbuf.c.

References dbgf, errf, and warnf.

Referenced by handle_cli_iax2_set_debug_jb(), and load_module().

56 {
57  errf = err;
58  warnf = warn;
59  dbgf = dbg;
60 }
static jb_output_function_t dbgf
Definition: jitterbuf.c:53
static jb_output_function_t warnf
Definition: jitterbuf.c:53
static jb_output_function_t errf
Definition: jitterbuf.c:53