AIROC™ BTSDK v4.9 - Documentation | ||||
This page describes the process and functions used to decode Opus. More...
Data Structures | |
struct | StereoWidthState |
struct | OpusEncoder |
Modules | |
Decoder related CTLs | |
Macros | |
#define | MAX_ENCODER_BUFFER 480 |
Typedefs | |
typedef struct OpusDecoder | OpusDecoder |
Opus decoder state. More... | |
Functions | |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int | celt_opus_decoder_get_size (int channels) |
Gets the size of an OpusDecoder structure. More... | |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusDecoder * | celt_opus_decoder_create (int Fs, int channels, int *error) |
Allocates and initializes a decoder state. More... | |
OPUS_EXPORT int | celt_opus_decoder_init (OpusDecoder *st, int Fs, int channels) OPUS_ARG_NONNULL(1) |
Initializes a previously allocated decoder state. More... | |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int | celt_opus_decode (OpusDecoder *st, const unsigned char *data, int len, opus_int16 *pcm, int frame_size, int decode_fec) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4) |
Decode an Opus packet. More... | |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int | opus_decode_float (OpusDecoder *st, const unsigned char *data, int len, float *pcm, int frame_size, int decode_fec) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4) |
Decode an Opus packet with floating point output. More... | |
OPUS_EXPORT int | celt_opus_decoder_ctl (OpusDecoder *st, int request,...) OPUS_ARG_NONNULL(1) |
Perform a CTL function on an Opus decoder. More... | |
OPUS_EXPORT void | celt_opus_decoder_destroy (OpusDecoder *st) |
Frees an OpusDecoder allocated by celt_opus_decoder_create(). More... | |
OPUS_EXPORT int | celt_opus_packet_parse (const unsigned char *data, int len, unsigned char *out_toc, const unsigned char *frames[48], opus_int16 size[48], int *payload_offset) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4) |
Parse an opus packet into one or more frames. More... | |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int | celt_opus_packet_get_bandwidth (const unsigned char *data) OPUS_ARG_NONNULL(1) |
Gets the bandwidth of an Opus packet. More... | |
int | celt_opus_packet_get_samples_per_frame (const unsigned char *data, int Fs) OPUS_ARG_NONNULL(1) |
Gets the number of samples per frame from an Opus packet. More... | |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int | celt_opus_packet_get_nb_channels (const unsigned char *data) OPUS_ARG_NONNULL(1) |
Gets the number of channels from an Opus packet. More... | |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int | celt_opus_packet_get_nb_frames (const unsigned char packet[], int len) OPUS_ARG_NONNULL(1) |
Gets the number of frames in an Opus packet. More... | |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int | celt_opus_packet_get_nb_samples (const unsigned char packet[], int len, int Fs) OPUS_ARG_NONNULL(1) |
Gets the number of samples of an Opus packet. More... | |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int | celt_opus_decoder_get_nb_samples (const OpusDecoder *dec, const unsigned char packet[], int len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) |
Gets the number of samples of an Opus packet. More... | |
OPUS_EXPORT void | opus_pcm_soft_clip (float *pcm, int frame_size, int channels, float *softclip_mem) |
Applies soft-clipping to bring a float signal within the [-1,1] range. More... | |
This page describes the process and functions used to decode Opus.
The decoding process also starts with creating a decoder state. This can be done with:
where
While celt_opus_decoder_create() allocates memory for the state, it's also possible to initialize pre-allocated memory:
where celt_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 should be made about it.
The decoder state is always continuous in memory and only a shallow copy is sufficient to copy it (e.g. memcpy())
To decode a frame, celt_opus_decode() or opus_decode_float() must be called with a packet of compressed audio data:
where
celt_opus_decode() and opus_decode_float() return the number of samples (per channel) decoded from the packet. If that value is negative, then an error has occurred. This can occur if the packet is corrupted or if the audio buffer is too small to hold the decoded audio.
Opus is a stateful codec with overlapping blocks and as a result Opus packets are not coded independently of each other. Packets must be passed into the decoder serially and in the correct order for a correct decode. Lost packets can be replaced with loss concealment by calling the decoder with a null pointer and zero length for the missing packet.
A single codec state may only be accessed from a single thread at a time and any required locking must be performed by the caller. Separate streams must be decoded with separate decoder states and can be decoded in parallel unless the library was compiled with NONTHREADSAFE_PSEUDOSTACK defined.
typedef struct OpusDecoder OpusDecoder |
Opus decoder state.
This contains the complete state of an Opus decoder. It is position independent and can be freely copied.
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int celt_opus_decode | ( | OpusDecoder * | st, |
const unsigned char * | data, | ||
int | len, | ||
opus_int16 * | pcm, | ||
int | frame_size, | ||
int | decode_fec | ||
) |
Decode an Opus packet.
[in] | st | OpusDecoder* : Decoder state |
[in] | data | char* : Input payload. Use a NULL pointer to indicate packet loss |
[in] | len | opus_int32 : Number of bytes in payload* |
[out] | pcm | opus_int16* : Output signal (interleaved if 2 channels). length is frame_size*channels*sizeof(opus_int16) |
[in] | frame_size | Number of samples per channel of available space in 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. |
[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. |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusDecoder* celt_opus_decoder_create | ( | int | Fs, |
int | channels, | ||
int * | error | ||
) |
Allocates and initializes a decoder state.
[in] | Fs | opus_int32 : Sample rate to decode at (Hz). This must be one of 8000, 12000, 16000, 24000, or 48000. |
[in] | channels | int : Number of channels (1 or 2) to decode |
[out] | error | int* : OPUS_OK Success or Error codes |
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.
OPUS_EXPORT int celt_opus_decoder_ctl | ( | OpusDecoder * | st, |
int | request, | ||
... | |||
) |
Perform a CTL function on an Opus decoder.
Generally the request and subsequent arguments are generated by a convenience macro.
st | OpusDecoder* : Decoder state. |
request | This and all remaining parameters should be replaced by one of the convenience macros in Generic CTLs or Decoder related CTLs. |
OPUS_EXPORT void celt_opus_decoder_destroy | ( | OpusDecoder * | st | ) |
Frees an OpusDecoder
allocated by celt_opus_decoder_create().
[in] | st | OpusDecoder* : State to be freed. |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int celt_opus_decoder_get_nb_samples | ( | const OpusDecoder * | dec, |
const unsigned char | packet[], | ||
int | len | ||
) |
Gets the number of samples of an Opus packet.
[in] | dec | OpusDecoder* : Decoder state |
[in] | packet | char* : Opus packet |
[in] | len | opus_int32 : Length of packet |
OPUS_BAD_ARG | Insufficient data was passed to the function |
OPUS_INVALID_PACKET | The compressed data passed is corrupted or of an unsupported type |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int celt_opus_decoder_get_size | ( | int | channels | ) |
Gets the size of an OpusDecoder
structure.
[in] | channels | int : Number of channels. This must be 1 or 2. |
OPUS_EXPORT int celt_opus_decoder_init | ( | OpusDecoder * | st, |
int | Fs, | ||
int | channels | ||
) |
Initializes a previously allocated decoder state.
The state must be at least the size returned by celt_opus_decoder_get_size(). This is intended for applications which use their own allocator instead of malloc.
[in] | st | OpusDecoder* : Decoder state. |
[in] | Fs | opus_int32 : Sampling rate to decode to (Hz). This must be one of 8000, 12000, 16000, 24000, or 48000. |
[in] | channels | int : Number of channels (1 or 2) to decode |
OPUS_OK | Success or Error codes |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int celt_opus_packet_get_bandwidth | ( | const unsigned char * | data | ) |
Gets the bandwidth of an Opus packet.
[in] | data | char* : Opus packet |
OPUS_BANDWIDTH_NARROWBAND | Narrowband (4kHz bandpass) |
OPUS_BANDWIDTH_MEDIUMBAND | Mediumband (6kHz bandpass) |
OPUS_BANDWIDTH_WIDEBAND | Wideband (8kHz bandpass) |
OPUS_BANDWIDTH_SUPERWIDEBAND | Superwideband (12kHz bandpass) |
OPUS_BANDWIDTH_FULLBAND | Fullband (20kHz bandpass) |
OPUS_INVALID_PACKET | The compressed data passed is corrupted or of an unsupported type |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int celt_opus_packet_get_nb_channels | ( | const unsigned char * | data | ) |
Gets the number of channels from an Opus packet.
[in] | data | char* : Opus packet |
OPUS_INVALID_PACKET | The compressed data passed is corrupted or of an unsupported type |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int celt_opus_packet_get_nb_frames | ( | const unsigned char | packet[], |
int | len | ||
) |
Gets the number of frames in an Opus packet.
[in] | packet | char* : Opus packet |
[in] | len | opus_int32 : Length of packet |
OPUS_BAD_ARG | Insufficient data was passed to the function |
OPUS_INVALID_PACKET | The compressed data passed is corrupted or of an unsupported type |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int celt_opus_packet_get_nb_samples | ( | const unsigned char | packet[], |
int | len, | ||
int | Fs | ||
) |
Gets the number of samples of an Opus packet.
[in] | packet | char* : Opus packet |
[in] | len | opus_int32 : Length of packet |
[in] | Fs | opus_int32 : Sampling rate in Hz. This must be a multiple of 400, or inaccurate results will be returned. |
OPUS_BAD_ARG | Insufficient data was passed to the function |
OPUS_INVALID_PACKET | The compressed data passed is corrupted or of an unsupported type |
int celt_opus_packet_get_samples_per_frame | ( | const unsigned char * | data, |
int | Fs | ||
) |
Gets the number of samples per frame from an Opus packet.
[in] | data | char* : Opus packet. This must contain at least one byte of data. |
[in] | Fs | opus_int32 : Sampling rate in Hz. This must be a multiple of 400, or inaccurate results will be returned. |
OPUS_EXPORT int celt_opus_packet_parse | ( | const unsigned char * | data, |
int | len, | ||
unsigned char * | out_toc, | ||
const unsigned char * | frames[48], | ||
opus_int16 | size[48], | ||
int * | payload_offset | ||
) |
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.
[in] | data | char* : Opus packet to be parsed |
[in] | len | opus_int32 : size of data |
[out] | out_toc | char* : TOC pointer |
[out] | frames | char*[48] encapsulated frames |
[out] | size | opus_int16[48] sizes of the encapsulated frames |
[out] | payload_offset | int* : returns the position of the payload within the packet (in bytes) |
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode_float | ( | OpusDecoder * | st, |
const unsigned char * | data, | ||
int | len, | ||
float * | pcm, | ||
int | frame_size, | ||
int | decode_fec | ||
) |
Decode an Opus packet with floating point output.
[in] | st | OpusDecoder* : Decoder state |
[in] | data | char* : Input payload. Use a NULL pointer to indicate packet loss |
[in] | len | opus_int32 : Number of bytes in payload |
[out] | pcm | float* : Output signal (interleaved if 2 channels). length is frame_size*channels*sizeof(float) |
[in] | frame_size | Number of samples per channel of available space in 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. |
[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. |
OPUS_EXPORT void opus_pcm_soft_clip | ( | float * | pcm, |
int | frame_size, | ||
int | channels, | ||
float * | softclip_mem | ||
) |
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.
[in,out] | pcm | float* : Input PCM and modified PCM |
[in] | frame_size | int Number of samples per channel to process |
[in] | channels | int : Number of channels |
[in,out] | softclip_mem | float* : State memory for the soft clipping process (one float per channel, initialized to zero) |