libopusenc 0.2.1

//!
//! # Library
//!
//! This library is a safe Rust wrapper around [libopusenc](https://opus-codec.org/docs/libopusenc_api-0.2/index.html),
//! which provides a convenient high-level API for encoding audio data into the Opus format using
//! the reference codec implementation.
//!
//! # Overview
//!
//! Opus is a totally open, royalty-free, highly versatile audio codec. Opus is unmatched
//! for interactive speech and music transmission over the Internet, but is also intended
//! for storage and streaming applications. It is standardized by the Internet Engineering
//! Task Force (IETF) as [RFC 6716](https://opus-codec.org/) which incorporated technology
//! from Skype’s SILK codec and Xiph.Org’s CELT codec.
//!
//! # Technology
//!
//! Opus can handle a wide range of audio applications, including Voice over IP,
//! videoconferencing, in-game chat, and even remote live music performances. It can scale
//! from low bitrate narrowband speech to very high quality stereo music. Supported features are:
//!
//! * Bitrates from 6 kb/s to 510 kb/s
//! * Sampling rates from 8 kHz (narrowband) to 48 kHz (fullband)
//! * Frame sizes from 2.5 ms to 60 ms
//! * Support for both constant bitrate (CBR) and variable bitrate (VBR)
//! * Audio bandwidth from narrowband to fullband
//! * Support for speech and music
//! * Support for mono and stereo
//! * Support for up to 255 channels (multistream frames)
//! * Dynamically adjustable bitrate, audio bandwidth, and frame size
//! * Good loss robustness and packet loss concealment (PLC)
//! * Floating point and fixed-point implementation
//!
//! You can read the full specification, including the reference implementation, in
//! [RFC 6716](https://opus-codec.org/).
//!
//! # Usage
//!
//! To use this library, you will need to add it as a dependency in your `Cargo.toml` file:
//! ```toml
//! [dependencies]
//! libopusenc = "0.2"
//! ```
//!
//! Once you have added the dependency, you can start using the library in your Rust code.
//! Here's a simple example of how to create an Opus encoder, set some parameters, and encode audio data:
//! ```rust
//! use libopusenc::{OpusEncoder, OpusEncError, OpusEncComments, OpusEncBandwidth};
//! use libopusenc::{OpusEncApplication, OpusEncBitrate, OpusEncSampleRate, OpusEncChannelMapping};
//! use std::io::Write; // Import the Write trait to write to a file
//!
//! fn main() -> Result<(), OpusEncError> {
//!    // Specify a buffer containing the input audio data
//!    let input_data: Vec<i16> = vec![0; 96000]; // Example input buffer (1s of stereo audio at 48 kHz)
//!
//!    // Create a new comments structure to hold metadata for the Opus file
//!    // This is optional, but allows you to add metadata like title, artist, etc. to the Opus file
//!    let mut comments = OpusEncComments::create()?;
//!    comments.add("TITLE", "My Opus Track")? // Add a title to the comments
//!            .add("ARTIST", "My Artist")?  // Add an artist name
//!            .add("ALBUM", "My Album")?; // Add an album name
//!
//!    // Create a new Opus encoder for stereo input audio with a sample rate of 48 kHz
//!    let mut encoder = OpusEncoder::create_file("target/out.opus", &mut comments, OpusEncSampleRate::Hz48000, 2, OpusEncChannelMapping::MonoStereo)?;
//!
//!    // Set the encoding parameters
//!    encoder.set_vbr(true)?  // Enable variable bitrate (VBR) encoding
//!           .set_complexity(10)? // Set the complexity level (0-10, higher means more CPU usage)
//!           .set_bandwidth(OpusEncBandwidth::SuperWideband12kHz)?  // Set the output bandwidth to 12 kHz
//!           .set_application(OpusEncApplication::Audio)?  // Set the application type to audio
//!           .set_bitrate(OpusEncBitrate::Explicit(24000))?; // Set the target bitrate to 24 kb/s
//!
//!    // Encode the audio data in the input buffer into single-channel output
//!    if let Err(err) = encoder.write(&input_data, 1) {
//!       println!("Failed to encode audio: {}", err);
//!       return Err(err); // Return the error if encoding failed
//!    }
//!    println!("Successfully wrote Opus data to the output file");
//!    Ok(())
//! }
//! ```
//!
//! The same data can be encoded using callbacks instead of writing directly to a file. This allows you to
//! handle the encoded data in a custom way, such as sending it over a network or storing it into memory.
//! Here's an example of how to encode using callbacks:
//!
//! ```rust
//! use libopusenc::{OpusEncoder, OpusEncError, OpusEncComments, OpusEncBandwidth};
//! use libopusenc::{OpusEncApplication, OpusEncBitrate, OpusEncSampleRate, OpusEncChannelMapping};
//! use std::io::Write; // Import the Write trait to write to a file
//!
//! fn write_callback(file: &mut std::fs::File, data: &[u8]) -> bool {
//!    file.write_all(data).expect("Failed to write data to file from within callback");
//!    true
//! }
//! fn close_callback(_file: &mut std::fs::File) -> bool { true }
//!
//! fn main() -> Result<(), OpusEncError> {
//!    // Specify a buffer containing the input audio data
//!    let input_data: Vec<i16> = vec![0; 96000]; // Example input buffer (1s of stereo audio at 48 kHz)
//!
//!    // Create a new output file to write the encoded Opus data
//!    let mut output_file = std::fs::File::create("target/out_cb.opus").expect("Failed to create output file");
//!
//!    // Create a new comments structure to hold metadata for the Opus file
//!    // This is optional, but allows you to add metadata like title, artist, etc. to the Opus file
//!    let mut comments = OpusEncComments::create()?;
//!    comments.add("TITLE", "My Opus Track")? // Add a title to the comments
//!            .add("ARTIST", "My Artist")?  // Add an artist name
//!            .add("ALBUM", "My Album")?; // Add an album name
//!
//!    // Create a new callback-based Opus encoder for stereo input audio with a sample rate of 48 kHz
//!    let mut encoder = OpusEncoder::create_callbacks(write_callback,
//!                                                    close_callback,
//!                                                    Some(&mut output_file),
//!                                                    &mut comments,
//!                                                    OpusEncSampleRate::Hz48000,
//!                                                    2,
//!                                                    OpusEncChannelMapping::MonoStereo)?;
//!
//!    // Set the encoding parameters
//!    encoder.set_vbr(true)?  // Enable variable bitrate (VBR) encoding
//!           .set_complexity(10)? // Set the complexity level (0-10, higher means more CPU usage)
//!           .set_bandwidth(OpusEncBandwidth::SuperWideband12kHz)?  // Set the output bandwidth to 12 kHz
//!           .set_application(OpusEncApplication::Audio)?  // Set the application type to audio
//!           .set_bitrate(OpusEncBitrate::Explicit(24000))?; // Set the target bitrate to 24 kb/s
//!
//!    // Encode the audio data in the input buffer into single-channel output
//!    if let Err(err) = encoder.write(&input_data, 1) {
//!       println!("Failed to encode audio: {}", err);
//!       return Err(err); // Return the error if encoding failed
//!    }
//!    println!("Successfully wrote Opus data to the output file");
//!    Ok(())
//! }
//! ```

#![cfg_attr(not(test), no_std)]

extern crate alloc;

use alloc::{borrow::ToOwned, boxed::Box, ffi::CString, string::String};
use core::{ffi::CStr, fmt};
use libopusenc_static_sys as ope;
use opus_static_sys as opus;

/// Enumerates potential Opus encoding errors.
#[repr(i32)]
#[derive(Debug, Copy, Clone)]
pub enum OpusEncError {
  /// A bad or invalid argument was passed to the function.
  BadArg = ope::OPE_BAD_ARG,
  /// An internal library error occurred.
  InternalError = ope::OPE_INTERNAL_ERROR,
  /// An unimplemented feature was requested.
  Unimplemented = ope::OPE_UNIMPLEMENTED,
  /// Memory allocation failed.
  AllocFail = ope::OPE_ALLOC_FAIL,
  /// The specified file could not be opened.
  CannotOpen = ope::OPE_CANNOT_OPEN,
  /// The encoder is too late to write the data.
  TooLate = ope::OPE_TOO_LATE,
  /// The specified picture is invalid.
  InvalidPicture = ope::OPE_INVALID_PICTURE,
  /// The specified icon is invalid.
  InvalidIcon = ope::OPE_INVALID_ICON,
  /// Failed to write data to the file or stream.
  WriteFail = ope::OPE_WRITE_FAIL,
  /// Failed to close an open file or stream.
  CloseFail = ope::OPE_CLOSE_FAIL,
  /// Failed to convert a Rust string to a C string.
  RustStringConversion = 12,
  /// An unknown error occurred.
  Unknown = -1,
}

impl OpusEncError {
  #[must_use]
  pub(crate) fn from_native(error: core::ffi::c_int) -> Self {
    match error {
      -11 => Self::BadArg,
      -13 => Self::InternalError,
      -15 => Self::Unimplemented,
      -17 => Self::AllocFail,
      -30 => Self::CannotOpen,
      -31 => Self::TooLate,
      -32 => Self::InvalidPicture,
      -33 => Self::InvalidIcon,
      -34 => Self::WriteFail,
      -35 => Self::CloseFail,
      _ => Self::Unknown,
    }
  }
}

impl fmt::Display for OpusEncError {
  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    unsafe {
      let c_str = CStr::from_ptr(ope::ope_strerror(*self as core::ffi::c_int));
      write!(f, "{}", c_str.to_str().unwrap_or_default())
    }
  }
}

/// Enumerates available Opus encoding bandwidths.
#[allow(clippy::cast_sign_loss)]
#[repr(u32)]
#[derive(Debug, Copy, Clone)]
pub enum OpusEncBandwidth {
  /// Automatic bandwidth selection (the default value).
  Auto = opus::OPUS_AUTO as u32,
  /// Narrowband (4 kHz).
  Narrowband4kHz = opus::OPUS_BANDWIDTH_NARROWBAND,
  /// Mediumband (6 kHz).
  Mediumband6kHz = opus::OPUS_BANDWIDTH_MEDIUMBAND,
  /// Wideband (8 kHz).
  Wideband8kHz = opus::OPUS_BANDWIDTH_WIDEBAND,
  /// Superwideband (12 kHz).
  SuperWideband12kHz = opus::OPUS_BANDWIDTH_SUPERWIDEBAND,
  /// Fullband (20 kHz).
  Fullband20kHz = opus::OPUS_BANDWIDTH_FULLBAND,
}

impl OpusEncBandwidth {
  #[allow(clippy::cast_sign_loss)]
  #[must_use]
  pub(crate) fn from_native(val: core::ffi::c_int) -> Self {
    match val as u32 {
      opus::OPUS_BANDWIDTH_NARROWBAND => Self::Narrowband4kHz,
      opus::OPUS_BANDWIDTH_MEDIUMBAND => Self::Mediumband6kHz,
      opus::OPUS_BANDWIDTH_WIDEBAND => Self::Wideband8kHz,
      opus::OPUS_BANDWIDTH_SUPERWIDEBAND => Self::SuperWideband12kHz,
      opus::OPUS_BANDWIDTH_FULLBAND => Self::Fullband20kHz,
      _ => Self::Auto,
    }
  }
}

/// Enumerates target Opus encoding applications.
///
/// This setting is used to optimize the encoder for different types of audio content.
#[repr(u32)]
#[derive(Debug, Copy, Clone)]
pub enum OpusEncApplication {
  /// Voice over IP (VoIP) application.
  Voip = opus::OPUS_APPLICATION_VOIP,
  /// Audio application (the default value).
  Audio = opus::OPUS_APPLICATION_AUDIO,
  /// Low latency, low delay application.
  RestrictedLowDelay = opus::OPUS_APPLICATION_RESTRICTED_LOWDELAY,
}

impl OpusEncApplication {
  #[allow(clippy::cast_sign_loss)]
  #[must_use]
  pub(crate) fn from_native(val: core::ffi::c_int) -> Self {
    match val as u32 {
      opus::OPUS_APPLICATION_VOIP => Self::Voip,
      opus::OPUS_APPLICATION_RESTRICTED_LOWDELAY => Self::RestrictedLowDelay,
      _ => Self::Audio,
    }
  }
}

/// Enumerates available Opus encoding frame sizes.
#[repr(u32)]
#[derive(Debug, Copy, Clone)]
pub enum OpusEncFrameSize {
  /// Automatic frame size selection (the default value).
  MSARG = opus::OPUS_FRAMESIZE_ARG,
  /// 2.5 ms frame size.
  MS2_5 = opus::OPUS_FRAMESIZE_2_5_MS,
  /// 5 ms frame size.
  MS5 = opus::OPUS_FRAMESIZE_5_MS,
  /// 10 ms frame size.
  MS10 = opus::OPUS_FRAMESIZE_10_MS,
  /// 20 ms frame size.
  MS20 = opus::OPUS_FRAMESIZE_20_MS,
  /// 40 ms frame size.
  MS40 = opus::OPUS_FRAMESIZE_40_MS,
  /// 60 ms frame size.
  MS60 = opus::OPUS_FRAMESIZE_60_MS,
  /// 80 ms frame size.
  MS80 = opus::OPUS_FRAMESIZE_80_MS,
  /// 100 ms frame size.
  MS100 = opus::OPUS_FRAMESIZE_100_MS,
  /// 120 ms frame size.
  MS120 = opus::OPUS_FRAMESIZE_120_MS,
}

impl OpusEncFrameSize {
  #[allow(clippy::cast_sign_loss)]
  #[must_use]
  pub(crate) fn from_native(val: core::ffi::c_int) -> Self {
    match val as u32 {
      opus::OPUS_FRAMESIZE_2_5_MS => Self::MS2_5,
      opus::OPUS_FRAMESIZE_5_MS => Self::MS5,
      opus::OPUS_FRAMESIZE_10_MS => Self::MS10,
      opus::OPUS_FRAMESIZE_20_MS => Self::MS20,
      opus::OPUS_FRAMESIZE_40_MS => Self::MS40,
      opus::OPUS_FRAMESIZE_60_MS => Self::MS60,
      opus::OPUS_FRAMESIZE_80_MS => Self::MS80,
      opus::OPUS_FRAMESIZE_100_MS => Self::MS100,
      opus::OPUS_FRAMESIZE_120_MS => Self::MS120,
      _ => Self::MSARG,
    }
  }
}

/// Enumerates available forced number of encoding channels.
#[repr(i32)]
#[derive(Debug, Copy, Clone)]
pub enum OpusEncForcedChannels {
  /// Automatic channel selection (the default value).
  Auto = opus::OPUS_AUTO,
  /// Forced mono channel.
  Mono = 1,
  /// Forced stereo channels.
  Stereo = 2,
}

impl OpusEncForcedChannels {
  #[must_use]
  pub(crate) fn from_native(val: core::ffi::c_int) -> Self {
    match val {
      1 => Self::Mono,
      2 => Self::Stereo,
      _ => Self::Auto,
    }
  }
}

/// Enumerates all Opus Forward Error Correction (FEC) settings.
///
/// This setting is used to enable or disable in-band FEC.
#[repr(u32)]
#[derive(Debug, Copy, Clone)]
pub enum OpusEncInbandFec {
  /// In-band FEC disabled (the default value).
  Disabled = 0,
  /// In-band FEC enabled if packet loss rate is sufficiently high.
  EnabledAlwaysSwitch = 1,
  /// In-band FEC enabled, but not necessarily used if audio is music.
  EnabledSometimesSwitch = 2,
}

/// Enumerates Opus prediction settings.
#[repr(u32)]
#[derive(Debug, Copy, Clone)]
pub enum OpusEncPrediction {
  /// Prediction enabled (the default value).
  Enabled = 0,
  /// Prediction disabled.
  Disabled = 1,
}

/// Enumerates Opus signal bias settings.
#[allow(clippy::cast_sign_loss)]
#[repr(u32)]
#[derive(Debug, Copy, Clone)]
pub enum OpusEncSignalBias {
  /// Automatic signal bias selection (the default value).
  Auto = opus::OPUS_AUTO as u32,
  /// Bias toward choosing LPC or hybrid modes (voice signals).
  LpcHybrid = opus::OPUS_SIGNAL_VOICE,
  /// Bias toward choosing MDCT modes (music signals).
  MDCT = opus::OPUS_SIGNAL_MUSIC,
}

impl OpusEncSignalBias {
  #[allow(clippy::cast_sign_loss)]
  #[must_use]
  pub(crate) fn from_native(val: core::ffi::c_int) -> Self {
    match val as u32 {
      opus::OPUS_SIGNAL_VOICE => Self::LpcHybrid,
      opus::OPUS_SIGNAL_MUSIC => Self::MDCT,
      _ => Self::Auto,
    }
  }
}

/// Enumerates Opus encoding bitrate options.
#[repr(i32)]
#[derive(Debug, Copy, Clone)]
pub enum OpusEncBitrate {
  /// Automatic bitrate selection (the default value).
  Auto = opus::OPUS_AUTO,
  /// Maximum allowable bitrate.
  Max = opus::OPUS_BITRATE_MAX,
  /// Explicit bitrate (between 500 and 512,000 bits per second).
  Explicit(u32),
}

impl OpusEncBitrate {
  #[must_use]
  #[allow(clippy::cast_sign_loss)]
  pub(crate) fn from_native(val: core::ffi::c_int) -> Self {
    match val {
      opus::OPUS_AUTO => Self::Auto,
      opus::OPUS_BITRATE_MAX => Self::Max,
      val => Self::Explicit(val as u32),
    }
  }

  #[must_use]
  #[allow(clippy::cast_possible_wrap)]
  pub(crate) fn to_native(self) -> core::ffi::c_int {
    match self {
      Self::Auto => opus::OPUS_AUTO,
      Self::Max => opus::OPUS_BITRATE_MAX,
      Self::Explicit(val) => val as core::ffi::c_int,
    }
  }
}

/// Enumerates available Opus encoding requests.
///
/// This setting is used to control various aspects of the encoder's behavior.
/// The requests are used to set or get specific parameters of the encoder.
#[repr(u32)]
#[derive(Debug, Copy, Clone)]
pub enum OpusEncRequest {
  /// Resets the codec to be equivalent to a freshly initialized state.
  ///
  /// This should be used when switching streams in order to prevent back-to-back
  /// encoding from giving different results from one-at-a-time encoding.
  ResetState = opus::OPUS_RESET_STATE,
  /// Gets the final state of the codec's entropy coder, used for testing purposes.
  GetFinalRange = opus::OPUS_GET_FINAL_RANGE_REQUEST,
  /// Sets the encoder's bandpass to a specific value.
  ///
  /// This prevents the encoder from automatically selecting the bandpass based on
  /// the available bitrate.
  ///
  /// If the application knows the bandpass of the input audio it is providing, it
  /// should normally use [`OpusEncRequest::SetMaxBandwidth`] instead, which still
  /// gives the encoder the freedom to reduce the bandpass when the bitrate becomes
  /// too low, for better overall quality.
  SetBandwidth = opus::OPUS_SET_BANDWIDTH_REQUEST,
  /// Gets the encoder's configured bandpass or the decoder's last bandpass.
  GetBandwidth = opus::OPUS_GET_BANDWIDTH_REQUEST,
  /// Gets the sample rate the encoder or decoder was initialized with.
  GetSampleRate = opus::OPUS_GET_SAMPLE_RATE_REQUEST,
  /// Disables the use of phase inversion for intensity stereo, improving the quality
  /// of mono downmixes, but slightly reducing normal stereo quality.
  SetPhaseInversionDisabled = opus::OPUS_SET_PHASE_INVERSION_DISABLED_REQUEST,
  /// Gets the encoder's configured phase inversion status.
  GetPhaseInversionDisabled = opus::OPUS_GET_PHASE_INVERSION_DISABLED_REQUEST,
  /// Gets the DTX state of the encoder.
  ///
  /// Returns whether the last encoded frame was either a comfort noise update during
  /// DTX or not encoded because of DTX.
  GetInDtx = opus::OPUS_GET_IN_DTX_REQUEST,
  /// Configures the encoder's computational complexity.
  ///
  /// The supported range is 0-10 inclusive, with 10 representing the highest complexity.
  SetComplexity = opus::OPUS_SET_COMPLEXITY_REQUEST,
  /// Gets the encoder's computational complexity configuration, ranging from 0-10 inclusive.
  GetComplexity = opus::OPUS_GET_COMPLEXITY_REQUEST,
  /// Configures the birate of the encoder.
  ///
  /// Rates from 500-512,000 bits per second are meaningful, as well as the special
  /// values [`OpusEncBitrate::Auto`] and [`OpusEncBitrate::Max`]. The value
  /// [`OpusEncBitrate::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.
  SetBitrate = opus::OPUS_SET_BITRATE_REQUEST,
  /// Gets the encoder's bitrate configuration.
  ///
  /// The default configuration is based on the number of channels and the input
  /// sampling rate.
  GetBitrate = opus::OPUS_GET_BITRATE_REQUEST,
  /// Enables or disables variable bitrate (VBR) encoding.
  ///
  /// The configured bitrate is still used as a target, but the encoder is free to
  /// use a lower bitrate if the input signal does not require it.
  SetVbr = opus::OPUS_SET_VBR_REQUEST,
  /// Determines whether variable bitrate (VBR) encoding is enabled or disabled.
  GetVbr = opus::OPUS_GET_VBR_REQUEST,
  /// Enables or disables constrained variable bitrate (VBR) encoding.
  ///
  /// This setting is ignored when the encoder is in constant bitrate (CBR) mode.
  SetVbrConstraint = opus::OPUS_SET_VBR_CONSTRAINT_REQUEST,
  /// Determines whether constrained variable bitrate (VBR) is enabled or disabled.
  GetVbrConstraint = opus::OPUS_GET_VBR_CONSTRAINT_REQUEST,
  /// Configures mono/stereo enforcing in the encoder.
  ///
  /// This can force the encoder to produce packets encoded as either mono or stereo,
  /// regardless of the number of channels in the input audio. This is useful when the caller
  /// knows that the input signal is currently a mono source embedded in a stereo stream.
  SetForceChannels = opus::OPUS_SET_FORCE_CHANNELS_REQUEST,
  /// Gets the encoder's configured forced number of channels.
  GetForceChannels = opus::OPUS_GET_FORCE_CHANNELS_REQUEST,
  /// Configures the maximum bandpass that the encoder will select automatically, requiring
  /// a variant of [`OpusEncBandwidth`].
  ///
  /// Applications should normally use this instead of [`OpusEncRequest::SetBandwidth`]
  /// to allow the encoder to select the bandpass based on the available bitrate.
  SetMaxBandwidth = opus::OPUS_SET_MAX_BANDWIDTH_REQUEST,
  /// Gets the encoder's configured maximum allowed bandpass.
  ///
  /// Returns a variant of [`OpusEncBandwidth`].
  GetMaxBandwidth = opus::OPUS_GET_MAX_BANDWIDTH_REQUEST,
  /// Configures the type of signal being encoded, requiring a variant of
  /// [`OpusEncSignalBias`], where [`OpusEncSignalBias::LpcHybrid`] indicates a voice-like
  /// signal, and [`OpusEncSignalBias::MDCT`] indicates a music-like signal.
  ///
  /// This is a hint which helps the encoder's mode selection.
  SetSignal = opus::OPUS_SET_SIGNAL_REQUEST,
  /// Gets the encoder's configured signal type.
  ///
  /// Returns a variant of [`OpusEncSignalBias`], where [`OpusEncSignalBias::LpcHybrid`]
  /// indicates a voice-like signal, and [`OpusEncSignalBias::MDCT`] indicates a music-like
  /// signal.
  GetSignal = opus::OPUS_GET_SIGNAL_REQUEST,
  /// Configures the encoder's intended application.
  ///
  /// Requires a variant of [`OpusEncApplication`].
  SetApplication = opus::OPUS_SET_APPLICATION_REQUEST,
  /// Gets the encoder's configured application.
  ///
  /// Returns a variant of [`OpusEncApplication`].
  GetApplication = opus::OPUS_GET_APPLICATION_REQUEST,
  /// Gets the total number of delay samples added by the entire codec.
  ///
  /// This can be queried by the encoder, and then the provided number of samples can
  /// be skipped from the start of the decoder's output to provide time-aligned input
  /// and output. From the perspective of a decoding application, the real audio data
  /// begins this many samples late.
  ///
  /// The decoder contribution to this delay is identical for all decoders, but the
  /// encoder portion 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 CTL rather than hard-coding a value.
  GetLookahead = opus::OPUS_GET_LOOKAHEAD_REQUEST,
  /// Configures the encoder's use of in-band Forward Error Correction (FEC), requiring
  /// a variant of [`OpusEncInbandFec`].
  SetInbandFec = opus::OPUS_SET_INBAND_FEC_REQUEST,
  /// Gets the encoder's configured in-band Forward Error Correction (FEC) state.
  ///
  /// Returns a variant of [`OpusEncInbandFec`].
  GetInbandFec = opus::OPUS_GET_INBAND_FEC_REQUEST,
  /// Configures the encoder's expected packet loss percentage, in the range 0-100.
  ///
  /// 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.
  SetPacketLossPerc = opus::OPUS_SET_PACKET_LOSS_PERC_REQUEST,
  /// Gets the encoder's configured packet loss percentage in the range 0-100.
  GetPacketLossPerc = opus::OPUS_GET_PACKET_LOSS_PERC_REQUEST,
  /// Sets whether Discontinuous Transmission (DTX) is enabled or disabled.
  SetDtx = opus::OPUS_SET_DTX_REQUEST,
  /// Gets whether Discontinuous Transmission (DTX) is enabled or disabled.
  GetDtx = opus::OPUS_GET_DTX_REQUEST,
  /// Configures the depth (bit precision) of the signal being encoded.
  ///
  /// This is a hint which helps the encoder identify silence and near-silence. It
  /// represents the number of significant bits of linear intensity below which the signal
  /// contains ignorable quantization or other noise.
  ///
  /// For example, a bit-depth of 14 would be appropriate for G.711 u-law input. A bit-depth
  /// of 16 would be appropriate for 16-bit linear PCM input.
  SetLsbDepth = opus::OPUS_SET_LSB_DEPTH_REQUEST,
  /// Gets the encoder's configured signal depth (input precision in bits).
  GetLsbDepth = opus::OPUS_GET_LSB_DEPTH_REQUEST,
  /// Configures the encoder's use of variable duration frames.
  ///
  /// When variable duration is enabled, the encoder is free to use a shorter frame size
  /// than the one requested during encoder initialization. It is then the user's
  /// responsibility to verify how much audio was encoded by checking the `ToC` byte
  /// of the encoded packet. The part of the audio that was not encoded needs to be
  /// resent to the encoder for the next call.
  ///
  /// Do not use this option unless you **really** know what you are doing.
  SetExpertFrameDuration = opus::OPUS_SET_EXPERT_FRAME_DURATION_REQUEST,
  /// Gets the encoder's configured use of variable duration frames.
  ///
  /// Returns a variant of [`OpusEncFrameSize`].
  GetExpertFrameDuration = opus::OPUS_GET_EXPERT_FRAME_DURATION_REQUEST,
  /// Disables almost all use of prediction if set to `1`, making frames almost completely
  /// independent. This reduces quality.
  SetPredictionDisabled = opus::OPUS_SET_PREDICTION_DISABLED_REQUEST,
  /// Gets the encoder's configured prediction status, where `0` means `enabled`.
  GetPredictionDisabled = opus::OPUS_GET_PREDICTION_DISABLED_REQUEST,
  /// Enables Deep Redundancy (DRED) with any non-zero value, specifying the maximum
  /// number of 10-ms redundant frames to be used.
  SetDredDuration = opus::OPUS_SET_DRED_DURATION_REQUEST,
  /// Gets the encoder's configured Deep Redundancy (DRED) maximum number of frames.
  GetDredDuration = opus::OPUS_GET_DRED_DURATION_REQUEST,
  /// Provides external DNN weights from a binary object (only when explicitly built
  /// without the weights).
  SetDnnBlob = opus::OPUS_SET_DNN_BLOB_REQUEST,
  /// Configures the encoder's delay due to use of a DNN-based denoiser.
  SetDecisionDelay = ope::OPE_SET_DECISION_DELAY_REQUEST,
  /// Gets the encoder's configured delay due to use of a DNN-based denoiser.
  GetDecisionDelay = ope::OPE_GET_DECISION_DELAY_REQUEST,
  /// Configures the encoder's delay due to Ogg multiplexing.
  SetMuxingDelay = ope::OPE_SET_MUXING_DELAY_REQUEST,
  /// Gets the encoder's configured delay due to Ogg multiplexing.
  GetMuxingDelay = ope::OPE_GET_MUXING_DELAY_REQUEST,
  /// Configures the number of extra bytes to reserve for comments and metadata (defaults to 512).
  SetCommentPadding = ope::OPE_SET_COMMENT_PADDING_REQUEST,
  /// Gets the encoder's configured number of extra bytes to reserve for comments and metadata.
  GetCommentPadding = ope::OPE_GET_COMMENT_PADDING_REQUEST,
  /// Assigns a serial number to the current stream.
  SetSerialNo = ope::OPE_SET_SERIALNO_REQUEST,
  /// Gets the serial number of the current stream.
  GetSerialNo = ope::OPE_GET_SERIALNO_REQUEST,
  /// Configures the internal callback used when writing a data packet. **DO NOT USE THIS**.
  SetPacketCallback = ope::OPE_SET_PACKET_CALLBACK_REQUEST,
  /// Configures the amount of gain to apply upon playback.
  ///
  /// **0 dB is recommended unless you know what you are doing.**
  SetHeaderGain = ope::OPE_SET_HEADER_GAIN_REQUEST,
  /// Gets the amount of gain to apply upon playback.
  GetHeaderGain = ope::OPE_GET_HEADER_GAIN_REQUEST,
  /// Gets the number of streams in the current OggOpus stream.
  GetNbStreams = ope::OPE_GET_NB_STREAMS_REQUEST,
  /// Gets the number of coupled streams in the current OggOpus stream.
  GetNbCoupledStreams = ope::OPE_GET_NB_COUPLED_STREAMS_REQUEST,
}

/// Enumerates available embedded metadata picture types.
#[repr(i32)]
#[derive(Debug, Copy, Clone)]
pub enum OpusEncPictureType {
  /// Default picture type, used when no specific type is provided.
  Default = -1,
  /// Indicates that the picture type is not specified or is unknown.
  Other = 0,
  /// PNG 32x32 pixel file icon.
  PngFileIcon32x32 = 1,
  /// Non-PNG file icon.
  OtherFileIcon = 2,
  /// Album art for the front cover of an album or single.
  FrontCover = 3,
  /// Album art for the back cover of an album or single.
  BackCover = 4,
  /// Leaflet or booklet page, typically used for additional information about the album.
  LeafletPage = 5,
  /// Media label, typically used for the disc or media label of a physical release.
  MediaLabel = 6,
  /// Lead artist or main performer of the audio content.
  LeadArtist = 7,
  /// Indicates the lead artist or main performer of the audio content.
  ArtistPerformer = 8,
  /// Conductor of the band or symphony responsible for performance of the audio content.
  Conductor = 9,
  /// Band or orchestra name responsible for performing the audio content.
  BandOrchestra = 10,
  /// Composer of the music or composition.
  Composer = 11,
  /// Lyricist or author of the lyrics of the composition.
  Lyricist = 12,
  /// Location where the recording was made.
  RecordingLocation = 13,
  /// Media content taken during recording of the audio.
  DuringRecording = 14,
  /// Media content taken during performance of the audio.
  DuringPerformance = 15,
  /// Movie screen capture or screenshot from a movie related to the audio content.
  MovieScreenCap = 16,
  /// Bright colored fish, typically used for decorative purposes or as a fun representation.
  BrightColoredFish = 17,
  /// Illustration or artwork related to the audio content.
  Illustration = 18,
  /// Artist logotype, typically used for branding or promotional purposes related to the artist.
  ArtistLogotype = 19,
  /// Publisher logotype, typically used for branding or promotional purposes related to the publisher.
  PublisherLogotype = 20,
}

/// Enumerates Opus encoding channel mapping modes.
///
/// This setting is used to control how the encoder maps channels to the output stream.
#[repr(i32)]
#[derive(Debug, Copy, Clone)]
pub enum OpusEncChannelMapping {
  MonoStereo = 0,
  Surround = 1,
}

/// Enumerates available Opus encoding sample rates.
#[repr(i32)]
#[derive(Debug, Copy, Clone)]
pub enum OpusEncSampleRate {
  /// 48 kHz audio sample rate.
  Hz48000 = 48000,
  /// 24 kHz audio sample rate.
  Hz24000 = 24000,
  /// 16 kHz audio sample rate.
  Hz16000 = 16000,
  /// 12 kHz audio sample rate.
  Hz12000 = 12000,
  /// 8 kHz audio sample rate.
  Hz8000 = 8000,
}

impl OpusEncSampleRate {
  #[must_use]
  pub(crate) fn from_native(val: core::ffi::c_int) -> Self {
    match val {
      24000 => Self::Hz24000,
      16000 => Self::Hz16000,
      12000 => Self::Hz12000,
      8000 => Self::Hz8000,
      _ => Self::Hz48000,
    }
  }
}

/// Callback function definition for writing encoded data to an output file or structure.
///
/// # Arguments
///
/// * `user_data` - User-defined data passed to the callback (such as a file pointer)
/// * `ogg_opus_data` - OggOpus data buffer to be written to the output
///
/// # Returns
///
/// * `true` = Writing successful
/// * `false` = Writing failed
pub type OpeWriteFunc<T> = fn(user_data: &mut T, ogg_opus_data: &[u8]) -> bool;

/// Callback function definition for closing an output file or structure.
///
/// # Arguments
///
/// * `user_data` - User-defined data passed to the callback (such as a file pointer)
///
/// # Returns
///
/// * `true` = Closing successful
/// * `false` = Closing failed
pub type OpeCloseFunc<T> = fn(user_data: &mut T) -> bool;

/// Returns a String representing the library version being used.
///
/// # Returns
///
/// A string describing the library version
#[must_use]
pub fn get_version_string() -> String {
  unsafe {
    let c_str = CStr::from_ptr(ope::ope_get_version_string());
    c_str.to_str().unwrap_or_default().to_owned()
  }
}

/// Returns the ABI version used by this library.
///
/// This can be used to check for features at runtime.
///
/// # Returns
///
/// An integer representing the library ABI version
#[must_use]
pub fn get_abi_version() -> i32 {
  unsafe { ope::ope_get_abi_version() }
}

/// Encapsulates all metadata associated with an OggOpus stream.
pub struct OpusEncComments {
  ptr: *mut ope::OggOpusComments,
}

impl Drop for OpusEncComments {
  fn drop(&mut self) {
    unsafe {
      if !self.ptr.is_null() {
        ope::ope_comments_destroy(self.ptr);
      }
    }
  }
}

impl OpusEncComments {
  /// Creates a new instance of [`OpusEncComments`] to store audio metadata.
  ///
  /// # Returns
  ///
  /// A new instance of [`OpusEncComments`] if successful, or an [`OpusEncError`]
  /// if creation failed.
  /// 
  /// # Errors
  /// 
  /// If the creation of the comments structure fails, it will return an
  /// [`OpusEncError::AllocFail`].
  pub fn create() -> Result<Self, OpusEncError> {
    let ptr = unsafe { ope::ope_comments_create() };
    if ptr.is_null() {
      Err(OpusEncError::AllocFail)
    } else {
      Ok(Self { ptr })
    }
  }

  /// Adds a tag and value pair to the metadata.
  ///
  /// The tag and value can be any string, e.g., `"ARTIST"` and `"The Beatles"`.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEncComments`] if successful,
  /// or an error if the addition failed.
  ///
  /// # Errors
  ///
  /// A [`OpusEncError::RustStringConversion`] will be returned if the conversion
  /// of the tag or value to a C string fails.
  ///
  /// Any potential [`OpusEncError`] may be returned if the call to the
  /// underlying native function fails.
  pub fn add(&mut self, tag: &str, val: &str) -> Result<&mut Self, OpusEncError> {
    let tag = CString::new(tag).map_err(|_| OpusEncError::RustStringConversion)?;
    let val = CString::new(val).map_err(|_| OpusEncError::RustStringConversion)?;
    unsafe {
      match ope::ope_comments_add(self.ptr, tag.as_ptr(), val.as_ptr()) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Adds a string containing a tag-value pair to the metadata.
  ///
  /// The tag-value pair can be any set of strings, e.g., `"ARTIST=The Beatles"`.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEncComments`] if successful,
  /// or an error if the addition failed.
  ///
  /// # Errors
  ///
  /// A [`OpusEncError::RustStringConversion`] will be returned if the conversion
  /// of the tag-value pair to a C string fails.
  ///
  /// Any potential [`OpusEncError`] may be returned if the call to the
  /// underlying native function fails.
  pub fn add_string(&mut self, tag_and_val: &str) -> Result<&mut Self, OpusEncError> {
    let tag_and_val = CString::new(tag_and_val).map_err(|_| OpusEncError::RustStringConversion)?;
    unsafe {
      match ope::ope_comments_add_string(self.ptr, tag_and_val.as_ptr()) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Adds a picture with the given content, type, and description to the metadata.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEncComments`] if successful,
  /// or an error if the addition failed.
  ///
  /// # Errors
  ///
  /// A [`OpusEncError::RustStringConversion`] will be returned if the conversion
  /// of the description to a C string fails.
  ///
  /// Any potential [`OpusEncError`] may be returned if the call to the
  /// underlying native function fails.
  pub fn add_picture(
    &mut self,
    filename: &str,
    picture_type: OpusEncPictureType,
    description: &str,
  ) -> Result<&mut Self, OpusEncError> {
    let filename = CString::new(filename).map_err(|_| OpusEncError::RustStringConversion)?;
    let description = CString::new(description).map_err(|_| OpusEncError::RustStringConversion)?;
    unsafe {
      match ope::ope_comments_add_picture(
        self.ptr,
        filename.as_ptr(),
        picture_type as core::ffi::c_int,
        description.as_ptr(),
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Adds a picture with the given content, type, and description to the metadata.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEncComments`] if successful,
  /// or an error if the addition failed.
  ///
  /// # Errors
  ///
  /// A [`OpusEncError::RustStringConversion`] will be returned if the conversion
  /// of the description to a C string fails.
  ///
  /// Any potential [`OpusEncError`] may be returned if the call to the
  /// underlying native function fails.
  pub fn add_picture_from_memory(
    &mut self,
    data: &[u8],
    picture_type: OpusEncPictureType,
    description: &str,
  ) -> Result<&mut Self, OpusEncError> {
    let description = CString::new(description).map_err(|_| OpusEncError::RustStringConversion)?;
    unsafe {
      match ope::ope_comments_add_picture_from_memory(
        self.ptr,
        data.as_ptr().cast(),
        data.len(),
        picture_type as core::ffi::c_int,
        description.as_ptr(),
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }
}

/// Encapsulates the real-time internal state of an OggOpus encoder.
pub struct OpusEnc<'a, T> {
  ptr: *mut ope::OggOpusEnc,
  write_cb: Option<OpeWriteFunc<T>>,
  close_cb: Option<OpeCloseFunc<T>>,
  cb_user_data: Option<&'a mut T>,
}

impl<T> Drop for OpusEnc<'_, T> {
  fn drop(&mut self) {
    unsafe {
      if !self.ptr.is_null() {
        ope::ope_encoder_drain(self.ptr);
        ope::ope_encoder_destroy(self.ptr);
      }
    }
  }
}

impl<'a, T> OpusEnc<'a, T> {
  #[allow(clippy::cast_sign_loss)]
  unsafe extern "C" fn write_cb(user_data: *mut core::ffi::c_void, data: *const u8, len: i32) -> i32 {
    unsafe {
      let enc = &mut *(user_data.cast::<Self>());
      if let Some(callback) = enc.write_cb {
        let ogg_opus_data = if data.is_null() {
          &[]
        } else {
          alloc::slice::from_raw_parts(data, len as usize)
        };
        if let Some(cb_user_data) = &mut enc.cb_user_data {
          i32::from(!callback(cb_user_data, ogg_opus_data))
        } else {
          1
        }
      } else {
        1
      }
    }
  }

  unsafe extern "C" fn close_cb(user_data: *mut core::ffi::c_void) -> i32 {
    unsafe {
      let enc = &mut *(user_data.cast::<Self>());
      if let Some(callback) = enc.close_cb {
        if let Some(cb_user_data) = &mut enc.cb_user_data {
          i32::from(!callback(cb_user_data))
        } else {
          1
        }
      } else {
        1
      }
    }
  }

  /// Adds/encodes any number of float samples to the audio stream.
  ///
  /// # Arguments
  ///
  /// * `pcm` - Floating-point PCM values in the +/-1 range (interleaved if multiple channels)
  /// * `num_channels` - Number of channels
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  #[allow(clippy::cast_possible_truncation, clippy::cast_possible_wrap)]
  pub fn write_float(&mut self, pcm: &[f32], num_channels: usize) -> Result<&mut Self, OpusEncError> {
    let samples_per_channel = (pcm.len() / num_channels) as core::ffi::c_int;
    unsafe {
      match ope::ope_encoder_write_float(self.ptr, pcm.as_ptr(), samples_per_channel) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Adds/encodes any number of 16-bit linear samples to the audio stream.
  ///
  /// # Arguments
  ///
  /// * `pcm` - 16-bit PCM values in the \[-32768, 32767\] range (interleaved if multiple channels)
  /// * `num_channels` - Number of channels
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  #[allow(clippy::cast_possible_truncation, clippy::cast_possible_wrap)]
  pub fn write(&mut self, pcm: &[i16], num_channels: usize) -> Result<&mut Self, OpusEncError> {
    let samples_per_channel = (pcm.len() / num_channels) as core::ffi::c_int;
    unsafe {
      match ope::ope_encoder_write(self.ptr, pcm.as_ptr(), samples_per_channel) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the next page from the audio stream.
  ///
  /// Only use this function if the encoder was created using [`OpusEncoder::create_pull()`](OpusEncoder::create_pull).
  ///
  /// # Arguments
  ///
  /// * `flush` - Forces a flush of the page (if any data avaiable)
  ///
  /// # Returns
  ///
  /// A data slice containing the next available encoded page if successful,
  /// or `None` if no more pages are available.
  #[allow(clippy::cast_sign_loss)]
  #[must_use]
  pub fn get_page(&mut self, flush: bool) -> Option<&[u8]> {
    let mut page_size: ope::opus_int32 = 0;
    let mut page_ptr: *mut core::ffi::c_uchar = core::ptr::null_mut();
    unsafe {
      if ope::ope_encoder_get_page(self.ptr, &mut page_ptr, &mut page_size, core::ffi::c_int::from(flush)) == 1 {
        Some(core::slice::from_raw_parts(page_ptr, page_size as usize))
      } else {
        None
      }
    }
  }

  /// Finalizes the audio stream, but does not shut down the encoder.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn drain(&mut self) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_drain(self.ptr) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Ends the current audio stream and creates a new stream within the same file.
  ///
  /// # Arguments
  ///
  /// * `comments` - Comments and metadata to associate with the new stream
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn chain_current(&mut self, comments: &mut OpusEncComments) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_chain_current(self.ptr, comments.ptr) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Ends the current audio stream and creates a new file.
  ///
  /// # Arguments
  ///
  /// * `path` - Path where to create the new file
  /// * `comments` - Comments and metadata to associate with the new stream
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn continue_new_file(&mut self, path: &str, comments: &mut OpusEncComments) -> Result<&mut Self, OpusEncError> {
    let path = CString::new(path).map_err(|_| OpusEncError::RustStringConversion)?;
    unsafe {
      match ope::ope_encoder_continue_new_file(self.ptr, path.as_ptr(), comments.ptr) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Ends the current audio stream and creates a new callback-based encoding structure.
  ///
  /// # Arguments
  ///
  /// * `user_data` - Data to pass to the callbacks upon invocation (such as a file pointer)
  /// * `comments` - Comments and metadata to associate with the new stream
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn continue_new_callbacks(
    &mut self,
    user_data: Option<&'a mut T>,
    comments: &mut OpusEncComments,
  ) -> Result<&mut Self, OpusEncError> {
    unsafe {
      self.cb_user_data = user_data;
      match ope::ope_encoder_continue_new_callbacks(self.ptr, core::ptr::from_mut(self).cast(), comments.ptr) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Writes the file header immediately rather than waiting for audio to begin.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn flush_header(&mut self) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_flush_header(self.ptr) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Resets the internal state of the encoder to be the same as if the encoder was
  /// newly created without destroying the encoder itself.
  ///
  /// This should be used when switching streams in order to prevent back-to-back
  /// encoding from giving different results from one-at-a-time encoding.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn reset_state(&mut self) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(self.ptr, OpusEncRequest::ResetState as core::ffi::c_int) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the final state of the codec's entropy coder, used for testing purposes.
  ///
  /// # Returns
  ///
  /// The final state of the codec's entropy coder as a `u32`,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_final_range(&mut self) -> Result<u32, OpusEncError> {
    let mut final_range: u32 = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetFinalRange as core::ffi::c_int,
        core::ptr::from_mut(&mut final_range),
      ) {
        0 => Ok(final_range),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Sets the encoder's bandpass to a specific value.
  ///
  /// This prevents the encoder from automatically selecting the bandpass based on
  /// the available bitrate.
  ///
  /// If the application knows the bandpass of the input audio it is providing, it
  /// should normally use [`OpusEnc::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.
  ///
  /// # Arguments
  ///
  /// * `bandwidth` - The desired bandpass to set for the encoder, which should be a variant of [`OpusEncBandwidth`].
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_bandwidth(&mut self, bandwidth: OpusEncBandwidth) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetBandwidth as core::ffi::c_int,
        bandwidth as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured bandpass.
  ///
  /// # Returns
  ///
  /// An [`OpusEncBandwidth`] variant representing the current bandpass setting of the encoder,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_bandwidth(&mut self) -> Result<OpusEncBandwidth, OpusEncError> {
    let mut bandwidth: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetBandwidth as core::ffi::c_int,
        core::ptr::from_mut(&mut bandwidth),
      ) {
        0 => Ok(OpusEncBandwidth::from_native(bandwidth)),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the sample rate that the encoder was initialized with.
  ///
  /// # Returns
  ///
  /// An [`OpusEncSampleRate`] variant representing the sample rate of the encoder,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_sample_rate(&mut self) -> Result<OpusEncSampleRate, OpusEncError> {
    let mut rate: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetSampleRate as core::ffi::c_int,
        core::ptr::from_mut(&mut rate),
      ) {
        0 => Ok(OpusEncSampleRate::from_native(rate)),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Disables the use of phase inversion for intensity stereo, improving the quality
  /// of mono downmixes, but slightly reducing normal stereo quality.
  ///
  /// # Arguments
  ///
  /// * `disabled` - A boolean value indicating whether to disable phase inversion (`true` to disable, `false` to enable).
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_phase_inversion_disabled(&mut self, disabled: bool) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetPhaseInversionDisabled as core::ffi::c_int,
        core::ffi::c_int::from(disabled),
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured phase inversion status.
  ///
  /// # Returns
  ///
  /// `True` if phase inversion is disabled (meaning that the encoder will not use
  /// phase inversion for intensity stereo), and `False` if it is enabled,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_phase_inversion_disabled(&mut self) -> Result<bool, OpusEncError> {
    let mut disabled: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetPhaseInversionDisabled as core::ffi::c_int,
        core::ptr::from_mut(&mut disabled),
      ) {
        0 => Ok(disabled != 0),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the DTX state of the encoder.
  ///
  /// Returns whether the last encoded frame was either a comfort noise update during
  /// DTX or not encoded because of DTX.
  ///
  /// # Returns
  ///
  /// `True` if the last encoded frame was a comfort noise update during DTX or
  /// if the last frame was not encoded because of DTX, or an error if the
  /// operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_in_dtx(&mut self) -> Result<bool, OpusEncError> {
    let mut in_dtx: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetInDtx as core::ffi::c_int,
        core::ptr::from_mut(&mut in_dtx),
      ) {
        0 => Ok(in_dtx != 0),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Configures the encoder's computational complexity.
  ///
  /// The supported range is 0-10 inclusive, with 10 representing the highest complexity.
  ///
  /// # Arguments
  ///
  /// * `complexity` - The desired complexity level for the encoder, ranging from 0 to 10.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_complexity(&mut self, complexity: i32) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetComplexity as core::ffi::c_int,
        complexity.clamp(0, 10) as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's computational complexity configuration, ranging from 0-10 inclusive.
  ///
  /// # Returns
  ///
  /// The current complexity setting of the encoder as an `i32`,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_complexity(&mut self) -> Result<i32, OpusEncError> {
    let mut complexity: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetComplexity as core::ffi::c_int,
        core::ptr::from_mut(&mut complexity),
      ) {
        0 => Ok(complexity),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Configures the birate of the encoder.
  ///
  /// Rates from 500-512,000 bits per second are meaningful, as well as the special
  /// values [`OpusEncBitrate::Auto`] and [`OpusEncBitrate::Max`]. The value
  /// [`OpusEncBitrate::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.
  ///
  /// # Arguments
  ///
  /// * `bitrate` - The desired bitrate for the encoder, which should be a variant of [`OpusEncBitrate`].
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_bitrate(&mut self, bitrate: OpusEncBitrate) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetBitrate as core::ffi::c_int,
        bitrate.to_native(),
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's bitrate configuration.
  ///
  /// The default configuration is based on the number of channels and the input
  /// sampling rate.
  ///
  /// # Returns
  ///
  /// An [`OpusEncBitrate`] variant representing the current bitrate setting of the encoder,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_bitrate(&mut self) -> Result<OpusEncBitrate, OpusEncError> {
    let mut bitrate: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetBitrate as core::ffi::c_int,
        core::ptr::from_mut(&mut bitrate),
      ) {
        0 => Ok(OpusEncBitrate::from_native(bitrate)),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Enables or disables variable bitrate (VBR) encoding.
  ///
  /// The configured bitrate is still used as a target, but the encoder is free to
  /// use a lower bitrate if the input signal does not require it.
  ///
  /// # Arguments
  ///
  /// * `vbr` - A boolean value indicating whether to enable (`true`) or disable (`false`) variable bitrate encoding.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_vbr(&mut self, vbr: bool) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetVbr as core::ffi::c_int,
        core::ffi::c_int::from(vbr),
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Determines whether variable bitrate (VBR) encoding is enabled or disabled.
  ///
  /// # Returns
  ///
  /// `True` if VBR encoding is enabled, or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_vbr(&mut self) -> Result<bool, OpusEncError> {
    let mut vbr: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetVbr as core::ffi::c_int,
        core::ptr::from_mut(&mut vbr),
      ) {
        0 => Ok(vbr != 0),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Enables or disables constrained variable bitrate (VBR) encoding.
  ///
  /// This setting is ignored when the encoder is in constant bitrate (CBR) mode.
  ///
  /// # Arguments
  ///
  /// * `constrainted` - A boolean value indicating whether to enable (`true`) or disable (`false`) constrained VBR encoding.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_vbr_constraint(&mut self, constrained: bool) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetVbrConstraint as core::ffi::c_int,
        core::ffi::c_int::from(constrained),
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Determines whether constrained variable bitrate (VBR) is enabled or disabled.
  ///
  /// # Returns
  ///
  /// `True` if constrained VBR is enabled, or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_vbr_constraint(&mut self) -> Result<bool, OpusEncError> {
    let mut constrained: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetVbrConstraint as core::ffi::c_int,
        core::ptr::from_mut(&mut constrained),
      ) {
        0 => Ok(constrained != 0),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Configures mono/stereo enforcing in the encoder.
  ///
  /// This can force the encoder to produce packets encoded as either mono or stereo,
  /// regardless of the number of channels in the input audio. This is useful when the caller
  /// knows that the input signal is currently a mono source embedded in a stereo stream.
  ///
  /// # Arguments
  ///
  /// * `channels` - The desired number of channels for the encoder to enforce, as an [`OpusEncForcedChannels`] variant.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_force_channels(&mut self, channels: OpusEncForcedChannels) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetForceChannels as core::ffi::c_int,
        channels as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured forced number of channels.
  ///
  /// # Returns
  ///
  /// An [`OpusEncForcedChannels`] variant representing the current forced
  /// channel configuration of the encoder, or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_force_channels(&mut self) -> Result<OpusEncForcedChannels, OpusEncError> {
    let mut channels: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetForceChannels as core::ffi::c_int,
        core::ptr::from_mut(&mut channels),
      ) {
        0 => Ok(OpusEncForcedChannels::from_native(channels)),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Configures the maximum bandpass that the encoder will select automatically.
  ///
  /// Applications should normally use this instead of [`OpusEnc::set_bandwidth`]
  /// to allow the encoder to select the bandpass based on the available bitrate.
  ///
  /// # Arguments
  ///
  /// * `bandwidth` - The desired maximum bandpass for the encoder, which should be a variant of [`OpusEncBandwidth`].
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_max_bandwidth(&mut self, bandwidth: OpusEncBandwidth) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetMaxBandwidth as core::ffi::c_int,
        bandwidth as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured maximum allowed bandpass.
  ///
  /// # Returns
  ///
  /// An [`OpusEncBandwidth`] variant representing the maximum bandpass that
  /// the encoder will select automatically, or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_max_bandwidth(&mut self) -> Result<OpusEncBandwidth, OpusEncError> {
    let mut bandwidth: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetMaxBandwidth as core::ffi::c_int,
        core::ptr::from_mut(&mut bandwidth),
      ) {
        0 => Ok(OpusEncBandwidth::from_native(bandwidth)),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Configures the type of signal being encoded, where [`OpusEncSignalBias::LpcHybrid`]
  /// should be used for a voice-like signal, and [`OpusEncSignalBias::MDCT`] should be used
  /// for music-like signals.
  ///
  /// This is a hint which helps the encoder's mode selection.
  ///
  /// # Arguments
  ///
  /// * `signal` - The desired signal type for the encoder, which should be a variant of [`OpusEncSignalBias`].
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_signal_bias(&mut self, signal: OpusEncSignalBias) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetSignal as core::ffi::c_int,
        signal as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured signal type.
  ///
  /// # Returns
  ///
  /// An [`OpusEncSignalBias`] variant, where [`OpusEncSignalBias::LpcHybrid`]
  /// indicates a voice-like signal, and [`OpusEncSignalBias::MDCT`] indicates a music-like
  /// signal, or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_signal_bias(&mut self) -> Result<OpusEncSignalBias, OpusEncError> {
    let mut signal: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetSignal as core::ffi::c_int,
        core::ptr::from_mut(&mut signal),
      ) {
        0 => Ok(OpusEncSignalBias::from_native(signal)),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Configures the encoder's intended application.
  ///
  /// # Arguments
  ///
  /// * `application` - The desired application type for the encoder, which should be a variant of [`OpusEncApplication`].
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_application(&mut self, application: OpusEncApplication) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetApplication as core::ffi::c_int,
        application as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured application.
  ///
  /// # Returns
  ///
  /// An [`OpusEncApplication`] variant representing the current application
  /// setting of the encoder, or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_application(&mut self) -> Result<OpusEncApplication, OpusEncError> {
    let mut application: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetApplication as core::ffi::c_int,
        core::ptr::from_mut(&mut application),
      ) {
        0 => Ok(OpusEncApplication::from_native(application)),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the total number of delay samples added by the entire codec.
  ///
  /// This can be queried by the encoder, and then the provided number of samples can
  /// be skipped from the start of the decoder's output to provide time-aligned input
  /// and output. From the perspective of a decoding application, the real audio data
  /// begins this many samples late.
  ///
  /// The decoder contribution to this delay is identical for all decoders, but the
  /// encoder portion may vary from implementation to implementation, version to version,
  /// or even depend on the encoder's initial configuration. Applications needing
  /// delay compensation should rely on this function rather than hard-coding a value.
  ///
  /// # Returns
  ///
  /// The total number of delay samples added by the entire codec as an `i32`,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_lookahead(&mut self) -> Result<i32, OpusEncError> {
    let mut lookahead: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetLookahead as core::ffi::c_int,
        core::ptr::from_mut(&mut lookahead),
      ) {
        0 => Ok(lookahead),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Configures the encoder's use of in-band Forward Error Correction (FEC).
  ///
  /// # Arguments
  ///
  /// * `fec` - A boolean value indicating whether to enable (`true`) or disable (`false`) in-band FEC for the encoder.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_inband_fec(&mut self, fec: bool) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetInbandFec as core::ffi::c_int,
        core::ffi::c_int::from(fec),
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured in-band Forward Error Correction (FEC) state.
  ///
  /// # Returns
  ///
  /// `True` if in-band FEC is enabled, or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_inband_fec(&mut self) -> Result<bool, OpusEncError> {
    let mut fec: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetInbandFec as core::ffi::c_int,
        core::ptr::from_mut(&mut fec),
      ) {
        0 => Ok(fec != 0),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Configures the encoder's expected packet loss percentage, in the range 0-100.
  ///
  /// 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.
  ///
  /// # Arguments
  ///
  /// * `loss_perc` - The desired expected packet loss percentage, ranging from 0 to 100.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_packet_loss_perc(&mut self, loss_perc: i32) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetPacketLossPerc as core::ffi::c_int,
        loss_perc.clamp(0, 100) as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured packet loss percentage in the range 0-100.
  ///
  /// # Returns
  ///
  /// The current packet loss percentage setting of the encoder as an `i32`,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_packet_loss_perc(&mut self) -> Result<i32, OpusEncError> {
    let mut loss_perc: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetPacketLossPerc as core::ffi::c_int,
        core::ptr::from_mut(&mut loss_perc),
      ) {
        0 => Ok(loss_perc),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Sets whether Discontinuous Transmission (DTX) is enabled or disabled.
  ///
  /// # Arguments
  ///
  /// * `enabled` - A boolean value indicating whether to enable (`true`) or disable (`false`) DTX for the encoder.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_dtx_enabled(&mut self, enabled: bool) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetDtx as core::ffi::c_int,
        core::ffi::c_int::from(enabled),
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets whether Discontinuous Transmission (DTX) is enabled or disabled.
  ///
  /// # Returns
  ///
  /// `True` if DTX is enabled, or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_dtx_enabled(&mut self) -> Result<bool, OpusEncError> {
    let mut dtx: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetDtx as core::ffi::c_int,
        core::ptr::from_mut(&mut dtx),
      ) {
        0 => Ok(dtx != 0),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Configures the depth (bit precision) of the signal being encoded.
  ///
  /// This is a hint which helps the encoder identify silence and near-silence. It
  /// represents the number of significant bits of linear intensity below which the signal
  /// contains ignorable quantization or other noise.
  ///
  /// For example, a bit-depth of 14 would be appropriate for G.711 u-law input. A bit-depth
  /// of 16 would be appropriate for 16-bit linear PCM input.
  ///
  /// # Arguments
  ///
  /// * `depth` - The desired bit depth for the encoder, which should be an `i32` representing the number of valid significant bits.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_lsb_depth(&mut self, depth: i32) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetLsbDepth as core::ffi::c_int,
        depth as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured signal depth (input precision in bits).
  ///
  /// # Returns
  ///
  /// The current signal depth of the encoder as an `i32`, or an error
  /// if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_lsb_depth(&mut self) -> Result<i32, OpusEncError> {
    let mut depth: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetLsbDepth as core::ffi::c_int,
        core::ptr::from_mut(&mut depth),
      ) {
        0 => Ok(depth),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Configures the encoder's use of variable duration frames.
  ///
  /// When variable duration is enabled, the encoder is free to use a shorter frame size
  /// than the one requested during encoder initialization. It is then the user's
  /// responsibility to verify how much audio was encoded by checking the `ToC` byte
  /// of the encoded packet. The part of the audio that was not encoded needs to be
  /// resent to the encoder for the next call.
  ///
  /// Do not use this option unless you **really** know what you are doing.
  ///
  /// # Arguments
  ///
  /// * `duration` - The length of the variable duration frame in milliseconds, which should be a variant of [`OpusEncFrameSize`].
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_expert_frame_duration(&mut self, duration: OpusEncFrameSize) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetExpertFrameDuration as core::ffi::c_int,
        duration as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured use of variable duration frames.
  ///
  /// # Returns
  ///
  /// An [`OpusEncFrameSize`] representing the current frame duration
  /// setting of the encoder, or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_expert_frame_duration(&mut self) -> Result<OpusEncFrameSize, OpusEncError> {
    let mut duration: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetExpertFrameDuration as core::ffi::c_int,
        core::ptr::from_mut(&mut duration),
      ) {
        0 => Ok(OpusEncFrameSize::from_native(duration)),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Disables almost all use of prediction, making frames almost completely
  /// independent. This reduces quality.
  ///
  /// # Arguments
  ///
  /// * `disabled` - A boolean value indicating whether to disable (`true`) or enable (`false`) prediction in the encoder.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_prediction_disabled(&mut self, disabled: bool) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetPredictionDisabled as core::ffi::c_int,
        core::ffi::c_int::from(disabled),
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured prediction status.
  ///
  /// # Returns
  ///
  /// `True` if prediction is disabled (meaning that the encoder will not use
  /// prediction for encoding frames), and `False` if it is enabled,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_prediction_disabled(&mut self) -> Result<bool, OpusEncError> {
    let mut disabled: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetPredictionDisabled as core::ffi::c_int,
        core::ptr::from_mut(&mut disabled),
      ) {
        0 => Ok(disabled != 0),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Enables Deep Redundancy (DRED) with any non-zero value, specifying the maximum
  /// number of 10-ms redundant frames to be used.
  ///
  /// # Arguments
  ///
  /// * `duration` - The maximum number of 10-ms redundant frames to use for deep redundancy.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_dred_duration(&mut self, duration: i32) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetDredDuration as core::ffi::c_int,
        duration as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured Deep Redundancy (DRED) maximum number of frames.
  ///
  /// # Returns
  ///
  /// The current maximum number of 10-ms redundant frames that the encoder
  /// is configured to use for Deep Redundancy (DRED) an `i32`,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_dred_duration(&mut self) -> Result<i32, OpusEncError> {
    let mut duration: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetDredDuration as core::ffi::c_int,
        core::ptr::from_mut(&mut duration),
      ) {
        0 => Ok(duration),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Provides external DNN weights from a binary object.
  ///
  /// This should only be used when the library was explicitly built
  /// without the weights.
  ///
  /// # Arguments
  ///
  /// * `blob` - A byte slice representing the binary data of the DNN weights.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  #[allow(clippy::cast_possible_truncation, clippy::cast_possible_wrap)]
  pub fn set_dnn_blob(&mut self, blob: &[u8]) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetDnnBlob as core::ffi::c_int,
        blob.as_ptr(),
        blob.len() as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Configures the encoder's delay due to use of a DNN-based denoiser.
  ///
  /// # Arguments
  ///
  /// * `delay` - The desired delay in milliseconds introduced by the DNN-based denoiser.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_decision_delay(&mut self, delay: i32) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetDecisionDelay as core::ffi::c_int,
        delay as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured delay due to use of a DNN-based denoiser.
  ///
  /// # Returns
  ///
  /// The current delay due to the DNN-based denoiser as an `i32`,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_decision_delay(&mut self) -> Result<i32, OpusEncError> {
    let mut delay: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetDecisionDelay as core::ffi::c_int,
        core::ptr::from_mut(&mut delay),
      ) {
        0 => Ok(delay),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Configures the encoder's delay due to Ogg multiplexing.
  ///
  /// # Arguments
  ///
  /// * `delay` - The desired delay in milliseconds introduced by Ogg multiplexing.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_muxing_delay(&mut self, delay: i32) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetMuxingDelay as core::ffi::c_int,
        delay as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured delay due to Ogg multiplexing.
  ///
  /// # Returns
  ///
  /// The current delay due to Ogg multiplexing as an `i32`,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_muxing_delay(&mut self) -> Result<i32, OpusEncError> {
    let mut delay: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetMuxingDelay as core::ffi::c_int,
        core::ptr::from_mut(&mut delay),
      ) {
        0 => Ok(delay),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Configures the number of extra bytes to reserve for comments and metadata (defaults to 512).
  ///
  /// # Arguments
  ///
  /// * `padding` - The desired number of extra bytes to reserve for comments and metadata.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_comment_padding(&mut self, padding: i32) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetCommentPadding as core::ffi::c_int,
        padding as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the encoder's configured number of extra bytes to reserve for comments and metadata.
  ///
  /// # Returns
  ///
  /// The current number of extra bytes reserved for comments and metadata as an `i32`,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_comment_padding(&mut self) -> Result<i32, OpusEncError> {
    let mut padding: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetCommentPadding as core::ffi::c_int,
        core::ptr::from_mut(&mut padding),
      ) {
        0 => Ok(padding),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Assigns a serial number to the current stream.
  ///
  /// # Arguments
  ///
  /// * `serial_no` - The desired serial number for the stream.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  #[allow(clippy::cast_possible_wrap)]
  pub fn set_serial_no(&mut self, serial_no: u32) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetSerialNo as core::ffi::c_int,
        serial_no as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the serial number of the current stream.
  ///
  /// # Returns
  ///
  /// The current serial number of the OggOpus stream as a `u32`,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  #[allow(clippy::cast_sign_loss)]
  pub fn get_serial_no(&mut self) -> Result<u32, OpusEncError> {
    let mut serial_no: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetSerialNo as core::ffi::c_int,
        core::ptr::from_mut(&mut serial_no),
      ) {
        0 => Ok(serial_no as u32),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Configures the amount of gain to apply upon playback.
  ///
  /// **0 dB is recommended unless you know what you are doing.**
  ///
  /// # Arguments
  ///
  /// * `gain` - The desired gain in decibels (dB) to apply to the audio signal upon playback.
  ///
  /// # Returns
  ///
  /// A mutable reference to the current instance of [`OpusEnc`] if successful,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn set_header_gain(&mut self, gain: i32) -> Result<&mut Self, OpusEncError> {
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::SetHeaderGain as core::ffi::c_int,
        gain as core::ffi::c_int,
      ) {
        0 => Ok(self),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the amount of gain to apply upon playback.
  ///
  /// # Returns
  ///
  /// The current gain value in decibels (dB) that will be applied to the
  /// encoded stream upon playback as an `i32`, or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  pub fn get_header_gain(&mut self) -> Result<i32, OpusEncError> {
    let mut gain: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetHeaderGain as core::ffi::c_int,
        core::ptr::from_mut(&mut gain),
      ) {
        0 => Ok(gain),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the number of streams in the current OggOpus stream.
  ///
  /// # Returns
  ///
  /// The number of streams in the current OggOpus stream as a `u8`,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
  pub fn get_nb_streams(&mut self) -> Result<u8, OpusEncError> {
    let mut nb_streams: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetNbStreams as core::ffi::c_int,
        core::ptr::from_mut(&mut nb_streams),
      ) {
        0 => Ok(nb_streams as u8),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }

  /// Gets the number of coupled streams in the current OggOpus stream.
  ///
  /// # Returns
  ///
  /// The number of coupled streams in the current OggOpus stream as a `u8`,
  /// or an error if the operation failed.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon operation failure.
  #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
  pub fn get_nb_coupled_streams(&mut self) -> Result<u8, OpusEncError> {
    let mut nb_coupled_streams: core::ffi::c_int = 0;
    unsafe {
      match ope::ope_encoder_ctl(
        self.ptr,
        OpusEncRequest::GetNbCoupledStreams as core::ffi::c_int,
        core::ptr::from_mut(&mut nb_coupled_streams),
      ) {
        0 => Ok(nb_coupled_streams as u8),
        err => Err(OpusEncError::from_native(err)),
      }
    }
  }
}

/// Provides methods for creating and managing an Opus encoder.
pub struct OpusEncoder;

impl OpusEncoder {
  /// Creates a new OggOpus file and encoder.
  ///
  /// # Arguments
  ///
  /// * `path` - Path where the file should be created
  /// * `comments` - Comments and metadata associated with the stream
  /// * `rate` - Sampling rate of the input audio
  /// * `channels` - Number of channels in the input audio
  /// * `family` - Channel mapping family (mono/stereo or surround)
  ///
  /// # Returns
  ///
  /// Newly-created [`OpusEnc`] encoder that can be used to encode audio
  /// into the specified OggOpus file.
  ///
  /// # Errors
  ///
  /// A [`OpusEncError::RustStringConversion`] error will be returned
  /// if conversion of the `path` to a C string fails.
  ///
  /// Any [`OpusEncError`] variant may be returned upon failure to create
  /// the encoder.
  pub fn create_file<'a>(
    path: &str,
    comments: &'a mut OpusEncComments,
    rate: OpusEncSampleRate,
    channels: u8,
    family: OpusEncChannelMapping,
  ) -> Result<Box<OpusEnc<'a, ()>>, OpusEncError> {
    let mut error = core::ffi::c_int::default();
    let path = CString::new(path).map_err(|_| OpusEncError::RustStringConversion)?;
    unsafe {
      let encoder = ope::ope_encoder_create_file(
        path.as_ptr(),
        comments.ptr,
        rate as ope::opus_int32,
        core::ffi::c_int::from(channels),
        family as core::ffi::c_int,
        core::ptr::from_mut(&mut error),
      );
      if encoder.is_null() {
        Err(OpusEncError::from_native(error))
      } else {
        Ok(Box::new(OpusEnc {
          ptr: encoder,
          write_cb: None,
          close_cb: None,
          cb_user_data: None,
        }))
      }
    }
  }

  /// Creates a new OggOpus stream to be manipulated using callbacks.
  ///
  /// This method allows for more control over the encoding process by using
  /// callbacks for writing encoded audio data and closing the stream. This is
  /// particularly useful for applications that need to handle the encoded
  /// data in a custom way, such as streaming it over a network or writing it
  /// to a custom output format.
  ///
  /// The `write_callback` will be invoked every time there is encoded audio data
  /// available for writing to a file, and the `close_callback` will be invoked when the
  /// audio stream is ready to be closed.
  ///
  /// # Arguments
  ///
  /// * `write_callback` - Callback function to handle writing encoded audio data
  /// * `close_callback` - Callback function to handle closing the stream
  /// * `user_data` - User-defined data to pass to the callback functions (such as a file pointer)
  /// * `comments` - Comments and metadata associated with the stream
  /// * `rate` - Sampling rate of the input audio
  /// * `channels` - Number of channels in the input audio
  /// * `family` - Channel mapping family (mono/stereo or surround)
  ///
  /// # Returns
  ///
  /// Newly-created [`OpusEnc`] encoder that can be used to encode audio using
  /// the provided callback functions.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon failure to create
  /// the encoder.
  pub fn create_callbacks<'a, T>(
    write_callback: OpeWriteFunc<T>,
    close_callback: OpeCloseFunc<T>,
    user_data: Option<&'a mut T>,
    comments: &mut OpusEncComments,
    rate: OpusEncSampleRate,
    channels: u8,
    family: OpusEncChannelMapping,
  ) -> Result<Box<OpusEnc<'a, T>>, OpusEncError> {
    let mut error = core::ffi::c_int::default();
    let native_callbacks = ope::OpusEncCallbacks {
      write: Some(OpusEnc::<T>::write_cb),
      close: Some(OpusEnc::<T>::close_cb),
    };
    let mut enc = Box::new(OpusEnc {
      ptr: core::ptr::null_mut(),
      write_cb: Some(write_callback),
      close_cb: Some(close_callback),
      cb_user_data: user_data,
    });
    unsafe {
      let encoder = ope::ope_encoder_create_callbacks(
        &native_callbacks,
        core::ptr::from_mut(enc.as_mut()).cast(),
        comments.ptr,
        rate as ope::opus_int32,
        core::ffi::c_int::from(channels),
        family as core::ffi::c_int,
        core::ptr::from_mut(&mut error),
      );
      if encoder.is_null() {
        Err(OpusEncError::from_native(error))
      } else {
        enc.ptr = encoder;
        Ok(enc)
      }
    }
  }

  /// Creates a new OggOpus stream to be used along with [`OpusEnc::get_page`].
  ///
  /// This is mostly useful for muxing with other streams.
  ///
  /// # Arguments
  ///
  /// * `comments` - Comments and metadata associated with the stream
  /// * `rate` - Sampling rate of the input audio
  /// * `channels` - Number of channels in the input audio
  /// * `family` - Channel mapping family (mono/stereo or surround)
  ///
  /// # Returns
  ///
  /// Newly-created [`OpusEnc`] encoder that can be used to encode audio
  /// into an OggOpus stream accessible via the [`OpusEnc::get_page`] function.
  ///
  /// # Errors
  ///
  /// Any [`OpusEncError`] variant may be returned upon failure to create
  /// the encoder.
  pub fn create_pull<'a>(
    comments: &mut OpusEncComments,
    rate: OpusEncSampleRate,
    channels: u8,
    family: OpusEncChannelMapping,
  ) -> Result<Box<OpusEnc<'a, ()>>, OpusEncError> {
    let mut error = core::ffi::c_int::default();
    unsafe {
      let encoder = ope::ope_encoder_create_pull(
        comments.ptr,
        rate as ope::opus_int32,
        core::ffi::c_int::from(channels),
        family as core::ffi::c_int,
        core::ptr::from_mut(&mut error),
      );
      if encoder.is_null() {
        Err(OpusEncError::from_native(error))
      } else {
        Ok(Box::new(OpusEnc {
          ptr: encoder,
          write_cb: None,
          close_cb: None,
          cb_user_data: None,
        }))
      }
    }
  }
}

#[cfg(test)]
mod tests {
  use alloc::vec::Vec;
  use std::io::Write;

  fn read_wav_file(path: &str) -> Vec<i16> {
    let wav_reader = hound::WavReader::open(path).expect("Failed to open WAV file");
    wav_reader
      .into_samples::<i16>()
      .collect::<Result<Vec<_>, _>>()
      .expect("Failed to read WAV file")
  }

  #[test]
  fn test_file_encoding() {
    let audio = read_wav_file("test_assets/wav_test1.wav");
    let mut comments = crate::OpusEncComments::create().expect("Failed to create OpusEncComments");
    comments
      .add("TITLE", "Some Track")
      .expect("Failed to add comment")
      .add_string("ARTIST=Test Artist")
      .expect("Failed to add comment string")
      .add_string("ALBUM=Test Album")
      .expect("Failed to add comment string");
    crate::OpusEncoder::create_file(
      "test_assets/test1.opus",
      &mut comments,
      crate::OpusEncSampleRate::Hz48000,
      1,
      crate::OpusEncChannelMapping::MonoStereo,
    )
    .expect("Failed to create OpusEnc")
    .set_vbr(true)
    .expect("Failed to set VBR")
    .set_complexity(10)
    .expect("Failed to set complexity")
    .set_bandwidth(crate::OpusEncBandwidth::SuperWideband12kHz)
    .expect("Failed to set bandwidth")
    .set_application(crate::OpusEncApplication::Audio)
    .expect("Failed to set application")
    .set_bitrate(crate::OpusEncBitrate::Explicit(24000))
    .expect("Failed to set bitrate")
    .write(&audio, 1)
    .expect("Failed to write audio");
  }

  #[test]
  fn test_file_encoding_callbacks() {
    fn write_callback(file: &mut std::fs::File, data: &[u8]) -> bool {
      file
        .write_all(data)
        .expect("Failed to write data to file from within callback");
      true
    }
    fn close_callback(_file: &mut std::fs::File) -> bool {
      true
    }

    let audio = read_wav_file("test_assets/wav_test1.wav");
    let mut output_file = std::fs::File::create("test_assets/test_cb.opus").expect("Failed to create output file");
    let mut comments = crate::OpusEncComments::create().expect("Failed to create OpusEncComments");
    comments
      .add("TITLE", "Some Track CB")
      .expect("Failed to add comment")
      .add_string("ARTIST=Test Artist CB")
      .expect("Failed to add comment string")
      .add_string("ALBUM=Test Album CB")
      .expect("Failed to add comment string");
    crate::OpusEncoder::create_callbacks(
      write_callback,
      close_callback,
      Some(&mut output_file),
      &mut comments,
      crate::OpusEncSampleRate::Hz48000,
      1,
      crate::OpusEncChannelMapping::MonoStereo,
    )
    .expect("Failed to create OpusEnc")
    .set_vbr(true)
    .expect("Failed to set VBR")
    .set_complexity(10)
    .expect("Failed to set complexity")
    .set_bandwidth(crate::OpusEncBandwidth::SuperWideband12kHz)
    .expect("Failed to set bandwidth")
    .set_application(crate::OpusEncApplication::Audio)
    .expect("Failed to set application")
    .set_bitrate(crate::OpusEncBitrate::Explicit(24000))
    .expect("Failed to set bitrate")
    .write(&audio, 1)
    .expect("Failed to write audio");
  }
}