Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 1 | /* Copyright (c) 2007-2008 CSIRO |
| 2 | Copyright (c) 2007-2009 Xiph.Org Foundation |
Ralph Giles | 5f6e472 | 2012-03-19 17:10:13 -0700 | [diff] [blame] | 3 | Copyright (c) 2008 Gregory Maxwell |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 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: |
Ralph Giles | 5f6e472 | 2012-03-19 17:10:13 -0700 | [diff] [blame] | 14 | |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 15 | - Redistributions of source code must retain the above copyright |
| 16 | notice, this list of conditions and the following disclaimer. |
Ralph Giles | 5f6e472 | 2012-03-19 17:10:13 -0700 | [diff] [blame] | 17 | |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 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. |
Ralph Giles | 5f6e472 | 2012-03-19 17:10:13 -0700 | [diff] [blame] | 21 | |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 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 |
Jean-Marc Valin | cb05e7c | 2012-04-20 16:40:24 -0400 | [diff] [blame] | 25 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER |
| 26 | OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 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 | #ifndef OPUS_CUSTOM_H |
| 36 | #define OPUS_CUSTOM_H |
| 37 | |
| 38 | |
| 39 | #include "opus_defines.h" |
| 40 | |
| 41 | #ifdef __cplusplus |
| 42 | extern "C" { |
| 43 | #endif |
| 44 | |
Jean-Marc Valin | 3870ddb | 2011-09-01 15:22:37 -0400 | [diff] [blame] | 45 | #ifdef CUSTOM_MODES |
| 46 | #define OPUS_CUSTOM_EXPORT OPUS_EXPORT |
Gregory Maxwell | afc8d53 | 2011-09-28 15:13:26 -0400 | [diff] [blame] | 47 | #define OPUS_CUSTOM_EXPORT_STATIC OPUS_EXPORT |
Jean-Marc Valin | 3870ddb | 2011-09-01 15:22:37 -0400 | [diff] [blame] | 48 | #else |
| 49 | #define OPUS_CUSTOM_EXPORT |
Gregory Maxwell | afc8d53 | 2011-09-28 15:13:26 -0400 | [diff] [blame] | 50 | #ifdef CELT_C |
| 51 | #define OPUS_CUSTOM_EXPORT_STATIC static inline |
| 52 | #else |
| 53 | #define OPUS_CUSTOM_EXPORT_STATIC |
| 54 | #endif |
Jean-Marc Valin | 3870ddb | 2011-09-01 15:22:37 -0400 | [diff] [blame] | 55 | #endif |
| 56 | |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 57 | /** Contains the state of an encoder. One encoder state is needed |
| 58 | for each stream. It is initialised once at the beginning of the |
| 59 | stream. Do *not* re-initialise the state for every frame. |
| 60 | @brief Encoder state |
| 61 | */ |
Jean-Marc Valin | 242da53 | 2011-09-05 20:53:33 -0400 | [diff] [blame] | 62 | typedef struct OpusCustomEncoder OpusCustomEncoder; |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 63 | |
| 64 | /** State of the decoder. One decoder state is needed for each stream. |
| 65 | It is initialised once at the beginning of the stream. Do *not* |
| 66 | re-initialise the state for every frame */ |
Jean-Marc Valin | 242da53 | 2011-09-05 20:53:33 -0400 | [diff] [blame] | 67 | typedef struct OpusCustomDecoder OpusCustomDecoder; |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 68 | |
| 69 | /** The mode contains all the information necessary to create an |
| 70 | encoder. Both the encoder and decoder need to be initialised |
| 71 | with exactly the same mode, otherwise the quality will be very |
| 72 | bad */ |
Jean-Marc Valin | 242da53 | 2011-09-05 20:53:33 -0400 | [diff] [blame] | 73 | typedef struct OpusCustomMode OpusCustomMode; |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 74 | |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 75 | /** Creates a new mode struct. This will be passed to an encoder or |
| 76 | decoder. The mode MUST NOT BE DESTROYED until the encoders and |
| 77 | decoders that use it are destroyed as well. |
| 78 | @param Fs Sampling rate (32000 to 96000 Hz) |
| 79 | @param frame_size Number of samples (per channel) to encode in each |
| 80 | packet (even values; 64 - 512) |
| 81 | @param error Returned error code (if NULL, no error will be returned) |
| 82 | @return A newly created mode |
| 83 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame^] | 84 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomMode *opus_custom_mode_create(opus_int32 Fs, int frame_size, int *error); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 85 | |
| 86 | /** Destroys a mode struct. Only call this after all encoders and |
| 87 | decoders using this mode are destroyed as well. |
| 88 | @param mode Mode to be destroyed |
| 89 | */ |
Jean-Marc Valin | 242da53 | 2011-09-05 20:53:33 -0400 | [diff] [blame] | 90 | OPUS_CUSTOM_EXPORT void opus_custom_mode_destroy(OpusCustomMode *mode); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 91 | |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 92 | /* Encoder */ |
| 93 | |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame^] | 94 | OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_encoder_get_size(const OpusCustomMode *mode, int channels); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 95 | |
| 96 | /** Creates a new encoder state. Each stream needs its own encoder |
| 97 | state (can't be shared across simultaneous streams). |
| 98 | @param mode Contains all the information about the characteristics of |
| 99 | * the stream (must be the same characteristics as used for the |
| 100 | * decoder) |
| 101 | @param channels Number of channels |
| 102 | @param error Returns an error code |
| 103 | @return Newly created encoder state. |
| 104 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame^] | 105 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomEncoder *opus_custom_encoder_create(const OpusCustomMode *mode, int channels, int *error); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 106 | |
Gregory Maxwell | afc8d53 | 2011-09-28 15:13:26 -0400 | [diff] [blame] | 107 | OPUS_CUSTOM_EXPORT_STATIC int opus_custom_encoder_init(OpusCustomEncoder *st, const OpusCustomMode *mode, int channels); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 108 | |
| 109 | /** Destroys a an encoder state. |
| 110 | @param st Encoder state to be destroyed |
| 111 | */ |
Jean-Marc Valin | 242da53 | 2011-09-05 20:53:33 -0400 | [diff] [blame] | 112 | OPUS_CUSTOM_EXPORT void opus_custom_encoder_destroy(OpusCustomEncoder *st); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 113 | |
| 114 | /** Encodes a frame of audio. |
| 115 | @param st Encoder state |
| 116 | @param pcm PCM audio in float format, with a normal range of +/-1.0. |
| 117 | * Samples with a range beyond +/-1.0 are supported but will |
| 118 | * be clipped by decoders using the integer API and should |
| 119 | * only be used if it is known that the far end supports |
| 120 | * extended dynmaic range. There must be exactly |
| 121 | * frame_size samples per channel. |
| 122 | @param compressed The compressed data is written here. This may not alias pcm or |
| 123 | * optional_synthesis. |
| 124 | @param nbCompressedBytes Maximum number of bytes to use for compressing the frame |
| 125 | * (can change from one frame to another) |
| 126 | @return Number of bytes written to "compressed". Will be the same as |
| 127 | * "nbCompressedBytes" unless the stream is VBR and will never be larger. |
| 128 | * If negative, an error has occurred (see error codes). It is IMPORTANT that |
| 129 | * the length returned be somehow transmitted to the decoder. Otherwise, no |
| 130 | * decoding is possible. |
| 131 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame^] | 132 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode_float(OpusCustomEncoder *st, const float *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 133 | |
| 134 | /** Encodes a frame of audio. |
| 135 | @param st Encoder state |
| 136 | @param pcm PCM audio in signed 16-bit format (native endian). There must be |
| 137 | * exactly frame_size samples per channel. |
| 138 | @param compressed The compressed data is written here. This may not alias pcm or |
| 139 | * optional_synthesis. |
| 140 | @param nbCompressedBytes Maximum number of bytes to use for compressing the frame |
| 141 | * (can change from one frame to another) |
| 142 | @return Number of bytes written to "compressed". Will be the same as |
| 143 | * "nbCompressedBytes" unless the stream is VBR and will never be larger. |
| 144 | * If negative, an error has occurred (see error codes). It is IMPORTANT that |
| 145 | * the length returned be somehow transmitted to the decoder. Otherwise, no |
| 146 | * decoding is possible. |
| 147 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame^] | 148 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode(OpusCustomEncoder *st, const opus_int16 *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 149 | |
| 150 | /** Query and set encoder parameters |
| 151 | @param st Encoder state |
| 152 | @param request Parameter to change or query |
| 153 | @param value Pointer to a 32-bit int value |
| 154 | @return Error code |
| 155 | */ |
Jean-Marc Valin | 242da53 | 2011-09-05 20:53:33 -0400 | [diff] [blame] | 156 | OPUS_CUSTOM_EXPORT int opus_custom_encoder_ctl(OpusCustomEncoder * restrict st, int request, ...); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 157 | |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 158 | /* Decoder */ |
| 159 | |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame^] | 160 | OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_decoder_get_size(const OpusCustomMode *mode, int channels); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 161 | |
| 162 | /** Creates a new decoder state. Each stream needs its own decoder state (can't |
| 163 | be shared across simultaneous streams). |
| 164 | @param mode Contains all the information about the characteristics of the |
| 165 | stream (must be the same characteristics as used for the encoder) |
| 166 | @param channels Number of channels |
| 167 | @param error Returns an error code |
| 168 | @return Newly created decoder state. |
| 169 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame^] | 170 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomDecoder *opus_custom_decoder_create(const OpusCustomMode *mode, int channels, int *error); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 171 | |
Gregory Maxwell | afc8d53 | 2011-09-28 15:13:26 -0400 | [diff] [blame] | 172 | OPUS_CUSTOM_EXPORT_STATIC int opus_custom_decoder_init(OpusCustomDecoder *st, const OpusCustomMode *mode, int channels); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 173 | |
| 174 | /** Destroys a a decoder state. |
| 175 | @param st Decoder state to be destroyed |
| 176 | */ |
Jean-Marc Valin | 242da53 | 2011-09-05 20:53:33 -0400 | [diff] [blame] | 177 | OPUS_CUSTOM_EXPORT void opus_custom_decoder_destroy(OpusCustomDecoder *st); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 178 | |
| 179 | /** Decodes a frame of audio. |
| 180 | @param st Decoder state |
| 181 | @param data Compressed data produced by an encoder |
| 182 | @param len Number of bytes to read from "data". This MUST be exactly the number |
| 183 | of bytes returned by the encoder. Using a larger value WILL NOT WORK. |
| 184 | @param pcm One frame (frame_size samples per channel) of decoded PCM will be |
| 185 | returned here in float format. |
| 186 | @return Error code. |
| 187 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame^] | 188 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode_float(OpusCustomDecoder *st, const unsigned char *data, int len, float *pcm, int frame_size); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 189 | |
| 190 | /** Decodes a frame of audio. |
| 191 | @param st Decoder state |
| 192 | @param data Compressed data produced by an encoder |
| 193 | @param len Number of bytes to read from "data". This MUST be exactly the number |
| 194 | of bytes returned by the encoder. Using a larger value WILL NOT WORK. |
| 195 | @param pcm One frame (frame_size samples per channel) of decoded PCM will be |
| 196 | returned here in 16-bit PCM format (native endian). |
| 197 | @return Error code. |
| 198 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame^] | 199 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode(OpusCustomDecoder *st, const unsigned char *data, int len, opus_int16 *pcm, int frame_size); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 200 | |
| 201 | /** Query and set decoder parameters |
| 202 | @param st Decoder state |
| 203 | @param request Parameter to change or query |
| 204 | @param value Pointer to a 32-bit int value |
| 205 | @return Error code |
| 206 | */ |
Jean-Marc Valin | 242da53 | 2011-09-05 20:53:33 -0400 | [diff] [blame] | 207 | OPUS_CUSTOM_EXPORT int opus_custom_decoder_ctl(OpusCustomDecoder * restrict st, int request, ...); |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 208 | |
Jean-Marc Valin | 06237d7 | 2011-09-01 13:20:40 -0400 | [diff] [blame] | 209 | #ifdef __cplusplus |
| 210 | } |
| 211 | #endif |
| 212 | |
| 213 | #endif /* OPUS_CUSTOM_H */ |