more doc
[speexdsp.git] / include / speex / speex_jitter.h
1 /* Copyright (C) 2002 Jean-Marc Valin */
2 /**
3    @file speex_jitter.h
4    @brief Adaptive jitter buffer for Speex
5 */
6 /*
7    Redistribution and use in source and binary forms, with or without
8    modification, are permitted provided that the following conditions
9    are met:
10    
11    - Redistributions of source code must retain the above copyright
12    notice, this list of conditions and the following disclaimer.
13    
14    - Redistributions in binary form must reproduce the above copyright
15    notice, this list of conditions and the following disclaimer in the
16    documentation and/or other materials provided with the distribution.
17    
18    - Neither the name of the Xiph.org Foundation nor the names of its
19    contributors may be used to endorse or promote products derived from
20    this software without specific prior written permission.
21    
22    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
25    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
26    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
27    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
28    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
29    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
30    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
31    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
32    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33
34 */
35
36 #ifndef SPEEX_JITTER_H
37 #define SPEEX_JITTER_H
38 /** @defgroup JitterBuffer JitterBuffer: Adaptive jitter buffer
39  *  This is the jitter buffer that reorders UDP/RTP packets and adjusts the buffer size
40  * to maintain good quality and low latency.
41  *  @{
42  */
43
44 #include "speex.h"
45 #include "speex_bits.h"
46
47 #ifdef __cplusplus
48 extern "C" {
49 #endif
50
51 /** Generic adaptive jitter buffer state */
52 struct JitterBuffer_;
53
54 /** Generic adaptive jitter buffer state */
55 typedef struct JitterBuffer_ JitterBuffer;
56
57 /** Definition of an incoming packet */
58 typedef struct _JitterBufferPacket JitterBufferPacket;
59
60 /** Definition of an incoming packet */
61 struct _JitterBufferPacket {
62    char        *data;       /**< Data bytes contained in the packet */
63    spx_uint32_t len;        /**< Length of the packet in bytes */
64    spx_uint32_t timestamp;  /**< Timestamp for the packet */
65    spx_uint32_t span;       /**< Time covered by the packet (same units as timestamp) */
66 };
67
68 /** Packet has been retrieved */
69 #define JITTER_BUFFER_OK 0
70 /** Packet is missing */
71 #define JITTER_BUFFER_MISSING 1
72 /** Packet is incomplete (does not cover the entive tick */
73 #define JITTER_BUFFER_INCOMPLETE 2
74 /** There was an error in the jitter buffer */
75 #define JITTER_BUFFER_INTERNAL_ERROR -1
76 /** Invalid argument */
77 #define JITTER_BUFFER_BAD_ARGUMENT -2
78
79
80 /** Set minimum amount of extra buffering required (margin) */
81 #define JITTER_BUFFER_SET_MARGIN 0
82 /** Get minimum amount of extra buffering required (margin) */
83 #define JITTER_BUFFER_GET_MARGIN 1
84
85
86 /** Initialises jitter buffer 
87  * 
88  * @param tick Number of samples per "tick", i.e. the time period of the elements that will be retrieved
89  * @return Newly created jitter buffer state
90  */
91 JitterBuffer *jitter_buffer_init(int tick);
92
93 /** Restores jitter buffer to its original state 
94  * 
95  * @param jitter Jitter buffer state
96  */
97 void jitter_buffer_reset(JitterBuffer *jitter);
98
99 /** Destroys jitter buffer 
100  * 
101  * @param jitter Jitter buffer state
102  */
103 void jitter_buffer_destroy(JitterBuffer *jitter);
104
105 /** Put one packet into the jitter buffer
106  * 
107  * @param jitter Jitter buffer state
108  * @param packet Incoming packet
109 */
110 void jitter_buffer_put(JitterBuffer *jitter, const JitterBufferPacket *packet);
111
112 /** Get one packet from the jitter buffer
113  * 
114  * @param jitter Jitter buffer state
115  * @param packet Returned packet
116  * @param current_timestamp Timestamp for the returned packet 
117 */
118 int jitter_buffer_get(JitterBuffer *jitter, JitterBufferPacket *packet, spx_uint32_t *current_timestamp);
119
120 /** Get pointer timestamp of jitter buffer
121  * 
122  * @param jitter Jitter buffer state
123 */
124 int jitter_buffer_get_pointer_timestamp(JitterBuffer *jitter);
125
126 /** Advance by one tick
127  * 
128  * @param jitter Jitter buffer state
129 */
130 void jitter_buffer_tick(JitterBuffer *jitter);
131
132 /** Used like the ioctl function to control the jitter buffer parameters
133  * 
134  * @param jitter Jitter buffer state
135  * @param request ioctl-type request (one of the JITTER_BUFFER_* macros)
136  * @param ptr Data exchanged to-from function
137  * @return 0 if no error, -1 if request in unknown
138 */
139 int jitter_buffer_ctl(JitterBuffer *jitter, int request, void *ptr);
140
141 /* @} */
142
143 /** @defgroup SpeexJitter SpeexJitter: Adaptive jitter buffer specifically for Speex
144  *  This is the jitter buffer that reorders UDP/RTP packets and adjusts the buffer size
145  * to maintain good quality and low latency. This is a simplified version that works only
146  * with Speex, but is much easier to use.
147  *  @{
148 */
149
150 /** Speex jitter-buffer state. Never use it directly! */
151 typedef struct SpeexJitter {
152    SpeexBits current_packet;         /**< Current Speex packet */
153    int valid_bits;                   /**< True if Speex bits are valid */
154    JitterBuffer *packets;            /**< Generic jitter buffer state */
155    void *dec;                        /**< Pointer to Speex decoder */
156    spx_int32_t frame_size;           /**< Frame size of Speex decoder */
157 } SpeexJitter;
158
159 /** Initialise jitter buffer 
160  * 
161  * @param jitter State of the Speex jitter buffer
162  * @param decoder Speex decoder to call
163  * @param sampling_rate Sampling rate used by the decoder
164 */
165 void speex_jitter_init(SpeexJitter *jitter, void *decoder, int sampling_rate);
166
167 /** Destroy jitter buffer */
168 void speex_jitter_destroy(SpeexJitter *jitter);
169
170 /** Put one packet into the jitter buffer */
171 void speex_jitter_put(SpeexJitter *jitter, char *packet, int len, int timestamp);
172
173 /** Get one packet from the jitter buffer */
174 void speex_jitter_get(SpeexJitter *jitter, spx_int16_t *out, int *start_offset);
175
176 /** Get pointer timestamp of jitter buffer */
177 int speex_jitter_get_pointer_timestamp(SpeexJitter *jitter);
178
179 #ifdef __cplusplus
180 }
181 #endif
182
183 /* @} */
184 #endif