Wed Jan 8 2020 09:50:14

Asterisk developer's documentation


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...
 
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

#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().

#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().

#define JB_HISTORY_DROPPCT_MAX   4

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

Definition at line 38 of file jitterbuf.h.

#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().

#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().

#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

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,...)

Definition at line 166 of file jitterbuf.h.

typedef struct jitterbuf jitterbuf

Enumeration Type Documentation

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 };
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

void jb_destroy ( jitterbuf jb)

destroy jitterbuf

Definition at line 101 of file jitterbuf.c.

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

Referenced by jb_destroy_adaptive(), and pvt_destructor().

102 {
103  jb_frame *frame;
104  jb_dbg2("jb_destroy(%x)\n", jb);
105 
106  /* free all the frames on the "free list" */
107  frame = jb->free;
108  while (frame != NULL) {
109  jb_frame *next = frame->next;
110  ast_free(frame);
111  frame = next;
112  }
113 
114  /* free ourselves! */
115  ast_free(jb);
116 }
#define jb_dbg2(...)
Definition: jitterbuf.c:52
jb_frame * free
Definition: jitterbuf.h:119
#define ast_free(a)
Definition: astmm.h:97
struct jb_frame * next
Definition: jitterbuf.h:104
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 787 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(), and jb_get_adaptive().

788 {
789  enum jb_return_code ret = _jb_get(jb, frameout, now, interpl);
790 #if 0
791  static int lastts=0;
792  int thists = ((ret == JB_OK) || (ret == JB_DROP)) ? frameout->ts : 0;
793  jb_warn("jb_get(%x,%x,%ld) = %d (%d)\n", jb, frameout, now, ret, thists);
794  if (thists && thists < lastts) jb_warn("XXXX timestamp roll-back!!!\n");
795  lastts = thists;
796 #endif
797  if (ret == JB_INTERP)
798  frameout->ms = jb->info.last_voice_ms;
799 
800  return ret;
801 }
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:552
#define jb_warn(...)
Definition: jitterbuf.c:45
enum jb_return_code jb_getall ( jitterbuf jb,
jb_frame frameout 
)

unconditionally get frames from jitterbuf until empty

Definition at line 803 of file jitterbuf.c.

References JB_NOFRAME, JB_OK, and queue_getall().

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

804 {
805  jb_frame *frame;
806  frame = queue_getall(jb);
807 
808  if (!frame) {
809  return JB_NOFRAME;
810  }
811 
812  *frameout = *frame;
813  return JB_OK;
814 }
static jb_frame * queue_getall(jitterbuf *jb)
Definition: jitterbuf.c:456
enum jb_return_code jb_getinfo ( jitterbuf jb,
jb_info stats 
)

get jitterbuf info: only "statistics" may be valid

Definition at line 817 of file jitterbuf.c.

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

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

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

new jitterbuf

Definition at line 88 of file jitterbuf.c.

References ast_calloc, jb_dbg2, and jb_reset().

Referenced by jb_create_adaptive(), and new_iax().

89 {
90  jitterbuf *jb;
91 
92  if (!(jb = ast_calloc(1, sizeof(*jb))))
93  return NULL;
94 
95  jb_reset(jb);
96 
97  jb_dbg2("jb_new() = %x\n", jb);
98  return jb;
99 }
#define jb_dbg2(...)
Definition: jitterbuf.c:52
#define ast_calloc(a, b)
Definition: astmm.h:82
void jb_reset(jitterbuf *jb)
reset jitterbuf
Definition: jitterbuf.c:74
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 769 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(), jb_next_adaptive(), and update_jbsched().

770 {
771  if (jb->info.silence_begin_ts) {
772  if (jb->frames) {
773  long next = queue_next(jb);
774  history_get(jb);
775  /* shrink during silence */
776  if (jb->info.target - jb->info.current < -jb->info.conf.target_extra)
777  return jb->info.last_adjustment + 10;
778  return next + jb->info.target;
779  }
780  else
781  return JB_LONGMAX;
782  } else {
783  return jb->info.next_voice_ts;
784  }
785 }
long silence_begin_ts
Definition: jitterbuf.h:91
jb_frame * frames
Definition: jitterbuf.h:118
#define JB_LONGMAX
Definition: jitterbuf.c:42
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:400
long next_voice_ts
Definition: jitterbuf.h:89
static void history_get(jitterbuf *jb)
Definition: jitterbuf.c:297
long current
Definition: jitterbuf.h:86
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 527 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(), and schedule_delivery().

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

75 {
76  /* only save settings and free list */
77  jb_conf s = jb->info.conf;
78  jb_frame *fr = jb->free;
79  memset(jb, 0, sizeof(*jb));
80  jb->info.conf = s;
81  jb->free = fr;
82 
83  /* initialize length, using the default value */
85  jb->info.silence_begin_ts = -1;
86 }
#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
enum jb_return_code jb_setconf ( jitterbuf jb,
jb_conf conf 
)

set jitterbuf conf

Definition at line 827 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 jb_create_adaptive(), and new_iax().

828 {
829  /* take selected settings from the struct */
830 
831  jb->info.conf.max_jitterbuf = conf->max_jitterbuf;
834 
835  /* -1 indicates use of the default JB_TARGET_EXTRA value */
836  jb->info.conf.target_extra = ( conf->target_extra == -1 )
838  : conf->target_extra
839  ;
840 
841  /* update these to match new target_extra setting */
842  jb->info.current = jb->info.conf.target_extra;
843  jb->info.target = jb->info.conf.target_extra;
844 
845  return JB_OK;
846 }
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
void jb_setoutput ( jb_output_function_t  err,
jb_output_function_t  warn,
jb_output_function_t  dbg 
)

Definition at line 57 of file jitterbuf.c.

Referenced by handle_cli_iax2_set_debug_jb(), and load_module().

58 {
59  errf = err;
60  warnf = warn;
61  dbgf = dbg;
62 }
static jb_output_function_t dbgf
Definition: jitterbuf.c:55
static jb_output_function_t warnf
Definition: jitterbuf.c:55
static jb_output_function_t errf
Definition: jitterbuf.c:55