HISE Docs

Engine

The Engine object contains functions related to global properties (like sample rate or host tempo).

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:

  1. Cleaner output
  2. 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)



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)



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)



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)



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()



Join Discussion Next: ErrorHandler