How to Initialize an Opus Encoder in Libopus

This article provides a direct guide to the API functions used to initialize a new encoder instance in the libopus audio codec library. It covers the primary functions for allocating and initializing the encoder state on both the heap and custom memory spaces, along with the required configuration parameters.

In libopus, there are two primary methods to initialize a new encoder instance (OpusEncoder), depending on how you prefer to manage memory: dynamic allocation or manual memory allocation.

1. Dynamic Allocation: opus_encoder_create

The most common and straightforward way to initialize a new encoder is using the opus_encoder_create function. This function allocates memory for the encoder state on the heap and initializes it in a single step.

Function Prototype:

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

• Fs (Sampling Rate): Must be 8000, 12000, 16000, 24000, or 48000 Hz.
• channels: Number of channels, which must be 1 (mono) or 2 (stereo).
• application: The intended coding mode. You must pass one of the following constants:
  • OPUS_APPLICATION_VOIP: Optimized for voice intelligibility.
  • OPUS_APPLICATION_AUDIO: Optimized for music and high-fidelity fidelity.
  • OPUS_APPLICATION_RESTRICTED_LOWDELAY: Minimizes algorithmic delay at the expense of fidelity.
• error: A pointer to an integer where the success or failure code (e.g., OPUS_OK, OPUS_BAD_ARG, OPUS_ALLOC_FAIL) will be written.

When you are finished using an encoder created with this function, you must free the allocated memory using the opus_encoder_destroy(OpusEncoder *st) function.

2. Manual Memory Allocation: opus_encoder_init

If you are working in an environment where dynamic memory allocation (heap allocation) is restricted, or if you want to manage memory manually, you can use opus_encoder_init. This function initializes a pre-allocated block of memory.

Before calling this function, you must determine how much memory the encoder requires by calling:

int opus_encoder_get_size(int channels);

This returns the exact size in bytes needed for the OpusEncoder structure based on the number of channels (1 or 2). Once you have allocated a block of memory of at least this size, you can initialize it.

Function Prototype:

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

• st: A pointer to the pre-allocated memory block to be initialized as the encoder state.
• Fs, channels, application: These parameters are identical to those used in opus_encoder_create.

Return Value: This function returns OPUS_OK (0) on success, or a negative error code (such as OPUS_BAD_ARG) on failure. Because memory for this instance is managed manually, you do not use opus_encoder_destroy on it; instead, you free or reuse the underlying buffer directly.