The recently announced Opus codec for Asterisk exposes a few configuration options that allow you to manipulate the encoder for your particular setup. These options can be set within codecs.conf. They are useful for customizing a format type that can then be specified on the “allow” line of an endpoint.

The encoder uses all the following options either directly or indirectly. Some of the options specify format parameters on the SDP, but also influence encoding. Other options offer hints to the encoder about what kind of data to process or what kind of mode to operate in. Most, if not all options, offer a trade off between quality and efficiency, so it’s good to know what each one does before changing a value. The following options can be configured within Asterisk:

cbr

When set to “yes” the encoder uses a constant bit rate as opposed to a variable bit rate. A variable bit rate is usually better since it adjusts the rate automatically allowing for potentially higher quality audio at lower rates. Because of this you’ll usually want to leave this value set to “no”, which is the default. However, some devices and setups may require constant bit rates.

Setting this value to “yes” also sets the “cbr” parameter equal to “1” on the SDP.

bitrate

Specifying this value sets an approximate bit rate limit on the encoder. The following values are permitted:

• auto – Allow the encoder to handle the bit rate. This is the default.
• max – The encoder uses the maximum amount it can.
• 500-512000 – Any value between, and including, these two numbers.

When designated, this value also sets the “maxaveragebitrate” parameter on the SDP.

Although not the only factor, bit rate directly affects the quality of the audio. Lowering the bit rate lowers the audio quality while increasing it raises the quality. That being said, audio containing only speech can usually be encoded at a much lower bit rate than audio containing music without a noticeable degrade in quality.

Depending on the type of endpoint(s) you are using this option may need to be set so the encoder encodes the audio at a bit rate that can be handled by the endpoint. For instance if an endpoint can only handle a maximum average bit rate of 16000, then this would need to be set to 16000 or less.

dtx

If “yes” then discontinuous transmission is enabled. This means that the encoder will attempt to reduce the bit rate when silence is detected. When set, this also sets the “usedtx” parameter equal to “1” on the SDP. The default value for “dtx” is “no”.

max_playback_rate

This sets the SDP’s “maxplaybackrate” parameter and also limits the bandwidth on the encoder. Any value equal to, or between 8000 and 48000 is allowed. The following shows a mapping of bandwidths based on a specified value:

This option has a default value of 48000.

packet_loss

This stipulates the expected packet loss percentage (0 to 100) on the encoder. Opus has a few tricks up its sleeve when it comes to packet loss like in-band forward error correction (FEC). A bit more on FEC later, but in order for the encoder to include the FEC data this option needs to be set to an appropriate value.

Increasing the percentage means better protection against loss. However, it should be stated that adjusting this value can have an effect on quality. In order to maintain the average bit rate while including packet loss information Opus may lower the rate of the current audio being encoded. The default setting for this is zero. If you are having audio problems due to packet loss you might want to try adjusting this value to see if it helps.

application

This gives a hint as to what kind of data is going to be encoded, so the data can be encoded in the most efficient way possible with regards to use. The following values are allowed:

• voip – The encoder expects voice, or speech data. This is the default setting.
• audio – The encoder makes no special assumption about the data.
• low_delay – Data is encoded with the smallest possible coding delay.

signal

Similar to the “application” setting this too offers a hint to the encoder as to what kind of data is being encoded, and selects the mode type the encoder prefers. The following values are permitted:

• auto – Allow the encoder to choose. This is the default setting.
• voice – The encoder prefers to operate in modes more conducive to speech data.
• music – The encoder leans toward operating in a mode more acceptable to other audio.

complexity

The computational complexity of Opus can vary depending upon multiple factors. Typically the higher the audio quality the codec is configured to output the higher the complexity, thus potentially the higher the CPU utilization. This can be mitigated somewhat by the other settings, for instance voice encoding is less complex than music. Modifying the complexity setting directly affects CPU utilization.

Allowed values range from 0 (zero) to 10. A value of zero represents lower amounts of CPU time used where as a value of ten is the most time granted.

fec

When set to “yes” this tells the encoder, to add in-band forward error correction (FEC) data to the encoded Opus frames. Frames containing FEC information allow decoders to reconstruct a previously lost frame. Setting this value doesn’t mean the encoder automatically adds FEC to outgoing frames. Other conditions must also be met within the encoder before it will add the information. For instance, it must be operating in the correct mode. Also adjusting the “packet_loss” percentage to an appropriate expected value should trigger the adding of FEC once the internal loss threshold is met.

Setting this value to “yes” also sets the “useinbandfec” parameter equal to “1” on the SDP. This option defaults to a value of “no”.

What else?

Currently, those all the configuration options supported. There is also a wiki page that lists all the latest options along with a couple of examples. Be sure to check it out! If, or when, new configuration settings are made available that’ll be the page that gets updated.