JUCE
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
Synthesiser Class Reference

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

Public Member Functions

 Synthesiser ()
 Creates a new synthesiser.
 
virtual ~Synthesiser ()
 Destructor.
 
void clearVoices ()
 Deletes all voices.
 
int getNumVoices () const noexcept
 Returns the number of voices that have been added.
 
SynthesiserVoicegetVoice (int index) const
 Returns one of the voices that have been added.
 
SynthesiserVoiceaddVoice (SynthesiserVoice *newVoice)
 Adds a new voice to the synth.
 
void removeVoice (int index)
 Deletes one of the voices.
 
void clearSounds ()
 Deletes all sounds.
 
int getNumSounds () const noexcept
 Returns the number of sounds that have been added to the synth.
 
SynthesiserSoundgetSound (int index) const noexcept
 Returns one of the sounds.
 
SynthesiserSoundaddSound (const SynthesiserSound::Ptr &newSound)
 Adds a new sound to the synthesiser.
 
void removeSound (int index)
 Removes and deletes one of the sounds.
 
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.
 
bool isNoteStealingEnabled () const noexcept
 Returns true if note-stealing is enabled.
 
virtual void noteOn (int midiChannel, int midiNoteNumber, float velocity)
 Triggers a note-on event.
 
virtual void noteOff (int midiChannel, int midiNoteNumber, bool allowTailOff)
 Triggers a note-off event.
 
virtual void allNotesOff (int midiChannel, bool allowTailOff)
 Turns off all notes.
 
virtual void handlePitchWheel (int midiChannel, int wheelValue)
 Sends a pitch-wheel message to any active voices.
 
virtual void handleController (int midiChannel, int controllerNumber, int controllerValue)
 Sends a midi controller message to any active voices.
 
virtual void handleAftertouch (int midiChannel, int midiNoteNumber, int aftertouchValue)
 Sends an aftertouch message.
 
virtual void handleSustainPedal (int midiChannel, bool isDown)
 Handles a sustain pedal event.
 
virtual void handleSostenutoPedal (int midiChannel, bool isDown)
 Handles a sostenuto pedal event.
 
virtual void handleSoftPedal (int midiChannel, bool isDown)
 Can be overridden to handle soft pedal events.
 
virtual void setCurrentPlaybackSampleRate (double sampleRate)
 Tells the synthesiser what the sample rate is for the audio it's being used to render.
 
void renderNextBlock (AudioSampleBuffer &outputAudio, const MidiBuffer &inputMidi, int startSample, int numSamples)
 Creates the next block of audio output.
 

Protected Member Functions

virtual SynthesiserVoicefindFreeVoice (SynthesiserSound *soundToPlay, const bool stealIfNoneAvailable) const
 Searches through the voices to find one that's not currently playing, and which can play the given sound.
 
virtual SynthesiserVoicefindVoiceToSteal (SynthesiserSound *soundToPlay) const
 Chooses a voice that is most suitable for being re-used.
 
void startVoice (SynthesiserVoice *voice, SynthesiserSound *sound, int midiChannel, int midiNoteNumber, float velocity)
 Starts a specified voice playing a particular sound.
 
virtual void handleMidiEvent (const MidiMessage &)
 Can be overridden to do custom handling of incoming midi events.
 

Protected Attributes

CriticalSection lock
 This is used to control access to the rendering callback and the note trigger methods.
 
OwnedArray< SynthesiserVoicevoices
 
ReferenceCountedArray
< SynthesiserSound
sounds
 
int lastPitchWheelValues [16]
 The last pitch-wheel values for each midi channel.
 

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.

Constructor & Destructor Documentation

Synthesiser::Synthesiser ( )

Creates a new synthesiser.

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

virtual Synthesiser::~Synthesiser ( )
virtual

Destructor.

Member Function Documentation

void Synthesiser::clearVoices ( )

Deletes all voices.

int Synthesiser::getNumVoices ( ) const
noexcept

Returns the number of voices that have been added.

SynthesiserVoice* Synthesiser::getVoice ( int  index) const

Returns one of the voices that have been added.

SynthesiserVoice* 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.

void Synthesiser::removeVoice ( int  index)

Deletes one of the voices.

void Synthesiser::clearSounds ( )

Deletes all sounds.

int Synthesiser::getNumSounds ( ) const
noexcept

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

SynthesiserSound* Synthesiser::getSound ( int  index) const
noexcept

Returns one of the sounds.

SynthesiserSound* 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.

void Synthesiser::removeSound ( int  index)

Removes and deletes one of the sounds.

void 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.

bool Synthesiser::isNoteStealingEnabled ( ) const
noexcept

Returns true if note-stealing is enabled.

See Also
setNoteStealingEnabled
virtual void 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.

virtual void Synthesiser::noteOff ( int  midiChannel,
int  midiNoteNumber,
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.

virtual void 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.

virtual void 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
midiChannelthe midi channel, from 1 to 16 inclusive
wheelValuethe wheel position, from 0 to 0x3fff, as returned by MidiMessage::getPitchWheelValue()
virtual void 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
midiChannelthe midi channel, from 1 to 16 inclusive
controllerNumberthe midi controller type, as returned by MidiMessage::getControllerNumber()
controllerValuethe midi controller value, between 0 and 127, as returned by MidiMessage::getControllerValue()
virtual void 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
midiChannelthe midi channel, from 1 to 16 inclusive
midiNoteNumberthe midi note number, 0 to 127
aftertouchValuethe aftertouch value, between 0 and 127, as returned by MidiMessage::getAftertouchValue()
virtual void Synthesiser::handleSustainPedal ( int  midiChannel,
bool  isDown 
)
virtual

Handles a sustain pedal event.

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

Handles a sostenuto pedal event.

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

Can be overridden to handle soft pedal events.

virtual void 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.

void Synthesiser::renderNextBlock ( AudioSampleBuffer 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.

virtual SynthesiserVoice* Synthesiser::findFreeVoice ( SynthesiserSound soundToPlay,
const 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.

This can be overridden to implement custom voice-stealing algorithms.

virtual SynthesiserVoice* Synthesiser::findVoiceToSteal ( SynthesiserSound soundToPlay) const
protectedvirtual

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

The default method returns the one that has been playing for the longest, but you may want to override this and do something more cunning instead.

void 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.

virtual void Synthesiser::handleMidiEvent ( const MidiMessage )
protectedvirtual

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

Member Data Documentation

CriticalSection Synthesiser::lock
protected

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

OwnedArray<SynthesiserVoice> Synthesiser::voices
protected
ReferenceCountedArray<SynthesiserSound> Synthesiser::sounds
protected
int Synthesiser::lastPitchWheelValues[16]
protected

The last pitch-wheel values for each midi channel.


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