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