engine::TimeStretcher Class Reference

Handles time/pitch stretching using various supported libraries. More...

#include <tracktion_TimeStretch.h>

Classes
struct	ElastiqueProOptions
	A set of options that can be used in conjunction with the elastiquePro Mode to fine tune the algorithm. More...

Public Types
enum	Mode {   disabled = 0 , elastiqueTransient = 1 , elastiqueTonal = 2 , soundtouchNormal = 3 ,   soundtouchBetter = 4 , ara = 5 , melodyne = ara , elastiquePro = 6 ,   elastiqueEfficient = 7 , elastiqueMobile = 8 , elastiqueMonophonic = 9 , rubberbandMelodic = 10 ,   rubberbandPercussive = 11 , elastiqueDirectPro = 12 , elastiqueDirectEfficient = 13 , elastiqueDirectMobile = 14 ,   signalsmithDefault = 15 , signalsmithCheaper = 16 , defaultMode = disabled }
	Holds the various algorithms to which can be used (if enabled). More...

Public Member Functions
	TimeStretcher ()
	Creates an TimeStretcher using the default mode.
	~TimeStretcher ()
	Destructor.
void	initialise (double sourceSampleRate, int samplesPerBlock, int numChannels, Mode, ElastiqueProOptions, bool realtime)
	Initialises the TimeStretcher ready to perform timestretching.
bool	isInitialised () const
	Returns true if this has been fully initialised.
void	reset ()
	Resets the TimeStretcher ready for a new set of audio data, maintains mode, speed and pitch ratios.
bool	setSpeedAndPitch (float speedRatio, float semitones)
	Sets the timestretch speed ratio and semitones pitch shift.
int	getMaxFramesNeeded () const
	Returns the maximum number of frames that will ever be returned by getFramesNeeded.
int	getFramesNeeded () const
	Returns the expected number of frames required to generate some output.
int	processData (const float *const *inChannels, int numSamples, float *const *outChannels)
	Processes some input frames and fills some output frames with the applied speed ratio and pitch shift.
int	processData (AudioFifo &inFifo, int numSamples, AudioFifo &outFifo)
	Processes some input frames and fills some output frames from a pair of AudioFifos, useful for real-time use.
int	flush (float *const *outChannels)
	Flushes the end of the stream when input data is exhausted but there is still output data available.
int	getLatencySamples () const
	Returns the latency in samples introduced by the stretching algorithm.

Static Public Member Functions
static Mode	checkModeIsAvailable (Mode)
	Checks if the given mode is available for use.
static juce::StringArray	getPossibleModes (Engine &, bool excludeARA)
	Returns the names of the available Modes.
static Mode	getModeFromName (Engine &, const juce::String &name)
	Returns the Mode for a given name.
static juce::String	getNameOfMode (Mode)
	Returns the name of a given Mode for display purposes.
static bool	isARA (Mode)
	Returns true if the given Mode is an ARA mode.
static bool	isMelodyne (Mode m)
static bool	canProcessFor (Mode)
	Checks that the given Mode is a valid mode and not disabled.
static int	getLatencySamplesForMode (Mode, double sampleRate, bool realtime)
	Returns the latency for a given mode and sample rate without creating a full stretcher.

Detailed Description

Handles time/pitch stretching using various supported libraries.

Currently supported libraries are SoundTouch, RubberBand, Elastique and Signalsmith Stretch. These libraries may require additional module config options to enable and fall under their own licence terms so make sure to check those before distributing any code.

Member Enumeration Documentation

Mode

enum engine::TimeStretcher::Mode

Holds the various algorithms to which can be used (if enabled).

Enumerator
disabled	No algorithm enabled.
elastiqueTransient	Defunct, don't use.
elastiqueTonal	Defunct, don't use.
soundtouchNormal	SoundTouch normal quality, lower CPU use.
soundtouchBetter	SoundTouch better quality, higher CPU use.
ara	ARA plugin (e.g. Melodyne), only used for clip timestretching.
melodyne	Deprecated: Use ara instead.
elastiquePro	Elastique Pro good all round (. See also ElastiqueProOptions).
elastiqueEfficient	Elastique lower quality and lower CPU usage.
elastiqueMobile	Elastique lower quality and lower CPU usage, optimised for mobile.
elastiqueMonophonic	Elastique which can sound better for monophonic sounds.
rubberbandMelodic	RubberBand tailored to melodic sounds prioritising pitch accuracy.
rubberbandPercussive	RubberBand tailored to percussive sounds prioritising transient accuracy.
elastiqueDirectPro	Elastique Direct Pro good all round (. See also ElastiqueProOptions).
elastiqueDirectEfficient	Elastique Direct lower quality and lower CPU usage.
elastiqueDirectMobile	Elastique Direct lower quality and lower CPU usage, optimised for mobile.
signalsmithDefault	Signalsmith Stretch default quality preset.
signalsmithCheaper	Signalsmith Stretch cheaper/faster preset.
defaultMode	Default mode.

Constructor & Destructor Documentation

TimeStretcher()

engine::TimeStretcher::TimeStretcher

(

)

Creates an TimeStretcher using the default mode.

~TimeStretcher()

engine::TimeStretcher::~TimeStretcher

(

)

Destructor.

Member Function Documentation

checkModeIsAvailable()

static Mode engine::TimeStretcher::checkModeIsAvailable ( Mode  )

static

Checks if the given mode is available for use.

getPossibleModes()

static juce::StringArray engine::TimeStretcher::getPossibleModes ( Engine &  , bool  excludeARA  )

static

Returns the names of the available Modes.

getModeFromName()

static Mode engine::TimeStretcher::getModeFromName ( Engine &  , const juce::String &  name  )

static

Returns the Mode for a given name.

See also

getPossibleModes.

getNameOfMode()

static juce::String engine::TimeStretcher::getNameOfMode ( Mode  )

static

Returns the name of a given Mode for display purposes.

isARA()

static bool engine::TimeStretcher::isARA ( Mode  )

static

Returns true if the given Mode is an ARA mode.

isMelodyne()

static bool engine::TimeStretcher::isMelodyne ( Mode  m )

static

Deprecated:

Use isARA instead.

canProcessFor()

static bool engine::TimeStretcher::canProcessFor ( Mode  )

static

Checks that the given Mode is a valid mode and not disabled.

initialise()

void engine::TimeStretcher::initialise	(	double	sourceSampleRate,
		int	samplesPerBlock,
		int	numChannels,
		Mode	,
		ElastiqueProOptions	,
		bool	realtime
	)

Initialises the TimeStretcher ready to perform timestretching.

This must be called at least once before calling the processData methods.

Parameters

sourceSampleRate	The sample rate this will be processed at
samplesPerBlock	The expected number of samples per process block
numChannels	The number of channels to process
Mode	The Mode to enable
ElastiqueProOptions	The Elastique options to use, ignored in non-ElastiquePro modes
realtime	Indicates this is for real-time or offline use

isInitialised()

bool engine::TimeStretcher::isInitialised

(

)

const

Returns true if this has been fully initialised.

reset()

void engine::TimeStretcher::reset

(

)

Resets the TimeStretcher ready for a new set of audio data, maintains mode, speed and pitch ratios.

setSpeedAndPitch()

bool engine::TimeStretcher::setSpeedAndPitch	(	float	speedRatio,
		float	semitones
	)

Sets the timestretch speed ratio and semitones pitch shift.

Parameters

speedRatio	The ratio for timestretched speed. 1 = no stretching, 2 = half as fast, 0.5 = twice as fast etc.
semitones	The number of semitones to adjust the pitch by 0 = not shift, 12 = up one oct, -12 = down one oct etc.

getMaxFramesNeeded()

int engine::TimeStretcher::getMaxFramesNeeded

(

)

const

Returns the maximum number of frames that will ever be returned by getFramesNeeded.

This can be used to size FIFOs for real-time use accordingly.

getFramesNeeded()

int engine::TimeStretcher::getFramesNeeded

(

)

const

Returns the expected number of frames required to generate some output.

This should be queried each block and the returned number of frames be passes to processData. Passing this many frames to processData must always produce at least one block of output, including the first call after a reset, so implementations account for any internal buffering their algorithm needs before it emits. This never exceeds getMaxFramesNeeded.

processData() [1/2]

int engine::TimeStretcher::processData	(	const float *const *	inChannels,
		int	numSamples,
		float *const *	outChannels
	)

Processes some input frames and fills some output frames with the applied speed ratio and pitch shift.

Parameters

inChannels	The input sample data in non-interleaved format
numSamples	The number of input frames to read from inChannels
outChannels	The destination for non-interleaved output samples. This should be as big as samplesPerBlock passed to the constructor but it may not fill the whole buffer. In cases where less than samplesPerBlock is returned, you should query getFramesNeeded and call this method again, incrementing destination buffers as required.

Returns

The number of frames read and hence written to outChannels

processData() [2/2]

int engine::TimeStretcher::processData	(	AudioFifo &	inFifo,
		int	numSamples,
		AudioFifo &	outFifo
	)

Processes some input frames and fills some output frames from a pair of AudioFifos, useful for real-time use.

Parameters

inFifo	The input sample data to read from
numSamples	The number of input frames to read from inFifo. In inFifo must have this number of frames ready
outFifo	The destination for output samples. This should have at lest samplesPerBlock free.

Returns

The number of frames read and hence written to outFifo

flush()

int engine::TimeStretcher::flush

(

float *const *

outChannels

)

Flushes the end of the stream when input data is exhausted but there is still output data available.

Once you have called this, you can no longer call processData.

Parameters

outChannels

The destination for non-interleaved output samples. This should be as big as samplesPerBlock passed to the constructor but it may not fill the whole buffer. In cases where less than samplesPerBlock is returned, you should query getFramesNeeded and call this method again, incrementing destination buffers as required.

Returns

The number of frames read and hence written to outChannels

getLatencySamples()

int engine::TimeStretcher::getLatencySamples

(

)

const

Returns the latency in samples introduced by the stretching algorithm.

This can be used to report latency to the audio graph for compensation.

getLatencySamplesForMode()

static int engine::TimeStretcher::getLatencySamplesForMode ( Mode  , double  sampleRate, bool  realtime  )

static

Returns the latency for a given mode and sample rate without creating a full stretcher.

Useful for reporting latency to the graph before the stretcher is initialised.

---

The documentation for this class was generated from the following file:

• tracktion_TimeStretch.h