Thu Jul 9 13:41:22 2009

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

configuration constants

#define JB_ADJUST_DELAY   40
#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_HISTORY_SZ   500
#define JB_TARGET_EXTRA   40

Typedefs

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

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
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.
enum jb_return_code jb_getall (jitterbuf *jb, jb_frame *frameout)
 unconditionally get frames from jitterbuf until empty
enum jb_return_code jb_getinfo (jitterbuf *jb, jb_info *stats)
 get jitterbuf info: only "statistics" may be valid
jitterbufjb_new (void)
 new jitterbuf
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)
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
void jb_reset (jitterbuf *jb)
 reset jitterbuf
enum jb_return_code jb_setconf (jitterbuf *jb, jb_conf *conf)
 set jitterbuf conf
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.


Define 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(), 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 void(*) jb_output_function_t(const char *fmt,...)

Definition at line 166 of file jitterbuf.h.


Enumeration Type Documentation

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

00057                    {
00058    /* frame types */
00059    JB_TYPE_CONTROL,  /*!< 0            */
00060    JB_TYPE_VOICE,    /*!< 1            */
00061    JB_TYPE_VIDEO,    /*!< 2 - reserved */
00062    JB_TYPE_SILENCE   /*!< 3            */
00063 };

enum jb_return_code

Enumerator:
JB_OK 
JB_EMPTY 
JB_NOFRAME 
JB_INTERP 
JB_DROP 
JB_SCHED 

Definition at line 47 of file jitterbuf.h.

00047                     {
00048    /* return codes */
00049    JB_OK,            /* 0 */
00050    JB_EMPTY,         /* 1 */
00051    JB_NOFRAME,       /* 2 */
00052    JB_INTERP,        /* 3 */
00053    JB_DROP,          /* 4 */
00054    JB_SCHED          /* 5 */
00055 };


Function Documentation

void jb_destroy ( jitterbuf jb  ) 

destroy jitterbuf

Definition at line 95 of file jitterbuf.c.

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

Referenced by jb_destroy_adaptive(), and pvt_destructor().

00096 {
00097    jb_frame *frame; 
00098    jb_dbg2("jb_destroy(%x)\n", jb);
00099 
00100    /* free all the frames on the "free list" */
00101    frame = jb->free;
00102    while (frame != NULL) {
00103       jb_frame *next = frame->next;
00104       ast_free(frame);
00105       frame = next;
00106    }
00107 
00108    /* free ourselves! */ 
00109    ast_free(jb);
00110 }

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

00790 {
00791    enum jb_return_code ret = _jb_get(jb, frameout, now, interpl);
00792 #if 0
00793    static int lastts=0;
00794    int thists = ((ret == JB_OK) || (ret == JB_DROP)) ? frameout->ts : 0;
00795    jb_warn("jb_get(%x,%x,%ld) = %d (%d)\n", jb, frameout, now, ret, thists);
00796    if (thists && thists < lastts) jb_warn("XXXX timestamp roll-back!!!\n");
00797    lastts = thists;
00798 #endif
00799    if (ret == JB_INTERP) 
00800       frameout->ms = jb->info.last_voice_ms;
00801    
00802    return ret;
00803 }

enum jb_return_code jb_getall ( jitterbuf jb,
jb_frame frameout 
)

unconditionally get frames from jitterbuf until empty

Definition at line 805 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().

00806 {
00807    jb_frame *frame;
00808    frame = queue_getall(jb);
00809 
00810    if (!frame) {
00811       return JB_NOFRAME;
00812    }
00813 
00814    *frameout = *frame;
00815    return JB_OK;
00816 }

enum jb_return_code jb_getinfo ( jitterbuf jb,
jb_info stats 
)

get jitterbuf info: only "statistics" may be valid

Definition at line 819 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().

00820 {
00821 
00822    history_get(jb);
00823 
00824    *stats = jb->info;
00825 
00826    return JB_OK;
00827 }

jitterbuf* jb_new ( void   ) 

new jitterbuf

Definition at line 82 of file jitterbuf.c.

References ast_malloc, jb_dbg2, and jb_reset().

Referenced by jb_create_adaptive(), and new_iax().

00083 {
00084    jitterbuf *jb;
00085 
00086    if (!(jb = ast_malloc(sizeof(*jb)))) 
00087       return NULL;
00088 
00089    jb_reset(jb);
00090 
00091    jb_dbg2("jb_new() = %x\n", jb);
00092    return jb;
00093 }

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

00772 {
00773    if (jb->info.silence_begin_ts) {
00774       if (jb->frames) {
00775          long next = queue_next(jb);
00776          history_get(jb);
00777          /* shrink during silence */
00778          if (jb->info.target - jb->info.current < -jb->info.conf.target_extra)
00779             return jb->info.last_adjustment + 10;
00780          return next + jb->info.target;
00781       }
00782       else 
00783          return JB_LONGMAX;
00784    } else {
00785       return jb->info.next_voice_ts;
00786    }
00787 }

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 508 of file jitterbuf.c.

References ast_debug, jb_info::conf, jitterbuf::dropem, jitterbuf::frames, jb_info::frames_dropped, jb_info::frames_in, history_put(), jitterbuf::info, jb_dbg2, JB_DROP, JB_OK, JB_SCHED, JB_TYPE_VOICE, jb_conf::max_jitterbuf, jb_frame::prev, queue_put(), and jb_frame::ts.

Referenced by jb_put_adaptive(), and schedule_delivery().

00509 {
00510    long numts;
00511 
00512    jb_dbg2("jb_put(%x,%x,%ld,%ld,%ld)\n", jb, data, ms, ts, now);
00513 
00514    numts = 0;
00515    if (jb->frames)
00516       numts = jb->frames->prev->ts - jb->frames->ts;
00517 
00518    if (numts >= jb->info.conf.max_jitterbuf) {
00519       if (!jb->dropem) {
00520          ast_debug(1, "Attempting to exceed Jitterbuf max %ld timeslots\n",
00521             jb->info.conf.max_jitterbuf);
00522          jb->dropem = 1;
00523       }
00524       jb->info.frames_dropped++;
00525       return JB_DROP;
00526    } else {
00527       jb->dropem = 0;
00528    }
00529 
00530    if (type == JB_TYPE_VOICE) {
00531       /* presently, I'm only adding VOICE frames to history and drift calculations; mostly because with the
00532        * IAX integrations, I'm sending retransmitted control frames with their awkward timestamps through */
00533       if (history_put(jb,ts,now,ms)) {
00534          jb->info.frames_dropped++;
00535          return JB_DROP;
00536       }
00537    }
00538 
00539    jb->info.frames_in++;
00540 
00541    /* if put into head of queue, caller needs to reschedule */
00542    if (queue_put(jb,data,type,ms,ts)) {
00543       return JB_SCHED;
00544    }
00545    return JB_OK;
00546 }

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 70 of file jitterbuf.c.

References jb_info::conf, jitterbuf::info, JB_TARGET_EXTRA, and s.

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

00071 {
00072    /* only save settings */
00073    jb_conf s = jb->info.conf;
00074    memset(jb, 0, sizeof(*jb));
00075    jb->info.conf = s;
00076 
00077    /* initialize length, using the default value */
00078    jb->info.current = jb->info.target = jb->info.conf.target_extra = JB_TARGET_EXTRA;
00079    jb->info.silence_begin_ts = -1; 
00080 }

enum jb_return_code jb_setconf ( jitterbuf jb,
jb_conf conf 
)

set jitterbuf conf

Definition at line 829 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().

00830 {
00831    /* take selected settings from the struct */
00832 
00833    jb->info.conf.max_jitterbuf = conf->max_jitterbuf;
00834    jb->info.conf.resync_threshold = conf->resync_threshold;
00835    jb->info.conf.max_contig_interp = conf->max_contig_interp;
00836 
00837    /* -1 indicates use of the default JB_TARGET_EXTRA value */
00838    jb->info.conf.target_extra = ( conf->target_extra == -1 )
00839       ? JB_TARGET_EXTRA
00840       : conf->target_extra
00841       ;
00842       
00843    /* update these to match new target_extra setting */
00844    jb->info.current = jb->info.conf.target_extra;
00845    jb->info.target = jb->info.conf.target_extra;
00846 
00847    return JB_OK;
00848 }

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

Definition at line 53 of file jitterbuf.c.

Referenced by handle_cli_iax2_set_debug_jb(), handle_cli_iax2_set_debug_jb_deprecated(), and load_module().

00054 {
00055    errf = err;
00056    warnf = warn;
00057    dbgf = dbg;
00058 }


Generated on Thu Jul 9 13:41:22 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7