Decode an Opus packet.
@param [in] st OpusDecoder*: Decoder state
@param [in] data char*: Input payload. Use a NULL pointer to indicate packet loss
@param [in] len opus_int32: Number of bytes in payload*
@param [out] pcm opus_int16*: Output signal (interleaved if 2 channels). length
is frame_sizechannelssizeof(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 must be a multiple of 2.5 ms.
@param [in] decode_fec int: 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 OpusDecoder*: Decoder state
@param [in] data char*: Input payload. Use a NULL pointer to indicate packet loss
@param [in] len opus_int32: Number of bytes in payload
@param [out] pcm float*: Output signal (interleaved if 2 channels). length
is frame_sizechannelssizeof(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 must be a multiple of 2.5 ms.
@param [in] decode_fec int: 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
Allocates and initializes a decoder state.
@param [in] Fs opus_int32: Sample rate to decode at (Hz).
This must be one of 8000, 12000, 16000,
24000, or 48000.
@param [in] channels int: Number of channels (1 or 2) to decode
@param [out] error int*: #OPUS_OK Success or @ref opus_errorcodes
Perform a CTL function on an Opus decoder.
Frees an OpusDecoder allocated by opus_decoder_create().
@param[in] st OpusDecoder*: State to be freed.
Gets the number of samples of an Opus packet.
@param [in] dec OpusDecoder*: Decoder state
@param [in] packet char*: Opus packet
@param [in] len opus_int32: 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
Gets the size of an OpusDecoder structure.
@param [in] channels int: Number of channels.
This must be 1 or 2.
@returns The size in bytes.
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 OpusDecoder*: Decoder state.
@param [in] Fs opus_int32: Sampling rate to decode to (Hz).
This must be one of 8000, 12000, 16000,
24000, or 48000.
@param [in] channels int: Number of channels (1 or 2) to decode
@retval #OPUS_OK Success or @ref opus_errorcodes
Encodes an Opus frame.
@param [in] st OpusEncoder*: Encoder state
@param [in] pcm opus_int16*: Input signal (interleaved if 2 channels). length is frame_sizechannelssizeof(opus_int16)
@param [in] frame_size int: 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 unsigned char*: Output payload.
This must contain storage for at
least \a max_data_bytes.
@param [in] max_data_bytes opus_int32: 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 OpusEncoder*: Encoder state
@param [in] pcm float*: 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_sizechannelssizeof(float)
@param [in] frame_size int: 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 unsigned char*: Output payload.
This must contain storage for at
least \a max_data_bytes.
@param [in] max_data_bytes opus_int32: 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.
Allocates and initializes an encoder state.
There are three coding modes:
Perform a CTL function on an Opus encoder.
Frees an OpusEncoder allocated by opus_encoder_create().
@param[in] st OpusEncoder*: State to be freed.
Gets the size of an OpusEncoder structure.
@param[in] channels int: Number of channels.
This must be 1 or 2.
@returns The size in bytes.
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 OpusEncoder*: Encoder state
@param [in] Fs opus_int32: Sampling rate of input signal (Hz)
This must be one of 8000, 12000, 16000,
24000, or 48000.
@param [in] channels int: Number of channels (1 or 2) in input signal
@param [in] application int: Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)
@retval #OPUS_OK Success or @ref opus_errorcodes
Gets the libopus version string.
Pads a given Opus multi-stream packet to a larger size (possibly changing the TOC sequence).
@param[in,out] data const unsigned char*: The buffer containing the
packet to pad.
@param len opus_int32: The size of the packet.
This must be at least 1.
@param new_len opus_int32: The desired size of the packet after padding.
This must be at least 1.
@param nb_streams opus_int32: 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 const unsigned char*: The buffer containing the
packet to strip.
@param len opus_int32: The size of the packet.
This must be at least 1.
@param nb_streams opus_int32: 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.
Gets the bandwidth of an Opus packet.
@param [in] data char*: 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 channels from an Opus packet.
@param [in] data char*: 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 char*: Opus packet
@param [in] len opus_int32: 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 char*: Opus packet
@param [in] len opus_int32: Length of packet
@param [in] Fs opus_int32: 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 per frame from an Opus packet.
@param [in] data char*: Opus packet.
This must contain at least one byte of
data.
@param [in] Fs opus_int32: Sampling rate in Hz.
This must be a multiple of 400, or
inaccurate results will be returned.
@returns Number of samples per frame.
Pads a given Opus packet to a larger size (possibly changing the TOC sequence).
@param[in,out] data const unsigned char*: The buffer containing the
packet to pad.
@param len opus_int32: The size of the packet.
This must be at least 1.
@param new_len opus_int32: 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.
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 char*: Opus packet to be parsed
@param [in] len opus_int32: size of data
@param [out] out_toc char*: TOC pointer
@param [out] frames char*[48] encapsulated frames
@param [out] size opus_int16[48] sizes of the encapsulated frames
@param [out] payload_offset int*: returns the position of the payload within the packet (in bytes)
@returns number of frames
Remove all padding from a given Opus packet and rewrite the TOC sequence to
minimize space usage.
@param[in,out] data const unsigned char*: The buffer containing the
packet to strip.
@param len opus_int32: 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.
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 float*: Input PCM and modified PCM
@param [in] frame_size int Number of samples per channel to process
@param [in] channels int: Number of channels
@param [in,out] softclip_mem float*: State memory for the soft clipping process (one float per channel, initialized to zero)
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.
Allocates memory and initializes the new repacketizer with
opus_repacketizer_init().
Frees an OpusRepacketizer allocated by
opus_repacketizer_create().
@param[in] rp OpusRepacketizer*: State to be freed.
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 OpusRepacketizer*: The repacketizer state containing the
frames.
@returns The total number of frames contained in the packet data submitted
to the repacketizer state.
Gets the size of an OpusRepacketizer 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 OpusRepacketizer*: The repacketizer state to
(re)initialize.
@returns A pointer to the same repacketizer state that was passed in.
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 OpusRepacketizer*: The repacketizer state from which to
construct the new packet.
@param[out] data const unsigned char*: The buffer in which to
store the output packet.
@param maxlen opus_int32: The maximum number of bytes to store in
the output buffer. In order to guarantee
success, this should be at least
1277opus_repacketizer_get_nb_frames(rp).
However,
1opus_repacketizer_get_nb_frames(rp)
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.
Construct a new packet from data previously submitted to the repacketizer
state via opus_repacketizer_cat().
@param rp OpusRepacketizer*: The repacketizer state from which to
construct the new packet.
@param begin int: The index of the first frame in the current
repacketizer state to include in the output.
@param end int: One past the index of the last frame in the
current repacketizer state to include in the
output.
@param[out] data const unsigned char*: The buffer in which to
store the output packet.
@param maxlen opus_int32: The maximum number of bytes to store in
the output buffer. In order to guarantee
success, this should be at least
1276 for a single frame,
or for multiple frames,
1277*(end-begin).
However, 1*(end-begin) 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 [begin,end) 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.
Converts an opus error code into a human readable string.