diff options
Diffstat (limited to 'lib/rbcodec/codecs/libopus/opus.h')
-rw-r--r-- | lib/rbcodec/codecs/libopus/opus.h | 66 |
1 files changed, 52 insertions, 14 deletions
diff --git a/lib/rbcodec/codecs/libopus/opus.h b/lib/rbcodec/codecs/libopus/opus.h index c242fec0e7..38817b405a 100644 --- a/lib/rbcodec/codecs/libopus/opus.h +++ b/lib/rbcodec/codecs/libopus/opus.h | |||
@@ -136,10 +136,11 @@ extern "C" { | |||
136 | * <li>audio_frame is the audio data in opus_int16 (or float for opus_encode_float())</li> | 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> | 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> | 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)</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> | ||
140 | * </ul> | 141 | * </ul> |
141 | * | 142 | * |
142 | * opus_encode() and opus_encode_frame() return the number of bytes actually written to the packet. | 143 | * opus_encode() and opus_encode_float() return the number of bytes actually written to the packet. |
143 | * The return value <b>can be negative</b>, which indicates that an error has occurred. If the return value | 144 | * The return value <b>can be negative</b>, which indicates that an error has occurred. If the return value |
144 | * is 1 byte, then the packet does not need to be transmitted (DTX). | 145 | * is 1 byte, then the packet does not need to be transmitted (DTX). |
145 | * | 146 | * |
@@ -252,9 +253,10 @@ OPUS_EXPORT int opus_encoder_init( | |||
252 | * memory for the output | 253 | * memory for the output |
253 | * payload. This may be | 254 | * payload. This may be |
254 | * used to impose an upper limit on | 255 | * used to impose an upper limit on |
255 | * the variable bitrate, but should | 256 | * the instant bitrate, but should |
256 | * not be used as the only bitrate | 257 | * not be used as the only bitrate |
257 | * control. | 258 | * control. Use #OPUS_SET_BITRATE to |
259 | * control the bitrate. | ||
258 | * @returns The length of the encoded packet (in bytes) on success or a | 260 | * @returns The length of the encoded packet (in bytes) on success or a |
259 | * negative error code (see @ref opus_errorcodes) on failure. | 261 | * negative error code (see @ref opus_errorcodes) on failure. |
260 | */ | 262 | */ |
@@ -292,9 +294,10 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode( | |||
292 | * memory for the output | 294 | * memory for the output |
293 | * payload. This may be | 295 | * payload. This may be |
294 | * used to impose an upper limit on | 296 | * used to impose an upper limit on |
295 | * the variable bitrate, but should | 297 | * the instant bitrate, but should |
296 | * not be used as the only bitrate | 298 | * not be used as the only bitrate |
297 | * control. | 299 | * control. Use #OPUS_SET_BITRATE to |
300 | * control the bitrate. | ||
298 | * @returns The length of the encoded packet (in bytes) on success or a | 301 | * @returns The length of the encoded packet (in bytes) on success or a |
299 | * negative error code (see @ref opus_errorcodes) on failure. | 302 | * negative error code (see @ref opus_errorcodes) on failure. |
300 | */ | 303 | */ |
@@ -340,7 +343,7 @@ OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...) OPUS_ARG_NON | |||
340 | * where | 343 | * where |
341 | * @li Fs is the sampling rate and must be 8000, 12000, 16000, 24000, or 48000 | 344 | * @li Fs is the sampling rate and must be 8000, 12000, 16000, 24000, or 48000 |
342 | * @li channels is the number of channels (1 or 2) | 345 | * @li channels is the number of channels (1 or 2) |
343 | * @li error will hold the error code in case or failure (or #OPUS_OK on success) | 346 | * @li error will hold the error code in case of failure (or #OPUS_OK on success) |
344 | * @li the return value is a newly created decoder state to be used for decoding | 347 | * @li the return value is a newly created decoder state to be used for decoding |
345 | * | 348 | * |
346 | * While opus_decoder_create() allocates memory for the state, it's also possible | 349 | * While opus_decoder_create() allocates memory for the state, it's also possible |
@@ -371,7 +374,7 @@ OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...) OPUS_ARG_NON | |||
371 | * @li max_size is the max duration of the frame in samples (per channel) that can fit into the decoded_frame array | 374 | * @li max_size is the max duration of the frame in samples (per channel) that can fit into the decoded_frame array |
372 | * | 375 | * |
373 | * opus_decode() and opus_decode_float() return the number of samples (per channel) decoded from the packet. | 376 | * opus_decode() and opus_decode_float() return the number of samples (per channel) decoded from the packet. |
374 | * If that value is negative, then an error has occured. This can occur if the packet is corrupted or if the audio | 377 | * If that value is negative, then an error has occurred. This can occur if the packet is corrupted or if the audio |
375 | * buffer is too small to hold the decoded audio. | 378 | * buffer is too small to hold the decoded audio. |
376 | * | 379 | * |
377 | * Opus is a stateful codec with overlapping blocks and as a result Opus | 380 | * Opus is a stateful codec with overlapping blocks and as a result Opus |
@@ -447,8 +450,11 @@ OPUS_EXPORT int opus_decoder_init( | |||
447 | * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length | 450 | * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length |
448 | * is frame_size*channels*sizeof(opus_int16) | 451 | * is frame_size*channels*sizeof(opus_int16) |
449 | * @param [in] frame_size Number of samples per channel of available space in \a pcm. | 452 | * @param [in] frame_size Number of samples per channel of available space in \a pcm. |
450 | * If this is less than the maximum frame size (120 ms), this function will | 453 | * If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will |
451 | * not be capable of decoding some packets. | 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. | ||
452 | * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be | 458 | * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be |
453 | * decoded. If no such data is available, the frame is decoded as if it were lost. | 459 | * decoded. If no such data is available, the frame is decoded as if it were lost. |
454 | * @returns Number of decoded samples or @ref opus_errorcodes | 460 | * @returns Number of decoded samples or @ref opus_errorcodes |
@@ -468,8 +474,12 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode( | |||
468 | * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload | 474 | * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload |
469 | * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length | 475 | * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length |
470 | * is frame_size*channels*sizeof(float) | 476 | * is frame_size*channels*sizeof(float) |
471 | * @param [in] frame_size Number of samples per channel of available space in *pcm, | 477 | * @param [in] frame_size Number of samples per channel of available space in \a pcm. |
472 | * if less than the maximum frame size (120ms) some frames can not be decoded | 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. | ||
473 | * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be | 483 | * @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. | 484 | * 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 | 485 | * @returns Number of decoded samples or @ref opus_errorcodes |
@@ -510,7 +520,7 @@ OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st); | |||
510 | * @param [in] len <tt>opus_int32</tt>: size of data | 520 | * @param [in] len <tt>opus_int32</tt>: size of data |
511 | * @param [out] out_toc <tt>char*</tt>: TOC pointer | 521 | * @param [out] out_toc <tt>char*</tt>: TOC pointer |
512 | * @param [out] frames <tt>char*[48]</tt> encapsulated frames | 522 | * @param [out] frames <tt>char*[48]</tt> encapsulated frames |
513 | * @param [out] size <tt>short[48]</tt> sizes of the encapsulated frames | 523 | * @param [out] size <tt>opus_int16[48]</tt> sizes of the encapsulated frames |
514 | * @param [out] payload_offset <tt>int*</tt>: returns the position of the payload within the packet (in bytes) | 524 | * @param [out] payload_offset <tt>int*</tt>: returns the position of the payload within the packet (in bytes) |
515 | * @returns number of frames | 525 | * @returns number of frames |
516 | */ | 526 | */ |
@@ -519,7 +529,7 @@ OPUS_EXPORT int opus_packet_parse( | |||
519 | opus_int32 len, | 529 | opus_int32 len, |
520 | unsigned char *out_toc, | 530 | unsigned char *out_toc, |
521 | const unsigned char *frames[48], | 531 | const unsigned char *frames[48], |
522 | short size[48], | 532 | opus_int16 size[48], |
523 | int *payload_offset | 533 | int *payload_offset |
524 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); | 534 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); |
525 | 535 | ||
@@ -556,18 +566,46 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_channels(const unsign | |||
556 | * @param [in] packet <tt>char*</tt>: Opus packet | 566 | * @param [in] packet <tt>char*</tt>: Opus packet |
557 | * @param [in] len <tt>opus_int32</tt>: Length of packet | 567 | * @param [in] len <tt>opus_int32</tt>: Length of packet |
558 | * @returns Number of frames | 568 | * @returns Number of frames |
569 | * @retval OPUS_BAD_ARG Insufficient data was passed to the function | ||
559 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type | 570 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
560 | */ | 571 | */ |
561 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1); | 572 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1); |
562 | 573 | ||
563 | /** Gets the number of samples of an Opus packet. | 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. | ||
564 | * @param [in] dec <tt>OpusDecoder*</tt>: Decoder state | 587 | * @param [in] dec <tt>OpusDecoder*</tt>: Decoder state |
565 | * @param [in] packet <tt>char*</tt>: Opus packet | 588 | * @param [in] packet <tt>char*</tt>: Opus packet |
566 | * @param [in] len <tt>opus_int32</tt>: Length of packet | 589 | * @param [in] len <tt>opus_int32</tt>: Length of packet |
567 | * @returns Number of samples | 590 | * @returns Number of samples |
591 | * @retval OPUS_BAD_ARG Insufficient data was passed to the function | ||
568 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type | 592 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
569 | */ | 593 | */ |
570 | 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); | 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 | |||
571 | /**@}*/ | 609 | /**@}*/ |
572 | 610 | ||
573 | /** @defgroup opus_repacketizer Repacketizer | 611 | /** @defgroup opus_repacketizer Repacketizer |