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 */
7
@brief Contains all the functions for encoding and decoding audio
11
Redistribution and use in source and binary forms, with or without
12
modification, are permitted provided that the following conditions
15
- Redistributions of source code must retain the above copyright
16
notice, this list of conditions and the following disclaimer.
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.
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.
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.
42
#include "celt_types.h"
48
#if defined(__GNUC__) && defined(CELT_BUILD)
49
#define EXPORT __attribute__ ((visibility ("default")))
51
#define EXPORT __declspec(dllexport)
56
#define _celt_check_int(x) (((void)((x) == (celt_int32)0)), (celt_int32)(x))
57
#define _celt_check_mode_ptr_ptr(ptr) ((ptr) + ((ptr) - (CELTMode**)(ptr)))
62
/** An (or more) invalid argument (e.g. out of range) */
63
#define CELT_BAD_ARG -1
64
/** The mode struct passed is invalid */
65
#define CELT_INVALID_MODE -2
66
/** An internal error was detected */
67
#define CELT_INTERNAL_ERROR -3
68
/** The data passed (e.g. compressed data to decoder) is corrupted */
69
#define CELT_CORRUPTED_DATA -4
70
/** Invalid/unsupported request number */
71
#define CELT_UNIMPLEMENTED -5
72
/** An encoder or decoder structure is invalid or already freed */
73
#define CELT_INVALID_STATE -6
74
/** Memory allocation has failed */
75
#define CELT_ALLOC_FAIL -7
78
#define CELT_GET_MODE_REQUEST 1
79
/** Get the CELTMode used by an encoder or decoder */
80
#define CELT_GET_MODE(x) CELT_GET_MODE_REQUEST, _celt_check_mode_ptr_ptr(x)
82
#define CELT_SET_COMPLEXITY_REQUEST 2
83
/** Controls the complexity from 0-10 (int) */
84
#define CELT_SET_COMPLEXITY(x) CELT_SET_COMPLEXITY_REQUEST, _celt_check_int(x)
86
#define CELT_SET_PREDICTION_REQUEST 4
87
/** Controls the use of interframe prediction.
89
1=Short term interframe prediction allowed
90
2=Long term prediction allowed
92
#define CELT_SET_PREDICTION(x) CELT_SET_PREDICTION_REQUEST, _celt_check_int(x)
94
#define CELT_SET_BITRATE_REQUEST 6
95
/** Set the target VBR rate in bits per second(int); 0=CBR (default) */
96
#define CELT_SET_BITRATE(x) CELT_SET_BITRATE_REQUEST, _celt_check_int(x)
98
/** Reset the encoder/decoder memories to zero*/
99
#define CELT_RESET_STATE_REQUEST 8
100
#define CELT_RESET_STATE CELT_RESET_STATE_REQUEST
102
#define CELT_SET_VBR_CONSTRAINT_REQUEST 10
103
#define CELT_SET_VBR_CONSTRAINT(x) CELT_SET_VBR_CONSTRAINT_REQUEST, _celt_check_int(x)
105
#define CELT_SET_VBR_REQUEST 12
106
#define CELT_SET_VBR(x) CELT_SET_VBR_REQUEST, _celt_check_int(x)
108
#define CELT_SET_INPUT_CLIPPING_REQUEST 14
109
#define CELT_SET_INPUT_CLIPPING(x) CELT_SET_INPUT_CLIPPING_REQUEST, _celt_check_int(x)
111
#define CELT_SET_START_BAND_REQUEST 10000
112
#define CELT_SET_START_BAND(x) CELT_SET_START_BAND_REQUEST, _celt_check_int(x)
114
#define CELT_SET_END_BAND_REQUEST 10001
115
#define CELT_SET_END_BAND(x) CELT_SET_END_BAND_REQUEST, _celt_check_int(x)
117
#define CELT_SET_CHANNELS_REQUEST 10002
118
#define CELT_SET_CHANNELS(x) CELT_SET_CHANNELS_REQUEST, _celt_check_int(x)
120
/** GET the lookahead used in the current mode */
121
#define CELT_GET_LOOKAHEAD 1001
122
/** GET the sample rate used in the current mode */
123
#define CELT_GET_SAMPLE_RATE 1003
125
/** GET the bit-stream version for compatibility check */
126
#define CELT_GET_BITSTREAM_VERSION 2000
129
/** Contains the state of an encoder. One encoder state is needed
130
for each stream. It is initialised once at the beginning of the
131
stream. Do *not* re-initialise the state for every frame.
134
typedef struct CELTEncoder CELTEncoder;
136
/** State of the decoder. One decoder state is needed for each stream.
137
It is initialised once at the beginning of the stream. Do *not*
138
re-initialise the state for every frame */
139
typedef struct CELTDecoder CELTDecoder;
141
/** The mode contains all the information necessary to create an
142
encoder. Both the encoder and decoder need to be initialised
143
with exactly the same mode, otherwise the quality will be very
145
typedef struct CELTMode CELTMode;
148
/** \defgroup codec Encoding and decoding */
153
/** Creates a new mode struct. This will be passed to an encoder or
154
decoder. The mode MUST NOT BE DESTROYED until the encoders and
155
decoders that use it are destroyed as well.
156
@param Fs Sampling rate (32000 to 96000 Hz)
157
@param frame_size Number of samples (per channel) to encode in each
158
packet (even values; 64 - 512)
159
@param error Returned error code (if NULL, no error will be returned)
160
@return A newly created mode
162
EXPORT CELTMode *celt_mode_create(celt_int32 Fs, int frame_size, int *error);
164
/** Destroys a mode struct. Only call this after all encoders and
165
decoders using this mode are destroyed as well.
166
@param mode Mode to be destroyed
168
EXPORT void celt_mode_destroy(CELTMode *mode);
170
/** Query information from a mode */
171
EXPORT int celt_mode_info(const CELTMode *mode, int request, celt_int32 *value);
175
EXPORT int celt_encoder_get_size(int channels);
177
EXPORT int celt_encoder_get_size_custom(const CELTMode *mode, int channels);
179
/** Creates a new encoder state. Each stream needs its own encoder
180
state (can't be shared across simultaneous streams).
181
@param channels Number of channels
182
@param error Returns an error code
183
@return Newly created encoder state.
185
EXPORT CELTEncoder *celt_encoder_create(int sampling_rate, int channels, int *error);
187
/** Creates a new encoder state. Each stream needs its own encoder
188
state (can't be shared across simultaneous streams).
189
@param mode Contains all the information about the characteristics of
190
* the stream (must be the same characteristics as used for the
192
@param channels Number of channels
193
@param error Returns an error code
194
@return Newly created encoder state.
196
EXPORT CELTEncoder *celt_encoder_create_custom(const CELTMode *mode, int channels, int *error);
198
EXPORT CELTEncoder *celt_encoder_init(CELTEncoder *st, int sampling_rate, int channels, int *error);
200
EXPORT CELTEncoder *celt_encoder_init_custom(CELTEncoder *st, const CELTMode *mode, int channels, int *error);
202
/** Destroys a an encoder state.
203
@param st Encoder state to be destroyed
205
EXPORT void celt_encoder_destroy(CELTEncoder *st);
207
/** Encodes a frame of audio.
208
@param st Encoder state
209
@param pcm PCM audio in float format, with a normal range of ±1.0.
210
* Samples with a range beyond ±1.0 are supported but will
211
* be clipped by decoders using the integer API and should
212
* only be used if it is known that the far end supports
213
* extended dynmaic range. There must be exactly
214
* frame_size samples per channel.
215
@param compressed The compressed data is written here. This may not alias pcm or
216
* optional_synthesis.
217
@param nbCompressedBytes Maximum number of bytes to use for compressing the frame
218
* (can change from one frame to another)
219
@return Number of bytes written to "compressed". Will be the same as
220
* "nbCompressedBytes" unless the stream is VBR and will never be larger.
221
* If negative, an error has occurred (see error codes). It is IMPORTANT that
222
* the length returned be somehow transmitted to the decoder. Otherwise, no
223
* decoding is possible.
225
EXPORT int celt_encode_float(CELTEncoder *st, const float *pcm, int frame_size, unsigned char *compressed, int nbCompressedBytes);
227
/** Encodes a frame of audio.
228
@param st Encoder state
229
@param pcm PCM audio in signed 16-bit format (native endian). There must be
230
* exactly frame_size samples per channel.
231
@param compressed The compressed data is written here. This may not alias pcm or
232
* optional_synthesis.
233
@param nbCompressedBytes Maximum number of bytes to use for compressing the frame
234
* (can change from one frame to another)
235
@return Number of bytes written to "compressed". Will be the same as
236
* "nbCompressedBytes" unless the stream is VBR and will never be larger.
237
* If negative, an error has occurred (see error codes). It is IMPORTANT that
238
* the length returned be somehow transmitted to the decoder. Otherwise, no
239
* decoding is possible.
241
EXPORT int celt_encode(CELTEncoder *st, const celt_int16 *pcm, int frame_size, unsigned char *compressed, int nbCompressedBytes);
243
/** Query and set encoder parameters
244
@param st Encoder state
245
@param request Parameter to change or query
246
@param value Pointer to a 32-bit int value
249
EXPORT int celt_encoder_ctl(CELTEncoder * st, int request, ...);
253
EXPORT int celt_decoder_get_size(int channels);
255
EXPORT int celt_decoder_get_size_custom(const CELTMode *mode, int channels);
257
/** Creates a new decoder state. Each stream needs its own decoder state (can't
258
be shared across simultaneous streams).
259
@param mode Contains all the information about the characteristics of the
260
stream (must be the same characteristics as used for the encoder)
261
@param channels Number of channels
262
@param error Returns an error code
263
@return Newly created decoder state.
265
EXPORT CELTDecoder *celt_decoder_create(int sampling_rate, int channels, int *error);
267
/** Creates a new decoder state. Each stream needs its own decoder state (can't
268
be shared across simultaneous streams).
269
@param mode Contains all the information about the characteristics of the
270
stream (must be the same characteristics as used for the encoder)
271
@param channels Number of channels
272
@param error Returns an error code
273
@return Newly created decoder state.
275
EXPORT CELTDecoder *celt_decoder_create_custom(const CELTMode *mode, int channels, int *error);
277
EXPORT CELTDecoder *celt_decoder_init(CELTDecoder *st, int sampling_rate, int channels, int *error);
279
EXPORT CELTDecoder *celt_decoder_init_custom(CELTDecoder *st, const CELTMode *mode, int channels, int *error);
281
/** Destroys a a decoder state.
282
@param st Decoder state to be destroyed
284
EXPORT void celt_decoder_destroy(CELTDecoder *st);
286
/** Decodes a frame of audio.
287
@param st Decoder state
288
@param data Compressed data produced by an encoder
289
@param len Number of bytes to read from "data". This MUST be exactly the number
290
of bytes returned by the encoder. Using a larger value WILL NOT WORK.
291
@param pcm One frame (frame_size samples per channel) of decoded PCM will be
292
returned here in float format.
295
EXPORT int celt_decode_float(CELTDecoder *st, const unsigned char *data, int len, float *pcm, int frame_size);
297
/** Decodes a frame of audio.
298
@param st Decoder state
299
@param data Compressed data produced by an encoder
300
@param len Number of bytes to read from "data". This MUST be exactly the number
301
of bytes returned by the encoder. Using a larger value WILL NOT WORK.
302
@param pcm One frame (frame_size samples per channel) of decoded PCM will be
303
returned here in 16-bit PCM format (native endian).
306
EXPORT int celt_decode(CELTDecoder *st, const unsigned char *data, int len, celt_int16 *pcm, int frame_size);
308
/** Query and set decoder parameters
309
@param st Decoder state
310
@param request Parameter to change or query
311
@param value Pointer to a 32-bit int value
314
EXPORT int celt_decoder_ctl(CELTDecoder * st, int request, ...);
317
/** Returns the English string that corresponds to an error code
318
* @param error Error code (negative for an error, 0 for success
319
* @return Constant string (must NOT be freed)
321
EXPORT const char *celt_strerror(int error);
added
removed
celt-0.11.0-src/libcelt/celt.h
