speex.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424
  1. /* Copyright (C) 2002-2006 Jean-Marc Valin*/
  2. /**
  3. @file speex.h
  4. @brief Describes the different modes of the codec
  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. - Redistributions of source code must retain the above copyright
  11. notice, this list of conditions and the following disclaimer.
  12. - Redistributions in binary form must reproduce the above copyright
  13. notice, this list of conditions and the following disclaimer in the
  14. documentation and/or other materials provided with the distribution.
  15. - Neither the name of the Xiph.org Foundation nor the names of its
  16. contributors may be used to endorse or promote products derived from
  17. this software without specific prior written permission.
  18. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19. ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21. A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
  22. CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  23. EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  24. PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  25. PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  26. LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  27. NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  28. SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29. */
  30. #ifndef SPEEX_H
  31. #define SPEEX_H
  32. /** @defgroup Codec Speex encoder and decoder
  33. * This is the Speex codec itself.
  34. * @{
  35. */
  36. #include "speex/speex_bits.h"
  37. #include "speex/speex_types.h"
  38. #ifdef __cplusplus
  39. extern "C" {
  40. #endif
  41. /* Values allowed for *ctl() requests */
  42. /** Set enhancement on/off (decoder only) */
  43. #define SPEEX_SET_ENH 0
  44. /** Get enhancement state (decoder only) */
  45. #define SPEEX_GET_ENH 1
  46. /*Would be SPEEX_SET_FRAME_SIZE, but it's (currently) invalid*/
  47. /** Obtain frame size used by encoder/decoder */
  48. #define SPEEX_GET_FRAME_SIZE 3
  49. /** Set quality value */
  50. #define SPEEX_SET_QUALITY 4
  51. /** Get current quality setting */
  52. /* #define SPEEX_GET_QUALITY 5 -- Doesn't make much sense, does it? */
  53. /** Set sub-mode to use */
  54. #define SPEEX_SET_MODE 6
  55. /** Get current sub-mode in use */
  56. #define SPEEX_GET_MODE 7
  57. /** Set low-band sub-mode to use (wideband only)*/
  58. #define SPEEX_SET_LOW_MODE 8
  59. /** Get current low-band mode in use (wideband only)*/
  60. #define SPEEX_GET_LOW_MODE 9
  61. /** Set high-band sub-mode to use (wideband only)*/
  62. #define SPEEX_SET_HIGH_MODE 10
  63. /** Get current high-band mode in use (wideband only)*/
  64. #define SPEEX_GET_HIGH_MODE 11
  65. /** Set VBR on (1) or off (0) */
  66. #define SPEEX_SET_VBR 12
  67. /** Get VBR status (1 for on, 0 for off) */
  68. #define SPEEX_GET_VBR 13
  69. /** Set quality value for VBR encoding (0-10) */
  70. #define SPEEX_SET_VBR_QUALITY 14
  71. /** Get current quality value for VBR encoding (0-10) */
  72. #define SPEEX_GET_VBR_QUALITY 15
  73. /** Set complexity of the encoder (0-10) */
  74. #define SPEEX_SET_COMPLEXITY 16
  75. /** Get current complexity of the encoder (0-10) */
  76. #define SPEEX_GET_COMPLEXITY 17
  77. /** Set bit-rate used by the encoder (or lower) */
  78. #define SPEEX_SET_BITRATE 18
  79. /** Get current bit-rate used by the encoder or decoder */
  80. #define SPEEX_GET_BITRATE 19
  81. /** Define a handler function for in-band Speex request*/
  82. #define SPEEX_SET_HANDLER 20
  83. /** Define a handler function for in-band user-defined request*/
  84. #define SPEEX_SET_USER_HANDLER 22
  85. /** Set sampling rate used in bit-rate computation */
  86. #define SPEEX_SET_SAMPLING_RATE 24
  87. /** Get sampling rate used in bit-rate computation */
  88. #define SPEEX_GET_SAMPLING_RATE 25
  89. /** Reset the encoder/decoder memories to zero*/
  90. #define SPEEX_RESET_STATE 26
  91. /** Get VBR info (mostly used internally) */
  92. #define SPEEX_GET_RELATIVE_QUALITY 29
  93. /** Set VAD status (1 for on, 0 for off) */
  94. #define SPEEX_SET_VAD 30
  95. /** Get VAD status (1 for on, 0 for off) */
  96. #define SPEEX_GET_VAD 31
  97. /** Set Average Bit-Rate (ABR) to n bits per seconds */
  98. #define SPEEX_SET_ABR 32
  99. /** Get Average Bit-Rate (ABR) setting (in bps) */
  100. #define SPEEX_GET_ABR 33
  101. /** Set DTX status (1 for on, 0 for off) */
  102. #define SPEEX_SET_DTX 34
  103. /** Get DTX status (1 for on, 0 for off) */
  104. #define SPEEX_GET_DTX 35
  105. /** Set submode encoding in each frame (1 for yes, 0 for no, setting to no breaks the standard) */
  106. #define SPEEX_SET_SUBMODE_ENCODING 36
  107. /** Get submode encoding in each frame */
  108. #define SPEEX_GET_SUBMODE_ENCODING 37
  109. /*#define SPEEX_SET_LOOKAHEAD 38*/
  110. /** Returns the lookahead used by Speex */
  111. #define SPEEX_GET_LOOKAHEAD 39
  112. /** Sets tuning for packet-loss concealment (expected loss rate) */
  113. #define SPEEX_SET_PLC_TUNING 40
  114. /** Gets tuning for PLC */
  115. #define SPEEX_GET_PLC_TUNING 41
  116. /** Sets the max bit-rate allowed in VBR mode */
  117. #define SPEEX_SET_VBR_MAX_BITRATE 42
  118. /** Gets the max bit-rate allowed in VBR mode */
  119. #define SPEEX_GET_VBR_MAX_BITRATE 43
  120. /** Turn on/off input/output high-pass filtering */
  121. #define SPEEX_SET_HIGHPASS 44
  122. /** Get status of input/output high-pass filtering */
  123. #define SPEEX_GET_HIGHPASS 45
  124. /** Get "activity level" of the last decoded frame, i.e.
  125. how much damage we cause if we remove the frame */
  126. #define SPEEX_GET_ACTIVITY 47
  127. /* Preserving compatibility:*/
  128. /** Equivalent to SPEEX_SET_ENH */
  129. #define SPEEX_SET_PF 0
  130. /** Equivalent to SPEEX_GET_ENH */
  131. #define SPEEX_GET_PF 1
  132. /* Values allowed for mode queries */
  133. /** Query the frame size of a mode */
  134. #define SPEEX_MODE_FRAME_SIZE 0
  135. /** Query the size of an encoded frame for a particular sub-mode */
  136. #define SPEEX_SUBMODE_BITS_PER_FRAME 1
  137. /** Get major Speex version */
  138. #define SPEEX_LIB_GET_MAJOR_VERSION 1
  139. /** Get minor Speex version */
  140. #define SPEEX_LIB_GET_MINOR_VERSION 3
  141. /** Get micro Speex version */
  142. #define SPEEX_LIB_GET_MICRO_VERSION 5
  143. /** Get extra Speex version */
  144. #define SPEEX_LIB_GET_EXTRA_VERSION 7
  145. /** Get Speex version string */
  146. #define SPEEX_LIB_GET_VERSION_STRING 9
  147. /*#define SPEEX_LIB_SET_ALLOC_FUNC 10
  148. #define SPEEX_LIB_GET_ALLOC_FUNC 11
  149. #define SPEEX_LIB_SET_FREE_FUNC 12
  150. #define SPEEX_LIB_GET_FREE_FUNC 13
  151. #define SPEEX_LIB_SET_WARNING_FUNC 14
  152. #define SPEEX_LIB_GET_WARNING_FUNC 15
  153. #define SPEEX_LIB_SET_ERROR_FUNC 16
  154. #define SPEEX_LIB_GET_ERROR_FUNC 17
  155. */
  156. /** Number of defined modes in Speex */
  157. #define SPEEX_NB_MODES 3
  158. /** modeID for the defined narrowband mode */
  159. #define SPEEX_MODEID_NB 0
  160. /** modeID for the defined wideband mode */
  161. #define SPEEX_MODEID_WB 1
  162. /** modeID for the defined ultra-wideband mode */
  163. #define SPEEX_MODEID_UWB 2
  164. struct SpeexMode;
  165. /* Prototypes for mode function pointers */
  166. /** Encoder state initialization function */
  167. typedef void *(*encoder_init_func)(const struct SpeexMode *mode);
  168. /** Encoder state destruction function */
  169. typedef void (*encoder_destroy_func)(void *st);
  170. /** Main encoding function */
  171. typedef int (*encode_func)(void *state, void *in, SpeexBits *bits);
  172. /** Function for controlling the encoder options */
  173. typedef int (*encoder_ctl_func)(void *state, int request, void *ptr);
  174. /** Decoder state initialization function */
  175. typedef void *(*decoder_init_func)(const struct SpeexMode *mode);
  176. /** Decoder state destruction function */
  177. typedef void (*decoder_destroy_func)(void *st);
  178. /** Main decoding function */
  179. typedef int (*decode_func)(void *state, SpeexBits *bits, void *out);
  180. /** Function for controlling the decoder options */
  181. typedef int (*decoder_ctl_func)(void *state, int request, void *ptr);
  182. /** Query function for a mode */
  183. typedef int (*mode_query_func)(const void *mode, int request, void *ptr);
  184. /** Struct defining a Speex mode */
  185. typedef struct SpeexMode {
  186. /** Pointer to the low-level mode data */
  187. const void *mode;
  188. /** Pointer to the mode query function */
  189. mode_query_func query;
  190. /** The name of the mode (you should not rely on this to identify the mode)*/
  191. const char *modeName;
  192. /**ID of the mode*/
  193. int modeID;
  194. /**Version number of the bitstream (incremented every time we break
  195. bitstream compatibility*/
  196. int bitstream_version;
  197. /** Pointer to encoder initialization function */
  198. encoder_init_func enc_init;
  199. /** Pointer to encoder destruction function */
  200. encoder_destroy_func enc_destroy;
  201. /** Pointer to frame encoding function */
  202. encode_func enc;
  203. /** Pointer to decoder initialization function */
  204. decoder_init_func dec_init;
  205. /** Pointer to decoder destruction function */
  206. decoder_destroy_func dec_destroy;
  207. /** Pointer to frame decoding function */
  208. decode_func dec;
  209. /** ioctl-like requests for encoder */
  210. encoder_ctl_func enc_ctl;
  211. /** ioctl-like requests for decoder */
  212. decoder_ctl_func dec_ctl;
  213. } SpeexMode;
  214. /**
  215. * Returns a handle to a newly created Speex encoder state structure. For now,
  216. * the "mode" argument can be &nb_mode or &wb_mode . In the future, more modes
  217. * may be added. Note that for now if you have more than one channels to
  218. * encode, you need one state per channel.
  219. *
  220. * @param mode The mode to use (either speex_nb_mode or speex_wb.mode)
  221. * @return A newly created encoder state or NULL if state allocation fails
  222. */
  223. void *speex_encoder_init(const SpeexMode *mode);
  224. /** Frees all resources associated to an existing Speex encoder state.
  225. * @param state Encoder state to be destroyed */
  226. void speex_encoder_destroy(void *state);
  227. /** Uses an existing encoder state to encode one frame of speech pointed to by
  228. "in". The encoded bit-stream is saved in "bits".
  229. @param state Encoder state
  230. @param in Frame that will be encoded with a +-2^15 range. This data MAY be
  231. overwritten by the encoder and should be considered uninitialised
  232. after the call.
  233. @param bits Bit-stream where the data will be written
  234. @return 0 if frame needs not be transmitted (DTX only), 1 otherwise
  235. */
  236. int speex_encode(void *state, float *in, SpeexBits *bits);
  237. /** Uses an existing encoder state to encode one frame of speech pointed to by
  238. "in". The encoded bit-stream is saved in "bits".
  239. @param state Encoder state
  240. @param in Frame that will be encoded with a +-2^15 range
  241. @param bits Bit-stream where the data will be written
  242. @return 0 if frame needs not be transmitted (DTX only), 1 otherwise
  243. */
  244. int speex_encode_int(void *state, spx_int16_t *in, SpeexBits *bits);
  245. /** Used like the ioctl function to control the encoder parameters
  246. *
  247. * @param state Encoder state
  248. * @param request ioctl-type request (one of the SPEEX_* macros)
  249. * @param ptr Data exchanged to-from function
  250. * @return 0 if no error, -1 if request in unknown, -2 for invalid parameter
  251. */
  252. int speex_encoder_ctl(void *state, int request, void *ptr);
  253. /** Returns a handle to a newly created decoder state structure. For now,
  254. * the mode argument can be &nb_mode or &wb_mode . In the future, more modes
  255. * may be added. Note that for now if you have more than one channels to
  256. * decode, you need one state per channel.
  257. *
  258. * @param mode Speex mode (one of speex_nb_mode or speex_wb_mode)
  259. * @return A newly created decoder state or NULL if state allocation fails
  260. */
  261. void *speex_decoder_init(const SpeexMode *mode);
  262. /** Frees all resources associated to an existing decoder state.
  263. *
  264. * @param state State to be destroyed
  265. */
  266. void speex_decoder_destroy(void *state);
  267. /** Uses an existing decoder state to decode one frame of speech from
  268. * bit-stream bits. The output speech is saved written to out.
  269. *
  270. * @param state Decoder state
  271. * @param bits Bit-stream from which to decode the frame (NULL if the packet was lost)
  272. * @param out Where to write the decoded frame
  273. * @return return status (0 for no error, -1 for end of stream, -2 corrupt stream)
  274. */
  275. int speex_decode(void *state, SpeexBits *bits, float *out);
  276. /** Uses an existing decoder state to decode one frame of speech from
  277. * bit-stream bits. The output speech is saved written to out.
  278. *
  279. * @param state Decoder state
  280. * @param bits Bit-stream from which to decode the frame (NULL if the packet was lost)
  281. * @param out Where to write the decoded frame
  282. * @return return status (0 for no error, -1 for end of stream, -2 corrupt stream)
  283. */
  284. int speex_decode_int(void *state, SpeexBits *bits, spx_int16_t *out);
  285. /** Used like the ioctl function to control the encoder parameters
  286. *
  287. * @param state Decoder state
  288. * @param request ioctl-type request (one of the SPEEX_* macros)
  289. * @param ptr Data exchanged to-from function
  290. * @return 0 if no error, -1 if request in unknown, -2 for invalid parameter
  291. */
  292. int speex_decoder_ctl(void *state, int request, void *ptr);
  293. /** Query function for mode information
  294. *
  295. * @param mode Speex mode
  296. * @param request ioctl-type request (one of the SPEEX_* macros)
  297. * @param ptr Data exchanged to-from function
  298. * @return 0 if no error, -1 if request in unknown, -2 for invalid parameter
  299. */
  300. int speex_mode_query(const SpeexMode *mode, int request, void *ptr);
  301. /** Functions for controlling the behavior of libspeex
  302. * @param request ioctl-type request (one of the SPEEX_LIB_* macros)
  303. * @param ptr Data exchanged to-from function
  304. * @return 0 if no error, -1 if request in unknown, -2 for invalid parameter
  305. */
  306. int speex_lib_ctl(int request, void *ptr);
  307. /** Default narrowband mode */
  308. extern const SpeexMode speex_nb_mode;
  309. /** Default wideband mode */
  310. extern const SpeexMode speex_wb_mode;
  311. /** Default "ultra-wideband" mode */
  312. extern const SpeexMode speex_uwb_mode;
  313. /** List of all modes available */
  314. extern const SpeexMode * const speex_mode_list[SPEEX_NB_MODES];
  315. /** Obtain one of the modes available */
  316. const SpeexMode * speex_lib_get_mode (int mode);
  317. #ifndef WIN32
  318. /* We actually override the function in the narrowband case so that we can avoid linking in the wideband stuff */
  319. #define speex_lib_get_mode(mode) ((mode)==SPEEX_MODEID_NB ? &speex_nb_mode : speex_lib_get_mode (mode))
  320. #endif
  321. #ifdef __cplusplus
  322. }
  323. #endif
  324. /** @}*/
  325. #endif