The decoding process also starts with creating a decoder state.
More...
Typedefs |
typedef struct OpusDecoder | OpusDecoder |
| Opus decoder state.
|
Functions |
int | opus_decoder_get_size (int channels) |
| Gets the size of an OpusDecoder structure.
|
OpusDecoder * | opus_decoder_create (opus_int32 Fs, int channels, int *error) |
| Allocates and initializes a decoder state.
|
int | opus_decoder_init (OpusDecoder *st, opus_int32 Fs, int channels) |
| Initializes a previously allocated decoder state.
|
int | opus_decode (OpusDecoder *st, const unsigned char *data, int len, opus_int16 *pcm, int frame_size, int decode_fec) |
| Decode an Opus frame.
|
int | opus_decode_float (OpusDecoder *st, const unsigned char *data, int len, float *pcm, int frame_size, int decode_fec) |
| Decode an opus frame with floating point output.
|
int | opus_decoder_ctl (OpusDecoder *st, int request,...) |
| Perform a CTL function on an Opus decoder.
|
void | opus_decoder_destroy (OpusDecoder *st) |
| Frees an OpusDecoder allocated by opus_decoder_create.
|
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) |
| Parse an opus packet into one or more frames.
|
int | opus_packet_get_bandwidth (const unsigned char *data) |
| Gets the bandwidth of an Opus packet.
|
int | opus_packet_get_samples_per_frame (const unsigned char *data, opus_int32 Fs) |
| Gets the number of samples per frame from an Opus packet.
|
int | opus_packet_get_nb_channels (const unsigned char *data) |
| Gets the number of channels from an Opus packet.
|
int | opus_packet_get_nb_frames (const unsigned char packet[], int len) |
| Gets the number of frames in an Opus packet.
|
int | opus_decoder_get_nb_samples (const OpusDecoder *dec, const unsigned char packet[], int len) |
| Gets the number of samples of an Opus packet.
|
Detailed Description
The decoding process also starts with creating a decoder state.
This can be done with:
where
- Fs is the sampling rate and must be 8000, 12000, 16000, 24000, or 48000
- channels is the number of channels (1 or 2)
- error will hold the error code in case or failure (or OPUS_OK on success)
- the return value is a newly created decoder state to be used for decoding
While opus_decoder_create() allocates memory for the state, it's also possible to initialize pre-allocated memory:
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 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, opus_decode() or opus_decode_float() must be called with a packet of compressed audio data:
frame_size = opus_decode(enc, packet, len, decoded, max_size);
where
- packet is the byte array containing the compressed data
- len is the exact number of bytes contained in the packet
- decoded is the decoded audio data in opus_int16 (or float for opus_decode_float())
- 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 ()per 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.
Typedef Documentation
Function Documentation
int opus_decode |
( |
OpusDecoder * |
st, |
|
|
const unsigned char * |
data, |
|
|
int |
len, |
|
|
opus_int16 * |
pcm, |
|
|
int |
frame_size, |
|
|
int |
decode_fec | |
|
) |
| | |
Decode an Opus frame.
- Parameters:
-
[in] | st | OpusDecoder* : Decoder state |
[in] | data | char* : Input payload. Use a NULL pointer to indicate packet loss |
[in] | len | int : 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 less than the maximum frame size (120ms) some frames can not be decoded |
[in] | decode_fec | int : 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 were lost. |
- Returns:
- Number of decoded samples or Error codes
int opus_decode_float |
( |
OpusDecoder * |
st, |
|
|
const unsigned char * |
data, |
|
|
int |
len, |
|
|
float * |
pcm, |
|
|
int |
frame_size, |
|
|
int |
decode_fec | |
|
) |
| | |
Decode an opus frame with floating point output.
- Parameters:
-
[in] | st | OpusDecoder* : Decoder state |
[in] | data | char* : Input payload. Use a NULL pointer to indicate packet loss |
[in] | len | int : 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 less than the maximum frame size (120ms) some frames can not be decoded |
[in] | decode_fec | int : 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 were lost. |
- Returns:
- Number of decoded samples or Error codes
Allocates and initializes a decoder state.
- Parameters:
-
[in] | Fs | opus_int32 : Sampling rate of input signal (Hz) |
[in] | channels | int : Number of channels (1/2) in input signal |
[out] | error | int* : OPUS_OK Success or Error codes |
int 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.
- See also:
- Generic CTLs
Frees an OpusDecoder allocated by opus_decoder_create.
- Parameters:
-
[in] | st | OpusDecoder* : State to be freed. |
int opus_decoder_get_nb_samples |
( |
const OpusDecoder * |
dec, |
|
|
const unsigned char |
packet[], |
|
|
int |
len | |
|
) |
| | |
Gets the number of samples of an Opus packet.
- Parameters:
-
[in] | dec | OpusDecoder* : Decoder state |
[in] | packet | char* : Opus packet |
[in] | len | int : Length of packet |
- Returns:
- Number of samples
- Return values:
-
| OPUS_INVALID_PACKET | The compressed data passed is corrupted or of an unsupported type |
int opus_decoder_get_size |
( |
int |
channels |
) |
|
Gets the size of an OpusDecoder structure.
- Parameters:
-
[in] | channels | int : Number of channels |
- Returns:
- size
Initializes a previously allocated decoder state.
The state must be the size returned by opus_decoder_get_size. This is intended for applications which use their own allocator instead of malloc.
- See also:
- opus_decoder_create,opus_decoder_get_size To reset a previously initialized state use the OPUS_RESET_STATE CTL.
- Parameters:
-
[in] | st | OpusDecoder* : Decoder state. |
[in] | Fs | opus_int32 : Sampling rate of input signal (Hz) |
[in] | channels | int : Number of channels (1/2) in input signal |
- Return values:
-
int opus_packet_get_bandwidth |
( |
const unsigned char * |
data |
) |
|
Gets the bandwidth of an Opus packet.
- Parameters:
-
[in] | data | char* : Opus packet |
- Return values:
-
| 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 |
int opus_packet_get_nb_channels |
( |
const unsigned char * |
data |
) |
|
Gets the number of channels from an Opus packet.
- Parameters:
-
[in] | data | char* : Opus packet |
- Returns:
- Number of channels
- Return values:
-
| OPUS_INVALID_PACKET | The compressed data passed is corrupted or of an unsupported type |
int opus_packet_get_nb_frames |
( |
const unsigned char |
packet[], |
|
|
int |
len | |
|
) |
| | |
Gets the number of frames in an Opus packet.
- Parameters:
-
[in] | packet | char* : Opus packet |
[in] | len | int : Length of packet |
- Returns:
- Number of frames
- Return values:
-
| OPUS_INVALID_PACKET | The compressed data passed is corrupted or of an unsupported type |
int opus_packet_get_samples_per_frame |
( |
const unsigned char * |
data, |
|
|
opus_int32 |
Fs | |
|
) |
| | |
Gets the number of samples per frame from an Opus packet.
- Parameters:
-
[in] | data | char* : Opus packet |
[in] | Fs | opus_int32 : Sampling rate in Hz |
- Returns:
- Number of samples per frame
- Return values:
-
| OPUS_INVALID_PACKET | The compressed data passed is corrupted or of an unsupported type |
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 | |
|
) |
| | |
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.
- Parameters:
-
[in] | data | char* : Opus packet to be parsed |
[in] | len | int : size of data |
[out] | out_toc | char* : TOC pointer |
[out] | frames | char*[48] encapsulated frames |
[out] | size | short[48] sizes of the encapsulated frames |
[out] | payload_offset | int* : returns the position of the payload within the packet (in bytes) |
- Returns:
- number of frames