opus.h (59505B)
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 assumptions 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 145 * is 2 bytes or less, then the packet does not need to be transmitted (DTX). 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 * @note Since this function does not take the application as input, it will overestimate 171 * the size required for OPUS_APPLICATION_RESTRICTED_SILK and OPUS_APPLICATION_RESTRICTED_CELT. 172 * That is generally not a problem, except when trying to know the size to use for a copy. 173 */ 174 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_encoder_get_size(int channels); 175 176 /** 177 */ 178 179 /** Allocates and initializes an encoder state. 180 * There are three coding modes: 181 * 182 * @ref OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voice 183 * signals. It enhances the input signal by high-pass filtering and 184 * emphasizing formants and harmonics. Optionally it includes in-band 185 * forward error correction to protect against packet loss. Use this 186 * mode for typical VoIP applications. Because of the enhancement, 187 * even at high bitrates the output may sound different from the input. 188 * 189 * @ref OPUS_APPLICATION_AUDIO gives best quality at a given bitrate for most 190 * non-voice signals like music. Use this mode for music and mixed 191 * (music/voice) content, broadcast, and applications requiring less 192 * than 15 ms of coding delay. 193 * 194 * @ref OPUS_APPLICATION_RESTRICTED_LOWDELAY configures low-delay mode that 195 * disables the speech-optimized mode in exchange for slightly reduced delay. 196 * This mode can only be set on an newly initialized or freshly reset encoder 197 * because it changes the codec delay. 198 * 199 * This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution). 200 * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz) 201 * This must be one of 8000, 12000, 16000, 202 * 24000, or 48000. 203 * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) in input signal 204 * @param [in] application <tt>int</tt>: Coding mode (one of @ref OPUS_APPLICATION_VOIP, @ref OPUS_APPLICATION_AUDIO, or @ref OPUS_APPLICATION_RESTRICTED_LOWDELAY) 205 * @param [out] error <tt>int*</tt>: @ref opus_errorcodes 206 * @note Regardless of the sampling rate and number channels selected, the Opus encoder 207 * can switch to a lower audio bandwidth or number of channels if the bitrate 208 * selected is too low. This also means that it is safe to always use 48 kHz stereo input 209 * and let the encoder optimize the encoding. 210 */ 211 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusEncoder *opus_encoder_create( 212 opus_int32 Fs, 213 int channels, 214 int application, 215 int *error 216 ); 217 218 /** Initializes a previously allocated encoder state 219 * The memory pointed to by st must be at least the size returned by opus_encoder_get_size(). 220 * This is intended for applications which use their own allocator instead of malloc. 221 * @see opus_encoder_create(),opus_encoder_get_size() 222 * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL. 223 * @param [in] st <tt>OpusEncoder*</tt>: Encoder state 224 * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz) 225 * This must be one of 8000, 12000, 16000, 226 * 24000, or 48000. 227 * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) in input signal 228 * @param [in] application <tt>int</tt>: Coding mode (one of OPUS_APPLICATION_VOIP, OPUS_APPLICATION_AUDIO, or OPUS_APPLICATION_RESTRICTED_LOWDELAY) 229 * @retval #OPUS_OK Success or @ref opus_errorcodes 230 */ 231 OPUS_EXPORT int opus_encoder_init( 232 OpusEncoder *st, 233 opus_int32 Fs, 234 int channels, 235 int application 236 ) OPUS_ARG_NONNULL(1); 237 238 /** Encodes an Opus frame. 239 * @param [in] st <tt>OpusEncoder*</tt>: Encoder state 240 * @param [in] pcm <tt>opus_int16*</tt>: Input signal (interleaved if 2 channels). length is frame_size*channels*sizeof(opus_int16) 241 * @param [in] frame_size <tt>int</tt>: Number of samples per channel in the 242 * input signal. 243 * This must be an Opus frame size for 244 * the encoder's sampling rate. 245 * For example, at 48 kHz the permitted 246 * values are 120, 240, 480, 960, 1920, 247 * and 2880. 248 * Passing in a duration of less than 249 * 10 ms (480 samples at 48 kHz) will 250 * prevent the encoder from using the LPC 251 * or hybrid modes. 252 * @param [out] data <tt>unsigned char*</tt>: Output payload. 253 * This must contain storage for at 254 * least \a max_data_bytes. 255 * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated 256 * memory for the output 257 * payload. This may be 258 * used to impose an upper limit on 259 * the instant bitrate, but should 260 * not be used as the only bitrate 261 * control. Use #OPUS_SET_BITRATE to 262 * control the bitrate. 263 * @returns The length of the encoded packet (in bytes) on success or a 264 * negative error code (see @ref opus_errorcodes) on failure. 265 */ 266 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode( 267 OpusEncoder *st, 268 const opus_int16 *pcm, 269 int frame_size, 270 unsigned char *data, 271 opus_int32 max_data_bytes 272 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4); 273 274 /** Encodes an Opus frame. 275 * @param [in] st <tt>OpusEncoder*</tt>: Encoder state 276 * @param [in] pcm <tt>opus_int32*</tt>: Input signal (interleaved if 2 channels) representing (or slightly exceeding) 24-bit values. length is frame_size*channels*sizeof(opus_int32) 277 * @param [in] frame_size <tt>int</tt>: Number of samples per channel in the 278 * input signal. 279 * This must be an Opus frame size for 280 * the encoder's sampling rate. 281 * For example, at 48 kHz the permitted 282 * values are 120, 240, 480, 960, 1920, 283 * and 2880. 284 * Passing in a duration of less than 285 * 10 ms (480 samples at 48 kHz) will 286 * prevent the encoder from using the LPC 287 * or hybrid modes. 288 * @param [out] data <tt>unsigned char*</tt>: Output payload. 289 * This must contain storage for at 290 * least \a max_data_bytes. 291 * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated 292 * memory for the output 293 * payload. This may be 294 * used to impose an upper limit on 295 * the instant bitrate, but should 296 * not be used as the only bitrate 297 * control. Use #OPUS_SET_BITRATE to 298 * control the bitrate. 299 * @returns The length of the encoded packet (in bytes) on success or a 300 * negative error code (see @ref opus_errorcodes) on failure. 301 */ 302 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode24( 303 OpusEncoder *st, 304 const opus_int32 *pcm, 305 int frame_size, 306 unsigned char *data, 307 opus_int32 max_data_bytes 308 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4); 309 310 /** Encodes an Opus frame from floating point input. 311 * @param [in] st <tt>OpusEncoder*</tt>: Encoder state 312 * @param [in] pcm <tt>float*</tt>: Input in float format (interleaved if 2 channels), with a normal range of +/-1.0. 313 * Samples with a range beyond +/-1.0 are supported but will 314 * be clipped by decoders using the integer API and should 315 * only be used if it is known that the far end supports 316 * extended dynamic range. 317 * length is frame_size*channels*sizeof(float) 318 * @param [in] frame_size <tt>int</tt>: Number of samples per channel in the 319 * input signal. 320 * This must be an Opus frame size for 321 * the encoder's sampling rate. 322 * For example, at 48 kHz the permitted 323 * values are 120, 240, 480, 960, 1920, 324 * and 2880. 325 * Passing in a duration of less than 326 * 10 ms (480 samples at 48 kHz) will 327 * prevent the encoder from using the LPC 328 * or hybrid modes. 329 * @param [out] data <tt>unsigned char*</tt>: Output payload. 330 * This must contain storage for at 331 * least \a max_data_bytes. 332 * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated 333 * memory for the output 334 * payload. This may be 335 * used to impose an upper limit on 336 * the instant bitrate, but should 337 * not be used as the only bitrate 338 * control. Use #OPUS_SET_BITRATE to 339 * control the bitrate. 340 * @returns The length of the encoded packet (in bytes) on success or a 341 * negative error code (see @ref opus_errorcodes) on failure. 342 */ 343 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode_float( 344 OpusEncoder *st, 345 const float *pcm, 346 int frame_size, 347 unsigned char *data, 348 opus_int32 max_data_bytes 349 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4); 350 351 /** Frees an <code>OpusEncoder</code> allocated by opus_encoder_create(). 352 * @param[in] st <tt>OpusEncoder*</tt>: State to be freed. 353 */ 354 OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st); 355 356 /** Perform a CTL function on an Opus encoder. 357 * 358 * Generally the request and subsequent arguments are generated 359 * by a convenience macro. 360 * @param st <tt>OpusEncoder*</tt>: Encoder state. 361 * @param request This and all remaining parameters should be replaced by one 362 * of the convenience macros in @ref opus_genericctls or 363 * @ref opus_encoderctls. 364 * @see opus_genericctls 365 * @see opus_encoderctls 366 */ 367 OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...) OPUS_ARG_NONNULL(1); 368 /**@}*/ 369 370 /** @defgroup opus_decoder Opus Decoder 371 * @{ 372 * 373 * @brief This page describes the process and functions used to decode Opus. 374 * 375 * The decoding process also starts with creating a decoder 376 * state. This can be done with: 377 * @code 378 * int error; 379 * OpusDecoder *dec; 380 * dec = opus_decoder_create(Fs, channels, &error); 381 * @endcode 382 * where 383 * @li Fs is the sampling rate and must be 8000, 12000, 16000, 24000, or 48000 384 * @li channels is the number of channels (1 or 2) 385 * @li error will hold the error code in case of failure (or #OPUS_OK on success) 386 * @li the return value is a newly created decoder state to be used for decoding 387 * 388 * While opus_decoder_create() allocates memory for the state, it's also possible 389 * to initialize pre-allocated memory: 390 * @code 391 * int size; 392 * int error; 393 * OpusDecoder *dec; 394 * size = opus_decoder_get_size(channels); 395 * dec = malloc(size); 396 * error = opus_decoder_init(dec, Fs, channels); 397 * @endcode 398 * where opus_decoder_get_size() returns the required size for the decoder state. Note that 399 * future versions of this code may change the size, so no assumptions should be made about it. 400 * 401 * The decoder state is always continuous in memory and only a shallow copy is sufficient 402 * to copy it (e.g. memcpy()) 403 * 404 * To decode a frame, opus_decode() or opus_decode_float() must be called with a packet of compressed audio data: 405 * @code 406 * frame_size = opus_decode(dec, packet, len, decoded, max_size, 0); 407 * @endcode 408 * where 409 * 410 * @li packet is the byte array containing the compressed data 411 * @li len is the exact number of bytes contained in the packet 412 * @li decoded is the decoded audio data in opus_int16 (or float for opus_decode_float()) 413 * @li max_size is the max duration of the frame in samples (per channel) that can fit into the decoded_frame array 414 * 415 * opus_decode() and opus_decode_float() return the number of samples (per channel) decoded from the packet. 416 * If that value is negative, then an error has occurred. This can occur if the packet is corrupted or if the audio 417 * buffer is too small to hold the decoded audio. 418 * 419 * Opus is a stateful codec with overlapping blocks and as a result Opus 420 * packets are not coded independently of each other. Packets must be 421 * passed into the decoder serially and in the correct order for a correct 422 * decode. Lost packets can be replaced with loss concealment by calling 423 * the decoder with a null pointer and zero length for the missing packet. 424 * 425 * A single codec state may only be accessed from a single thread at 426 * a time and any required locking must be performed by the caller. Separate 427 * streams must be decoded with separate decoder states and can be decoded 428 * in parallel unless the library was compiled with NONTHREADSAFE_PSEUDOSTACK 429 * defined. 430 * 431 */ 432 433 /** Opus decoder state. 434 * This contains the complete state of an Opus decoder. 435 * It is position independent and can be freely copied. 436 * @see opus_decoder_create,opus_decoder_init 437 */ 438 typedef struct OpusDecoder OpusDecoder; 439 440 /** Opus DRED decoder. 441 * This contains the complete state of an Opus DRED decoder. 442 * It is position independent and can be freely copied. 443 * @see opus_dred_decoder_create,opus_dred_decoder_init 444 */ 445 typedef struct OpusDREDDecoder OpusDREDDecoder; 446 447 448 /** Opus DRED state. 449 * This contains the complete state of an Opus DRED packet. 450 * It is position independent and can be freely copied. 451 * @see opus_dred_create,opus_dred_init 452 */ 453 typedef struct OpusDRED OpusDRED; 454 455 /** Gets the size of an <code>OpusDecoder</code> structure. 456 * @param [in] channels <tt>int</tt>: Number of channels. 457 * This must be 1 or 2. 458 * @returns The size in bytes. 459 */ 460 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_size(int channels); 461 462 /** Allocates and initializes a decoder state. 463 * @param [in] Fs <tt>opus_int32</tt>: Sample rate to decode at (Hz). 464 * This must be one of 8000, 12000, 16000, 465 * 24000, or 48000. 466 * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) to decode 467 * @param [out] error <tt>int*</tt>: #OPUS_OK Success or @ref opus_errorcodes 468 * 469 * Internally Opus stores data at 48000 Hz, so that should be the default 470 * value for Fs. However, the decoder can efficiently decode to buffers 471 * at 8, 12, 16, and 24 kHz so if for some reason the caller cannot use 472 * data at the full sample rate, or knows the compressed data doesn't 473 * use the full frequency range, it can request decoding at a reduced 474 * rate. Likewise, the decoder is capable of filling in either mono or 475 * interleaved stereo pcm buffers, at the caller's request. 476 */ 477 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusDecoder *opus_decoder_create( 478 opus_int32 Fs, 479 int channels, 480 int *error 481 ); 482 483 /** Initializes a previously allocated decoder state. 484 * The state must be at least the size returned by opus_decoder_get_size(). 485 * This is intended for applications which use their own allocator instead of malloc. @see opus_decoder_create,opus_decoder_get_size 486 * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL. 487 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state. 488 * @param [in] Fs <tt>opus_int32</tt>: Sampling rate to decode to (Hz). 489 * This must be one of 8000, 12000, 16000, 490 * 24000, or 48000. 491 * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) to decode 492 * @retval #OPUS_OK Success or @ref opus_errorcodes 493 */ 494 OPUS_EXPORT int opus_decoder_init( 495 OpusDecoder *st, 496 opus_int32 Fs, 497 int channels 498 ) OPUS_ARG_NONNULL(1); 499 500 /** Decode an Opus packet. 501 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state 502 * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss 503 * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload* 504 * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length 505 * is frame_size*channels*sizeof(opus_int16) 506 * @param [in] frame_size Number of samples per channel of available space in \a pcm. 507 * If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will 508 * not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1), 509 * then frame_size needs to be exactly the duration of audio that is missing, otherwise the 510 * decoder will not be in the optimal state to decode the next incoming packet. For the PLC and 511 * FEC cases, frame_size <b>must</b> be a multiple of 2.5 ms. 512 * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be 513 * decoded. If no such data is available, the frame is decoded as if it were lost. 514 * @returns Number of decoded samples per channel or @ref opus_errorcodes 515 */ 516 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode( 517 OpusDecoder *st, 518 const unsigned char *data, 519 opus_int32 len, 520 opus_int16 *pcm, 521 int frame_size, 522 int decode_fec 523 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); 524 525 /** Decode an Opus packet. 526 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state 527 * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss 528 * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload* 529 * @param [out] pcm <tt>opus_int32*</tt>: Output signal (interleaved if 2 channels) representing (or slightly exceeding) 24-bit values. length 530 * is frame_size*channels*sizeof(opus_int32) 531 * @param [in] frame_size Number of samples per channel of available space in \a pcm. 532 * If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will 533 * not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1), 534 * then frame_size needs to be exactly the duration of audio that is missing, otherwise the 535 * decoder will not be in the optimal state to decode the next incoming packet. For the PLC and 536 * FEC cases, frame_size <b>must</b> be a multiple of 2.5 ms. 537 * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be 538 * decoded. If no such data is available, the frame is decoded as if it were lost. 539 * @returns Number of decoded samples or @ref opus_errorcodes 540 */ 541 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode24( 542 OpusDecoder *st, 543 const unsigned char *data, 544 opus_int32 len, 545 opus_int32 *pcm, 546 int frame_size, 547 int decode_fec 548 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); 549 550 /** Decode an Opus packet with floating point output. 551 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state 552 * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss 553 * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload 554 * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length 555 * is frame_size*channels*sizeof(float) 556 * @param [in] frame_size Number of samples per channel of available space in \a pcm. 557 * If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will 558 * not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1), 559 * then frame_size needs to be exactly the duration of audio that is missing, otherwise the 560 * decoder will not be in the optimal state to decode the next incoming packet. For the PLC and 561 * FEC cases, frame_size <b>must</b> be a multiple of 2.5 ms. 562 * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be 563 * decoded. If no such data is available the frame is decoded as if it were lost. 564 * @returns Number of decoded samples per channel or @ref opus_errorcodes 565 */ 566 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode_float( 567 OpusDecoder *st, 568 const unsigned char *data, 569 opus_int32 len, 570 float *pcm, 571 int frame_size, 572 int decode_fec 573 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); 574 575 /** Perform a CTL function on an Opus decoder. 576 * 577 * Generally the request and subsequent arguments are generated 578 * by a convenience macro. 579 * @param st <tt>OpusDecoder*</tt>: Decoder state. 580 * @param request This and all remaining parameters should be replaced by one 581 * of the convenience macros in @ref opus_genericctls or 582 * @ref opus_decoderctls. 583 * @see opus_genericctls 584 * @see opus_decoderctls 585 */ 586 OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...) OPUS_ARG_NONNULL(1); 587 588 /** Frees an <code>OpusDecoder</code> allocated by opus_decoder_create(). 589 * @param[in] st <tt>OpusDecoder*</tt>: State to be freed. 590 */ 591 OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st); 592 593 /** Gets the size of an <code>OpusDREDDecoder</code> structure. 594 * @returns The size in bytes. 595 */ 596 OPUS_EXPORT int opus_dred_decoder_get_size(void); 597 598 /** Allocates and initializes an OpusDREDDecoder state. 599 * @param [out] error <tt>int*</tt>: #OPUS_OK Success or @ref opus_errorcodes 600 */ 601 OPUS_EXPORT OpusDREDDecoder *opus_dred_decoder_create(int *error); 602 603 /** Initializes an <code>OpusDREDDecoder</code> state. 604 * @param[in] dec <tt>OpusDREDDecoder*</tt>: State to be initialized. 605 */ 606 OPUS_EXPORT int opus_dred_decoder_init(OpusDREDDecoder *dec); 607 608 /** Frees an <code>OpusDREDDecoder</code> allocated by opus_dred_decoder_create(). 609 * @param[in] dec <tt>OpusDREDDecoder*</tt>: State to be freed. 610 */ 611 OPUS_EXPORT void opus_dred_decoder_destroy(OpusDREDDecoder *dec); 612 613 /** Perform a CTL function on an Opus DRED decoder. 614 * 615 * Generally the request and subsequent arguments are generated 616 * by a convenience macro. 617 * @param dred_dec <tt>OpusDREDDecoder*</tt>: DRED Decoder state. 618 * @param request This and all remaining parameters should be replaced by one 619 * of the convenience macros in @ref opus_genericctls or 620 * @ref opus_decoderctls. 621 * @see opus_genericctls 622 * @see opus_decoderctls 623 */ 624 OPUS_EXPORT int opus_dred_decoder_ctl(OpusDREDDecoder *dred_dec, int request, ...); 625 626 /** Gets the size of an <code>OpusDRED</code> structure. 627 * @returns The size in bytes. 628 */ 629 OPUS_EXPORT int opus_dred_get_size(void); 630 631 /** Allocates and initializes a DRED state. 632 * @param [out] error <tt>int*</tt>: #OPUS_OK Success or @ref opus_errorcodes 633 */ 634 OPUS_EXPORT OpusDRED *opus_dred_alloc(int *error); 635 636 /** Frees an <code>OpusDRED</code> allocated by opus_dred_create(). 637 * @param[in] dec <tt>OpusDRED*</tt>: State to be freed. 638 */ 639 OPUS_EXPORT void opus_dred_free(OpusDRED *dec); 640 641 /** Decode an Opus DRED packet. 642 * @param [in] dred_dec <tt>OpusDRED*</tt>: DRED Decoder state 643 * @param [in] dred <tt>OpusDRED*</tt>: DRED state 644 * @param [in] data <tt>char*</tt>: Input payload 645 * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload 646 * @param [in] max_dred_samples <tt>opus_int32</tt>: Maximum number of DRED samples that may be needed (if available in the packet). 647 * @param [in] sampling_rate <tt>opus_int32</tt>: Sampling rate used for max_dred_samples argument. Needs not match the actual sampling rate of the decoder. 648 * @param [out] dred_end <tt>opus_int32*</tt>: Number of non-encoded (silence) samples between the DRED timestamp and the last DRED sample. 649 * @param [in] defer_processing <tt>int</tt>: Flag (0 or 1). If set to one, the CPU-intensive part of the DRED decoding is deferred until opus_dred_process() is called. 650 * @returns Offset (positive) of the first decoded DRED samples, zero if no DRED is present, or @ref opus_errorcodes 651 */ 652 OPUS_EXPORT int opus_dred_parse(OpusDREDDecoder *dred_dec, OpusDRED *dred, const unsigned char *data, opus_int32 len, opus_int32 max_dred_samples, opus_int32 sampling_rate, int *dred_end, int defer_processing) OPUS_ARG_NONNULL(1); 653 654 /** Finish decoding an Opus DRED packet. The function only needs to be called if opus_dred_parse() was called with defer_processing=1. 655 * The source and destination will often be the same DRED state. 656 * @param [in] dred_dec <tt>OpusDRED*</tt>: DRED Decoder state 657 * @param [in] src <tt>OpusDRED*</tt>: Source DRED state to start the processing from. 658 * @param [out] dst <tt>OpusDRED*</tt>: Destination DRED state to store the updated state after processing. 659 * @returns @ref opus_errorcodes 660 */ 661 OPUS_EXPORT int opus_dred_process(OpusDREDDecoder *dred_dec, const OpusDRED *src, OpusDRED *dst); 662 663 /** Decode audio from an Opus DRED packet with 16-bit output. 664 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state 665 * @param [in] dred <tt>OpusDRED*</tt>: DRED state 666 * @param [in] dred_offset <tt>opus_int32</tt>: position of the redundancy to decode (in samples before the beginning of the real audio data in the packet). 667 * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length 668 * is frame_size*channels*sizeof(opus_int16) 669 * @param [in] frame_size Number of samples per channel to decode in \a pcm. 670 * frame_size <b>must</b> be a multiple of 2.5 ms. 671 * @returns Number of decoded samples or @ref opus_errorcodes 672 */ 673 OPUS_EXPORT int opus_decoder_dred_decode(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, opus_int16 *pcm, opus_int32 frame_size); 674 675 /** Decode audio from an Opus DRED packet with 24-bit output. 676 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state 677 * @param [in] dred <tt>OpusDRED*</tt>: DRED state 678 * @param [in] dred_offset <tt>opus_int32</tt>: position of the redundancy to decode (in samples before the beginning of the real audio data in the packet). 679 * @param [out] pcm <tt>opus_int32*</tt>: Output signal (interleaved if 2 channels). length 680 * is frame_size*channels*sizeof(opus_int16) 681 * @param [in] frame_size Number of samples per channel to decode in \a pcm. 682 * frame_size <b>must</b> be a multiple of 2.5 ms. 683 * @returns Number of decoded samples or @ref opus_errorcodes 684 */ 685 OPUS_EXPORT int opus_decoder_dred_decode24(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, opus_int32 *pcm, opus_int32 frame_size); 686 687 /** Decode audio from an Opus DRED packet with floating point output. 688 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state 689 * @param [in] dred <tt>OpusDRED*</tt>: DRED state 690 * @param [in] dred_offset <tt>opus_int32</tt>: position of the redundancy to decode (in samples before the beginning of the real audio data in the packet). 691 * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length 692 * is frame_size*channels*sizeof(float) 693 * @param [in] frame_size Number of samples per channel to decode in \a pcm. 694 * frame_size <b>must</b> be a multiple of 2.5 ms. 695 * @returns Number of decoded samples or @ref opus_errorcodes 696 */ 697 OPUS_EXPORT int opus_decoder_dred_decode_float(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, float *pcm, opus_int32 frame_size); 698 699 700 /** Parse an opus packet into one or more frames. 701 * Opus_decode will perform this operation internally so most applications do 702 * not need to use this function. 703 * This function does not copy the frames, the returned pointers are pointers into 704 * the input packet. 705 * @param [in] data <tt>char*</tt>: Opus packet to be parsed 706 * @param [in] len <tt>opus_int32</tt>: size of data 707 * @param [out] out_toc <tt>char*</tt>: TOC pointer 708 * @param [out] frames <tt>char*[48]</tt> encapsulated frames 709 * @param [out] size <tt>opus_int16[48]</tt> sizes of the encapsulated frames 710 * @param [out] payload_offset <tt>int*</tt>: returns the position of the payload within the packet (in bytes) 711 * @returns number of frames 712 */ 713 OPUS_EXPORT int opus_packet_parse( 714 const unsigned char *data, 715 opus_int32 len, 716 unsigned char *out_toc, 717 const unsigned char *frames[48], 718 opus_int16 size[48], 719 int *payload_offset 720 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(5); 721 722 /** Gets the bandwidth of an Opus packet. 723 * @param [in] data <tt>char*</tt>: Opus packet 724 * @retval OPUS_BANDWIDTH_NARROWBAND Narrowband (4kHz bandpass) 725 * @retval OPUS_BANDWIDTH_MEDIUMBAND Mediumband (6kHz bandpass) 726 * @retval OPUS_BANDWIDTH_WIDEBAND Wideband (8kHz bandpass) 727 * @retval OPUS_BANDWIDTH_SUPERWIDEBAND Superwideband (12kHz bandpass) 728 * @retval OPUS_BANDWIDTH_FULLBAND Fullband (20kHz bandpass) 729 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type 730 */ 731 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_bandwidth(const unsigned char *data) OPUS_ARG_NONNULL(1); 732 733 /** Gets the number of samples per frame from an Opus packet. 734 * @param [in] data <tt>char*</tt>: Opus packet. 735 * This must contain at least one byte of 736 * data. 737 * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz. 738 * This must be a multiple of 400, or 739 * inaccurate results will be returned. 740 * @returns Number of samples per frame. 741 */ 742 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs) OPUS_ARG_NONNULL(1); 743 744 /** Gets the number of channels from an Opus packet. 745 * @param [in] data <tt>char*</tt>: Opus packet 746 * @returns Number of channels 747 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type 748 */ 749 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_channels(const unsigned char *data) OPUS_ARG_NONNULL(1); 750 751 /** Gets the number of frames in an Opus packet. 752 * @param [in] packet <tt>char*</tt>: Opus packet 753 * @param [in] len <tt>opus_int32</tt>: Length of packet 754 * @returns Number of frames 755 * @retval OPUS_BAD_ARG Insufficient data was passed to the function 756 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type 757 */ 758 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1); 759 760 /** Gets the number of samples of an Opus packet. 761 * @param [in] packet <tt>char*</tt>: Opus packet 762 * @param [in] len <tt>opus_int32</tt>: Length of packet 763 * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz. 764 * This must be a multiple of 400, or 765 * inaccurate results will be returned. 766 * @returns Number of samples 767 * @retval OPUS_BAD_ARG Insufficient data was passed to the function 768 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type 769 */ 770 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); 771 772 /** Checks whether an Opus packet has LBRR. 773 * @param [in] packet <tt>char*</tt>: Opus packet 774 * @param [in] len <tt>opus_int32</tt>: Length of packet 775 * @returns 1 is LBRR is present, 0 otherwise 776 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type 777 */ 778 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_has_lbrr(const unsigned char packet[], opus_int32 len); 779 780 /** Gets the number of samples of an Opus packet. 781 * @param [in] dec <tt>OpusDecoder*</tt>: Decoder state 782 * @param [in] packet <tt>char*</tt>: Opus packet 783 * @param [in] len <tt>opus_int32</tt>: Length of packet 784 * @returns Number of samples 785 * @retval OPUS_BAD_ARG Insufficient data was passed to the function 786 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type 787 */ 788 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); 789 790 /** Applies soft-clipping to bring a float signal within the [-1,1] range. If 791 * the signal is already in that range, nothing is done. If there are values 792 * outside of [-1,1], then the signal is clipped as smoothly as possible to 793 * both fit in the range and avoid creating excessive distortion in the 794 * process. 795 * @param [in,out] pcm <tt>float*</tt>: Input PCM and modified PCM 796 * @param [in] frame_size <tt>int</tt> Number of samples per channel to process 797 * @param [in] channels <tt>int</tt>: Number of channels 798 * @param [in,out] softclip_mem <tt>float*</tt>: State memory for the soft clipping process (one float per channel, initialized to zero) 799 */ 800 OPUS_EXPORT void opus_pcm_soft_clip(float *pcm, int frame_size, int channels, float *softclip_mem); 801 802 803 /**@}*/ 804 805 /** @defgroup opus_repacketizer Repacketizer 806 * @{ 807 * 808 * The repacketizer can be used to merge multiple Opus packets into a single 809 * packet or alternatively to split Opus packets that have previously been 810 * merged. Splitting valid Opus packets is always guaranteed to succeed, 811 * whereas merging valid packets only succeeds if all frames have the same 812 * mode, bandwidth, and frame size, and when the total duration of the merged 813 * packet is no more than 120 ms. The 120 ms limit comes from the 814 * specification and limits decoder memory requirements at a point where 815 * framing overhead becomes negligible. 816 * 817 * The repacketizer currently only operates on elementary Opus 818 * streams. It will not manipulate multistream packets successfully, except in 819 * the degenerate case where they consist of data from a single stream. 820 * 821 * The repacketizing process starts with creating a repacketizer state, either 822 * by calling opus_repacketizer_create() or by allocating the memory yourself, 823 * e.g., 824 * @code 825 * OpusRepacketizer *rp; 826 * rp = (OpusRepacketizer*)malloc(opus_repacketizer_get_size()); 827 * if (rp != NULL) 828 * opus_repacketizer_init(rp); 829 * @endcode 830 * 831 * Then the application should submit packets with opus_repacketizer_cat(), 832 * extract new packets with opus_repacketizer_out() or 833 * opus_repacketizer_out_range(), and then reset the state for the next set of 834 * input packets via opus_repacketizer_init(). 835 * 836 * For example, to split a sequence of packets into individual frames: 837 * @code 838 * unsigned char *data; 839 * int len; 840 * while (get_next_packet(&data, &len)) 841 * { 842 * unsigned char out[1276]; 843 * opus_int32 out_len; 844 * int nb_frames; 845 * int err; 846 * int i; 847 * err = opus_repacketizer_cat(rp, data, len); 848 * if (err != OPUS_OK) 849 * { 850 * release_packet(data); 851 * return err; 852 * } 853 * nb_frames = opus_repacketizer_get_nb_frames(rp); 854 * for (i = 0; i < nb_frames; i++) 855 * { 856 * out_len = opus_repacketizer_out_range(rp, i, i+1, out, sizeof(out)); 857 * if (out_len < 0) 858 * { 859 * release_packet(data); 860 * return (int)out_len; 861 * } 862 * output_next_packet(out, out_len); 863 * } 864 * opus_repacketizer_init(rp); 865 * release_packet(data); 866 * } 867 * @endcode 868 * 869 * Alternatively, to combine a sequence of frames into packets that each 870 * contain up to <code>TARGET_DURATION_MS</code> milliseconds of data: 871 * @code 872 * // The maximum number of packets with duration TARGET_DURATION_MS occurs 873 * // when the frame size is 2.5 ms, for a total of (TARGET_DURATION_MS*2/5) 874 * // packets. 875 * unsigned char *data[(TARGET_DURATION_MS*2/5)+1]; 876 * opus_int32 len[(TARGET_DURATION_MS*2/5)+1]; 877 * int nb_packets; 878 * unsigned char out[1277*(TARGET_DURATION_MS*2/2)]; 879 * opus_int32 out_len; 880 * int prev_toc; 881 * nb_packets = 0; 882 * while (get_next_packet(data+nb_packets, len+nb_packets)) 883 * { 884 * int nb_frames; 885 * int err; 886 * nb_frames = opus_packet_get_nb_frames(data[nb_packets], len[nb_packets]); 887 * if (nb_frames < 1) 888 * { 889 * release_packets(data, nb_packets+1); 890 * return nb_frames; 891 * } 892 * nb_frames += opus_repacketizer_get_nb_frames(rp); 893 * // If adding the next packet would exceed our target, or it has an 894 * // incompatible TOC sequence, output the packets we already have before 895 * // submitting it. 896 * // N.B., The nb_packets > 0 check ensures we've submitted at least one 897 * // packet since the last call to opus_repacketizer_init(). Otherwise a 898 * // single packet longer than TARGET_DURATION_MS would cause us to try to 899 * // output an (invalid) empty packet. It also ensures that prev_toc has 900 * // been set to a valid value. Additionally, len[nb_packets] > 0 is 901 * // guaranteed by the call to opus_packet_get_nb_frames() above, so the 902 * // reference to data[nb_packets][0] should be valid. 903 * if (nb_packets > 0 && ( 904 * ((prev_toc & 0xFC) != (data[nb_packets][0] & 0xFC)) || 905 * opus_packet_get_samples_per_frame(data[nb_packets], 48000)*nb_frames > 906 * TARGET_DURATION_MS*48)) 907 * { 908 * out_len = opus_repacketizer_out(rp, out, sizeof(out)); 909 * if (out_len < 0) 910 * { 911 * release_packets(data, nb_packets+1); 912 * return (int)out_len; 913 * } 914 * output_next_packet(out, out_len); 915 * opus_repacketizer_init(rp); 916 * release_packets(data, nb_packets); 917 * data[0] = data[nb_packets]; 918 * len[0] = len[nb_packets]; 919 * nb_packets = 0; 920 * } 921 * err = opus_repacketizer_cat(rp, data[nb_packets], len[nb_packets]); 922 * if (err != OPUS_OK) 923 * { 924 * release_packets(data, nb_packets+1); 925 * return err; 926 * } 927 * prev_toc = data[nb_packets][0]; 928 * nb_packets++; 929 * } 930 * // Output the final, partial packet. 931 * if (nb_packets > 0) 932 * { 933 * out_len = opus_repacketizer_out(rp, out, sizeof(out)); 934 * release_packets(data, nb_packets); 935 * if (out_len < 0) 936 * return (int)out_len; 937 * output_next_packet(out, out_len); 938 * } 939 * @endcode 940 * 941 * An alternate way of merging packets is to simply call opus_repacketizer_cat() 942 * unconditionally until it fails. At that point, the merged packet can be 943 * obtained with opus_repacketizer_out() and the input packet for which 944 * opus_repacketizer_cat() needs to be re-added to a newly reinitialized 945 * repacketizer state. 946 */ 947 948 typedef struct OpusRepacketizer OpusRepacketizer; 949 950 /** Gets the size of an <code>OpusRepacketizer</code> structure. 951 * @returns The size in bytes. 952 */ 953 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void); 954 955 /** (Re)initializes a previously allocated repacketizer state. 956 * The state must be at least the size returned by opus_repacketizer_get_size(). 957 * This can be used for applications which use their own allocator instead of 958 * malloc(). 959 * It must also be called to reset the queue of packets waiting to be 960 * repacketized, which is necessary if the maximum packet duration of 120 ms 961 * is reached or if you wish to submit packets with a different Opus 962 * configuration (coding mode, audio bandwidth, frame size, or channel count). 963 * Failure to do so will prevent a new packet from being added with 964 * opus_repacketizer_cat(). 965 * @see opus_repacketizer_create 966 * @see opus_repacketizer_get_size 967 * @see opus_repacketizer_cat 968 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to 969 * (re)initialize. 970 * @returns A pointer to the same repacketizer state that was passed in. 971 */ 972 OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1); 973 974 /** Allocates memory and initializes the new repacketizer with 975 * opus_repacketizer_init(). 976 */ 977 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusRepacketizer *opus_repacketizer_create(void); 978 979 /** Frees an <code>OpusRepacketizer</code> allocated by 980 * opus_repacketizer_create(). 981 * @param[in] rp <tt>OpusRepacketizer*</tt>: State to be freed. 982 */ 983 OPUS_EXPORT void opus_repacketizer_destroy(OpusRepacketizer *rp); 984 985 /** Add a packet to the current repacketizer state. 986 * This packet must match the configuration of any packets already submitted 987 * for repacketization since the last call to opus_repacketizer_init(). 988 * This means that it must have the same coding mode, audio bandwidth, frame 989 * size, and channel count. 990 * This can be checked in advance by examining the top 6 bits of the first 991 * byte of the packet, and ensuring they match the top 6 bits of the first 992 * byte of any previously submitted packet. 993 * The total duration of audio in the repacketizer state also must not exceed 994 * 120 ms, the maximum duration of a single packet, after adding this packet. 995 * 996 * The contents of the current repacketizer state can be extracted into new 997 * packets using opus_repacketizer_out() or opus_repacketizer_out_range(). 998 * 999 * In order to add a packet with a different configuration or to add more 1000 * audio beyond 120 ms, you must clear the repacketizer state by calling 1001 * opus_repacketizer_init(). 1002 * If a packet is too large to add to the current repacketizer state, no part 1003 * of it is added, even if it contains multiple frames, some of which might 1004 * fit. 1005 * If you wish to be able to add parts of such packets, you should first use 1006 * another repacketizer to split the packet into pieces and add them 1007 * individually. 1008 * @see opus_repacketizer_out_range 1009 * @see opus_repacketizer_out 1010 * @see opus_repacketizer_init 1011 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to which to 1012 * add the packet. 1013 * @param[in] data <tt>const unsigned char*</tt>: The packet data. 1014 * The application must ensure 1015 * this pointer remains valid 1016 * until the next call to 1017 * opus_repacketizer_init() or 1018 * opus_repacketizer_destroy(). 1019 * @param len <tt>opus_int32</tt>: The number of bytes in the packet data. 1020 * @returns An error code indicating whether or not the operation succeeded. 1021 * @retval #OPUS_OK The packet's contents have been added to the repacketizer 1022 * state. 1023 * @retval #OPUS_INVALID_PACKET The packet did not have a valid TOC sequence, 1024 * the packet's TOC sequence was not compatible 1025 * with previously submitted packets (because 1026 * the coding mode, audio bandwidth, frame size, 1027 * or channel count did not match), or adding 1028 * this packet would increase the total amount of 1029 * audio stored in the repacketizer state to more 1030 * than 120 ms. 1031 */ 1032 OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2); 1033 1034 1035 /** Construct a new packet from data previously submitted to the repacketizer 1036 * state via opus_repacketizer_cat(). 1037 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to 1038 * construct the new packet. 1039 * @param begin <tt>int</tt>: The index of the first frame in the current 1040 * repacketizer state to include in the output. 1041 * @param end <tt>int</tt>: One past the index of the last frame in the 1042 * current repacketizer state to include in the 1043 * output. 1044 * @param[out] data <tt>const unsigned char*</tt>: The buffer in which to 1045 * store the output packet. 1046 * @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in 1047 * the output buffer. In order to guarantee 1048 * success, this should be at least 1049 * <code>1276</code> for a single frame, 1050 * or for multiple frames, 1051 * <code>1277*(end-begin)</code>. 1052 * However, <code>1*(end-begin)</code> plus 1053 * the size of all packet data submitted to 1054 * the repacketizer since the last call to 1055 * opus_repacketizer_init() or 1056 * opus_repacketizer_create() is also 1057 * sufficient, and possibly much smaller. 1058 * @returns The total size of the output packet on success, or an error code 1059 * on failure. 1060 * @retval #OPUS_BAD_ARG <code>[begin,end)</code> was an invalid range of 1061 * frames (begin < 0, begin >= end, or end > 1062 * opus_repacketizer_get_nb_frames()). 1063 * @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the 1064 * complete output packet. 1065 */ 1066 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); 1067 1068 /** Return the total number of frames contained in packet data submitted to 1069 * the repacketizer state so far via opus_repacketizer_cat() since the last 1070 * call to opus_repacketizer_init() or opus_repacketizer_create(). 1071 * This defines the valid range of packets that can be extracted with 1072 * opus_repacketizer_out_range() or opus_repacketizer_out(). 1073 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state containing the 1074 * frames. 1075 * @returns The total number of frames contained in the packet data submitted 1076 * to the repacketizer state. 1077 */ 1078 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1); 1079 1080 /** Construct a new packet from data previously submitted to the repacketizer 1081 * state via opus_repacketizer_cat(). 1082 * This is a convenience routine that returns all the data submitted so far 1083 * in a single packet. 1084 * It is equivalent to calling 1085 * @code 1086 * opus_repacketizer_out_range(rp, 0, opus_repacketizer_get_nb_frames(rp), 1087 * data, maxlen) 1088 * @endcode 1089 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to 1090 * construct the new packet. 1091 * @param[out] data <tt>const unsigned char*</tt>: The buffer in which to 1092 * store the output packet. 1093 * @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in 1094 * the output buffer. In order to guarantee 1095 * success, this should be at least 1096 * <code>1277*opus_repacketizer_get_nb_frames(rp)</code>. 1097 * However, 1098 * <code>1*opus_repacketizer_get_nb_frames(rp)</code> 1099 * plus the size of all packet data 1100 * submitted to the repacketizer since the 1101 * last call to opus_repacketizer_init() or 1102 * opus_repacketizer_create() is also 1103 * sufficient, and possibly much smaller. 1104 * @returns The total size of the output packet on success, or an error code 1105 * on failure. 1106 * @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the 1107 * complete output packet. 1108 */ 1109 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1); 1110 1111 /** Pads a given Opus packet to a larger size (possibly changing the TOC sequence). 1112 * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the 1113 * packet to pad. 1114 * @param len <tt>opus_int32</tt>: The size of the packet. 1115 * This must be at least 1. 1116 * @param new_len <tt>opus_int32</tt>: The desired size of the packet after padding. 1117 * This must be at least as large as len. 1118 * @returns an error code 1119 * @retval #OPUS_OK \a on success. 1120 * @retval #OPUS_BAD_ARG \a len was less than 1 or new_len was less than len. 1121 * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. 1122 */ 1123 OPUS_EXPORT int opus_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len); 1124 1125 /** Remove all padding from a given Opus packet and rewrite the TOC sequence to 1126 * minimize space usage. 1127 * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the 1128 * packet to strip. 1129 * @param len <tt>opus_int32</tt>: The size of the packet. 1130 * This must be at least 1. 1131 * @returns The new size of the output packet on success, or an error code 1132 * on failure. 1133 * @retval #OPUS_BAD_ARG \a len was less than 1. 1134 * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. 1135 */ 1136 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_packet_unpad(unsigned char *data, opus_int32 len); 1137 1138 /** Pads a given Opus multi-stream packet to a larger size (possibly changing the TOC sequence). 1139 * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the 1140 * packet to pad. 1141 * @param len <tt>opus_int32</tt>: The size of the packet. 1142 * This must be at least 1. 1143 * @param new_len <tt>opus_int32</tt>: The desired size of the packet after padding. 1144 * This must be at least 1. 1145 * @param nb_streams <tt>opus_int32</tt>: The number of streams (not channels) in the packet. 1146 * This must be at least as large as len. 1147 * @returns an error code 1148 * @retval #OPUS_OK \a on success. 1149 * @retval #OPUS_BAD_ARG \a len was less than 1. 1150 * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. 1151 */ 1152 OPUS_EXPORT int opus_multistream_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len, int nb_streams); 1153 1154 /** Remove all padding from a given Opus multi-stream packet and rewrite the TOC sequence to 1155 * minimize space usage. 1156 * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the 1157 * packet to strip. 1158 * @param len <tt>opus_int32</tt>: The size of the packet. 1159 * This must be at least 1. 1160 * @param nb_streams <tt>opus_int32</tt>: The number of streams (not channels) in the packet. 1161 * This must be at least 1. 1162 * @returns The new size of the output packet on success, or an error code 1163 * on failure. 1164 * @retval #OPUS_BAD_ARG \a len was less than 1 or new_len was less than len. 1165 * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. 1166 */ 1167 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_packet_unpad(unsigned char *data, opus_int32 len, int nb_streams); 1168 1169 /**@}*/ 1170 1171 #ifdef __cplusplus 1172 } 1173 #endif 1174 1175 #endif /* OPUS_H */