#include <RubberBandLiveShifter.h>

Classes
struct	Logger
	Interface for log callbacks that may optionally be provided to the shifter on construction. More...

Public Types
enum	Option { OptionWindowShort = 0x00000000 , OptionWindowMedium = 0x00100000 , OptionFormantShifted = 0x00000000 , OptionFormantPreserved = 0x01000000 , OptionChannelsApart = 0x00000000 , OptionChannelsTogether = 0x10000000 }

enum	PresetOption { DefaultOptions = 0x00000000 }

typedef int	Options
	A bitwise OR of values from the RubberBandLiveShifter::Option enum.

Public Member Functions
	RubberBandLiveShifter (size_t sampleRate, size_t channels, Options options)
	Construct a pitch shifter object to run at the given sample rate, with the given number of channels.

	RubberBandLiveShifter (size_t sampleRate, size_t channels, std::shared_ptr< Logger > logger, Options options)
	Construct a pitch shifter object with a custom debug logger.

	~RubberBandLiveShifter ()

void	reset ()
	Reset the shifter's internal buffers.

void	setPitchScale (double scale)
	Set the pitch scaling ratio for the shifter.

void	setFormantScale (double scale)
	Set a pitch scale for the vocal formant envelope separately from the overall pitch scale.

double	getPitchScale () const
	Return the last pitch scaling ratio value that was set (either on construction or with setPitchScale()).

double	getFormantScale () const
	Return the last formant scaling ratio that was set with setFormantScale, or 0.0 if the default automatic scaling is in effect.

size_t	getStartDelay () const
	Return the output delay of the shifter.

size_t	getChannelCount () const
	Return the number of channels this shifter was constructed with.

void	setFormantOption (Options options)
	Change an OptionFormant configuration setting.

size_t	getBlockSize () const
	Query the number of sample frames that must be passed to, and will be returned by, each shift() call.

void	shift (const float const input, float const output)
	Pitch-shift a single block of sample frames.

void	setDebugLevel (int level)
	Set the level of debug output.

Static Public Member Functions
static void	setDefaultDebugLevel (int level)
	Set the default level of debug output for subsequently constructed shifters.

Protected Member Functions
	RubberBandLiveShifter (const RubberBandLiveShifter &)=delete

RubberBandLiveShifter &	operator= (const RubberBandLiveShifter &)=delete

Protected Attributes
Impl *	m_d

Detailed Description

Summary

RubberBand::RubberBandLiveShifter is an interface to the Rubber Band Library designed for applications that need to perform pitch-shifting only, without time-stretching, and to do so in a straightforward block-by-block process with the shortest available processing delay. For the more general interface, see RubberBand::RubberBandStretcher.

RubberBandLiveShifter has a much simpler API than RubberBandStretcher. Its process function, called RubberBandLiveShifter::shift(), accepts a fixed number of sample frames on each call and always returns exactly the same number of sample frames. This is in contrast to the process/available/retrieve call sequence that RubberBandStretcher requires as a result of its variable output rate.

The number of frames accepted by and returned from RubberBandLiveShifter::shift() are not under the caller's control: they must always be exactly the number given by RubberBandLiveShifter::getBlockSize(). But this number is fixed for the lifetime of the shifter, so it only needs to be queried once after construction and then fixed-size buffers may be used.

Using RubberBandLiveShifter also gives a shorter processing delay than a typical buffering setup using RubberBandStretcher, making it a useful choice for some streamed or live situations. However, it is still not a low-latency effect, with a delay of 50ms or more between input and output signals depending on configuration. (The actual value may be queried via RubberBandLiveShifter::getStartDelay().) The shifter is real-time safe in the sense of avoiding allocation, locking, or blocking operations in the processing path.

Thread safety

Multiple instances of RubberBandLiveShifter may be created and used in separate threads concurrently. However, for any single instance of RubberBandLiveShifter, you may not call RubberBandLiveShifter::shift() more than once concurrently, and you may not change the pitch scaling ratio using RubberBandLiveShifter::setPitchScale() while a RubberBandLiveShifter::shift() call is being executed. Changing the ratio is real-time safe, so when the pitch ratio is time-varying, it is normal to update the ratio before each shift call.

Definition at line 94 of file RubberBandLiveShifter.h.

Member Typedef Documentation

◆ Options

int RubberBand::RubberBandLiveShifter::Options

A bitwise OR of values from the RubberBandLiveShifter::Option enum.

Definition at line 115 of file RubberBandLiveShifter.h.

Member Enumeration Documentation

◆ Option

enum RubberBand::RubberBandLiveShifter::Option

Enumerator
OptionWindowShort
OptionWindowMedium
OptionFormantShifted
OptionFormantPreserved
OptionChannelsApart
OptionChannelsTogether

Definition at line 98 of file RubberBandLiveShifter.h.

◆ PresetOption

enum RubberBand::RubberBandLiveShifter::PresetOption

Enumerator
DefaultOptions

Definition at line 117 of file RubberBandLiveShifter.h.

Constructor & Destructor Documentation

◆ RubberBandLiveShifter() [1/3]

RubberBand::RubberBandLiveShifter::RubberBandLiveShifter	(	size_t	sampleRate,
		size_t	channels,
		Options	options )

Construct a pitch shifter object to run at the given sample rate, with the given number of channels.

◆ RubberBandLiveShifter() [2/3]

RubberBand::RubberBandLiveShifter::RubberBandLiveShifter	(	size_t	sampleRate,
		size_t	channels,
		std::shared_ptr< Logger >	logger,
		Options	options )

Construct a pitch shifter object with a custom debug logger.

This may be useful for debugging if the default logger output (which simply goes to cerr) is not visible in the runtime environment, or if the application has a standard or more realtime-appropriate logging mechanism.

See the documentation for the other constructor above for details of the arguments other than the logger.

Note that although the supplied logger gets to decide what to do with log messages, the separately-set debug level (see setDebugLevel() and setDefaultDebugLevel()) still determines whether any given debug message is sent to the logger in the first place.

◆ ~RubberBandLiveShifter()

RubberBand::RubberBandLiveShifter::~RubberBandLiveShifter ( )

◆ RubberBandLiveShifter() [3/3]

RubberBand::RubberBandLiveShifter::RubberBandLiveShifter ( const RubberBandLiveShifter & )

protecteddelete

Member Function Documentation

◆ reset()

void RubberBand::RubberBandLiveShifter::reset ( )

Reset the shifter's internal buffers.

The shifter should subsequently behave as if it had just been constructed (although retaining the current pitch ratio).

◆ setPitchScale()

void RubberBand::RubberBandLiveShifter::setPitchScale ( double scale )

Set the pitch scaling ratio for the shifter.

This is the ratio of target frequency to source frequency. For example, a ratio of 2.0 would shift up by one octave; 0.5 down by one octave; or 1.0 leave the pitch unaffected.

To put this in musical terms, a pitch scaling ratio corresponding to a shift of S equal-tempered semitones (where S is positive for an upwards shift and negative for downwards) is pow(2.0, S / 12.0).

This function may be called at any time, so long as it is not called concurrently with shift(). You should either call this function from the same thread as shift(), or provide your own mutex or similar mechanism to ensure that setPitchScale and shift() cannot be run at once (there is no internal mutex for this purpose).

◆ setFormantScale()

void RubberBand::RubberBandLiveShifter::setFormantScale ( double scale )

Set a pitch scale for the vocal formant envelope separately from the overall pitch scale.

This is a ratio of target frequency to source frequency. For example, a ratio of 2.0 would shift the formant envelope up by one octave; 0.5 down by one octave; or 1.0 leave the formant unaffected.

By default this is set to the special value of 0.0, which causes the scale to be calculated automatically. It will be treated as 1.0 / the pitch scale if OptionFormantPreserved is specified, or 1.0 for OptionFormantShifted.

Conversely, if this is set to a value other than the default 0.0, formant shifting will happen regardless of the state of the OptionFormantPreserved/OptionFormantShifted option.

This function is provided for special effects only. You do not need to call it for ordinary pitch shifting, with or without formant preservation - just specify or omit the OptionFormantPreserved option as appropriate. Use this function only if you want to shift formants by a distance other than that of the overall pitch shift.

◆ getPitchScale()

double RubberBand::RubberBandLiveShifter::getPitchScale ( ) const

Return the last pitch scaling ratio value that was set (either on construction or with setPitchScale()).

◆ getFormantScale()

double RubberBand::RubberBandLiveShifter::getFormantScale ( ) const

Return the last formant scaling ratio that was set with setFormantScale, or 0.0 if the default automatic scaling is in effect.

◆ getStartDelay()

size_t RubberBand::RubberBandLiveShifter::getStartDelay ( ) const

Return the output delay of the shifter.

This is the number of audio samples that one should discard at the start of the output, in order to ensure that the resulting audio has the expected time alignment with the input.

Ensure you have set the pitch scale to its proper starting value before calling getStartDelay().

◆ getChannelCount()

size_t RubberBand::RubberBandLiveShifter::getChannelCount ( ) const

Return the number of channels this shifter was constructed with.

◆ setFormantOption()

void RubberBand::RubberBandLiveShifter::setFormantOption ( Options options )

Change an OptionFormant configuration setting.

This may be called at any time in any mode.

Note that if running multi-threaded in Offline mode, the change may not take effect immediately if processing is already under way when this function is called.

◆ getBlockSize()

size_t RubberBand::RubberBandLiveShifter::getBlockSize ( ) const

Query the number of sample frames that must be passed to, and will be returned by, each shift() call.

This value is fixed for the lifetime of the shifter.

Note that the blocksize refers to the number of audio sample frames, which may be multi-channel, not the number of individual samples.

◆ shift()

void RubberBand::RubberBandLiveShifter::shift	(	const float const	input,
		float const	output )

Pitch-shift a single block of sample frames.

The number of sample frames (samples per channel) processed per call is constant.

"input" should point to de-interleaved audio data with one float array per channel, with each array containing n samples where n is the value returned by getBlockSize().

"output" should point to a float array per channel, with each array having enough room to store n samples where n is the value returned by getBlockSize().

The input and output must be separate arrays; they cannot alias one another or overlap.

Sample values are conventionally expected to be in the range -1.0f to +1.0f.

◆ setDebugLevel()

void RubberBand::RubberBandLiveShifter::setDebugLevel ( int level )

Set the level of debug output.

The supported values are:

Report errors only.
Report some information on construction and ratio change. Nothing is reported during normal processing unless something changes.
Report a significant amount of information about ongoing calculations during normal processing.

The default is whatever has been set using setDefaultDebugLevel(), or 0 if that function has not been called.

All output goes to cerr unless a custom RubberBandLiveShifter::Logger has been provided on construction. Because writing to cerr is not RT-safe, only debug level 0 is RT-safe in normal use by default. Debug levels 0 and 1 use only C-string constants as debug messages, so they are RT-safe if your custom logger is RT-safe. Levels 2 and 3 are not guaranteed to be RT-safe in any conditions as they may construct messages by allocation.

See also: Logger; setDefaultDebugLevel

◆ setDefaultDebugLevel()

static void RubberBand::RubberBandLiveShifter::setDefaultDebugLevel ( int level )

static

Set the default level of debug output for subsequently constructed shifters.

See also: setDebugLevel

◆ operator=()

RubberBandLiveShifter & RubberBand::RubberBandLiveShifter::operator= ( const RubberBandLiveShifter & )