title: How to use the speex jitter buffer
body: <p>I am using the speex library to encode, decode and preprocess audio data. I think the speex library is very useful, but when I use the speex <strong>jitter buffer</strong>, I have some problems. 
  I use multi-thread, and one thread puts the received data into the jitter buffer and another thread gets the data from the active jitter buffer, sometimes the 'getting' thread can't get effective data especially when it is faster than the 'putting data' thread. In addition, I am using the mutex to protect the jitter buffer. </p>
  
  <p>I don't know how to use the jitter buffer exactly. I hope someone can help me.</p>
  
  <p>This is my code :</p>
  
  <pre><code>speex_jitter_buffer.h
  
  #include &lt;speex/speex_jitter.h&gt;
  #include &lt;speex/speex.h&gt;
  
  /** @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. Never use it directly! */
  typedef struct SpeexJitter {
     SpeexBits current_packet;         /**&lt; Current Speex packet */
     int valid_bits;                   /**&lt; True if Speex bits are valid */
     JitterBuffer *packets;            /**&lt; Generic jitter buffer state */
     void *dec;                        /**&lt; Pointer to Speex decoder */
     spx_int32_t frame_size;           /**&lt; Frame size of Speex decoder */
  } SpeexJitter;
  
  /** 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 */
  void speex_jitter_destroy(SpeexJitter *jitter);
  
  /** Put one packet into the jitter buffer */
  void speex_jitter_put(SpeexJitter *jitter, char *packet, int len, int timestamp);
  
  /** Get one packet from the jitter buffer */
  void speex_jitter_get(SpeexJitter *jitter, spx_int16_t *out, int *start_offset);
  
  /** Get pointer timestamp of jitter buffer */
  int speex_jitter_get_pointer_timestamp(SpeexJitter *jitter);
  
  #ifdef __cplusplus
  }
  #endif
  </code></pre>
  
  <p>speex_jitter_buffer.cpp</p>
  
  <pre><code>#include &lt;speex/speex_jitter.h&gt;
  #include "speex_jitter_buffer.h"
  
  #ifndef NULL
  #define NULL 0
  #endif
  
  
  void speex_jitter_init(SpeexJitter *jitter, void *decoder, int sampling_rate)
  {
     jitter-&gt;dec = decoder;
     speex_decoder_ctl(decoder, SPEEX_GET_FRAME_SIZE, &amp;jitter-&gt;frame_size);
  
     jitter-&gt;packets = jitter_buffer_init(jitter-&gt;frame_size);
  
     speex_bits_init(&amp;jitter-&gt;current_packet);
     jitter-&gt;valid_bits = 0;
  
  }
  
  void speex_jitter_destroy(SpeexJitter *jitter)
  {
     jitter_buffer_destroy(jitter-&gt;packets);
     speex_bits_destroy(&amp;jitter-&gt;current_packet);
  }
  
  void speex_jitter_put(SpeexJitter *jitter, char *packet, int len, int timestamp)
  {
     JitterBufferPacket p;
     p.data = packet;
     p.len = len;
     p.timestamp = timestamp;
     p.span = jitter-&gt;frame_size;
     jitter_buffer_put(jitter-&gt;packets, &amp;p);
  }
  
  void speex_jitter_get(SpeexJitter *jitter, spx_int16_t *out, int *current_timestamp)
  {
     int i;
     int ret;
     spx_int32_t activity;
     char data[2048];
     JitterBufferPacket packet;
     packet.data = data;
  
     if (jitter-&gt;valid_bits)
     {
        /* Try decoding last received packet */
        ret = speex_decode_int(jitter-&gt;dec, &amp;jitter-&gt;current_packet, out);
        if (ret == 0)
        {
           jitter_buffer_tick(jitter-&gt;packets);
           return;
        } else {
           jitter-&gt;valid_bits = 0;
        }
     }
  
     ret = jitter_buffer_get(jitter-&gt;packets, &amp;packet, jitter-&gt;frame_size, NULL);
  
     if (ret != JITTER_BUFFER_OK)
     {
        /* No packet found */
  
        /*fprintf (stderr, "lost/late frame\n");*/
        /*Packet is late or lost*/
        speex_decode_int(jitter-&gt;dec, NULL, out);
     } else {
        speex_bits_read_from(&amp;jitter-&gt;current_packet, packet.data, packet.len);
        /* Decode packet */
        ret = speex_decode_int(jitter-&gt;dec, &amp;jitter-&gt;current_packet, out);
        if (ret == 0)
        {
           jitter-&gt;valid_bits = 1;
        } else {
           /* Error while decoding */
           for (i=0;i&lt;jitter-&gt;frame_size;i++)
              out[i]=0;
        }
     }
     speex_decoder_ctl(jitter-&gt;dec, SPEEX_GET_ACTIVITY, &amp;activity);
     if (activity &lt; 30)
        jitter_buffer_update_delay(jitter-&gt;packets, &amp;packet, NULL);
     jitter_buffer_tick(jitter-&gt;packets);
  }
  
  int speex_jitter_get_pointer_timestamp(SpeexJitter *jitter)
  {
     return jitter_buffer_get_pointer_timestamp(jitter-&gt;packets);
  }
  </code></pre>
  
  <p>Then I am using the "speex_jitter_buffer.h" header file.</p>
  
  <p>The 'putting' thread code:</p>
  
  <pre><code>m_jitter_mutex.lock();
  speex_jitter_put(&amp;jitter, recvBuf, payloadLength, timestamp);
  m_jitter_mutex.unlock();
  </code></pre>
  
  <p>The 'getting' thread code:</p>
  
  <pre><code>while(true)
  {
      Sleep(20);
  
      m_jitter_mutex.lock();
      speex_jitter_get(&amp;jitter, (spx_int16_t*)pcm_short, NULL);
      m_pOut-&gt;Play(pcm_char, pcm_data_length);  // play the pcm data
      m_jitter_mutex.lock();
  }
  </code></pre>
  
  <p>I also want to use the speex library to do echo cancellation, but I don't know how to us it exactly. Thank you every much.</p>