Base class for a musical device that can play sounds. More...

#include <juce_Synthesiser.h>

Collaboration diagram for juce::Synthesiser:

[legend]

Public Member Functions
	Synthesiser ()
	Creates a new synthesiser. More...

virtual	~Synthesiser ()
	Destructor. More...

SynthesiserSound *	addSound (const SynthesiserSound::Ptr &newSound)
	Adds a new sound to the synthesiser. More...

SynthesiserVoice *	addVoice (SynthesiserVoice *newVoice)
	Adds a new voice to the synth. More...

virtual void	allNotesOff (int midiChannel, bool allowTailOff)
	Turns off all notes. More...

void	clearSounds ()
	Deletes all sounds. More...

void	clearVoices ()
	Deletes all voices. More...

int	getNumSounds () const noexcept
	Returns the number of sounds that have been added to the synth. More...

int	getNumVoices () const noexcept
	Returns the number of voices that have been added. More...

double	getSampleRate () const noexcept
	Returns the current target sample rate at which rendering is being done. More...

SynthesiserSound::Ptr	getSound (int index) const noexcept
	Returns one of the sounds. More...

SynthesiserVoice *	getVoice (int index) const
	Returns one of the voices that have been added. More...

virtual void	handleAftertouch (int midiChannel, int midiNoteNumber, int aftertouchValue)
	Sends an aftertouch message. More...

virtual void	handleChannelPressure (int midiChannel, int channelPressureValue)
	Sends a channel pressure message. More...

virtual void	handleController (int midiChannel, int controllerNumber, int controllerValue)
	Sends a midi controller message to any active voices. More...

virtual void	handlePitchWheel (int midiChannel, int wheelValue)
	Sends a pitch-wheel message to any active voices. More...

virtual void	handleProgramChange (int midiChannel, int programNumber)
	Can be overridden to handle an incoming program change message. More...

virtual void	handleSoftPedal (int midiChannel, bool isDown)
	Can be overridden to handle soft pedal events. More...

virtual void	handleSostenutoPedal (int midiChannel, bool isDown)
	Handles a sostenuto pedal event. More...

virtual void	handleSustainPedal (int midiChannel, bool isDown)
	Handles a sustain pedal event. More...

bool	isNoteStealingEnabled () const noexcept
	Returns true if note-stealing is enabled. More...

virtual void	noteOff (int midiChannel, int midiNoteNumber, float velocity, bool allowTailOff)
	Triggers a note-off event. More...

virtual void	noteOn (int midiChannel, int midiNoteNumber, float velocity)
	Triggers a note-on event. More...

void	removeSound (int index)
	Removes and deletes one of the sounds. More...

void	removeVoice (int index)
	Deletes one of the voices. More...

void	renderNextBlock (AudioBuffer< double > &outputAudio, const MidiBuffer &inputMidi, int startSample, int numSamples)

void	renderNextBlock (AudioBuffer< float > &outputAudio, const MidiBuffer &inputMidi, int startSample, int numSamples)
	Creates the next block of audio output. More...

virtual void	setCurrentPlaybackSampleRate (double sampleRate)
	Tells the synthesiser what the sample rate is for the audio it's being used to render. More...

void	setMinimumRenderingSubdivisionSize (int numSamples, bool shouldBeStrict=false) noexcept
	Sets a minimum limit on the size to which audio sub-blocks will be divided when rendering. More...

void	setNoteStealingEnabled (bool shouldStealNotes)
	If set to true, then the synth will try to take over an existing voice if it runs out and needs to play another note. More...

Protected Member Functions
virtual SynthesiserVoice *	findFreeVoice (SynthesiserSound *soundToPlay, int midiChannel, int midiNoteNumber, bool stealIfNoneAvailable) const
	Searches through the voices to find one that's not currently playing, and which can play the given sound. More...

virtual SynthesiserVoice *	findVoiceToSteal (SynthesiserSound *soundToPlay, int midiChannel, int midiNoteNumber) const
	Chooses a voice that is most suitable for being re-used. More...

virtual void	handleMidiEvent (const MidiMessage &)
	Can be overridden to do custom handling of incoming midi events. More...

virtual void	renderVoices (AudioBuffer< double > &outputAudio, int startSample, int numSamples)

virtual void	renderVoices (AudioBuffer< float > &outputAudio, int startSample, int numSamples)
	Renders the voices for the given range. More...

void	startVoice (SynthesiserVoice voice, SynthesiserSound sound, int midiChannel, int midiNoteNumber, float velocity)
	Starts a specified voice playing a particular sound. More...

void	stopVoice (SynthesiserVoice *, float velocity, bool allowTailOff)
	Stops a given voice. More...

Protected Attributes
int	lastPitchWheelValues [16]
	The last pitch-wheel values for each midi channel. More...

CriticalSection	lock
	This is used to control access to the rendering callback and the note trigger methods. More...

ReferenceCountedArray< SynthesiserSound >	sounds

OwnedArray< SynthesiserVoice >	voices

Private Member Functions
template<typename floatType >
void	processNextBlock (AudioBuffer< floatType > &, const MidiBuffer &, int startSample, int numSamples)

Private Attributes
uint32	lastNoteOnCounter = 0

int	minimumSubBlockSize = 32

double	sampleRate = 0

bool	shouldStealNotes = true

bool	subBlockSubdivisionIsStrict = false

BigInteger	sustainPedalsDown

Detailed Description

Base class for a musical device that can play sounds.

To create a synthesiser, you'll need to create a subclass of SynthesiserSound to describe each sound available to your synth, and a subclass of SynthesiserVoice which can play back one of these sounds.

Then you can use the addVoice() and addSound() methods to give the synthesiser a set of sounds, and a set of voices it can use to play them. If you only give it one voice it will be monophonic - the more voices it has, the more polyphony it'll have available.

Then repeatedly call the renderNextBlock() method to produce the audio. Any midi events that go in will be scanned for note on/off messages, and these are used to start and stop the voices playing the appropriate sounds.

While it's playing, you can also cause notes to be triggered by calling the noteOn(), noteOff() and other controller methods.

Before rendering, be sure to call the setCurrentPlaybackSampleRate() to tell it what the target playback rate is. This value is passed on to the voices so that they can pitch their output correctly.

@tags{Audio}

Constructor & Destructor Documentation

◆ Synthesiser()

juce::Synthesiser::Synthesiser ( )

Creates a new synthesiser.

You'll need to add some sounds and voices before it'll make any sound.

◆ ~Synthesiser()

virtual juce::Synthesiser::~Synthesiser ( )

virtual

Destructor.

Member Function Documentation

◆ addSound()

SynthesiserSound* juce::Synthesiser::addSound ( const SynthesiserSound::Ptr & newSound )

Adds a new sound to the synthesiser.

The object passed in is reference counted, so will be deleted when the synthesiser and all voices are no longer using it.

◆ addVoice()

SynthesiserVoice* juce::Synthesiser::addVoice ( SynthesiserVoice * newVoice )

Adds a new voice to the synth.

All the voices should be the same class of object and are treated equally.

The object passed in will be managed by the synthesiser, which will delete it later on when no longer needed. The caller should not retain a pointer to the voice.

◆ allNotesOff()

virtual void juce::Synthesiser::allNotesOff	(	int	midiChannel,
		bool	allowTailOff
	)

virtual

Turns off all notes.

This will turn off any voices that are playing a sound on the given midi channel.

If midiChannel is 0 or less, then all voices will be turned off, regardless of which channel they're playing. Otherwise it represents a valid midi channel, from 1 to 16 inclusive.

If allowTailOff is true, the voices will be allowed to fade out the notes gracefully (if they can do). If this is false, the notes will all be cut off immediately.

This method will be called automatically according to the midi data passed into renderNextBlock(), but may be called explicitly too.

◆ clearSounds()

void juce::Synthesiser::clearSounds ( )

Deletes all sounds.

◆ clearVoices()

void juce::Synthesiser::clearVoices ( )

Deletes all voices.

◆ findFreeVoice()

virtual SynthesiserVoice* juce::Synthesiser::findFreeVoice	(	SynthesiserSound *	soundToPlay,
		int	midiChannel,
		int	midiNoteNumber,
		bool	stealIfNoneAvailable
	)		const

protectedvirtual

Searches through the voices to find one that's not currently playing, and which can play the given sound.

Returns nullptr if all voices are busy and stealing isn't enabled.

To implement a custom note-stealing algorithm, you can either override this method, or (preferably) override findVoiceToSteal().

◆ findVoiceToSteal()

virtual SynthesiserVoice* juce::Synthesiser::findVoiceToSteal	(	SynthesiserSound *	soundToPlay,
		int	midiChannel,
		int	midiNoteNumber
	)		const

protectedvirtual

Chooses a voice that is most suitable for being re-used.

The default method will attempt to find the oldest voice that isn't the bottom or top note being played. If that's not suitable for your synth, you can override this method and do something more cunning instead.

◆ getNumSounds()

int juce::Synthesiser::getNumSounds ( ) const

inlinenoexcept

Returns the number of sounds that have been added to the synth.

◆ getNumVoices()

int juce::Synthesiser::getNumVoices ( ) const

inlinenoexcept

Returns the number of voices that have been added.

◆ getSampleRate()

double juce::Synthesiser::getSampleRate ( ) const

inlinenoexcept

Returns the current target sample rate at which rendering is being done.

Subclasses may need to know this so that they can pitch things correctly.

◆ getSound()

SynthesiserSound::Ptr juce::Synthesiser::getSound ( int index ) const

inlinenoexcept

Returns one of the sounds.

References juce::gl::index.

◆ getVoice()

SynthesiserVoice* juce::Synthesiser::getVoice ( int index ) const

Returns one of the voices that have been added.

◆ handleAftertouch()

virtual void juce::Synthesiser::handleAftertouch	(	int	midiChannel,
		int	midiNoteNumber,
		int	aftertouchValue
	)

virtual

Sends an aftertouch message.

This will send an aftertouch message to any voices that are playing sounds on the given midi channel and note number.

This method will be called automatically according to the midi data passed into renderNextBlock(), but may be called explicitly too.

Parameters

midiChannel	the midi channel, from 1 to 16 inclusive
midiNoteNumber	the midi note number, 0 to 127
aftertouchValue	the aftertouch value, between 0 and 127, as returned by MidiMessage::getAftertouchValue()

◆ handleChannelPressure()

virtual void juce::Synthesiser::handleChannelPressure	(	int	midiChannel,
		int	channelPressureValue
	)

virtual

Sends a channel pressure message.

This will send a channel pressure message to any voices that are playing sounds on the given midi channel.

This method will be called automatically according to the midi data passed into renderNextBlock(), but may be called explicitly too.

Parameters

midiChannel	the midi channel, from 1 to 16 inclusive
channelPressureValue	the pressure value, between 0 and 127, as returned by MidiMessage::getChannelPressureValue()

◆ handleController()

virtual void juce::Synthesiser::handleController	(	int	midiChannel,
		int	controllerNumber,
		int	controllerValue
	)

virtual

Sends a midi controller message to any active voices.

This will send a midi controller message to any voices that are playing sounds on the given midi channel.

This method will be called automatically according to the midi data passed into renderNextBlock(), but may be called explicitly too.

Parameters

midiChannel	the midi channel, from 1 to 16 inclusive
controllerNumber	the midi controller type, as returned by MidiMessage::getControllerNumber()
controllerValue	the midi controller value, between 0 and 127, as returned by MidiMessage::getControllerValue()

◆ handleMidiEvent()

virtual void juce::Synthesiser::handleMidiEvent ( const MidiMessage & )

protectedvirtual

Can be overridden to do custom handling of incoming midi events.

◆ handlePitchWheel()

virtual void juce::Synthesiser::handlePitchWheel	(	int	midiChannel,
		int	wheelValue
	)

virtual

Sends a pitch-wheel message to any active voices.

This will send a pitch-wheel message to any voices that are playing sounds on the given midi channel.

This method will be called automatically according to the midi data passed into renderNextBlock(), but may be called explicitly too.

Parameters

midiChannel	the midi channel, from 1 to 16 inclusive
wheelValue	the wheel position, from 0 to 0x3fff, as returned by MidiMessage::getPitchWheelValue()

◆ handleProgramChange()

virtual void juce::Synthesiser::handleProgramChange	(	int	midiChannel,
		int	programNumber
	)

virtual

Can be overridden to handle an incoming program change message.

The base class implementation of this has no effect, but you may want to make your own synth react to program changes.

◆ handleSoftPedal()

virtual void juce::Synthesiser::handleSoftPedal	(	int	midiChannel,
		bool	isDown
	)

virtual

Can be overridden to handle soft pedal events.

◆ handleSostenutoPedal()

virtual void juce::Synthesiser::handleSostenutoPedal	(	int	midiChannel,
		bool	isDown
	)

virtual

Handles a sostenuto pedal event.

◆ handleSustainPedal()

virtual void juce::Synthesiser::handleSustainPedal	(	int	midiChannel,
		bool	isDown
	)

virtual

Handles a sustain pedal event.

◆ isNoteStealingEnabled()

bool juce::Synthesiser::isNoteStealingEnabled ( ) const

inlinenoexcept

Returns true if note-stealing is enabled.

See also: setNoteStealingEnabled

◆ noteOff()

virtual void juce::Synthesiser::noteOff	(	int	midiChannel,
		int	midiNoteNumber,
		float	velocity,
		bool	allowTailOff
	)

virtual

Triggers a note-off event.

This will turn off any voices that are playing a sound for the given note/channel.

If allowTailOff is true, the voices will be allowed to fade out the notes gracefully (if they can do). If this is false, the notes will all be cut off immediately.

This method will be called automatically according to the midi data passed into renderNextBlock(), but may be called explicitly too.

The midiChannel parameter is the channel, between 1 and 16 inclusive.

◆ noteOn()

virtual void juce::Synthesiser::noteOn	(	int	midiChannel,
		int	midiNoteNumber,
		float	velocity
	)

virtual

Triggers a note-on event.

The default method here will find all the sounds that want to be triggered by this note/channel. For each sound, it'll try to find a free voice, and use the voice to start playing the sound.

Subclasses might want to override this if they need a more complex algorithm.

This method will be called automatically according to the midi data passed into renderNextBlock(), but may be called explicitly too.

The midiChannel parameter is the channel, between 1 and 16 inclusive.

◆ processNextBlock()

template<typename floatType >

void juce::Synthesiser::processNextBlock	(	AudioBuffer< floatType > &	,
		const MidiBuffer &	,
		int	startSample,
		int	numSamples
	)

private

◆ removeSound()

void juce::Synthesiser::removeSound ( int index )

Removes and deletes one of the sounds.

◆ removeVoice()

void juce::Synthesiser::removeVoice ( int index )

Deletes one of the voices.

◆ renderNextBlock() [1/2]

void juce::Synthesiser::renderNextBlock	(	AudioBuffer< double > &	outputAudio,
		const MidiBuffer &	inputMidi,
		int	startSample,
		int	numSamples
	)

◆ renderNextBlock() [2/2]

void juce::Synthesiser::renderNextBlock	(	AudioBuffer< float > &	outputAudio,
		const MidiBuffer &	inputMidi,
		int	startSample,
		int	numSamples
	)

Creates the next block of audio output.

This will process the next numSamples of data from all the voices, and add that output to the audio block supplied, starting from the offset specified. Note that the data will be added to the current contents of the buffer, so you should clear it before calling this method if necessary.

The midi events in the inputMidi buffer are parsed for note and controller events, and these are used to trigger the voices. Note that the startSample offset applies both to the audio output buffer and the midi input buffer, so any midi events with timestamps outside the specified region will be ignored.

◆ renderVoices() [1/2]

virtual void juce::Synthesiser::renderVoices	(	AudioBuffer< double > &	outputAudio,
		int	startSample,
		int	numSamples
	)

protectedvirtual

◆ renderVoices() [2/2]

virtual void juce::Synthesiser::renderVoices	(	AudioBuffer< float > &	outputAudio,
		int	startSample,
		int	numSamples
	)

protectedvirtual

Renders the voices for the given range.

By default this just calls renderNextBlock() on each voice, but you may need to override it to handle custom cases.

◆ setCurrentPlaybackSampleRate()

virtual void juce::Synthesiser::setCurrentPlaybackSampleRate ( double sampleRate )

virtual

Tells the synthesiser what the sample rate is for the audio it's being used to render.

This value is propagated to the voices so that they can use it to render the correct pitches.

◆ setMinimumRenderingSubdivisionSize()

void juce::Synthesiser::setMinimumRenderingSubdivisionSize	(	int	numSamples,
		bool	shouldBeStrict = `false`
	)

noexcept

Sets a minimum limit on the size to which audio sub-blocks will be divided when rendering.

When rendering, the audio blocks that are passed into renderNextBlock() will be split up into smaller blocks that lie between all the incoming midi messages, and it is these smaller sub-blocks that are rendered with multiple calls to renderVoices().

Obviously in a pathological case where there are midi messages on every sample, then renderVoices() could be called once per sample and lead to poor performance, so this setting allows you to set a lower limit on the block size.

The default setting is 32, which means that midi messages are accurate to about < 1ms accuracy, which is probably fine for most purposes, but you may want to increase or decrease this value for your synth.

If shouldBeStrict is true, the audio sub-blocks will strictly never be smaller than numSamples.

If shouldBeStrict is false (default), the first audio sub-block in the buffer is allowed to be smaller, to make sure that the first MIDI event in a buffer will always be sample-accurate (this can sometimes help to avoid quantisation or phasing issues).

◆ setNoteStealingEnabled()

void juce::Synthesiser::setNoteStealingEnabled ( bool shouldStealNotes )

If set to true, then the synth will try to take over an existing voice if it runs out and needs to play another note.

The value of this boolean is passed into findFreeVoice(), so the result will depend on the implementation of this method.

◆ startVoice()

void juce::Synthesiser::startVoice	(	SynthesiserVoice *	voice,
		SynthesiserSound *	sound,
		int	midiChannel,
		int	midiNoteNumber,
		float	velocity
	)

protected

Starts a specified voice playing a particular sound.

You'll probably never need to call this, it's used internally by noteOn(), but may be needed by subclasses for custom behaviours.

◆ stopVoice()

void juce::Synthesiser::stopVoice	(	SynthesiserVoice *	,
		float	velocity,
		bool	allowTailOff
	)

protected

Stops a given voice.

You should never need to call this, it's used internally by noteOff, but is protected in case it's useful for some custom subclasses. It basically just calls through to SynthesiserVoice::stopNote(), and has some assertions to sanity-check a few things.

Member Data Documentation

◆ lastNoteOnCounter

uint32 juce::Synthesiser::lastNoteOnCounter = 0

private

◆ lastPitchWheelValues

int juce::Synthesiser::lastPitchWheelValues[16]

protected

The last pitch-wheel values for each midi channel.

◆ lock

CriticalSection juce::Synthesiser::lock

protected

This is used to control access to the rendering callback and the note trigger methods.

◆ minimumSubBlockSize

int juce::Synthesiser::minimumSubBlockSize = 32

private

◆ sampleRate

double juce::Synthesiser::sampleRate = 0

private

◆ shouldStealNotes

bool juce::Synthesiser::shouldStealNotes = true

private

◆ sounds

ReferenceCountedArray<SynthesiserSound> juce::Synthesiser::sounds

protected

◆ subBlockSubdivisionIsStrict

bool juce::Synthesiser::subBlockSubdivisionIsStrict = false

private

◆ sustainPedalsDown

BigInteger juce::Synthesiser::sustainPedalsDown

private

◆ voices

OwnedArray<SynthesiserVoice> juce::Synthesiser::voices

protected

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

juce_Synthesiser.h

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Synthesiser()

◆ ~Synthesiser()

Member Function Documentation

◆ addSound()

◆ addVoice()

◆ allNotesOff()

◆ clearSounds()

◆ clearVoices()

◆ findFreeVoice()

◆ findVoiceToSteal()

◆ getNumSounds()

◆ getNumVoices()

◆ getSampleRate()

◆ getSound()

◆ getVoice()

◆ handleAftertouch()

◆ handleChannelPressure()

◆ handleController()

◆ handleMidiEvent()

◆ handlePitchWheel()

◆ handleProgramChange()

◆ handleSoftPedal()

◆ handleSostenutoPedal()

◆ handleSustainPedal()

◆ isNoteStealingEnabled()

◆ noteOff()

◆ noteOn()

◆ processNextBlock()

◆ removeSound()

◆ removeVoice()

◆ renderNextBlock() [1/2]

◆ renderNextBlock() [2/2]

◆ renderVoices() [1/2]

◆ renderVoices() [2/2]

◆ setCurrentPlaybackSampleRate()

◆ setMinimumRenderingSubdivisionSize()

◆ setNoteStealingEnabled()

◆ startVoice()

◆ stopVoice()

Member Data Documentation

◆ lastNoteOnCounter

◆ lastPitchWheelValues

◆ lock

◆ minimumSubBlockSize

◆ sampleRate

◆ shouldStealNotes

◆ sounds

◆ subBlockSubdivisionIsStrict

◆ sustainPedalsDown

◆ voices