Engine
The Engine
object contains a lot of functions related to global properties (like sample rate or host tempo) and object creation.
Engine.getSampleRate() // returns the current sample rate
Engine.sendAllNotesOff() // sends a all note off (MIDI Panic) message at the next audio buffer
Class methods
addModuleStateToUserPreset
Adds an entire module to the user preset system.
Engine.addModuleStateToUserPreset(var moduleId)
This function can be used to add the entire state of a HISE module to the user preset. This function will create the same XML element for the given module as it is stored in the XML file of the project (or if you copy a module using Ctrl+C) and attach it to the user preset's xml data. moduleId
can be either the ID of the module that you want to attach to the user preset, or it can be a JSON object that provides additional functionality to remove properties and child elements.
Be aware that you can only use this method with HISE modules that do not have any child processors as this would cause a rearrangement of the signal tree with unexpected side effects!
Passing in a JSON object as parameter allows you to sanitize the XML element before it gets stored into the user preset XML tree. This has two benefits:
- Cleaner output
- Protection against weird side effects - eg. the user could manually edit the routing matrix and cause havoc.
Property | Type | Description |
ID
|
String | the ID of the HISE module as seen in the Patch Browser (the string you would normally pass into this method). |
RemovedProperties
|
Array | A list of all properties (as String) that you want to remove from the XML data before saving. Be aware that this only applies to the root XML element. |
RemovedChildElements
|
Array | A list of all child elements (String of the XML tag) of the XML element that you want to remove before saving. |
If you remove child elements or properties with this method, HISE will create a copy of the data that is about to be deleted BEFORE loading a new preset and then attaches it to the XML data that was loaded to ensure that this data remains static.
allNotesOff
Sends an allNotesOff message at the next buffer.
Engine.allNotesOff()
clearMidiFilePool
Removes all entries from the MIDi file pool.
Engine.clearMidiFilePool()
clearSampleMapPool
Removes all entries from the samplemap pool
Engine.clearSampleMapPool()
clearUndoHistory
Clears the undo history.
Engine.clearUndoHistory()
compressJSON
Compresses a JSON object as Base64 string using zstd.
Engine.compressJSON(var object)
copyToClipboard
Copies the given text to the clipboard.
Engine.copyToClipboard(String textToCopy)
createAndRegisterAudioFile
Creates a audio file holder and registers it so you can access it from other modules.
Engine.createAndRegisterAudioFile(int index)
createAndRegisterRingBuffer
Creates a ring buffer and registers it so you can access it from other modules.
Engine.createAndRegisterRingBuffer(int index)
createAndRegisterSliderPackData
Creates a SliderPack Data object and registers it so you can access it from other modules.
Engine.createAndRegisterSliderPackData(int index)
createAndRegisterTableData
Creates a Table object and registers it so you can access it from other modules.
Engine.createAndRegisterTableData(int index)
createBackgroundTask
Creates a background task that can execute heavyweight functions.
Engine.createBackgroundTask(String name)
createBeatportManager
Creates a beatport manager object.
Engine.createBeatportManager()
createBroadcaster
Creates a broadcaster that can send messages to attached listeners.
Engine.createBroadcaster(var defaultValues)
This creates a Broadcaster
object that can listen to value changes. The argument you pass in here is a metadata object that describes the properties of the Broadcaster.
/** If you start a comment with `/**` it will get attached to the metadata objects as `comment` property. */
const var bc = Engine.createBroadcaster({
"id": "My Broadcaster", // give it a meaningful name
"colour": -1, // assign a colour (-1 just creates a random colour from the ID hash)
"tags": ["audio", "value-handling"], // assign some tags
"args": ["myValue", "isPlaying"]
});
The information from the metadata will vastly help the broadcaster map appearance, so from the example code you'll get this beauty:
In addition to the usual properties you also need to supply an array of strings called args
which will define the argument amount and name. They will all be initialised to undefined
so that the callbacks only start happening when you assign a value to them (or the event source does this for you).
Be aware that every function you pass into Broadcaster.addListener()
will need to have as many parameters as you define with the args
property or it will cause an error message. Also if you are planning to attach the broadcaster to a predefined internal event (eg. component property changes), the numbers must also match the expected argument amount (in this particular case: 3)
createDspNetwork
Creates a Dsp node network.
Engine.createDspNetwork(String id)
createErrorHandler
Creates an error handler that reacts on initialisation errors.
Engine.createErrorHandler()
createExpansionHandler
Creates (and activates) the expansion handler.
Engine.createExpansionHandler()
createFFT
Creates an FFT object.
Engine.createFFT()
createFixObjectFactory
Creates a fix object factory using the data layout.
Engine.createFixObjectFactory(var layoutDescription)
createGlobalScriptLookAndFeel
Creates a (or returns an existing ) script look and feel object.
Engine.createGlobalScriptLookAndFeel()
createLicenseUnlocker
Creates a reference to the script license manager.
Engine.createLicenseUnlocker()
createMacroHandler
Creates a macro handler that lets you programmatically change the macro connections.
Engine.createMacroHandler()
createMessageHolder
Creates a storage object for Message events.
Engine.createMessageHolder()
createMidiAutomationHandler
Creates a MIDI Automation handler.
Engine.createMidiAutomationHandler()
createMidiList
Creates a MIDI List object.
Engine.createMidiList()
createModulationMatrix
Creates a modulation matrix object that handles dynamic modulation using the given Global Modulator Container as source.
Engine.createModulationMatrix(String containerId)
createNeuralNetwork
Creates a neural network with the given ID.
Engine.createNeuralNetwork(String id)
createThreadSafeStorage
Creates a thread safe storage container.
Engine.createThreadSafeStorage()
createTimerObject
Creates a new timer object.
Engine.createTimerObject()
createTransportHandler
Creates an object that can listen to transport events.
Engine.createTransportHandler()
createUnorderedStack
Creates a unordered stack that can hold up to 128 float numbers.
Engine.createUnorderedStack()
createUserPresetHandler
Creates an user preset handler.
Engine.createUserPresetHandler()
decodeBase64ValueTree
Decodes an Base64 encrypted valuetree (eg. HiseSnippets).
Engine.decodeBase64ValueTree( String b64Data)
doubleToString
Returns a string of the value with the supplied number of digits.
Engine.doubleToString(double value, int digits)
dumpAsJSON
Exports an object as JSON.
Engine.dumpAsJSON(var object, String fileName)
extendTimeOut
Extends the compilation timeout. Use this if you have a long task that would get cancelled otherwise. This is doing nothing in compiled plugins.
Engine.extendTimeOut(int additionalMilliseconds)
getBufferSize
Returns the current maximum processing block size.
Engine.getBufferSize()
getClipboardContent
Returns the clipboard content.
Engine.getClipboardContent()
getComplexDataReference
Returns a reference to a complex data type from the given module.
Engine.getComplexDataReference(String dataType, String moduleId, int index)
getControlRateDownsamplingFactor
Returns the downsampling factor for the modulation signal (default is 8).
Engine.getControlRateDownsamplingFactor()
getCpuUsage
Returns the current CPU usage in percent (0 ... 100)
Engine.getCpuUsage()
getCurrentUserPresetName
Returns the currently loaded user preset (without extension).
Engine.getCurrentUserPresetName()
getDecibelsForGainFactor
Converts gain factor (0.0 .. 1.0) to decibel (-100.0 ... 0).
Engine.getDecibelsForGainFactor(double gainFactor)
getDeviceResolution
Returns the full screen resolution for the current device.
Engine.getDeviceResolution()
getDeviceType
Returns the mobile device that this software is running on.
Engine.getDeviceType()
getDspNetworkReference
Creates a reference to the DSP network of another script processor.
Engine.getDspNetworkReference(String processorId, String id)
getExpansionList
Creates a list of all available expansions.
Engine.getExpansionList()
getExtraDefinitionsInBackend
Returns the platform specific extra definitions from the Project settings as JSON object.
Engine.getExtraDefinitionsInBackend()
getFilterModeList
Returns an object that contains all filter modes.
Engine.getFilterModeList()
You can use this object to create a list of filter modes you would like to add to your plugin.
Example Code:
// Create a filter effect
const var effect = Synth.addEffect("PolyphonicFilter", "filter", 0);
// Create a filter graph
const var display = Content.addFloatingTile("tile", 0, 0);
display.set("width", 200);
display.set("height", 50);
display.setContentData({"Type": "FilterDisplay",
"ProcessorId": "filter"});
// Create a knob for the frequency
const var filterKnob = Content.addKnob("filterKnob", 250, 0);
filterKnob.set("mode", "Frequency");
inline function f(component, value){ effect.setAttribute(effect.Frequency, value); };
filterKnob.setControlCallback(f);
const var modeSelector = Content.addComboBox("modeSelector", 400, 10);
// Create the filter mode list object
const var filterList = Engine.getFilterModeList();
// Pick some values from the object and store it in an array
const var filterModes = [ filterList.StateVariableNotch,
filterList.StateVariableLP ];
// Create an array with a name for each mode
const var filterNames = [ "Notch",
"SVF Lowpass"];
// Use the filterNames list as combobox items
modeSelector.set("items", filterNames.join("\n"));
inline function modeCallback(component, value)
{
// combobox values are starting with 1
local index = value-1;
if(index >= 0)
{
// use the index to get the actual number from the filterModes array.
effect.setAttribute(effect.Mode, filterModes[index]);
}
}
modeSelector.setControlCallback(modeCallback);
getFrequencyForMidiNoteNumber
Converts midi note number 0 ... 127 to Frequency 20 ... 20.000.
Engine.getFrequencyForMidiNoteNumber(int midiNumber)
getGainFactorForDecibels
Converts decibel (-100.0 ... 0.0) to gain factor (0.0 ... 1.0).
Engine.getGainFactorForDecibels(double decibels)
getGlobalPitchFactor
Returns the global pitch factor (in semitones).
Engine.getGlobalPitchFactor()
getGlobalRoutingManager
Returns a reference to the global routing manager.
Engine.getGlobalRoutingManager()
getHostBpm
Returns the Bpm of the host.
Engine.getHostBpm()
getLatencySamples
Returns the latency of the plugin as reported to the host. Default is 0.
Engine.getLatencySamples()
getLorisManager
Returns a reference to the global Loris manager.
Engine.getLorisManager()
getMacroName
Returns the name for the given macro index.
Engine.getMacroName(int index)
getMasterPeakLevel
Returns the current peak volume (0...1) for the given channel.
Engine.getMasterPeakLevel(int channel)
getMemoryUsage
Returns the current memory usage in MB.
Engine.getMemoryUsage()
This only takes the size of the preload buffers and streaming buffers of the samples into account - the actual memory consumption might be much higher if you are using lots of images.
getMidiNoteFromName
Converts MIDI note name to MIDI number ("C3" for middle C).
Engine.getMidiNoteFromName(String midiNoteName)
getMidiNoteName
Converts MIDI note number to Midi note name ("C3" for middle C).
Engine.getMidiNoteName(int midiNumber)
getMilliSecondsForQuarterBeats
Converts quarter beats to milliseconds using the current tempo.
Engine.getMilliSecondsForQuarterBeats(double quarterBeats)
getMilliSecondsForQuarterBeatsWithTempo
Converts quarter beats to milliseconds using the given tempo.
Engine.getMilliSecondsForQuarterBeatsWithTempo(double quarterBeats, double bpm)
getMilliSecondsForSamples
Converts samples to milli seconds.
Engine.getMilliSecondsForSamples(double samples)
getMilliSecondsForTempo
Returns the millisecond value for the supplied tempo (HINT: Use "TempoSync" mode from Slider!)
Engine.getMilliSecondsForTempo(int tempoIndex)
getName
Returns the product name (not the HISE name!).
Engine.getName()
getNumPluginChannels
Returns the amount of output channels.
Engine.getNumPluginChannels()
getNumVoices
Returns the amount of currently active voices.
Engine.getNumVoices()
getOS
Returns the current operating system ("OSX", "LINUX", or ("WIN").
Engine.getOS()
You can use this method to query the OS in order to implement some platform specific code. HISE tries to abstract as much OS specifics as possible,but especially when it comes to font loading, there are some subtle differences between the different operating systems.
Console.print(Engine.getOS());
getPitchRatioFromSemitones
Converts a semitone value to a pitch ratio (-12 ... 12) -> (0.5 ... 2.0)
Engine.getPitchRatioFromSemitones(double semiTones)
getPlayHead
Allows access to the data of the host (playing status, timeline, etc...).
Engine.getPlayHead()
getPreloadMessage
Returns the current preload message if there is one.
Engine.getPreloadMessage()
getPreloadProgress
Returns the preload progress from 0.0 to 1.0. Use this to display some kind of loading icon.
Engine.getPreloadProgress()
getProjectInfo
Returns project and company info from the Project's preferences.
Engine.getProjectInfo()
getQuarterBeatsForMilliSeconds
Converts milliseconds to quarter beats using the current tempo.
Engine.getQuarterBeatsForMilliSeconds(double milliSeconds)
getQuarterBeatsForMilliSecondsWithTempo
Converts milliseconds to quarter beats using the given tempo.
Engine.getQuarterBeatsForMilliSecondsWithTempo(double milliSeconds, double bpm)
getQuarterBeatsForSamples
Converts samples to quarter beats using the current tempo.
Engine.getQuarterBeatsForSamples(double samples)
getQuarterBeatsForSamplesWithTempo
Converts samples to quarter beats using the given tempo.
Engine.getQuarterBeatsForSamplesWithTempo(double samples, double bpm)
getRegexMatches
Returns an array with all matches.
Engine.getRegexMatches(String stringToMatch, String regex)
getSampleFilesFromDirectory
Iterates the given sub-directory of the Samples folder and returns a list with all references to audio files.
Engine.getSampleFilesFromDirectory( String relativePathFromSampleFolder, bool recursive)
getSampleRate
Returns the current sample rate.
Engine.getSampleRate()
getSamplesForMilliSeconds
Converts milli seconds to samples
Engine.getSamplesForMilliSeconds(double milliSeconds)
getSamplesForQuarterBeats
Converts quarter beats to samples using the current tempo.
Engine.getSamplesForQuarterBeats(double quarterBeats)
getSamplesForQuarterBeatsWithTempo
Converts quarter beats to samples using the given tempo.
Engine.getSamplesForQuarterBeatsWithTempo(double quarterBeats, double bpm)
getSemitonesFromPitchRatio
Converts a pitch ratio to semitones (0.5 ... 2.0) -> (-12 ... 12)
Engine.getSemitonesFromPitchRatio(double pitchRatio)
getSettingsWindowObject
Returns a object that contains the properties for the settings dialog.
Engine.getSettingsWindowObject()
getStringWidth
Returns the width of the string for the given font properties.
Engine.getStringWidth(String text, String fontName, float fontSize, float fontSpacing)
getSystemStats
Returns info about the current hardware and OS configuration.
Engine.getSystemStats()
getSystemTime
Returns a fully described string of this date and time in ISO-8601 format (using the local timezone) with or without divider characters.
Engine.getSystemTime(bool includeDividerCharacters)
getTempoName
Returns the tempo name for the given index
Engine.getTempoName(int tempoIndex)
getUptime
Returns the uptime of the engine in seconds.
Engine.getUptime()
getUserPresetList
Returns a list of all available user presets as relative path.
Engine.getUserPresetList()
getVersion
Returns the product version (not the HISE version!).
Engine.getVersion()
getWavetableList
Returns the list of wavetables of the current expansion (or factory content).
Engine.getWavetableList()
getZoomLevel
Returns the current Zoom Level.
Engine.getZoomLevel()
isControllerUsedByAutomation
Checks if the given CC number is used for parameter automation and returns the index of the control.
Engine.isControllerUsedByAutomation(int controllerNumber)
isHISE
Returns true if the project is running inside HISE. You can use this during development to simulate different environments.
Engine.isHISE()
isMpeEnabled
Checks if the global MPE mode is enabled.
Engine.isMpeEnabled()
isPlugin
Returns true if running as VST / AU / AAX plugin.
Engine.isPlugin()
isUserPresetReadOnly
Checks if the user preset is read only.
Engine.isUserPresetReadOnly(var optionalFile)
loadAudioFileIntoBufferArray
Loads a file and returns its content as array of Buffers.
Engine.loadAudioFileIntoBufferArray(String audioFileReference)
loadAudioFilesIntoPool
Calling this makes sure that all audio files are loaded into the pool and will be available in the compiled plugin. Returns a list of all references.
Engine.loadAudioFilesIntoPool()
loadFont
Loads a font file. This is deprecated, because it might result in different names on various OS. Use loadFontAs() instead.
Engine.loadFont( String fileName)
loadFontAs
Loads the font from the given file in the image folder and registers it under the fontId. This is platform agnostic.
Engine.loadFontAs(String fileName, String fontId)
This call pulls a font from the Images
folder and gives it a FontID (string) reference that you can use later on.
{PROJECT_FOLDER} refers to the root of the projects Images folder. Just put your font there, or in a subfolder like in this example (fonts/).
Engine.loadFontAs("{PROJECT_FOLDER}fonts/Nunito-Regular.ttf", "nunito");
loadFromJSON
Imports a JSON file as object.
Engine.loadFromJSON(String fileName)
loadImageIntoPool
Loads an image into the pool. You can use a wildcard to load multiple images at once.
Engine.loadImageIntoPool( String id)
loadNextUserPreset
Loads the next user preset.
Engine.loadNextUserPreset(bool stayInDirectory)
loadPreviousUserPreset
Loads the previous user preset.
Engine.loadPreviousUserPreset(bool stayInDirectory)
loadUserPreset
Loads a user preset with the given relative path (use /
for directory separation) or the given ScriptFile object.
Engine.loadUserPreset(var relativePathOrFileObject)
logSettingWarning
This warning will show up in the console so people can migrate in the next years...
Engine.logSettingWarning( String methodName)
matchesRegex
Matches the string against the regex token.
Engine.matchesRegex(String stringToMatch, String regex)
openWebsite
launches the given URL in the system's web browser.
Engine.openWebsite(String url)
performUndoAction
Performs an action that can be undone via Engine.undo().
Engine.performUndoAction(var thisObject, var undoAction)
This function will perform an undoable action that is defined by the function you pass in as second parameter. The function expects a single parameter that is either true
when the function should be undone or false if it needs to be performed (or "redone").
The first parameter will be used as this
object during the execution and can contain the information that the function needs in order to perform the action.
Calling this function will perform the action immediately and will add it to the undo manager that can be controlled with Engine.undo()
, Engine.redo()
.
This function can be used in order to implement more complex undoable actions than the native UI widgets provide.
Example
This example just operates on an array and changes the values inside an undoable operation.
const var myList = [1, 2, 3, 4, 5, 6];
Engine.performUndoAction({
"obj": myList, // the object that will be modified
"newValue": [3, 4, 5, 6, 7], // the new state
"oldValue": myList.clone() // the old state (we need to clone it or it will not keep the old values)
}, function(isUndo)
{
this.obj.clear();
// pick the values from the old or new state
for(v in isUndo ? this.oldValue : this.newValue)
this.obj.push(v);
});
// new state
Console.print(trace(myList));
Engine.undo();
// old state
Console.print(trace(myList));
Engine.redo();
// new state
Console.print(trace(myList));
playBuffer
Previews a audio buffer with a callback indicating the state.
Engine.playBuffer(var bufferData, var callback, double fileSampleRate)
quit
Signals that the application should terminate.
Engine.quit()
rebuildCachedPools
Rebuilds the entries for all cached pools (MIDI files and samplemaps).
Engine.rebuildCachedPools()
redo
Redo the last controller change.
Engine.redo()
reloadAllSamples
Forces a full (asynchronous) reload of all samples (eg. after the sample directory has changed).
Engine.reloadAllSamples()
renderAudio
Renders a MIDI event list as audio data on a background thread and calls a function when it's ready.
Engine.renderAudio(var eventList, var finishCallback)
saveUserPreset
Asks for a preset name (if presetName is empty) and saves the current user preset.
Engine.saveUserPreset(var presetName)
setAllowDuplicateSamples
Sets whether the samples are allowed to be duplicated. Set this to false if you operate on the same samples differently.
Engine.setAllowDuplicateSamples(bool shouldAllow)
setCompileProgress
Displays the progress (0.0 to 1.0) in the progress bar of the editor.
Engine.setCompileProgress(var progress)
setCurrentExpansion
Sets the active expansion and updates the preset browser.
Engine.setCurrentExpansion( String expansionName)
setDiskMode
Sets the Streaming Mode (0 -> Fast-SSD, 1 -> Slow-HDD)
Engine.setDiskMode(int mode)
setFrontendMacros
Enables the macro system to be used by the end user.
Engine.setFrontendMacros(var nameList)
Pass it a list of names to name the macros
const var macroNames = ["Volume", "FilterFreq", "FilterQ", "Reverb"];
Engine.setFrontendMacros(macroNames);
setGlobalFont
Sets the font that will be used as default font for various things.
Engine.setGlobalFont(String fontName)
In order to do so, put them all in a Fonts
subdirectory of the Images
folder, and access it with
javascriptEngine.loadFontAs("{PROJECT_FOLDER}Fonts/Heebo.ttf", "heebo");Engine.setGlobalFont("heebo");
setGlobalPitchFactor
Sets the global pitch factor (in semitones).
Engine.setGlobalPitchFactor(double pitchFactorInSemitones)
setHostBpm
Overwrites the host BPM. Use -1 for sync to host.
Engine.setHostBpm(double newTempo)
setKeyColour
Sets a key of the global keyboard to the specified colour (using the form 0x00FF00 for eg. of the key to the specified colour.
Engine.setKeyColour(int keyNumber, int colourAsHex)
setLatencySamples
sets the latency of the plugin as reported to the host. Default is 0.
Engine.setLatencySamples(int latency)
setLowestKeyToDisplay
Changes the lowest visible key on the on screen keyboard.
Engine.setLowestKeyToDisplay(int keyNumber)
setMaximumBlockSize
Sets the maximum buffer size that is processed at once. If the buffer size from the audio driver / host is bigger than this number, it will split up the incoming buffer and call process multiple times.
Engine.setMaximumBlockSize(int numSamplesPerBlock)
Depending on your project architecture, it might make sense to limit the maximum buffer size that will be processed by your DSP module tree.
This will not guarantee that the buffer size is always the same, but rather split up the incoming buffer into chunks of this size. So if you have a 512 audio buffer and call Engine.setMaximumBlockSize(300)
, then you will process alternating audio buffers of 300 and 212 samples.
This is the "global" variant of the container.fix_block nodes that perform this operation locally within a DSP network.
Obviously this will come with a slightly higher CPU load, but the benefits of having a defined upper limit for the buffer allows you to implement a few cross-module modulation concepts that would not be possible otherwise (as the cross-module communication usually happens once per buffer size, an update rate of 11ms eg. might not be good enough for envelope modulation signals etc).
Usually you're best bet is to not use this function until you really need it for your project to work.
setMinimumSampleRate
Sets the minimum sample rate for the global processing (and adds oversampling if the current samplerate is lower).
Engine.setMinimumSampleRate(double minimumSampleRate)
setUserPresetTagList
Sets the tags that appear in the user preset browser.
Engine.setUserPresetTagList(var listOfTags)
setZoomLevel
Sets the new zoom level (1.0 = 100%)
Engine.setZoomLevel(double newLevel)
showErrorMessage
Shows a error message on the compiled plugin (or prints it on the console). Use isCritical if you want to disable the "Ignore" Button.
Engine.showErrorMessage(String message, bool isCritical)
showMessage
Shows a message with an overlay on the compiled plugin with an "OK" button in order to notify the user about important events.
Engine.showMessage(String message)
showMessageBox
Shows a message box with an OK button and a icon defined by the type variable.
Engine.showMessageBox(String title, String markdownMessage, int type)
showYesNoWindow
Shows a message with a question and executes the function after the user has selected his choice.
Engine.showYesNoWindow(String title, String markdownMessage, var callback)
sortWithFunction
Sorts an array with a given comparison function.
Engine.sortWithFunction(var arrayToSort, var sortFunction)
uncompressJSON
Expands a compressed JSON object.
Engine.uncompressJSON( String b64)
undo
Reverts the last controller change.
Engine.undo()