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 */ 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 (one of @ref OPUS_APPLICATION_VOIP, @ref OPUS_APPLICATION_AUDIO, or @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 (one of OPUS_APPLICATION_VOIP, OPUS_APPLICATION_AUDIO, or 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 assumptions 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 /** Opus DRED decoder. 402 * This contains the complete state of an Opus DRED decoder. 403 * It is position independent and can be freely copied. 404 * @see opus_dred_decoder_create,opus_dred_decoder_init 405 */ 406 typedef struct OpusDREDDecoder OpusDREDDecoder; 407 408 409 /** Opus DRED state. 410 * This contains the complete state of an Opus DRED packet. 411 * It is position independent and can be freely copied. 412 * @see opus_dred_create,opus_dred_init 413 */ 414 typedef struct OpusDRED OpusDRED; 415 416 /** Gets the size of an <code>OpusDecoder</code> structure. 417 * @param [in] channels <tt>int</tt>: Number of channels. 418 * This must be 1 or 2. 419 * @returns The size in bytes. 420 */ 421 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_size(int channels); 422 423 /** Allocates and initializes a decoder state. 424 * @param [in] Fs <tt>opus_int32</tt>: Sample rate to decode at (Hz). 425 * This must be one of 8000, 12000, 16000, 426 * 24000, or 48000. 427 * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) to decode 428 * @param [out] error <tt>int*</tt>: #OPUS_OK Success or @ref opus_errorcodes 429 * 430 * Internally Opus stores data at 48000 Hz, so that should be the default 431 * value for Fs. However, the decoder can efficiently decode to buffers 432 * at 8, 12, 16, and 24 kHz so if for some reason the caller cannot use 433 * data at the full sample rate, or knows the compressed data doesn't 434 * use the full frequency range, it can request decoding at a reduced 435 * rate. Likewise, the decoder is capable of filling in either mono or 436 * interleaved stereo pcm buffers, at the caller's request. 437 */ 438 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusDecoder *opus_decoder_create( 439 opus_int32 Fs, 440 int channels, 441 int *error 442 ); 443 444 /** Initializes a previously allocated decoder state. 445 * The state must be at least the size returned by opus_decoder_get_size(). 446 * This is intended for applications which use their own allocator instead of malloc. @see opus_decoder_create,opus_decoder_get_size 447 * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL. 448 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state. 449 * @param [in] Fs <tt>opus_int32</tt>: Sampling rate to decode to (Hz). 450 * This must be one of 8000, 12000, 16000, 451 * 24000, or 48000. 452 * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) to decode 453 * @retval #OPUS_OK Success or @ref opus_errorcodes 454 */ 455 OPUS_EXPORT int opus_decoder_init( 456 OpusDecoder *st, 457 opus_int32 Fs, 458 int channels 459 ) OPUS_ARG_NONNULL(1); 460 461 /** Decode an Opus packet. 462 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state 463 * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss 464 * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload* 465 * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length 466 * is frame_size*channels*sizeof(opus_int16) 467 * @param [in] frame_size Number of samples per channel of available space in \a pcm. 468 * If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will 469 * not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1), 470 * then frame_size needs to be exactly the duration of audio that is missing, otherwise the 471 * decoder will not be in the optimal state to decode the next incoming packet. For the PLC and 472 * FEC cases, frame_size <b>must</b> be a multiple of 2.5 ms. 473 * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be 474 * decoded. If no such data is available, the frame is decoded as if it were lost. 475 * @returns Number of decoded samples or @ref opus_errorcodes 476 */ 477 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode( 478 OpusDecoder *st, 479 const unsigned char *data, 480 opus_int32 len, 481 opus_int16 *pcm, 482 int frame_size, 483 int decode_fec 484 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); 485 486 /** Decode an Opus packet with floating point output. 487 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state 488 * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss 489 * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload 490 * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length 491 * is frame_size*channels*sizeof(float) 492 * @param [in] frame_size Number of samples per channel of available space in \a pcm. 493 * If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will 494 * not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1), 495 * then frame_size needs to be exactly the duration of audio that is missing, otherwise the 496 * decoder will not be in the optimal state to decode the next incoming packet. For the PLC and 497 * FEC cases, frame_size <b>must</b> be a multiple of 2.5 ms. 498 * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be 499 * decoded. If no such data is available the frame is decoded as if it were lost. 500 * @returns Number of decoded samples or @ref opus_errorcodes 501 */ 502 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode_float( 503 OpusDecoder *st, 504 const unsigned char *data, 505 opus_int32 len, 506 float *pcm, 507 int frame_size, 508 int decode_fec 509 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); 510 511 /** Perform a CTL function on an Opus decoder. 512 * 513 * Generally the request and subsequent arguments are generated 514 * by a convenience macro. 515 * @param st <tt>OpusDecoder*</tt>: Decoder state. 516 * @param request This and all remaining parameters should be replaced by one 517 * of the convenience macros in @ref opus_genericctls or 518 * @ref opus_decoderctls. 519 * @see opus_genericctls 520 * @see opus_decoderctls 521 */ 522 OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...) OPUS_ARG_NONNULL(1); 523 524 /** Frees an <code>OpusDecoder</code> allocated by opus_decoder_create(). 525 * @param[in] st <tt>OpusDecoder*</tt>: State to be freed. 526 */ 527 OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st); 528 529 /** Gets the size of an <code>OpusDREDDecoder</code> structure. 530 * @returns The size in bytes. 531 */ 532 OPUS_EXPORT int opus_dred_decoder_get_size(void); 533 534 /** Allocates and initializes an OpusDREDDecoder state. 535 * @param [out] error <tt>int*</tt>: #OPUS_OK Success or @ref opus_errorcodes 536 */ 537 OPUS_EXPORT OpusDREDDecoder *opus_dred_decoder_create(int *error); 538 539 /** Initializes an <code>OpusDREDDecoder</code> state. 540 * @param[in] dec <tt>OpusDREDDecoder*</tt>: State to be initialized. 541 */ 542 OPUS_EXPORT int opus_dred_decoder_init(OpusDREDDecoder *dec); 543 544 /** Frees an <code>OpusDREDDecoder</code> allocated by opus_dred_decoder_create(). 545 * @param[in] dec <tt>OpusDREDDecoder*</tt>: State to be freed. 546 */ 547 OPUS_EXPORT void opus_dred_decoder_destroy(OpusDREDDecoder *dec); 548 549 /** Perform a CTL function on an Opus DRED decoder. 550 * 551 * Generally the request and subsequent arguments are generated 552 * by a convenience macro. 553 * @param dred_dec <tt>OpusDREDDecoder*</tt>: DRED Decoder state. 554 * @param request This and all remaining parameters should be replaced by one 555 * of the convenience macros in @ref opus_genericctls or 556 * @ref opus_decoderctls. 557 * @see opus_genericctls 558 * @see opus_decoderctls 559 */ 560 OPUS_EXPORT int opus_dred_decoder_ctl(OpusDREDDecoder *dred_dec, int request, ...); 561 562 /** Gets the size of an <code>OpusDRED</code> structure. 563 * @returns The size in bytes. 564 */ 565 OPUS_EXPORT int opus_dred_get_size(void); 566 567 /** Allocates and initializes a DRED state. 568 * @param [out] error <tt>int*</tt>: #OPUS_OK Success or @ref opus_errorcodes 569 */ 570 OPUS_EXPORT OpusDRED *opus_dred_alloc(int *error); 571 572 /** Frees an <code>OpusDRED</code> allocated by opus_dred_create(). 573 * @param[in] dec <tt>OpusDRED*</tt>: State to be freed. 574 */ 575 OPUS_EXPORT void opus_dred_free(OpusDRED *dec); 576 577 /** Decode an Opus DRED packet. 578 * @param [in] dred_dec <tt>OpusDRED*</tt>: DRED Decoder state 579 * @param [in] dred <tt>OpusDRED*</tt>: DRED state 580 * @param [in] data <tt>char*</tt>: Input payload 581 * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload 582 * @param [in] max_dred_samples <tt>opus_int32</tt>: Maximum number of DRED samples that may be needed (if available in the packet). 583 * @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. 584 * @param [out] dred_end <tt>opus_int32*</tt>: Number of non-encoded (silence) samples between the DRED timestamp and the last DRED sample. 585 * @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. 586 * @returns Offset (positive) of the first decoded DRED samples, zero if no DRED is present, or @ref opus_errorcodes 587 */ 588 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); 589 590 /** Finish decoding an Opus DRED packet. The function only needs to be called if opus_dred_parse() was called with defer_processing=1. 591 * The source and destination will often be the same DRED state. 592 * @param [in] dred_dec <tt>OpusDRED*</tt>: DRED Decoder state 593 * @param [in] src <tt>OpusDRED*</tt>: Source DRED state to start the processing from. 594 * @param [out] dst <tt>OpusDRED*</tt>: Destination DRED state to store the updated state after processing. 595 * @returns @ref opus_errorcodes 596 */ 597 OPUS_EXPORT int opus_dred_process(OpusDREDDecoder *dred_dec, const OpusDRED *src, OpusDRED *dst); 598 599 /** Decode audio from an Opus DRED packet with floating point output. 600 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state 601 * @param [in] dred <tt>OpusDRED*</tt>: DRED state 602 * @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). 603 * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length 604 * is frame_size*channels*sizeof(opus_int16) 605 * @param [in] frame_size Number of samples per channel to decode in \a pcm. 606 * frame_size <b>must</b> be a multiple of 2.5 ms. 607 * @returns Number of decoded samples or @ref opus_errorcodes 608 */ 609 OPUS_EXPORT int opus_decoder_dred_decode(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, opus_int16 *pcm, opus_int32 frame_size); 610 611 /** Decode audio from an Opus DRED packet with floating point output. 612 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state 613 * @param [in] dred <tt>OpusDRED*</tt>: DRED state 614 * @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). 615 * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length 616 * is frame_size*channels*sizeof(float) 617 * @param [in] frame_size Number of samples per channel to decode in \a pcm. 618 * frame_size <b>must</b> be a multiple of 2.5 ms. 619 * @returns Number of decoded samples or @ref opus_errorcodes 620 */ 621 OPUS_EXPORT int opus_decoder_dred_decode_float(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, float *pcm, opus_int32 frame_size); 622 623 624 /** Parse an opus packet into one or more frames. 625 * Opus_decode will perform this operation internally so most applications do 626 * not need to use this function. 627 * This function does not copy the frames, the returned pointers are pointers into 628 * the input packet. 629 * @param [in] data <tt>char*</tt>: Opus packet to be parsed 630 * @param [in] len <tt>opus_int32</tt>: size of data 631 * @param [out] out_toc <tt>char*</tt>: TOC pointer 632 * @param [out] frames <tt>char*[48]</tt> encapsulated frames 633 * @param [out] size <tt>opus_int16[48]</tt> sizes of the encapsulated frames 634 * @param [out] payload_offset <tt>int*</tt>: returns the position of the payload within the packet (in bytes) 635 * @returns number of frames 636 */ 637 OPUS_EXPORT int opus_packet_parse( 638 const unsigned char *data, 639 opus_int32 len, 640 unsigned char *out_toc, 641 const unsigned char *frames[48], 642 opus_int16 size[48], 643 int *payload_offset 644 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(5); 645 646 /** Gets the bandwidth of an Opus packet. 647 * @param [in] data <tt>char*</tt>: Opus packet 648 * @retval OPUS_BANDWIDTH_NARROWBAND Narrowband (4kHz bandpass) 649 * @retval OPUS_BANDWIDTH_MEDIUMBAND Mediumband (6kHz bandpass) 650 * @retval OPUS_BANDWIDTH_WIDEBAND Wideband (8kHz bandpass) 651 * @retval OPUS_BANDWIDTH_SUPERWIDEBAND Superwideband (12kHz bandpass) 652 * @retval OPUS_BANDWIDTH_FULLBAND Fullband (20kHz bandpass) 653 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type 654 */ 655 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_bandwidth(const unsigned char *data) OPUS_ARG_NONNULL(1); 656 657 /** Gets the number of samples per frame from an Opus packet. 658 * @param [in] data <tt>char*</tt>: Opus packet. 659 * This must contain at least one byte of 660 * data. 661 * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz. 662 * This must be a multiple of 400, or 663 * inaccurate results will be returned. 664 * @returns Number of samples per frame. 665 */ 666 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs) OPUS_ARG_NONNULL(1); 667 668 /** Gets the number of channels from an Opus packet. 669 * @param [in] data <tt>char*</tt>: Opus packet 670 * @returns Number of channels 671 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type 672 */ 673 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_channels(const unsigned char *data) OPUS_ARG_NONNULL(1); 674 675 /** Gets the number of frames in an Opus packet. 676 * @param [in] packet <tt>char*</tt>: Opus packet 677 * @param [in] len <tt>opus_int32</tt>: Length of packet 678 * @returns Number of frames 679 * @retval OPUS_BAD_ARG Insufficient data was passed to the function 680 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type 681 */ 682 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1); 683 684 /** Gets the number of samples of an Opus packet. 685 * @param [in] packet <tt>char*</tt>: Opus packet 686 * @param [in] len <tt>opus_int32</tt>: Length of packet 687 * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz. 688 * This must be a multiple of 400, or 689 * inaccurate results will be returned. 690 * @returns Number of samples 691 * @retval OPUS_BAD_ARG Insufficient data was passed to the function 692 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type 693 */ 694 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); 695 696 /** Checks whether an Opus packet has LBRR. 697 * @param [in] packet <tt>char*</tt>: Opus packet 698 * @param [in] len <tt>opus_int32</tt>: Length of packet 699 * @returns 1 is LBRR is present, 0 otherwise 700 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type 701 */ 702 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_has_lbrr(const unsigned char packet[], opus_int32 len); 703 704 /** Gets the number of samples of an Opus packet. 705 * @param [in] dec <tt>OpusDecoder*</tt>: Decoder state 706 * @param [in] packet <tt>char*</tt>: Opus packet 707 * @param [in] len <tt>opus_int32</tt>: Length of packet 708 * @returns Number of samples 709 * @retval OPUS_BAD_ARG Insufficient data was passed to the function 710 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type 711 */ 712 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); 713 714 /** Applies soft-clipping to bring a float signal within the [-1,1] range. If 715 * the signal is already in that range, nothing is done. If there are values 716 * outside of [-1,1], then the signal is clipped as smoothly as possible to 717 * both fit in the range and avoid creating excessive distortion in the 718 * process. 719 * @param [in,out] pcm <tt>float*</tt>: Input PCM and modified PCM 720 * @param [in] frame_size <tt>int</tt> Number of samples per channel to process 721 * @param [in] channels <tt>int</tt>: Number of channels 722 * @param [in,out] softclip_mem <tt>float*</tt>: State memory for the soft clipping process (one float per channel, initialized to zero) 723 */ 724 OPUS_EXPORT void opus_pcm_soft_clip(float *pcm, int frame_size, int channels, float *softclip_mem); 725 726 727 /**@}*/ 728 729 /** @defgroup opus_repacketizer Repacketizer 730 * @{ 731 * 732 * The repacketizer can be used to merge multiple Opus packets into a single 733 * packet or alternatively to split Opus packets that have previously been 734 * merged. Splitting valid Opus packets is always guaranteed to succeed, 735 * whereas merging valid packets only succeeds if all frames have the same 736 * mode, bandwidth, and frame size, and when the total duration of the merged 737 * packet is no more than 120 ms. The 120 ms limit comes from the 738 * specification and limits decoder memory requirements at a point where 739 * framing overhead becomes negligible. 740 * 741 * The repacketizer currently only operates on elementary Opus 742 * streams. It will not manipualte multistream packets successfully, except in 743 * the degenerate case where they consist of data from a single stream. 744 * 745 * The repacketizing process starts with creating a repacketizer state, either 746 * by calling opus_repacketizer_create() or by allocating the memory yourself, 747 * e.g., 748 * @code 749 * OpusRepacketizer *rp; 750 * rp = (OpusRepacketizer*)malloc(opus_repacketizer_get_size()); 751 * if (rp != NULL) 752 * opus_repacketizer_init(rp); 753 * @endcode 754 * 755 * Then the application should submit packets with opus_repacketizer_cat(), 756 * extract new packets with opus_repacketizer_out() or 757 * opus_repacketizer_out_range(), and then reset the state for the next set of 758 * input packets via opus_repacketizer_init(). 759 * 760 * For example, to split a sequence of packets into individual frames: 761 * @code 762 * unsigned char *data; 763 * int len; 764 * while (get_next_packet(&data, &len)) 765 * { 766 * unsigned char out[1276]; 767 * opus_int32 out_len; 768 * int nb_frames; 769 * int err; 770 * int i; 771 * err = opus_repacketizer_cat(rp, data, len); 772 * if (err != OPUS_OK) 773 * { 774 * release_packet(data); 775 * return err; 776 * } 777 * nb_frames = opus_repacketizer_get_nb_frames(rp); 778 * for (i = 0; i < nb_frames; i++) 779 * { 780 * out_len = opus_repacketizer_out_range(rp, i, i+1, out, sizeof(out)); 781 * if (out_len < 0) 782 * { 783 * release_packet(data); 784 * return (int)out_len; 785 * } 786 * output_next_packet(out, out_len); 787 * } 788 * opus_repacketizer_init(rp); 789 * release_packet(data); 790 * } 791 * @endcode 792 * 793 * Alternatively, to combine a sequence of frames into packets that each 794 * contain up to <code>TARGET_DURATION_MS</code> milliseconds of data: 795 * @code 796 * // The maximum number of packets with duration TARGET_DURATION_MS occurs 797 * // when the frame size is 2.5 ms, for a total of (TARGET_DURATION_MS*2/5) 798 * // packets. 799 * unsigned char *data[(TARGET_DURATION_MS*2/5)+1]; 800 * opus_int32 len[(TARGET_DURATION_MS*2/5)+1]; 801 * int nb_packets; 802 * unsigned char out[1277*(TARGET_DURATION_MS*2/2)]; 803 * opus_int32 out_len; 804 * int prev_toc; 805 * nb_packets = 0; 806 * while (get_next_packet(data+nb_packets, len+nb_packets)) 807 * { 808 * int nb_frames; 809 * int err; 810 * nb_frames = opus_packet_get_nb_frames(data[nb_packets], len[nb_packets]); 811 * if (nb_frames < 1) 812 * { 813 * release_packets(data, nb_packets+1); 814 * return nb_frames; 815 * } 816 * nb_frames += opus_repacketizer_get_nb_frames(rp); 817 * // If adding the next packet would exceed our target, or it has an 818 * // incompatible TOC sequence, output the packets we already have before 819 * // submitting it. 820 * // N.B., The nb_packets > 0 check ensures we've submitted at least one 821 * // packet since the last call to opus_repacketizer_init(). Otherwise a 822 * // single packet longer than TARGET_DURATION_MS would cause us to try to 823 * // output an (invalid) empty packet. It also ensures that prev_toc has 824 * // been set to a valid value. Additionally, len[nb_packets] > 0 is 825 * // guaranteed by the call to opus_packet_get_nb_frames() above, so the 826 * // reference to data[nb_packets][0] should be valid. 827 * if (nb_packets > 0 && ( 828 * ((prev_toc & 0xFC) != (data[nb_packets][0] & 0xFC)) || 829 * opus_packet_get_samples_per_frame(data[nb_packets], 48000)*nb_frames > 830 * TARGET_DURATION_MS*48)) 831 * { 832 * out_len = opus_repacketizer_out(rp, out, sizeof(out)); 833 * if (out_len < 0) 834 * { 835 * release_packets(data, nb_packets+1); 836 * return (int)out_len; 837 * } 838 * output_next_packet(out, out_len); 839 * opus_repacketizer_init(rp); 840 * release_packets(data, nb_packets); 841 * data[0] = data[nb_packets]; 842 * len[0] = len[nb_packets]; 843 * nb_packets = 0; 844 * } 845 * err = opus_repacketizer_cat(rp, data[nb_packets], len[nb_packets]); 846 * if (err != OPUS_OK) 847 * { 848 * release_packets(data, nb_packets+1); 849 * return err; 850 * } 851 * prev_toc = data[nb_packets][0]; 852 * nb_packets++; 853 * } 854 * // Output the final, partial packet. 855 * if (nb_packets > 0) 856 * { 857 * out_len = opus_repacketizer_out(rp, out, sizeof(out)); 858 * release_packets(data, nb_packets); 859 * if (out_len < 0) 860 * return (int)out_len; 861 * output_next_packet(out, out_len); 862 * } 863 * @endcode 864 * 865 * An alternate way of merging packets is to simply call opus_repacketizer_cat() 866 * unconditionally until it fails. At that point, the merged packet can be 867 * obtained with opus_repacketizer_out() and the input packet for which 868 * opus_repacketizer_cat() needs to be re-added to a newly reinitialized 869 * repacketizer state. 870 */ 871 872 typedef struct OpusRepacketizer OpusRepacketizer; 873 874 /** Gets the size of an <code>OpusRepacketizer</code> structure. 875 * @returns The size in bytes. 876 */ 877 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void); 878 879 /** (Re)initializes a previously allocated repacketizer state. 880 * The state must be at least the size returned by opus_repacketizer_get_size(). 881 * This can be used for applications which use their own allocator instead of 882 * malloc(). 883 * It must also be called to reset the queue of packets waiting to be 884 * repacketized, which is necessary if the maximum packet duration of 120 ms 885 * is reached or if you wish to submit packets with a different Opus 886 * configuration (coding mode, audio bandwidth, frame size, or channel count). 887 * Failure to do so will prevent a new packet from being added with 888 * opus_repacketizer_cat(). 889 * @see opus_repacketizer_create 890 * @see opus_repacketizer_get_size 891 * @see opus_repacketizer_cat 892 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to 893 * (re)initialize. 894 * @returns A pointer to the same repacketizer state that was passed in. 895 */ 896 OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1); 897 898 /** Allocates memory and initializes the new repacketizer with 899 * opus_repacketizer_init(). 900 */ 901 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusRepacketizer *opus_repacketizer_create(void); 902 903 /** Frees an <code>OpusRepacketizer</code> allocated by 904 * opus_repacketizer_create(). 905 * @param[in] rp <tt>OpusRepacketizer*</tt>: State to be freed. 906 */ 907 OPUS_EXPORT void opus_repacketizer_destroy(OpusRepacketizer *rp); 908 909 /** Add a packet to the current repacketizer state. 910 * This packet must match the configuration of any packets already submitted 911 * for repacketization since the last call to opus_repacketizer_init(). 912 * This means that it must have the same coding mode, audio bandwidth, frame 913 * size, and channel count. 914 * This can be checked in advance by examining the top 6 bits of the first 915 * byte of the packet, and ensuring they match the top 6 bits of the first 916 * byte of any previously submitted packet. 917 * The total duration of audio in the repacketizer state also must not exceed 918 * 120 ms, the maximum duration of a single packet, after adding this packet. 919 * 920 * The contents of the current repacketizer state can be extracted into new 921 * packets using opus_repacketizer_out() or opus_repacketizer_out_range(). 922 * 923 * In order to add a packet with a different configuration or to add more 924 * audio beyond 120 ms, you must clear the repacketizer state by calling 925 * opus_repacketizer_init(). 926 * If a packet is too large to add to the current repacketizer state, no part 927 * of it is added, even if it contains multiple frames, some of which might 928 * fit. 929 * If you wish to be able to add parts of such packets, you should first use 930 * another repacketizer to split the packet into pieces and add them 931 * individually. 932 * @see opus_repacketizer_out_range 933 * @see opus_repacketizer_out 934 * @see opus_repacketizer_init 935 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to which to 936 * add the packet. 937 * @param[in] data <tt>const unsigned char*</tt>: The packet data. 938 * The application must ensure 939 * this pointer remains valid 940 * until the next call to 941 * opus_repacketizer_init() or 942 * opus_repacketizer_destroy(). 943 * @param len <tt>opus_int32</tt>: The number of bytes in the packet data. 944 * @returns An error code indicating whether or not the operation succeeded. 945 * @retval #OPUS_OK The packet's contents have been added to the repacketizer 946 * state. 947 * @retval #OPUS_INVALID_PACKET The packet did not have a valid TOC sequence, 948 * the packet's TOC sequence was not compatible 949 * with previously submitted packets (because 950 * the coding mode, audio bandwidth, frame size, 951 * or channel count did not match), or adding 952 * this packet would increase the total amount of 953 * audio stored in the repacketizer state to more 954 * than 120 ms. 955 */ 956 OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2); 957 958 959 /** Construct a new packet from data previously submitted to the repacketizer 960 * state via opus_repacketizer_cat(). 961 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to 962 * construct the new packet. 963 * @param begin <tt>int</tt>: The index of the first frame in the current 964 * repacketizer state to include in the output. 965 * @param end <tt>int</tt>: One past the index of the last frame in the 966 * current repacketizer state to include in the 967 * output. 968 * @param[out] data <tt>const unsigned char*</tt>: The buffer in which to 969 * store the output packet. 970 * @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in 971 * the output buffer. In order to guarantee 972 * success, this should be at least 973 * <code>1276</code> for a single frame, 974 * or for multiple frames, 975 * <code>1277*(end-begin)</code>. 976 * However, <code>1*(end-begin)</code> plus 977 * the size of all packet data submitted to 978 * the repacketizer since the last call to 979 * opus_repacketizer_init() or 980 * opus_repacketizer_create() is also 981 * sufficient, and possibly much smaller. 982 * @returns The total size of the output packet on success, or an error code 983 * on failure. 984 * @retval #OPUS_BAD_ARG <code>[begin,end)</code> was an invalid range of 985 * frames (begin < 0, begin >= end, or end > 986 * opus_repacketizer_get_nb_frames()). 987 * @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the 988 * complete output packet. 989 */ 990 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); 991 992 /** Return the total number of frames contained in packet data submitted to 993 * the repacketizer state so far via opus_repacketizer_cat() since the last 994 * call to opus_repacketizer_init() or opus_repacketizer_create(). 995 * This defines the valid range of packets that can be extracted with 996 * opus_repacketizer_out_range() or opus_repacketizer_out(). 997 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state containing the 998 * frames. 999 * @returns The total number of frames contained in the packet data submitted 1000 * to the repacketizer state. 1001 */ 1002 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1); 1003 1004 /** Construct a new packet from data previously submitted to the repacketizer 1005 * state via opus_repacketizer_cat(). 1006 * This is a convenience routine that returns all the data submitted so far 1007 * in a single packet. 1008 * It is equivalent to calling 1009 * @code 1010 * opus_repacketizer_out_range(rp, 0, opus_repacketizer_get_nb_frames(rp), 1011 * data, maxlen) 1012 * @endcode 1013 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to 1014 * construct the new packet. 1015 * @param[out] data <tt>const unsigned char*</tt>: The buffer in which to 1016 * store the output packet. 1017 * @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in 1018 * the output buffer. In order to guarantee 1019 * success, this should be at least 1020 * <code>1277*opus_repacketizer_get_nb_frames(rp)</code>. 1021 * However, 1022 * <code>1*opus_repacketizer_get_nb_frames(rp)</code> 1023 * plus the size of all packet data 1024 * submitted to the repacketizer since the 1025 * last call to opus_repacketizer_init() or 1026 * opus_repacketizer_create() is also 1027 * sufficient, and possibly much smaller. 1028 * @returns The total size of the output packet on success, or an error code 1029 * on failure. 1030 * @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the 1031 * complete output packet. 1032 */ 1033 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1); 1034 1035 /** Pads a given Opus packet to a larger size (possibly changing the TOC sequence). 1036 * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the 1037 * packet to pad. 1038 * @param len <tt>opus_int32</tt>: The size of the packet. 1039 * This must be at least 1. 1040 * @param new_len <tt>opus_int32</tt>: The desired size of the packet after padding. 1041 * This must be at least as large as len. 1042 * @returns an error code 1043 * @retval #OPUS_OK \a on success. 1044 * @retval #OPUS_BAD_ARG \a len was less than 1 or new_len was less than len. 1045 * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. 1046 */ 1047 OPUS_EXPORT int opus_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len); 1048 1049 /** Remove all padding from a given Opus packet and rewrite the TOC sequence to 1050 * minimize space usage. 1051 * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the 1052 * packet to strip. 1053 * @param len <tt>opus_int32</tt>: The size of the packet. 1054 * This must be at least 1. 1055 * @returns The new size of the output packet on success, or an error code 1056 * on failure. 1057 * @retval #OPUS_BAD_ARG \a len was less than 1. 1058 * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. 1059 */ 1060 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_packet_unpad(unsigned char *data, opus_int32 len); 1061 1062 /** Pads a given Opus multi-stream packet to a larger size (possibly changing the TOC sequence). 1063 * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the 1064 * packet to pad. 1065 * @param len <tt>opus_int32</tt>: The size of the packet. 1066 * This must be at least 1. 1067 * @param new_len <tt>opus_int32</tt>: The desired size of the packet after padding. 1068 * This must be at least 1. 1069 * @param nb_streams <tt>opus_int32</tt>: The number of streams (not channels) in the packet. 1070 * This must be at least as large as len. 1071 * @returns an error code 1072 * @retval #OPUS_OK \a on success. 1073 * @retval #OPUS_BAD_ARG \a len was less than 1. 1074 * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. 1075 */ 1076 OPUS_EXPORT int opus_multistream_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len, int nb_streams); 1077 1078 /** Remove all padding from a given Opus multi-stream packet and rewrite the TOC sequence to 1079 * minimize space usage. 1080 * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the 1081 * packet to strip. 1082 * @param len <tt>opus_int32</tt>: The size of the packet. 1083 * This must be at least 1. 1084 * @param nb_streams <tt>opus_int32</tt>: The number of streams (not channels) in the packet. 1085 * This must be at least 1. 1086 * @returns The new size of the output packet on success, or an error code 1087 * on failure. 1088 * @retval #OPUS_BAD_ARG \a len was less than 1 or new_len was less than len. 1089 * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. 1090 */ 1091 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_packet_unpad(unsigned char *data, opus_int32 len, int nb_streams); 1092 1093 /**@}*/ 1094 1095 #ifdef __cplusplus 1096 } 1097 #endif 1098 1099 #endif /* OPUS_H */ 1100