Documentation updates based on feedback

Author: HEnquist

README.md

@@ -60,9 +60,12 @@ For example, converting a file from 44.1 kHz to 48 kHz.
 The ratio, 48 kHz / 44.1 kHz (equivalent to 160 / 147),
 is fixed and constant throughout the process.
 
-Synchronous resampling is implemented via FFT. The data is FFT:ed, the spectrum modified,
-and then inverse FFT:ed to get the resampled data.
-This type of resampler is considerably faster but doesn't support changing the resampling ratio.
+Synchronous resampling is implemented via FFT (Fast Fourier Transform).
+The audio data is transformed into the frequency domain,
+the spectrum is scaled to match the target sample rate,
+and then transformed back to produce the resampled output.
+This type of resampler is considerably faster than sinc-based approaches
+but doesn't support changing the resampling ratio.
 
 ## Usage
 The resamplers provided by this library are intended to support processing streams of audio.
@@ -74,21 +77,28 @@ This gives a good compromise between efficiency and memory usage.
 ### Chunk size and fixed size options
 
 Rubato processes audio in chunks.
-The size of these chunks is determined by the chunk size parameter given to the resampler constructor.
-Depending on the configuration, this parameter determines
-the number of frames in the input or output chunk, or both.
+The `chunk_size` parameter given to the resampler constructor sets the target size
+for the **fixed side** — the side that always has the same number of frames per call.
+The other side is variable and will differ from call to call.
 
 The resamplers allow specifying which side should have a fixed size.
 
-*   **Fixed input**: The input chunk size is fixed to the given value.
-    The output chunk size will vary depending on how many samples can be calculated using the available input data.
-    This is convenient to use for resampling data from a source that delivers data in fixed size chunks.
-*   **Fixed output**: The output chunk size is fixed to the given value.
-    The input chunk size will vary depending on how many new samples the resampler needs to calculate the output.
-    This is meant to be used for resampling data that will be sent to some target that requires fixed size chunks.
-*   **Both input and output fixed**: Both input and output chunk sizes are fixed.
+*   **Fixed input** (`FixedAsync::Input` / `FixedSync::Input`):
+    The input chunk size is fixed to `chunk_size` frames per call.
+    The output chunk size varies depending on how many samples can be calculated
+    from the available input data.
+    This is convenient when the audio source delivers data in fixed-size chunks
+    (e.g. a hardware capture callback).
+*   **Fixed output** (`FixedAsync::Output` / `FixedSync::Output`):
+    The output chunk size is fixed to `chunk_size` frames per call.
+    The input chunk size varies depending on how many new samples the resampler
+    needs to fill the output.
+    This is useful when the audio destination consumes fixed-size chunks
+    (e.g. a hardware playback callback).
+*   **Both input and output fixed** (`FixedSync::Both`):
+    Both input and output chunk sizes are fixed.
     This mode is only available for the synchronous resampler.
-    In this mode, the chunk size parameter is used as a hint,
+    In this mode, the `chunk_size` parameter is used as a hint,
     and the actual chunk sizes are calculated to fit the resampling ratio exactly.
     For example, a 44.1 kHz to 48 kHz resampler must use an input chunk size that is a multiple of 147,
     and an output chunk size that is a multiple of 160, in order to maintain the correct resampling ratio.
@@ -99,6 +109,24 @@ The resamplers allow specifying which side should have a fixed size.
     For asynchronous resamplers, fixing both input and output chunk sizes is not possible
     since the resampling ratio can change, requiring at least one side to be variable.
 
+### Input and output sizes per call
+
+The `chunk_size` constructor parameter is only the *target* size for the fixed side.
+Always call `input_frames_next()` before providing data to `process_into_buffer`
+to find out the exact number of input frames required for that call.
+Similarly, call `output_frames_next()` to find the exact number of output frames that will be written.
+
+*   With fixed input, `input_frames_next()` always returns `chunk_size`.
+    `output_frames_next()` varies and must be checked each call.
+*   With fixed output, `output_frames_next()` always returns `chunk_size`.
+    `input_frames_next()` varies and must be checked each call.
+*   With `FixedSync::Both`, both values are fixed, but they may differ from `chunk_size`
+    because they are rounded to fit the exact sample-rate ratio.
+
+The input and output buffers must be large enough to hold at least the number of frames
+reported by `input_frames_next()` and `output_frames_next()` respectively.
+Both buffers may be larger than required — only the needed frames are read or written.
+
 ### Resampling quality
 The synchronous resampler has no quality settings, it always delivers the best quality.
 

src/lib.rs

@@ -67,11 +67,41 @@ pub use crate::windows::{calculate_cutoff, WindowFunction};
 
 /// A struct for providing optional parameters when calling
 /// [process_into_buffer](Resampler::process_into_buffer).
+///
+/// All fields have sensible defaults: zero offsets, no partial length, and all channels active.
+/// Pass `None` as the `indexing` argument to use these defaults without constructing the struct.
 #[derive(Debug, Clone)]
 pub struct Indexing {
+    /// Number of frames to skip at the beginning of the input buffer before reading.
+    /// Use this to process a sub-region of a larger buffer without copying data.
+    /// Defaults to `0` (read from the start of the buffer).
     pub input_offset: usize,
+
+    /// Number of frames to skip at the beginning of the output buffer before writing.
+    /// Use this to write results into a sub-region of a larger buffer.
+    /// Defaults to `0` (write from the start of the buffer).
     pub output_offset: usize,
+
+    /// Set to `Some(n)` when the input buffer contains fewer valid frames than
+    /// [Resampler::input_frames_next] requires.
+    /// The resampler will read the first `n` frames from the input buffer and
+    /// treat the remaining frames as silence.
+    /// This is useful for processing the very last (partial) chunk of a stream or audio clip.
+    ///
+    /// **Important:** even with `partial_len` set, the output buffer must still be large enough
+    /// to hold at least [Resampler::output_frames_next] frames (plus `output_offset`),
+    /// because the resampler always produces a full output chunk.
+    ///
+    /// Set to `Some(0)` to process a chunk of pure silence (e.g. to flush the resampler delay).
+    ///
+    /// Defaults to `None`, meaning the full [Resampler::input_frames_next] frames are read.
     pub partial_len: Option<usize>,
+
+    /// Optional per-channel processing mask.
+    /// When `Some(vec)`, each element corresponds to one channel:
+    /// `true` means the channel is processed normally,
+    /// `false` means the channel is skipped and its output is left unchanged.
+    /// When `None`, all channels are processed.
     pub active_channels_mask: Option<Vec<bool>>,
 }
 

src/synchro.rs

@@ -203,14 +203,33 @@ where
     /// In this mode, the chunk size is not arbitrarily selectable.
     /// Instead, it is automatically calculated based on the provided value as a reference.
     ///
-    /// The delay from the resampler depends on the length of the FFT.
-    /// It can be reduced by increasing the `sub_chunks` value.
-    /// This determines how many sub chunks each chunk should be split into while processing.
-    /// The actual number may be different,
-    /// based on what is possible for the given input and output sample rates.
-    /// A large number of sub chunks (i.e. short sub chunks) reduces the cutoff frequency
-    /// of the anti-aliasing filter.
-    /// It is recommended to set `sub_chunks` to 1 unless this leads to an unacceptably large delay.
+    /// The resampler introduces a delay equal to half the internal FFT block size,
+    /// expressed as a number of output frames.
+    /// This delay can be queried via [Resampler::output_delay].
+    ///
+    /// The `sub_chunks` parameter controls how many sub-chunks each processing chunk is divided into.
+    /// A higher value uses a smaller FFT block size, which reduces the delay proportionally.
+    /// However, a smaller FFT block also lowers the cutoff frequency of the anti-aliasing filter,
+    /// which may affect quality at high frequencies.
+    ///
+    /// The actual number of sub-chunks used may differ from the requested value,
+    /// since the FFT block size must be a valid multiple of the minimum block size
+    /// for the given sample rate pair.
+    ///
+    /// A sub-chunk size (i.e. `chunk_size / sub_chunks`) between roughly 100 and 1000 frames
+    /// is generally a good target. The best value depends on the delay tolerance and quality
+    /// requirements of the application. If uncertain, start with a sub-chunk size of a few hundred
+    /// frames — meaning `sub_chunks = chunk_size / desired_sub_chunk_size` — and adjust as needed.
+    ///
+    /// The requested value is treated as a hint: the actual sub-chunk size is rounded up to the
+    /// nearest integer multiple of the minimum valid block size for the given sample rate pair.
+    /// The minimum block size is determined by the GCD (Greatest Common Divisor) of the two
+    /// sample rates: `rate / gcd(rate_in, rate_out)` for each side.
+    /// For example, a 44100 → 48000 resampler has a GCD of 300, giving minimum blocks of 147
+    /// (input) and 160 (output), so sub-chunk sizes can only be multiples of those values.
+    /// A 48000 → 96000 resampler has a GCD of 48000, giving minimum blocks of 1 and 2,
+    /// so the sub-chunk size can be chosen almost freely.
+    /// A value of `0` is treated as `1`.
     ///
     /// Parameters are:
     /// - `sample_rate_input`: Input sample rate, must be > 0.