HISE Docs

Synth

The Synth Object grants access to the current Sound Generators internals (scoped). Depending on the type of Sound Generator, there are some function which will not work, because they are limited to a certain Processor type (You will get a error message if you try to use a illegal API call)


Class methods

addController

Adds a controller to the buffer.

Synth.addController(int channel, int number, int value, int timeStampSamples)



addEffect

Adds a effect (index = -1 to append it at the end).

Synth.addEffect( String type,  String id, int index)



addMessageFromHolder

Adds the event from the given holder and returns a event id for note ons.

Synth.addMessageFromHolder(var messageHolder)



addModulator

Adds a Modulator to the synth's chain. If it already exists, it returns the index.

Synth.addModulator(int chainId,  String type,  String id)



addNoteOff

Adds a note off to the buffer.

Synth.addNoteOff(int channel, int noteNumber, int timeStampSamples)



addNoteOn

Adds a note on to the buffer.

Synth.addNoteOn(int channel, int noteNumber, int velocity, int timeStampSamples)


Be aware that if you call this method with a positive timestamp, it might create a stuck note if you don't ensure that the note-off message you create has a timestamp bigger than this.

There's a shortcut to solving this issue: the new API call Synth.setFixNoteOnAfterNoteOff() which performs a few safe checks to prevent stuck notes in this scenario.

addPitchFade

Adds a pitch fade to the given event ID.

Synth.addPitchFade(int eventId, int fadeTimeMilliseconds, int targetCoarsePitch, int targetFinePitch)



addToFront

Adds the interface to the Container's body (or the frontend interface if compiled)

Synth.addToFront(bool addToFront)



addVolumeFade

Fades all voices with the given event id to the target volume (in decibels).

Synth.addVolumeFade(int eventId, int fadeTimeMilliseconds, int targetVolume)



attachNote

Attaches an artificial note to be stopped when the original note is stopped.

Synth.attachNote(int originalNoteId, int artificialNoteId)



createBuilder

Creates a Builder object that can be used to create the module tree.

Synth.createBuilder()



deferCallbacks

Defers all callbacks to the message thread (midi callbacks become read-only).

Synth.deferCallbacks(bool makeAsynchronous)



getAllEffects

Returns an array of all effects that match the given regex.

Synth.getAllEffects(String regex)



getAllModulators

Returns an array of all modulators that match the given regex.

Synth.getAllModulators(String regex)



getAttribute

Returns the attribute of the parent synth.

Synth.getAttribute(int attributeIndex)



getAudioSampleProcessor

Returns the child synth with the supplied name.

Synth.getAudioSampleProcessor( String name)



getChildSynth

Returns the child synth with the supplied name.

Synth.getChildSynth( String name)



getChildSynthByIndex

Returns the child synth with the given index.

Synth.getChildSynthByIndex(int index)



getDisplayBufferSource

Returns a reference to a processor that holds a display buffer.

Synth.getDisplayBufferSource( String name)



getEffect

Returns the Effect with the supplied name. Can only be called in onInit(). It looks also in all child processors.

Synth.getEffect( String name)



getIdList

Searches the child processors and returns a list with every ID of the given type.

Synth.getIdList( String type)



getMidiPlayer

Creates a reference to the given MIDI player.

Synth.getMidiPlayer( String playerId)



getMidiProcessor

Returns the MidiProcessor with the supplied name. Can not be the own name!

Synth.getMidiProcessor( String name)



getModulator

Returns the Modulator with the supplied name. Can be only called in onInit. It looks also in all child processors.

Synth.getModulator( String name)



getModulatorIndex

Returns the index of the Modulator in the chain with the supplied chainId

Synth.getModulatorIndex(int chainId,  String id)



getNumChildSynths

Returns the number of child synths. Works with SynthGroups and SynthChains.

Synth.getNumChildSynths()



getNumPressedKeys

Returns the number of pressed keys (!= the number of playing voices!).

Synth.getNumPressedKeys()



getRoutingMatrix

Creates a reference to the routing matrix of the given processor.

Synth.getRoutingMatrix( String processorId)



getSampler

Returns the first sampler with the name name.

Synth.getSampler( String name)



getSliderPackProcessor

Returns the sliderpack processor with the given name.

Synth.getSliderPackProcessor( String name)



getSlotFX

Returns the first slot with the given name.

Synth.getSlotFX( String name)



getTableProcessor

Returns the table processor with the given name.

Synth.getTableProcessor( String name)



getTimerInterval

Returns the current timer interval in seconds.

Synth.getTimerInterval()



isArtificialEventActive

Checks if the artificial event is active

Synth.isArtificialEventActive(int eventId)



isKeyDown

Checks if the given key is pressed.

Synth.isKeyDown(int noteNumber)



isLegatoInterval

Checks if any key is pressed.

Synth.isLegatoInterval()



isSustainPedalDown

Returns true if the sustain pedal is pressed.

Synth.isSustainPedalDown()



isTimerRunning

Checks if the timer for this script is running.

Synth.isTimerRunning()



noteOff

Sends a note off message. The envelopes will tail off.

Synth.noteOff(int noteNumber)



noteOffByEventId

Sends a note off message for the supplied event ID. This is more stable than the deprecated noteOff() method.

Synth.noteOffByEventId(int eventId)



noteOffDelayedByEventId

Sends a note off message for the supplied event ID with the given delay in samples.

Synth.noteOffDelayedByEventId(int eventId, int timestamp)



noteOffFromUI

Injects a note off to the incoming MIDI buffer (similar to playNoteFromUI).

Synth.noteOffFromUI(int channel, int noteNumber)



playNote

Plays a note and returns the event id. Be careful or you get stuck notes!

Synth.playNote(int noteNumber, int velocity)



playNoteFromUI

Injects a note on to the incoming MIDI buffer (just as if the virtual keyboard was pressed.

Synth.playNoteFromUI(int channel, int noteNumber, int velocity)



playNoteWithStartOffset

Plays a note and returns the event id with the given channel and start offset.

Synth.playNoteWithStartOffset(int channel, int number, int velocity, int offset)



removeEffect

Removes the given effect.

Synth.removeEffect(var effect)



removeModulator

Removes the modulator.

Synth.removeModulator(var mod)



sendController

Sends a controller event to the synth.

Synth.sendController(int controllerNumber, int controllerValue)



sendControllerToChildSynths

The same as sendController (for backwards compatibility)

Synth.sendControllerToChildSynths(int controllerNumber, int controllerValue)



setAttribute

Sets an attribute of the parent synth.

Synth.setAttribute(int attributeIndex, float newAttribute)



setClockSpeed

Sets the internal clock speed.

Synth.setClockSpeed(int clockSpeed)



setFixNoteOnAfterNoteOff

Adds a few additional safe checks to prevent stuck notes from note offs being processed before their note-on message.

Synth.setFixNoteOnAfterNoteOff(bool shouldBeFixed)


If you're doing any kind of time-manipulation in your MIDI processing, you might end up with a scenario where a note on message is scheduled after its respective note-off message (and with respective note-off message I'm talking about the note-on message with the same event ID). There are usually two reasons for this: either because you're calling Synth.addNoteOn() with a positive timestamp or Message.delayEvent() with an existing event.

The default behaviour of HISE until now was that it was simply your problem to deal with that and if you've created a note-on in the future, the only way to prevent it from creating a stuck note is to make sure that the note-off has a timestamp bigger than the note-on.

That's where this method comes in handy. Just call this once in your onInit script of the script that does the processing and it will magically solve this problem with two safe checks:

  1. If a note-off message is about to be processed, it will look in the event queue of scheduled events if there is a note-on message with the same ID but a bigger timestamp and then cancel this event.
  2. If you call any of the API methods that create an artificial note-off, it will also check the queue for future note-on events and perform the same check.

The first check solves hanging notes from Message.delayEvent() and the latter will solve all issues with artificial note pairs having the wrong timestamp order.

Important: this is a per-sound generator setting, so calling it in your Interface script will not affect the MIDI processing of the child sound generator that actually does the MIDI manipulation!


setMacroControl

Sets one of the eight macro controllers to the newValue.

Synth.setMacroControl(int macroIndex, float newValue)


Calling this method will have the same effect as turning the respective Macro Control but you can use it for a more fine-grained control about what and when to send the value change.

Unlike everything else in a proper programming language, the range of the macroIndex argument starts with 1 (to be consistent with the labels in HISE).

The value argument is expected to be in the 0 - 127 value range, but it doesn't need to be an integer.

It's your responsibility to watch out that this call does not occur in a control that is connected to the same macro control or you might end up getting a recursive loop and freeze your system!

setModulatorAttribute

Sets a ModulatorAttribute.

Synth.setModulatorAttribute(int chainId, int modulatorIndex, int attributeIndex, float newValue)



setShouldKillRetriggeredNote

If set to true, this will kill retriggered notes (default).

Synth.setShouldKillRetriggeredNote(bool killNote)



setUseUniformVoiceHandler

Use a uniform voice index for the given container.

Synth.setUseUniformVoiceHandler(String containerId, bool shouldUseUniformVoiceHandling)


This is a new feature introduced with HISE 3.5.0 and ensures that all sound generators will use the same voice index whenever a new voice is started. Synchronizing the voice indexes comes with a slight overhead (so it's disabled by default), but it allows you to use envelope modulators as global modulation source because now it can properly fetch the required modulation values because it's guaranteed that the voice indexes will match.

In order to use this function, call it with a container ID that you want to be used as root for the voice unification. This is not required to be the master container, so you can still perform additional MIDI processing (arpeggiators, glide scripts etc). However you need to ensure that beyond that point every sound generator will start not more than one voice for each incoming MIDI event.

setVoiceGainValue

Applies a gain factor to a specified voice.

Synth.setVoiceGainValue(int voiceIndex, float gainValue)



setVoicePitchValue

Applies a pitch factor (0.5 ... 2.0) to a specified voice.

Synth.setVoicePitchValue(int voiceIndex, double pitchValue)



startTimer

Starts the timer of the synth.

Synth.startTimer(double seconds)



stopTimer

Stops the timer of the synth. You can call this also in the timer callback.

Synth.stopTimer()