Rubato Audio Resampling Library

Rubato is a flexible audio sample rate conversion library for Rust. It is designed for both real-time audio streams and offline batch processing by processing audio in chunks.

Key features include:

• Flexible Resampling Ratios: Ratios can be updated on the fly.
• High Performance: Designed with real-time safety in mind, avoiding allocations during processing to ensure predictable performance.
• Multiple Resampler Types: Offers a choice between high-quality asynchronous sinc resamplers and high-speed synchronous FFT-based resamplers.

Rubato uses traits to define specific capabilities of a resampler. Instead of checking error variants, you can use these traits to access functionality at compile-time or query them via shared references.

• Adjustable: Provides set_resample_ratio and set_resample_ratio_relative.
• Resizable: Provides set_chunk_size.

If you have a trait object of type Resampler, you can recover these capabilities using .as_adjustable() or .as_resizable(), or check for them using .is_adjustable() and .is_resizable().

Rubato handles input and output data via Adapter and AdapterMut objects from the audioadapter crate. This allows the library to work with any sample layout or format.

• Common Data Structures: The audioadapter-buffers crate provides ready-to-use adapters for common structures.
• Migration Path: If you are migrating from Rubato v0.16 or earlier (which used a vector of vectors), use the SequentialSliceOfVecs adapter from audioadapter-buffers as a starting point.

Synchronous resampling is used when the input and output sample rates are fixed and locked (e.g., converting a file from 44.1 kHz to 48 kHz).

Implementation details:

• Method: Uses FFT (Fast Fourier Transform) to transform audio into the frequency domain, scale the spectrum, and transform it back.
• Performance: Significantly faster than sinc-based approaches.
• Limitation: Does not support changing the resampling ratio once started.

The synchronous resampler always provides the best quality. For the asynchronous resampler, you can balance speed and quality using different interpolation methods:

• Cubic sinc interpolation: Equivalent quality to the synchronous resampler, but computationally heavy.
• Sinc interpolation: You can reduce the length of the sinc function to increase speed (each halving nearly doubles speed) at the cost of high-frequency roll-off. You can also lower the polynomial degree to quadratic or linear to increase speed and distortion.
• Plain polynomial interpolation: The fastest option. It avoids expensive sinc interpolation and provides no anti-alias filtering. It is often efficient enough for many applications with little perceived quality loss.

The Slip resampler is a lightweight tool for matching two rates that are almost identical (e.g., a few ppm difference).

Important Limitations:

• It is not a true sample rate converter; it does not perform interpolation or filtering.
• It works by passing samples through and occasionally inserting or dropping a single frame, using a short crossfade to hide the correction.
• It should only be used for tracking tiny clock drift where the ratio is very close to 1.0. For any significant ratio change, use an Async resampler.

The Slip resampler is a very low-cost option designed to match two almost-equal sample rates by occasionally inserting or dropping a single frame (hidden by a short crossfade).

Use cases:

• Compensating for small clock differences.
• Real-time applications where high-frequency roll-off or delay must be avoided.

Characteristics:

• Adds no delay.
• Adds no high-frequency roll-off.
• The ratio is intended to be adjusted at runtime via the Adjustable trait using a feedback loop.

Asynchronous resampling is used when input and output sample rates are not locked, allowing the resampling ratio to vary over time. This is essential for real-time streams where input and output device clocks may drift.

There are two modes:

1. With Anti-aliasing (Async::new_sinc): Uses band-limited interpolation with sinc filters. This provides high quality but is CPU-intensive. The ratio can be updated at any time.
2. Without Anti-aliasing (Async::new_poly): Omits the sinc interpolation for much higher speed, but produces lower quality results (potential aliasing).

Because the chunk_size is only a target for the fixed side, you must query the resampler for the exact number of frames required for each processing step. Always call these methods before providing or reading data:

1. Call input_frames_next() to find the exact number of input frames required for the next call.
2. Call output_frames_next() to find the exact number of output frames that will be written.

Behavior by mode:

• Fixed input: input_frames_next() always returns chunk_size. output_frames_next() varies.
• Fixed output: output_frames_next() always returns chunk_size. input_frames_next() varies.
• FixedSync::Both: Both values are fixed, but they may differ from chunk_size due to rounding to fit the exact sample-rate ratio.

Ensure your input and output buffers are large enough to accommodate the values returned by these methods.