Synth
The Synth
object grants access to the 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.
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:
- 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.
- 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()