@}
     @defgroup opus_libinfo Opus library information functions
    @{
     
     Converts an opus error code into a human readable string.
    
    @param[in] error <tt>int</tt>: Error number
    @returns Error string

  Gets the libopus version string.
    
    Applications may look for the substring "-fixed" in the version string to
    determine whether they have a fixed-point or floating-point build at
    runtime.
    
    @returns Version string

  Gets the size of an <code>OpusEncoder</code> structure.
    @param[in] channels <tt>int</tt>: Number of channels.
                                      This must be 1 or 2.
    @returns The size in bytes.

  Allocates and initializes an encoder state.
   There are three coding modes:
   
   @ref OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voice
      signals. It enhances the  input signal by high-pass filtering and
      emphasizing formants and harmonics. Optionally  it includes in-band
      forward error correction to protect against packet loss. Use this
      mode for typical VoIP applications. Because of the enhancement,
      even at high bitrates the output may sound different from the input.
   
   @ref OPUS_APPLICATION_AUDIO gives best quality at a given bitrate for most
      non-voice signals like music. Use this mode for music and mixed
      (music/voice) content, broadcast, and applications requiring less
      than 15 ms of coding delay.
   
   @ref OPUS_APPLICATION_RESTRICTED_LOWDELAY configures low-delay mode that
      disables the speech-optimized mode in exchange for slightly reduced delay.
      This mode can only be set on an newly initialized or freshly reset encoder
      because it changes the codec delay.
   
   This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution).
   @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
                                       This must be one of 8000, 12000, 16000,
                                       24000, or 48000.
   @param [in] channels <tt>int</tt>: Number of channels (1 or 2) in input signal
   @param [in] application <tt>int</tt>: Coding mode (@ref OPUS_APPLICATION_VOIP/@ref OPUS_APPLICATION_AUDIO/@ref OPUS_APPLICATION_RESTRICTED_LOWDELAY)
   @param [out] error <tt>int*</tt>: @ref opus_errorcodes
   @note Regardless of the sampling rate and number channels selected, the Opus encoder
   can switch to a lower audio bandwidth or number of channels if the bitrate
   selected is too low. This also means that it is safe to always use 48 kHz stereo input
   and let the encoder optimize the encoding.

  Initializes a previously allocated encoder state
    The memory pointed to by st must be at least the size returned by opus_encoder_get_size().
    This is intended for applications which use their own allocator instead of malloc.
    @see opus_encoder_create(),opus_encoder_get_size()
    To reset a previously initialized state, use the #OPUS_RESET_STATE CTL.
    @param [in] st <tt>OpusEncoder*</tt>: Encoder state
    @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
                                        This must be one of 8000, 12000, 16000,
                                        24000, or 48000.
    @param [in] channels <tt>int</tt>: Number of channels (1 or 2) in input signal
    @param [in] application <tt>int</tt>: Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)
    @retval #OPUS_OK Success or @ref opus_errorcodes

  Encodes an Opus frame.
    @param [in] st <tt>OpusEncoder*</tt>: Encoder state
    @param [in] pcm <tt>opus_int16*</tt>: Input signal (interleaved if 2 channels). length is frame_size*channels*sizeof(opus_int16)
    @param [in] frame_size <tt>int</tt>: Number of samples per channel in the
                                         input signal.
                                         This must be an Opus frame size for
                                         the encoder's sampling rate.
                                         For example, at 48 kHz the permitted
                                         values are 120, 240, 480, 960, 1920,
                                         and 2880.
                                         Passing in a duration of less than
                                         10 ms (480 samples at 48 kHz) will
                                         prevent the encoder from using the LPC
                                         or hybrid modes.
    @param [out] data <tt>unsigned char*</tt>: Output payload.
                                               This must contain storage for at
                                               least \a max_data_bytes.
    @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated
                                                    memory for the output
                                                    payload. This may be
                                                    used to impose an upper limit on
                                                    the instant bitrate, but should
                                                    not be used as the only bitrate
                                                    control. Use #OPUS_SET_BITRATE to
                                                    control the bitrate.
    @returns The length of the encoded packet (in bytes) on success or a
             negative error code (see @ref opus_errorcodes) on failure.

  Encodes an Opus frame from floating point input.
    @param [in] st <tt>OpusEncoder*</tt>: Encoder state
    @param [in] pcm <tt>float*</tt>: Input in float format (interleaved if 2 channels), with a normal range of +/-1.0.
             Samples with a range beyond +/-1.0 are supported but will
             be clipped by decoders using the integer API and should
             only be used if it is known that the far end supports
             extended dynamic range.
             length is frame_size*channels*sizeof(float)
    @param [in] frame_size <tt>int</tt>: Number of samples per channel in the
                                         input signal.
                                         This must be an Opus frame size for
                                         the encoder's sampling rate.
                                         For example, at 48 kHz the permitted
                                         values are 120, 240, 480, 960, 1920,
                                         and 2880.
                                         Passing in a duration of less than
                                         10 ms (480 samples at 48 kHz) will
                                         prevent the encoder from using the LPC
                                         or hybrid modes.
    @param [out] data <tt>unsigned char*</tt>: Output payload.
                                               This must contain storage for at
                                               least \a max_data_bytes.
    @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated
                                                    memory for the output
                                                    payload. This may be
                                                    used to impose an upper limit on
                                                    the instant bitrate, but should
                                                    not be used as the only bitrate
                                                    control. Use #OPUS_SET_BITRATE to
                                                    control the bitrate.
    @returns The length of the encoded packet (in bytes) on success or a
             negative error code (see @ref opus_errorcodes) on failure.

  Frees an <code>OpusEncoder</code> allocated by opus_encoder_create().
    @param[in] st <tt>OpusEncoder*</tt>: State to be freed.

  Perform a CTL function on an Opus encoder.
    
    Generally the request and subsequent arguments are generated
    by a convenience macro.
    @param st <tt>OpusEncoder*</tt>: Encoder state.
    @param request This and all remaining parameters should be replaced by one
                   of the convenience macros in @ref opus_genericctls or
                   @ref opus_encoderctls.
    @see opus_genericctls
    @see opus_encoderctls

  Gets the size of an <code>OpusDecoder</code> structure.
    @param [in] channels <tt>int</tt>: Number of channels.
                                       This must be 1 or 2.
    @returns The size in bytes.

  Allocates and initializes a decoder state.
    @param [in] Fs <tt>opus_int32</tt>: Sample rate to decode at (Hz).
                                        This must be one of 8000, 12000, 16000,
                                        24000, or 48000.
    @param [in] channels <tt>int</tt>: Number of channels (1 or 2) to decode
    @param [out] error <tt>int*</tt>: #OPUS_OK Success or @ref opus_errorcodes
    
    Internally Opus stores data at 48000 Hz, so that should be the default
    value for Fs. However, the decoder can efficiently decode to buffers
    at 8, 12, 16, and 24 kHz so if for some reason the caller cannot use
    data at the full sample rate, or knows the compressed data doesn't
    use the full frequency range, it can request decoding at a reduced
    rate. Likewise, the decoder is capable of filling in either mono or
    interleaved stereo pcm buffers, at the caller's request.

  Initializes a previously allocated decoder state.
    The state must be at least the size returned by opus_decoder_get_size().
    This is intended for applications which use their own allocator instead of malloc. @see opus_decoder_create,opus_decoder_get_size
    To reset a previously initialized state, use the #OPUS_RESET_STATE CTL.
    @param [in] st <tt>OpusDecoder*</tt>: Decoder state.
    @param [in] Fs <tt>opus_int32</tt>: Sampling rate to decode to (Hz).
                                        This must be one of 8000, 12000, 16000,
                                        24000, or 48000.
    @param [in] channels <tt>int</tt>: Number of channels (1 or 2) to decode
    @retval #OPUS_OK Success or @ref opus_errorcodes

  Decode an Opus packet.
    @param [in] st <tt>OpusDecoder*</tt>: Decoder state
    @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
    @param [in] len <tt>opus_int32</tt>: Number of bytes in payload*
    @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length
     is frame_size*channels*sizeof(opus_int16)
    @param [in] frame_size Number of samples per channel of available space in \a pcm.
     If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will
     not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1),
     then frame_size needs to be exactly the duration of audio that is missing, otherwise the
     decoder will not be in the optimal state to decode the next incoming packet. For the PLC and
     FEC cases, frame_size <b>must</b> be a multiple of 2.5 ms.
    @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be
     decoded. If no such data is available, the frame is decoded as if it were lost.
    @returns Number of decoded samples or @ref opus_errorcodes

  Decode an Opus packet with floating point output.
    @param [in] st <tt>OpusDecoder*</tt>: Decoder state
    @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
    @param [in] len <tt>opus_int32</tt>: Number of bytes in payload
    @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length
     is frame_size*channels*sizeof(float)
    @param [in] frame_size Number of samples per channel of available space in \a pcm.
     If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will
     not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1),
     then frame_size needs to be exactly the duration of audio that is missing, otherwise the
     decoder will not be in the optimal state to decode the next incoming packet. For the PLC and
     FEC cases, frame_size <b>must</b> be a multiple of 2.5 ms.
    @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be
     decoded. If no such data is available the frame is decoded as if it were lost.
    @returns Number of decoded samples or @ref opus_errorcodes

  Perform a CTL function on an Opus decoder.
    
    Generally the request and subsequent arguments are generated
    by a convenience macro.
    @param st <tt>OpusDecoder*</tt>: Decoder state.
    @param request This and all remaining parameters should be replaced by one
                   of the convenience macros in @ref opus_genericctls or
                   @ref opus_decoderctls.
    @see opus_genericctls
    @see opus_decoderctls

  Frees an <code>OpusDecoder</code> allocated by opus_decoder_create().
    @param[in] st <tt>OpusDecoder*</tt>: State to be freed.

  Parse an opus packet into one or more frames.
    Opus_decode will perform this operation internally so most applications do
    not need to use this function.
    This function does not copy the frames, the returned pointers are pointers into
    the input packet.
    @param [in] data <tt>char*</tt>: Opus packet to be parsed
    @param [in] len <tt>opus_int32</tt>: size of data
    @param [out] out_toc <tt>char*</tt>: TOC pointer
    @param [out] frames <tt>char*[48]</tt> encapsulated frames
    @param [out] size <tt>opus_int16[48]</tt> sizes of the encapsulated frames
    @param [out] payload_offset <tt>int*</tt>: returns the position of the payload within the packet (in bytes)
    @returns number of frames

  Gets the bandwidth of an Opus packet.
    @param [in] data <tt>char*</tt>: Opus packet
    @retval OPUS_BANDWIDTH_NARROWBAND Narrowband (4kHz bandpass)
    @retval OPUS_BANDWIDTH_MEDIUMBAND Mediumband (6kHz bandpass)
    @retval OPUS_BANDWIDTH_WIDEBAND Wideband (8kHz bandpass)
    @retval OPUS_BANDWIDTH_SUPERWIDEBAND Superwideband (12kHz bandpass)
    @retval OPUS_BANDWIDTH_FULLBAND Fullband (20kHz bandpass)
    @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type

  Gets the number of samples per frame from an Opus packet.
    @param [in] data <tt>char*</tt>: Opus packet.
                                     This must contain at least one byte of
                                     data.
    @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz.
                                        This must be a multiple of 400, or
                                        inaccurate results will be returned.
    @returns Number of samples per frame.

  Gets the number of channels from an Opus packet.
    @param [in] data <tt>char*</tt>: Opus packet
    @returns Number of channels
    @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type

  Gets the number of frames in an Opus packet.
    @param [in] packet <tt>char*</tt>: Opus packet
    @param [in] len <tt>opus_int32</tt>: Length of packet
    @returns Number of frames
    @retval OPUS_BAD_ARG Insufficient data was passed to the function
    @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type

  Gets the number of samples of an Opus packet.
    @param [in] packet <tt>char*</tt>: Opus packet
    @param [in] len <tt>opus_int32</tt>: Length of packet
    @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz.
                                        This must be a multiple of 400, or
                                        inaccurate results will be returned.
    @returns Number of samples
    @retval OPUS_BAD_ARG Insufficient data was passed to the function
    @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type

  Gets the number of samples of an Opus packet.
    @param [in] dec <tt>OpusDecoder*</tt>: Decoder state
    @param [in] packet <tt>char*</tt>: Opus packet
    @param [in] len <tt>opus_int32</tt>: Length of packet
    @returns Number of samples
    @retval OPUS_BAD_ARG Insufficient data was passed to the function
    @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type

  Applies soft-clipping to bring a float signal within the [-1,1] range. If
    the signal is already in that range, nothing is done. If there are values
    outside of [-1,1], then the signal is clipped as smoothly as possible to
    both fit in the range and avoid creating excessive distortion in the
    process.
    @param [in,out] pcm <tt>float*</tt>: Input PCM and modified PCM
    @param [in] frame_size <tt>int</tt> Number of samples per channel to process
    @param [in] channels <tt>int</tt>: Number of channels
    @param [in,out] softclip_mem <tt>float*</tt>: State memory for the soft clipping process (one float per channel, initialized to zero)

  Gets the size of an <code>OpusRepacketizer</code> structure.
    @returns The size in bytes.

  (Re)initializes a previously allocated repacketizer state.
    The state must be at least the size returned by opus_repacketizer_get_size().
    This can be used for applications which use their own allocator instead of
    malloc().
    It must also be called to reset the queue of packets waiting to be
    repacketized, which is necessary if the maximum packet duration of 120 ms
    is reached or if you wish to submit packets with a different Opus
    configuration (coding mode, audio bandwidth, frame size, or channel count).
    Failure to do so will prevent a new packet from being added with
    opus_repacketizer_cat().
    @see opus_repacketizer_create
    @see opus_repacketizer_get_size
    @see opus_repacketizer_cat
    @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to
                                          (re)initialize.
    @returns A pointer to the same repacketizer state that was passed in.

  Allocates memory and initializes the new repacketizer with
   opus_repacketizer_init().

  Frees an <code>OpusRepacketizer</code> allocated by
    opus_repacketizer_create().
    @param[in] rp <tt>OpusRepacketizer*</tt>: State to be freed.

  Add a packet to the current repacketizer state.
    This packet must match the configuration of any packets already submitted
    for repacketization since the last call to opus_repacketizer_init().
    This means that it must have the same coding mode, audio bandwidth, frame
    size, and channel count.
    This can be checked in advance by examining the top 6 bits of the first
    byte of the packet, and ensuring they match the top 6 bits of the first
    byte of any previously submitted packet.
    The total duration of audio in the repacketizer state also must not exceed
    120 ms, the maximum duration of a single packet, after adding this packet.
    
    The contents of the current repacketizer state can be extracted into new
    packets using opus_repacketizer_out() or opus_repacketizer_out_range().
    
    In order to add a packet with a different configuration or to add more
    audio beyond 120 ms, you must clear the repacketizer state by calling
    opus_repacketizer_init().
    If a packet is too large to add to the current repacketizer state, no part
    of it is added, even if it contains multiple frames, some of which might
    fit.
    If you wish to be able to add parts of such packets, you should first use
    another repacketizer to split the packet into pieces and add them
    individually.
    @see opus_repacketizer_out_range
    @see opus_repacketizer_out
    @see opus_repacketizer_init
    @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to which to
                                          add the packet.
    @param[in] data <tt>const unsigned char*</tt>: The packet data.
                                                   The application must ensure
                                                   this pointer remains valid
                                                   until the next call to
                                                   opus_repacketizer_init() or
                                                   opus_repacketizer_destroy().
    @param len <tt>opus_int32</tt>: The number of bytes in the packet data.
    @returns An error code indicating whether or not the operation succeeded.
    @retval #OPUS_OK The packet's contents have been added to the repacketizer
                     state.
    @retval #OPUS_INVALID_PACKET The packet did not have a valid TOC sequence,
                                 the packet's TOC sequence was not compatible
                                 with previously submitted packets (because
                                 the coding mode, audio bandwidth, frame size,
                                 or channel count did not match), or adding
                                 this packet would increase the total amount of
                                 audio stored in the repacketizer state to more
                                 than 120 ms.

  Construct a new packet from data previously submitted to the repacketizer
    state via opus_repacketizer_cat().
    @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to
                                          construct the new packet.
    @param begin <tt>int</tt>: The index of the first frame in the current
                               repacketizer state to include in the output.
    @param end <tt>int</tt>: One past the index of the last frame in the
                             current repacketizer state to include in the
                             output.
    @param[out] data <tt>const unsigned char*</tt>: The buffer in which to
                                                    store the output packet.
    @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in
                                       the output buffer. In order to guarantee
                                       success, this should be at least
                                       <code>1276</code> for a single frame,
                                       or for multiple frames,
                                       <code>1277*(end-begin)</code>.
                                       However, <code>1*(end-begin)</code> plus
                                       the size of all packet data submitted to
                                       the repacketizer since the last call to
                                       opus_repacketizer_init() or
                                       opus_repacketizer_create() is also
                                       sufficient, and possibly much smaller.
    @returns The total size of the output packet on success, or an error code
             on failure.
    @retval #OPUS_BAD_ARG <code>[begin,end)</code> was an invalid range of
                          frames (begin < 0, begin >= end, or end >
                          opus_repacketizer_get_nb_frames()).
    @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the
                                   complete output packet.

  Return the total number of frames contained in packet data submitted to
    the repacketizer state so far via opus_repacketizer_cat() since the last
    call to opus_repacketizer_init() or opus_repacketizer_create().
    This defines the valid range of packets that can be extracted with
    opus_repacketizer_out_range() or opus_repacketizer_out().
    @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state containing the
                                          frames.
    @returns The total number of frames contained in the packet data submitted
             to the repacketizer state.

  Construct a new packet from data previously submitted to the repacketizer
    state via opus_repacketizer_cat().
    This is a convenience routine that returns all the data submitted so far
    in a single packet.
    It is equivalent to calling
    @code
    opus_repacketizer_out_range(rp, 0, opus_repacketizer_get_nb_frames(rp),
                                data, maxlen)
    @endcode
    @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to
                                          construct the new packet.
    @param[out] data <tt>const unsigned char*</tt>: The buffer in which to
                                                    store the output packet.
    @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in
                                       the output buffer. In order to guarantee
                                       success, this should be at least
                                       <code>1277*opus_repacketizer_get_nb_frames(rp)</code>.
                                       However,
                                       <code>1*opus_repacketizer_get_nb_frames(rp)</code>
                                       plus the size of all packet data
                                       submitted to the repacketizer since the
                                       last call to opus_repacketizer_init() or
                                       opus_repacketizer_create() is also
                                       sufficient, and possibly much smaller.
    @returns The total size of the output packet on success, or an error code
             on failure.
    @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the
                                   complete output packet.

  Pads a given Opus packet to a larger size (possibly changing the TOC sequence).
    @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the
                                                      packet to pad.
    @param len <tt>opus_int32</tt>: The size of the packet.
                                    This must be at least 1.
    @param new_len <tt>opus_int32</tt>: The desired size of the packet after padding.
                                    This must be at least as large as len.
    @returns an error code
    @retval #OPUS_OK \a on success.
    @retval #OPUS_BAD_ARG \a len was less than 1 or new_len was less than len.
    @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet.

  Remove all padding from a given Opus packet and rewrite the TOC sequence to
    minimize space usage.
    @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the
                                                      packet to strip.
    @param len <tt>opus_int32</tt>: The size of the packet.
                                    This must be at least 1.
    @returns The new size of the output packet on success, or an error code
             on failure.
    @retval #OPUS_BAD_ARG \a len was less than 1.
    @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet.

  Pads a given Opus multi-stream packet to a larger size (possibly changing the TOC sequence).
    @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the
                                                      packet to pad.
    @param len <tt>opus_int32</tt>: The size of the packet.
                                    This must be at least 1.
    @param new_len <tt>opus_int32</tt>: The desired size of the packet after padding.
                                    This must be at least 1.
    @param nb_streams <tt>opus_int32</tt>: The number of streams (not channels) in the packet.
                                    This must be at least as large as len.
    @returns an error code
    @retval #OPUS_OK \a on success.
    @retval #OPUS_BAD_ARG \a len was less than 1.
    @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet.

  Remove all padding from a given Opus multi-stream packet and rewrite the TOC sequence to
    minimize space usage.
    @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the
                                                      packet to strip.
    @param len <tt>opus_int32</tt>: The size of the packet.
                                    This must be at least 1.
    @param nb_streams <tt>opus_int32</tt>: The number of streams (not channels) in the packet.
                                    This must be at least 1.
    @returns The new size of the output packet on success, or an error code
             on failure.
    @retval #OPUS_BAD_ARG \a len was less than 1 or new_len was less than len.
    @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet.