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
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
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.
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
Decode a multistream Opus packet.
@param st OpusMSDecoder*: Multistream decoder state.
@param[in] data const unsigned char*: Input payload.
Use a NULL
pointer to indicate packet
loss.
@param len opus_int32: Number of bytes in payload.
@param[out] pcm opus_int16*: Output signal, with interleaved
samples.
This must contain room for
frame_size*channels
samples.
@param frame_size int: The number of samples per channel of
available space in \a pcm.
If this is less than the maximum packet duration
(120 ms; 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 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 samples decoded on success or a negative error code
(see @ref opus_errorcodes) on failure.
Decode a multistream Opus packet with floating point output.
@param st OpusMSDecoder*: Multistream decoder state.
@param[in] data const unsigned char*: Input payload.
Use a NULL
pointer to indicate packet
loss.
@param len opus_int32: Number of bytes in payload.
@param[out] pcm opus_int16*: Output signal, with interleaved
samples.
This must contain room for
frame_size*channels
samples.
@param frame_size int: The number of samples per channel of
available space in \a pcm.
If this is less than the maximum packet duration
(120 ms; 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 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 samples decoded on success or a negative error code
(see @ref opus_errorcodes) on failure.
Allocates and initializes a multistream decoder state.
Call opus_multistream_decoder_destroy() to release
this object when finished.
@param Fs opus_int32: Sampling rate to decode at (in Hz).
This must be one of 8000, 12000, 16000,
24000, or 48000.
@param channels int: Number of channels to output.
This must be at most 255.
It may be different from the number of coded
channels (streams +
coupled_streams).
@param streams int: The total number of streams coded in the
input.
This must be no more than 255.
@param coupled_streams int: Number of streams to decode as coupled
(2 channel) streams.
This must be no larger than the total
number of streams.
Additionally, The total number of
coded channels (streams +
coupled_streams) must be no
more than 255.
@param[in] mapping const unsigned char[channels]: Mapping from
coded channels to output channels, as described in
@ref opus_multistream.
@param[out] error int *: Returns #OPUS_OK on success, or an error
code (see @ref opus_errorcodes) on
failure.
Gets the size of an OpusMSDecoder structure.
@param streams int: The total number of streams coded in the
input.
This must be no more than 255.
@param coupled_streams int: Number streams to decode as coupled
(2 channel) streams.
This must be no larger than the total
number of streams.
Additionally, The total number of
coded channels (streams +
coupled_streams) must be no
more than 255.
@returns The size in bytes on success, or a negative error code
(see @ref opus_errorcodes) on error.
Intialize a previously allocated decoder state object.
The memory pointed to by \a st must be at least the size returned by
opus_multistream_encoder_get_size().
This is intended for applications which use their own allocator instead of
malloc.
To reset a previously initialized state, use the #OPUS_RESET_STATE CTL.
@see opus_multistream_decoder_create
@see opus_multistream_deocder_get_size
@param st OpusMSEncoder*: Multistream encoder state to initialize.
@param Fs opus_int32: Sampling rate to decode at (in Hz).
This must be one of 8000, 12000, 16000,
24000, or 48000.
@param channels int: Number of channels to output.
This must be at most 255.
It may be different from the number of coded
channels (streams +
coupled_streams).
@param streams int: The total number of streams coded in the
input.
This must be no more than 255.
@param coupled_streams int: Number of streams to decode as coupled
(2 channel) streams.
This must be no larger than the total
number of streams.
Additionally, The total number of
coded channels (streams +
coupled_streams) must be no
more than 255.
@param[in] mapping const unsigned char[channels]: Mapping from
coded channels to output channels, as described in
@ref opus_multistream.
@returns #OPUS_OK on success, or an error code (see @ref opus_errorcodes)
on failure.
Encodes a multistream Opus frame.
@param st OpusMSEncoder*: Multistream encoder state.
@param[in] pcm const opus_int16*: The input signal as interleaved
samples.
This must contain
frame_sizechannels
samples.
@param 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 a multistream Opus frame from floating point input.
@param st OpusMSEncoder*: Multistream encoder state.
@param[in] pcm const float*: The input signal as interleaved
samples 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.
This must contain
frame_sizechannels
samples.
@param 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 a multistream encoder state.
Call opus_multistream_encoder_destroy() to release
this object when finished.
@param Fs opus_int32: Sampling rate of the input signal (in Hz).
This must be one of 8000, 12000, 16000,
24000, or 48000.
@param channels int: Number of channels in the input signal.
This must be at most 255.
It may be greater than the number of
coded channels (streams +
coupled_streams).
@param streams int: The total number of streams to encode from the
input.
This must be no more than the number of channels.
@param coupled_streams int: Number of coupled (2 channel) streams
to encode.
This must be no larger than the total
number of streams.
Additionally, The total number of
encoded channels (streams +
coupled_streams) must be no
more than the number of input channels.
@param[in] mapping const unsigned char[channels]: Mapping from
encoded channels to input channels, as described in
@ref opus_multistream. As an extra constraint, the
multistream encoder does not allow encoding coupled
streams for which one channel is unused since this
is never a good idea.
@param application int: The target encoder application.
This must be one of the following:
Gets the size of an OpusMSEncoder structure.
@param streams int: The total number of streams to encode from the
input.
This must be no more than 255.
@param coupled_streams int: Number of coupled (2 channel) streams
to encode.
This must be no larger than the total
number of streams.
Additionally, The total number of
encoded channels (streams +
coupled_streams) must be no
more than 255.
@returns The size in bytes on success, or a negative error code
(see @ref opus_errorcodes) on error.
Initialize a previously allocated multistream encoder state.
The memory pointed to by \a st must be at least the size returned by
opus_multistream_encoder_get_size().
This is intended for applications which use their own allocator instead of
malloc.
To reset a previously initialized state, use the #OPUS_RESET_STATE CTL.
@see opus_multistream_encoder_create
@see opus_multistream_encoder_get_size
@param st OpusMSEncoder*: Multistream encoder state to initialize.
@param Fs opus_int32: Sampling rate of the input signal (in Hz).
This must be one of 8000, 12000, 16000,
24000, or 48000.
@param channels int: Number of channels in the input signal.
This must be at most 255.
It may be greater than the number of
coded channels (streams +
coupled_streams).
@param streams int: The total number of streams to encode from the
input.
This must be no more than the number of channels.
@param coupled_streams int: Number of coupled (2 channel) streams
to encode.
This must be no larger than the total
number of streams.
Additionally, The total number of
encoded channels (streams +
coupled_streams) must be no
more than the number of input channels.
@param[in] mapping const unsigned char[channels]: Mapping from
encoded channels to input channels, as described in
@ref opus_multistream. As an extra constraint, the
multistream encoder does not allow encoding coupled
streams for which one channel is unused since this
is never a good idea.
@param application int: The target encoder application.
This must be one of the following:
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.
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.
(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.