Typedefs | Functions

Opus Decoder

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.
OpusDecoderopus_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:

 int          error;
 OpusDecoder *dec;
 dec = opus_decoder_create(Fs, channels, &error);

where

While opus_decoder_create() allocates memory for the state, it's also possible to initialize pre-allocated memory:

 int          size;
 int          error;
 OpusDecoder *dec;
 size = opus_decoder_get_size(channels);
 dec = malloc(size);
 error = opus_decoder_init(dec, Fs, channels);

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

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

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.

See also:
opus_decoder_create,opus_decoder_init

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
OpusDecoder* opus_decoder_create ( opus_int32  Fs,
int  channels,
int *  error 
)

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
void opus_decoder_destroy ( OpusDecoder st  ) 

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
int opus_decoder_init ( OpusDecoder st,
opus_int32  Fs,
int  channels 
)

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:
OPUS_OK Success or Error codes
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
 All Files Functions Typedefs Defines