The Tor Browser / file comparison
comparison: media/libopus/include/opus_custom.h
media/libopus/include/opus_custom.h
- changeset 0
- 6474c204b198
equal
deleted
inserted
replaced
| -1:000000000000 | 0:c675c6eb8df0 |
|---|---|
| 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 | |
| 45 # define OPUS_CUSTOM_EXPORT OPUS_EXPORT | |
| 46 # define OPUS_CUSTOM_EXPORT_STATIC OPUS_EXPORT | |
| 47 #else | |
| 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 | |
| 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 | |
| 129 | |
| 130 #if !defined(OPUS_BUILD) || defined(CELT_ENCODER_C) | |
| 131 | |
| 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 | |
| 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 | |
| 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 | |
| 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 | |
| 240 | |
| 241 #if !defined(OPUS_BUILD) || defined(CELT_DECODER_C) | |
| 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 | |
| 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 | |
| 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 | |
| 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 */ |
