Class WorkletSynthesizer

This synthesizer uses an AudioWorklet node to provide real-time playback.

Hierarchy (View Summary)

BasicSynthesizer
- WorkletSynthesizer

Constructors

constructor

new WorkletSynthesizer(
context: BaseAudioContext,
config?: Partial<SynthConfig>,
): WorkletSynthesizer
Creates a new instance of an AudioWorklet-based synthesizer.

Warning
Avoid using multiple synthesizer instances. The SoundBankManager and one instance should be sufficient, especially when using more than 16 channels. See this comment for more info.
Parameters
- context: BaseAudioContext
  The audio context.
- config: Partial<SynthConfig> = DEFAULT_SYNTH_CONFIG
  Optional configuration for the synthesizer.
Returns WorkletSynthesizer
Overrides BasicSynthesizer.constructor
- Defined in src/synthesizer/worklet/worklet_synthesizer.ts:42

Properties

`Readonly`context

context: BaseAudioContext

Synthesizer's parent audio context instance.

`Readonly`convolverNode

convolverNode: ConvolverNode | undefined

The AudioNode that processes the synthesizer's captured reverb tail through a Web Audio ConvolverNode.

`Readonly`eventHandler

eventHandler: SynthEventHandler = ...

The synthesizer's event handler. It allows setting up custom event listeners for the synthesizer.

`Readonly`isReady

isReady: Promise<unknown>

A promise that gets resolved when the synthesizer gets fully initialized.

`Readonly`midiChannels

midiChannels: LibMIDIChannel[] = []

The synthesizer's (virtual) MIDI channels.

presetList

presetList: MIDIPatchFull[] = []

The current preset list of the synthesizer, including all sound banks with their offsets set through the SoundBankManager.

`Readonly`soundBankManager

soundBankManager: SoundBankManager = ...

The synthesizer's sound bank manager. It allows managing the sound bank list.

Accessors

currentTime

get currentTime(): number
The connected BaseAudioContext's time.

Returns number
Inherited from BasicSynthesizer.currentTime
- Defined in src/synthesizer/basic/basic_synthesizer.ts:267

midiParameters

get midiParameters(): Readonly<GlobalMIDIParameter>
The GlobalMIDIParameters of the synthesizer. These are only editable via MIDI messages.

Returns Readonly<GlobalMIDIParameter>
Inherited from BasicSynthesizer.midiParameters
- Defined in src/synthesizer/basic/basic_synthesizer.ts:260

systemParameters

get systemParameters(): Readonly<GlobalSystemParameter>
The GlobalSystemParameters of the synthesizer. These are only editable via the API.

Returns Readonly<GlobalSystemParameter>
Inherited from BasicSynthesizer.systemParameters
- Defined in src/synthesizer/basic/basic_synthesizer.ts:276

voiceCount

get voiceCount(): number
The current amount of voices (notes) being synthesized. A real-time value.

Returns number
Inherited from BasicSynthesizer.voiceCount
- Defined in src/synthesizer/basic/basic_synthesizer.ts:247

Methods

addNewChannel

addNewChannel(): void
Adds a new channel to the synthesizer. The channel appears in BasicSynthesizer.midiChannels once the core confirms it with a channelAdded event.

Returns void
Inherited from BasicSynthesizer.addNewChannel
- Defined in src/synthesizer/basic/basic_synthesizer.ts:452

channelPressure

channelPressure(
    channel: number,
    pressure: number,
    eventOptions?: SynthMethodOptions,
): void
Apply pressure to the given channel. It usually controls the vibrato amount.
Parameters
- channel: number
  The MIDI channel to use. It usually ranges from 0 to 15, but it depends on the channel count.
- pressure: number
  The pressure to apply. Ranges from 0 to 127. 0 means no pressure, 127 means max.
- eventOptions: SynthMethodOptions = DEFAULT_SYNTH_METHOD_OPTIONS
  Additional options for this command.
Returns void
Example
```
// Set channel 1 pressure to 64 (middle)
synth.channelPressure(1, 64);
```
Inherited from BasicSynthesizer.channelPressure
- Defined in src/synthesizer/basic/basic_synthesizer.ts:660

connect

connect(destinationNode: AudioNode): AudioNode
Connects the synthesizer to a given AudioNode.
Parameters
- destinationNode: AudioNode
  The node to connect to.
Returns AudioNode
The destination node.
Inherited from BasicSynthesizer.connect
- Defined in src/synthesizer/basic/basic_synthesizer.ts:285

connectChannel

connectChannel(targetNode: AudioNode, channelNumber: number): AudioNode
Connects a given channel output to the given audio node. Note that this output is only meant for visualization and may be silent when an insertion effect for this channel is enabled.
Parameters
- targetNode: AudioNode
  The node to connect to.
- channelNumber: number
  The channel number to connect to, will be rolled over if value is greater than 15.
Returns AudioNode
The target node.
Example
```
// Create an analyzer for channel 1
const analyzer = context.createAnalyser();
synth.connectChannel(analyzer, 0);
```
Inherited from BasicSynthesizer.connectChannel
- Defined in src/synthesizer/basic/basic_synthesizer.ts:474

controllerChange

controllerChange(
    channel: number,
    controller: MIDIController,
    value: number,
    eventOptions?: SynthMethodOptions,
): void
Set a given MIDI controller to a given value.

Tip
Refer to this table for the list of controllers supported by default.
Parameters
- channel: number
  The MIDI channel to use. It usually ranges from 0 to 15, but it depends on the channel count.
- controller: MIDIController
  The MIDI CC number of the controller to change.
- value: number
  The value to set the given controller to. Ranges from 0 to 127.
- eventOptions: SynthMethodOptions = DEFAULT_SYNTH_METHOD_OPTIONS
  Additional options for this command.
Returns void
Example
```
// Set controller 10 (Channel Pan) on channel 2 to 127 (hard right)
synth.controllerChange(2, 10, 127);
```
Inherited from BasicSynthesizer.controllerChange
- Defined in src/synthesizer/basic/basic_synthesizer.ts:618

destroy

destroy(): void
Properly disposes of the synthesizer along with its audio nodes and the core. All pending operations (such as loading a sound bank) are rejected.

Warning
Remember, you MUST call this method after you're done with the synthesizer! Otherwise it will keep processing and the performance will greatly suffer.

Note
For WorkerSynthesizer, the Worker itself is owned by you. Terminate it after calling this method if it is no longer needed.

Returns void
Inherited from BasicSynthesizer.destroy
- Defined in src/synthesizer/basic/basic_synthesizer.ts:324

disconnect

disconnect(destinationNode: AudioNode): AudioNode
Disconnects the synthesizer from a given AudioNode.
Parameters
- destinationNode: AudioNode
  The node to disconnect from.
Returns AudioNode
The destination node.
Inherited from BasicSynthesizer.disconnect
- Defined in src/synthesizer/basic/basic_synthesizer.ts:300

disconnectChannel

disconnectChannel(targetNode: AudioNode, channelNumber: number): void
Disconnects a given channel output from the given audio node.
Parameters
- targetNode: AudioNode
  The node to disconnect from.
- channelNumber: number
  The channel number to disconnect, will be rolled over if value is greater than 15.
Returns void
Example
```
// Disconnect the analyzer from earlier
synth.disconnectChannel(analyzer, 0);
```
Inherited from BasicSynthesizer.disconnectChannel
- Defined in src/synthesizer/basic/basic_synthesizer.ts:494

getMergedOutput

getMergedOutput(): ChannelMergerNode
Returns a ChannelMergerNode with all 16 channel outputs merged into a single one, with multiple channels, layered as follows:
- Channel1L, Channel1R
- ...
- Channel16L, Channel16R
This is intended for offline audio rendering via OfflineAudioContext to allow extraction of separate channels.

Note
The main output is not included in the merged output, as Web Audio caps the number of channels at 32 (16 stereo pairs).

Warning
Make sure the OfflineAudioContext is created with 32 channels, otherwise the channels will be downmixed.

Tip
An example demonstrating this can be found here.
Returns ChannelMergerNode
- Defined in src/synthesizer/worklet/worklet_synthesizer.ts:118

getSnapshot

getSnapshot(): Promise<SynthesizerSnapshot>
Gets the current SynthesizerSnapshot of the synthesizer.

Returns Promise<SynthesizerSnapshot>
Inherited from BasicSynthesizer.getSnapshot
- Defined in src/synthesizer/basic/basic_synthesizer.ts:436

lockMIDIParameter

lockMIDIParameter<P extends keyof GlobalMIDIParameter>(
parameter: P,
isLocked: boolean,
): void
Locks or unlocks a given GlobalMIDIParameter. This prevents any changes to it until it's unlocked.
Type Parameters
- P extends keyof GlobalMIDIParameter
Parameters
- parameter: P
  The Global MIDI Parameter to lock.
- isLocked: boolean
  If the parameter should be locked.
Returns void
Example
```
// Lock the MIDI system to GS
synth.lockMIDIParameter("system", "gs");
```
Inherited from BasicSynthesizer.lockMIDIParameter
- Defined in src/synthesizer/basic/basic_synthesizer.ts:385

noteOff

noteOff(
    channel: number,
    midiNote: number,
    eventOptions?: SynthMethodOptions,
): void
Stops playing a note.
Parameters
- channel: number
  The MIDI channel to use. It usually ranges from 0 to 15, but it depends on the channel count.
- midiNote: number
  The MIDI note number to stop. Ranges from 0 to 127.
- eventOptions: SynthMethodOptions = DEFAULT_SYNTH_METHOD_OPTIONS
  Additional options for this command.
Returns void
Example
```
// Stop the note 77 (F) on channel 15
synth.noteOff(15, 77);
```
Inherited from BasicSynthesizer.noteOff
- Defined in src/synthesizer/basic/basic_synthesizer.ts:575

noteOn

noteOn(
    channel: number,
    midiNote: number,
    velocity: number,
    eventOptions?: SynthMethodOptions,
): void
Starts playing a note.

Note
A velocity of 0 is treated like a Note Off message.
Parameters
- channel: number
  The MIDI channel to use. It usually ranges from 0 to 15, but it depends on the channel count.
- midiNote: number
  The MIDI note number to play. Ranges from 0 to 127.
- velocity: number
  Controls how loud the note is. Ranges from 0 to 127, where 127 is the loudest and 1 is the quietest.
- eventOptions: SynthMethodOptions = DEFAULT_SYNTH_METHOD_OPTIONS
  Additional options for this command.
Returns void
Example
```
// Start the note 64 (E) on channel 0 with velocity of 120
synth.noteOn(0, 64, 120);
```
Inherited from BasicSynthesizer.noteOn
- Defined in src/synthesizer/basic/basic_synthesizer.ts:549

pitchWheel

pitchWheel(
    channel: number,
    value: number,
    eventOptions?: SynthMethodOptions,
): void
Change the channel's pitch, including the currently playing notes.
Parameters
- channel: number
  The MIDI channel to use. It usually ranges from 0 to 15, but it depends on the channel count.
- value: number
  The 14-bit pitch value. Ranges from 0 to 16383 where 8192 is no pitch change.
- eventOptions: SynthMethodOptions = DEFAULT_SYNTH_METHOD_OPTIONS
  Additional options for this command.
Returns void
Example
```
// Set pitch bend on channel 1 to middle (no change)
synth.pitchWheel(1, 8192);
```
Inherited from BasicSynthesizer.pitchWheel
- Defined in src/synthesizer/basic/basic_synthesizer.ts:716

pitchWheelRange

pitchWheelRange(
    channel: number,
    range: number,
    eventOptions?: SynthMethodOptions,
): void
Change the channel's pitch bend range in semitones. It uses Registered Parameter Number controllers internally.

Tip
The pitch bend range can be decimal, for example, 0.5 means +- half a semitone. The fractional part is sent through the Data Entry LSB with a precision of 1/128 of a semitone.
Parameters
- channel: number
  The MIDI channel to use. It usually ranges from 0 to 15, but it depends on the channel count.
- range: number
  The bend range in semitones.
- eventOptions: SynthMethodOptions = DEFAULT_SYNTH_METHOD_OPTIONS
  Additional options for this command.
Returns void
Example
```
// Set the pitch bend range on channel 0 to +-12 semitones (one octave)
synth.pitchWheelRange(0, 12);
```
Inherited from BasicSynthesizer.pitchWheelRange
- Defined in src/synthesizer/basic/basic_synthesizer.ts:749

polyPressure

polyPressure(
    channel: number,
    midiNote: number,
    pressure: number,
    eventOptions?: SynthMethodOptions,
): void
Apply pressure to the given note on a given channel. It may be bound to specific parameters with system exclusive messages to allow for extra controls, such as per-note pitch wheel.
Parameters
- channel: number
  The MIDI channel to use. It usually ranges from 0 to 15, but it depends on the channel count.
- midiNote: number
  The MIDI note number to apply pressure to. Ranges from 0 to 127.
- pressure: number
  The pressure to apply. Ranges from 0 to 127.
- eventOptions: SynthMethodOptions = DEFAULT_SYNTH_METHOD_OPTIONS
  Additional options for this command.
Returns void
Example
```
// Set channel 11 pressure on note 60 (C) to 127 (max)
synth.polyPressure(11, 60, 127);
```
Inherited from BasicSynthesizer.polyPressure
- Defined in src/synthesizer/basic/basic_synthesizer.ts:689

programChange

programChange(
    channel: number,
    programNumber: number,
    eventOptions?: SynthMethodOptions,
): void
Changes the program for the given channel.
Parameters
- channel: number
  The MIDI channel to use. It usually ranges from 0 to 15, but it depends on the channel count.
- programNumber: number
  The MIDI program number to use. Ranges from 0 to 127.
- eventOptions: SynthMethodOptions = DEFAULT_SYNTH_METHOD_OPTIONS
  Additional options for this command.
Returns void
Example
```
// Change the program on channel 0 to 16 (drawbar organ)
synth.programChange(0, 16);
```
Inherited from BasicSynthesizer.programChange
- Defined in src/synthesizer/basic/basic_synthesizer.ts:814

reset

reset(): void
Fully resets the synthesizer to GS mode.

Returns void
Inherited from BasicSynthesizer.reset
- Defined in src/synthesizer/basic/basic_synthesizer.ts:639

reverbateEverythingBecauseWhyNot

reverbateEverythingBecauseWhyNot(): "That's the spirit!"
Yes please!

Cranks the reverb up to the max and returns a string that says: That's the spirit!

Returns "That's the spirit!"
Inherited from BasicSynthesizer.reverbateEverythingBecauseWhyNot
- Defined in src/synthesizer/basic/basic_synthesizer.ts:931

sendMessage

sendMessage(
    message: Iterable<number>,
    channelOffset?: number,
    eventOptions?: SynthMethodOptions,
): void
Sends a raw MIDI message to the synthesizer.
Parameters
- message: Iterable<number>
  The MIDI message to process.
- channelOffset: number = 0
  Adds to the channel number of the message. It defaults to 0.
- eventOptions: SynthMethodOptions = DEFAULT_SYNTH_METHOD_OPTIONS
  Additional options for this command.
Returns void
Example
```
// Send a MIDI note on message for channel 2 with note 61 (C#) and velocity 120
synth.sendMessage([0x92, 0x3d, 0x78]);
```
Inherited from BasicSynthesizer.sendMessage
- Defined in src/synthesizer/basic/basic_synthesizer.ts:513

setLogLevel

setLogLevel(
    enableInfo: boolean,
    enableWarning: boolean,
    enableGroup: boolean,
): void
Sets spessasynth_core's log level in the processor.
Parameters
- enableInfo: boolean
  Enable info (verbose)
- enableWarning: boolean
  Enable warnings (unrecognized messages)
- enableGroup: boolean
  Enable groups (to group a lot of logs)
Returns void
Example
```
// Enable all logs
synth.setLogLevel(true, true, true);
```
Inherited from BasicSynthesizer.setLogLevel
- Defined in src/synthesizer/basic/basic_synthesizer.ts:356

setSystemParameter

setSystemParameter<K extends keyof GlobalSystemParameter>(
parameter: K,
value: GlobalSystemParameter[K],
): void
Sets a GlobalSystemParameter to a given value.
Type Parameters
- K extends keyof GlobalSystemParameter
Parameters
- parameter: K
  The parameter to set.
- value: GlobalSystemParameter[K]
  The value to set.
Returns void
Example
```
// Set the master gain to 200%
synth.setSystemParameter("gain", 2);
```
Inherited from BasicSynthesizer.setSystemParameter
- Defined in src/synthesizer/basic/basic_synthesizer.ts:412

startOfflineRender

startOfflineRender(
config: OfflineRenderWorkletData<LibSynthesizerSnapshot>,
): Promise<void>
Starts an offline audio render.

Warning
Call this method immediately after you've set up the synthesizer. Do NOT call any other methods after initializing before this one. Chromium seems to ignore worklet messages for OfflineAudioContext.
Parameters
- config: OfflineRenderWorkletData<LibSynthesizerSnapshot>
  The configuration to use for rendering.
Returns Promise<void>
- Defined in src/synthesizer/worklet/worklet_synthesizer.ts:65

stopAll

stopAll(force?: boolean): void
Stop all notes. Equivalent of MIDI "panic".
Parameters
- force: boolean = false
  If the notes should immediately be stopped, defaults to false.
Returns void
Inherited from BasicSynthesizer.stopAll
- Defined in src/synthesizer/basic/basic_synthesizer.ts:592

systemExclusive

systemExclusive(
    messageData:
        | number[]
        | Iterable<number, any, any>
        | Uint8Array<ArrayBufferLike>,
    channelOffset?: number,
    eventOptions?: SynthMethodOptions,
): void
Sends a MIDI Sysex message to the synthesizer.

Tip
Refer to the MIDI Implementation for the list of supported System Exclusives.
Parameters
- messageData: number[] | Iterable<number, any, any> | Uint8Array<ArrayBufferLike>
  The message's data, excluding the F0 byte, but including the F7 at the end.
- channelOffset: number = 0
  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 (0-based), send a system exclusive for channel 0 and specify the channel offset to be 16.
- eventOptions: SynthMethodOptions = DEFAULT_SYNTH_METHOD_OPTIONS
  Additional options for this command.
Returns void
Example
```
// Send a GS DT1 Use Drums On Channel 10 (turn channel 10 into a drum channel)
synth.systemExclusive([
    0x41, 0x10, 0x42, 0x12, 0x40, 0x1a, 0x15, 0x01, 0x10, 0xf7
]);

// Send the same message with a channel offset of 10 (turn channel 20 into a drum channel)
synth.systemExclusive(
    [0x41, 0x10, 0x42, 0x12, 0x40, 0x1a, 0x15, 0x01, 0x10, 0xf7],
    10
);
```
Inherited from BasicSynthesizer.systemExclusive
- Defined in src/synthesizer/basic/basic_synthesizer.ts:856

tuneKeys

tuneKeys(
program: number,
tunings: { sourceKey: number; targetPitch: number }[],
): void
Tunes individual MIDI key numbers on a given program using the MIDI Tuning Standard. Think of it as a pitch wheel but for individual notes.

Warning
This tuning is not applied per channel, but per MIDI program number.
Parameters
- program: number
  The MIDI program to tune. Ranges from 0 to 127.
- tunings: { sourceKey: number; targetPitch: number }[]
  An array of tunings, each containing two properties:
  
  sourceKey - The MIDI note number to tune.
  
  targetPitch - The MIDI note number of the target pitch. Fractional values are allowed, for example, 60.5 is C plus 50 cents. A targetPitch of -1 restores the default tuning.
Returns void
Inherited from BasicSynthesizer.tuneKeys
- Defined in src/synthesizer/basic/basic_synthesizer.ts:884

Class WorkletSynthesizer

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns WorkletSynthesizer

Properties

Readonlycontext

ReadonlyconvolverNode

ReadonlyeventHandler

ReadonlyisReady

ReadonlymidiChannels

presetList

ReadonlysoundBankManager

Accessors

currentTime

Returns number

midiParameters

Returns Readonly<GlobalMIDIParameter>

systemParameters

Returns Readonly<GlobalSystemParameter>

voiceCount

Returns number

Methods

addNewChannel

Returns void

channelPressure

Parameters

Returns void

Example

connect

Parameters

Returns AudioNode

connectChannel

Parameters

Returns AudioNode

Example

controllerChange

Parameters

Returns void

Example

destroy

Returns void

disconnect

Parameters

Returns AudioNode

disconnectChannel

Parameters

Returns void

Example

getMergedOutput

Returns ChannelMergerNode

getSnapshot

Returns Promise<SynthesizerSnapshot>

lockMIDIParameter

Type Parameters

Parameters

Returns void

Example

noteOff

Parameters

Returns void

Example

noteOn

Parameters

Returns void

Example

pitchWheel

Parameters

Returns void

Example

pitchWheelRange

Parameters

Returns void

Example

`Readonly`context

`Readonly`convolverNode

`Readonly`eventHandler

`Readonly`isReady

`Readonly`midiChannels

`Readonly`soundBankManager