PitchShiftOutput< T, BufferT > Class Template Reference

Real-time pitch shifting audio effect. More...

#include <PitchShift.h>

Inheritance diagram for PitchShiftOutput< T, BufferT >:

Public Member Functions
	PitchShiftOutput (Print &out)
	Constructor.
virtual void	addNotifyAudioChange (AudioInfoSupport &bi)
	Adds target to be notified about audio changes.
virtual AudioInfo	audioInfo () override
	provides the actual input AudioInfo
virtual AudioInfo	audioInfoOut ()
virtual int	availableForWrite () override
bool	begin ()
	Initialize pitch shifting with current configuration.
virtual bool	begin (AudioInfo info)
bool	begin (PitchShiftInfo info)
	Initialize pitch shifting with configuration.
virtual void	clearNotifyAudioChange ()
	Deletes all change notify subscriptions.
PitchShiftInfo	defaultConfig ()
	Get default configuration for pitch shifting.
void	end ()
	Stop pitch shifting and deactivate the effect.
virtual void	flush ()
virtual bool	isDeletable ()
	If true we need to release the related memory in the destructor.
bool	isNotifyActive ()
	Checks if the automatic AudioInfo update is active.
virtual	operator bool ()
virtual bool	removeNotifyAudioChange (AudioInfoSupport &bi)
	Removes a target in order not to be notified about audio changes.
virtual void	setAudioInfo (AudioInfo newInfo) override
	Defines the input AudioInfo.
void	setNotifyActive (bool flag)
	Deactivate/Reactivate automatic AudioInfo updates: (default is active)
size_t	write (const uint8_t *data, size_t len) override
	Process and write audio data with pitch shifting applied.
virtual size_t	write (uint8_t ch) override
virtual void	writeSilence (size_t len)

Protected Member Functions
void	notifyAudioChange (AudioInfo info)
T	pitchShift (T value)
	Execute pitch shift on a single sample.

Protected Attributes
int	_timeout = 10
bool	active = false
	Whether pitch shifting is currently active.
BufferT	buffer
	Variable speed buffer for pitch shifting.
PitchShiftInfo	cfg
	Current configuration.
bool	is_active = false
bool	is_notify_active = true
Vector< AudioInfoSupport * >	notify_vector
Print *	p_out = nullptr
	Output stream for processed audio.
SingleBuffer< uint8_t >	tmp {MAX_SINGLE_CHARS}
int	tmpPos = 0

Detailed Description

template<typename T, class BufferT>
class audio_tools::PitchShiftOutput< T, BufferT >

Real-time pitch shifting audio effect.

This class implements real-time pitch shifting that changes the frequency of audio without affecting its duration. It can shift pitch up or down while maintaining the original playback speed. The implementation:

1. Reduces multi-channel audio to mono for processing
2. Applies pitch shifting using a configurable buffer algorithm
3. Outputs the shifted audio in the original channel configuration

The pitch shifting is accomplished using a variable-speed ring buffer that reads at different rates than it writes. Three buffer implementations are available:

• VariableSpeedRingBufferSimple: Basic implementation with potential artifacts
• VariableSpeedRingBuffer180: Uses 180° phase shifting to reduce artifacts
  
• VariableSpeedRingBuffer: Advanced implementation with interpolation and phase restoration

Note

Pitch shifting is a complex DSP operation that requires buffering, which introduces some latency. The buffer size affects both quality and latency.

Template Parameters

T	Sample data type (int16_t, int32_t, float, etc.)
BufferT	Buffer implementation type (one of the VariableSpeedRingBuffer variants)

Constructor & Destructor Documentation

PitchShiftOutput()

template<typename T , class BufferT >

PitchShiftOutput ( Print &  out )

inline

Constructor.

Parameters

out	Reference to the output stream where processed audio will be written

Member Function Documentation

addNotifyAudioChange()

virtual void addNotifyAudioChange ( AudioInfoSupport &  bi )

inlinevirtualinherited

Adds target to be notified about audio changes.

Reimplemented in CodecNOP, EncodedAudioOutput, EncodedAudioStream, AACDecoderFDK, DecoderBasic, MP3DecoderHelix, MP3DecoderMAD, OggContainerDecoder, Pipeline, and Pipeline::ModifyingStreamAdapter.

audioInfo()

virtual AudioInfo audioInfo ( )

inlineoverridevirtualinherited

provides the actual input AudioInfo

Implements AudioInfoSupport.

Reimplemented in AdapterPrintToAudioOutput, and AdapterAudioStreamToAudioOutput.

audioInfoOut()

virtual AudioInfo audioInfoOut ( )

inlinevirtualinherited

provides the actual output AudioInfo: this is usually the same as audioInfo() unless we use a transforming stream

Reimplemented in PureDataStream, PWMAudioOutput, ChannelFormatConverterStreamT< T >, ChannelFormatConverterStream, NumberFormatConverterStreamT< TFrom, TTo >, NumberFormatConverterStream, FormatConverterStream, Pipeline, ResampleStream, and ResampleStreamT< TInterpolator >.

availableForWrite()

virtual int availableForWrite ( )

inlineoverridevirtualinherited

Reimplemented from Print.

Reimplemented in RTSPOutput.

begin() [1/3]

template<typename T , class BufferT >

bool begin ( )

inlinevirtual

Initialize pitch shifting with current configuration.

Returns

true if initialization successful

Reimplemented from AudioOutput.

begin() [2/3]

virtual bool begin ( AudioInfo  info )

inlinevirtualinherited

Reimplemented in AudioESP32ULP, CsvOutput< T >, and EncodedAudioOutput.

begin() [3/3]

template<typename T , class BufferT >

bool begin ( PitchShiftInfo  info )

inline

Initialize pitch shifting with configuration.

Parameters

info	Configuration containing pitch_shift factor, buffer_size, and audio format

Returns

true if initialization successful

defaultConfig()

template<typename T , class BufferT >

PitchShiftInfo defaultConfig ( )

inline

Get default configuration for pitch shifting.

Returns

PitchShiftInfo with default values appropriate for type T

end()

template<typename T , class BufferT >

void end ( )

inlinevirtual

Stop pitch shifting and deactivate the effect.

Reimplemented from AudioOutput.

flush()

virtual void flush ( )

inlinevirtualinherited

Reimplemented from Print.

isDeletable()

virtual bool isDeletable ( )

inlinevirtualinherited

If true we need to release the related memory in the destructor.

Reimplemented in AdapterPrintToAudioOutput, and AdapterAudioStreamToAudioOutput.

operator bool()

virtual operator bool ( )

inlinevirtualinherited

Reimplemented in RTSPOutput, and EncodedAudioOutput.

pitchShift()

template<typename T , class BufferT >

T pitchShift ( T  value )

inlineprotected

Execute pitch shift on a single sample.

This method performs the core pitch shifting operation by writing the input sample to the buffer and reading back the pitch-shifted result. The time difference between write and read operations, controlled by the buffer's increment factor, creates the pitch shift effect.

Parameters

value

Input sample value

Returns

Pitch-shifted sample value

setAudioInfo()

virtual void setAudioInfo ( AudioInfo  info )

inlineoverridevirtualinherited

Defines the input AudioInfo.

Implements AudioInfoSupport.

Reimplemented in ChannelsSelectOutput, AdapterPrintToAudioOutput, MultiOutput, AdapterAudioStreamToAudioOutput, CsvOutput< T >, PWMAudioOutput, and EncodedAudioOutput.

write()

template<typename T , class BufferT >

size_t write ( const uint8_t *  data, size_t  len  )

inlineoverridevirtual

Process and write audio data with pitch shifting applied.

This method processes the input audio by:

1. Converting multi-channel samples to mono by averaging
2. Applying pitch shifting to the mono signal
3. Duplicating the processed signal to all output channels

Parameters

data	Pointer to input audio data
len	Number of bytes to process

Returns

Number of bytes written to output

Implements AudioOutput.

writeSilence()

virtual void writeSilence ( size_t  len )

inlinevirtualinherited

Writes n 0 values (= silence)

Parameters

len

---

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

• src/AudioTools/CoreAudio/AudioEffects/PitchShift.h