API Reference

Synth management

synth_create

Creates a new synthesizer. See more details here.

SyntaxExample

gml

synth_create([polyphony], [channels], [format], [sample_rate])

gml

var _polyphony = 4;
var _channels = audio_stereo;
var _format = buffer_s16;
var _sample_rate = 44100;

// Create a synthesizer using all of the default values
synth = synth_create(_polyphony, _channels, _format, _sample_rate);

// The same result as above
synth = synth_create();

Argument	Type	Description	Default
[polyphony]	`Real`	How many notes can be played at once during live playback	`4`
[channels]	`Constant.AudioChannelType`	Sets the synth to be mono or stereo	`audio_stereo`
[format]	`Constant.BufferDataType`	The format audio data should be written as (`buffer_u8` or `buffer_s16`)	`buffer_s16`
[sample_rate]	`Real`	The sample rate to render audio at (8000 - 48000)	`44100`

Returns: Id.Instance<obj_synth_engine>

synth_create_preset SynthEnginePro

Creates a new synthesizer from a preset. See more details here.

SyntaxExample

gml

synth_create(preset, [polyphony], [channels], [format], [sample_rate])

gml

var _polyphony = 4;
var _channels = audio_stereo;
var _format = buffer_s16;
var _sample_rate = 44100;

synth = synth_create_preset(synth_preset_organ, _polyphony, _channels, _format, _sample_rate);

// The same result as above
synth = synth_create_preset(synth_preset_organ);

Argument	Type	Description	Default
preset	`Real`	One of the `synth_preset_*` constants
[polyphony]	`Real`	How many notes can be played at once during live playback (Some presets will override this)	`4`
[channels]	`Constant.AudioChannelType`	Sets the synth to be mono or stereo	`audio_stereo`
[format]	`Constant.BufferDataType`	The format audio data should be written as (`buffer_u8` or `buffer_s16`)	`buffer_s16`
[sample_rate]	`Real`	The sample rate to render audio at (8000 - 48000)	`44100`

Returns: Id.Instance<obj_synth_engine>

synth_destroy

Destroy a previously created synth.

SyntaxExample

gml

synth_destroy(synth)

gml

synth = synth_create();

// Some time later...
synth_destroy(synth);

Argument	Type	Description
synth	`Id.Instance`	A reference to the synth you want to destroy, previously created with `synth_create()` or `synth_create_preset()`

synth_amp_envelope_adsr

Set the amp envelope of the synth to a standard ADSR shape. See more details here.

SyntaxExample

gml

synth_amp_envelope_adsr(synth, attack, decay, sustain, release)

gml

synth = synth_create();
synth_amp_envelope_adsr(synth, 0.1, 0, 1, 0.1);

Argument	Type	Description
synth	`Id.Instance`	A reference to the synth you want to apply the envelope to, previously created with `synth_create()` or `synth_create_preset()`
attack	`Real`	How long a note takes to "fade in" to full volume
decay	`Real`	How long it takes to go from full volume after the attack to the sustain level
sustain	`Real`	How loud the volume should be when a note is held after the attack and decay
release	`Real`	How long the note takes to fade out

synth_set_panning

Change the stereo panning of a synth. This has no effect for mono channel synths.

SyntaxExample

gml

synth_set_panning(synth, [panning])

gml

synth = synth_create();
synth_set_panning(synth, 0.5);

Argument	Type	Description	Default
synth	`Id.Instance`	A reference to the synth you want to destroy, previously created with `synth_create()` or `synth_create_preset()`
panning	`Real`	Left/right panning between -1 and 1, where -1 is all the way left and 1 is all the way right.	`0`

Generators

synth_add_osc

Add an oscillator preset to the synth. See more details here.

SyntaxExample

gml

synth_add_osc(synth, waveform, [semitone_offset], [amp_factor])

gml

synth = synth_create();
sine_osc = synth_add_osc(synth, synth_waveform_sine);
saw_osc = synth_add_osc(synth, synth_waveform_saw, 12, 0.5);

Argument	Type	Description	Default
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
waveform	`Real`	One of the `synth_waveform_*` constants
[semitone_offset]	`Real`	What note the oscillator should play in terms of musical semitones away from the actual played note	`0`
[amp_factor]	`Real`	How loud this oscillator should be (between 0 and 1, 1 being full volume)	`1`

Returns: Real

synth_add_osc_ext

dd an oscillator to a synth using an animation curve as the waveform shape. See more details here.

SyntaxExample

gml

synth_add_osc(synth, animation_curve, curve_name, [semitone_offset], [amp_factor])

gml

synth = synth_create();

var _animation_curve_asset = ac_synth_waves_smooth;
var _curve_name = "Sine";

synth_add_osc_ext(synth, _animation_curve_asset, _curve_name);

Argument	Type	Description	Default
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
animation_curve	`Asset.GMAnimCurve \| Struct.AnimCurve`	The animation curve asset that holds the curve you want to use
curve_name	`String \| Real`	The name (or index) of the curve you want to use as your waveform
[semitone_offset]	`Real`	What note the oscillator should play in terms of musical semitones away from the actual played note	`0`
[amp_factor]	`Real`	How loud the oscillator should be (between 0 and 1, with 1 being full volume)	`1`

Returns: Real

synth_add_noise SynthEnginePro

Add a noise generator to a synth. See more details here.

SyntaxExample

gml

synth_add_noise(synth, [type], [amp_factor])

gml

synth = synth_create();
synth_add_noise(synth, synth_noise_white, 0.5);

Argument	Type	Description	Default
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
[type]	`Real`	The type of noise to use, one of the `synth_noise_*` constants	`synth_noise_white`
[amp_factor]	`Real`	How loud the generator should be (between 0 and 1, with 1 being full volume)	`1`

Returns: Real

synth_add_processor SynthEnginePro

Add a processor generator to a synth. This is an advanced feature. See more details here.

SyntaxExample

gml

synth_add_processor(synth, callback)

gml

synth = synth_create();

// Pure sine wave generator
synth_add_processor(synth, function(note, amp, data) {
    var _output = 0;

    // Calculate the full cycle of a wave using synth rate and note frequency
    var _period = data.sample_rate / note.frequency;

    // Calculate the current position in the wave
    var _position = note.i % _period;

    // Calculate the output using the sine function
    _output = sin(_position * 2 * pi / _period);

    // Multiply the output by the amp value so it's the right volume
    return _output * amp;
});

Argument	Type	Description
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
callback	`Function`	Function that gets passed `note`, `amplitude`, and `synth data`. Should return a real between -1 and 1.

Returns: Real

synth_remove_generator

Remove a previously made oscillator, noise generator, or processor.

SyntaxExample

gml

synth_remove_generator(synth, generator)

gml

synth = synth_create();

// Add a sine oscillator
sine_osc = synth_add_osc(synth, synth_waveform_sine);

// Later on, remove it
synth_remove_generator(synth, sine_osc);

Argument	Type	Description
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
generator	`Real`	Generator reference, as returned by `synth_add_osc`, `synth_add_noise`, `synth_add_processor`, etc.

Playback

More details about playback related functions can be found here.

synth_note_on

Begin playing a note on a synthesizer. Akin to pressing down a key on a keyboard.

SyntaxExample

gml

synth_note_on(synth, [frequency], [amplitude])

gml

var _C4 = 261.63;
var _E4 = 329.63;
var _G4 = 392.00;

// Play a C major chord
synth_note_on(synth, _C4);
synth_note_on(synth, _E4);
synth_note_on(synth, _G4);

Argument	Type	Description	Default
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
[frequency]	`Real`	The note frequency (hz) that you want to play	`440`
[amplitude]	`Real`	How loud this note should be played (velocity)	`1`

Returns: Real

synth_note_on_ext

Play a note on a synthesizer for a set length of time. Akin to pressing down a key on a keyboard and holding for a set length of time.

Notes played with this function can not be stopped early with synth_note_off().

SyntaxExample

gml

synth_note_on_ext(synth, length, [frequency], [amplitude])

gml

var _C4 = 261.63;
var _E4 = 329.63;
var _G4 = 392.00;
var _length = 1;

// Play a C major chord for exactly 1 second
synth_note_on_ext(synth, _length, _C4);
synth_note_on_ext(synth, _length, _E4);
synth_note_on_ext(synth, _length, _G4);

Argument	Type	Description	Default
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
length	`Real`	How long you want to play the note for, in seconds
[frequency]	`Real`	The note frequency (hz) that you want to play	`440`
[amplitude]	`Real`	How loud this note should be played (velocity)	`1`

synth_note_off

Stop playing a previously played note (and trigger its amp envelope release). Akin to releasing a previously pressed key on a keyboard.

SyntaxExample

gml

synth_note_off(synth, note_index)

gml

note_index = synth_note_on(synth, 440);

// Somewhere else in your project
synth_note_off(synth, note_index);

Argument	Type	Description
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
note_index	`Real`	Note reference, as returned by `synth_note_on`

synth_render_audio

Renders synthesizer audio of a single note into a buffer and sound asset. This function returns a struct that can be used to play and manage the generated audio. See below for return details.

SyntaxExample

gml

synth_render_audio(synth, length, [frequency], [amplitude])

gml

// Render an A4 note played for 1 second
var _synth_a4 = synth_render_audio(synth, 1, 440);

// Play the audio
audio_play_sound(_synth_a4.sound, 1, false);

// Clean it up some time later when we no longer need it
_synth_a4.cleanup();

Argument	Type	Description	Default
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
length	`Real`	How long you want to play the note for, in seconds
[frequency]	`Real`	The note frequency (hz) that you want to play	`440`
[amplitude]	`Real`	How loud this note should be played (velocity)	`1`

Returns: Struct

The returned struct has three keys, sound, cleanup, and buffer. The sound key holds a reference to the generated sound index that you can use to play your audio, and cleanup is a function you can call to free the memory associated with your sound when you no longer need it.

The buffer key is the buffer contining the generated sound data, but be careful not to delete this buffer manually. It is tied to the internal audio buffer created for your sound, and should only be removed using the cleanup function.

synth_render_buffer

Renders synthesizer audio of a single note into a buffer. This function is used internally when rendering audio, and should only be used if you only need to access the audio data, like if you wanted to write the audio data to a file (which could be done with my free extension, WaveWrite).

SyntaxExample

gml

synth_render_buffer(synth, length, [frequency], [amplitude])

gml

// Render an A4 note played for 1 second
var _buffer = synth_render_buffer(synth, 1, 440);

Argument	Type	Description	Default
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
length	`Real`	How long you want to play the note for, in seconds
[frequency]	`Real`	The note frequency (hz) that you want to play	`440`
[amplitude]	`Real`	How loud this note should be played (velocity)	`1`

Returns: Id.Buffer

synth_play_audio

Renders synthesizer audio of a single note and immediately plays it, cleaning up memory once playback finishes.

This function should mostly be used for testing purposes only, as rendering a note every time you want to play it will have unnecessary performance costs. The ideal use case for using this function is if you are testing out different synth configurations, and want to hear audio immediately just one time. For rendering audio and playing it back multiple times, you should use synth_render_audio() instead.

SyntaxExample

gml

synth_play_audio(synth, length, [frequency], [amplitude], [cleanup_offset])

gml

// Render and play an A4 note for 1 second
synth_play_audio(synth, 1, 440);

Argument	Type	Description	Default
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
length	`Real`	How long you want to play the note for, in seconds
[frequency]	`Real`	The note frequency (hz) that you want to play	`440`
[amplitude]	`Real`	How loud this note should be played (velocity)	`1`
[cleanup_offset]	`Real`	How long in seconds to wait before cleaning up the audio	`1`

LFOs

More details about LFO related functions can be found in this section.

synth_add_lfo

Adds an LFO to a synth that can be connected to other parameters.

SyntaxExample

gml

synth_add_lfo(synth, waveform, [frequency], [amount], [note_trigger])

gml

synth = synth_create();
var _LFO = synth_add_lfo(synth, synth_waveform_sine, 10, 1);

Argument	Type	Description	Default
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
waveform	`Real`	One of the `synth_waveform_*` constants
[frequency]	`Real`	The frequency (hz) of the LFO wave	`5`
[amount]	`Real`	How strongly to affect connections, usually between 0 and 1. For pitch, a value of 1 is +/-12 semitones. For panning, a value of 1 is full left and right panning. For amp envelopes, a value of 1 is full volume to quiet, and 0 is no modulation.	`0.5`
[note_trigger]	`Bool`	When true, will reset the LFO phase whenever a note is pressed (and no other notes are pressed)	`false`

Returns: Real

synth_add_lfo_ext

Adds an LFO to a synth using an animation curve as the waveform shape that can be connected to other parameters.

SyntaxExample

gml

synth_add_lfo_ext(synth, animation_curve, curve_name, [frequency], [amount], [note_trigger])

gml

synth = synth_create();
var _LFO = synth_add_lfo(synth, ac_synth_waves_smooth, "Sine", 10, 1);

Argument	Type	Description	Default
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
animation_curve	`Asset.GMAnimCurve \| Struct.AnimCurve`	The animation curve asset that holds the curve you want to use
curve_name	`String \| Real`	The name (or index) of the curve you want to use as your waveform
[frequency]	`Real`	The frequency (hz) of the LFO wave	`5`
[amount]	`Real`	How strongly to affect connections, usually between 0 and 1. For pitch, a value of 1 is +/-12 semitones. For panning, a value of 1 is full left and right panning. For amp envelopes, a value of 1 is full volume to quiet, and 0 is no modulation.	`0.5`
[note_trigger]	`Bool`	When true, will reset the LFO phase whenever a note is pressed (and no other notes are pressed)	`false`

Returns: Real

synth_connect_lfo_amp

Connect an LFO to synth amp. This will replace any existing ADSR envelope.

SyntaxExample

gml

synth_connect_lfo_amp(synth, lfo, [release])

gml

synth = synth_create();

var _LFO = synth_add_lfo(synth, synth_waveform_sine, 10, 1);
synth_connect_lfo_amp(synth, _LFO);

Argument	Type	Description	Default
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
lfo	`Real`	LFO reference, as returned by `synth_add_lfo()` or `synth_add_lfo_ext()`
[release]	`Real`	How long a note should take to fade out	`0.1`

synth_connect_lfo_panning

Connect an LFO to synth panning.

SyntaxExample

gml

synth_connect_lfo_panning(synth, lfo)

gml

synth = synth_create();

var _LFO = synth_add_lfo(synth, synth_waveform_sine, 10, 1);
synth_connect_lfo_panning(synth, _LFO);

Argument	Type	Description
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
lfo	`Real`	LFO reference, as returned by `synth_add_lfo()` or `synth_add_lfo_ext()`

synth_connect_lfo_pitch SynthEnginePro

Connect an LFO to note pitch. See more details here.

SyntaxExample

gml

synth_connect_lfo_pitch(synth, lfo, [osc])

gml

synth = synth_create();

var _LFO = synth_add_lfo(synth, synth_waveform_sine, 10, 1);
synth_connect_lfo_pitch(synth, _LFO);

Argument	Type	Description	Default
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
lfo	`Real`	LFO reference, as returned by `synth_add_lfo()` or `synth_add_lfo_ext()`
[osc]	`Real`	Oscillator index to attach the LFO to, or -1 to affect all oscillators (note that only one LFO can be attached to an oscillator at a time)	`-1`

synth_disconnect_lfo_panning

Disconnects any LFO to a synths panning.

SyntaxExample

gml

synth_disconnect_lfo_panning(synth)

gml

// If there was an attached LFO to the synth's panning, this will remove it
synth_disconnect_lfo_panning(synth);

Argument	Type	Description
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`

synth_disconnect_lfo_pitch SynthEnginePro

Disconnects any LFO from an oscillators pitch

SyntaxExample

gml

synth_disconnect_lfo_pitch(synth, [osc])

gml

// If there are any LFOs attached to any oscillators, this will remove all of them
synth_disconnect_lfo_pitch(synth);

Argument	Type	Description	Default
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
[osc]	`Real`	Oscillator index to remove the LFO from, or -1 to affect all oscillators	`-1`

synth_remove_lfo

Remove a previously made LFO from a synth.

SyntaxExample

gml

synth_remove_lfo(synth, lfo)

gml

synth = synth_create();
var _LFO = synth_add_lfo(synth, synth_waveform_sine, 10, 1);

// Some time later...
synth_remove_lfo(synth, _LFO);

Argument	Type	Description
synth	`Id.Instance`	Synth reference, previously created with `synth_create()` or `synth_create_preset()`
lfo	`Real`	LFO reference, as returned by `synth_add_lfo()` or `synth_add_lfo_ext()`

Misc

synth_get_waveform_preset

Get the animation curve info for a given synth waveform preset. Used internally.

gml

synth_get_waveform_preset(waveform)

Argument	Type	Description
waveform	`Real`	One of the `synth_waveform_*` constants

Returns: Struct

Constants

Waveforms

gml

synth_waveform_sine
synth_waveform_saw
synth_waveform_square
synth_waveform_triangle

SynthEnginePro

gml

synth_waveform_soft_square
synth_waveform_pwm_10
synth_waveform_pwm_20
synth_waveform_pwm_25
synth_waveform_pwm_30
synth_waveform_pwm_40
synth_waveform_organ_1
synth_waveform_organ_2
synth_waveform_flute
synth_waveform_noisy_sine
synth_waveform_messy_square
synth_waveform_hi
synth_waveform_mosquito
synth_waveform_arches
synth_waveform_sqwine
synth_waveform_tiny_saw

Noise types

gml

synth_noise_white
synth_noise_brown
synth_noise_pink

Synth presets SynthEnginePro

gml

synth_preset_square
synth_preset_sine
synth_preset_triangle
synth_preset_saw
synth_preset_hell_alarm
synth_preset_noise_shot
synth_preset_lasers
synth_preset_strange_sitar
synth_preset_woodwind
synth_preset_organ
synth_preset_pwm_sweeper
synth_preset_clean_bass
synth_preset_tiny_stabs
synth_preset_sine_dream_pad
synth_preset_wide_energy
synth_preset_e_piano
synth_preset_70s_synth
synth_preset_move_your_mouse
synth_preset_telephone
synth_preset_arp

Max audio buffers

More info about max audio buffers can be found here.

gml

synth_max_audio_buffers

API Reference ​

Table of contents ​

Synth management ​

synth_create ​

synth_create_preset SynthEnginePro ​

synth_destroy ​

synth_amp_envelope_adsr ​

synth_set_panning ​

Generators ​

synth_add_osc ​

synth_add_osc_ext ​

synth_add_noise SynthEnginePro ​

synth_add_processor SynthEnginePro ​

synth_remove_generator ​

Playback ​

synth_note_on ​

synth_note_on_ext ​

synth_note_off ​

synth_render_audio ​

synth_render_buffer ​

synth_play_audio ​

LFOs ​

synth_add_lfo ​

synth_add_lfo_ext ​

synth_connect_lfo_amp ​

synth_connect_lfo_panning ​

synth_connect_lfo_pitch SynthEnginePro ​

synth_disconnect_lfo_panning ​

synth_disconnect_lfo_pitch SynthEnginePro ​

synth_remove_lfo ​

Misc ​

synth_get_waveform_preset ​

Constants ​

Waveforms ​

Noise types ​

Synth presets SynthEnginePro ​

Max audio buffers ​

API Reference

Table of contents

Synth management

synth_create

synth_create_preset SynthEnginePro

synth_destroy

synth_amp_envelope_adsr

synth_set_panning

Generators

synth_add_osc

synth_add_osc_ext

synth_add_noise SynthEnginePro

synth_add_processor SynthEnginePro

synth_remove_generator

Playback

synth_note_on

synth_note_on_ext

synth_note_off

synth_render_audio

synth_render_buffer

synth_play_audio

LFOs

synth_add_lfo

synth_add_lfo_ext

synth_connect_lfo_amp

synth_connect_lfo_panning

synth_connect_lfo_pitch SynthEnginePro

synth_disconnect_lfo_panning

synth_disconnect_lfo_pitch SynthEnginePro

synth_remove_lfo

Misc

synth_get_waveform_preset

Constants

Waveforms

Noise types

Synth presets SynthEnginePro

Max audio buffers