opus.h   opus.h 
/* Copyright (c) 2010 Xiph.Org Foundation /* Copyright (c) 2010-2011 Xiph.Org Foundation, Skype Limited
Written by Jean-Marc Valin */ Written by Jean-Marc Valin and Koen Vos */
/* /*
Redistribution and use in source and binary forms, with or without Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions modification, are permitted provided that the following conditions
are met: are met:
- Redistributions of source code must retain the above copyright - Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer. notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright - Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the notice, this list of conditions and the following disclaimer in the
skipping to change at line 28 skipping to change at line 28
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION O R A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION O R
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/ */
/**
* @file opus.h
* @brief Opus reference implementation API
*/
#ifndef OPUS_H #ifndef OPUS_H
#define OPUS_H #define OPUS_H
#include "opus_types.h" #include "opus_types.h"
#include "opus_defines.h"
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
#if defined(__GNUC__) && defined(OPUS_BUILD) /**
#define OPUS_EXPORT __attribute__ ((visibility ("default"))) * @mainpage Opus
#elif defined(WIN32) *
#define OPUS_EXPORT __declspec(dllexport) * The Opus codec is designed for interactive speech and audio transmission
#else over the Internet.
#define OPUS_EXPORT * It is designed by the IETF Codec Working Group and incorporates technolo
#endif gy from
* Skype's SILK codec and Xiph.Org's CELT codec.
#define __check_int(x) (((void)((x) == (int)0)), (int)(x)) *
#define __check_int_ptr(ptr) ((ptr) + ((ptr) - (int*)(ptr))) * The Opus codec is designed to handle a wide range of interactive audio a
pplications,
* including Voice over IP, videoconferencing, in-game chat, and even remot
e live music
* performances. It can scale from low bit-rate narrowband speech to very h
igh quality
* stereo music. Its main features are:
* @li Sampling rates from 8 to 48 kHz
* @li Bit-rates from 6 kb/s 510 kb/s
* @li Support for both constant bit-rate (CBR) and variable bit-rate (VBR)
* @li Audio bandwidth from narrowband to full-band
* @li Support for speech and music
* @li Support for mono and stereo
* @li Frame sizes from 2.5 ms to 60 ms
* @li Good loss robustness and packet loss concealment (PLC)
* @li Floating point and fixed-point implementation
*
* Documentation sections:
* @li @ref opusencoder
* @li @ref opusdecoder
* @li @ref repacketizer
* @li @ref libinfo
*/
/* Error codes */ /** @defgroup opusencoder Opus Encoder
/** No error */ * @{
#define OPUS_OK 0 *
/** An (or more) invalid argument (e.g. out of range) */ * Since Opus is a stateful codec, the encoding process starts with creati
#define OPUS_BAD_ARG -1 ng an encoder
/** The mode struct passed is invalid */ * state. This can be done with:
#define OPUS_BUFFER_TOO_SMALL -2 *
/** An internal error was detected */ * @code
#define OPUS_INTERNAL_ERROR -3 * int error;
/** The data passed (e.g. compressed data to decoder) is corrupted */ * OpusEncoder *enc;
#define OPUS_CORRUPTED_DATA -4 * enc = opus_encoder_create(Fs, channels, application, &error);
/** Invalid/unsupported request number */ * @endcode
#define OPUS_UNIMPLEMENTED -5 *
/** An encoder or decoder structure is invalid or already freed */ * From this point, @c enc can be used for encoding an audio stream. An en
#define OPUS_INVALID_STATE -6 coder state
/** Memory allocation has failed */ * @b must @b not be used for more than one stream at the same time. Simil
#define OPUS_ALLOC_FAIL -7 arly, the encoder
* state @b must @b not be re-initialized for each frame.
#define OPUS_BITRATE_AUTO -1 *
* While opus_encoder_create() allocates memory for the state, it's also p
#define OPUS_APPLICATION_VOIP 2000 ossible
#define OPUS_APPLICATION_AUDIO 2001 * to initialize pre-allocated memory:
*
#define OPUS_SIGNAL_AUTO 3000 * @code
#define OPUS_SIGNAL_VOICE 3001 * int size;
#define OPUS_SIGNAL_MUSIC 3002 * int error;
* OpusEncoder *enc;
#define MODE_SILK_ONLY 1000 * size = opus_encoder_get_size(channels);
#define MODE_HYBRID 1001 * enc = malloc(size);
#define MODE_CELT_ONLY 1002 * error = opus_encoder_init(enc, Fs, channels, application);
* @endcode
#define OPUS_BANDWIDTH_AUTO 1100 *
#define OPUS_BANDWIDTH_NARROWBAND 1101 * where opus_encoder_get_size() returns the required size for the encoder
#define OPUS_BANDWIDTH_MEDIUMBAND 1102 state. Note that
#define OPUS_BANDWIDTH_WIDEBAND 1103 * future versions of this code may change the size, so no assuptions shou
#define OPUS_BANDWIDTH_SUPERWIDEBAND 1104 ld be made about it.
#define OPUS_BANDWIDTH_FULLBAND 1105 *
* The encoder state is always continuous in memory and only a shallow cop
#define OPUS_SET_MODE_REQUEST 0 y is sufficient
#define OPUS_SET_MODE(x) OPUS_SET_MODE_REQUEST, __check_int(x) * to copy it (e.g. memcpy())
#define OPUS_GET_MODE_REQUEST 1 *
#define OPUS_GET_MODE(x) OPUS_GET_MODE_REQUEST, __check_int_ptr(x) * It is possible to change some of the encoder's settings using the opus_
encoder_ctl()
#define OPUS_SET_BITRATE_REQUEST 2 * interface. All these settings already default to the recommended value,
#define OPUS_SET_BITRATE(x) OPUS_SET_BITRATE_REQUEST, __check_int(x) so they should
#define OPUS_GET_BITRATE_REQUEST 3 * only be changed when necessary. The most common settings one may want t
#define OPUS_GET_BITRATE(x) OPUS_GET_BITRATE_REQUEST, __check_int_ptr(x) o change are:
*
#define OPUS_SET_VBR_FLAG_REQUEST 6 * @code
#define OPUS_SET_VBR_FLAG(x) OPUS_SET_VBR_FLAG_REQUEST, __check_int(x) * opus_encoder_ctl(enc, OPUS_SET_BITRATE(bitrate));
#define OPUS_GET_VBR_FLAG_REQUEST 7 * opus_encoder_ctl(enc, OPUS_SET_COMPLEXITY(complexity));
#define OPUS_GET_VBR_FLAG(x) OPUS_GET_VBR_FLAG_REQUEST, __check_int_ptr(x) * opus_encoder_ctl(enc, OPUS_SET_SIGNAL(signal_type));
* @endcode
#define OPUS_SET_BANDWIDTH_REQUEST 8 *
#define OPUS_SET_BANDWIDTH(x) OPUS_SET_BANDWIDTH_REQUEST, __check_int(x) * where
#define OPUS_GET_BANDWIDTH_REQUEST 9 *
#define OPUS_GET_BANDWIDTH(x) OPUS_GET_BANDWIDTH_REQUEST, __check_int_ptr(x * @arg bitrate is in bits per second (b/s)
) * @arg complexity is a value from 1 to 10, where 1 is the lowest complexi
ty and 10 is the highest
#define OPUS_SET_COMPLEXITY_REQUEST 10 * @arg signal_type is either OPUS_AUTO (default), OPUS_SIGNAL_VOICE, or O
#define OPUS_SET_COMPLEXITY(x) OPUS_SET_COMPLEXITY_REQUEST, __check_int(x) PUS_SIGNAL_MUSIC
#define OPUS_GET_COMPLEXITY_REQUEST 11 *
#define OPUS_GET_COMPLEXITY(x) OPUS_GET_COMPLEXITY_REQUEST, __check_int_ptr * See @ref encoderctls and @ref genericctls for a complete list of parame
(x) ters that can be set or queried. Most parameters can be set or changed at a
ny time during a stream.
#define OPUS_SET_INBAND_FEC_FLAG_REQUEST 12 *
#define OPUS_SET_INBAND_FEC_FLAG(x) OPUS_SET_INBAND_FEC_FLAG_REQUEST, __che * To encode a frame, opus_encode() or opus_encode_float() must be called
ck_int(x) with exactly one frame (2.5, 5, 10, 20, 40 or 60 ms) of audio data:
#define OPUS_GET_INBAND_FEC_FLAG_REQUEST 13 * @code
#define OPUS_GET_INBAND_FEC_FLAG(x) OPUS_GET_INBAND_FEC_FLAG_REQUEST, __che * len = opus_encode(enc, audio_frame, frame_size, packet, max_packet);
ck_int_ptr(x) * @endcode
*
#define OPUS_SET_PACKET_LOSS_PERC_REQUEST 14 * where
#define OPUS_SET_PACKET_LOSS_PERC(x) OPUS_SET_PACKET_LOSS_PERC_REQUEST, __c * <ul>
heck_int(x) * <li>audio_frame is the audio data in opus_int16 (or float for opus_enco
#define OPUS_GET_PACKET_LOSS_PERC_REQUEST 15 de_float())</li>
#define OPUS_GET_PACKET_LOSS_PERC(x) OPUS_GET_PACKET_LOSS_PERC_REQUEST, __c * <li>frame_size is the duration of the frame in samples (per channel)</l
heck_int_ptr(x) i>
* <li>packet is the byte array to which the compressed data is written</l
#define OPUS_SET_DTX_FLAG_REQUEST 16 i>
#define OPUS_SET_DTX_FLAG(x) OPUS_SET_DTX_FLAG_REQUEST, __check_int(x) * <li>max_packet is the maximum number of bytes that can be written in th
#define OPUS_GET_DTX_FLAG_REQUEST 17 e packet (1276 bytes is recommended)</li>
#define OPUS_GET_DTX_FLAG(x) OPUS_GET_DTX_FLAG_REQUEST, __check_int_ptr(x) * </ul>
*
#define OPUS_SET_VOICE_RATIO_REQUEST 18 * opus_encode() and opus_encode_frame() return the number of bytes actual
#define OPUS_SET_VOICE_RATIO(x) OPUS_SET_VOICE_RATIO_REQUEST, __check_int(x ly written to the packet.
) * The return value <b>can be negative</b>, which indicates that an error
#define OPUS_GET_VOICE_RATIO_REQUEST 19 has occurred. If the return value
#define OPUS_GET_VOICE_RATIO(x) OPUS_GET_VOICE_RATIO_REQUEST, __check_int_p * is 1 byte, then the packet does not need to be transmitted (DTX).
tr(x) *
* Once the encoder state if no longer needed, it can be destroyed with
#define OPUS_SET_VBR_CONSTRAINT_REQUEST 20 *
#define OPUS_SET_VBR_CONSTRAINT(x) OPUS_SET_VBR_CONSTRAINT_REQUEST, __check * @code
_int(x) * opus_encoder_destroy(enc);
#define OPUS_GET_VBR_CONSTRAINT_REQUEST 21 * @endcode
#define OPUS_GET_VBR_CONSTRAINT(x) OPUS_GET_VBR_CONSTRAINT_REQUEST, __check *
_int_ptr(x) * If the encoder was created with opus_encoder_init() rather than opus_en
coder_create(),
#define OPUS_SET_FORCE_MONO_REQUEST 22 * then no action is required aside from potentially freeing the memory th
#define OPUS_SET_FORCE_MONO(x) OPUS_SET_FORCE_MONO_REQUEST, __check_int(x) at was manually
#define OPUS_GET_FORCE_MONO_REQUEST 23 * allocated for it (calling free(enc) for the example above)
#define OPUS_GET_FORCE_MONO(x) OPUS_GET_FORCE_MONO_REQUEST, __check_int_ptr *
(x) */
#define OPUS_SET_SIGNAL_REQUEST 24 /** Opus encoder state.
#define OPUS_SET_SIGNAL(x) OPUS_SET_SIGNAL_REQUEST, __check_int(x) * This contains the complete state of an Opus encoder.
#define OPUS_GET_SIGNAL_REQUEST 25 * It is position independent and can be freely copied.
#define OPUS_GET_SIGNAL(x) OPUS_GET_SIGNAL_REQUEST, __check_int_ptr(x) * @see opus_encoder_create,opus_encoder_init
*/
typedef struct OpusEncoder OpusEncoder;
#define OPUS_GET_LOOKAHEAD_REQUEST 27 OPUS_EXPORT int opus_encoder_get_size(int channels);
#define OPUS_GET_LOOKAHEAD(x) OPUS_GET_LOOKAHEAD_REQUEST, __check_int_ptr(x
)
typedef struct OpusEncoder OpusEncoder; /**
typedef struct OpusDecoder OpusDecoder; */
/* /** Allocates and initializes an encoder state.
* There are two coding modes: * There are three coding modes:
* OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voice *
* @ref OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voi
ce
* signals. It enhances the input signal by high-pass filtering and * signals. It enhances the input signal by high-pass filtering and
* emphasizing formants and harmonics. Optionally it includes in-band * emphasizing formants and harmonics. Optionally it includes in-band
* forward error correction to protect against packet loss. Use this * forward error correction to protect against packet loss. Use this
* mode for typical VoIP applications. Because of the enhancement, * mode for typical VoIP applications. Because of the enhancement,
* even at high bitrates the output may sound different from the input. * even at high bitrates the output may sound different from the input.
* OPUS_APPLICATION_AUDIO gives best quality at a given bitrate for most *
* @ref OPUS_APPLICATION_AUDIO gives best quality at a given bitrate for mo
st
* non-voice signals like music. Use this mode for music and mixed * non-voice signals like music. Use this mode for music and mixed
* (music/voice) content, broadcast, and applications requiring less * (music/voice) content, broadcast, and applications requiring less
* than 15 ms of coding delay. * 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 d
elay.
*
* This is useful when the caller knows that the speech-optimized modes wil
l not be needed (use with caution).
* @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
* @param [in] channels <tt>int</tt>: Number of channels (1/2) in input sig
nal
* @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 errorcodes
* @note Regardless of the sampling rate and number channels selected, the
Opus encoder
* can switch to a lower audio audio bandwidth or number of channels if the
bitrate
* selected is too low. This also means that it is safe to always use 48 kH
z stereo input
* and let the encoder optimize the encoding.
*/ */
/* Returns initialized encoder state */
OPUS_EXPORT OpusEncoder *opus_encoder_create( OPUS_EXPORT OpusEncoder *opus_encoder_create(
int Fs, /* Sampling rate of input signal (Hz) */ opus_int32 Fs,
int channels, /* Number of channels (1/2) in input signal int channels,
*/ int application,
int application /* Coding mode (OPUS_APPLICATION_VOIP/OPUS_ int *error
APPLICATION_AUDIO) */
); );
OPUS_EXPORT OpusEncoder *opus_encoder_init( /** Initializes a previously allocated encoder state
OpusEncoder *st, /* Encoder state */ * The memory pointed to by st must be the size returned by opus_encoder_g
int Fs, /* Sampling rate of input signal (Hz) */ et_size.
int channels, /* Number of channels (1/2) in input signal * This is intended for applications which use their own allocator instead
*/ of malloc.
int application /* Coding mode (OPUS_APPLICATION_VOIP/OPUS_ * @see opus_encoder_create(),opus_encoder_get_size()
APPLICATION_AUDIO) */ * 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)
* @param [in] channels <tt>int</tt>: Number of channels (1/2) in input si
gnal
* @param [in] application <tt>int</tt>: Coding mode (OPUS_APPLICATION_VOI
P/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)
* @retval OPUS_OK Success or @ref errorcodes
*/
OPUS_EXPORT int opus_encoder_init(
OpusEncoder *st,
opus_int32 Fs,
int channels,
int application
); );
/* Returns length of the data payload (in bytes) */ /** Encodes an Opus frame.
* The passed frame_size must an opus frame size for the encoder's samplin
g rate.
* For example, at 48kHz the permitted values are 120, 240, 480, or 960.
* Passing in a duration of less than 10ms (480 samples at 48kHz) will
* prevent the encoder from using the LPC or hybrid modes.
* @param [in] st <tt>OpusEncoder*</tt>: Encoder state
* @param [in] pcm <tt>opus_int16*</tt>: Input signal (interleaved if 2 ch
annels). length is frame_size*channels*sizeof(opus_int16)
* @param [in] frame_size <tt>int</tt>: Number of samples per frame of inp
ut signal
* @param [out] data <tt>char*</tt>: Output payload (at least max_data_byt
es long)
* @param [in] max_data_bytes <tt>int</tt>: Allocated memory for payload;
don't use for controlling bitrate
* @returns length of the data payload (in bytes) or @ref errorcodes
*/
OPUS_EXPORT int opus_encode( OPUS_EXPORT int opus_encode(
OpusEncoder *st, /* Encoder state */ OpusEncoder *st,
const opus_int16 *pcm, /* Input signal (interleaved if 2 channels) const opus_int16 *pcm,
. length is frame_size*channels */ int frame_size,
int frame_size, /* Number of samples per frame of input sig unsigned char *data,
nal */ int max_data_bytes
unsigned char *data, /* Output payload (no more than max_data_by
tes long) */
int max_data_bytes /* Allocated memory for payload; don't use
for controlling bitrate */
); );
/** Encodes an Opus frame from floating point input.
* The passed frame_size must an opus frame size for the encoder's samplin
g rate.
* For example, at 48kHz the permitted values are 120, 240, 480, or 960.
* Passing in a duration of less than 10ms (480 samples at 48kHz) will
* prevent the encoder from using the LPC or hybrid modes.
* @param [in] st <tt>OpusEncoder*</tt>: Encoder state
* @param [in] pcm <tt>float*</tt>: Input signal (interleaved if 2 channel
s). length is frame_size*channels*sizeof(float)
* @param [in] frame_size <tt>int</tt>: Number of samples per frame of inp
ut signal
* @param [out] data <tt>char*</tt>: Output payload (at least max_data_byt
es long)
* @param [in] max_data_bytes <tt>int</tt>: Allocated memory for payload;
don't use for controlling bitrate
* @returns length of the data payload (in bytes) or @ref errorcodes
*/
OPUS_EXPORT int opus_encode_float(
OpusEncoder *st,
const float *pcm,
int frame_size,
unsigned char *data,
int max_data_bytes
);
/** Frees an OpusEncoder allocated by opus_encoder_create.
* @param[in] st <tt>OpusEncoder*</tt>: State to be freed.
*/
OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st); OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st);
/** Perform a CTL function on an Opus encoder.
* @see encoderctls
*/
OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...); OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...);
/**@}*/
/** @defgroup opusdecoder Opus Decoder
* @{
*
*
* The decoding process also starts with creating a decoder
* state. This can be done with:
* @code
* int error;
* OpusDecoder *dec;
* dec = opus_decoder_create(Fs, channels, &error);
* @endcode
* where
* @li Fs is the sampling rate and must be 8000, 12000, 16000, 24000, or 4
8000
* @li channels is the number of channels (1 or 2)
* @li error will hold the error code in case or failure (or OPUS_OK on su
ccess)
* @li the return value is a newly created decoder state to be used for de
coding
*
* While opus_decoder_create() allocates memory for the state, it's also p
ossible
* to initialize pre-allocated memory:
* @code
* int size;
* int error;
* OpusDecoder *dec;
* size = opus_decoder_get_size(channels);
* dec = malloc(size);
* error = opus_decoder_init(dec, Fs, channels);
* @endcode
* where opus_decoder_get_size() returns the required size for the decoder
state. Note that
* future versions of this code may change the size, so no assuptions shou
ld be made about it.
*
* The decoder state is always continuous in memory and only a shallow cop
y is sufficient
* to copy it (e.g. memcpy())
*
* To decode a frame, opus_decode() or opus_decode_float() must be called
with a packet of compressed audio data:
* @code
* frame_size = opus_decode(enc, packet, len, decoded, max_size);
* @endcode
* where
*
* @li packet is the byte array containing the compressed data
* @li len is the exact number of bytes contained in the packet
* @li decoded is the decoded audio data in opus_int16 (or float for opus_
decode_float())
* @li max_size is the max duration of the frame in samples (per channel)
that can fit into the decoded_frame array
*
* opus_decode() and opus_decode_frame() return the number of samples ()pe
r channel) decoded from the packet.
* If that value is negative, then an error has occured. This can occur if
the packet is corrupted or if the audio
* buffer is too small to hold the decoded audio.
*/
/** Opus decoder state.
* This contains the complete state of an Opus decoder.
* It is position independent and can be freely copied.
* @see opus_decoder_create,opus_decoder_init
*/
typedef struct OpusDecoder OpusDecoder;
/** Gets the size of an OpusDecoder structure.
* @param [in] channels <tt>int</tt>: Number of channels
* @returns size
*/
OPUS_EXPORT int opus_decoder_get_size(int channels);
/** Allocates and initializes a decoder state.
* @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
* @param [in] channels <tt>int</tt>: Number of channels (1/2) in input si
gnal
* @param [out] error <tt>int*</tt>: OPUS_OK Success or @ref errorcodes
*/
OPUS_EXPORT OpusDecoder *opus_decoder_create( OPUS_EXPORT OpusDecoder *opus_decoder_create(
int Fs, /* Sampling rate of output signal (Hz) */ opus_int32 Fs,
int channels /* Number of channels (1/2) in output signa int channels,
l */ int *error
); );
OPUS_EXPORT OpusDecoder *opus_decoder_init(OpusDecoder *st, /** Initializes a previously allocated decoder state.
int Fs, /* Sampling rate of output signal (Hz) */ * The state must be the size returned by opus_decoder_get_size.
int channels /* Number of channels (1/2) in output signa * This is intended for applications which use their own allocator instead
l */ 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 of input signal (Hz)
* @param [in] channels <tt>int</tt>: Number of channels (1/2) in input si
gnal
* @retval OPUS_OK Success or @ref errorcodes
*/
OPUS_EXPORT int opus_decoder_init(
OpusDecoder *st,
opus_int32 Fs,
int channels
); );
/* Returns the number of samples decoded or a negative error code */ /** Decode an Opus frame
* @param [in] st <tt>OpusDecoder*</tt>: Decoder state
* @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to i
ndicate packet loss
* @param [in] len <tt>int</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 *pcm,
* if less than the maximum frame size (120ms) some frames can not be dec
oded
* @param [in] decode_fec <tt>int</tt>: Flag (0/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 we
re lost.
* @returns Number of decoded samples or @ref errorcodes
*/
OPUS_EXPORT int opus_decode( OPUS_EXPORT int opus_decode(
OpusDecoder *st, /* Decoder state */ OpusDecoder *st,
const unsigned char *data, /* Input payload. Use a NULL pointer to ind const unsigned char *data,
icate packet loss */ int len,
int len, /* Number of bytes in payload */ opus_int16 *pcm,
opus_int16 *pcm, /* Output signal (interleaved if 2 channels int frame_size,
). length is frame_size*channels */ int decode_fec
int frame_size, /* Number of samples per frame of input sig
nal */
int decode_fec /* Flag (0/1) to request that any in-band f
orward error correction data be */
/* decoded. If no such data is available th
e frame is decoded as if it were lost. */
); );
/** Decode an opus frame 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 i
ndicate packet loss
* @param [in] len <tt>int</tt>: Number of bytes in payload
* @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 chann
els). length
* is frame_size*channels*sizeof(float)
* @param [in] frame_size Number of samples per channel of available space
in *pcm,
* if less than the maximum frame size (120ms) some frames can not be dec
oded
* @param [in] decode_fec <tt>int</tt>: Flag (0/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 we
re lost.
* @returns Number of decoded samples or @ref errorcodes
*/
OPUS_EXPORT int opus_decode_float(
OpusDecoder *st,
const unsigned char *data,
int len,
float *pcm,
int frame_size,
int decode_fec
);
/** Perform a CTL function on an Opus decoder.
* @see decoderctls
*/
OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...); OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...);
/** Frees an OpusDecoder allocated by opus_decoder_create.
* @param[in] st <tt>OpusDecoder*</tt>: State to be freed.
*/
OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st); OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st);
OPUS_EXPORT int opus_packet_parse(const unsigned char *data, int len, /** Parse an opus packet into one or more frames.
unsigned char *out_toc, const unsigned char *frames[48], * Opus_decode will perform this operation internally so most applications
short size[48], const unsigned char **payload); do
* not need to use this function.
* This function does not copy the frames, the returned pointers are point
ers into
* the input packet.
* @param [in] data <tt>char*</tt>: Opus packet to be parsed
* @param [in] len <tt>int</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>short[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
*/
OPUS_EXPORT int opus_packet_parse(
const unsigned char *data,
int len,
unsigned char *out_toc,
const unsigned char *frames[48],
short size[48],
int *payload_offset
);
/** 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
*/
OPUS_EXPORT int opus_packet_get_bandwidth(const unsigned char *data); OPUS_EXPORT int opus_packet_get_bandwidth(const unsigned char *data);
OPUS_EXPORT int opus_packet_get_samples_per_frame(const unsigned char *data
, int Fs); /** Gets the number of samples per frame from an Opus packet.
* @param [in] data <tt>char*</tt>: Opus packet
* @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz
* @returns Number of samples per frame
* @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or
of an unsupported type
*/
OPUS_EXPORT int opus_packet_get_samples_per_frame(const unsigned char *data
, opus_int32 Fs);
/** 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
*/
OPUS_EXPORT int opus_packet_get_nb_channels(const unsigned char *data); OPUS_EXPORT int opus_packet_get_nb_channels(const unsigned char *data);
OPUS_EXPORT int opus_packet_get_nb_frames(const unsigned char packet[], int
len);
OPUS_EXPORT int opus_decoder_get_nb_samples(const OpusDecoder *dec, const u
nsigned char packet[], int len);
OPUS_EXPORT const char *opus_strerror(int error); /** Gets the number of frame in an Opus packet.
* @param [in] packet <tt>char*</tt>: Opus packet
* @param [in] len <tt>int</tt>: Length of packet
* @returns Number of frames
* @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or
of an unsupported type
*/
OPUS_EXPORT int opus_packet_get_nb_frames(const unsigned char packet[], int
len);
OPUS_EXPORT const char *opus_get_version_string(void); /** 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>int</tt>: Length of packet
* @returns Number of samples
* @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or
of an unsupported type
*/
OPUS_EXPORT int opus_decoder_get_nb_samples(const OpusDecoder *dec, const u
nsigned char packet[], int len);
/**@}*/
/* For testing purposes: the encoder and decoder state should /** @defgroup repacketizer Repacketizer
always be identical after coding a payload */ * @{
OPUS_EXPORT int opus_encoder_get_final_range(OpusEncoder *st); *
OPUS_EXPORT int opus_decoder_get_final_range(OpusDecoder *st); * The repacketizer can be used to merge multiple Opus packets into a sing
le packet
* or alternatively to split Opus packets that have previously been merged
.
*
*/
/* Repacketizer */
typedef struct OpusRepacketizer OpusRepacketizer; typedef struct OpusRepacketizer OpusRepacketizer;
OPUS_EXPORT int opus_repacketizer_get_size(void); OPUS_EXPORT int opus_repacketizer_get_size(void);
OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp); OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp);
OPUS_EXPORT OpusRepacketizer *opus_repacketizer_create(void); OPUS_EXPORT OpusRepacketizer *opus_repacketizer_create(void);
OPUS_EXPORT void opus_repacketizer_destroy(OpusRepacketizer *rp); OPUS_EXPORT void opus_repacketizer_destroy(OpusRepacketizer *rp);
OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, int len); OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, int len);
OPUS_EXPORT int opus_repacketizer_out_range(OpusRepacketizer *rp, int begin , int end, unsigned char *data, int maxlen); OPUS_EXPORT opus_int32 opus_repacketizer_out_range(OpusRepacketizer *rp, in t begin, int end, unsigned char *data, int maxlen);
OPUS_EXPORT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp); OPUS_EXPORT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp);
OPUS_EXPORT int opus_repacketizer_out(OpusRepacketizer *rp, unsigned char * OPUS_EXPORT opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned
data, int maxlen); char *data, int maxlen);
/**@}*/
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
#endif /* OPUS_H */ #endif /* OPUS_H */
 End of changes. 35 change blocks. 
192 lines changed or deleted 502 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/