Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 1 | /* Copyright (c) 2010-2011 Xiph.Org Foundation, Skype Limited |
| 2 | Written by Jean-Marc Valin and Koen Vos */ |
| 3 | /* |
| 4 | Redistribution and use in source and binary forms, with or without |
| 5 | modification, are permitted provided that the following conditions |
| 6 | are met: |
| 7 | |
| 8 | - Redistributions of source code must retain the above copyright |
| 9 | notice, this list of conditions and the following disclaimer. |
| 10 | |
| 11 | - Redistributions in binary form must reproduce the above copyright |
| 12 | notice, this list of conditions and the following disclaimer in the |
| 13 | documentation and/or other materials provided with the distribution. |
| 14 | |
| 15 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 16 | ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 17 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 18 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER |
| 19 | OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
| 20 | EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
| 21 | PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR |
| 22 | PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF |
| 23 | LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING |
| 24 | NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
| 25 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 26 | */ |
| 27 | |
| 28 | /** |
| 29 | * @file opus.h |
| 30 | * @brief Opus reference implementation API |
| 31 | */ |
| 32 | |
| 33 | #ifndef OPUS_H |
| 34 | #define OPUS_H |
| 35 | |
| 36 | #include "opus_types.h" |
| 37 | #include "opus_defines.h" |
| 38 | |
| 39 | #ifdef __cplusplus |
| 40 | extern "C" { |
| 41 | #endif |
| 42 | |
| 43 | /** |
| 44 | * @mainpage Opus |
| 45 | * |
| 46 | * The Opus codec is designed for interactive speech and audio transmission over the Internet. |
| 47 | * It is designed by the IETF Codec Working Group and incorporates technology from |
| 48 | * Skype's SILK codec and Xiph.Org's CELT codec. |
| 49 | * |
| 50 | * The Opus codec is designed to handle a wide range of interactive audio applications, |
| 51 | * including Voice over IP, videoconferencing, in-game chat, and even remote live music |
| 52 | * performances. It can scale from low bit-rate narrowband speech to very high quality |
| 53 | * stereo music. Its main features are: |
| 54 | |
| 55 | * @li Sampling rates from 8 to 48 kHz |
| 56 | * @li Bit-rates from 6 kb/s to 510 kb/s |
| 57 | * @li Support for both constant bit-rate (CBR) and variable bit-rate (VBR) |
| 58 | * @li Audio bandwidth from narrowband to full-band |
| 59 | * @li Support for speech and music |
| 60 | * @li Support for mono and stereo |
| 61 | * @li Support for multichannel (up to 255 channels) |
| 62 | * @li Frame sizes from 2.5 ms to 60 ms |
| 63 | * @li Good loss robustness and packet loss concealment (PLC) |
| 64 | * @li Floating point and fixed-point implementation |
| 65 | * |
| 66 | * Documentation sections: |
| 67 | * @li @ref opus_encoder |
| 68 | * @li @ref opus_decoder |
| 69 | * @li @ref opus_repacketizer |
| 70 | * @li @ref opus_multistream |
| 71 | * @li @ref opus_libinfo |
| 72 | * @li @ref opus_custom |
| 73 | */ |
| 74 | |
| 75 | /** @defgroup opus_encoder Opus Encoder |
| 76 | * @{ |
| 77 | * |
| 78 | * @brief This page describes the process and functions used to encode Opus. |
| 79 | * |
| 80 | * Since Opus is a stateful codec, the encoding process starts with creating an encoder |
| 81 | * state. This can be done with: |
| 82 | * |
| 83 | * @code |
| 84 | * int error; |
| 85 | * OpusEncoder *enc; |
| 86 | * enc = opus_encoder_create(Fs, channels, application, &error); |
| 87 | * @endcode |
| 88 | * |
| 89 | * From this point, @c enc can be used for encoding an audio stream. An encoder state |
| 90 | * @b must @b not be used for more than one stream at the same time. Similarly, the encoder |
| 91 | * state @b must @b not be re-initialized for each frame. |
| 92 | * |
| 93 | * While opus_encoder_create() allocates memory for the state, it's also possible |
| 94 | * to initialize pre-allocated memory: |
| 95 | * |
| 96 | * @code |
| 97 | * int size; |
| 98 | * int error; |
| 99 | * OpusEncoder *enc; |
| 100 | * size = opus_encoder_get_size(channels); |
| 101 | * enc = malloc(size); |
| 102 | * error = opus_encoder_init(enc, Fs, channels, application); |
| 103 | * @endcode |
| 104 | * |
| 105 | * where opus_encoder_get_size() returns the required size for the encoder state. Note that |
| 106 | * future versions of this code may change the size, so no assuptions should be made about it. |
| 107 | * |
| 108 | * The encoder state is always continuous in memory and only a shallow copy is sufficient |
| 109 | * to copy it (e.g. memcpy()) |
| 110 | * |
| 111 | * It is possible to change some of the encoder's settings using the opus_encoder_ctl() |
| 112 | * interface. All these settings already default to the recommended value, so they should |
| 113 | * only be changed when necessary. The most common settings one may want to change are: |
| 114 | * |
| 115 | * @code |
| 116 | * opus_encoder_ctl(enc, OPUS_SET_BITRATE(bitrate)); |
| 117 | * opus_encoder_ctl(enc, OPUS_SET_COMPLEXITY(complexity)); |
| 118 | * opus_encoder_ctl(enc, OPUS_SET_SIGNAL(signal_type)); |
| 119 | * @endcode |
| 120 | * |
| 121 | * where |
| 122 | * |
| 123 | * @arg bitrate is in bits per second (b/s) |
| 124 | * @arg complexity is a value from 1 to 10, where 1 is the lowest complexity and 10 is the highest |
| 125 | * @arg signal_type is either OPUS_AUTO (default), OPUS_SIGNAL_VOICE, or OPUS_SIGNAL_MUSIC |
| 126 | * |
| 127 | * See @ref opus_encoderctls and @ref opus_genericctls for a complete list of parameters that can be set or queried. Most parameters can be set or changed at any time during a stream. |
| 128 | * |
| 129 | * To encode a frame, opus_encode() or opus_encode_float() must be called with exactly one frame (2.5, 5, 10, 20, 40 or 60 ms) of audio data: |
| 130 | * @code |
| 131 | * len = opus_encode(enc, audio_frame, frame_size, packet, max_packet); |
| 132 | * @endcode |
| 133 | * |
| 134 | * where |
| 135 | * <ul> |
| 136 | * <li>audio_frame is the audio data in opus_int16 (or float for opus_encode_float())</li> |
| 137 | * <li>frame_size is the duration of the frame in samples (per channel)</li> |
| 138 | * <li>packet is the byte array to which the compressed data is written</li> |
| 139 | * <li>max_packet is the maximum number of bytes that can be written in the packet (4000 bytes is recommended). |
| 140 | * Do not use max_packet to control VBR target bitrate, instead use the #OPUS_SET_BITRATE CTL.</li> |
| 141 | * </ul> |
| 142 | * |
| 143 | * opus_encode() and opus_encode_float() return the number of bytes actually written to the packet. |
| 144 | * The return value <b>can be negative</b>, which indicates that an error has occurred. If the return value |
Felicia Lim | d03c373 | 2016-07-25 20:28:37 +0200 | [diff] [blame] | 145 | * is 2 bytes or less, then the packet does not need to be transmitted (DTX). |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 146 | * |
| 147 | * Once the encoder state if no longer needed, it can be destroyed with |
| 148 | * |
| 149 | * @code |
| 150 | * opus_encoder_destroy(enc); |
| 151 | * @endcode |
| 152 | * |
| 153 | * If the encoder was created with opus_encoder_init() rather than opus_encoder_create(), |
| 154 | * then no action is required aside from potentially freeing the memory that was manually |
| 155 | * allocated for it (calling free(enc) for the example above) |
| 156 | * |
| 157 | */ |
| 158 | |
| 159 | /** Opus encoder state. |
| 160 | * This contains the complete state of an Opus encoder. |
| 161 | * It is position independent and can be freely copied. |
| 162 | * @see opus_encoder_create,opus_encoder_init |
| 163 | */ |
| 164 | typedef struct OpusEncoder OpusEncoder; |
| 165 | |
| 166 | /** Gets the size of an <code>OpusEncoder</code> structure. |
| 167 | * @param[in] channels <tt>int</tt>: Number of channels. |
| 168 | * This must be 1 or 2. |
| 169 | * @returns The size in bytes. |
| 170 | */ |
| 171 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_encoder_get_size(int channels); |
| 172 | |
| 173 | /** |
| 174 | */ |
| 175 | |
| 176 | /** Allocates and initializes an encoder state. |
| 177 | * There are three coding modes: |
| 178 | * |
| 179 | * @ref OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voice |
| 180 | * signals. It enhances the input signal by high-pass filtering and |
| 181 | * emphasizing formants and harmonics. Optionally it includes in-band |
| 182 | * forward error correction to protect against packet loss. Use this |
| 183 | * mode for typical VoIP applications. Because of the enhancement, |
| 184 | * even at high bitrates the output may sound different from the input. |
| 185 | * |
| 186 | * @ref OPUS_APPLICATION_AUDIO gives best quality at a given bitrate for most |
| 187 | * non-voice signals like music. Use this mode for music and mixed |
| 188 | * (music/voice) content, broadcast, and applications requiring less |
| 189 | * than 15 ms of coding delay. |
| 190 | * |
| 191 | * @ref OPUS_APPLICATION_RESTRICTED_LOWDELAY configures low-delay mode that |
| 192 | * disables the speech-optimized mode in exchange for slightly reduced delay. |
| 193 | * This mode can only be set on an newly initialized or freshly reset encoder |
| 194 | * because it changes the codec delay. |
| 195 | * |
| 196 | * This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution). |
| 197 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz) |
| 198 | * This must be one of 8000, 12000, 16000, |
| 199 | * 24000, or 48000. |
| 200 | * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) in input signal |
| 201 | * @param [in] application <tt>int</tt>: Coding mode (@ref OPUS_APPLICATION_VOIP/@ref OPUS_APPLICATION_AUDIO/@ref OPUS_APPLICATION_RESTRICTED_LOWDELAY) |
| 202 | * @param [out] error <tt>int*</tt>: @ref opus_errorcodes |
| 203 | * @note Regardless of the sampling rate and number channels selected, the Opus encoder |
| 204 | * can switch to a lower audio bandwidth or number of channels if the bitrate |
| 205 | * selected is too low. This also means that it is safe to always use 48 kHz stereo input |
| 206 | * and let the encoder optimize the encoding. |
| 207 | */ |
| 208 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusEncoder *opus_encoder_create( |
| 209 | opus_int32 Fs, |
| 210 | int channels, |
| 211 | int application, |
| 212 | int *error |
| 213 | ); |
| 214 | |
| 215 | /** Initializes a previously allocated encoder state |
| 216 | * The memory pointed to by st must be at least the size returned by opus_encoder_get_size(). |
| 217 | * This is intended for applications which use their own allocator instead of malloc. |
| 218 | * @see opus_encoder_create(),opus_encoder_get_size() |
| 219 | * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL. |
| 220 | * @param [in] st <tt>OpusEncoder*</tt>: Encoder state |
| 221 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz) |
| 222 | * This must be one of 8000, 12000, 16000, |
| 223 | * 24000, or 48000. |
| 224 | * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) in input signal |
| 225 | * @param [in] application <tt>int</tt>: Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY) |
| 226 | * @retval #OPUS_OK Success or @ref opus_errorcodes |
| 227 | */ |
| 228 | OPUS_EXPORT int opus_encoder_init( |
| 229 | OpusEncoder *st, |
| 230 | opus_int32 Fs, |
| 231 | int channels, |
| 232 | int application |
| 233 | ) OPUS_ARG_NONNULL(1); |
| 234 | |
| 235 | /** Encodes an Opus frame. |
| 236 | * @param [in] st <tt>OpusEncoder*</tt>: Encoder state |
| 237 | * @param [in] pcm <tt>opus_int16*</tt>: Input signal (interleaved if 2 channels). length is frame_size*channels*sizeof(opus_int16) |
| 238 | * @param [in] frame_size <tt>int</tt>: Number of samples per channel in the |
| 239 | * input signal. |
| 240 | * This must be an Opus frame size for |
| 241 | * the encoder's sampling rate. |
| 242 | * For example, at 48 kHz the permitted |
| 243 | * values are 120, 240, 480, 960, 1920, |
| 244 | * and 2880. |
| 245 | * Passing in a duration of less than |
| 246 | * 10 ms (480 samples at 48 kHz) will |
| 247 | * prevent the encoder from using the LPC |
| 248 | * or hybrid modes. |
| 249 | * @param [out] data <tt>unsigned char*</tt>: Output payload. |
| 250 | * This must contain storage for at |
| 251 | * least \a max_data_bytes. |
| 252 | * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated |
| 253 | * memory for the output |
| 254 | * payload. This may be |
| 255 | * used to impose an upper limit on |
| 256 | * the instant bitrate, but should |
| 257 | * not be used as the only bitrate |
| 258 | * control. Use #OPUS_SET_BITRATE to |
| 259 | * control the bitrate. |
| 260 | * @returns The length of the encoded packet (in bytes) on success or a |
| 261 | * negative error code (see @ref opus_errorcodes) on failure. |
| 262 | */ |
| 263 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode( |
| 264 | OpusEncoder *st, |
| 265 | const opus_int16 *pcm, |
| 266 | int frame_size, |
| 267 | unsigned char *data, |
| 268 | opus_int32 max_data_bytes |
| 269 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4); |
| 270 | |
| 271 | /** Encodes an Opus frame from floating point input. |
| 272 | * @param [in] st <tt>OpusEncoder*</tt>: Encoder state |
| 273 | * @param [in] pcm <tt>float*</tt>: Input in float format (interleaved if 2 channels), with a normal range of +/-1.0. |
| 274 | * Samples with a range beyond +/-1.0 are supported but will |
| 275 | * be clipped by decoders using the integer API and should |
| 276 | * only be used if it is known that the far end supports |
| 277 | * extended dynamic range. |
| 278 | * length is frame_size*channels*sizeof(float) |
| 279 | * @param [in] frame_size <tt>int</tt>: Number of samples per channel in the |
| 280 | * input signal. |
| 281 | * This must be an Opus frame size for |
| 282 | * the encoder's sampling rate. |
| 283 | * For example, at 48 kHz the permitted |
| 284 | * values are 120, 240, 480, 960, 1920, |
| 285 | * and 2880. |
| 286 | * Passing in a duration of less than |
| 287 | * 10 ms (480 samples at 48 kHz) will |
| 288 | * prevent the encoder from using the LPC |
| 289 | * or hybrid modes. |
| 290 | * @param [out] data <tt>unsigned char*</tt>: Output payload. |
| 291 | * This must contain storage for at |
| 292 | * least \a max_data_bytes. |
| 293 | * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated |
| 294 | * memory for the output |
| 295 | * payload. This may be |
| 296 | * used to impose an upper limit on |
| 297 | * the instant bitrate, but should |
| 298 | * not be used as the only bitrate |
| 299 | * control. Use #OPUS_SET_BITRATE to |
| 300 | * control the bitrate. |
| 301 | * @returns The length of the encoded packet (in bytes) on success or a |
| 302 | * negative error code (see @ref opus_errorcodes) on failure. |
| 303 | */ |
| 304 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode_float( |
| 305 | OpusEncoder *st, |
| 306 | const float *pcm, |
| 307 | int frame_size, |
| 308 | unsigned char *data, |
| 309 | opus_int32 max_data_bytes |
| 310 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4); |
| 311 | |
| 312 | /** Frees an <code>OpusEncoder</code> allocated by opus_encoder_create(). |
| 313 | * @param[in] st <tt>OpusEncoder*</tt>: State to be freed. |
| 314 | */ |
| 315 | OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st); |
| 316 | |
| 317 | /** Perform a CTL function on an Opus encoder. |
| 318 | * |
| 319 | * Generally the request and subsequent arguments are generated |
| 320 | * by a convenience macro. |
| 321 | * @param st <tt>OpusEncoder*</tt>: Encoder state. |
| 322 | * @param request This and all remaining parameters should be replaced by one |
| 323 | * of the convenience macros in @ref opus_genericctls or |
| 324 | * @ref opus_encoderctls. |
| 325 | * @see opus_genericctls |
| 326 | * @see opus_encoderctls |
| 327 | */ |
| 328 | OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...) OPUS_ARG_NONNULL(1); |
| 329 | /**@}*/ |
| 330 | |
| 331 | /** @defgroup opus_decoder Opus Decoder |
| 332 | * @{ |
| 333 | * |
| 334 | * @brief This page describes the process and functions used to decode Opus. |
| 335 | * |
| 336 | * The decoding process also starts with creating a decoder |
| 337 | * state. This can be done with: |
| 338 | * @code |
| 339 | * int error; |
| 340 | * OpusDecoder *dec; |
| 341 | * dec = opus_decoder_create(Fs, channels, &error); |
| 342 | * @endcode |
| 343 | * where |
| 344 | * @li Fs is the sampling rate and must be 8000, 12000, 16000, 24000, or 48000 |
| 345 | * @li channels is the number of channels (1 or 2) |
| 346 | * @li error will hold the error code in case of failure (or #OPUS_OK on success) |
| 347 | * @li the return value is a newly created decoder state to be used for decoding |
| 348 | * |
| 349 | * While opus_decoder_create() allocates memory for the state, it's also possible |
| 350 | * to initialize pre-allocated memory: |
| 351 | * @code |
| 352 | * int size; |
| 353 | * int error; |
| 354 | * OpusDecoder *dec; |
| 355 | * size = opus_decoder_get_size(channels); |
| 356 | * dec = malloc(size); |
| 357 | * error = opus_decoder_init(dec, Fs, channels); |
| 358 | * @endcode |
| 359 | * where opus_decoder_get_size() returns the required size for the decoder state. Note that |
| 360 | * future versions of this code may change the size, so no assuptions should be made about it. |
| 361 | * |
| 362 | * The decoder state is always continuous in memory and only a shallow copy is sufficient |
| 363 | * to copy it (e.g. memcpy()) |
| 364 | * |
| 365 | * To decode a frame, opus_decode() or opus_decode_float() must be called with a packet of compressed audio data: |
| 366 | * @code |
| 367 | * frame_size = opus_decode(dec, packet, len, decoded, max_size, 0); |
| 368 | * @endcode |
| 369 | * where |
| 370 | * |
| 371 | * @li packet is the byte array containing the compressed data |
| 372 | * @li len is the exact number of bytes contained in the packet |
| 373 | * @li decoded is the decoded audio data in opus_int16 (or float for opus_decode_float()) |
| 374 | * @li max_size is the max duration of the frame in samples (per channel) that can fit into the decoded_frame array |
| 375 | * |
| 376 | * opus_decode() and opus_decode_float() return the number of samples (per channel) decoded from the packet. |
| 377 | * If that value is negative, then an error has occurred. This can occur if the packet is corrupted or if the audio |
| 378 | * buffer is too small to hold the decoded audio. |
| 379 | * |
| 380 | * Opus is a stateful codec with overlapping blocks and as a result Opus |
| 381 | * packets are not coded independently of each other. Packets must be |
| 382 | * passed into the decoder serially and in the correct order for a correct |
| 383 | * decode. Lost packets can be replaced with loss concealment by calling |
| 384 | * the decoder with a null pointer and zero length for the missing packet. |
| 385 | * |
| 386 | * A single codec state may only be accessed from a single thread at |
| 387 | * a time and any required locking must be performed by the caller. Separate |
| 388 | * streams must be decoded with separate decoder states and can be decoded |
| 389 | * in parallel unless the library was compiled with NONTHREADSAFE_PSEUDOSTACK |
| 390 | * defined. |
| 391 | * |
| 392 | */ |
| 393 | |
| 394 | /** Opus decoder state. |
| 395 | * This contains the complete state of an Opus decoder. |
| 396 | * It is position independent and can be freely copied. |
| 397 | * @see opus_decoder_create,opus_decoder_init |
| 398 | */ |
| 399 | typedef struct OpusDecoder OpusDecoder; |
| 400 | |
| 401 | /** Gets the size of an <code>OpusDecoder</code> structure. |
| 402 | * @param [in] channels <tt>int</tt>: Number of channels. |
| 403 | * This must be 1 or 2. |
| 404 | * @returns The size in bytes. |
| 405 | */ |
| 406 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_size(int channels); |
| 407 | |
| 408 | /** Allocates and initializes a decoder state. |
| 409 | * @param [in] Fs <tt>opus_int32</tt>: Sample rate to decode at (Hz). |
| 410 | * This must be one of 8000, 12000, 16000, |
| 411 | * 24000, or 48000. |
| 412 | * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) to decode |
| 413 | * @param [out] error <tt>int*</tt>: #OPUS_OK Success or @ref opus_errorcodes |
| 414 | * |
| 415 | * Internally Opus stores data at 48000 Hz, so that should be the default |
| 416 | * value for Fs. However, the decoder can efficiently decode to buffers |
| 417 | * at 8, 12, 16, and 24 kHz so if for some reason the caller cannot use |
| 418 | * data at the full sample rate, or knows the compressed data doesn't |
| 419 | * use the full frequency range, it can request decoding at a reduced |
| 420 | * rate. Likewise, the decoder is capable of filling in either mono or |
| 421 | * interleaved stereo pcm buffers, at the caller's request. |
| 422 | */ |
| 423 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusDecoder *opus_decoder_create( |
| 424 | opus_int32 Fs, |
| 425 | int channels, |
| 426 | int *error |
| 427 | ); |
| 428 | |
| 429 | /** Initializes a previously allocated decoder state. |
| 430 | * The state must be at least the size returned by opus_decoder_get_size(). |
| 431 | * This is intended for applications which use their own allocator instead of malloc. @see opus_decoder_create,opus_decoder_get_size |
| 432 | * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL. |
| 433 | * @param [in] st <tt>OpusDecoder*</tt>: Decoder state. |
| 434 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate to decode to (Hz). |
| 435 | * This must be one of 8000, 12000, 16000, |
| 436 | * 24000, or 48000. |
| 437 | * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) to decode |
| 438 | * @retval #OPUS_OK Success or @ref opus_errorcodes |
| 439 | */ |
| 440 | OPUS_EXPORT int opus_decoder_init( |
| 441 | OpusDecoder *st, |
| 442 | opus_int32 Fs, |
| 443 | int channels |
| 444 | ) OPUS_ARG_NONNULL(1); |
| 445 | |
| 446 | /** Decode an Opus packet. |
| 447 | * @param [in] st <tt>OpusDecoder*</tt>: Decoder state |
| 448 | * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss |
| 449 | * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload* |
| 450 | * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length |
| 451 | * is frame_size*channels*sizeof(opus_int16) |
| 452 | * @param [in] frame_size Number of samples per channel of available space in \a pcm. |
| 453 | * If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will |
| 454 | * not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1), |
| 455 | * then frame_size needs to be exactly the duration of audio that is missing, otherwise the |
| 456 | * decoder will not be in the optimal state to decode the next incoming packet. For the PLC and |
| 457 | * FEC cases, frame_size <b>must</b> be a multiple of 2.5 ms. |
| 458 | * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be |
| 459 | * decoded. If no such data is available, the frame is decoded as if it were lost. |
| 460 | * @returns Number of decoded samples or @ref opus_errorcodes |
| 461 | */ |
| 462 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode( |
| 463 | OpusDecoder *st, |
| 464 | const unsigned char *data, |
| 465 | opus_int32 len, |
| 466 | opus_int16 *pcm, |
| 467 | int frame_size, |
| 468 | int decode_fec |
| 469 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); |
| 470 | |
| 471 | /** Decode an Opus packet with floating point output. |
| 472 | * @param [in] st <tt>OpusDecoder*</tt>: Decoder state |
| 473 | * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss |
| 474 | * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload |
| 475 | * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length |
| 476 | * is frame_size*channels*sizeof(float) |
| 477 | * @param [in] frame_size Number of samples per channel of available space in \a pcm. |
| 478 | * If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will |
| 479 | * not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1), |
| 480 | * then frame_size needs to be exactly the duration of audio that is missing, otherwise the |
| 481 | * decoder will not be in the optimal state to decode the next incoming packet. For the PLC and |
| 482 | * FEC cases, frame_size <b>must</b> be a multiple of 2.5 ms. |
| 483 | * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be |
| 484 | * decoded. If no such data is available the frame is decoded as if it were lost. |
| 485 | * @returns Number of decoded samples or @ref opus_errorcodes |
| 486 | */ |
| 487 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode_float( |
| 488 | OpusDecoder *st, |
| 489 | const unsigned char *data, |
| 490 | opus_int32 len, |
| 491 | float *pcm, |
| 492 | int frame_size, |
| 493 | int decode_fec |
| 494 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); |
| 495 | |
| 496 | /** Perform a CTL function on an Opus decoder. |
| 497 | * |
| 498 | * Generally the request and subsequent arguments are generated |
| 499 | * by a convenience macro. |
| 500 | * @param st <tt>OpusDecoder*</tt>: Decoder state. |
| 501 | * @param request This and all remaining parameters should be replaced by one |
| 502 | * of the convenience macros in @ref opus_genericctls or |
| 503 | * @ref opus_decoderctls. |
| 504 | * @see opus_genericctls |
| 505 | * @see opus_decoderctls |
| 506 | */ |
| 507 | OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...) OPUS_ARG_NONNULL(1); |
| 508 | |
| 509 | /** Frees an <code>OpusDecoder</code> allocated by opus_decoder_create(). |
| 510 | * @param[in] st <tt>OpusDecoder*</tt>: State to be freed. |
| 511 | */ |
| 512 | OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st); |
| 513 | |
| 514 | /** Parse an opus packet into one or more frames. |
| 515 | * Opus_decode will perform this operation internally so most applications do |
| 516 | * not need to use this function. |
| 517 | * This function does not copy the frames, the returned pointers are pointers into |
| 518 | * the input packet. |
| 519 | * @param [in] data <tt>char*</tt>: Opus packet to be parsed |
| 520 | * @param [in] len <tt>opus_int32</tt>: size of data |
| 521 | * @param [out] out_toc <tt>char*</tt>: TOC pointer |
| 522 | * @param [out] frames <tt>char*[48]</tt> encapsulated frames |
| 523 | * @param [out] size <tt>opus_int16[48]</tt> sizes of the encapsulated frames |
| 524 | * @param [out] payload_offset <tt>int*</tt>: returns the position of the payload within the packet (in bytes) |
| 525 | * @returns number of frames |
| 526 | */ |
| 527 | OPUS_EXPORT int opus_packet_parse( |
| 528 | const unsigned char *data, |
| 529 | opus_int32 len, |
| 530 | unsigned char *out_toc, |
| 531 | const unsigned char *frames[48], |
| 532 | opus_int16 size[48], |
| 533 | int *payload_offset |
| 534 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); |
| 535 | |
| 536 | /** Gets the bandwidth of an Opus packet. |
| 537 | * @param [in] data <tt>char*</tt>: Opus packet |
| 538 | * @retval OPUS_BANDWIDTH_NARROWBAND Narrowband (4kHz bandpass) |
| 539 | * @retval OPUS_BANDWIDTH_MEDIUMBAND Mediumband (6kHz bandpass) |
| 540 | * @retval OPUS_BANDWIDTH_WIDEBAND Wideband (8kHz bandpass) |
| 541 | * @retval OPUS_BANDWIDTH_SUPERWIDEBAND Superwideband (12kHz bandpass) |
| 542 | * @retval OPUS_BANDWIDTH_FULLBAND Fullband (20kHz bandpass) |
| 543 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
| 544 | */ |
| 545 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_bandwidth(const unsigned char *data) OPUS_ARG_NONNULL(1); |
| 546 | |
| 547 | /** Gets the number of samples per frame from an Opus packet. |
| 548 | * @param [in] data <tt>char*</tt>: Opus packet. |
| 549 | * This must contain at least one byte of |
| 550 | * data. |
| 551 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz. |
| 552 | * This must be a multiple of 400, or |
| 553 | * inaccurate results will be returned. |
| 554 | * @returns Number of samples per frame. |
| 555 | */ |
| 556 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs) OPUS_ARG_NONNULL(1); |
| 557 | |
| 558 | /** Gets the number of channels from an Opus packet. |
| 559 | * @param [in] data <tt>char*</tt>: Opus packet |
| 560 | * @returns Number of channels |
| 561 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
| 562 | */ |
| 563 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_channels(const unsigned char *data) OPUS_ARG_NONNULL(1); |
| 564 | |
| 565 | /** Gets the number of frames in an Opus packet. |
| 566 | * @param [in] packet <tt>char*</tt>: Opus packet |
| 567 | * @param [in] len <tt>opus_int32</tt>: Length of packet |
| 568 | * @returns Number of frames |
| 569 | * @retval OPUS_BAD_ARG Insufficient data was passed to the function |
| 570 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
| 571 | */ |
| 572 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1); |
| 573 | |
| 574 | /** Gets the number of samples of an Opus packet. |
| 575 | * @param [in] packet <tt>char*</tt>: Opus packet |
| 576 | * @param [in] len <tt>opus_int32</tt>: Length of packet |
| 577 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz. |
| 578 | * This must be a multiple of 400, or |
| 579 | * inaccurate results will be returned. |
| 580 | * @returns Number of samples |
| 581 | * @retval OPUS_BAD_ARG Insufficient data was passed to the function |
| 582 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
| 583 | */ |
| 584 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_samples(const unsigned char packet[], opus_int32 len, opus_int32 Fs) OPUS_ARG_NONNULL(1); |
| 585 | |
| 586 | /** Gets the number of samples of an Opus packet. |
| 587 | * @param [in] dec <tt>OpusDecoder*</tt>: Decoder state |
| 588 | * @param [in] packet <tt>char*</tt>: Opus packet |
| 589 | * @param [in] len <tt>opus_int32</tt>: Length of packet |
| 590 | * @returns Number of samples |
| 591 | * @retval OPUS_BAD_ARG Insufficient data was passed to the function |
| 592 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
| 593 | */ |
| 594 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_nb_samples(const OpusDecoder *dec, const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2); |
| 595 | |
| 596 | /** Applies soft-clipping to bring a float signal within the [-1,1] range. If |
| 597 | * the signal is already in that range, nothing is done. If there are values |
| 598 | * outside of [-1,1], then the signal is clipped as smoothly as possible to |
| 599 | * both fit in the range and avoid creating excessive distortion in the |
| 600 | * process. |
| 601 | * @param [in,out] pcm <tt>float*</tt>: Input PCM and modified PCM |
| 602 | * @param [in] frame_size <tt>int</tt> Number of samples per channel to process |
| 603 | * @param [in] channels <tt>int</tt>: Number of channels |
| 604 | * @param [in,out] softclip_mem <tt>float*</tt>: State memory for the soft clipping process (one float per channel, initialized to zero) |
| 605 | */ |
| 606 | OPUS_EXPORT void opus_pcm_soft_clip(float *pcm, int frame_size, int channels, float *softclip_mem); |
| 607 | |
| 608 | |
| 609 | /**@}*/ |
| 610 | |
| 611 | /** @defgroup opus_repacketizer Repacketizer |
| 612 | * @{ |
| 613 | * |
| 614 | * The repacketizer can be used to merge multiple Opus packets into a single |
| 615 | * packet or alternatively to split Opus packets that have previously been |
| 616 | * merged. Splitting valid Opus packets is always guaranteed to succeed, |
| 617 | * whereas merging valid packets only succeeds if all frames have the same |
| 618 | * mode, bandwidth, and frame size, and when the total duration of the merged |
flim | c91ee5b | 2016-01-26 14:33:44 +0100 | [diff] [blame] | 619 | * packet is no more than 120 ms. The 120 ms limit comes from the |
| 620 | * specification and limits decoder memory requirements at a point where |
| 621 | * framing overhead becomes negligible. |
| 622 | * |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 623 | * The repacketizer currently only operates on elementary Opus |
| 624 | * streams. It will not manipualte multistream packets successfully, except in |
| 625 | * the degenerate case where they consist of data from a single stream. |
| 626 | * |
| 627 | * The repacketizing process starts with creating a repacketizer state, either |
| 628 | * by calling opus_repacketizer_create() or by allocating the memory yourself, |
| 629 | * e.g., |
| 630 | * @code |
| 631 | * OpusRepacketizer *rp; |
| 632 | * rp = (OpusRepacketizer*)malloc(opus_repacketizer_get_size()); |
| 633 | * if (rp != NULL) |
| 634 | * opus_repacketizer_init(rp); |
| 635 | * @endcode |
| 636 | * |
| 637 | * Then the application should submit packets with opus_repacketizer_cat(), |
| 638 | * extract new packets with opus_repacketizer_out() or |
| 639 | * opus_repacketizer_out_range(), and then reset the state for the next set of |
| 640 | * input packets via opus_repacketizer_init(). |
| 641 | * |
| 642 | * For example, to split a sequence of packets into individual frames: |
| 643 | * @code |
| 644 | * unsigned char *data; |
| 645 | * int len; |
| 646 | * while (get_next_packet(&data, &len)) |
| 647 | * { |
| 648 | * unsigned char out[1276]; |
| 649 | * opus_int32 out_len; |
| 650 | * int nb_frames; |
| 651 | * int err; |
| 652 | * int i; |
| 653 | * err = opus_repacketizer_cat(rp, data, len); |
| 654 | * if (err != OPUS_OK) |
| 655 | * { |
| 656 | * release_packet(data); |
| 657 | * return err; |
| 658 | * } |
| 659 | * nb_frames = opus_repacketizer_get_nb_frames(rp); |
| 660 | * for (i = 0; i < nb_frames; i++) |
| 661 | * { |
| 662 | * out_len = opus_repacketizer_out_range(rp, i, i+1, out, sizeof(out)); |
| 663 | * if (out_len < 0) |
| 664 | * { |
| 665 | * release_packet(data); |
| 666 | * return (int)out_len; |
| 667 | * } |
| 668 | * output_next_packet(out, out_len); |
| 669 | * } |
| 670 | * opus_repacketizer_init(rp); |
| 671 | * release_packet(data); |
| 672 | * } |
| 673 | * @endcode |
| 674 | * |
| 675 | * Alternatively, to combine a sequence of frames into packets that each |
| 676 | * contain up to <code>TARGET_DURATION_MS</code> milliseconds of data: |
| 677 | * @code |
| 678 | * // The maximum number of packets with duration TARGET_DURATION_MS occurs |
| 679 | * // when the frame size is 2.5 ms, for a total of (TARGET_DURATION_MS*2/5) |
| 680 | * // packets. |
| 681 | * unsigned char *data[(TARGET_DURATION_MS*2/5)+1]; |
| 682 | * opus_int32 len[(TARGET_DURATION_MS*2/5)+1]; |
| 683 | * int nb_packets; |
| 684 | * unsigned char out[1277*(TARGET_DURATION_MS*2/2)]; |
| 685 | * opus_int32 out_len; |
| 686 | * int prev_toc; |
| 687 | * nb_packets = 0; |
| 688 | * while (get_next_packet(data+nb_packets, len+nb_packets)) |
| 689 | * { |
| 690 | * int nb_frames; |
| 691 | * int err; |
| 692 | * nb_frames = opus_packet_get_nb_frames(data[nb_packets], len[nb_packets]); |
| 693 | * if (nb_frames < 1) |
| 694 | * { |
| 695 | * release_packets(data, nb_packets+1); |
| 696 | * return nb_frames; |
| 697 | * } |
| 698 | * nb_frames += opus_repacketizer_get_nb_frames(rp); |
| 699 | * // If adding the next packet would exceed our target, or it has an |
| 700 | * // incompatible TOC sequence, output the packets we already have before |
| 701 | * // submitting it. |
| 702 | * // N.B., The nb_packets > 0 check ensures we've submitted at least one |
| 703 | * // packet since the last call to opus_repacketizer_init(). Otherwise a |
| 704 | * // single packet longer than TARGET_DURATION_MS would cause us to try to |
| 705 | * // output an (invalid) empty packet. It also ensures that prev_toc has |
| 706 | * // been set to a valid value. Additionally, len[nb_packets] > 0 is |
| 707 | * // guaranteed by the call to opus_packet_get_nb_frames() above, so the |
| 708 | * // reference to data[nb_packets][0] should be valid. |
| 709 | * if (nb_packets > 0 && ( |
| 710 | * ((prev_toc & 0xFC) != (data[nb_packets][0] & 0xFC)) || |
| 711 | * opus_packet_get_samples_per_frame(data[nb_packets], 48000)*nb_frames > |
| 712 | * TARGET_DURATION_MS*48)) |
| 713 | * { |
| 714 | * out_len = opus_repacketizer_out(rp, out, sizeof(out)); |
| 715 | * if (out_len < 0) |
| 716 | * { |
| 717 | * release_packets(data, nb_packets+1); |
| 718 | * return (int)out_len; |
| 719 | * } |
| 720 | * output_next_packet(out, out_len); |
| 721 | * opus_repacketizer_init(rp); |
| 722 | * release_packets(data, nb_packets); |
| 723 | * data[0] = data[nb_packets]; |
| 724 | * len[0] = len[nb_packets]; |
| 725 | * nb_packets = 0; |
| 726 | * } |
| 727 | * err = opus_repacketizer_cat(rp, data[nb_packets], len[nb_packets]); |
| 728 | * if (err != OPUS_OK) |
| 729 | * { |
| 730 | * release_packets(data, nb_packets+1); |
| 731 | * return err; |
| 732 | * } |
| 733 | * prev_toc = data[nb_packets][0]; |
| 734 | * nb_packets++; |
| 735 | * } |
| 736 | * // Output the final, partial packet. |
| 737 | * if (nb_packets > 0) |
| 738 | * { |
| 739 | * out_len = opus_repacketizer_out(rp, out, sizeof(out)); |
| 740 | * release_packets(data, nb_packets); |
| 741 | * if (out_len < 0) |
| 742 | * return (int)out_len; |
| 743 | * output_next_packet(out, out_len); |
| 744 | * } |
| 745 | * @endcode |
| 746 | * |
| 747 | * An alternate way of merging packets is to simply call opus_repacketizer_cat() |
| 748 | * unconditionally until it fails. At that point, the merged packet can be |
| 749 | * obtained with opus_repacketizer_out() and the input packet for which |
| 750 | * opus_repacketizer_cat() needs to be re-added to a newly reinitialized |
| 751 | * repacketizer state. |
| 752 | */ |
| 753 | |
| 754 | typedef struct OpusRepacketizer OpusRepacketizer; |
| 755 | |
| 756 | /** Gets the size of an <code>OpusRepacketizer</code> structure. |
| 757 | * @returns The size in bytes. |
| 758 | */ |
| 759 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void); |
| 760 | |
| 761 | /** (Re)initializes a previously allocated repacketizer state. |
| 762 | * The state must be at least the size returned by opus_repacketizer_get_size(). |
| 763 | * This can be used for applications which use their own allocator instead of |
| 764 | * malloc(). |
| 765 | * It must also be called to reset the queue of packets waiting to be |
| 766 | * repacketized, which is necessary if the maximum packet duration of 120 ms |
| 767 | * is reached or if you wish to submit packets with a different Opus |
| 768 | * configuration (coding mode, audio bandwidth, frame size, or channel count). |
| 769 | * Failure to do so will prevent a new packet from being added with |
| 770 | * opus_repacketizer_cat(). |
| 771 | * @see opus_repacketizer_create |
| 772 | * @see opus_repacketizer_get_size |
| 773 | * @see opus_repacketizer_cat |
| 774 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to |
| 775 | * (re)initialize. |
| 776 | * @returns A pointer to the same repacketizer state that was passed in. |
| 777 | */ |
| 778 | OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1); |
| 779 | |
| 780 | /** Allocates memory and initializes the new repacketizer with |
| 781 | * opus_repacketizer_init(). |
| 782 | */ |
| 783 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusRepacketizer *opus_repacketizer_create(void); |
| 784 | |
| 785 | /** Frees an <code>OpusRepacketizer</code> allocated by |
| 786 | * opus_repacketizer_create(). |
| 787 | * @param[in] rp <tt>OpusRepacketizer*</tt>: State to be freed. |
| 788 | */ |
| 789 | OPUS_EXPORT void opus_repacketizer_destroy(OpusRepacketizer *rp); |
| 790 | |
| 791 | /** Add a packet to the current repacketizer state. |
| 792 | * This packet must match the configuration of any packets already submitted |
| 793 | * for repacketization since the last call to opus_repacketizer_init(). |
| 794 | * This means that it must have the same coding mode, audio bandwidth, frame |
| 795 | * size, and channel count. |
| 796 | * This can be checked in advance by examining the top 6 bits of the first |
| 797 | * byte of the packet, and ensuring they match the top 6 bits of the first |
| 798 | * byte of any previously submitted packet. |
| 799 | * The total duration of audio in the repacketizer state also must not exceed |
| 800 | * 120 ms, the maximum duration of a single packet, after adding this packet. |
| 801 | * |
| 802 | * The contents of the current repacketizer state can be extracted into new |
| 803 | * packets using opus_repacketizer_out() or opus_repacketizer_out_range(). |
| 804 | * |
| 805 | * In order to add a packet with a different configuration or to add more |
| 806 | * audio beyond 120 ms, you must clear the repacketizer state by calling |
| 807 | * opus_repacketizer_init(). |
| 808 | * If a packet is too large to add to the current repacketizer state, no part |
| 809 | * of it is added, even if it contains multiple frames, some of which might |
| 810 | * fit. |
| 811 | * If you wish to be able to add parts of such packets, you should first use |
| 812 | * another repacketizer to split the packet into pieces and add them |
| 813 | * individually. |
| 814 | * @see opus_repacketizer_out_range |
| 815 | * @see opus_repacketizer_out |
| 816 | * @see opus_repacketizer_init |
| 817 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to which to |
| 818 | * add the packet. |
| 819 | * @param[in] data <tt>const unsigned char*</tt>: The packet data. |
| 820 | * The application must ensure |
| 821 | * this pointer remains valid |
| 822 | * until the next call to |
| 823 | * opus_repacketizer_init() or |
| 824 | * opus_repacketizer_destroy(). |
| 825 | * @param len <tt>opus_int32</tt>: The number of bytes in the packet data. |
| 826 | * @returns An error code indicating whether or not the operation succeeded. |
| 827 | * @retval #OPUS_OK The packet's contents have been added to the repacketizer |
| 828 | * state. |
| 829 | * @retval #OPUS_INVALID_PACKET The packet did not have a valid TOC sequence, |
| 830 | * the packet's TOC sequence was not compatible |
| 831 | * with previously submitted packets (because |
| 832 | * the coding mode, audio bandwidth, frame size, |
| 833 | * or channel count did not match), or adding |
| 834 | * this packet would increase the total amount of |
| 835 | * audio stored in the repacketizer state to more |
| 836 | * than 120 ms. |
| 837 | */ |
| 838 | OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2); |
| 839 | |
| 840 | |
| 841 | /** Construct a new packet from data previously submitted to the repacketizer |
| 842 | * state via opus_repacketizer_cat(). |
| 843 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to |
| 844 | * construct the new packet. |
| 845 | * @param begin <tt>int</tt>: The index of the first frame in the current |
| 846 | * repacketizer state to include in the output. |
| 847 | * @param end <tt>int</tt>: One past the index of the last frame in the |
| 848 | * current repacketizer state to include in the |
| 849 | * output. |
| 850 | * @param[out] data <tt>const unsigned char*</tt>: The buffer in which to |
| 851 | * store the output packet. |
| 852 | * @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in |
| 853 | * the output buffer. In order to guarantee |
| 854 | * success, this should be at least |
| 855 | * <code>1276</code> for a single frame, |
| 856 | * or for multiple frames, |
| 857 | * <code>1277*(end-begin)</code>. |
| 858 | * However, <code>1*(end-begin)</code> plus |
| 859 | * the size of all packet data submitted to |
| 860 | * the repacketizer since the last call to |
| 861 | * opus_repacketizer_init() or |
| 862 | * opus_repacketizer_create() is also |
| 863 | * sufficient, and possibly much smaller. |
| 864 | * @returns The total size of the output packet on success, or an error code |
| 865 | * on failure. |
| 866 | * @retval #OPUS_BAD_ARG <code>[begin,end)</code> was an invalid range of |
| 867 | * frames (begin < 0, begin >= end, or end > |
| 868 | * opus_repacketizer_get_nb_frames()). |
| 869 | * @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the |
| 870 | * complete output packet. |
| 871 | */ |
| 872 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out_range(OpusRepacketizer *rp, int begin, int end, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); |
| 873 | |
| 874 | /** Return the total number of frames contained in packet data submitted to |
| 875 | * the repacketizer state so far via opus_repacketizer_cat() since the last |
| 876 | * call to opus_repacketizer_init() or opus_repacketizer_create(). |
| 877 | * This defines the valid range of packets that can be extracted with |
| 878 | * opus_repacketizer_out_range() or opus_repacketizer_out(). |
| 879 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state containing the |
| 880 | * frames. |
| 881 | * @returns The total number of frames contained in the packet data submitted |
| 882 | * to the repacketizer state. |
| 883 | */ |
| 884 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1); |
| 885 | |
| 886 | /** Construct a new packet from data previously submitted to the repacketizer |
| 887 | * state via opus_repacketizer_cat(). |
| 888 | * This is a convenience routine that returns all the data submitted so far |
| 889 | * in a single packet. |
| 890 | * It is equivalent to calling |
| 891 | * @code |
| 892 | * opus_repacketizer_out_range(rp, 0, opus_repacketizer_get_nb_frames(rp), |
| 893 | * data, maxlen) |
| 894 | * @endcode |
| 895 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to |
| 896 | * construct the new packet. |
| 897 | * @param[out] data <tt>const unsigned char*</tt>: The buffer in which to |
| 898 | * store the output packet. |
| 899 | * @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in |
| 900 | * the output buffer. In order to guarantee |
| 901 | * success, this should be at least |
| 902 | * <code>1277*opus_repacketizer_get_nb_frames(rp)</code>. |
| 903 | * However, |
| 904 | * <code>1*opus_repacketizer_get_nb_frames(rp)</code> |
| 905 | * plus the size of all packet data |
| 906 | * submitted to the repacketizer since the |
| 907 | * last call to opus_repacketizer_init() or |
| 908 | * opus_repacketizer_create() is also |
| 909 | * sufficient, and possibly much smaller. |
| 910 | * @returns The total size of the output packet on success, or an error code |
| 911 | * on failure. |
| 912 | * @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the |
| 913 | * complete output packet. |
| 914 | */ |
| 915 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1); |
| 916 | |
| 917 | /** Pads a given Opus packet to a larger size (possibly changing the TOC sequence). |
| 918 | * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the |
| 919 | * packet to pad. |
| 920 | * @param len <tt>opus_int32</tt>: The size of the packet. |
| 921 | * This must be at least 1. |
| 922 | * @param new_len <tt>opus_int32</tt>: The desired size of the packet after padding. |
| 923 | * This must be at least as large as len. |
| 924 | * @returns an error code |
| 925 | * @retval #OPUS_OK \a on success. |
| 926 | * @retval #OPUS_BAD_ARG \a len was less than 1 or new_len was less than len. |
| 927 | * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. |
| 928 | */ |
| 929 | OPUS_EXPORT int opus_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len); |
| 930 | |
| 931 | /** Remove all padding from a given Opus packet and rewrite the TOC sequence to |
| 932 | * minimize space usage. |
| 933 | * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the |
| 934 | * packet to strip. |
| 935 | * @param len <tt>opus_int32</tt>: The size of the packet. |
| 936 | * This must be at least 1. |
| 937 | * @returns The new size of the output packet on success, or an error code |
| 938 | * on failure. |
| 939 | * @retval #OPUS_BAD_ARG \a len was less than 1. |
| 940 | * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. |
| 941 | */ |
| 942 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_packet_unpad(unsigned char *data, opus_int32 len); |
| 943 | |
| 944 | /** Pads a given Opus multi-stream packet to a larger size (possibly changing the TOC sequence). |
| 945 | * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the |
| 946 | * packet to pad. |
| 947 | * @param len <tt>opus_int32</tt>: The size of the packet. |
| 948 | * This must be at least 1. |
| 949 | * @param new_len <tt>opus_int32</tt>: The desired size of the packet after padding. |
| 950 | * This must be at least 1. |
| 951 | * @param nb_streams <tt>opus_int32</tt>: The number of streams (not channels) in the packet. |
| 952 | * This must be at least as large as len. |
| 953 | * @returns an error code |
| 954 | * @retval #OPUS_OK \a on success. |
| 955 | * @retval #OPUS_BAD_ARG \a len was less than 1. |
| 956 | * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. |
| 957 | */ |
| 958 | OPUS_EXPORT int opus_multistream_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len, int nb_streams); |
| 959 | |
| 960 | /** Remove all padding from a given Opus multi-stream packet and rewrite the TOC sequence to |
| 961 | * minimize space usage. |
| 962 | * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the |
| 963 | * packet to strip. |
| 964 | * @param len <tt>opus_int32</tt>: The size of the packet. |
| 965 | * This must be at least 1. |
| 966 | * @param nb_streams <tt>opus_int32</tt>: The number of streams (not channels) in the packet. |
| 967 | * This must be at least 1. |
| 968 | * @returns The new size of the output packet on success, or an error code |
| 969 | * on failure. |
| 970 | * @retval #OPUS_BAD_ARG \a len was less than 1 or new_len was less than len. |
| 971 | * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. |
| 972 | */ |
| 973 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_packet_unpad(unsigned char *data, opus_int32 len, int nb_streams); |
| 974 | |
| 975 | /**@}*/ |
| 976 | |
| 977 | #ifdef __cplusplus |
| 978 | } |
| 979 | #endif |
| 980 | |
| 981 | #endif /* OPUS_H */ |