Summary

The primary Rubber Band Library API is contained in the class RubberBand::RubberBandStretcher. This class can perform both pitch shifting and time stretching and supports every feature of the library. A simpler, more limited API that supports only pitch-shifting can be found in RubberBand::RubberBandLiveShifter.

RubberBandStretcher supports two processing modes, offline and real-time, and two processing "engines", known as the R2 or Faster engine and the R3 or Finer engine. The choices of processing mode and engine are fixed on construction: see the constructor RubberBandStretcher::RubberBandStretcher. The two engines work identically in API terms, and both of them support both offline and real-time modes as described below.

Offline mode

In offline mode, you must provide the audio block-by-block in two passes. In the first pass, call RubberBandStretcher::study() on each block; in the second pass, call RubberBandStretcher::process() on each block and receive the output via RubberBandStretcher::retrieve().

In offline mode, the time and pitch ratios are fixed as soon as the study pass has begun and cannot be changed afterwards. (But see RubberBandStretcher::setKeyFrameMap() for a way to do pre-planned variable time stretching in offline mode.) Offline mode also performs padding and delay compensation so that the stretched result has an exact start and duration.

Real-time mode

In real-time mode, there is no study pass, just a single streaming pass in which the audio is passed to RubberBandStretcher::process() and output received via RubberBandStretcher::retrieve().

In real-time mode you can change the time and pitch ratios at any time.

You may need to perform signal padding and delay compensation in real-time mode; see RubberBandStretcher::getPreferredStartPad() and RubberBandStretcher::getStartDelay() for details.

Rubber Band Library is RT-safe when used in real-time mode with "normal" processing parameters. That is, it performs no allocation, locking, or blocking operations after initialisation during normal use, even when the time and pitch ratios change. There are certain exceptions that include error states and extremely rapid changes between extreme ratios, as well as the case in which more frames are passed to RubberBandStretcher::process() than the values returned by RubberBandStretcher::getSamplesRequired() or set using RubberBandStretcher::setMaxProcessSize(), when buffer reallocation may occur. See the latter function's documentation for details. Note that offline mode is never RT-safe.

Thread safety

Multiple instances of RubberBandStretcher may be created and used in separate threads concurrently. However, for any single instance of RubberBandStretcher, you may not call RubberBandStretcher::process() more than once concurrently, and you may not change the time or pitch ratio while a RubberBandStretcher::process() call is being executed (if the stretcher was created in "real-time mode"; in "offline mode" you can't change the ratios during use anyway).

So you can run RubberBandStretcher::process() in its own thread if you like, but if you want to change ratios dynamically from a different thread, you will need some form of mutex in your code. Changing the time or pitch ratio is real-time safe except in extreme circumstances, so for most applications that may change these dynamically it probably makes most sense to do so from the same thread as calls RubberBandStretcher::process(), even if that is a real-time thread.