Alexandre Lision | 744f742 | 2013-09-25 11:39:37 -0400 | [diff] [blame] | 1 | /* Copyright (c) 2007-2008 CSIRO |
| 2 | Copyright (c) 2007-2009 Xiph.Org Foundation |
| 3 | Copyright (c) 2008-2012 Gregory Maxwell |
| 4 | Written by Jean-Marc Valin and Gregory Maxwell */ |
| 5 | /* |
| 6 | Redistribution and use in source and binary forms, with or without |
| 7 | modification, are permitted provided that the following conditions |
| 8 | are met: |
| 9 | |
| 10 | - Redistributions of source code must retain the above copyright |
| 11 | notice, this list of conditions and the following disclaimer. |
| 12 | |
| 13 | - Redistributions in binary form must reproduce the above copyright |
| 14 | notice, this list of conditions and the following disclaimer in the |
| 15 | documentation and/or other materials provided with the distribution. |
| 16 | |
| 17 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 18 | ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 19 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 20 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER |
| 21 | OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
| 22 | EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
| 23 | PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR |
| 24 | PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF |
| 25 | LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING |
| 26 | NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
| 27 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 28 | */ |
| 29 | |
| 30 | /** |
| 31 | @file opus_custom.h |
| 32 | @brief Opus-Custom reference implementation API |
| 33 | */ |
| 34 | |
| 35 | #ifndef OPUS_CUSTOM_H |
| 36 | #define OPUS_CUSTOM_H |
| 37 | |
| 38 | #include "opus_defines.h" |
| 39 | |
| 40 | #ifdef __cplusplus |
| 41 | extern "C" { |
| 42 | #endif |
| 43 | |
| 44 | #ifdef CUSTOM_MODES |
Alexandre Lision | 8538238 | 2014-01-27 15:54:16 -0500 | [diff] [blame] | 45 | # define OPUS_CUSTOM_EXPORT OPUS_EXPORT |
| 46 | # define OPUS_CUSTOM_EXPORT_STATIC OPUS_EXPORT |
Alexandre Lision | 744f742 | 2013-09-25 11:39:37 -0400 | [diff] [blame] | 47 | #else |
Alexandre Lision | 8538238 | 2014-01-27 15:54:16 -0500 | [diff] [blame] | 48 | # define OPUS_CUSTOM_EXPORT |
| 49 | # ifdef OPUS_BUILD |
| 50 | # define OPUS_CUSTOM_EXPORT_STATIC static OPUS_INLINE |
| 51 | # else |
| 52 | # define OPUS_CUSTOM_EXPORT_STATIC |
| 53 | # endif |
Alexandre Lision | 744f742 | 2013-09-25 11:39:37 -0400 | [diff] [blame] | 54 | #endif |
| 55 | |
| 56 | /** @defgroup opus_custom Opus Custom |
| 57 | * @{ |
| 58 | * Opus Custom is an optional part of the Opus specification and |
| 59 | * reference implementation which uses a distinct API from the regular |
| 60 | * API and supports frame sizes that are not normally supported.\ Use |
| 61 | * of Opus Custom is discouraged for all but very special applications |
| 62 | * for which a frame size different from 2.5, 5, 10, or 20 ms is needed |
| 63 | * (for either complexity or latency reasons) and where interoperability |
| 64 | * is less important. |
| 65 | * |
| 66 | * In addition to the interoperability limitations the use of Opus custom |
| 67 | * disables a substantial chunk of the codec and generally lowers the |
| 68 | * quality available at a given bitrate. Normally when an application needs |
| 69 | * a different frame size from the codec it should buffer to match the |
| 70 | * sizes but this adds a small amount of delay which may be important |
| 71 | * in some very low latency applications. Some transports (especially |
| 72 | * constant rate RF transports) may also work best with frames of |
| 73 | * particular durations. |
| 74 | * |
| 75 | * Libopus only supports custom modes if they are enabled at compile time. |
| 76 | * |
| 77 | * The Opus Custom API is similar to the regular API but the |
| 78 | * @ref opus_encoder_create and @ref opus_decoder_create calls take |
| 79 | * an additional mode parameter which is a structure produced by |
| 80 | * a call to @ref opus_custom_mode_create. Both the encoder and decoder |
| 81 | * must create a mode using the same sample rate (fs) and frame size |
| 82 | * (frame size) so these parameters must either be signaled out of band |
| 83 | * or fixed in a particular implementation. |
| 84 | * |
| 85 | * Similar to regular Opus the custom modes support on the fly frame size |
| 86 | * switching, but the sizes available depend on the particular frame size in |
| 87 | * use. For some initial frame sizes on a single on the fly size is available. |
| 88 | */ |
| 89 | |
| 90 | /** Contains the state of an encoder. One encoder state is needed |
| 91 | for each stream. It is initialized once at the beginning of the |
| 92 | stream. Do *not* re-initialize the state for every frame. |
| 93 | @brief Encoder state |
| 94 | */ |
| 95 | typedef struct OpusCustomEncoder OpusCustomEncoder; |
| 96 | |
| 97 | /** State of the decoder. One decoder state is needed for each stream. |
| 98 | It is initialized once at the beginning of the stream. Do *not* |
| 99 | re-initialize the state for every frame. |
| 100 | @brief Decoder state |
| 101 | */ |
| 102 | typedef struct OpusCustomDecoder OpusCustomDecoder; |
| 103 | |
| 104 | /** The mode contains all the information necessary to create an |
| 105 | encoder. Both the encoder and decoder need to be initialized |
| 106 | with exactly the same mode, otherwise the output will be |
| 107 | corrupted. |
| 108 | @brief Mode configuration |
| 109 | */ |
| 110 | typedef struct OpusCustomMode OpusCustomMode; |
| 111 | |
| 112 | /** Creates a new mode struct. This will be passed to an encoder or |
| 113 | * decoder. The mode MUST NOT BE DESTROYED until the encoders and |
| 114 | * decoders that use it are destroyed as well. |
| 115 | * @param [in] Fs <tt>int</tt>: Sampling rate (8000 to 96000 Hz) |
| 116 | * @param [in] frame_size <tt>int</tt>: Number of samples (per channel) to encode in each |
| 117 | * packet (64 - 1024, prime factorization must contain zero or more 2s, 3s, or 5s and no other primes) |
| 118 | * @param [out] error <tt>int*</tt>: Returned error code (if NULL, no error will be returned) |
| 119 | * @return A newly created mode |
| 120 | */ |
| 121 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomMode *opus_custom_mode_create(opus_int32 Fs, int frame_size, int *error); |
| 122 | |
| 123 | /** Destroys a mode struct. Only call this after all encoders and |
| 124 | * decoders using this mode are destroyed as well. |
| 125 | * @param [in] mode <tt>OpusCustomMode*</tt>: Mode to be freed. |
| 126 | */ |
| 127 | OPUS_CUSTOM_EXPORT void opus_custom_mode_destroy(OpusCustomMode *mode); |
| 128 | |
Alexandre Lision | 8538238 | 2014-01-27 15:54:16 -0500 | [diff] [blame] | 129 | |
| 130 | #if !defined(OPUS_BUILD) || defined(CELT_ENCODER_C) |
| 131 | |
Alexandre Lision | 744f742 | 2013-09-25 11:39:37 -0400 | [diff] [blame] | 132 | /* Encoder */ |
| 133 | /** Gets the size of an OpusCustomEncoder structure. |
| 134 | * @param [in] mode <tt>OpusCustomMode *</tt>: Mode configuration |
| 135 | * @param [in] channels <tt>int</tt>: Number of channels |
| 136 | * @returns size |
| 137 | */ |
| 138 | OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_encoder_get_size( |
| 139 | const OpusCustomMode *mode, |
| 140 | int channels |
| 141 | ) OPUS_ARG_NONNULL(1); |
| 142 | |
Alexandre Lision | 8538238 | 2014-01-27 15:54:16 -0500 | [diff] [blame] | 143 | # ifdef CUSTOM_MODES |
| 144 | /** Initializes a previously allocated encoder state |
| 145 | * The memory pointed to by st must be the size returned by opus_custom_encoder_get_size. |
| 146 | * This is intended for applications which use their own allocator instead of malloc. |
| 147 | * @see opus_custom_encoder_create(),opus_custom_encoder_get_size() |
| 148 | * To reset a previously initialized state use the OPUS_RESET_STATE CTL. |
| 149 | * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state |
| 150 | * @param [in] mode <tt>OpusCustomMode *</tt>: Contains all the information about the characteristics of |
| 151 | * the stream (must be the same characteristics as used for the |
| 152 | * decoder) |
| 153 | * @param [in] channels <tt>int</tt>: Number of channels |
| 154 | * @return OPUS_OK Success or @ref opus_errorcodes |
| 155 | */ |
| 156 | OPUS_CUSTOM_EXPORT int opus_custom_encoder_init( |
| 157 | OpusCustomEncoder *st, |
| 158 | const OpusCustomMode *mode, |
| 159 | int channels |
| 160 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2); |
| 161 | # endif |
| 162 | #endif |
| 163 | |
| 164 | |
Alexandre Lision | 744f742 | 2013-09-25 11:39:37 -0400 | [diff] [blame] | 165 | /** Creates a new encoder state. Each stream needs its own encoder |
| 166 | * state (can't be shared across simultaneous streams). |
| 167 | * @param [in] mode <tt>OpusCustomMode*</tt>: Contains all the information about the characteristics of |
| 168 | * the stream (must be the same characteristics as used for the |
| 169 | * decoder) |
| 170 | * @param [in] channels <tt>int</tt>: Number of channels |
| 171 | * @param [out] error <tt>int*</tt>: Returns an error code |
| 172 | * @return Newly created encoder state. |
| 173 | */ |
| 174 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomEncoder *opus_custom_encoder_create( |
| 175 | const OpusCustomMode *mode, |
| 176 | int channels, |
| 177 | int *error |
| 178 | ) OPUS_ARG_NONNULL(1); |
| 179 | |
Alexandre Lision | 744f742 | 2013-09-25 11:39:37 -0400 | [diff] [blame] | 180 | |
| 181 | /** Destroys a an encoder state. |
| 182 | * @param[in] st <tt>OpusCustomEncoder*</tt>: State to be freed. |
| 183 | */ |
| 184 | OPUS_CUSTOM_EXPORT void opus_custom_encoder_destroy(OpusCustomEncoder *st); |
| 185 | |
| 186 | /** Encodes a frame of audio. |
| 187 | * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state |
| 188 | * @param [in] pcm <tt>float*</tt>: PCM audio in float format, with a normal range of +/-1.0. |
| 189 | * Samples with a range beyond +/-1.0 are supported but will |
| 190 | * be clipped by decoders using the integer API and should |
| 191 | * only be used if it is known that the far end supports |
| 192 | * extended dynamic range. There must be exactly |
| 193 | * frame_size samples per channel. |
| 194 | * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal |
| 195 | * @param [out] compressed <tt>char *</tt>: The compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long. |
| 196 | * @param [in] maxCompressedBytes <tt>int</tt>: Maximum number of bytes to use for compressing the frame |
| 197 | * (can change from one frame to another) |
| 198 | * @return Number of bytes written to "compressed". |
| 199 | * If negative, an error has occurred (see error codes). It is IMPORTANT that |
| 200 | * the length returned be somehow transmitted to the decoder. Otherwise, no |
| 201 | * decoding is possible. |
| 202 | */ |
| 203 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode_float( |
| 204 | OpusCustomEncoder *st, |
| 205 | const float *pcm, |
| 206 | int frame_size, |
| 207 | unsigned char *compressed, |
| 208 | int maxCompressedBytes |
| 209 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4); |
| 210 | |
| 211 | /** Encodes a frame of audio. |
| 212 | * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state |
| 213 | * @param [in] pcm <tt>opus_int16*</tt>: PCM audio in signed 16-bit format (native endian). |
| 214 | * There must be exactly frame_size samples per channel. |
| 215 | * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal |
| 216 | * @param [out] compressed <tt>char *</tt>: The compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long. |
| 217 | * @param [in] maxCompressedBytes <tt>int</tt>: 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". |
| 220 | * If negative, an error has occurred (see error codes). It is IMPORTANT that |
| 221 | * the length returned be somehow transmitted to the decoder. Otherwise, no |
| 222 | * decoding is possible. |
| 223 | */ |
| 224 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode( |
| 225 | OpusCustomEncoder *st, |
| 226 | const opus_int16 *pcm, |
| 227 | int frame_size, |
| 228 | unsigned char *compressed, |
| 229 | int maxCompressedBytes |
| 230 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4); |
| 231 | |
| 232 | /** Perform a CTL function on an Opus custom encoder. |
| 233 | * |
| 234 | * Generally the request and subsequent arguments are generated |
| 235 | * by a convenience macro. |
| 236 | * @see opus_encoderctls |
| 237 | */ |
| 238 | OPUS_CUSTOM_EXPORT int opus_custom_encoder_ctl(OpusCustomEncoder * OPUS_RESTRICT st, int request, ...) OPUS_ARG_NONNULL(1); |
| 239 | |
Alexandre Lision | 8538238 | 2014-01-27 15:54:16 -0500 | [diff] [blame] | 240 | |
| 241 | #if !defined(OPUS_BUILD) || defined(CELT_DECODER_C) |
Alexandre Lision | 744f742 | 2013-09-25 11:39:37 -0400 | [diff] [blame] | 242 | /* Decoder */ |
| 243 | |
| 244 | /** Gets the size of an OpusCustomDecoder structure. |
| 245 | * @param [in] mode <tt>OpusCustomMode *</tt>: Mode configuration |
| 246 | * @param [in] channels <tt>int</tt>: Number of channels |
| 247 | * @returns size |
| 248 | */ |
| 249 | OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_decoder_get_size( |
| 250 | const OpusCustomMode *mode, |
| 251 | int channels |
| 252 | ) OPUS_ARG_NONNULL(1); |
| 253 | |
Alexandre Lision | 744f742 | 2013-09-25 11:39:37 -0400 | [diff] [blame] | 254 | /** Initializes a previously allocated decoder state |
| 255 | * The memory pointed to by st must be the size returned by opus_custom_decoder_get_size. |
| 256 | * This is intended for applications which use their own allocator instead of malloc. |
| 257 | * @see opus_custom_decoder_create(),opus_custom_decoder_get_size() |
| 258 | * To reset a previously initialized state use the OPUS_RESET_STATE CTL. |
| 259 | * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state |
| 260 | * @param [in] mode <tt>OpusCustomMode *</tt>: Contains all the information about the characteristics of |
| 261 | * the stream (must be the same characteristics as used for the |
| 262 | * encoder) |
| 263 | * @param [in] channels <tt>int</tt>: Number of channels |
| 264 | * @return OPUS_OK Success or @ref opus_errorcodes |
| 265 | */ |
| 266 | OPUS_CUSTOM_EXPORT_STATIC int opus_custom_decoder_init( |
| 267 | OpusCustomDecoder *st, |
| 268 | const OpusCustomMode *mode, |
| 269 | int channels |
| 270 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2); |
| 271 | |
Alexandre Lision | 8538238 | 2014-01-27 15:54:16 -0500 | [diff] [blame] | 272 | #endif |
| 273 | |
| 274 | |
| 275 | /** Creates a new decoder state. Each stream needs its own decoder state (can't |
| 276 | * be shared across simultaneous streams). |
| 277 | * @param [in] mode <tt>OpusCustomMode</tt>: Contains all the information about the characteristics of the |
| 278 | * stream (must be the same characteristics as used for the encoder) |
| 279 | * @param [in] channels <tt>int</tt>: Number of channels |
| 280 | * @param [out] error <tt>int*</tt>: Returns an error code |
| 281 | * @return Newly created decoder state. |
| 282 | */ |
| 283 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomDecoder *opus_custom_decoder_create( |
| 284 | const OpusCustomMode *mode, |
| 285 | int channels, |
| 286 | int *error |
| 287 | ) OPUS_ARG_NONNULL(1); |
| 288 | |
Alexandre Lision | 744f742 | 2013-09-25 11:39:37 -0400 | [diff] [blame] | 289 | /** Destroys a an decoder state. |
| 290 | * @param[in] st <tt>OpusCustomDecoder*</tt>: State to be freed. |
| 291 | */ |
| 292 | OPUS_CUSTOM_EXPORT void opus_custom_decoder_destroy(OpusCustomDecoder *st); |
| 293 | |
| 294 | /** Decode an opus custom frame with floating point output |
| 295 | * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state |
| 296 | * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss |
| 297 | * @param [in] len <tt>int</tt>: Number of bytes in payload |
| 298 | * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length |
| 299 | * is frame_size*channels*sizeof(float) |
| 300 | * @param [in] frame_size Number of samples per channel of available space in *pcm. |
| 301 | * @returns Number of decoded samples or @ref opus_errorcodes |
| 302 | */ |
| 303 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode_float( |
| 304 | OpusCustomDecoder *st, |
| 305 | const unsigned char *data, |
| 306 | int len, |
| 307 | float *pcm, |
| 308 | int frame_size |
| 309 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); |
| 310 | |
| 311 | /** Decode an opus custom frame |
| 312 | * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state |
| 313 | * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss |
| 314 | * @param [in] len <tt>int</tt>: Number of bytes in payload |
| 315 | * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length |
| 316 | * is frame_size*channels*sizeof(opus_int16) |
| 317 | * @param [in] frame_size Number of samples per channel of available space in *pcm. |
| 318 | * @returns Number of decoded samples or @ref opus_errorcodes |
| 319 | */ |
| 320 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode( |
| 321 | OpusCustomDecoder *st, |
| 322 | const unsigned char *data, |
| 323 | int len, |
| 324 | opus_int16 *pcm, |
| 325 | int frame_size |
| 326 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); |
| 327 | |
| 328 | /** Perform a CTL function on an Opus custom decoder. |
| 329 | * |
| 330 | * Generally the request and subsequent arguments are generated |
| 331 | * by a convenience macro. |
| 332 | * @see opus_genericctls |
| 333 | */ |
| 334 | OPUS_CUSTOM_EXPORT int opus_custom_decoder_ctl(OpusCustomDecoder * OPUS_RESTRICT st, int request, ...) OPUS_ARG_NONNULL(1); |
| 335 | |
| 336 | /**@}*/ |
| 337 | |
| 338 | #ifdef __cplusplus |
| 339 | } |
| 340 | #endif |
| 341 | |
| 342 | #endif /* OPUS_CUSTOM_H */ |