Opus Decoder

This page describes the process and functions used to decode Opus. 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, opus_int32 len, opus_int16 *pcm, int frame_size, int decode_fec)
	Decode an Opus packet.
int	opus_decode_float (OpusDecoder *st, const unsigned char *data, opus_int32 len, float *pcm, int frame_size, int decode_fec)
	Decode an Opus packet 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, opus_int32 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.
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[], opus_int32 len)
	Gets the number of frames in an Opus packet.
int	opus_packet_get_nb_samples (const unsigned char packet[], opus_int32 len, opus_int32 Fs)
	Gets the number of samples of an Opus packet.
int	opus_decoder_get_nb_samples (const OpusDecoder *dec, const unsigned char packet[], opus_int32 len)
	Gets the number of samples of an Opus packet.
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.

Detailed Description

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:

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

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 of 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:

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(dec, packet, len, decoded, max_size, 0);

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_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 Documentation

OpusDecoder

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

opus_decode()

int opus_decode	(	OpusDecoder *	st,
		const unsigned char *	data,
		opus_int32	len,
		opus_int16 *	pcm,
		int	frame_size,
		int	decode_fec
	)

Decode an Opus packet.

Parameters

[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.

Returns

Number of decoded samples or Error codes

opus_decode_float()

int opus_decode_float	(	OpusDecoder *	st,
		const unsigned char *	data,
		opus_int32	len,
		float *	pcm,
		int	frame_size,
		int	decode_fec
	)

Decode an Opus packet 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	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.

Returns

Number of decoded samples or Error codes

opus_decoder_create()

OpusDecoder * opus_decoder_create	(	opus_int32	Fs,
		int	channels,
		int *	error
	)

Allocates and initializes a decoder state.

Parameters

[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_decoder_ctl()

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.

Parameters

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.

See also

Generic CTLs

Decoder related CTLs

opus_decoder_destroy()

void opus_decoder_destroy

(

OpusDecoder *

st

)

Frees an OpusDecoder allocated by opus_decoder_create().

Parameters

[in]

st

OpusDecoder*: State to be freed.

opus_decoder_get_nb_samples()

int opus_decoder_get_nb_samples	(	const OpusDecoder *	dec,
		const unsigned char	packet[],
		opus_int32	len
	)

Gets the number of samples of an Opus packet.

Parameters

[in]	dec	OpusDecoder*: Decoder state
[in]	packet	char*: Opus packet
[in]	len	opus_int32: Length of packet

Returns

Number of samples

Return values

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_decoder_get_size()

int opus_decoder_get_size

(

int

channels

)

Gets the size of an OpusDecoder structure.

Parameters

[in]

channels

int: Number of channels. This must be 1 or 2.

Returns

The size in bytes.

opus_decoder_init()

int opus_decoder_init	(	OpusDecoder *	st,
		opus_int32	Fs,
		int	channels
	)

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 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 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

Return values

OPUS_OK

Success or Error codes

opus_packet_get_bandwidth()

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

opus_packet_get_nb_channels()

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

opus_packet_get_nb_frames()

int opus_packet_get_nb_frames	(	const unsigned char	packet[],
		opus_int32	len
	)

Gets the number of frames in an Opus packet.

Parameters

[in]	packet	char*: Opus packet
[in]	len	opus_int32: Length of packet

Returns

Number of frames

Return values

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_packet_get_nb_samples()

int opus_packet_get_nb_samples	(	const unsigned char	packet[],
		opus_int32	len,
		opus_int32	Fs
	)

Gets the number of samples of an Opus packet.

Parameters

[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.

Returns

Number of samples

Return values

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_packet_get_samples_per_frame()

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

Returns

Number of samples per frame.

opus_packet_parse()

int opus_packet_parse	(	const unsigned char *	data,
		opus_int32	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.

Parameters

[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)

Returns

number of frames

opus_pcm_soft_clip()

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.

Parameters

[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)