Trait rubato::Resampler

pub trait Resampler<T>: Send
where
    T: Sample,
{
    // Required methods
    fn process_into_buffer<Vin: AsRef<[T]>, Vout: AsMut<[T]>>(
        &mut self,
        wave_in: &[Vin],
        wave_out: &mut [Vout],
        active_channels_mask: Option<&[bool]>
    ) -> ResampleResult<(usize, usize)>;
    fn input_frames_max(&self) -> usize;
    fn input_frames_next(&self) -> usize;
    fn nbr_channels(&self) -> usize;
    fn output_frames_max(&self) -> usize;
    fn output_frames_next(&self) -> usize;
    fn output_delay(&self) -> usize;
    fn set_resample_ratio(
        &mut self,
        new_ratio: f64,
        ramp: bool
    ) -> ResampleResult<()>;
    fn set_resample_ratio_relative(
        &mut self,
        rel_ratio: f64,
        ramp: bool
    ) -> ResampleResult<()>;
    fn reset(&mut self);

    // Provided methods
    fn process<V: AsRef<[T]>>(
        &mut self,
        wave_in: &[V],
        active_channels_mask: Option<&[bool]>
    ) -> ResampleResult<Vec<Vec<T>>> { ... }
    fn process_partial_into_buffer<Vin: AsRef<[T]>, Vout: AsMut<[T]>>(
        &mut self,
        wave_in: Option<&[Vin]>,
        wave_out: &mut [Vout],
        active_channels_mask: Option<&[bool]>
    ) -> ResampleResult<(usize, usize)> { ... }
    fn process_partial<V: AsRef<[T]>>(
        &mut self,
        wave_in: Option<&[V]>,
        active_channels_mask: Option<&[bool]>
    ) -> ResampleResult<Vec<Vec<T>>> { ... }
    fn input_buffer_allocate(&self, filled: bool) -> Vec<Vec<T>> { ... }
    fn output_buffer_allocate(&self, filled: bool) -> Vec<Vec<T>> { ... }
}

A resampler that is used to resample a chunk of audio to a new sample rate. For asynchronous resamplers, the rate can be adjusted as required.

This trait is not object safe. If you need an object safe resampler, use the VecResampler wrapper trait.

Required Methods

fn process_into_buffer<Vin: AsRef<[T]>, Vout: AsMut<[T]>>( &mut self, wave_in: &[Vin], wave_out: &mut [Vout], active_channels_mask: Option<&[bool]> ) -> ResampleResult<(usize, usize)>

Resample a buffer of audio to a pre-allocated output buffer. Use this in real-time applications where the unpredictable time required to allocate memory from the heap can cause glitches. If this is not a problem, you may use the process method instead.

The input and output buffers are used in a non-interleaved format. The input is a slice, where each element of the slice is itself referenceable as a slice (AsRef<[T]>) which contains the samples for a single channel. Because [Vec<T>] implements AsRef<\[T\]>, the input may be Vec<Vec<T>>.

The output data is a slice, where each element of the slice is a [T] which contains the samples for a single channel. If the output channel slices do not have sufficient capacity for all output samples, the function will return an error with the expected size. You could allocate the required output buffer with output_buffer_allocate before calling this function and reuse the same buffer for each call.

The active_channels_mask is optional. Any channel marked as inactive by a false value will be skipped during processing and the corresponding output will be left unchanged. If None is given, all channels will be considered active.

Before processing, it checks that the input and outputs are valid. If either has the wrong number of channels, or if the buffer for any channel is too short, a ResampleError is returned. Both input and output are allowed to be longer than required. The number of input samples consumed and the number output samples written per channel is returned in a tuple, (input_frames, output_frames).

fn input_frames_max(&self) -> usize

Get the maximum number of input frames per channel the resampler could require.

fn input_frames_next(&self) -> usize

Get the number of frames per channel needed for the next call to process_into_buffer or process.

fn nbr_channels(&self) -> usize

Get the maximum number of channels this Resampler is configured for.

fn output_frames_max(&self) -> usize

Get the max number of output frames per channel.

fn output_frames_next(&self) -> usize

Get the number of frames per channel that will be output from the next call to process_into_buffer or process.

fn output_delay(&self) -> usize

Get the delay for the resampler, reported as a number of output frames.

fn set_resample_ratio( &mut self, new_ratio: f64, ramp: bool ) -> ResampleResult<()>

Update the resample ratio.

For asynchronous resamplers, the ratio must be within original / maximum to original * maximum, where the original and maximum are the resampling ratios that were provided to the constructor. Trying to set the ratio outside these bounds will return ResampleError::RatioOutOfBounds.

For synchronous resamplers, this will always return ResampleError::SyncNotAdjustable.

If the argument ramp is set to true, the ratio will be ramped from the old to the new value during processing of the next chunk. This allows smooth transitions from one ratio to another. If ramp is false, the new ratio will be applied from the start of the next chunk.

fn set_resample_ratio_relative( &mut self, rel_ratio: f64, ramp: bool ) -> ResampleResult<()>

Update the resample ratio as a factor relative to the original one.

For asynchronous resamplers, the relative ratio must be within 1 / maximum to maximum, where maximum is the maximum resampling ratio that was provided to the constructor. Trying to set the ratio outside these bounds will return ResampleError::RatioOutOfBounds.

Ratios above 1.0 slow down the output and lower the pitch, while ratios below 1.0 speed up the output and raise the pitch.

For synchronous resamplers, this will always return ResampleError::SyncNotAdjustable.

fn reset(&mut self)

Reset the resampler state and clear all internal buffers.

Provided Methods

fn process<V: AsRef<[T]>>( &mut self, wave_in: &[V], active_channels_mask: Option<&[bool]> ) -> ResampleResult<Vec<Vec<T>>>

This is a convenience wrapper for process_into_buffer that allocates the output buffer with each call. For realtime applications, use process_into_buffer with a buffer allocated by output_buffer_allocate instead of this function.

fn process_partial_into_buffer<Vin: AsRef<[T]>, Vout: AsMut<[T]>>( &mut self, wave_in: Option<&[Vin]>, wave_out: &mut [Vout], active_channels_mask: Option<&[bool]> ) -> ResampleResult<(usize, usize)>

This is a convenience method for processing the last frames at the end of a stream. Use this when there are fewer frames remaining than what the resampler requires as input. Calling this function is equivalent to padding the input buffer with zeros to make it the right input length, and then calling process_into_buffer. This method can also be called without any input frames, by providing None as input buffer. This can be utilized to push any remaining delayed frames out from the internal buffers. Note that this method allocates space for a temporary input buffer. Real-time applications should instead call process_into_buffer with a zero-padded pre-allocated input buffer.

fn process_partial<V: AsRef<[T]>>( &mut self, wave_in: Option<&[V]>, active_channels_mask: Option<&[bool]> ) -> ResampleResult<Vec<Vec<T>>>

This is a convenience method for processing the last frames at the end of a stream. It is similar to process_partial_into_buffer but allocates the output buffer with each call. Note that this method allocates space for both input and output.

fn input_buffer_allocate(&self, filled: bool) -> Vec<Vec<T>>

Convenience method for allocating an input buffer suitable for use with process_into_buffer. The buffer’s capacity is big enough to prevent allocating additional heap memory before any call to process_into_buffer regardless of the current resampling ratio.

The filled argument determines if the vectors should be pre-filled with zeros or not. When false, the vectors are only allocated but returned empty.

fn output_buffer_allocate(&self, filled: bool) -> Vec<Vec<T>>

Convenience method for allocating an output buffer suitable for use with process_into_buffer. The buffer’s capacity is big enough to prevent allocating additional heap memory during any call to process_into_buffer regardless of the current resampling ratio.

The filled argument determines if the vectors should be pre-filled with zeros or not. When false, the vectors are only allocated but returned empty.

Object Safety

This trait is not object safe.

Implementors

impl<T> Resampler<T> for FastFixedIn<T>

where T: Sample,

impl<T> Resampler<T> for FastFixedOut<T>

where T: Sample,

impl<T> Resampler<T> for FftFixedIn<T>

where T: Sample,

impl<T> Resampler<T> for FftFixedInOut<T>

where T: Sample,

impl<T> Resampler<T> for FftFixedOut<T>

where T: Sample,

impl<T> Resampler<T> for SincFixedIn<T>

where T: Sample,

impl<T> Resampler<T> for SincFixedOut<T>

where T: Sample,