You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
325 lines
13 KiB
325 lines
13 KiB
/* Copyright (c) 2007-2008 CSIRO |
|
Copyright (c) 2007-2009 Xiph.Org Foundation |
|
Copyright (c) 2008 Gregory Maxwell |
|
Written by Jean-Marc Valin and Gregory Maxwell */ |
|
/** |
|
@file celt.h |
|
@brief Contains all the functions for encoding and decoding audio |
|
*/ |
|
|
|
/* |
|
Redistribution and use in source and binary forms, with or without |
|
modification, are permitted provided that the following conditions |
|
are met: |
|
|
|
- Redistributions of source code must retain the above copyright |
|
notice, this list of conditions and the following disclaimer. |
|
|
|
- Redistributions in binary form must reproduce the above copyright |
|
notice, this list of conditions and the following disclaimer in the |
|
documentation and/or other materials provided with the distribution. |
|
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
|
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
|
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
|
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR |
|
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
|
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
|
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR |
|
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF |
|
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING |
|
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
|
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
|
*/ |
|
|
|
#ifndef CELT_H |
|
#define CELT_H |
|
|
|
#include "celt_types.h" |
|
|
|
#ifdef __cplusplus |
|
extern "C" { |
|
#endif |
|
|
|
#if defined(__GNUC__) && defined(CELT_BUILD) |
|
#define EXPORT __attribute__ ((visibility ("default"))) |
|
#elif defined(WIN32) |
|
#define EXPORT __declspec(dllexport) |
|
#else |
|
#define EXPORT |
|
#endif |
|
|
|
#define _celt_check_int(x) (((void)((x) == (celt_int32)0)), (celt_int32)(x)) |
|
#define _celt_check_mode_ptr_ptr(ptr) ((ptr) + ((ptr) - (const CELTMode**)(ptr))) |
|
#define _celt_check_int_ptr(ptr) ((ptr) + ((ptr) - (int*)(ptr))) |
|
|
|
/* Error codes */ |
|
/** No error */ |
|
#define CELT_OK 0 |
|
/** An (or more) invalid argument (e.g. out of range) */ |
|
#define CELT_BAD_ARG -1 |
|
/** The mode struct passed is invalid */ |
|
#define CELT_BUFFER_TOO_SMALL -2 |
|
/** An internal error was detected */ |
|
#define CELT_INTERNAL_ERROR -3 |
|
/** The data passed (e.g. compressed data to decoder) is corrupted */ |
|
#define CELT_CORRUPTED_DATA -4 |
|
/** Invalid/unsupported request number */ |
|
#define CELT_UNIMPLEMENTED -5 |
|
/** An encoder or decoder structure is invalid or already freed */ |
|
#define CELT_INVALID_STATE -6 |
|
/** Memory allocation has failed */ |
|
#define CELT_ALLOC_FAIL -7 |
|
|
|
|
|
/* Encoder/decoder Requests */ |
|
|
|
#define CELT_SET_COMPLEXITY_REQUEST 2 |
|
/** Controls the complexity from 0-10 (int) */ |
|
#define CELT_SET_COMPLEXITY(x) CELT_SET_COMPLEXITY_REQUEST, _celt_check_int(x) |
|
|
|
#define CELT_SET_PREDICTION_REQUEST 4 |
|
/** Controls the use of interframe prediction. |
|
0=Independent frames |
|
1=Short term interframe prediction allowed |
|
2=Long term prediction allowed |
|
*/ |
|
#define CELT_SET_PREDICTION(x) CELT_SET_PREDICTION_REQUEST, _celt_check_int(x) |
|
|
|
#define CELT_SET_BITRATE_REQUEST 6 |
|
/** Set the target VBR rate in bits per second(int); 0=CBR (default) */ |
|
#define CELT_SET_BITRATE(x) CELT_SET_BITRATE_REQUEST, _celt_check_int(x) |
|
|
|
#define CELT_RESET_STATE_REQUEST 8 |
|
/** Reset the encoder/decoder memories to zero*/ |
|
#define CELT_RESET_STATE CELT_RESET_STATE_REQUEST |
|
|
|
#define CELT_SET_VBR_CONSTRAINT_REQUEST 10 |
|
#define CELT_SET_VBR_CONSTRAINT(x) CELT_SET_VBR_CONSTRAINT_REQUEST, _celt_check_int(x) |
|
|
|
#define CELT_SET_VBR_REQUEST 12 |
|
#define CELT_SET_VBR(x) CELT_SET_VBR_REQUEST, _celt_check_int(x) |
|
|
|
#define CELT_SET_INPUT_CLIPPING_REQUEST 14 |
|
#define CELT_SET_INPUT_CLIPPING(x) CELT_SET_INPUT_CLIPPING_REQUEST, _celt_check_int(x) |
|
|
|
#define CELT_GET_AND_CLEAR_ERROR_REQUEST 15 |
|
#define CELT_GET_AND_CLEAR_ERROR(x) CELT_GET_AND_CLEAR_ERROR_REQUEST, _celt_check_int_ptr(x) |
|
|
|
#define CELT_GET_LOOKAHEAD_REQUEST 17 |
|
#define CELT_GET_LOOKAHEAD(x) CELT_GET_LOOKAHEAD_REQUEST, _celt_check_int_ptr(x) |
|
|
|
#define CELT_SET_CHANNELS_REQUEST 18 |
|
#define CELT_SET_CHANNELS(x) CELT_SET_CHANNELS_REQUEST, _celt_check_int(x) |
|
|
|
#define CELT_SET_LOSS_PERC_REQUEST 20 |
|
#define CELT_SET_LOSS_PERC(x) CELT_SET_LOSS_PERC_REQUEST, _celt_check_int(x) |
|
|
|
/* Internal */ |
|
#define CELT_SET_START_BAND_REQUEST 10000 |
|
#define CELT_SET_START_BAND(x) CELT_SET_START_BAND_REQUEST, _celt_check_int(x) |
|
|
|
#define CELT_SET_END_BAND_REQUEST 10001 |
|
#define CELT_SET_END_BAND(x) CELT_SET_END_BAND_REQUEST, _celt_check_int(x) |
|
|
|
|
|
|
|
/** Contains the state of an encoder. One encoder state is needed |
|
for each stream. It is initialised once at the beginning of the |
|
stream. Do *not* re-initialise the state for every frame. |
|
@brief Encoder state |
|
*/ |
|
typedef struct CELTEncoder CELTEncoder; |
|
|
|
/** State of the decoder. One decoder state is needed for each stream. |
|
It is initialised once at the beginning of the stream. Do *not* |
|
re-initialise the state for every frame */ |
|
typedef struct CELTDecoder CELTDecoder; |
|
|
|
/** The mode contains all the information necessary to create an |
|
encoder. Both the encoder and decoder need to be initialised |
|
with exactly the same mode, otherwise the quality will be very |
|
bad */ |
|
typedef struct CELTMode CELTMode; |
|
|
|
|
|
/** \defgroup codec Encoding and decoding */ |
|
/* @{ */ |
|
|
|
/* Mode calls */ |
|
|
|
/** Creates a new mode struct. This will be passed to an encoder or |
|
decoder. The mode MUST NOT BE DESTROYED until the encoders and |
|
decoders that use it are destroyed as well. |
|
@param Fs Sampling rate (32000 to 96000 Hz) |
|
@param frame_size Number of samples (per channel) to encode in each |
|
packet (even values; 64 - 512) |
|
@param error Returned error code (if NULL, no error will be returned) |
|
@return A newly created mode |
|
*/ |
|
EXPORT CELTMode *celt_mode_create(celt_int32 Fs, int frame_size, int *error); |
|
|
|
/** Destroys a mode struct. Only call this after all encoders and |
|
decoders using this mode are destroyed as well. |
|
@param mode Mode to be destroyed |
|
*/ |
|
EXPORT void celt_mode_destroy(CELTMode *mode); |
|
|
|
/* Encoder stuff */ |
|
|
|
EXPORT int celt_encoder_get_size(int channels); |
|
|
|
EXPORT int celt_encoder_get_size_custom(const CELTMode *mode, int channels); |
|
|
|
/** Creates a new encoder state. Each stream needs its own encoder |
|
state (can't be shared across simultaneous streams). |
|
@param channels Number of channels |
|
@param error Returns an error code |
|
@return Newly created encoder state. |
|
*/ |
|
EXPORT CELTEncoder *celt_encoder_create(int sampling_rate, int channels, int *error); |
|
|
|
/** Creates a new encoder state. Each stream needs its own encoder |
|
state (can't be shared across simultaneous streams). |
|
@param mode Contains all the information about the characteristics of |
|
* the stream (must be the same characteristics as used for the |
|
* decoder) |
|
@param channels Number of channels |
|
@param error Returns an error code |
|
@return Newly created encoder state. |
|
*/ |
|
EXPORT CELTEncoder *celt_encoder_create_custom(const CELTMode *mode, int channels, int *error); |
|
|
|
EXPORT CELTEncoder *celt_encoder_init(CELTEncoder *st, int sampling_rate, int channels, int *error); |
|
|
|
EXPORT CELTEncoder *celt_encoder_init_custom(CELTEncoder *st, const CELTMode *mode, int channels, int *error); |
|
|
|
/** Destroys a an encoder state. |
|
@param st Encoder state to be destroyed |
|
*/ |
|
EXPORT void celt_encoder_destroy(CELTEncoder *st); |
|
|
|
/** Encodes a frame of audio. |
|
@param st Encoder state |
|
@param pcm PCM audio in float format, with a normal range of ±1.0. |
|
* Samples with a range beyond ±1.0 are supported but will |
|
* be clipped by decoders using the integer API and should |
|
* only be used if it is known that the far end supports |
|
* extended dynmaic range. There must be exactly |
|
* frame_size samples per channel. |
|
@param compressed The compressed data is written here. This may not alias pcm or |
|
* optional_synthesis. |
|
@param nbCompressedBytes Maximum number of bytes to use for compressing the frame |
|
* (can change from one frame to another) |
|
@return Number of bytes written to "compressed". Will be the same as |
|
* "nbCompressedBytes" unless the stream is VBR and will never be larger. |
|
* If negative, an error has occurred (see error codes). It is IMPORTANT that |
|
* the length returned be somehow transmitted to the decoder. Otherwise, no |
|
* decoding is possible. |
|
*/ |
|
EXPORT int celt_encode_float(CELTEncoder *st, const float *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes); |
|
|
|
/** Encodes a frame of audio. |
|
@param st Encoder state |
|
@param pcm PCM audio in signed 16-bit format (native endian). There must be |
|
* exactly frame_size samples per channel. |
|
@param compressed The compressed data is written here. This may not alias pcm or |
|
* optional_synthesis. |
|
@param nbCompressedBytes Maximum number of bytes to use for compressing the frame |
|
* (can change from one frame to another) |
|
@return Number of bytes written to "compressed". Will be the same as |
|
* "nbCompressedBytes" unless the stream is VBR and will never be larger. |
|
* If negative, an error has occurred (see error codes). It is IMPORTANT that |
|
* the length returned be somehow transmitted to the decoder. Otherwise, no |
|
* decoding is possible. |
|
*/ |
|
EXPORT int celt_encode(CELTEncoder *st, const celt_int16 *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes); |
|
|
|
/** Query and set encoder parameters |
|
@param st Encoder state |
|
@param request Parameter to change or query |
|
@param value Pointer to a 32-bit int value |
|
@return Error code |
|
*/ |
|
EXPORT int celt_encoder_ctl(CELTEncoder * st, int request, ...); |
|
|
|
/* Decoder stuff */ |
|
|
|
EXPORT int celt_decoder_get_size(int channels); |
|
|
|
EXPORT int celt_decoder_get_size_custom(const CELTMode *mode, int channels); |
|
|
|
/** Creates a new decoder state. Each stream needs its own decoder state (can't |
|
be shared across simultaneous streams). |
|
@param mode Contains all the information about the characteristics of the |
|
stream (must be the same characteristics as used for the encoder) |
|
@param channels Number of channels |
|
@param error Returns an error code |
|
@return Newly created decoder state. |
|
*/ |
|
EXPORT CELTDecoder *celt_decoder_create(int sampling_rate, int channels, int *error); |
|
|
|
/** Creates a new decoder state. Each stream needs its own decoder state (can't |
|
be shared across simultaneous streams). |
|
@param mode Contains all the information about the characteristics of the |
|
stream (must be the same characteristics as used for the encoder) |
|
@param channels Number of channels |
|
@param error Returns an error code |
|
@return Newly created decoder state. |
|
*/ |
|
EXPORT CELTDecoder *celt_decoder_create_custom(const CELTMode *mode, int channels, int *error); |
|
|
|
EXPORT CELTDecoder *celt_decoder_init(CELTDecoder *st, int sampling_rate, int channels, int *error); |
|
|
|
EXPORT CELTDecoder *celt_decoder_init_custom(CELTDecoder *st, const CELTMode *mode, int channels, int *error); |
|
|
|
/** Destroys a a decoder state. |
|
@param st Decoder state to be destroyed |
|
*/ |
|
EXPORT void celt_decoder_destroy(CELTDecoder *st); |
|
|
|
/** Decodes a frame of audio. |
|
@param st Decoder state |
|
@param data Compressed data produced by an encoder |
|
@param len Number of bytes to read from "data". This MUST be exactly the number |
|
of bytes returned by the encoder. Using a larger value WILL NOT WORK. |
|
@param pcm One frame (frame_size samples per channel) of decoded PCM will be |
|
returned here in float format. |
|
@return Error code. |
|
*/ |
|
EXPORT int celt_decode_float(CELTDecoder *st, const unsigned char *data, int len, float *pcm, int frame_size); |
|
|
|
/** Decodes a frame of audio. |
|
@param st Decoder state |
|
@param data Compressed data produced by an encoder |
|
@param len Number of bytes to read from "data". This MUST be exactly the number |
|
of bytes returned by the encoder. Using a larger value WILL NOT WORK. |
|
@param pcm One frame (frame_size samples per channel) of decoded PCM will be |
|
returned here in 16-bit PCM format (native endian). |
|
@return Error code. |
|
*/ |
|
EXPORT int celt_decode(CELTDecoder *st, const unsigned char *data, int len, celt_int16 *pcm, int frame_size); |
|
|
|
/** Query and set decoder parameters |
|
@param st Decoder state |
|
@param request Parameter to change or query |
|
@param value Pointer to a 32-bit int value |
|
@return Error code |
|
*/ |
|
EXPORT int celt_decoder_ctl(CELTDecoder * st, int request, ...); |
|
|
|
|
|
/** Returns the English string that corresponds to an error code |
|
* @param error Error code (negative for an error, 0 for success |
|
* @return Constant string (must NOT be freed) |
|
*/ |
|
EXPORT const char *celt_strerror(int error); |
|
|
|
/* @} */ |
|
|
|
|
|
#ifdef __cplusplus |
|
} |
|
#endif |
|
|
|
#endif /*CELT_H */
|
|
|