Struct libsoxr::soxr::Soxr

pub struct Soxr { /* private fields */ }

This is the starting point for the Soxr algorithm.

Implementations

impl Soxr

pub fn create(
    input_rate: f64,
    output_rate: f64,
    num_channels: u32,
    io_spec: Option<&IOSpec>,
    quality_spec: Option<&QualitySpec>,
    runtime_spec: Option<&RuntimeSpec>
) -> Result<Soxr>

Create a new resampler. When io_spec, quality_spec or runtime_spec is None then SOXR will use it defaults:

• Default io_spec is per IOSpec(Datatype::Float32I, Datatype::Float32I)
• Default quality_spec is per QualitySpec(QualityRecipe::High, QualityFlags::ROLLOFF_SMALL)
• Default runtime_spec is per RuntimeSpec (1)

 use libsoxr::{Datatype, IOSpec, QualitySpec, RuntimeSpec, Soxr, QualityRecipe, QualityFlags};

 let io_spec = IOSpec::new(Datatype::Float32I, Datatype::Float64I);
 let quality_spec = QualitySpec::new(&QualityRecipe::VeryHigh, QualityFlags::HI_PREC_CLOCK);
 let runtime_spec = RuntimeSpec::new(4);
 let mut soxr = Soxr::create(1.0, 2.0, 1, Some(&io_spec), Some(&quality_spec), Some(&runtime_spec));
 assert!(soxr.is_ok());

pub fn version() -> &'static str

Get version of libsoxr library

pub fn set_error(&mut self, msg: String) -> Result<()>

Set error of Soxr engine

pub fn set_num_channels(&mut self, num_channels: u32) -> Result<()>

Change number of channels after creating Soxr object

pub fn error(&self) -> Option<String>

Query error status.

pub fn num_clips(&self) -> usize

Query int. clip counter (for R/W).

pub fn delay(&self) -> f64

Query current delay in output samples

pub fn engine(&self) -> String

Query resampling engine name.

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

Ready for fresh signal, same config.

pub fn set_io_ratio(&mut self, io_ratio: f64, slew_len: usize) -> Result<()>

For variable-rate resampling. See example # 5 of libsoxr repository for how to create a variable-rate resampler and how to use this function.

pub fn process<I, O>(
    &self,
    buf_in: Option<&[I]>,
    buf_out: &mut [O]
) -> Result<(usize, usize)>

Resamples Some(buf_in) into buf_out. Type is dependent on IOSpec. If you leave out IOSpec on create, it defaults to f32. Make sure that buf_out is large enough to hold the resampled data. Furthermore, to indicate end-of-input to the resampler, always end with a last call to process with None as buf_in. The result contains number of input samples used and number of output samples placed in ‘buf_out’

Example

// upscale factor 2, one channel with all the defaults
let soxr = Soxr::create(1.0, 2.0, 1, None, None, None).unwrap();

// source data, taken from 1-single-block.c of libsoxr examples.
let source: [f32; 48] = [0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0,
                         1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0,
                         0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0,
                         -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0];

// create room for 2*48 = 96 samples
let mut target: [f32; 96] = [0.0; 96];

// Two runs. First run will convert the source data into target.
// Last run with None is to inform resampler of end-of-input so it can clean up
soxr.process(Some(&source), &mut target).unwrap();
soxr.process::<f32,_>(None, &mut target[0..]).unwrap();

pub fn set_input<'a, S, T>(
    &'a mut self,
    input_fn: SoxrFunction<S, T>,
    state: Option<&'a mut S>,
    max_samples: usize
) -> Result<()>

Sets the input function of type SoxrFunction.

Please note that SoxrFunction gets a buffer as parameter which the function should fill. This is different from native libsoxr where you need to return the used input buffer from the input function.

The input buffer is allocated for you using a Vec with initial_capacity set to max_samples * channels that you supplied.

Please note that the state you pass into set_input may not be moved in memory. Thus it is wise to keep the state in a Box (heap) and not on the stack. TODO: check if Pinis an option here.

Example for ‘happy flow’

 use libsoxr::{Error, ErrorType, Soxr, SoxrFunction};

 struct State {
   // data for input function to supply Soxr with source samples.
   // In this case just a value, but you could put a handle to a FLAC file into this.
   value: f32
 }

 let input_fn = |state: &mut State, buffer: &mut [f32], samples: usize| {
     for sample in buffer.iter_mut().take(samples) {
        *sample = state.value;
     }
     return Ok(samples);
  };

 let mut soxr = Soxr::create(1.0, 2.0, 1, None, None, None).unwrap();
 let mut state = Box::new(State { value: 1.0 });
 assert!(soxr.set_input(input_fn, Some(&mut state), 100).is_ok());

 let source: [f32; 48] = [0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0,
                          1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0,
                          0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0,
                          -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0];

 // create room for 2*48 = 96 samples
 let mut target: [f32; 96] = [0.0; 96];
 // ask SOXR to fill target with 96 samples for which it will use `input_fn`
 assert!(soxr.output(&mut target[..], 96) == 96);
 assert!(soxr.error().is_none());

Example to handle error in input_fn

The input function may return an error. You can handle that using the returned Error type.

 use libsoxr::{Error, ErrorType, Soxr, SoxrFunction};

 struct State {
   // data for input function to supply Soxr with source samples.
   // In this case just a value, but you could put a handle to a FLAC file into this.
   value: f32,
   state_error: Option<&'static str>,
 }

 let input_fn = |state: &mut State, buffer: &mut [f32], samples: usize| {
     state.state_error = Some("Some Error");
     Err(Error::new(Some("input_fn".into()), ErrorType::ProcessError("Unexpected end of input".into())))
  };

 let mut soxr = Soxr::create(1.0, 2.0, 1, None, None, None).unwrap();
 let mut state = Box::new(State { value: 1.0, state_error: None });
 assert!(soxr.set_input(input_fn, Some(&mut state), 100).is_ok());

 let source: [f32; 48] = [0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0,
                          1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0,
                          0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0,
                          -1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0];

 // create room for 2*48 = 96 samples
 let mut target: [f32; 96] = [0.0; 96];
 assert!(soxr.output(&mut target[..], 96) == 0);
 assert!(soxr.error().is_some());
 // Please note that the ProcessError is not passed through into `error()`
 assert_eq!(soxr.error().unwrap(), "input function reported failure");
 // But you can use the State struct to pass specific errors which you can query on `soxr.error().is_some()`
 assert_eq!(state.state_error, Some("Some Error"));

pub fn output<S>(&self, data: &mut [S], samples: usize) -> usize

Resample and output a block of data using an app-supplied input function. This function must look and behave like soxr_input_fn_t and be registered with a previously created stream resampler using set_input then repeatedly call output.

• data - App-supplied buffer(s) for resampled data.
• samples - number of samples in buffer per channel, i.e. data.len() / number_of_channels returns number of samples in buffer

// call output using a buffer of 100 mono samples. For stereo devide by 2, so this buffer
// could hold 100 / number_of_channels = 50 stereo samples.
let mut buffer = [0.0f32; 100];
assert!(s.output(&mut buffer[..], 100) > 0);

Trait Implementations

impl Debug for Soxr

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

Formats the value using the given formatter.

impl Drop for Soxr

fn drop(&mut self)

Executes the destructor for this type.