Struct soundtouch::SoundTouch

source ·

pub struct SoundTouch(/* private fields */);

Expand description

Main class for tempo/pitch/rate adjusting routines.

Notes:

Initialize the SoundTouch object instance by setting up the sound stream parameters with functions set_sample_rate and set_channels, then set desired tempo/pitch/rate settings with the corresponding functions.
The SoundTouch class behaves like a first-in-first-out pipeline: The samples that are to be processed are fed into one of the pipe by calling function put_samples, while the ready processed samples can be read from the other end of the pipeline with function receive_samples. This crate provides a utility function generate_audio that does this.
The SoundTouch processing classes require certain sized batches of samples in order to process the sound. For this reason the classes buffer incoming samples until there are enough of samples available for processing, then they carry out the processing step and consequently make the processed samples available for outputting.
For the above reason, the processing routines introduce a certain latency between the input and output, so that the samples input to SoundTouch may not be immediately available in the output, and neither the amount of outputtable samples may not immediately be in direct relationship with the amount of previously input samples.
The tempo/pitch/rate control parameters can be altered during processing. Please notice though that they aren’t currently protected by semaphores, so in multi-thread application external semaphore protection may be required.
This class utilizes classes TDStretch for tempo change (without modifying pitch) and RateTransposer for changing the playback rate (that is, both tempo and pitch in the same ratio) of the sound. The third available control pitch (change pitch but maintain tempo) is produced by a combination of combining the two other controls.

Implementations§

source §

impl SoundTouch

source

pub fn new() -> Self

Crate a new SoundTouch instance.

source

pub fn set_channels(&mut self, num_channels: u32) -> &mut Self

Set the number of channels.

1 = mono
2 = stereo

source

pub fn set_sample_rate(&mut self, sample_rate: u32) -> &mut Self

Set the sample rate.

source

pub fn set_tempo(&mut self, tempo: f64) -> &mut Self

Set the tempo of the audio to generate.

source

pub fn set_pitch(&mut self, pitch: f64) -> &mut Self

Sets new pitch control value. Original pitch = 1.0, smaller values represent lower pitches, larger values higher pitch.

source

pub fn set_rate(&mut self, rate: f64) -> &mut Self

Sets new rate control value. Normal rate = 1.0, smaller values represent slower rate, larger faster rates.

source

pub fn set_tempo_change(&mut self, new_tempo: f64) -> &mut Self

Sets new tempo control value as a difference in percents compared to the original tempo (-50 .. +100 %).

source

pub fn set_rate_change(&mut self, new_rate: f64) -> &mut Self

Sets new rate control value as a difference in percents compared to the original rate (-50 .. +100 %).

source

pub fn set_pitch_octaves(&mut self, pitch_octaves: f64) -> &mut Self

Sets pitch change in octaves compared to the original pitch (-1.00 .. +1.00).

source

pub fn set_pitch_semitones(&mut self, pitch_semitones: i32) -> &mut Self

Sets pitch change in semi-tones compared to the original pitch (-12 .. +12).

source

pub fn set_setting(&mut self, setting: Setting, value: i32) -> &mut Self

Changes a setting controlling the processing system behaviour. See the Setting enum for available settings.

source

pub fn generate_audio(&mut self, samples: &[f32]) -> Vec<f32>

NOT FROM SOUNDTOUCH

Generates audio samples from given input samples using the settings set in the SoundTouch struct and returns them in a vector.

This is equivalent to calling put_samples and receive_samples until the unprocessed sample buffer is empty.

Do not use put_samples or receive_samples with this function.

source

pub fn put_samples(&mut self, samples: &[f32], num_samples: usize)

Adds num_samples pcs of samples from the samples memory position into the input of the object. Notice that sample rate must be set before calling this function, otherwise throws a runtime_error exception.

Note: num_samples should contain the number of samples per channel. Ex: If samples.len() is 6720 and there are 2 channels, then num_samples should be 3360.

source

pub fn receive_samples( &mut self, samples: &mut [f32], max_samples: usize, ) -> usize

Output samples from beginning of the sample buffer. Copies requested samples to output buffer and removes them from the sample buffer. If there are less than max_samples samples in the buffer, returns all that available.

source

pub fn receive_samples_no_in(&mut self, max_samples: usize) -> usize

Adjusts book-keeping so that given number of samples are removed from beginning of the sample buffer without copying them anywhere.

source

pub fn num_unprocessed_samples(&self) -> usize

Returns number of samples currently unprocessed.

source

pub fn clear(&mut self)

Clears all the samples in the object’s output and internal processing buffers.

source

pub fn flush(&mut self)

Flushes the last samples from the processing pipeline to the output. Clears also the internal processing buffers. Note: This function is meant for extracting the last samples of a sound stream. This function may introduce additional blank samples in the end of the sound stream, and thus it’s not recommended to call this function in the middle of a sound stream.

source

pub fn num_channels(&self) -> u32

Returns number of channels.

source

pub fn get_setting(&self, setting: Setting) -> i32

Gets a setting controlling the processing system behaviour. See the Setting enum for available settings.

source

pub fn get_input_output_sample_ratio(&mut self) -> f64

Get ratio between input and output audio durations, useful for calculating processed output duration: if you’ll process a stream of N samples, then you can expect to get out N * get_input_output_sample_ratio samples.

This ratio will give accurate target duration ratio for a full audio track, given that the the whole track is processed with same processing parameters.

If this ratio is applied to calculate intermediate offsets inside a processing stream, then this ratio is approximate and can deviate +- some tens of milliseconds from ideal offset, yet by end of the audio stream the duration ratio will become exact.

Example: if processing with parameters -tempo=15 -pitch=-3, the function will return value 0.8695652... Now, if processing an audio stream whose duration is exactly one million audio samples, then you can expect the processed output duration be 0.869565 * 1000000 = 869565 samples.

source