diff options
Diffstat (limited to 'pjmedia/src/pjmedia-codec/speex/speex_jitter.h')
| -rw-r--r-- | pjmedia/src/pjmedia-codec/speex/speex_jitter.h | 68 |
1 files changed, 52 insertions, 16 deletions
diff --git a/pjmedia/src/pjmedia-codec/speex/speex_jitter.h b/pjmedia/src/pjmedia-codec/speex/speex_jitter.h index 34043b37..f42def83 100644 --- a/pjmedia/src/pjmedia-codec/speex/speex_jitter.h +++ b/pjmedia/src/pjmedia-codec/speex/speex_jitter.h @@ -35,6 +35,11 @@ #ifndef SPEEX_JITTER_H #define SPEEX_JITTER_H +/** @defgroup JitterBuffer JitterBuffer: Adaptive jitter buffer + * This is the jitter buffer that reorders UDP/RTP packets and adjusts the buffer size + * to maintain good quality and low latency. + * @{ + */ #include "speex.h" #include "speex_bits.h" @@ -43,33 +48,51 @@ extern "C" { #endif +/** Generic adaptive jitter buffer state */ struct JitterBuffer_; +/** Generic adaptive jitter buffer state */ typedef struct JitterBuffer_ JitterBuffer; +/** Definition of an incoming packet */ typedef struct _JitterBufferPacket JitterBufferPacket; +/** Definition of an incoming packet */ struct _JitterBufferPacket { - char *data; - spx_uint32_t len; - spx_uint32_t timestamp; - spx_uint32_t span; + char *data; /**< Data bytes contained in the packet */ + spx_uint32_t len; /**< Length of the packet in bytes */ + spx_uint32_t timestamp; /**< Timestamp for the packet */ + spx_uint32_t span; /**< Time covered by the packet (same units as timestamp) */ }; - +/** Packet has been retrieved */ #define JITTER_BUFFER_OK 0 +/** Packet is missing */ #define JITTER_BUFFER_MISSING 1 +/** Packet is incomplete (does not cover the entive tick */ #define JITTER_BUFFER_INCOMPLETE 2 +/** There was an error in the jitter buffer */ #define JITTER_BUFFER_INTERNAL_ERROR -1 +/** Invalid argument */ #define JITTER_BUFFER_BAD_ARGUMENT -2 -/** Initialise jitter buffer */ +/** Initialises jitter buffer + * + * @param tick Number of samples per "tick", i.e. the time period of the elements that will be retrieved + * @return Newly created jitter buffer state + */ JitterBuffer *jitter_buffer_init(int tick); -/** Reset jitter buffer */ +/** Restores jitter buffer to its original state + * + * @param jitter Jitter buffer state + */ void jitter_buffer_reset(JitterBuffer *jitter); -/** Destroy jitter buffer */ +/** Destroys jitter buffer + * + * @param jitter Jitter buffer state + */ void jitter_buffer_destroy(JitterBuffer *jitter); /** Put one packet into the jitter buffer */ @@ -84,17 +107,30 @@ int jitter_buffer_get_pointer_timestamp(JitterBuffer *jitter); /** Advance by one tick */ void jitter_buffer_tick(JitterBuffer *jitter); +/* @} */ + +/** @defgroup SpeexJitter SpeexJitter: Adaptive jitter buffer specifically for Speex + * This is the jitter buffer that reorders UDP/RTP packets and adjusts the buffer size + * to maintain good quality and low latency. This is a simplified version that works only + * with Speex, but is much easier to use. + * @{ + */ -/** Speex jitter-buffer state. */ +/** Speex jitter-buffer state. Never use it directly! */ typedef struct SpeexJitter { - SpeexBits current_packet; /**< Current Speex packet */ - int valid_bits; /**< True if Speex bits are valid */ - JitterBuffer *packets; - void *dec; /**< Pointer to Speex decoder */ - int frame_size; /**< Frame size of Speex decoder */ + SpeexBits current_packet; /**< Current Speex packet */ + int valid_bits; /**< True if Speex bits are valid */ + JitterBuffer *packets; /**< Generic jitter buffer state */ + void *dec; /**< Pointer to Speex decoder */ + spx_int32_t frame_size; /**< Frame size of Speex decoder */ } SpeexJitter; -/** Initialise jitter buffer */ +/** Initialise jitter buffer + * + * @param jitter State of the Speex jitter buffer + * @param decoder Speex decoder to call + * @param sampling_rate Sampling rate used by the decoder +*/ void speex_jitter_init(SpeexJitter *jitter, void *decoder, int sampling_rate); /** Destroy jitter buffer */ @@ -113,5 +149,5 @@ int speex_jitter_get_pointer_timestamp(SpeexJitter *jitter); } #endif - +/* @} */ #endif |