1 /* Copyright (c) 2007-2008 CSIRO 2 Copyright (c) 2007-2009 Xiph.Org Foundation 3 Copyright (c) 2008 Gregory Maxwell 4 Written by Jean-Marc Valin and Gregory Maxwell */ 5 /** 6 @file celt.h 7 @brief Contains all the functions for encoding and decoding audio 8 */ 9 10 /* 11 Redistribution and use in source and binary forms, with or without 12 modification, are permitted provided that the following conditions 13 are met: 14 15 - Redistributions of source code must retain the above copyright 16 notice, this list of conditions and the following disclaimer. 17 18 - Redistributions in binary form must reproduce the above copyright 19 notice, this list of conditions and the following disclaimer in the 20 documentation and/or other materials provided with the distribution. 21 22 - Neither the name of the Xiph.org Foundation nor the names of its 23 contributors may be used to endorse or promote products derived from 24 this software without specific prior written permission. 25 26 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 27 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 28 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 29 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR 30 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 31 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 32 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 33 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 34 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 35 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 36 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 37 */ 38 39 module libcelt.celt; 40 import libcelt.celt_types; 41 42 template Tuple(E...) { alias Tuple = E; } 43 44 extern (C) { 45 46 enum _celt_check_int = (int x) => cast(celt_int32)x; 47 enum _celt_check_mode_ptr_ptr = (uint ptr) => cast(CELTMode **)ptr; //(ptr + ptr - cast(CELTMode **)ptr); // should be pointer type ? 48 49 /* Error codes */ 50 /** No error */ 51 enum CELT_OK = 0; 52 /** An (or more) invalid argument (e.g. out of range) */ 53 enum CELT_BAD_ARG = -1; 54 /** The mode struct passed is invalid */ 55 enum CELT_INVALID_MODE = -2; 56 /** An internal error was detected */ 57 enum CELT_INTERNAL_ERROR = -3; 58 /** The data passed (e.g. compressed data to decoder) is corrupted */ 59 enum CELT_CORRUPTED_DATA = -4; 60 /** Invalid/unsupported request number */ 61 enum CELT_UNIMPLEMENTED = -5; 62 /** An encoder or decoder structure is invalid or already freed */ 63 enum CELT_INVALID_STATE = -6; 64 /** Memory allocation has failed */ 65 enum CELT_ALLOC_FAIL = -7; 66 67 /* Requests */ 68 enum CELT_GET_MODE_REQUEST = 1; 69 /** Get the CELTMode used by an encoder or decoder */ 70 template CELT_GET_MODE(x...) { alias CELT_GET_MODE = Tuple!(CELT_GET_MODE_REQUEST, _celt_check_int(x)); } 71 enum CELT_SET_COMPLEXITY_REQUEST = 2; 72 /** Controls the complexity from 0-10 (int) */ 73 template CELT_SET_COMPLEXITY(x...) { alias CELT_SET_COMPLEXITY = Tuple!(CELT_SET_COMPLEXITY_REQUEST, _celt_check_int(x)); } 74 enum CELT_SET_PREDICTION_REQUEST = 4; 75 /** Controls the use of interframe prediction. 76 0=Independent frames 77 1=Short term interframe prediction allowed 78 2=Long term prediction allowed 79 */ 80 template CELT_SET_PREDICTION(x...) { alias CELT_SET_PREDICTION = Tuple!(CELT_SET_PREDICTION_REQUEST, _celt_check_int(x)); } 81 enum CELT_SET_VBR_RATE_REQUEST = 6; 82 /** Set the target VBR rate in bits per second(int); 0=CBR (default) */ 83 template CELT_SET_VBR_RATE(int x) { alias CELT_SET_VBR_RATE = Tuple!(CELT_SET_VBR_RATE_REQUEST, x); } 84 /** Reset the encoder/decoder memories to zero*/ 85 enum CELT_RESET_STATE_REQUEST = 8; 86 enum CELT_RESET_STATE = CELT_RESET_STATE_REQUEST; 87 88 enum CELT_SET_START_BAND_REQUEST = 10000; 89 /** Controls the complexity from 0-10 (int) */ 90 template CELT_SET_START_BAND(x...) { alias CELT_SET_START_BAND = Tuple!(CELT_SET_START_BAND_REQUEST, _celt_check_int(x)); } 91 92 /** GET the lookahead used in the current mode */ 93 enum CELT_GET_LOOKAHEAD = 1001; 94 /** GET the sample rate used in the current mode */ 95 enum CELT_GET_SAMPLE_RATE = 1003; 96 97 /** GET the bit-stream version for compatibility check */ 98 enum CELT_GET_BITSTREAM_VERSIO = 2000; 99 100 101 /** Contains the state of an encoder. One encoder state is needed 102 for each stream. It is initialised once at the beginning of the 103 stream. Do *not* re-initialise the state for every frame. 104 @brief Encoder state 105 */ 106 //typedef struct CELTEncoder CELTEncoder; 107 108 /** State of the decoder. One decoder state is needed for each stream. 109 It is initialised once at the beginning of the stream. Do *not* 110 re-initialise the state for every frame */ 111 //typedef struct CELTDecoder CELTDecoder; 112 113 /** The mode contains all the information necessary to create an 114 encoder. Both the encoder and decoder need to be initialised 115 with exactly the same mode, otherwise the quality will be very 116 bad */ 117 //typedef struct CELTMode CELTMode; 118 119 120 /** \defgroup codec Encoding and decoding */ 121 /* @{ */ 122 123 /* Mode calls */ 124 125 /** Creates a new mode struct. This will be passed to an encoder or 126 decoder. The mode MUST NOT BE DESTROYED until the encoders and 127 decoders that use it are destroyed as well. 128 @param Fs Sampling rate (32000 to 96000 Hz) 129 @param frame_size Number of samples (per channel) to encode in each 130 packet (even values; 64 - 512) 131 @param error Returned error code (if NULL, no error will be returned) 132 @return A newly created mode 133 */ 134 CELTMode *celt_mode_create(celt_int32 Fs, int frame_size, int *error); 135 136 /** Destroys a mode struct. Only call this after all encoders and 137 decoders using this mode are destroyed as well. 138 @param mode Mode to be destroyed 139 */ 140 void celt_mode_destroy(CELTMode *mode); 141 142 /** Query information from a mode */ 143 int celt_mode_info(const CELTMode *mode, int request, celt_int32 *value); 144 145 /* Encoder stuff */ 146 147 148 /** Creates a new encoder state. Each stream needs its own encoder 149 state (can't be shared across simultaneous streams). 150 @param mode Contains all the information about the characteristics of 151 * the stream (must be the same characteristics as used for the 152 * decoder) 153 @param channels Number of channels 154 @param error Returns an error code 155 @return Newly created encoder state. 156 */ 157 CELTEncoder *celt_encoder_create(const CELTMode *mode, int channels, int *error); 158 159 /** Destroys a an encoder state. 160 @param st Encoder state to be destroyed 161 */ 162 void celt_encoder_destroy(CELTEncoder *st); 163 164 /** Encodes a frame of audio. 165 @param st Encoder state 166 @param pcm PCM audio in float format, with a normal range of ±1.0. 167 * Samples with a range beyond ±1.0 are supported but will 168 * be clipped by decoders using the integer API and should 169 * only be used if it is known that the far end supports 170 * extended dynmaic range. There must be exactly 171 * frame_size samples per channel. 172 @param optional_resynthesis If not NULL, the encoder copies the audio signal that 173 * the decoder would decode. It is the same as calling the 174 * decoder on the compressed data, just faster. 175 * This may alias pcm. 176 @param compressed The compressed data is written here. This may not alias pcm or 177 * optional_synthesis. 178 @param nbCompressedBytes Maximum number of bytes to use for compressing the frame 179 * (can change from one frame to another) 180 @return Number of bytes written to "compressed". Will be the same as 181 * "nbCompressedBytes" unless the stream is VBR and will never be larger. 182 * If negative, an error has occurred (see error codes). It is IMPORTANT that 183 * the length returned be somehow transmitted to the decoder. Otherwise, no 184 * decoding is possible. 185 */ 186 int celt_encode_resynthesis_float(CELTEncoder *st, const float *pcm, float *optional_resynthesis, int frame_size, ubyte *compressed, int nbCompressedBytes); 187 188 /** Encodes a frame of audio. 189 @param st Encoder state 190 @param pcm PCM audio in float format, with a normal range of ±1.0. 191 * Samples with a range beyond ±1.0 are supported but will 192 * be clipped by decoders using the integer API and should 193 * only be used if it is known that the far end supports 194 * extended dynmaic range. There must be exactly 195 * frame_size samples per channel. 196 @param compressed The compressed data is written here. This may not alias pcm or 197 * optional_synthesis. 198 @param nbCompressedBytes Maximum number of bytes to use for compressing the frame 199 * (can change from one frame to another) 200 @return Number of bytes written to "compressed". Will be the same as 201 * "nbCompressedBytes" unless the stream is VBR and will never be larger. 202 * If negative, an error has occurred (see error codes). It is IMPORTANT that 203 * the length returned be somehow transmitted to the decoder. Otherwise, no 204 * decoding is possible. 205 */ 206 int celt_encode_float(CELTEncoder *st, const float *pcm, int frame_size, ubyte *compressed, int nbCompressedBytes); 207 208 /** Encodes a frame of audio. 209 @param st Encoder state 210 @param pcm PCM audio in signed 16-bit format (native endian). There must be 211 * exactly frame_size samples per channel. 212 @param optional_resynthesis If not NULL, the encoder copies the audio signal that 213 * the decoder would decode. It is the same as calling the 214 * decoder on the compressed data, just faster. 215 * This may alias pcm. 216 @param compressed The compressed data is written here. This may not alias pcm or 217 * optional_synthesis. 218 @param nbCompressedBytes Maximum number of bytes to use for compressing the frame 219 * (can change from one frame to another) 220 @return Number of bytes written to "compressed". Will be the same as 221 * "nbCompressedBytes" unless the stream is VBR and will never be larger. 222 * If negative, an error has occurred (see error codes). It is IMPORTANT that 223 * the length returned be somehow transmitted to the decoder. Otherwise, no 224 * decoding is possible. 225 */ 226 int celt_encode_resynthesis(CELTEncoder *st, const celt_int16 *pcm, celt_int16 *optional_resynthesis, int frame_size, ubyte *compressed, int nbCompressedBytes); 227 228 /** Encodes a frame of audio. 229 @param st Encoder state 230 @param pcm PCM audio in signed 16-bit format (native endian). There must be 231 * exactly frame_size samples per channel. 232 @param compressed The compressed data is written here. This may not alias pcm or 233 * optional_synthesis. 234 @param nbCompressedBytes Maximum number of bytes to use for compressing the frame 235 * (can change from one frame to another) 236 @return Number of bytes written to "compressed". Will be the same as 237 * "nbCompressedBytes" unless the stream is VBR and will never be larger. 238 * If negative, an error has occurred (see error codes). It is IMPORTANT that 239 * the length returned be somehow transmitted to the decoder. Otherwise, no 240 * decoding is possible. 241 */ 242 int celt_encode(CELTEncoder *st, const celt_int16 *pcm, int frame_size, ubyte *compressed, int nbCompressedBytes); 243 244 /** Query and set encoder parameters 245 @param st Encoder state 246 @param request Parameter to change or query 247 @param value Pointer to a 32-bit int value 248 @return Error code 249 */ 250 int celt_encoder_ctl(CELTEncoder * st, int request, ...); 251 252 /* Decoder stuff */ 253 254 255 /** Creates a new decoder state. Each stream needs its own decoder state (can't 256 be shared across simultaneous streams). 257 @param mode Contains all the information about the characteristics of the 258 stream (must be the same characteristics as used for the encoder) 259 @param channels Number of channels 260 @param error Returns an error code 261 @return Newly created decoder state. 262 */ 263 CELTDecoder *celt_decoder_create(const CELTMode *mode, int channels, int *error); 264 265 /** Destroys a a decoder state. 266 @param st Decoder state to be destroyed 267 */ 268 void celt_decoder_destroy(CELTDecoder *st); 269 270 /** Decodes a frame of audio. 271 @param st Decoder state 272 @param data Compressed data produced by an encoder 273 @param len Number of bytes to read from "data". This MUST be exactly the number 274 of bytes returned by the encoder. Using a larger value WILL NOT WORK. 275 @param pcm One frame (frame_size samples per channel) of decoded PCM will be 276 returned here in float format. 277 @return Error code. 278 */ 279 int celt_decode_float(CELTDecoder *st, const ubyte *data, int len, float *pcm, int frame_size); 280 281 /** Decodes a frame of audio. 282 @param st Decoder state 283 @param data Compressed data produced by an encoder 284 @param len Number of bytes to read from "data". This MUST be exactly the number 285 of bytes returned by the encoder. Using a larger value WILL NOT WORK. 286 @param pcm One frame (frame_size samples per channel) of decoded PCM will be 287 returned here in 16-bit PCM format (native endian). 288 @return Error code. 289 */ 290 int celt_decode(CELTDecoder *st, const ubyte *data, int len, celt_int16 *pcm, int frame_size); 291 292 /** Query and set decoder parameters 293 @param st Decoder state 294 @param request Parameter to change or query 295 @param value Pointer to a 32-bit int value 296 @return Error code 297 */ 298 int celt_decoder_ctl(CELTDecoder * st, int request, ...); 299 300 301 /** Returns the English string that corresponds to an error code 302 * @param error Error code (negative for an error, 0 for success 303 * @return Constant string (must NOT be freed) 304 */ 305 const char *celt_strerror(int error); 306 307 /* @} */ 308 }