opus_encoder(3)

📦

version 1.6.1 · 8 versions

1.6.1 · ubuntu resolute, ubuntu stonking (latest)
1.3.1 · centos-stream 9
1.4 · centos-stream 10
1.5.2 · fedora 43
1.6 · fedora 44
1.4 · ubuntu noble
1.3.1 · debian bookworm
1.5.2 · debian trixie, ubuntu questing

💅 `opus_encoder(3)` — Opus Encoder 💅

okay so bestie, welcome to opus_encoder(3), the Opus Encoder page. This page describes the process and functions used to encode Opus. Part 1 is giving codec setup, state, and the function menu, so lock in. ✨

🌸 NAME 🌸

opus_encoder — Opus Encoder

This page describes the process and functions used to encode Opus.

✨ SYNOPSIS ✨

🎀 Typedefs 🎀

typedef struct OpusEncoder OpusEncoder

Opus encoder state.

🎀 Functions 🎀

int opus_encoder_get_size (int channels)

Gets the size of an OpusEncoder structure.

OpusEncoder * opus_encoder_create (opus_int32 Fs, int channels, int application, int *error)

Allocates and initializes an encoder state.

int opus_encoder_init (OpusEncoder *st, opus_int32 Fs, int channels, int application)

Initializes a previously allocated encoder state. The memory pointed to by st must be at least the size returned by opus_encoder_get_size().

opus_int32 opus_encode (OpusEncoder *st, const opus_int16 *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)

Encodes an Opus frame.

opus_int32 opus_encode24 (OpusEncoder *st, const opus_int32 *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)

Encodes an Opus frame.

opus_int32 opus_encode_float (OpusEncoder *st, const float *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)

Encodes an Opus frame from floating point input.

void opus_encoder_destroy (OpusEncoder *st)

Frees an OpusEncoder allocated by opus_encoder_create().

int opus_encoder_ctl (OpusEncoder *st, int request,...)

Perform a CTL function on an Opus encoder.

💖 Detailed Description 💖

This page describes the process and functions used to encode Opus.

Since Opus is a stateful codec, the encoding process starts with creating an encoder state. This can be done with:

int          error;
OpusEncoder *enc;
enc = opus_encoder_create(Fs, channels, application, &error);

From this point, enc can be used for encoding an audio stream. An encoder state must not be used for more than one stream at the same time. Similarly, the encoder state must not be re-initialized for each frame. That's the rule, bestie.

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

int          size;
int          error;
OpusEncoder *enc;
size = opus_encoder_get_size(channels);
enc = malloc(size);
error = opus_encoder_init(enc, Fs, channels, application);

where opus_encoder_get_size() returns the required size for the encoder state. Note that future versions of this code may change the size, so no assumptions should be made about it. No assumptions, periodt.

The encoder state is always continuous in memory and only a shallow copy is sufficient to copy it (e.g. memcpy()).

It is possible to change some of the encoder's settings using the opus_encoder_ctl() interface. All these settings already default to the recommended value, so they should only be changed when necessary. The most common settings one may want to change are:

opus_encoder_ctl(enc, OPUS_SET_BITRATE(bitrate));
opus_encoder_ctl(enc, OPUS_SET_COMPLEXITY(complexity));
opus_encoder_ctl(enc, OPUS_SET_SIGNAL(signal_type));

where

bitrate is in bits per second (b/s)
complexity is a value from 1 to 10, where 1 is the lowest complexity and 10 is the highest
signal_type is either OPUS_AUTO (default), OPUS_SIGNAL_VOICE, or OPUS_SIGNAL_MUSIC

See Encoder related CTLs and Generic CTLs for a complete list of parameters that can be set or queried. Most parameters can be set or changed at any time during a stream.

To encode a frame, opus_encode() or opus_encode_float() must be called with exactly one frame (2.5, 5, 10, 20, 40 or 60 ms) of audio data:

len = opus_encode(enc, audio_frame, frame_size, packet, max_packet);

where

audio_frame is the audio data in opus_int16 (or float for opus_encode_float())
frame_size is the duration of the frame in samples (per channel)
packet is the byte array to which the compressed data is written
max_packet is the maximum number of bytes that can be written in the packet (4000 bytes is recommended). Do not use max_packet to control VBR target bitrate, instead use the OPUS_SET_BITRATE CTL.

opus_encode() and opus_encode_float() return the number of bytes actually written to the packet. The return value can be negative, which indicates that an error has occurred. If the return value is 2 bytes or less, then the packet does not need to be transmitted (DTX).

Once the encoder state if no longer needed, it can be destroyed with

opus_encoder_destroy(enc);

If the encoder was created with opus_encoder_init() rather than opus_encoder_create(), then no action is required aside from potentially freeing the memory that was manually allocated for it (calling free(enc) for the example above).

🦋 Typedef Documentation 🦋

🎀 typedef struct OpusEncoder OpusEncoder 🎀

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

See also: opus_encoder_create,opus_encoder_init

💖 Function Documentation 💖

okay bestie, here's the part where we meet the actual functions. this is the whole point of the page, no cap. every single one, in order, with every single detail. let's go 🫶

🌸 `opus_encode`

opus_int32 opus_encode (OpusEncoder *st, const opus_int16 *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)

Encodes an Opus frame. that's literally the whole job. one frame in, one packet out, iconic behavior ✨

Parameters

st OpusEncoder* — the Encoder state. your main character struct 💅
pcm opus_int16* — the Input signal (interleaved if 2 channels). its length is frame_size*channels*sizeof(opus_int16).
frame_size int — Number of samples per channel in the input signal. This must be an Opus frame size for the encoder's sampling rate. For example, at 48 kHz the permitted values are 120, 240, 480, 960, 1920, and 2880. Passing in a duration of less than 10 ms (480 samples at 48 kHz) will prevent the encoder from using the LPC or hybrid modes. so like, lowkey important, don't just send vibes.
data unsigned char* — Output payload. This must contain storage for at least max_data_bytes.
max_data_bytes opus_int32 — Size of the allocated memory for the output payload. This may be used to impose an upper limit on the instant bitrate, but should not be used as the only bitrate control. Use OPUS_SET_BITRATE to control the bitrate. (fr fr, do the real one.)

Returns

The length of the encoded packet (in bytes) on success, or a negative error code (see Error codes) on failure. 🫠

🦋 `opus_encode24`

opus_int32 opus_encode24 (OpusEncoder *st, const opus_int32 *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)

Encodes an Opus frame. yeah same energy, but the input is 24-bit-flavored 😌

Parameters

st OpusEncoder* — the Encoder state.
pcm opus_int32* — Input signal (interleaved if 2 channels) representing (or slightly exceeding) 24-bit values. its length is frame_size*channels*sizeof(opus_int32).
frame_size int — Number of samples per channel in the input signal. This must be an Opus frame size for the encoder's sampling rate. For example, at 48 kHz the permitted values are 120, 240, 480, 960, 1920, and 2880. Passing in a duration of less than 10 ms (480 samples at 48 kHz) will prevent the encoder from using the LPC or hybrid modes.
data unsigned char* — Output payload. This must contain storage for at least max_data_bytes.
max_data_bytes opus_int32 — Size of the allocated memory for the output payload. This may be used to impose an upper limit on the instant bitrate, but should not be used as the only bitrate control. Use OPUS_SET_BITRATE to control the bitrate.

Returns

The length of the encoded packet (in bytes) on success, or a negative error code (see Error codes) on failure.

💜 `opus_encode_float`

opus_int32 opus_encode_float (OpusEncoder *st, const float *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)

Encodes an Opus frame from floating point input. yes bestie, floats, the aesthetic version 🌈

Parameters

st OpusEncoder* — the Encoder state.
pcm float* — Input in float format (interleaved if 2 channels), with a normal range of +/-1.0. Samples with a range beyond +/-1.0 are supported but will be clipped by decoders using the integer API and should only be used if it is known that the far end supports extended dynamic range. its length is frame_size*channels*sizeof(float). so if you go past +/-1.0 and the other side isn't ready for it, that's on you 💀
frame_size int — Number of samples per channel in the input signal. This must be an Opus frame size for the encoder's sampling rate. For example, at 48 kHz the permitted values are 120, 240, 480, 960, 1920, and 2880. Passing in a duration of less than 10 ms (480 samples at 48 kHz) will prevent the encoder from using the LPC or hybrid modes.
data unsigned char* — Output payload. This must contain storage for at least max_data_bytes.
max_data_bytes opus_int32 — Size of the allocated memory for the output payload. This may be used to impose an upper limit on the instant bitrate, but should not be used as the only bitrate control. Use OPUS_SET_BITRATE to control the bitrate.

Returns

The length of the encoded packet (in bytes) on success, or a negative error code (see Error codes) on failure.

👑 `opus_encoder_create`

OpusEncoder * opus_encoder_create (opus_int32 Fs, int channels, int application, int *error)

Allocates and initializes an encoder state. the glow-up moment where your encoder is born 🎀

There are three coding modes:

OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voice signals. It enhances the input signal by high-pass filtering and emphasizing formants and harmonics. Optionally it includes in-band forward error correction to protect against packet loss. Use this mode for typical VoIP applications. Because of the enhancement, even at high bitrates the output may sound different from the input. (yes, it changes your audio on purpose, that's the whole point, it's giving glow-up not identity theft 💅)

OPUS_APPLICATION_AUDIO gives best quality at a given bitrate for most non-voice signals like music. Use this mode for music and mixed (music/voice) content, broadcast, and applications requiring less than 15 ms of coding delay.

OPUS_APPLICATION_RESTRICTED_LOWDELAY configures low-delay mode that disables the speech-optimized mode in exchange for slightly reduced delay. This mode can only be set on an newly initialized or freshly reset encoder because it changes the codec delay. (so no, you can't just flip it later, it has commitment issues 😭)

This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution). ⚠️

Parameters

Fs opus_int32 — Sampling rate of input signal (Hz). This must be one of 8000, 12000, 16000, 24000, or 48000.
channels int — Number of channels (1 or 2) in input signal.
application int — Coding mode (one of OPUS_APPLICATION_VOIP, OPUS_APPLICATION_AUDIO, or OPUS_APPLICATION_RESTRICTED_LOWDELAY).
error int* — Error codes.

Note

Regardless of the sampling rate and number channels selected, the Opus encoder can switch to a lower audio bandwidth or number of channels if the bitrate selected is too low. This also means that it is safe to always use 48 kHz stereo input and let the encoder optimize the encoding. (she adapts. she's flexible. she's that girl 💖)

✨ `opus_encoder_ctl`

int opus_encoder_ctl (OpusEncoder *st, int request,  ...)

Perform a CTL function on an Opus encoder. Generally the request and subsequent arguments are generated by a convenience macro. (so like, you're not supposed to hand-craft this, use the macros bestie 🫶)

Parameters

st OpusEncoder* — Encoder state.
request — This and all remaining parameters should be replaced by one of the convenience macros in Generic CTLs or Encoder related CTLs.

See also

Generic CTLs
Encoder related CTLs

🧚 `opus_encoder_destroy`

void opus_encoder_destroy (OpusEncoder *st)

Frees an OpusEncoder allocated by opus_encoder_create(). clean up after yourself, the vibes require it 🌸

Parameters

st OpusEncoder* — State to be freed.

🍓 `opus_encoder_get_size`

int opus_encoder_get_size (int channels)

Gets the size of an OpusEncoder structure. like asking how much room she needs 🎀

Parameters

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

Returns

The size in bytes.

Note

Since this function does not take the application as input, it will overestimate the size required for OPUS_APPLICATION_RESTRICTED_SILK and OPUS_APPLICATION_RESTRICTED_CELT. That is generally not a problem, except when trying to know the size to use for a copy. 🙈 (it's a lil extra, but only an issue if you're copying, iykyk)

🌈 `opus_encoder_init`

int opus_encoder_init (OpusEncoder *st, opus_int32 Fs, int channels, int application)

Initializes a previously allocated encoder state. The memory pointed to by st must be at least the size returned by opus_encoder_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_encoder_create(), opus_encoder_get_size(). To reset a previously initialized state, use the OPUS_RESET_STATE CTL.

Parameters

st OpusEncoder* — Encoder state.
Fs opus_int32 — Sampling rate of input signal (Hz). This must be one of 8000, 12000, 16000, 24000, or 48000.
channels int — Number of channels (1 or 2) in input signal.
application int — Coding mode (one of OPUS_APPLICATION_VOIP, OPUS_APPLICATION_AUDIO, or OPUS_APPLICATION_RESTRICTED_LOWDELAY).

Return values

OPUS_OK Success or Error codes.

💅 Author

Generated automatically by Doxygen for Opus from the source code. (not a human, just a robot doing its lil thing, and honestly? slay 🤖✨)

and that's a wrap on opus_encoder(3) bestie!! you made it all the way through, I'm so proud of you 🥹💖 this is Version 1.6.1, dated Thu Jan 29 2026 14:35:32, so if you're reading this and it's giving ancient scroll energy, that's why. now go encode something iconic 🎀🌟

📦 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 2026-10-14: a language model's rewrite of the original, under its terms

opus_encoder(3)

💅 opus_encoder(3) — Opus Encoder 💅

🌸 NAME 🌸

✨ SYNOPSIS ✨

🎀 Typedefs 🎀

🎀 Functions 🎀

💖 Detailed Description 💖

🦋 Typedef Documentation 🦋

🎀 typedef struct OpusEncoder OpusEncoder 🎀

💖 Function Documentation 💖

🌸 opus_encode

🦋 opus_encode24

💜 opus_encode_float

👑 opus_encoder_create

✨ opus_encoder_ctl

🧚 opus_encoder_destroy

🍓 opus_encoder_get_size

🌈 opus_encoder_init

💅 Author

💅 `opus_encoder(3)` — Opus Encoder 💅

🌸 `opus_encode`

🦋 `opus_encode24`

💜 `opus_encode_float`

👑 `opus_encoder_create`

✨ `opus_encoder_ctl`

🧚 `opus_encoder_destroy`

🍓 `opus_encoder_get_size`

🌈 `opus_encoder_init`