Real-time phase-vocoder pitch shifter (+-12 semitones, stereo-linked). More...

#include <PitchShifter.h>

Public Types
enum class	Quality { Standard , High , Studio }
	Engine and resample-back reader (see the file overview). More...

Public Member Functions
void	prepare (const AudioSpec &spec, int fftSize=0)
	Allocates all rings and spectral state.

void	reset () noexcept
	Clears all signal state (keeps parameters). Safe on the audio thread.

void	setQuality (Quality quality) noexcept
	Selects the engine and reader. Thread-safe. Standard and High crossfade into each other over 64 samples; crossing to or from Studio restarts the stream at the next block (the latencies differ), so a host should re-read getLatency() after it.

Quality	getQuality () const noexcept

void	setSemitones (T st) noexcept
	Sets the pitch shift in semitones, clamped to +-12.

void	setPitchRatio (T ratio) noexcept
	Sets the pitch shift as a frequency ratio, clamped to [0.5, 2]. Non-finite values are ignored.

void	setMix (T mix) noexcept
	Dry/wet mix, [0, 1]. The dry path is latency-compensated and the mix is ramped over at least 20 ms (the wet stream is decorrelated from the dry, so an unsmoothed step would click). Non-finite values are ignored.

void	setTransientPreserve (bool enabled) noexcept
	Enables phase reset on detected transients (default on).

void	setFormantPreserve (bool enabled) noexcept
	Keeps formants (vocal timbre) in place while pitch moves.

T	getSemitones () const noexcept

T	getMix () const noexcept

bool	getTransientPreserve () const noexcept

bool	getFormantPreserve () const noexcept

int	getLatency () const noexcept
	Reports total latency in samples. Studio: 1.5 * fftSize + lookahead + fftSize / 4 + 64 (5184, 108 ms, at the default frame and 48 kHz), held at every pitch. Standard and High: 2 * fftSize, exact at unity only (their real delay drifts with the pitch; file overview).

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
	Processes audio in-place.

Detailed Description

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

Real-time phase-vocoder pitch shifter (+-12 semitones, stereo-linked).

Template Parameters

T	Sample type (float or double).

Definition at line 102 of file PitchShifter.h.

Member Enumeration Documentation

◆ Quality

template<FloatType T>

enum class dspark::PitchShifter::Quality

strong

Engine and resample-back reader (see the file overview).

Enumerator
Standard	Standard/High engine, 4-point Catmull-Rom reader: the earlier default rendering.
High	Standard/High engine, 32-tap windowed-sinc reader: transparent HF.
Studio	Studio engine (default): see the file overview.

Definition at line 227 of file PitchShifter.h.

Member Function Documentation

◆ getFormantPreserve()

template<FloatType T>

bool dspark::PitchShifter< T >::getFormantPreserve ( ) const

inlinenoexcept

Returns: Whether formant preservation is enabled.

Definition at line 327 of file PitchShifter.h.

◆ getLatency()

template<FloatType T>

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

inlinenoexcept

Reports total latency in samples. Studio: 1.5 * fftSize + lookahead + fftSize / 4 + 64 (5184, 108 ms, at the default frame and 48 kHz), held at every pitch. Standard and High: 2 * fftSize, exact at unity only (their real delay drifts with the pitch; file overview).

Definition at line 336 of file PitchShifter.h.

◆ getMix()

template<FloatType T>

T dspark::PitchShifter< T >::getMix ( ) const

inlinenoexcept

Returns: Current dry/wet mix.

Definition at line 318 of file PitchShifter.h.

◆ getQuality()

template<FloatType T>

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

inlinenoexcept

Returns: The resample-back reader quality.

Definition at line 249 of file PitchShifter.h.

◆ getSemitones()

template<FloatType T>

T dspark::PitchShifter< T >::getSemitones ( ) const

inlinenoexcept

Returns: Current shift in semitones.

Definition at line 312 of file PitchShifter.h.

◆ getState()

template<FloatType T>

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

inline

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

Definition at line 339 of file PitchShifter.h.

◆ getTransientPreserve()

template<FloatType T>

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

inlinenoexcept

Returns: Whether transient phase reset is enabled.

Definition at line 321 of file PitchShifter.h.

◆ prepare()

template<FloatType T>

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

inline

Allocates all rings and spectral state.

Invalid specs (non-positive/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 2048 for Standard and High, and the power of two nearest 43 ms for Studio (2048 at 44.1 and 48 kHz, 4096 at 88.2 and 96 kHz). Smaller sizes lower latency and favour transients; larger sizes favour low-pitched material (Studio at 4096: lower spectral error, see the file overview, at 1.5 times the latency).

Definition at line 125 of file PitchShifter.h.

◆ processBlock()

template<FloatType T>

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

inlinenoexcept

Processes audio in-place.

Pass-through until prepare() succeeds. Channels beyond the prepared count are left untouched.

Parameters

buffer Audio block; all prepared channels are processed.

Definition at line 373 of file PitchShifter.h.

◆ reset()

template<FloatType T>

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

inlinenoexcept

Clears all signal state (keeps parameters). Safe on the audio thread.

Definition at line 199 of file PitchShifter.h.

◆ setFormantPreserve()

template<FloatType T>

void dspark::PitchShifter< T >::setFormantPreserve ( bool enabled )

inlinenoexcept

Keeps formants (vocal timbre) in place while pitch moves.

A cepstral lift extracts the smooth spectral envelope of each frame (quefrencies below ~1 ms) and the synthesis magnitudes are pre-warped by env(k*ratio)/env(k), so after the output resampler the envelope lands back where it started - the classic anti-chipmunk correction. Costs two extra FFTs per frame. Default off.

Definition at line 305 of file PitchShifter.h.

◆ setMix()

template<FloatType T>

void dspark::PitchShifter< T >::setMix ( T mix )

inlinenoexcept

Dry/wet mix, [0, 1]. The dry path is latency-compensated and the mix is ramped over at least 20 ms (the wet stream is decorrelated from the dry, so an unsmoothed step would click). Non-finite values are ignored.

Definition at line 283 of file PitchShifter.h.

◆ setPitchRatio()

template<FloatType T>

void dspark::PitchShifter< T >::setPitchRatio ( T ratio )

inlinenoexcept

Sets the pitch shift as a frequency ratio, clamped to [0.5, 2]. Non-finite values are ignored.

Definition at line 270 of file PitchShifter.h.

◆ setQuality()

template<FloatType T>

void dspark::PitchShifter< T >::setQuality ( Quality quality )

inlinenoexcept

Selects the engine and reader. Thread-safe. Standard and High crossfade into each other over 64 samples; crossing to or from Studio restarts the stream at the next block (the latencies differ), so a host should re-read getLatency() after it.

Parameters

quality Engine and reader. Out-of-range values clamp to Studio.

Definition at line 241 of file PitchShifter.h.

◆ setSemitones()

template<FloatType T>

void dspark::PitchShifter< T >::setSemitones ( T st )

inlinenoexcept

Sets the pitch shift in semitones, clamped to +-12.

The active shift glides toward the target at up to 0.5 semitones per analysis hop (a few ms at the default frame size), so live changes are click-free. Non-finite values are ignored.

Definition at line 261 of file PitchShifter.h.

◆ setState()

template<FloatType T>

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

inline

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

Definition at line 351 of file PitchShifter.h.

◆ setTransientPreserve()

template<FloatType T>

void dspark::PitchShifter< T >::setTransientPreserve ( bool enabled )

inlinenoexcept

Enables phase reset on detected transients (default on).

Definition at line 290 of file PitchShifter.h.

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

PitchShifter.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Quality

Member Function Documentation

◆ getFormantPreserve()

◆ getLatency()

◆ getMix()

◆ getQuality()

◆ getSemitones()

◆ getState()

◆ getTransientPreserve()

◆ prepare()

◆ processBlock()

◆ reset()

◆ setFormantPreserve()

◆ setMix()

◆ setPitchRatio()

◆ setQuality()

◆ setSemitones()

◆ setState()

◆ setTransientPreserve()