SpessaSynthProcessor¶

The core synthesis engine of SpessaSynth. This module converts sound bank and MIDI data into PCM audio data. The internal synthesis system is modeled after SoundFont2 synthesis model.

Initialization¶

1

const synth = new SpessaSynthProcessor(sampleRate, options);

• sampleRate - number - sample rate in Hertz, for example 44,100Hz.
• options - optional configuration, explained below:

Synth processor options¶

• maxBufferSize - number - The maximum buffer size the synthesizer can render at once. Attempting to .process() more samples than this will result in an error. Defaults to 128.
• enable event system - boolean - Indicates if the event system is enabled. This can be changed later.
• initialTime - number - The initial time of the synth, in seconds.
• enableEffects - boolean - Indicates if the effects are enabled. This can be changed later.
• reverbProcessor - ReverbProcessor - Reverb processor for the synthesizer. Leave undefined to use the default.
• chorusProcessor - ChorusProcessor - Chorus processor for the synthesizer. Leave undefined to use the default.
• delayProcessor - DelayProcessor - Delay processor for the synthesizer. Leave undefined to use the default.

All properties are optional. If they are not supplied, the defaults will be used.

Effects¶

• Reverb - How to implement your own reverb processor.
• Chorus - How to implement your own chorus processor.
• Delay - How to implement your own delay processor.

Managers¶

• Key Modifier Manager
• Sound Bank Manager

Methods¶

process¶

Render PCM float32 audio data to the stereo outputs and processes the effects if they are enabled.

1

synth.process(left, right, (startIndex = 0), (sampleCount = all));

• left - a Float32Array - the left audio output buffer.
• right - a Float32Array - the right audio output buffer.
• startIndex - optional, number - the offset at which to start rendering audio in the provided arrays. Default is 0.
• sampleCount - optional, number - the number of samples to render. Default is the entire length, starting from startIndex.

All Float32Arrays must be the same length

processSplit¶

Render PCM float32 audio data of separate channels + effects.

1
2
3
4
5
6
7

synth.processSplit(
    outputs,
    effectsLeft,
    effectsRight,
    (startIndex = 0),
    (sampleCount = all)
);

• separateChannels - an array of Float32Array pairs - one pair represents one channel ([L, R]), for example, the first pair is first channels L and R outputs and so on. If there are fewer arrays than the channels, the extra channels will render into the same arrays.
• effectsLeft - a Float32Array- the left output buffer for effects.
• effectsRight - a Float32Array - the right output buffer for effects.
• startIndex - optional, number - the offset at which to start rendering audio in the provided arrays. Default is 0.
• sampleCount - optional, number - the number of samples to render. Default is the entire length, starting from startIndex.

All Float32Arrays must be the same length

systemExclusive¶

Handle a MIDI System Exclusive message.

1

synth.systemExclusive(messageData, (channelOffset = 0));

• messageData - Uint8Array, the message byte data Excluding the 0xF0 byte!
• channelOffset - number, the channel offset for the message as they usually can only address the first 16 channels. For example, to send a system exclusive on channel 16, send a system exclusive for channel 0 and specify the channel offset to be 16.

controllerChange¶

Set a given MIDI controller to a given value.

1

synth.controllerChange(channel, controller, value);

• channel - the MIDI channel to use. It usually ranges from 0 to 15, but it depends on the channel count.
• controller - the MIDI CC number of the controller to change. Refer to this table for the list of controllers supported by default.
• value - the value to set the given controller to. Ranges from 0 to 127.

noteOn¶

Executes a MIDI Note On message on the specified channel. Starts playing a note.

1

synth.noteOn(channel, midiNote, velocity);

• channel - the MIDI channel to use. It usually ranges from 0 to 15, but it depends on the channel count.
• midiNote - the note to play. Ranges from 0 to 127.
• velocity - controls how loud the note is. Ranges from 0 to 127, where 127 is the loudest and 1 is the quietest.

noteOff¶

Executes a MIDI Note Off message on the specified channel. Stops playing a note.

1

synth.noteOff(channel, midiNote);

• channel - the MIDI channel to use. It Usually ranges from 0 to 15, but it depends on the channel count.
• midiNote - the note to play. Ranges from 0 to 127.

polyPressure¶

Executes a MIDI Poly Pressure (Aftertouch) message on the specified channel. This differs from the Channel Pressure in that it's per-note and not for the whole channel.

1

synth.polyPressure(channel, midiNote, pressure);

• channel - the channel to use. It usually ranges from 0 to 15, but it depends on the channel count.
• midiNote - the note to apply pressure to. Ranges from 0 to 127.
• pressure - the pressure to apply. Ranges from 0 to 127.

channelPressure¶

Executes a MIDI Channel Pressure (Aftertouch) message on the specified channel.

1

synth.channelPressure(channel, pressure);

• channel - the channel to use. It usually ranges from 0 to 15, but it depends on the channel count.
• pressure - the pressure to apply. Ranges from 0 to 127.

pitchWheel¶

Executes a MIDI Pitch Wheel message on the specified channel.

1

synth.pitchWheel(channel, pitch, (midiNote = -1));

• channel - the MIDI channel to use. It usually ranges from 0 to 15, but it depends on the channel count.
• pitch - the 14-bit MIDI pitch value to use (0 - 16,383)
• midiNote, optional - allows to set per-note pitch wheel, which will activate the per-note pitch mode. Leave unset or set to -1 for a regular pitch wheel.

programChange¶

Executes a MIDI Program Change message on the specified channel.

1

synth.programChange(channel, programNumber);

• channel - the MIDI channel to change. It usually ranges from 0 to 15, but it depends on the channel count.
• programNumber - the MIDI program number to use. Ranges from 0 to 127. To use other banks, go to controllerChange.

processMessage¶

Processes a raw MIDI message and allows scheduling it at a specific time.

1

synth.processMessage(message, (channnelOffset = 0), (options = null));

• message - number or any byte Typed Array (like Uint8Array) - the MIDI message to process.
• channelOffset - number, optional - adds to the channel number of the message. It defaults to 0.
• eventOptions - an object, currently defined properties are:
  • time - number - time in seconds for when the message is executed. This allows message scheduling. Absolute time in synth's current time. A value less than the current time causes the message to get executed immediately.

lockMIDIParameter¶

Locks or unlocks a given Global MIDI Parameter. This prevents any changes to it until it's unlocked.

1

synth.lockMIDIParameter(parameter, isLocked);

• parameter - the Global MIDI Parameter to lock, a string of the parameter type.
• isLocked - if the parameter should be locked, boolean.

setSystemParameter¶

Set a Global System Parameter.

1

synth.setSystemParameter(parameter, value);

• parameter - the type of the parameter to set, a string of the parameter type.
• value - the value of the parameter to set, depends on the type.

reset¶

Executes a full system reset of all controllers. This will reset all controllers to their default values, except for the locked controllers.

1

synth.reset(system);

• system, optional - The MIDISystem to reset the synthesizer to. Defaults to gs.

applySnapshot¶

Applies a SynthesizerSnapshot to this synthesizer.

1

synth.applySnapshot(snapshot);

• snapshot - the snapshot to apply.

getSnapshot¶

Gets a SynthesizerSnapshot instance of this synthesizer.

createMIDIChannel¶

Creates a new MIDI channel and adds it to the synthesizer.

1

synth.createMIDIChannel();

stopAllChannels¶

Stop all voices on all channels.

1

synth.stopAllChannels((force = false));

• force - if true, all notes are stopped immediately, otherwise they are stopped gracefully.

destroySynthProcessor¶

Delete all internal values and free up the memory.

clearCache¶

Clear the synthesizer's voice cache.

Properties¶

processorInitialized¶

A Promise that must be awaited before the processor can be used with a compressed sound bank.

sampleRate¶

The sample rate in Hertz.

onEventCall¶

This property can be defined as a function that listens for events.

Parameters the function gets called with an object:

• type - SynthProcessorEventData (string) - the event type.
• data - depends - the event data.

Refer to the synth event types for all events.

midiChannels¶

All MIDI channels of the synthesizer, an array of MIDIChannel.

midiParameters¶

The current Global MIDI Parameters of the synthesizer. These are only editable via MIDI messages.

Stored as key: value. Readonly.

systemParameters¶

The current Global System Parameters of the synthesizer. These are only editable via the API.

Stored as key: value. Readonly.

voiceCount¶

The current total amount of voices that are playing, a number.

currentTime¶

The current time of the synthesizer, in seconds.

reverbProcessor¶

Synthesizer's reverb processor, a ReverbProcessor instance

chorusProcessor¶

Synthesizer's chorus processor, a ChorusProcessor instance

delayProcessor¶

Synthesizer's delay processor, a DelayProcessor instance

soundBankManager¶

The sound bank manager of this synthesizer.

keyModifierManager¶

The key modifier manager of this synthesizer.

onMissingPreset¶

A handler for missing presets during program change. By default, it warns to console. It may be useful for allowing the synthesizer to work without any sound banks.

Parameters the function gets called with:

• patch - MIDIPatch - the MIDI patch that was requested.
• system - MIDISystem (gs, xg, gm or gm2) - the MIDI System for the request.

If a BasicPreset instance is returned by the function, it will be used by the channel.