opus_decoder(3)
okay bestie, welcome to opus_decoder(3) from the Opus manual β part 1 of 3, and it's giving decoder lore fr fr. π
β¨ 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_decode24 (OpusDecoder *st, const unsigned char *data, opus_int32 len, opus_int32 *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 16-bit output.int opus_decoder_dred_decode24 (OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, opus_int32 *pcm, opus_int32 frame_size)β Decode audio from an Opus DRED packet with 24-bit 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
Fsis the sampling rate and must be8000,12000,16000,24000, or48000channelsis the number of channels (1or2)errorwill hold the error code in case of failure (orOPUS_OKon 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
packetis the byte array containing the compressed datalenis the exact number of bytes contained in the packetdecodedis the decoded audio data inopus_int16(orfloatforopus_decode_float())max_sizeis the max duration of the frame in samples (per channel) that can fit into thedecoded_framearray
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 π
okay bestie, this is the main event β every single function this header hands you, with all the deets preserved exactly π no skips, no shortcuts, we're going the whole way.
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. Literally the moment the whole library was building toward β¨
Parameters
stOpusDecoder*β Decoder statedatachar*β Input payload. Use aNULLpointer to indicate packet losslenopus_int32β Number of bytes in payload*pcmopus_int16*β Output signal (interleaved if 2 channels). length isframe_size*channels*sizeof(opus_int16)frame_sizeβ Number of samples per channel of available space inpcm. 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), thenframe_sizeneeds 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_sizemust be a multiple of 2.5 ms.decode_fecintβ 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 per channel or Error codes
opus_decode24 π
int opus_decode24 (OpusDecoder * st, const unsigned char * data, opus_int32 len, opus_int32 * pcm, int frame_size, int decode_fec)
Decode an Opus packet. Same energy, but 24-bit flavored π¦
Parameters
stOpusDecoder*β Decoder statedatachar*β Input payload. Use aNULLpointer to indicate packet losslenopus_int32β Number of bytes in payload*pcmopus_int32*β Output signal (interleaved if 2 channels) representing (or slightly exceeding) 24-bit values. length isframe_size*channels*sizeof(opus_int32)frame_sizeβ Number of samples per channel of available space inpcm. 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), thenframe_sizeneeds 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_sizemust be a multiple of 2.5 ms.decode_fecintβ 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. For the girlies who live in float land π
Parameters
stOpusDecoder*β Decoder statedatachar*β Input payload. Use aNULLpointer to indicate packet losslenopus_int32β Number of bytes in payloadpcmfloat*β Output signal (interleaved if 2 channels). length isframe_size*channels*sizeof(float)frame_sizeβ Number of samples per channel of available space inpcm. 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), thenframe_sizeneeds 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_sizemust be a multiple of 2.5 ms.decode_fecintβ 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 per channel or Error codes
opus_decoder_create π
OpusDecoder * opus_decoder_create (opus_int32 Fs, int channels, int * error)
Allocates and initializes a decoder state. Yes queen, build the whole decoder from scratch π«Ά
Parameters
Fsopus_int32β Sample rate to decode at (Hz). This must be one of 8000, 12000, 16000, 24000, or 48000.channelsintβ Number of channels (1 or 2) to decodeerrorint*βOPUS_OKSuccess 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
stOpusDecoder*β 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(). Clean up after yourself, bestie, it's giving self-care π
Parameters
stOpusDecoder*β State to be freed.
opus_decoder_dred_decode π
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 16-bit output.
Parameters
stOpusDecoder*β Decoder statedredOpusDRED*β DRED statedred_offsetopus_int32β position of the redundancy to decode (in samples before the beginning of the real audio data in the packet).pcmopus_int16*β Output signal (interleaved if 2 channels). length isframe_size*channels*sizeof(opus_int16)frame_sizeβ Number of samples per channel to decode inpcm.frame_sizemust be a multiple of 2.5 ms.
Returns
Number of decoded samples or Error codes
opus_decoder_dred_decode24 π
int opus_decoder_dred_decode24 (OpusDecoder * st, const OpusDRED * dred, opus_int32 dred_offset, opus_int32 * pcm, opus_int32 frame_size)
Decode audio from an Opus DRED packet with 24-bit output.
Parameters
stOpusDecoder*β Decoder statedredOpusDRED*β DRED statedred_offsetopus_int32β position of the redundancy to decode (in samples before the beginning of the real audio data in the packet).pcmopus_int32*β Output signal (interleaved if 2 channels). length isframe_size*channels*sizeof(opus_int16)frame_sizeβ Number of samples per channel to decode inpcm.frame_sizemust be a multiple of 2.5 ms.
Returns
Number of decoded samples or Error codes
opus_decoder_dred_decode_float π¦
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
stOpusDecoder*β Decoder statedredOpusDRED*β DRED statedred_offsetopus_int32β position of the redundancy to decode (in samples before the beginning of the real audio data in the packet).pcmfloat*β Output signal (interleaved if 2 channels). length isframe_size*channels*sizeof(float)frame_sizeβ Number of samples per channel to decode inpcm.frame_sizemust be a multiple of 2.5 ms.
Returns
Number of decoded samples or Error codes
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. Peek before you decode, yk? π
Parameters
decOpusDecoder*β Decoder statepacketchar*β Opus packetlenopus_int32β Length of packet
Returns
Number of samples
Return values
OPUS_BAD_ARGβ Insufficient data was passed to the functionOPUS_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
channelsintβ 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. DIY girlies, this one's for you π«Ά
See also
opus_decoder_create, opus_decoder_get_size β To reset a previously initialized state, use the OPUS_RESET_STATE CTL.
Parameters
stOpusDecoder*β Decoder state.Fsopus_int32β Sampling rate to decode to (Hz). This must be one of 8000, 12000, 16000, 24000, or 48000.channelsintβ Number of channels (1 or 2) to decode
Return values
OPUS_OKβ Success or Error codes
opus_dred_alloc π
OpusDRED * opus_dred_alloc (int * error)
Allocates and initializes a DRED state.
Parameters
errorint*βOPUS_OKSuccess or Error codes
opus_dred_decoder_create β¨
OpusDREDDecoder * opus_dred_decoder_create (int * error)
Allocates and initializes an OpusDREDDecoder state.
Parameters
errorint*βOPUS_OKSuccess or Error codes
opus_dred_decoder_ctl ποΈ
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_decOpusDREDDecoder*β 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 π
okay bestie, this is the last stretch and it's giving very specific energy β DRED decoder housekeeping plus a whole lil family of packet-inspection cuties. let's get into it π
void opus_dred_decoder_destroy (OpusDREDDecoder * dec)
Frees an OpusDREDDecoder that was allocated by opus_dred_decoder_create(). bye babe π«Ά
Parameters
decβOpusDREDDecoder*: State to be freed.
int opus_dred_decoder_get_size (void )
Gets the size of an OpusDREDDecoder structure. very "how much room do I need" of it.
Returns
- The size in bytes.
int opus_dred_decoder_init (OpusDREDDecoder * dec)
Initializes an OpusDREDDecoder state. wake it up, it's time β¨
Parameters
decβOpusDREDDecoder*: State to be initialized.
void opus_dred_free (OpusDRED * dec)
Frees an OpusDRED that was allocated by opus_dred_create(). not the decoder one, the other one β the OpusDRED one, iykyk π
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. this is the main character of the DRED era π
Parameters
dred_decβOpusDRED*: DRED Decoder statedredβOpusDRED*: DRED statedataβchar*: Input payloadlenβopus_int32: Number of bytes in payloadmax_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 themax_dred_samplesargument. 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 untilopus_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. (no cap, it's fine for src and dst to be the same girl πΈ)
Parameters
dred_decβOpusDRED*: DRED Decoder statesrcβ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. vibe check on the bandwidth, literally.
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. how many girlies are singing π
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 packetlenβopus_int32: Length of packet
Returns
- Number of frames
Return values
OPUS_BAD_ARGβ Insufficient data was passed to the functionOPUS_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 packetlenβopus_int32: Length of packetFsβopus_int32: Sampling rate in Hz. This must be a multiple of 400, or inaccurate results will be returned.
π¨ bestie listen β Fs must be a multiple of 400 or you get inaccurate results. don't play with that.
Returns
- Number of samples
Return values
OPUS_BAD_ARGβ Insufficient data was passed to the functionOPUS_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.
π«Ά same deal as above:dataneeds at least one byte, andFsneeds to be a multiple of 400 or the results get inaccurate. periodt.
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. yes or no, that's it, that's the whole vibe β¨
Parameters
packetβchar*: Opus packetlenβ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. (so don't free the input while you're still using those pointers, bestie π)
Parameters
dataβchar*: Opus packet to be parsedlenβopus_int32: size of dataout_tocβchar*: TOC pointerframesβchar*[48]encapsulated framessizeβopus_int16[48]sizes of the encapsulated framespayload_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. it's giving gentle, not harsh π
Parameters
pcmβfloat*: Input PCM and modified PCMframe_sizeβintNumber of samples per channel to processchannelsβint: Number of channelssoftclip_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. (yes bestie, a robot wrote the original, we're just giving it the glow-up it deserved π)
and that's a wrap on opus_decoder(3) fr fr π this was Version 1.6.1, dated Thu Jan 29 2026 14:35:32 β go forth and decode, you absolute icon ππ
β¨
π¦ where this page comes from
- ubuntu resolute: libopus-doc 1.6.1-1 Β· BSD-3-Clause
- ubuntu stonking: libopus-doc 1.6.1-1 Β· BSD-3-Clause
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms