---
name: "opus_decoder"
section: "3"
platform: "linux"
package: "libopus-doc"
version: "1.5.2-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/opus_decoder"
---

# opus\_decoder(3)

Opus Decoder - This page describes the process and functions used to decode Opus.

## NAME

opus\_decoder - Opus Decoder

 \- This page describes the process and functions used to decode Opus.

## SYNOPSIS

### Typedefs

typedef struct **OpusDecoder** **OpusDecoder**\
 Opus decoder state.  typedef struct **OpusDREDDecoder** **OpusDREDDecoder**\
 Opus DRED decoder.  typedef struct **OpusDRED** **OpusDRED**\
 Opus DRED 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\_dred\_decoder\_get\_size** (void)\
 Gets the size of an `OpusDREDDecoder` structure.  **OpusDREDDecoder** \* **opus\_dred\_decoder\_create** (int \*error)\
 Allocates and initializes an OpusDREDDecoder state.  int **opus\_dred\_decoder\_init** (**OpusDREDDecoder** \*dec)\
 Initializes an `OpusDREDDecoder` state.  void **opus\_dred\_decoder\_destroy** (**OpusDREDDecoder** \*dec)\
 Frees an `OpusDREDDecoder` allocated by **opus\_dred\_decoder\_create()**.  int **opus\_dred\_decoder\_ctl** (**OpusDREDDecoder** \*dred\_dec, int request,...)\
 Perform a CTL function on an Opus DRED decoder.  int **opus\_dred\_get\_size** (void)\
 Gets the size of an `OpusDRED` structure.  **OpusDRED** \* **opus\_dred\_alloc** (int \*error)\
 Allocates and initializes a DRED state.  void **opus\_dred\_free** (**OpusDRED** \*dec)\
 Frees an `OpusDRED` allocated by opus\_dred\_create().  int **opus\_dred\_parse** (**OpusDREDDecoder** \*dred\_dec, **OpusDRED** \*dred, const unsigned char \*data, **opus\_int32** len, **opus\_int32** max\_dred\_samples, **opus\_int32** sampling\_rate, int \*dred\_end, int defer\_processing)\
 Decode an Opus DRED packet.  int **opus\_dred\_process** (**OpusDREDDecoder** \*dred\_dec, const **OpusDRED** \*src, **OpusDRED** \*dst)\
 Finish decoding an Opus DRED packet.  int **opus\_decoder\_dred\_decode** (**OpusDecoder** \*st, const **OpusDRED** \*dred, **opus\_int32** dred\_offset, **opus\_int16** \*pcm, **opus\_int32** frame\_size)\
 Decode audio from an Opus DRED packet with floating point output.  int **opus\_decoder\_dred\_decode\_float** (**OpusDecoder** \*st, const **OpusDRED** \*dred, **opus\_int32** dred\_offset, float \*pcm, **opus\_int32** frame\_size)\
 Decode audio from an Opus DRED packet with floating point output.  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\_packet\_has\_lbrr** (const unsigned char packet\[\], **opus\_int32** len)\
 Checks whether an Opus packet has LBRR.  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 assumptions 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

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

### typedef struct OpusDRED OpusDRED

Opus DRED state. This contains the complete state of an Opus DRED packet. It is position independent and can be freely copied.

**See also**

opus\_dred\_create,opus\_dred\_init

### typedef struct OpusDREDDecoder OpusDREDDecoder

Opus DRED decoder. This contains the complete state of an Opus DRED decoder. It is position independent and can be freely copied.

**See also**

**opus\_dred\_decoder\_create**,**opus\_dred\_decoder\_init**

## Function Documentation

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

*st* `OpusDecoder*`: Decoder state \
 *data* `char*`: Input payload. Use a NULL pointer to indicate packet loss \
 *len* `opus_int32`: Number of bytes in payload\* \
 *pcm* `opus_int16*`: Output signal (interleaved if 2 channels). length is frame\_size\*channels\*sizeof(opus\_int16) \
 *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. \
 *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**

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

*st* `OpusDecoder*`: Decoder state \
 *data* `char*`: Input payload. Use a NULL pointer to indicate packet loss \
 *len* `opus_int32`: Number of bytes in payload \
 *pcm* `float*`: Output signal (interleaved if 2 channels). length is frame\_size\*channels\*sizeof(float) \
 *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. \
 *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**

### OpusDecoder \* opus\_decoder\_create (opus\_int32 Fs, int channels, int \* error)

Allocates and initializes a decoder state.

**Parameters**

*Fs* `opus_int32`: Sample rate to decode at (Hz). This must be one of 8000, 12000, 16000, 24000, or 48000. \
 *channels* `int`: Number of channels (1 or 2) to decode \
 *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.

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

### void opus\_decoder\_destroy (OpusDecoder \* st)

Frees an `OpusDecoder` allocated by **opus\_decoder\_create()**.

**Parameters**

*st* `OpusDecoder*`: State to be freed.

### int opus\_decoder\_dred\_decode (OpusDecoder \* st, const OpusDRED \* dred, opus\_int32 dred\_offset, opus\_int16 \* pcm, opus\_int32 frame\_size)

Decode audio from an Opus DRED packet with floating point output.

**Parameters**

*st* `OpusDecoder*`: Decoder state \
 *dred* `OpusDRED*`: DRED state \
 *dred\_offset* `opus_int32`: position of the redundancy to decode (in samples before the beginning of the real audio data in the packet). \
 *pcm* `opus_int16*`: Output signal (interleaved if 2 channels). length is frame\_size\*channels\*sizeof(opus\_int16) \
 *frame\_size* Number of samples per channel to decode in *pcm*. frame\_size **must** be a multiple of 2.5 ms.

**Returns**

Number of decoded samples or **Error codes**

### int opus\_decoder\_dred\_decode\_float (OpusDecoder \* st, const OpusDRED \* dred, opus\_int32 dred\_offset, float \* pcm, opus\_int32 frame\_size)

Decode audio from an Opus DRED packet with floating point output.

**Parameters**

*st* `OpusDecoder*`: Decoder state \
 *dred* `OpusDRED*`: DRED state \
 *dred\_offset* `opus_int32`: position of the redundancy to decode (in samples before the beginning of the real audio data in the packet). \
 *pcm* `float*`: Output signal (interleaved if 2 channels). length is frame\_size\*channels\*sizeof(float) \
 *frame\_size* Number of samples per channel to decode in *pcm*. frame\_size **must** be a multiple of 2.5 ms.

**Returns**

Number of decoded samples or **Error codes**

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

*dec* `OpusDecoder*`: Decoder state \
 *packet* `char*`: Opus packet \
 *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

### int opus\_decoder\_get\_size (int channels)

Gets the size of an `OpusDecoder` structure.

**Parameters**

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

**Returns**

The size in bytes.

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

*st* `OpusDecoder*`: Decoder state. \
 *Fs* `opus_int32`: Sampling rate to decode to (Hz). This must be one of 8000, 12000, 16000, 24000, or 48000. \
 *channels* `int`: Number of channels (1 or 2) to decode

**Return values**

**OPUS\_OK Success or Error codes**

### OpusDRED \* opus\_dred\_alloc (int \* error)

**Allocates and initializes a DRED state.**

**Parameters**

*error* `int*`**: OPUS\_OK Success or Error codes**

### OpusDREDDecoder \* opus\_dred\_decoder\_create (int \* error)

**Allocates and initializes an OpusDREDDecoder state.**

**Parameters**

*error* `int*`**: OPUS\_OK Success or Error codes**

### int opus\_dred\_decoder\_ctl (OpusDREDDecoder \* dred\_dec, int request, ...)

**Perform a CTL function on an Opus DRED decoder. Generally the request and subsequent arguments are generated by a convenience macro.**

**Parameters**

*dred\_dec* `OpusDREDDecoder*`**: DRED 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**

### void opus\_dred\_decoder\_destroy (OpusDREDDecoder \* dec)

**Frees an** `OpusDREDDecoder` **allocated by opus\_dred\_decoder\_create().**

**Parameters**

*dec* `OpusDREDDecoder*`**: State to be freed.**

### int opus\_dred\_decoder\_get\_size (void)

**Gets the size of an** `OpusDREDDecoder` **structure.**

**Returns**

**The size in bytes.**

### int opus\_dred\_decoder\_init (OpusDREDDecoder \* dec)

**Initializes an** `OpusDREDDecoder` **state.**

**Parameters**

*dec* `OpusDREDDecoder*`**: State to be initialized.**

### void opus\_dred\_free (OpusDRED \* dec)

**Frees an** `OpusDRED` **allocated by opus\_dred\_create().**

**Parameters**

*dec* `OpusDRED*`**: State to be freed.**

### int opus\_dred\_get\_size (void)

**Gets the size of an** `OpusDRED` **structure.**

**Returns**

**The size in bytes.**

### int opus\_dred\_parse (OpusDREDDecoder \* dred\_dec, OpusDRED \* dred, const unsigned char \* data, opus\_int32 len, opus\_int32 max\_dred\_samples, opus\_int32 sampling\_rate, int \* dred\_end, int defer\_processing)

**Decode an Opus DRED packet.**

**Parameters**

*dred\_dec* `OpusDRED*`**: DRED Decoder state** \
 *dred* `OpusDRED*`**: DRED state** \
 *data* `char*`**: Input payload** \
 *len* `opus_int32`**: Number of bytes in payload** \
 *max\_dred\_samples* `opus_int32`**: Maximum number of DRED samples that may be needed (if available in the packet).** \
 *sampling\_rate* `opus_int32`**: Sampling rate used for max\_dred\_samples argument. Needs not match the actual sampling rate of the decoder.** \
 *dred\_end* `opus_int32*`**: Number of non-encoded (silence) samples between the DRED timestamp and the last DRED sample.** \
 *defer\_processing* `int`**: Flag (0 or 1). If set to one, the CPU-intensive part of the DRED decoding is deferred until opus\_dred\_process() is called.**

**Returns**

**Offset (positive) of the first decoded DRED samples, zero if no DRED is present, or Error codes**

### int opus\_dred\_process (OpusDREDDecoder \* dred\_dec, const OpusDRED \* src, OpusDRED \* dst)

**Finish decoding an Opus DRED packet. The function only needs to be called if opus\_dred\_parse() was called with defer\_processing=1. The source and destination will often be the same DRED state.**

**Parameters**

*dred\_dec* `OpusDRED*`**: DRED Decoder state** \
 *src* `OpusDRED*`**: Source DRED state to start the processing from.** \
 *dst* `OpusDRED*`**: Destination DRED state to store the updated state after processing.**

**Returns**

**Error codes**

### int opus\_packet\_get\_bandwidth (const unsigned char \* data)

**Gets the bandwidth of an Opus packet.**

**Parameters**

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

*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\[\], opus\_int32 len)

**Gets the number of frames in an Opus packet.**

**Parameters**

*packet* `char*`**: Opus packet** \
 *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**

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

*packet* `char*`**: Opus packet** \
 *len* `opus_int32`**: Length of packet** \
 *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**

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

*data* `char*`**: Opus packet. This must contain at least one byte of data.** \
 *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.**

### int opus\_packet\_has\_lbrr (const unsigned char packet\[\], opus\_int32 len)

**Checks whether an Opus packet has LBRR.**

**Parameters**

*packet* `char*`**: Opus packet** \
 *len* `opus_int32`**: Length of packet**

**Returns**

**1 is LBRR is present, 0 otherwise**

**Return values**

*OPUS\_INVALID\_PACKET* **The compressed data passed is corrupted or of an unsupported type**

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

*data* `char*`**: Opus packet to be parsed** \
 *len* `opus_int32`**: size of data** \
 *out\_toc* `char*`**: TOC pointer** \
 *frames* `char*[48]` **encapsulated frames** \
 *size* `opus_int16[48]` **sizes of the encapsulated frames** \
 *payload\_offset* `int*`**: returns the position of the payload within the packet (in bytes)**

**Returns**

**number of frames**

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

*pcm* `float*`**: Input PCM and modified PCM** \
 *frame\_size* `int` **Number of samples per channel to process** \
 *channels* `int`**: Number of channels** \
 *softclip\_mem* `float*`**: State memory for the soft clipping process (one float per channel, initialized to zero)**

## Author

**Generated automatically by Doxygen for Opus from the source code.**