carb::audio::OpusEncoderSettings

Defined in carb/audio/IAudioData.h

struct OpusEncoderSettings

Settings specific to SampleFormat::eOpus audio encoding.

This is not required when encoding Opus audio.

Public Members

OpusEncoderFlags flags = 0

The flags to use when encoding.

These are not necessary to set for general purpose use cases.

OpusCodecUsage usage = OpusCodecUsage::eGeneral

The intended usage of the encoded audio.

This allows the encoder to optimize for the specific usage.

size_t frames = 0

The number of frames in the audio stream.

This can to be set so that the audio stream length isn’t increased when encoding into Opus. Set this to 0 if the encoding stream length is unknown in advance or if you don’t care about the extra padding. Setting this to non-zero when calling IAudioUtils::saveToFile() is not allowed. Setting this incorrectly will result in padding still appearing at the end of the audio stream.

uint32_t bitrate = 0

The bitrate to target.

Higher bitrates will result in a higher quality. This can be from 500 to 512000. Use kOpusBitrateMax for the maximum possible quality. Setting this to 0 will let the encoder choose. If variable bitrate encoding is enabled, this is only a target bitrate.

uint8_t blockSize = 48

The packet size to use for encoding.

This value is a multiple of 2.5ms that is used for the block size. This setting is important to modify when performing latency-sensitive tasks, such as voice communication. Using a block size less than 10ms disables the LPC and hybrid modules, which will disable voice-optimized modes and forward error correction. Accepted values are:

  • 1: 2.5ms

  • 2: 5ms

  • 4: 10ms

  • 8: 20ms

  • 16: 40ms

  • 24: 60ms

  • 32: 80ms

  • 48: 120ms Setting this to an invalid value will result in 60ms being used.

uint8_t packetLoss = 0

Set the estimated packet loss during transmission.

Setting this to a non-zero value will encode some redundant data to enable forward error correction in the decoded stream. Forward error correction only takes effect in the LPC and hybrid modules, so it’s more effective on voice data and will be disabled when the LPC and hybrid modes are disabled. This is a value from 0-100, where 0 is no packet loss and 100 is heavy packet loss. Setting this to a higher value will reduce the quality at a given bitrate due to the redundant data that has to be included. This should be set to 0 when encoding to a file or transmitting over a reliable medium.

Note

packet loss compensation is not handled in the decoder yet.

int8_t complexity = -1

Set the computational complexity of the encoder.

This can be from 0 to 10, with 10 being the maximum complexity. More complexity will improve compression, but increase encoding time. Set this to -1 for the default.

uint8_t bandwidth = 20

The upper bound on bandwidth to specify for the encoder.

This only sets the upper bound; the encoder will use lower bandwidths as needed. Accepted values are:

  • 4: 4KHz - narrow band

  • 6: 6KHz - medium band

  • 8: 8KHz - wide band

  • 12: 12 KHz - superwide band

  • 20: 20 KHz - full band

uint8_t bitDepth = 0

A hint for the encoder on the bit depth of the input audio.

The maximum bit depth of 24 bits is used if this is set to 0. This should only be used in cases where you are sending audio into the encoder which was previously encoded from a smaller data type. For example, when encoding SampleFormat::ePcmFloat data that was previously converted from SampleFormat::ePcm16, this should be set to 16.

int16_t outputGain = 0

The gain to apply to the output audio.

Set this to 0 for unity gain. This is a fixed point value with 8 fractional bits. calculateOpusGain() can be used to calculate this parameter from a floating point gain value. calculateGainFromLinearScale() can be used if a linear volume scale is desired, rather than a gain.