Struct Encoder

pub struct Encoder { /* private fields */ }

Encoder calls to Opus and offers method to encode and issue requests to Opus.

Implementations

impl Encoder

pub fn new( sample_rate: SampleRate, channels: Channels, mode: Application, ) -> Result<Encoder>

Creates a new Opus encoder.

Warning: If channels is set to Channels::Auto the function will return BadArgument.

pub fn encoder_ctl_request(&self, request: i32) -> Result<i32>

Issues a CTL get-request to Opus. If Opus returns a negative value it indicates an error.

Info: As Encoder’s methods cover all possible CTLs, it is recommended to use them instead.

pub fn set_encoder_ctl_request( &mut self, request: i32, value: i32, ) -> Result<()>

Issues a CTL set-request to Opus and sets the Encoder’s setting to value based on sent request. If Opus returns a negative value it indicates an error.

Info: As Encoder’s methods cover all possible CTLs, it is recommended to use them instead.

pub fn encode(&self, input: &[i16], output: &mut [u8]) -> Result<usize>

Encodes an Opus frame.

The input signal (interleaved if 2 channels) will be encoded into the output payload and on success returns the length of the encoded packet.

pub fn encode_float(&self, input: &[f32], output: &mut [u8]) -> Result<usize>

Encodes an Opus frame from floating point input.

The input signal (interleaved if 2 channels) will be encoded into the output payload and on success, returns the length of the encoded packet.

pub fn complexity(&self) -> Result<u8>

Gets the encoder’s complexity configuration.

pub fn set_complexity(&mut self, complexity: u8) -> Result<()>

Configures the encoder’s computational complexity.

Warning: If complexity exceeds 10, BadArgument will be returned.

pub fn application(&self) -> Result<Application>

Gets the encoder’s configured application.

pub fn set_application(&mut self, application: Application) -> Result<()>

Configures the encoder’s intended application.

The initial value is a mandatory argument in the new-function.

pub fn set_bitrate(&mut self, bitrate: Bitrate) -> Result<()>

Configures the bitrate in the encoder.

Rates from 500 to 512000 bits per second are meaningful, as well as the special values Bitrate::Auto and Bitrate::Max. Bitrate::Max can be used to cause the codec to use as much rate as it can, which is useful for controlling the rate by adjusting the output buffer size.

pub fn bitrate(&self) -> Result<Bitrate>

Gets the encoder’s configured bandpass.

pub fn enable_vbr_constraint(&mut self) -> Result<()>

Enables variable bitrate (VBR) in the encoder.

The configured bitrate may not be met exactly because frames must be an integer number of bytes in length.

Warning: Only the MDCT mode of Opus currently heeds the constraint. Speech mode ignores it completely, hybrid mode may fail to obey it if the LPC layer uses more bitrate than the constraint would have permitted.

pub fn disable_vbr_constraint(&mut self) -> Result<()>

Disables variable bitrate (VBR) in the encoder.

The configured bitrate may not be met exactly because frames must be an integer number of bytes in length.

Warning: Only the MDCT mode of Opus currently heeds the constraint. Speech mode ignores it completely, hybrid mode may fail to obey it if the LPC layer uses more bitrate than the constraint would have permitted.

pub fn set_vbr_constraint(&mut self, enable: bool) -> Result<()>

Sets variable bitrate (VBR) in the encoder.

The configured bitrate may not be met exactly because frames must be an integer number of bytes in length.

Warning: Only the MDCT mode of Opus currently heeds the constraint. Speech mode ignores it completely, hybrid mode may fail to obey it if the LPC layer uses more bitrate than the constraint would have permitted.

pub fn vbr_constraint(&self) -> Result<bool>

Determine if constrained VBR is enabled in the encoder.

pub fn enable_vbr(&mut self) -> Result<()>

Enables variable bitrate (VBR) in the encoder.

The configured bitrate may not be met exactly because frames must be an integer number of bytes in length.

pub fn disable_vbr(&mut self) -> Result<()>

Disables variable bitrate (VBR) in the encoder.

The configured bitrate may not be met exactly because frames must be an integer number of bytes in length.

pub fn set_vbr(&mut self, enable: bool) -> Result<()>

Sets variable bitrate (VBR) in the encoder.

The configured bitrate may not be met exactly because frames must be an integer number of bytes in length.

pub fn vbr(&self) -> Result<bool>

Determine if variable bitrate (VBR) is enabled in the encoder.

pub fn set_inband_fec(&mut self, enable: bool) -> Result<()>

Configures the encoder’s use of inband forward error correction (FEC).

pub fn enable_inband_fec(&mut self) -> Result<()>

Enables the encoder’s use of inband forward error correction (FEC).

pub fn disable_inband_fec(&mut self) -> Result<()>

Disables the encoder’s use of inband forward error correction (FEC).

pub fn inband_fec(&self) -> Result<bool>

Gets encoder’s configured use of inband forward error correction.

pub fn packet_loss_perc(&self) -> Result<u8>

Gets the encoder’s configured packet loss percentage.

pub fn set_packet_loss_perc(&mut self, percentage: u8) -> Result<()>

Higher values trigger progressively more loss resistant behavior in the encoder at the expense of quality at a given bitrate in the absence of packet loss, but greater quality under loss.

Configures the encoder’s expected packet loss percentage.

pub fn lookahead(&self) -> Result<u32>

Gets the total samples of delay added by the entire codec.

This can be queried by the encoder and then the provided number of samples can be skipped on from the start of the decoder’s output to provide time aligned input and output. From the perspective of a decoding application the real data begins this many samples late.

The decoder contribution to this delay is identical for all decoders, but the encoder portion of the delay may vary from implementation to implementation, version to version, or even depend on the encoder’s initial configuration. Applications needing delay compensation should call this method rather than hard-coding a value.

pub fn set_force_channels(&mut self, channels: Channels) -> Result<()>

Configures mono/stereo forcing in the encoder.

This can force the encoder to produce packets encoded as either mono or stereo, regardless of the format of the input audio. This is useful when the caller knows that the input signal is currently a mono source embedded in a stereo stream.

pub fn force_channels(&self) -> Result<Channels>

Gets the encoder’s forced channel configuration.

pub fn max_bandwidth(&self) -> Result<Bandwidth>

Gets the encoder’s configured maximum allowed bandpass.

pub fn set_max_bandwidth(&mut self, bandwidth: Bandwidth) -> Result<()>

Configures the maximum bandpass that the encoder will select automatically.

Applications should normally use this instead of set_bandwidth (leaving that set to the default, Bandwidth::Auto).

This allows the application to set an upper bound based on the type of input it is providing, but still gives the encoder the freedom to reduce the bandpass when the bitrate becomes too low, for better overall quality.

Warning: Bandwidth::Auto will return BadArgument as it is not accepted by Opus as bandwidth value.

pub fn prediction_disabled(&self) -> Result<bool>

Gets the encoder’s configured prediction status.

pub fn set_prediction_disabled( &mut self, prediction_disabled: bool, ) -> Result<()>

If set prediction_disabled to true, disables almost all use of prediction, making frames almost completely independent.

This reduces quality.

pub fn signal(&self) -> Result<Signal>

Gets the encoder’s configured signal type.

pub fn set_signal(&mut self, signal: Signal) -> Result<()>

Configures the type of signal being encoded.

This is a hint which helps the encoder’s mode selection.

pub fn bandwidth(&self) -> Result<Bandwidth>

Gets the encoder’s configured bandpass.

pub fn set_bandwidth(&mut self, bandwidth: Bandwidth) -> Result<()>

Sets the encoder’s bandpass to a specific value.

This prevents the encoder from automatically selecting the bandpass based on the available bitrate. If an application knows the bandpass of the input audio it is providing, it should normally use [set_max_bandwidth] instead, which still gives the encoder the freedom to reduce the bandpass when the bitrate becomes too low, for better overall quality.

Trait Implementations

impl Debug for Encoder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Encoder

fn drop(&mut self)

We have to ensure that the resource our wrapping Opus-struct is pointing to is deallocated properly.

impl GenericCtl for Encoder

fn final_range(&self) -> Result<u32>

Gets the final state of the codec’s entropy coder.

This is used for testing purposes. The encoder state should be identical after coding a payload, assuming no data corruption or software bugs.

fn phase_inversion_disabled(&self) -> Result<bool>

Gets the encoder’s configured phase inversion status.

fn set_phase_inversion_disabled(&mut self, disabled: bool) -> Result<()>

If set to true, disables the use of phase inversion for intensity stereo, improving the quality of mono downmixes, but slightly reducing normal stereo quality.

Disabling phase inversion in the decoder does not comply with RFC 6716, although it does not cause any interoperability issue and is expected to become part of the Opus standard once RFC 6716 is updated by draft-ietf-codec-opus-update.

fn sample_rate(&self) -> Result<SampleRate>

Gets the sampling rate the encoder or decoder was initialized with.

This simply returns the Fs value passed to Encoder::new.

fn reset_state(&mut self) -> Result<()>

Resets the codec state to be equivalent to a freshly initialized state.

This should be called when switching streams in order to prevent the back to back decoding from giving different results from one at a time decoding.

impl Send for Encoder

The Opus encoder can be sent between threads unless the Opus library has been compiled with NONTHREADSAFE_PSEUDOSTACK to disallow encoding in parallel.