Playing notes

Once your synth has some oscillators attached, you can begin making notes. This can be done in two ways: By triggering notes live, and by rendering audio.

Playing live

SynthEngine uses an audio queue under the hood that is constantly playing and being processed. This method allows audio buffers to be filled in almost real time, which means notes can be played and heard immediately.

var _frequency = 440;

// Amp is 1 by default, and is optional
var _amp = 1;

note_index = synth_note_on(synth, _frequency, _amp);

The above code will trigger a note at 440hz, which is A4 on a musical keyboard. Sound will play immediately, and won't stop until you tell it to some time later:

synth_note_off(synth, note_index);

This is the same result as pushing down (synth_note_on()) the A4 key on a musical keyboard, and then lifting (synth_note_off()) that key later on.

When playing notes, the amplitude argument can also be seen as velocity, in that it will play that specific note quieter.

INFO

If you are trying to play a note when the max polyphony has been reached for your synth, then no note will play.

Note timing

It is also possible to play a note for a specific amount of time without having to manually call synth_note_off():

var _frequency = 440;
var _length = 1; // in seconds

synth_note_on_ext(synth, _length, _frequency);

It is also important to know that when a note stops being played (or when you call synth_note_off()) it does not mean that sound will stop immediately. That is when the programmatic "key" is lifted, and so your amp envelope's release will start at that point, similar to a traditional synthesizer.

Audio queue size

Internally, an audio queue is used to play audio live. This means that SynthEngine is constantly rotating through a queue of buffers as it renders audio. The amount of buffers that are used can impact performance, audio stability, and audio delay. This number is controlled by the synth_max_audio_buffers macro, and is 4 by default. If you find that your audio is stuttering you can increase this number, but doing so will increase the delay between triggering a note and hearing audio.

Rendering notes

SynthEngine supports rendering audio into a buffer and sound asset. This comes with a one-time up front performance cost, but will then be essentially "free" to play that sound any time after with no additional cost to performance. This can be helpful for things like sound effects.

var _length = 1;
var _frequency = 440;
var _amp = 1; // Default value, optional

var _synth_a4 = synth_render_audio(synth, _length, _frequency, _amp);

The above code will render your synthesizer playing an A4 note for 1 second, and record the data into a buffer and sound asset that you can use for playback:

audio_play_sound(_synth_a4.sound, 1, false);

If you no longer need to use the sound, you can free up memory by calling its cleanup method:

_synth_a4.cleanup();

This will free the audio buffer sound and the delete the buffer associated with the sound.

TIP

To make it easier to work with musical frequencies (and not have to manually look up which frequencies to use) check out my free library MusicTheoryLib. Instead of writing 440, you can use mt_note_frequency("A4") instead. This library is included in the SynthEngine demo.