Real-time and offline time stretching, 0.5x to 2x, pitch unchanged. More...

#include <TimeStretch.h>

Public Types
enum class	Quality { Standard , Studio }
	The engine that renders the stretch (see the file overview). More...

Public Member Functions
void	setQuality (Quality q) noexcept
	Selects the engine (applied at the next prepare()/reset()).

Quality	getQuality () const noexcept

void	prepare (const AudioSpec &spec, int fftSize=0)
	Allocates every buffer this class will ever use.

void	reset () noexcept
	Clears all signal state and empties the input queue (keeps parameters). Belongs to the owner of the stream.

void	setTimeRatio (T ratio) noexcept
	Sets the stretch as an output/input length ratio.

void	setTempoChangePercent (T pct) noexcept
	Sets the stretch as a tempo change in percent.

void	setTransientPreserve (bool on) noexcept
	Enables phase reset on detected transients (default on). Without it, attacks are stretched along with everything else and soften audibly.

void	setPhaseLock (bool on) noexcept
	Enables identity phase locking (default on).

T	getTimeRatio () const noexcept

bool	getTransientPreserve () const noexcept

bool	getPhaseLock () const noexcept

int	getLatency () const noexcept
	Latency of the fixed-rate processBlock() path in samples: one frame (42.7 ms at the default 2048 frame and 48 kHz), 0 before prepare() succeeds. The rate-changing feedInput()/pullOutput() pair carries no compensation latency - its output is the stretched timeline itself - and the offline process() removes its own delay.

int	getQueuedInputSamples () const noexcept
	Input samples accepted but not yet consumed by the stretch.

int	getInputCapacity () const noexcept
	Room for input right now, in samples (stream owner).

int	getAvailableOutput () const noexcept
	Stretched output ready right now, in samples (stream owner).

int	feedInput (AudioBufferView< const T > in) noexcept
	Hands input to the stretch; real-time safe (stream owner).

int	pullOutput (AudioBufferView< T > out) noexcept
	Takes stretched output; real-time safe (stream owner).

int64_t	getDiscardedInput () const noexcept
	Input samples the fixed-rate adaptor refused, cumulative since prepare() or reset() (stream owner).

std::vector< uint8_t >	getState () const
	Serializes the parameter state (setup/UI threads; allocates).

bool	setState (const uint8_t *data, size_t size)
	Restores parameters from a blob (tolerant; rejects foreign ids).

void	processBlock (AudioBufferView< T > buffer) noexcept
	Fixed-rate playback adaptor: streaming, in-place, real-time safe.

void	process (AudioBufferView< const T > in, AudioBuffer< T > &out)
	Offline whole-signal stretch (setup thread; allocates `out`).

void	beginOffline (int numChannels)
	Opens an offline stretch fed in blocks (setup thread; allocates).

void	pushOffline (AudioBufferView< const T > in)
	Feeds the next block of an offline session. No-op outside one.

void	finishOffline ()
	Ends the input of an offline session; everything left becomes available to pullOffline().

int	getOfflineAvailable () const noexcept
	Stretched samples ready to pull in an offline session.

int	pullOffline (AudioBufferView< T > out)
	Writes up to out.getNumSamples() stretched samples of an offline session and returns how many it wrote. Channels of `out` beyond the session's are left untouched.

Static Public Attributes
static constexpr T	kMinRatio = T(0.5)
	Smallest and largest stretch this class accepts.

static constexpr T	kMaxRatio = T(2)

Detailed Description

template<FloatType T>
class dspark::TimeStretch< T >

Real-time and offline time stretching, 0.5x to 2x, pitch unchanged.

Template Parameters

T	Sample type (float or double).

Definition at line 302 of file TimeStretch.h.

Member Enumeration Documentation

◆ Quality

template<FloatType T>

enum class dspark::TimeStretch::Quality

strong

The engine that renders the stretch (see the file overview).

Studio (default): phase-gradient propagation over a channel-summed reference and a strike-anchored time map (Effects/detail/StudioVocoder.h). Default frame about 85 ms; the fixed-rate adaptor's latency is that frame plus the onset detector's lookahead (about 32 ms).
Standard: the Standard engine, identity phase locking over the first channel's peaks and a transient-locked hop; default frame 2048. Kept bit-exact for renders already made with it; a state blob that predates the quality field restores it.

The choice takes effect at the next prepare() or reset(), because the two engines have different latencies and different stream geometry; getLatency() reports the engine in force.

Enumerator
Standard
Studio

Definition at line 331 of file TimeStretch.h.

Member Function Documentation

◆ beginOffline()

template<FloatType T>

void dspark::TimeStretch< T >::beginOffline ( int numChannels )

inline

Opens an offline stretch fed in blocks (setup thread; allocates).

For a signal too long to hold whole, or one decoded as it goes: push it with pushOffline() in blocks of any size, take the stretched signal as it becomes ready with pullOffline(), and close with finishOffline(), after which the rest can be pulled. The concatenated output is bit-identical to process() over the concatenated input - the same round(inputLength * ratio) samples, aligned with the input - whatever the blocking. Memory holds only what has not been fed to the engine yet (under one hop) and what has not been pulled.

Resets the streaming state and adopts the ratio in force immediately.

Parameters

numChannels Channels the session carries, at most the prepared count (clamped; channels beyond it are ignored by pushOffline()).

Definition at line 831 of file TimeStretch.h.

◆ feedInput()

template<FloatType T>

int dspark::TimeStretch< T >::feedInput ( AudioBufferView< const T > in )

inlinenoexcept

Hands input to the stretch; real-time safe (stream owner).

Takes as many of the block's samples as there is room for, in order, and runs every analysis frame the queue can now feed. Channels the caller does not supply are fed silence, so the stretch stays aligned across a prepared stereo pair.

Parameters

in	Source block; the caller keeps ownership and nothing is aliased or retained.

Returns: Samples taken from each channel, at most getInputCapacity(). 0 before prepare() succeeds or if processBlock() owns the instance.

Definition at line 585 of file TimeStretch.h.

◆ finishOffline()

template<FloatType T>

void dspark::TimeStretch< T >::finishOffline ( )

inline

Ends the input of an offline session; everything left becomes available to pullOffline().

Definition at line 876 of file TimeStretch.h.

◆ getAvailableOutput()

template<FloatType T>

int dspark::TimeStretch< T >::getAvailableOutput ( ) const

inlinenoexcept

Stretched output ready right now, in samples (stream owner).

The bound on what the next pullOutput() can write. 0 until enough input has been fed for the first overlap-add to complete, 0 before prepare() succeeds and 0 unless the pair owns the instance.

Definition at line 564 of file TimeStretch.h.

◆ getDiscardedInput()

template<FloatType T>

int64_t dspark::TimeStretch< T >::getDiscardedInput ( ) const

inlinenoexcept

Input samples the fixed-rate adaptor refused, cumulative since prepare() or reset() (stream owner).

Above ratio 1 the block cannot carry the stretched stream, so the adaptor refuses the fraction 1 - 1/ratio of the input at the head and counts it here rather than displacing what survives. Exactly 0 at ratio 1 and below, where the adaptor pads with silence instead of dropping, and 0 on the feedInput()/pullOutput() path, which refuses nothing.

Definition at line 651 of file TimeStretch.h.

◆ getInputCapacity()

template<FloatType T>

int dspark::TimeStretch< T >::getInputCapacity ( ) const

inlinenoexcept

Room for input right now, in samples (stream owner).

The bound on what the next feedInput() can take. It falls to 0 while the caller stops pulling, which is the back pressure that keeps the stretch honest instead of letting a queue overrun. 0 before prepare() succeeds and 0 once processBlock() owns the instance.

Definition at line 550 of file TimeStretch.h.

◆ getLatency()

template<FloatType T>

int dspark::TimeStretch< T >::getLatency ( ) const

inlinenoexcept

Latency of the fixed-rate processBlock() path in samples: one frame (42.7 ms at the default 2048 frame and 48 kHz), 0 before prepare() succeeds. The rate-changing feedInput()/pullOutput() pair carries no compensation latency - its output is the stretched timeline itself - and the offline process() removes its own delay.

Definition at line 532 of file TimeStretch.h.

◆ getOfflineAvailable()

template<FloatType T>

int dspark::TimeStretch< T >::getOfflineAvailable ( ) const

inlinenoexcept

Stretched samples ready to pull in an offline session.

Definition at line 886 of file TimeStretch.h.

◆ getPhaseLock()

template<FloatType T>

bool dspark::TimeStretch< T >::getPhaseLock ( ) const

inlinenoexcept

Returns: Whether identity phase locking is enabled.

Definition at line 522 of file TimeStretch.h.

◆ getQuality()

template<FloatType T>

Quality dspark::TimeStretch< T >::getQuality ( ) const

inlinenoexcept

Returns: The engine selected for the next prepare()/reset().

Definition at line 341 of file TimeStretch.h.

◆ getQueuedInputSamples()

template<FloatType T>

int dspark::TimeStretch< T >::getQueuedInputSamples ( ) const

inlinenoexcept

Input samples accepted but not yet consumed by the stretch.

Definition at line 538 of file TimeStretch.h.

◆ getState()

template<FloatType T>

std::vector< uint8_t > dspark::TimeStretch< T >::getState ( ) const

inline

Serializes the parameter state (setup/UI threads; allocates).

Definition at line 654 of file TimeStretch.h.

◆ getTimeRatio()

template<FloatType T>

T dspark::TimeStretch< T >::getTimeRatio ( ) const

inlinenoexcept

Returns: Current stretch ratio (output length / input length).

Definition at line 510 of file TimeStretch.h.

◆ getTransientPreserve()

template<FloatType T>

bool dspark::TimeStretch< T >::getTransientPreserve ( ) const

inlinenoexcept

Returns: Whether transient phase reset is enabled.

Definition at line 516 of file TimeStretch.h.

◆ prepare()

template<FloatType T>

void dspark::TimeStretch< T >::prepare	(	const AudioSpec &	spec,
		int	fftSize = `0`
	)

inline

Allocates every buffer this class will ever use.

Invalid specs (non-positive or non-finite rate, block size or channel count) and fftSize values that are not a power of two in [256, 1 << 20] are ignored: the previous state is kept and an unprepared instance stays pass-through.

Parameters

spec	Audio environment specification.
fftSize	STFT frame size, a power of two, used by whichever engine is selected. 0 (the default) selects each engine's own: 2048 for Standard, the power of two nearest 85 ms for Studio (4096 at 44.1 and 48 kHz, 8192 at 88.2 and 96 kHz). Larger favours low-pitched and sustained material, smaller favours dense strikes and lowers latency.

Definition at line 365 of file TimeStretch.h.

◆ process()

template<FloatType T>

void dspark::TimeStretch< T >::process	(	AudioBufferView< const T >	in,
		AudioBuffer< T > &	out
	)

inline

Offline whole-signal stretch (setup thread; allocates out).

out is resized to round(inputLength * ratio) samples and holds the stretched signal aligned with the input: the algorithmic delay is removed here, so no compensation is needed on this path. The ratio in force is adopted immediately rather than glided, and the streaming state is reset. An unprepared instance copies the input through. Identical to beginOffline(), one pushOffline() of the whole signal, finishOffline() and pulling everything.

Parameters

in	Source signal.
out	Destination; resized by this call.

Definition at line 775 of file TimeStretch.h.

◆ processBlock()

template<FloatType T>

void dspark::TimeStretch< T >::processBlock ( AudioBufferView< T > buffer )

inlinenoexcept

Fixed-rate playback adaptor: streaming, in-place, real-time safe.

Takes the block's samples into the input queue and writes the same number of samples of the stretched stream back into the block. See the file header for what happens to the length difference at ratios away from 1: below unity the shortfall is silence, above it the surplus input is refused at the head and reported by getDiscardedInput(). Pass-through until prepare() succeeds, and untouched if the feedInput()/pullOutput() pair already owns the instance; channels beyond the prepared count are left untouched.

Parameters

buffer Audio block; all prepared channels are processed.

Definition at line 694 of file TimeStretch.h.

◆ pullOffline()

template<FloatType T>

int dspark::TimeStretch< T >::pullOffline ( AudioBufferView< T > out )

inline

Writes up to out.getNumSamples() stretched samples of an offline session and returns how many it wrote. Channels of out beyond the session's are left untouched.

Definition at line 897 of file TimeStretch.h.

◆ pullOutput()

template<FloatType T>

int dspark::TimeStretch< T >::pullOutput ( AudioBufferView< T > out )

inlinenoexcept

Takes stretched output; real-time safe (stream owner).

Writes what is ready and no more. The output is the stretched timeline with nothing to compensate: sample k of the stream this returns is sample k of the stretched signal. Channels beyond the prepared count are left untouched.

Parameters

out	Destination block.

Returns: Samples written to each channel, at most getAvailableOutput(). 0 before prepare() succeeds or if processBlock() owns the instance.

Definition at line 622 of file TimeStretch.h.

◆ pushOffline()

template<FloatType T>

void dspark::TimeStretch< T >::pushOffline ( AudioBufferView< const T > in )

inline

Feeds the next block of an offline session. No-op outside one.

Definition at line 857 of file TimeStretch.h.

◆ reset()

template<FloatType T>

void dspark::TimeStretch< T >::reset ( )

inlinenoexcept

Clears all signal state and empties the input queue (keeps parameters). Belongs to the owner of the stream.

Definition at line 412 of file TimeStretch.h.

◆ setPhaseLock()

template<FloatType T>

void dspark::TimeStretch< T >::setPhaseLock ( bool on )

inlinenoexcept

Enables identity phase locking (default on).

Off leaves the plain phase vocoder, where every bin advances on its own instantaneous frequency and the bins of one partial lose their relative phase - the classic phasiness. It is exposed so the difference can be heard and measured, not because it is ever the better setting.

Definition at line 503 of file TimeStretch.h.

◆ setQuality()

template<FloatType T>

void dspark::TimeStretch< T >::setQuality ( Quality q )

inlinenoexcept

Selects the engine (applied at the next prepare()/reset()).

Definition at line 334 of file TimeStretch.h.

◆ setState()

template<FloatType T>

bool dspark::TimeStretch< T >::setState	(	const uint8_t *	data,
		size_t	size
	)

inline

Restores parameters from a blob (tolerant; rejects foreign ids).

Definition at line 665 of file TimeStretch.h.

◆ setTempoChangePercent()

template<FloatType T>

void dspark::TimeStretch< T >::setTempoChangePercent ( T pct )

inlinenoexcept

Sets the stretch as a tempo change in percent.

Playing a passage pct percent faster means fitting it into 1 / (1 + pct/100) of the time, so that is the ratio this sets: +10 gives 0.909, -10 gives 1.111. Values outside the ratio range clamp to it; non-finite values are ignored.

Definition at line 478 of file TimeStretch.h.

◆ setTimeRatio()

template<FloatType T>

void dspark::TimeStretch< T >::setTimeRatio ( T ratio )

inlinenoexcept

Sets the stretch as an output/input length ratio.

Above 1 the signal gets longer (slower); below 1 shorter (faster). Clamped to [0.5, 2]. Non-finite values are ignored. The change glides in over a few frames rather than jumping, so it is click-free on a running stream; reset() adopts it immediately.

Definition at line 462 of file TimeStretch.h.

◆ setTransientPreserve()

template<FloatType T>

void dspark::TimeStretch< T >::setTransientPreserve ( bool on )

inlinenoexcept

Enables phase reset on detected transients (default on). Without it, attacks are stretched along with everything else and soften audibly.

Definition at line 489 of file TimeStretch.h.

Member Data Documentation

◆ kMaxRatio

template<FloatType T>

constexpr T dspark::TimeStretch< T >::kMaxRatio = T(2)

staticconstexpr

Definition at line 312 of file TimeStretch.h.

◆ kMinRatio

template<FloatType T>

constexpr T dspark::TimeStretch< T >::kMinRatio = T(0.5)

staticconstexpr

Smallest and largest stretch this class accepts.

Definition at line 311 of file TimeStretch.h.

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

TimeStretch.h

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ Quality

Member Function Documentation

◆ beginOffline()

◆ feedInput()

◆ finishOffline()

◆ getAvailableOutput()

◆ getDiscardedInput()

◆ getInputCapacity()

◆ getLatency()

◆ getOfflineAvailable()

◆ getPhaseLock()

◆ getQuality()

◆ getQueuedInputSamples()

◆ getState()

◆ getTimeRatio()

◆ getTransientPreserve()

◆ prepare()

◆ process()

◆ processBlock()

◆ pullOffline()

◆ pullOutput()

◆ pushOffline()

◆ reset()

◆ setPhaseLock()

◆ setQuality()

◆ setState()

◆ setTempoChangePercent()

◆ setTimeRatio()

◆ setTransientPreserve()

Member Data Documentation

◆ kMaxRatio

◆ kMinRatio