HALion Developer Resource

Please choose from the below to learn how to get started and find short examples and detailed information on the selected topic.

/ HALion Developer Resource /

HALion Script

Getting Started

This section provides general information about HALion Script and the Lua scripting language. Links for learning more about Lua can be found in What is HALion Script?.

Diving Deeper

This section provides information about the inner workings of HALion and its implementation of the Lua scripting language. How to protect your work is described in Protecting Layers and Managing Script Modules.

HALion Script Reference

The classes and functions of the HALion Script language are described in the Class Reference and on the Reference pages. Many of the descriptions provide small code examples. For more details, see Exploring the Code Examples.

/ HALion Developer Resource / HALion Script /

Getting Started

This section provides general information about HALion Script and the Lua scripting language.

• What is HALion Script?
• Exploring the Code Examples
• Lua Syntax Highlighting

/ HALion Developer Resource / HALion Script / Getting Started /

What is HALion Script?

On this page:

• Lua Resources
• Lua Release

HALion Script allows you to customize and expand the features of HALion to a great extent. It is a domain-specific programming language based on the Lua scripting language. It comes with many functions tailored to HALion, while maintaining the general programmability of Lua. HALion Script allows you to manipulate musical events, access and modify parameters of HALion, control the behavior of macro pages, and much more. All of this can enhance your instrument creation greatly.

Fields of application:

• Arpeggiation and sequencing
• Chord generation and recognition
• Microtonal music and alternative scales
• Algorithmic composition
• Advanced, interactive playback for creating more realistic performances
• Custom-built workflows for macro pages
• Automization of repeating tasks while building large-scale libraries

Jump to Top

Lua Resources

Lua is a very common scripting language, used in many professional fields, such as game development or image processing, for example. To find out more about Lua, please visit lua.org. For learning Lua, we recommend the official book Programming in Lua and Lua's Reference Manual.

Jump to Top

Lua Release

HALion Script uses Lua 5.2.3 with the following standard libraries:

• basic library
• package library
• string manipulation
• table manipulation
• mathematical functions
• bitwise operations
• input and output facilities
• operating system facilities
• debug facilities

❕ The standard library coroutine is not supported. Furthermore, the functions io.popen, io.tmpfile, os.execute, os.exit, os.getenv, os.setlocale and os.tmpname are not supported.

The classes and functions of the HALion Script language are described in the Class Reference and on the Reference pages. Many of the descriptions provide small code examples. For more details, see Exploring the Code Examples.

Jump to Top

/ HALion Developer Resource / HALion Script / Getting Started /

Exploring the Code Examples

On this page:

• Program for Code Examples
• Loading the Code Examples

Many of the classes and functions that are are described in the Class Reference and on the Reference pages provide working code examples. The code examples use syntax highlighting. Comments are displayed in green, functions in magenta and values in blue, for example. See Lua Syntax Highlighting for more details.

Example

-- "Hello world!" Lua script

print("Hello world!")

The easiest way to explore the code examples is to copy the code to the clipboard and to paste it to the internal script editor of the Lua Script MIDI module. Please read on for information on how to do this.

Jump to Top

Program for Code Examples

If not stated otherwise, the following simple program will be sufficient for exploring the code examples in HALion.

1. Download the program Explore Code Examples.vstpreset
2. Drag the program to the Slot Rack.

To create the program manually, proceed as follows:

1. Select an empty program in the Program Table.
2. In the Program Tree, click Create New MIDI Module and select Lua Script.
3. In the Program Tree, click Create New Zone and select Synth Zone.
4. Load the program to the Slot Rack.

This is how your program should look like in the Program Tree.

Jump to Top

Loading the Code Examples

The program described above should be loaded in the Slot Rack.

1. Open a page with a code example, for example, onNote.
2. Double-click the code example to select all lines and press Ctrl/Cmd-C to copy the code to the clipboard.
3. Go to HALion and select Lua Script in the Program Tree.
4. Open the section for the Lua Script MIDI module, either in the Sound editor or in the MIDI Modules editor.
5. Click Edit Script to open the internal Script Editor.
6. Click the Script Editor window to bring it to focus and press Ctrl/Cmd-V to paste the code from the clipboard.
7. Click OK to activate the script.

Depending on the code example, you usually have to play a note or send a MIDI controller to get a sound or output message from the script. Typically, the description of the feature and the comments in the code will give you enough hints on what to do. In the example above, onNote prints the note ID, the MIDI note number and the MIDI velocity each time you play a note.

Jump to Top

/ HALion Developer Resource / HALion Script / Getting Started /

Lua Syntax Highlighting

The following pseudo code examplifies the Lua syntax highlighting used throughout this documentation.

--single line comment
  
--[[
    block comment
--]]
  
--keywords
and       break     do        else      elseif    end
false     for       function  goto      if        in
local     nil       not       or        repeat    return
then      true      until     while
  
--strings
a = 'alo\n123"'
a = "alo\n123\""
a = '\97lo\10\04923"'
a = [[alo
123"]]
a = [==[
alo
123"]==]
  
--numbers
3     3.0     3.1416     314.16e-2     0.31416E1
0xff  0x0.1E  0xA23p-4   0X1.921FB54442D18P+1
  
--functions
print(a)
print("Hello")
print(123)
  
for k,v in ipairs(t)
    print(v)
end

Keywords, strings and numbers extracted from Lua's Reference Manual, Chapter 3 - The Language.

/ HALion Developer Resource / HALion Script /

Diving Deeper

This section provides information about the inner workings of HALion and its implementation of the Lua scripting language. How to protect your work is described in Protecting Layers and Managing Script Modules.

• Working with Objects
• Working with UI Scripts
• Threads in HALion
• Script Initialization
• Creating Parameters
• Working with Parameters
• Using Slot Local Variables
• Protecting Layers
• Managing Script Modules
• Using External Files
• Debugging with LDT

/ HALion Developer Resource / HALion Script / Diving Deeper /

Working with Objects

On this page:

• Objects and Classes
• Class Reference
• Addressing Objects
• Calling Methods
• Using type() on Objects

In the HALion Script language, elements that make up the program, MIDI and note expression events, the definitions of parameters, etc., are all represented by objects. HALion Script provides dedicated functions for modifying these objects. To understand the principles of writing scripts that operate on objects, some terminology from object-oriented programming will be helpful.

Objects and Classes

Object-oriented programming (OOP) is a style of programming based on the concept of objects. In OOP objects are organized in classes. A class provides data fields and methods for an object. The data fields describe what the object is and the methods describe what it can do. A concrete occurance of an object is called an instance. The elements in the Program Tree are instances of different types of objects, for example, Bus objects, Layer objects, Zone objects, etc. MIDI and note expression events are represented by Event objects and each parameter has a ParameterDefinition object.

Class Reference

The classes/objects of the HALion Script language are structured in the following class hierarchy.

HALion Script Class Hierarchy

• Audio File
• Element
  • Bus
  • Effect
  • Instance
  • Layer
    • Program
  • MidiModule
  • ModulationMatrixRow
  • Slot
  • Zone
• Event
• LoadProgress
• ParameterDefinition

Classes deeper down inherit the data fields and methods of classes higher up in the class hierarchy. For example, the classes Bus, Instance, Layer, Effect, and so on, inherit all data fields and methods of the Element class. Subclasses add functionality to their parent class by providing more data fields and methods.

Addressing Objects

The Lua Script MIDI module itself can be addressed with this. Further objects can be addressed with this.parent, this.program or with the respective 'get' and 'find' functions.

After addressing an object, you can read its fields through dot-notation. In the following example, the name and the type of different objects are printed with .name and .type.

Example 1

-- Print the name and type of different objects.

print(this.name, this.type)
print(this.parent.name, this.parent.type)
print(this.program.name, this.program.type)
print(this.program:getChild().name, this.program:getChild().type)

Calling Methods

To operate on an element in the Program Tree, you must first address its object and then call the desired method. The basic syntax is as follows:

object:method()

Example 2

-- Get the object of the first Zone after the script module.

zone = this.parent:getZone()

-- setName operates on the Zone object.

zone:setName("MyZone")

Using type() on Objects

For the HALion Script language the type() function of Lua has been extended to return the type of an object.

Example 3

-- Print the name of all zones in the program.

elements = this.program:findChildren(true)

for i, element in ipairs(elements) do
    if type(element) == "Zone" then
        print(element.name)
    end
end

/ HALion Developer Resource / HALion Script / Diving Deeper /

Working with UI Scripts

On this page:

• Executing UI Scripts
  • Show/Hide Output Messages
• Addressing the Elements of the Program

Related pages:

• steinberg.help / MIDI Modules Reference / Lua Script

HALion offers two types of scripts:

UI scripts have the following restrictions:

• UI scripts are only executed when the UI is open. If the UI is closed, the UI script is not executed anymore.
• The parameters defined in a UI script cannot be automated.

❕ MIDI module scripts do not have these restrictions. Therefore, be sure to check if UI scripts are required for a specific task, and if not, use MIDI module scripts instead.

Executing UI Scripts

You can execute UI scripts for the macro page and even for each template. The Script section can be found in the Properties section in the lower left of the Macro Page Designer. Just as with the Lua Script MIDI Module, you can write your scripts with the internal editor or an external editor. See steinberg.help / MIDI Modules Reference / Lua Script for more details.

1. In the GUI Tree of the Macro Page Designer, select the element that has the macro page attached. Alternatively, select a control element, then go to the Show Templates tab and click Edit Element.
2. In the Properties section in the lower left of the Macro Page Designer, go to the Script section.
3. Click Edit Script to open the internal Script Editor, then enter your script and press OK. Alternatively, click Load Script and select a script file from disk.

Show/Hide Output Messages

The Output Messages section for the UI scripts is hidden by default.

• In the toolbar of the Macro Page Designer, click Show/Hide Script Output Messages to show or hide the Output Messages below the Resource / Library Browser.

The Output Messages section displays the messages of all UI scripts. The UI script the message belongs to is indicated by a prefix.

Addressing the Elements of the Program

A UI script cannot address the elements of a program directly. To address a program and its elements from the UI script, you must use getElement.

Example

-- Must be executed as UI script!
-- Print the name and type of the element that has the macro page attached.

element = getElement()
print(element.name, element.type)

-- Print the name and type of the parent element.

if element.parent then
    print(element.parent.name, element.parent.type)
end

/ HALion Developer Resource / HALion Script / Diving Deeper /

Threads in HALion

On this page:

• Script Error - Wrong Thread
• Using runAsync
• Using runSync

HALion provides two threads:

• Parameter changes and the storage of them are handled by the Controller thread.
• MIDI event processing and sound reproduction happen in the Processor thread.

You can think of these threads as two sections of code that are exectued in concurrency by HALion. Basically, the two threads are needed to separate longer-lasting function calls from timing-critical function calls. The functions that are called in the Controller thread are executed only as fast as required, while the functions that are called in the Processor thread are executed within an ASIO block.

The information whether a function can be called in the Controller thread, the Processor thread, or in both threads, can be found on the Reference pages below the description of each function.

It looks like this:

Available in: Controller, Processor.

Script Error - Wrong Thread

If you call a function in the wrong thread, the script module will output an error message.

Example 1

--[[
  Example for a script error when calling a function in the wrong thread.
  The onNote callback runs in the Processor thread. openURL runs in the Controller thread.
  Therefore, openURL cannot be called in onNote. The script produces a script error when playing a note.
--]]
 
function onNote(event)     
  openURL("http://www.steinberg.net/en/home.html")
end

The output message for the script error of the above example looks like this:

If this ever happens to you, please review your code and try to place the function call elsewhere in your script. Alternatively, you could use runAsync.

Using runAsync

By calling runAsync in the Processor thread you can invoke a function that is executed in the Controller thread. The execution of runAsync takes at least one audio block, or longer, depending on the function that was called. Please note that when using runAsync, the callback that called runAsync is put on hold until the function has completed.

Example 2

-- Using runAsync to call openURL within onNote.
 
function onNote(event)
  runAsync(function() openURL("http://www.steinberg.net/en/home.html") end)
end

Using runSync

By calling runSync in the Controller thread, you can invoke a function that is executed in the Processor thread. For example, by calling runSync in a parameter change callback, you can invoke an event function like playNote, releaseVoice, controlChange, etc. The callback that called runSync is not stopped and continues its execution. The specified function will be exectued in the next audio block.

-- Fade all voices, triggered by a script parameter.

defineSlotLocal("noteIDs")
noteIDs = {}
  
function onNote(event)
  local id = postEvent(event)
  table.insert(noteIDs, id)
end
  
function syncFadeAllVoices()
  for i, id in ipairs(noteIDs) do
      fade(id, nil, 0, 1000, true)
  end
  noteIDs = {}
end
  
function fadeAllVoices()
  if fadeVoices then
    runSync(syncFadeAllVoices, 1)
  end
end
  
defineParameter("fadeVoices", "Fade All Voices", false, fadeAllVoices)

/ HALion Developer Resource / HALion Script / Diving Deeper /

Script Initialization

When a program with a script is loaded into the Slot Rack, the global statements, all parameters and the onLoad, onLoadIntoSlot and onInit callbacks must be initialized. The order is as follows:

For more details about threads, see Threads in HALion.

Example

-- Script for testing the initialization when loading a program into the Slot Rack.
 
function onInit()
  print("onInit")  -- This is printed last, after onLoadIntoSlot.
end
 
function onLoadIntoSlot()
  print("onLoadIntoSlot")  -- This is printed after onLoad.
end
 
function onLoad()
  print("onLoad")  -- This is printed after the global statement.
end
 
print("Global statement") -- This is printed first.

/ HALion Developer Resource / HALion Script / Diving Deeper /

Creating Parameters

On this page:

• Defining Parameters
• Parameters vs. Global Variables
• Parameter Characteristics
  • Numeric
  • Indexed String Array
  • Boolean
  • String
  • Table
  • By Parameter Definition
  • By Named Arguments
• Parameter Change Callback
• Change Callback with Anonymous Function
• Defining Parameters by Named Arguments
• Additional Named Arguments

You need parameters to connect the script module with controls on the macro page and to save the script module's state with the program. Before you can connect your script module with controls on a macro page, you must specify the parameters that you want to use in your script by calling the function defineParameter for each of them. Once a parameter is defined, it is shown in the Parameter List. From this list, you can then connect it with a control on the macro page. When you save the program, the parameters that you defined for the script module are saved with it.

The function defineParameter also creates a global variable that represents the value of the parameter in the script. You can use this global variable like any other variable in the script (see Parameter vs. Global Variables for details).

Defining Parameters

defineParameter(name)

You define a parameter by calling the function defineParameter with at least its name as the first argument. This name serves as name for the parameter in the Parameter List and as name for the global variable that represents the parameter in the script. The additional arguments of defineParameter are optional and can be used to change the characteristics of the parameter (see Parameter Characteristics for details). If no further arguments are defined, the parameter will be a floating point value in the range from 0 to 100.

Jump to Top

Parameters vs. Global Variables

The function defineParameter creates a global variable that represents the value of the parameter in the script. It should be noted that:

• The rules for the naming and scope of global variables also apply for parameters.
• You can change the value of a parameter by assigning a new value to the corresponding global variable.
• The parameters that you defined for your script module are saved with the program, as opposed to global variables, which are not saved automatically.

The following example shows that parameters can be used just like global variables. After the parameter Scale has been defined, it is used to replace the note-on velocity. The value of Scale is changed by assigning the value of the last incoming MIDI controller to it.

Example 1

-- Change the parameter Scale through a MIDI controller and use its value to replace the note-on velocity.
 
-- Initialize variables.

min = 0
max = 100
maxVel = 127
defVel = 100
default = defVel / maxVel * max
maxCC = 127
 
-- Define Scale using the previous variables.

defineParameter("Scale", nil, default, min, max)
 
-- Use the value of Scale to replace the note-on velocity.

function onNote(event)
    event.velocity = maxVel * Scale / max
    postEvent(event)
end
 
-- Change the value of Scale through the last incoming MIDI controller.

function onController(event)
    Scale = event.value / maxCC * max
end

Jump to Top

Parameter Characteristics

How a parameter behaves depends on its characteristics. You determine the characteristics of a parameter with the arguments of defineParameter. To create a parameter with specific characteristics, the arguments must be set in the order in which they are shown in the following syntax examples.

Numeric

defineParameter(name, longName, default, min, max, increment, changeCallback)

Creates a numeric parameter. The default argument defines the value that the parameter will default to. The min and max arguments define the value range of the parameter. The increment argument defines the step size in which the parameter value can be adjusted. The arguments default, min, max and increment can be any integer or floating point value. How many digits are shown after the decimal point for a value string of a parameter is determined by the value of the increment argument. For example:

The automatic formatting of a value can be overridden with the format argument. See Additional Named Arguments for more details.

Indexed String Array

defineParameter(name, longName, default, strings, changeCallback)

Creates a parameter with integer indices that have a text representation given by the string values of an array. The default argument defines the index value that the parameter will default to. The strings argument must be an array with string values starting with index 0 or 1.

Boolean

defineParameter(name, longName, bool, changeCallback)

Creates a boolean parameter. The bool argument also defines the default value of the parameter.

String

defineParameter(name, longName, string, changeCallback)

Creates a parameter with a string value. You can change the string by assigning a new string value to the parameter.

Table

defineParameter(name, longName, table, changeCallback)

Creates a parameter with a table as value. The name argument of the parameter also defines the name of the table. You can access the values of the table using the regular methods, e.g., dot notation.

By Parameter Definition

defineParameter(name, longName, parameterDefinition, changeCallback)

Creates a parameter with the behavior of the specified ParameterDefinition. You can use this to clone the behavior of existing parameters.

By Named Arguments

defineParameter { name = "p", longName = "param", default = 0, min = 0, max = 100, increment = 0.01, onChanged = callback, type = "float", format = "%.2f", readOnly = false, writeAlways = false, automatable = true, persistent = true }

Creates a parameter by named arguments. The only argument to the function is a table with the key/value pairs that define the parameter. The additional keys type, format, readOnly, writeAlways, automatable, processorCallback and persistent give you control over more advanced features. They can only be set with named arguments. See Defining Parameters by Named Arguments for more details.

Example 2

-- Showcase different parameters.
 
-- Initialize variables.

maxVelocity = 127
 
-- Change callback of the parameter "Label".

function nameChanged()
    print("name changed to", Label) --Print the value of the parameter.
end
 
-- Initialize parameters.

defineParameter("Scale", nil, 100)                                          -- Parameter with default 100 and range 0 to 100.
defineParameter("Offset", nil, 0, -100, 100, 1)                             -- Bipolar parameter with integer steps.
defineParameter("Pan", nil, 0, -100, 100, 0.1)                              -- Bipolar parameter with 0.1 steps.
defineParameter("Mode", nil, 1, { "Off", "Normal", "Hyper" })               -- Indexed string array.
defineParameter("Enable", "Enable Filter", true)                            -- Switch with long name.
defineParameter("Label", nil, "untitled", nameChanged)                      -- String parameter.
defineParameter("Intervals", nil, { 0, 4, 7 })                              -- Table parameter.
defineParameter("Volume", nil, this.parent:getParameterDefinition("Level")) -- Parameter with the same behavior as the "Level" parameter of the parent layer.

-- Use the parameters Scale and Intervals to play a chord with fixed velocity.

function onNote(event)
    fixedVelocity = maxVelocity * Scale / 100
    local id1 = playNote(event.note + Intervals[1], fixedVelocity)
    local id2 = playNote(event.note + Intervals[2], fixedVelocity)
    local id3 = playNote(event.note + Intervals[3], fixedVelocity)
end

Jump to Top

Parameter Change Callback

The change callback is only called if the value of the parameter was changed on the user interface, e.g., by adjusting the corresponding control on the macro page, or by calling setParameter. It is not called if the value was changed by assigning a value from inside the script. The following example revisits Example 1 to demonstrate this:

Example 3

-- Change the parameter Scale through MIDI controller and use its value to replace the note-on velocity.
-- The current value of Scale is printed only if changed from UI, e.g., go to the Parameter List to adjust Scale
 
-- Initialize variables.

min = 0
max = 100
maxVel = 127
defVel = 100
default = defVel / maxVel * max
maxCC = 127
 
-- This callback function will only be called if you adjust Scale from the UI.

function valueChanged()
    print("Value of Scale changed to:", Scale)
end
 
-- Define Scale with the previous variables.

defineParameter("Scale", nil, default, min, max, valueChanged)
 
-- Use the value of Scale to replace the note-on velocity.

function onNote(event)
    event.velocity = maxVel * Scale / max
    postEvent(event)
end
 
-- Change the value of Scale through the last incoming MIDI controller.

function onController(event)
    -- Assigning a value to Scale will not call the callback function.
    Scale = event.value / maxCC * max
end

Jump to Top

Change Callback with Anonymous Function

In Example 2, the function nameChanged is declared before the associate parameter is defined. This is necessary for defineParameter in order to detect that the argument nameChanged is a function. If you want to declare the callback function after defining the corresponding parameter, you must call the callback function within an anonymous function. As the name suggests, an anonymous function is a function without a name.

Example 4

-- Define a string parameter.

defineParameter("Name", nil, "untitled", function() nameChanged() end)

-- If nameChanged is called inside an anonymous function, it can be declared after defineParameter.

function nameChanged()
    print("name changed to", Name) -- Print the value of the parameter.
end

Jump to Top

Defining Parameters by Named Arguments

When calling defineParameter with several arguments, the arguments are matched by their position and the associated values are passed on to the function. For this reason, the arguments of defineParameter must match the exact order and position when calling the function. Alternatively, you can set the arguments with the keys and values of a table. This method of passing arguments and values to a function is called named arguments.

Named arguments have the advantage that they can be set in any order and that optional or additional arguments can be left out without destroying the predefined order and position of the arguments of that function. The following example shows the parameters from Example 2 created with named arguments.

Example 5

-- Different parameters created with named arguments.
 
-- Change callback of the parameter "Label".

function nameChanged()
    print("name changed to", Label) --Print the value of the parameter.
end
 
-- Parameter with default 100 and range 0 to 100.

defineParameter{
    name = "Scale",
    default = 100
}
 
-- Bipolar parameter with integer steps.

defineParameter{
    name = "Offset",
    default = 0,
    min = -100,
    max = 100,
    increment = 1,
}
 
-- Bipolar parameter with 0.1 steps.

defineParameter{
    name = "Pan",
    default = 0,
    min = -100,
    max = 100,
    increment = 0.1,
}
 
-- Indexed string array.

defineParameter{
    name = "Mode",
    default = 1,
    strings = { "Off", "Normal", "Hyper" },
}
 
-- Switch with long name.

defineParameter{
    name = "Enable",
    longName = "Enable Filter",
    default = true,
}
 
-- String parameter.

defineParameter{
    name = "Label",
    default = "untitled",
    onChanged = nameChanged,
}
 
-- Table parameter.

defineParameter{
    name = "Intervals",
    default = { 0, 4, 7 },
}

❕ Creating a parameter by ParameterDefinition is not supported when using named arguments.

Jump to Top

Additional Named Arguments

(Since HALion 6.1)

If you create a parameter by named arguments, you get access to these additional arguments:

The arguments readOnly, writeAlways and automatable are usepful if you have a parameter that is used only for indication, but not for entering values.

Example 6

-- The following parameter is read only, not automatable and not persistent.

defineParameter {
    name = "deltaTime",
    longName = "Delta Time",
    default = 0,
    min = 0,
    max = 2^31,
    type = "float",
    format = "%.3f ms",
    readOnly = true,
    automatable = false,
    persistent = false,
}
   
-- Measure the time between subsequent notes.

function onNote(event)
    postEvent(event)
    t2 = getTime()
    if t1 then
        deltaTime = t2 - t1
    end
    t1 = t2
end
 
-- The following parameter change callback is executed in the processor context with high accuracy.

function onP1changed()
   this.parent:setParameterNormalized("Level", P1 / 100)
end
 
defineParameter{name = "P1", min=0, max=100, onChanged = onP1changed, processorCallback = true}

Jump to Top

/ HALion Developer Resource / HALion Script / Diving Deeper /

Working with Parameters

On this page:

• Properties of Parameters
• Addressing Parameters
  • Addressing Parameters by Name
  • Addressing Parameters by ID
• Using setParameter

Properties of Parameters

Every parameter has a ParameterDefinition object that describes the properties of a parameter. For example, you can retrieve the minimum, maximum, or default value of a parameter by reading the corresponding fields of the ParameterDefinition object (see getParameterDefinition for details). The fields of the ParameterDefinition object can only be read and not be modified.

The actual value of a parameter is not part of the ParameterDefinition object. It can be modified using the functions getParameter and setParameter or getParameterNormalized and setParameterNormalized.

Addressing Parameters

Functions like getParameter, setParameter or getParameterDefinition address the desired parameter by its name or ID.

Addressing Parameters by Name

Please do not mix up the parameter's label on the UI with its name in the engine. Sometimes, the label and the name of a parameter are the same, but most of the time they are different.

❕ Throughout this documentation "name of parameter..." refers to its name in the engine and not its label on the UI.

The name of a parameter can be found in HALion's Parameter List. The Parameter List gives you a detailed overview of the parameters of the currently selected element in the Program Tree. The following screenshot shows parts of the parameters of a zone.

The Parameter column lists the names of the parameters. Parameters that belong together can be grouped into functional sections, represented by the folders in the Parameter column.

• Parameters that do not belong to a section can be addressed directly. In the screenshot above, "UserAttOffset" addresses the attack offset of the user envelope in the zone, for example.
• Parameters that belong to a section need the name of the section as prefix, for example, the shape parameter of LFO 1 in the zone has the name "LFO 1.Shape".

Example 1

function onLoadIntoSlot()
  local zones = this.program:findZones(true)
  if zones[1] then
    print("LFO 1.Shape: "..tostring(zones[1]:hasParameter("LFO 1.Shape")))
    print("lfo 1.shape: "..tostring(zones[1]:hasParameter("lfo 1.shape")))
  end
end

❕ Addressing a parameter by its name is case sensitive.

Addressing Parameters by ID

The ID of a parameter can also be found in the Parameter List. By default, the Parameter List does not show the ID.

• To add the ID column to the Parameter List, right-click a column header and select ID (Dec).

The ID of "LFO 1.Shape" is 65542, for example.

Example 2

local lfo1ShapeID = 65542
function onLoadIntoSlot()
  local zones = this.program:findZones(true)
  if zones[1] then
    print("LFO 1.Shape: "..tostring(zones[1]:hasParameter(lfo1ShapeID)))
  end
end

Addressing parameters by name needs more computing time and might be a disadvantage for timing critical scripts. To optimize your script, you can read the ID of a parameter with getParameterDefinition during the initialization of the script and use this instead.

Example 3

-- Read the ID of the parent layer's level parameter.

local paramID = this.parent:getParameterDefinition("Level").id
 
-- Print the value of the parent layer's level parameter with each note-on.

function onNote(event)
    postEvent(event)
    print("Level = "..this.parent:getParameter(paramID))
end

Using setParameter

The functions setParameter and setParameterNormalized address parameters also by name or ID.

Example 4

-- Set the value of the Level parameter of the parent layer.

function onLoadIntoSlot()
    this.parent:setParameter("Level", 0) -- set via name
    this.parent:setParameter(38, 0) -- set via ID
end

/ HALion Developer Resource / HALion Script / Diving Deeper /

Using Slot Local Variables

If a program is loaded in several slots, the state of its parameters (e.g., level, cutoff, resonance, etc.) is synchronized across these slots. The same is true for the state of global variables in a Lua script. If a global variable is changed in one slot, its state will change in every other slot where the program is loaded.

However, the engine's playback state of the program is handled independently for each slot. This is necessary because each slot can receive different MIDI events. If some functions in your script depend on global variables that store the state of MIDI events, the automatic synchronization of global variables is usually a hindrance, because the global variables will be overwritten by the slot that received the latest MIDI events. To attain global variables that operate independently per slot, use slot local variables by calling defineSlotLocal.

Declaring Slot Local Variables

You declare slot local variables by calling defineSlotLocal with the name of the corresponding global variable as argument. You can call defineSlotLocal before or after the initialization of the variable, but it is common practice to call the function in advance.

Example

The following example plays a classic up arpeggio. The variables for the arpeggio (noteBuffer, arpRunning and arpeggioNotes) need to be declared as slot local variables, otherwise, the script will not work as expected if the program is loaded into more than one slot.

To explore the script:

1. Download SlotLocalVariables.vstpreset.
2. Load the program twice into the Slot Rack and send different chords to the slots.
3. Comment out the declaration of the slot local variables and send different chords to the slots again.

If slot local variables are declared, both slots play separate arpeggios. If slot local variables are not declared, only one slot will play an arpeggio with a mix of the chords that you are sending to the slots.

--[[
    Simple arpeggiator playing 1/16 notes with fixed velocity.
    The global variables noteBuffer, arpRunning and arpeggioNotes use defineSlotLocal.
--]]
 
-- Global statements.
 
-- Declare slot local variables.

defineSlotLocal("noteBuffer")
defineSlotLocal("arpRunning")
defineSlotLocal("arpeggioNotes")
 
-- Initialize variables.
-- Set note length to 1/16, i.e., one beat divided by four.

noteLength = 0.25

-- Set a fixed velocity of 100.

fixedVelocity = 100

-- Buffer for held notes.

noteBuffer = {}

-- Playback state of the arpeggiator.

arpRunning = false
 
-- Transfer the held notes into an array and sort its values.

function sortNotes()
    arpeggioNotes = {}
    for note in pairs(noteBuffer) do
        arpeggioNotes[#arpeggioNotes+1] = note
    end
    table.sort(arpeggioNotes)
end
 
-- Play up arpeggio.

function playArpeggioUp()
    arpRunning = true
    -- Start playback with index 1.
    local i = 1
    -- Playback for as long as there are arpeggio notes.
    while arpeggioNotes[i] do
        local id = playNote(arpeggioNotes[i], fixedVelocity, 0)
        wait(getBeatDuration() * noteLength * 0.5)
        -- Release the current voice after half the note length.
        releaseVoice(id)
        wait(getBeatDuration() * noteLength * 0.5)
        -- Increase index by 1 to play the next note.
        i = i + 1
        -- Reset playback to index 1, if index out of range.
        if not arpeggioNotes[i] then
            i = 1
        end
    end
    arpRunning = false
end
 
function onNote(event)
    -- Write notes to the buffer.
    noteBuffer[event.note] = event.velocity
    sortNotes()
    -- Start the arpeggio only if it is not running.
    if arpRunning == false then
        playArpeggioUp()
    end
end
 
function onRelease(event)
    -- Remove notes from the buffer.
    noteBuffer[event.note] = nil
    sortNotes()
end

/ HALion Developer Resource / HALion Script / Diving Deeper /

Protecting Layers

On this page:

• Using Layer Protection
  • Setting the Layer Protection
  • Applying the Layer Protection Automatically
  • Applying the Layer Protection Manually
• Accessing Protected Layers from a Script

Related pages:

• addLayerPassword
• Managing Script Modules

You might want to avoid that users make edits to critical parts of the program. Moreover, how you built a program for your instrument might be a considerable part of your intellectual property. To safeguard the program and your work, you can protect the layers to which the users should not have access.

Using Layer Protection

Protecting layers is a two-step process:

• First, you define the layers you want to protect by setting the Layer Protection in the Program Tree. This has the advantage that you can decide at an early stage which layers you want to be protected. You can continue your work as usual and you still can add or remove the protection as needed. The permanent activation of the layer protection happens later.
• Before you release the instrument to the public, you export the program and apply the protection by using Export Program as VST3 Preset... with the Protect option activated. All layers for which the layer protection is set will be permanently protected in the exported program.

❕ Applying the layer protection permanently by exporting a protected VST 3 preset cannot be undone. For this reason, you should always keep a backup of the unprotected program.

Setting the Layer Protection

1. In the Program Tree, right-click the column header and select Layer Protection. The column for setting the layer protection is added to the Program Tree. An open lock icon is displayed next to each layer, indicating that the layers are not protected yet.
2. Click the lock icon for the layer that you want to protect. A dialog opens where you can enter the password for the layer protection.
3. Enter a password in the text field. You must enter a password each time you protect a layer. You are free to use the same or different passwords for each of the layers.
4. Click OK to engage the layer protection.

The Layer Protection is engaged if a closed lock icon is displayed next to the layer. If a child layer is protected through a parent layer, its lock will turn light gray to indicate this. To disengage the Layer Protection, click the closed lock icon of a layer, so that an open lock icon is shown. This also resets the password of the layer. To apply the Layer Protection permanently, you must build a library or export a protected version of the program or layer.

Applying the Layer Protection Automatically

The Library Creator protects layers with activated protection automatically when building a VST Sound. This only affects the presets that go into the VST Sound container – not your source presets on disk. Using the Library Creator is the preferred way to protect layers permanently for release.

1. Set the Layer Protection as described above.
2. In the Library Creator, add the respective presets to your library.
3. Build the library and mount it.
4. Go to the MediaBay and load a preset from the library.

Notice how the protected layers cannot be accessed in the Program Tree any longer.

Applying the Layer Protection Manually

❕ Applying the layer protection cannot be undone. Please keep a backup of the unprotected program if you need to edit the layers at a later stage.

1. Right-click in the Program Tree and go to the Import/Export submenu.
2. Select Export Program as VST3 Preset...
3. Activate the Protect option.
4. Choose a location and file name.
5. Click Save to export the program and apply the layer protection permanently.

When you load the exported program, the protected layers cannot be accessed in the Program Tree any longer.

Accessing Protected Layers from a Script

By default, protected layers cannot be accessed by scripts. The parameters of a protected layer and any elements inside of it are hidden for scripts. This avoids unauthorized parsing of the Program Tree to retrieve hidden information. A script can access protected layers only by calling the function addLayerPassword with the correct password for the corresponding layers.

Example

-- Access the protected layer(s) which have the password "abc123".

addLayerPassword("abc123")

❕ To hide the password in addLayerPassword, you must also protect the script module. See Managing Script Modules for details.

/ HALion Developer Resource / HALion Script / Diving Deeper /

Managing Script Modules

On this page:

• Saving Modules
• Deleting Modules
• Protecting Modules
  • Using Protect Module

Related pages:

• Protecting Layers

You can add your script module to the MIDI module library by saving it as a MIDI module. Script modules that have been saved as MIDI modules behave like the factory MIDI modules and can be loaded with Create New MIDI Module.

Saving Modules

1. In the Program Tree, right-click the script module that you want to save.
2. On the MIDI Module Library submenu, select Save Module...
3. In the file dialog, enter a name for the module and click Save.

Deleting Modules

1. Right-click in the Program Tree.
2. On the MIDI Module Library submenu, select Delete Module...
3. Select the module that you want to delete and click Yes to confirm.

Protecting Modules

If you want to prevent others from viewing or changing the sources of your script module, you can protect the module with the Protect Module command.

Protecting a script module has the following effects:

• The source files for the script module cannot be edited anymore. This includes the script itself and any sources for the MacroPage of the module.
• The sections for source files and output messages will be hidden in the editor and cannot be accessed anymore.

Using Protect Module

1. In the Program Tree, right-click the script module that you want to protect.
2. On the MIDI Module Library submenu, select Protect Module. At this point, you can still revert the protection with the undo command of the history.
3. To protect the script module permanently, open the MIDI Module Library submenu and select Save Module... The next time you load the module, it will be protected. Alternatively, you can save the program together with the module.

❕ The protection of permanently protected modules cannot be undone. Make sure that you have an unprotected backup of the script module and its sources if you need to edit them at a later stage.

/ HALion Developer Resource / HALion Script / Diving Deeper /

Using External Files

(Since HALion 7.0)

The functions of the i/o and os libraries of Lua allow you to manipulate external files. External files are files that are managed by the operating system. For example, while developing large scale sample instruments, it can be helpful to read or write files with comma separated values (.csv). To protect private data, the location for reading and writing files is limited to the folders ./Documents/Steinberg and ./Documents/tmp of the user. In addition, you can read files from the VST sound that contains the executed script. Lua's i/o functions allow you to manipulate files. The functions os.remove and os.rename from the os library allow you to delete or rename files. See Input and Output Facilities and Operating System Facilities for a description of the respective functions.

❕ The functions io.popen, io.tmpfile, os.execute, os.exit, os.getenv, os.setlocale and os.tmpname are not supported.

Retrieving the File Path of ./Documents/Steinberg

You can use the function getUserSubPresetPath to retreive the file path of ./Documents/Steinberg on your system.

Example

-- Retrieve ./Documents/Steinberg/ and try to open a file.

fileLocation = getUserSubPresetPath()
posStart, posEnd = string.find(getUserSubPresetPath(), "Steinberg/")
fileLocation = string.sub(fileLocation, 1, posEnd)
 
io.input(fileLocation.."some.txt")

/ HALion Developer Resource / HALion Script / Diving Deeper /

Debugging with LDT

On this page:

• Installing LDT
• Setting Up a Debug Session
  • Starting LDT
  • Selecting a Workspace
  • Creating a Project
  • Configuring Attach Debug
  • Changing the Debug Port on Mac
• Starting a Debug Session
  • Loading the Code Example
  • Opening the Debug Perspective
  • Connecting the Lua Script module with LDT
• Stopping a Debug Session
• Using the LDT Debugger

External links:

• Eclipse LDT
• Java SE 8 JRE
• Java SE 8 JDK
• Debugging a Lua program

HALion uses Lua Development Tools (LDT) by Eclipse Foundation as the front end for debugging. LDT is an open source software for Windows and Mac OSX that provides you with an integrated development environment (IDE) for Lua with tools like code assistance, debugging, syntax coloring, code formatting, and many more. LDT allows you to debug scripts that run in HALion. After configuring Attach Debug in LDT, you can connect a Lua Script module for debugging its script. In LDT, you can monitor the script step by step, inspect variables and evaluate expressions. This way, you can identify and remove errors from your script more easily.

More information about LDT and support from the Eclipse community can be found here:

https://wiki.eclipse.org/LDT

Installing LDT

LDT can be downloaded from here:

https://www.eclipse.org/ldt/

• After downloading the package for your system, unpack the files into a folder of your choice.

❕ In addition, the Java SE 8 JRE (Windows) or the Java SE 8 JDK (Mac OSX) must be installed.

Windows

The Java SE 8 JRE can be downloaded from here:

https://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html

Mac OSX

The Java SE 8 JDK can be downloaded from here:

https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

❕ Mac OSX might tell you that you need to install the legacy Java SE 6 runtime. Please ignore the message and install the Java SE 8 JDK instead.

Setting Up a Debug Session

Before starting a debug session, some preparations are required. In the following, you will be guided through all the necessary steps.

Starting LDT

Windows

• Double-click LuaDevelopmentTools.exe.

Mac OSX

• Double-click the Eclipse application.

Selecting a Workspace

Upon start of LDT, the Eclipse Launcher will ask you to select a directory as workspace.

• Choose a location for Workspace and click Launch.

Creating a Project

1. Open File > New > Project, select Lua Project and click Next >.

2. Enter a Project name.

3. Select Create project at existing location (from existing source) and set Directory to the location of your scripts.

   

4. Click Next >. The contents of the specified directory will be scanned. You can ignore the warning that says, "Your project has no source folder defined."

5. Click Finish.

   

The Lua scripts that have been found will appear in the Script Explorer of LDT. You can load them via double-click.

Configuring Attach Debug

In order for incoming debug sessions to be accepted, you must create a Lua Attach to Application launch configuration.

1. Open Run > Debug Configurations...
2. Select Lua Attach to Application and click the New button to create a configuration of this type.
3. Enter a name and click Apply.
4. Click Close, since we do not want to debug at the moment.

Changing the Debug Port on Mac

On Mac, you must change the debug server port before you can start a debug session.

1. Open Lua Development Tools Product > Preferences... and go in Dynamic Languages > Debug.
2. Change Port to "Custom" and enter the value "10001".
3. Click Apply and Close.

❕ Do not change the debug server port on Windows.

Starting a Debug Session

Please load the following code example for your first debug session.

Loading the Code Example

Create a new Lua file in LDT.

1. In File > New > Other..., select Lua File and click Next >.
2. Enter a file name and click Finish.

❕ New Lua files will be saved to the directory that you specified for the Lua project.

• Copy the following code example to the editor area of LDT.

Example

function onNote(ev)
  print(ev)
  postEvent(ev)
end

• Click to save the script file in LDT.

Now it is time to start HALion and to load the script.

1. Open HALion, create a program with a synth zone and a Lua Script module.
2. Load the script file from the location where you saved it.

❕ The script running in the Lua Script module of HALion must be loaded from the same location where LDT saved it. This ensures that the script in LDT and HALion are physically the same file. Otherwise, the debugger cannot establish a connection between LDT (debugger server) and the Lua Script module (debugger client).

Opening the Debug Perspective

Most of the debug functionality can be found in the Debug perspective of LDT.

• Click in the top right corner of the editor area.
• Alternatively, in Window > Perspective > Open Perspective > Other..., select Debug and click Open.

Breakpoints can be set by double-clicking the margin.

• Double-click the margin in line two, for example.

Connecting the Lua Script module with LDT

The following steps will establish a connection between LDT (debugger server) and the Lua Script module (debugger client).

1. Open HALion, go to the Lua Script module and click the Connect to Debugger button. This defines the Lua Script module as debugger client. The Connect to Debugger button turns blue to indicate that it waits for the debugger server.
2. Open LDT and go to Run > Debug Configurations. In Lua Attach to Application, select the configuarion you have previously created.
3. Click Debug to start the debugger server.

The Connect to Debugger button in HALion turns green if debugger server and client are connected.

As a basic test, try the following steps with the code example from above and a breakpoint in line two:

1. Play a MIDI note. LDT will break into the onNote function.

   

2. Click Resume or press (F8) to continue the script. HALion prints the event and outputs the note.

Stopping a Debug Session

To stop the debug session:

• Open the Lua Script module in HALion and click the Connect to Debugger button.

The Connect to Debugger button turns gray and the Debug area in LDT says the Lua Attach to Application session has <terminated>.

Using the LDT Debugger

From now on, the debug session can be started from the Debug menu on the LDT toolbar.

Tips for using the LDT debugger can be found here:

Debugging a Lua program

Updates

This page lists the modified and added pages for each version.

On this page:

• HALion 7.1.0
• HALion 7.0.0
• HALion 6.4.20
• HALion 6.4.10
• HALion 6.4.0
• HALion 6.3.0
• HALion 6.2.20
• HALion 6.1.0

HALion 7.1.0

Added Pages

• setBypassNoteOff

HALion 7.0.0

Added Pages

• cancelDecompose
• decompose
• Decompose Output Modes
• getDecomposeOutputPath
• getDecomposeProgress
• getDecomposeSettings
• getUserSubPresetPath
• onData
• onRetrigger
• savePreset
• setZoneFMXAlgo
• startWriteOutputToFile
• stopWriteOutputToFile
• Using External Files

Modified Pages

• Event
• Event Types
• getNoteDuration
• getUserPresetPath
• isKeyDown
• isOctaveKeyDown
• Modulation Destination Types
• Modulation Source Types
• onNote
• onRelease
• onUnhandledEvent
• playNote
• postEvent
• Protecting Layers

HALion 6.4.20

Modified Pages

• Creating Parameters
• defineParameter

HALion 6.4.10

Added Pages

• AlternateData Table
• VoiceGroupsData Table
• Voice Group Steal Modes

HALion 6.4.0

Added Pages

• Bus Constructor
• Bypass Masks
• Effect Constructor
• getOnsets
• Layer Constructor
• MidiModule Constructor
• Program Constructor
• Zone Constructor

Modified Pages

• AudioFile
• clone
• Bus
• Effect
• Layer
• MidiModule
• Program
• Zone

HALion 6.3.0

Added Pages

• analyzePitch
• cancelPitchAnalysis
• getPitch
• getPitchAnalysisProgress

Modified Pages

• AudioFile

HALion 6.2.20

Added Pages

• Debugging with LDT

HALion 6.1.0

Added Pages

• getUndoContext
• runSync
• Undo Context Types

Modified Pages

• assignAutomation
• Creating Parameters
• defineParameter
• startUndoBlock
• Threads in HALion

Functions by Subject

Here you can browse the functions of the HALion Script language by their subject.

On this page:

• Audio File Functions
• Automation Functions
• Bus Functions
• Context Functions
• Conversion Functions
• Element Functions
• Event Callback
• Event Functions
• Instance Functions
• Layer Functions
• MIDI File Functions
• Modulation Matrix Functions
• ParameterDefinition Functions
• QC Functions
• Slot Functions
• Timing Functions
• UI Script Functions
• Undo Functions
• Voice Functions
• Zone Functions

Audio File Functions

analyzePitch, AudioFile.open, cancelDecompose, cancelPitchAnalysis, decompose, getDecomposeProgress, getOnsets, getPeak, getPitch, getPitchAnalysisProgress,

Automation Functions

assignAutomation, forgetAutomation, getAutomationIndex,

Bus Functions

appendEffect, findEffects, getEffect, getOutputBus, insertEffect, removeEffect, setOutputBus,

Context Functions

getAllocatedMemory, getBarDuration, getBeatDuration, getBeatTime, getBeatTimeInBar, getCC, getContext, getDecomposeOutputPath, getDecomposeSettings, getFreeVoices, getHostName, getHostVersion, getMsTime, getNoteDuration, getNoteExpression, getProcessedSamples, getProductName, getProductVersion, getSamplingRate, getScriptVersion, getSlotIndex, getTempo, getTime, getTimeSignature, getUsedMemory, getUsedVoices, getUsedVoicesOfSlot, getUserPresetPath, getUserSubPresetPath, getVoices, isKeyDown, isNoteHeld, isOctaveKeyDown, isPlaying,

Conversion Functions

beat2ms, ms2beat, ms2samples, samples2ms,

Element Functions

findChildren, getChild, getParameter, getParameterDefinition, getParameterNormalized, hasParameter, removeFromParent, setName, setParameter, setParameterNormalized,

Event Callback

onAfterTouch, onController, onData, onIdle, onInit, onLoad, onLoadIntoSlot, onLoadSubPreset, onNote, onNoteExpression, onPitchBend, onRelease, onRemoveFromSlot, onRetrigger, onSave, onSaveSubPreset, onTriggerPad, onUnhandledEvent,

Event Functions

afterTouch, controlChange, pitchBend, playNote, playTriggerPad, postEvent, releaseVoice,

Instance Functions

findBusses, findEffects, findSlots, getBus, getProgram, getSlot, setProgram,

Layer Functions

addQCAssignment, appendBus, appendLayer, appendLayerAsync, appendMidiModule, appendZone, findBusses, findEffects, findLayers, findMidiModules, findZones, getBus, getLayer, getMidiModule, getNumQCAssignments, getQCAssignmentBypass, getQCAssignmentCurve, getQCAssignmentMax, getQCAssignmentMin, getQCAssignmentMode, getQCAssignmentParamId, getQCAssignmentScope, getZone, insertBus, insertLayer, insertLayerAsync, insertMidiModule, insertZone, removeBus, removeLayer, removeMidiModule, removeQCAssignment, removeZone, setQCAssignmentBypass, setQCAssignmentCurve, setQCAssignmentMax, setQCAssignmentMin, setQCAssignmentMode, setQCAssignmentParamId, setQCAssignmentScope,

MIDI File Functions

insertEvent, readMidiFile, sortEvents, writeMidiFile,

Modulation Matrix Functions

getSource1, getSource2, setSource1, setSource2,

ParameterDefinition Functions

getDisplayString,

QC Functions

addQCAssignment, getNumQCAssignments, getQCAssignmentBypass, getQCAssignmentCurve, getQCAssignmentMax, getQCAssignmentMin, getQCAssignmentMode, getQCAssignmentParamId, getQCAssignmentScope, removeQCAssignment, setQCAssignmentBypass, setQCAssignmentCurve, setQCAssignmentMax, setQCAssignmentMin, setQCAssignmentMode, setQCAssignmentParamId, setQCAssignmentScope,

Slot Functions

findBusses, findEffects, getBus,

Timing Functions

runAsync, runSync, spawn, wait, waitBeat, waitForRelease,

UI Script Functions

getElement,

Undo Functions

endUndoBlock, getUndoContext, startUndoBlock,

Voice Functions

changeNoteExpression, changePan, changeTune, changeVolume, changeVolumedB, fade,

Zone Functions

getModulationMatrixRow, getOutputBus, setOutputBus,

/ HALion Developer Resource / HALion Script /

Class Reference

Class Hierarchy

• Audio File
• Element
  • Bus
  • Effect
  • Instance
  • Layer
    • Program
  • MidiModule
  • ModulationMatrixRow
  • Slot
  • Zone
• Event
• LoadProgress
• ParameterDefinition

/ HALion Developer Resource / HALion Script / Class Reference /

Audio File

The AudioFile class describes the properties of audio files.

On this page:

AudioFile Class, analyzePitch, cancelDecompose, cancelPitchAnalysis, decompose, getDecomposeProgress, getOnsets, getPeak, getPitch, getPitchAnalysisProgress

Classes

AudioFile Class

Description

The AudioFile.open function creates an AudioFile object of the specified audio file. The AudioFile object can be used to retrieve information from the audio file, for example, the sample rate, bit depth, length in samples, etc. The AudioFile object has the following fields.

❕ All fields of the AudioFile object are read-only.

Available in: Controller, Processor.

Fields

Example

-- Open an audio file from HALion Sonic 1.0.

fname = "vstsound://502B301A6C914CEDA5C7500DC890C4DC/.Samples/g:/projects/yamahacontentserver/download/release/smtg/winds/Samples/DP060_FluteC3.wav"
af = AudioFile.open(fname)
loops = af.loops

-- Print information from the audio file.

if af.valid then
  print(fname, "opened.")
  print("Sample Rate: ", af.rate)
  print("Bit Depth: ", af.bits)
  print("Channels: ", af.channels)
  print("Sample Length: ", af.length)
  if loops then
    print("Loop Start: ", loops[1].loopStart)
    print("Loop End: ", loops[1].loopEnd)
  end
else
  print(fname, "does not exist.")
end

Jump to Top

Methods

analyzePitch

analyzePitch(callback, channel)

(Since HALion 6.3)

Description

Function to analyze the pitch of an audio file. You specify the audio file with the AudioFile object that is returned by the AudioFile.open function. The arguments callback and channel are optional. If called without a callback function, analyzePitch will be executed in the same thread. If called with a callback function as argument, analyzePitch will be executed in a separate, parallel thread. You can specify the channel to be analyzed with the channel argument. Without the channel argument, multiple channels of an audio file will be summed before the pitch is analyzed. The callback function is called with the AudioFile object as the first and the channel as the second argument after the pitch has been analyzed. The results of analyzePitch are cashed for as long as the corresponding AudioFile object exists. The function itself does not return any pitch information. You must use getPitch to obtain the analyzed pitch.

Available in: Controller.

Arguments

Example

channelNames = { [0] = "All", "Left", "Right" }
  
defineParameter( "Channel", nil, 0, channelNames)
defineParameter( "Start", nil, false, function() if Start then onStart() end end)
defineParameter( "Cancel", nil, false)
  
-- Requires the Skylab content.
path = "vstsound://724ACB205EFF46F885735D1B216C37AD/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 01.vstpreset"
layer = loadPreset(path)
  
function onPitchAnalysisFinished(audioFile, channelNum)
    print("Progress: 100%")
    print(channelNames[channelNum].." channel(s) of "..audioFile.fileName.." analyzed.")
end
  
function onStart()
    zones = layer:findZones(true)
    for i, zone in ipairs(zones) do
        local samplePath = zone:getParameter("SampleOsc.Filename")
        print("File: "..samplePath)
        local afile = AudioFile.open(samplePath)
        afile:analyzePitch(onPitchAnalysisFinished, Channel)
        while afile:getPitchAnalysisProgress(Channel) < 1 do
            if Cancel then
                afile:cancelPitchAnalysis(Channel)
                break
            end
            local progressPercent = 100 * afile:getPitchAnalysisProgress(Channel)
            print(string.format("Progress: %2d%%", progressPercent))
            wait(2000)
        end
        if Cancel then
            Cancel = false
            print("Canceled!")
            break
        end
        local pitch = afile:getPitch(0, -1, Channel)
        print("Analyzed Pitch: "..pitch)
    end
    print("Done!")
    Start = false
end

Jump to Top

cancelDecompose

cancelDecompose()

(Since HALion 7.0)

Description

Function to cancel the decompose function for an audio file. You specify the audio file with the AudioFile object that is returned by the AudioFile.open function. To cancel the decompose of a specific audio file, the AudioFile object of the cancelDecompose function must match the AudioFile object of the corresponding decompose function.

Available in: Controller.

Example

outputModes = { "Tonal", "Noise", "All", "Mix", }
 
defineParameter { name = "Decompose", default = false, onChanged = function() if Decompose then onDecompose() end end }
defineParameter { name = "Cancel", default = false}
defineParameter { name = "Sensitivity", default = -24, min = -96, max = 0, increment = 0.1 }
defineParameter { name = "Cutoff", default = 20000, min = 20, max = 20000, increment = 1 }
defineParameter { name = "Duration", default = 80, min = 0, max = 100, increment = 0.1 }
defineParameter { name = "TonalLevel", default = 0, min = -96, max = 12, increment = 0.1 }
defineParameter { name = "NoiseLevel", default = 0, min = -96, max = 12, increment = 0.1 }
defineParameter { name = "Start", default = 0, min = 0, max = 1000, increment = 1 }
defineParameter { name = "Length", default = 0, min = 0, max = 1000, increment = 1 }
defineParameter { name = "OutputMode", default = DecomposeOutputMode.all, strings = outputModes }
defineParameter { name = "OutputPath", default = "" }
defineParameter { name = "Subfolder", default = "" }
 
function onDecomposeFinished(audioFile, file1, file2)
    print("Progress: 100%")
    print(audioFile.fileName, audioFile.length)
    if file1 then
        local afile1 = AudioFile.open(file1)
        print(afile1.fileName, afile1.length)
    end
    if file2 then
        local afile2 = AudioFile.open(file2)
        print(afile2.fileName, afile2.length)
    end
end
 
function onDecompose()
    zones = this.parent:findZones(true)
    for i, zone in ipairs(zones) do
        local samplePath = zone:getParameter("SampleOsc.Filename")
        local afile = AudioFile.open(samplePath)
        local startSamples = Start * afile.rate/1000
        local lengthSamples = Length * afile.rate/1000
        if not Subfolder == "" then
            if OutputPath == "" then
                OutputPath = getDecomposeOutputPath(samplePath)..Subfolder
            else
                OutputPath = OutputPath..Subfolder
            end
        end
        print("Decompose: "..samplePath)
        afile:decompose{
            callback = onDecomposeFinished,
            start = startSamples,
            length = lengthSamples,
            sensitivity = Sensitivity,
            cutoff = Cutoff,
            duration = Duration,
            tonalLevel = TonalLevel,
            noiseLevel = NoiseLevel,
            outputMode = OutputMode,
            outputPath = OutputPath,
        }
        while afile:getDecomposeProgress() < 1 do
            if Cancel then
                afile:cancelDecompose()
                break
            end
            local progress, errorMessage = afile:getDecomposeProgress()
            if errorMessage then
                print(errorMessage)
                break
            end
            local progressPercent = 100 * progress
            print(string.format("Progress: %2d%%", progressPercent))
            wait(2000)
        end
        if Cancel then
            Cancel = false
            print("Decompose Canceled!")
            break
        end
    end
    print("Decompose finished.")
    Decompose = false
end

Jump to Top

cancelPitchAnalysis

cancelPitchAnalysis(channel)

(Since HALion 6.3)

Description

Function to cancel a pitch analysis you started with analyzePitch. You specify the audio file with the AudioFile object that is returned by the AudioFile.open function. The channel argument specifies the channel of the audio file. The AudioFile object and the channel argument must match the call to analyzePitch.

Available in: Controller.

Arguments

Example

channelNames = { [0] = "All", "Left", "Right" }
  
defineParameter( "Channel", nil, 0, channelNames)
defineParameter( "Start", nil, false, function() if Start then onStart() end end)
defineParameter( "Cancel", nil, false)
  
-- Requires the Skylab content.
path = "vstsound://724ACB205EFF46F885735D1B216C37AD/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 01.vstpreset"
layer = loadPreset(path)
  
function onPitchAnalysisFinished(audioFile, channelNum)
    print("Progress: 100%")
    print(channelNames[channelNum].." channel(s) of "..audioFile.fileName.." analyzed.")
end
  
function onStart()
    zones = layer:findZones(true)
    for i, zone in ipairs(zones) do
        local samplePath = zone:getParameter("SampleOsc.Filename")
        print("File: "..samplePath)
        local afile = AudioFile.open(samplePath)
        afile:analyzePitch(onPitchAnalysisFinished, Channel)
        while afile:getPitchAnalysisProgress(Channel) < 1 do
            if Cancel then
                afile:cancelPitchAnalysis(Channel)
                break
            end
            local progressPercent = 100 * afile:getPitchAnalysisProgress(Channel)
            print(string.format("Progress: %2d%%", progressPercent))
            wait(2000)
        end
        if Cancel then
            Cancel = false
            print("Canceled!")
            break
        end
        local pitch = afile:getPitch(0, -1, Channel)
        print("Analyzed Pitch: "..pitch)
    end
    print("Done!")
    Start = false
end

Jump to Top

decompose

decompose{arguments}

(Since HALion 7.0)

Description

Function to decompose an audio file into its tonal and noise components. You specify the audio file with the AudioFile object that is returned by the AudioFile.open function. The decompose function can be configured with named arguments. The named arguments are optional and if called without, decompose will be executed with its default settings.

Available in: Controller.

Arguments

❕ Samples that were loaded from a VST Sound container can only be decomposed if the ouputPath argument is set to a valid file location. You can use getDecomposeOutputPath to obtain the file location from the decompose settings of the plug-in.

Example

outputModes = { "Tonal", "Noise", "All", "Mix", }
 
defineParameter { name = "Decompose", default = false, onChanged = function() if Decompose then onDecompose() end end }
defineParameter { name = "Cancel", default = false}
defineParameter { name = "Sensitivity", default = -24, min = -96, max = 0, increment = 0.1 }
defineParameter { name = "Cutoff", default = 20000, min = 20, max = 20000, increment = 1 }
defineParameter { name = "Duration", default = 80, min = 0, max = 100, increment = 0.1 }
defineParameter { name = "TonalLevel", default = 0, min = -96, max = 12, increment = 0.1 }
defineParameter { name = "NoiseLevel", default = 0, min = -96, max = 12, increment = 0.1 }
defineParameter { name = "Start", default = 0, min = 0, max = 1000, increment = 1 }
defineParameter { name = "Length", default = 0, min = 0, max = 1000, increment = 1 }
defineParameter { name = "OutputMode", default = DecomposeOutputMode.all, strings = outputModes }
defineParameter { name = "OutputPath", default = "" }
defineParameter { name = "Subfolder", default = "" }
 
function onDecomposeFinished(audioFile, file1, file2)
    print("Progress: 100%")
    print(audioFile.fileName, audioFile.length)
    if file1 then
        local afile1 = AudioFile.open(file1)
        print(afile1.fileName, afile1.length)
    end
    if file2 then
        local afile2 = AudioFile.open(file2)
        print(afile2.fileName, afile2.length)
    end
end
 
function onDecompose()
    zones = this.parent:findZones(true)
    for i, zone in ipairs(zones) do
        local samplePath = zone:getParameter("SampleOsc.Filename")
        local afile = AudioFile.open(samplePath)
        local startSamples = Start * afile.rate/1000
        local lengthSamples = Length * afile.rate/1000
        if not Subfolder == "" then
            if OutputPath == "" then
                OutputPath = getDecomposeOutputPath(samplePath)..Subfolder
            else
                OutputPath = OutputPath..Subfolder
            end
        end
        print("Decompose: "..samplePath)
        afile:decompose{
            callback = onDecomposeFinished,
            start = startSamples,
            length = lengthSamples,
            sensitivity = Sensitivity,
            cutoff = Cutoff,
            duration = Duration,
            tonalLevel = TonalLevel,
            noiseLevel = NoiseLevel,
            outputMode = OutputMode,
            outputPath = OutputPath,
        }
        while afile:getDecomposeProgress() < 1 do
            if Cancel then
                afile:cancelDecompose()
                break
            end
            local progress, errorMessage = afile:getDecomposeProgress()
            if errorMessage then
                print(errorMessage)
                break
            end
            local progressPercent = 100 * progress
            print(string.format("Progress: %2d%%", progressPercent))
            wait(2000)
        end
        if Cancel then
            Cancel = false
            print("Decompose Canceled!")
            break
        end
    end
    print("Decompose finished.")
    Decompose = false
end

Jump to Top

getDecomposeProgress

getDecomposeProgress()

(Since HALion 7.0)

Description

Function to monitor the progress of the decompose function for an audio file. You specify the audio file with the AudioFile object that is returned by the AudioFile.open function. To get the progress of a specific audio file that is being decomposed, the AudioFile object of the getDecomposeProgress function must match the AudioFile object of the corresponding decompose function. The function returns two values: the progress as a value between 0 and 1 and an error message if the decompose did not succeed.

Available in: Controller.

Return Values

Returns the progress as a float value between 0 and 1, and an error message if the decompose did not succeed. The error message returns nil if the decompose was successful.

Example

outputModes = { "Tonal", "Noise", "All", "Mix", }
 
defineParameter { name = "Decompose", default = false, onChanged = function() if Decompose then onDecompose() end end }
defineParameter { name = "Cancel", default = false}
defineParameter { name = "Sensitivity", default = -24, min = -96, max = 0, increment = 0.1 }
defineParameter { name = "Cutoff", default = 20000, min = 20, max = 20000, increment = 1 }
defineParameter { name = "Duration", default = 80, min = 0, max = 100, increment = 0.1 }
defineParameter { name = "TonalLevel", default = 0, min = -96, max = 12, increment = 0.1 }
defineParameter { name = "NoiseLevel", default = 0, min = -96, max = 12, increment = 0.1 }
defineParameter { name = "Start", default = 0, min = 0, max = 1000, increment = 1 }
defineParameter { name = "Length", default = 0, min = 0, max = 1000, increment = 1 }
defineParameter { name = "OutputMode", default = DecomposeOutputMode.all, strings = outputModes }
defineParameter { name = "OutputPath", default = "" }
defineParameter { name = "Subfolder", default = "" }
 
function onDecomposeFinished(audioFile, file1, file2)
    print("Progress: 100%")
    print(audioFile.fileName, audioFile.length)
    if file1 then
        local afile1 = AudioFile.open(file1)
        print(afile1.fileName, afile1.length)
    end
    if file2 then
        local afile2 = AudioFile.open(file2)
        print(afile2.fileName, afile2.length)
    end
end
 
function onDecompose()
    zones = this.parent:findZones(true)
    for i, zone in ipairs(zones) do
        local samplePath = zone:getParameter("SampleOsc.Filename")
        local afile = AudioFile.open(samplePath)
        local startSamples = Start * afile.rate/1000
        local lengthSamples = Length * afile.rate/1000
        if not Subfolder == "" then
            if OutputPath == "" then
                OutputPath = getDecomposeOutputPath(samplePath)..Subfolder
            else
                OutputPath = OutputPath..Subfolder
            end
        end
        print("Decompose: "..samplePath)
        afile:decompose{
            callback = onDecomposeFinished,
            start = startSamples,
            length = lengthSamples,
            sensitivity = Sensitivity,
            cutoff = Cutoff,
            duration = Duration,
            tonalLevel = TonalLevel,
            noiseLevel = NoiseLevel,
            outputMode = OutputMode,
            outputPath = OutputPath,
        }
        while afile:getDecomposeProgress() < 1 do
            if Cancel then
                afile:cancelDecompose()
                break
            end
            local progress, errorMessage = afile:getDecomposeProgress()
            if errorMessage then
                print(errorMessage)
                break
            end
            local progressPercent = 100 * progress
            print(string.format("Progress: %2d%%", progressPercent))
            wait(2000)
        end
        if Cancel then
            Cancel = false
            print("Decompose Canceled!")
            break
        end
    end
    print("Decompose finished.")
    Decompose = false
end

Jump to Top

getOnsets

getOnsets(start, length, peakThreshold, sensThreshold, minLength)

(Since HALion 6.4.0)

Description

Function to analyze the onsets in an audio file. You specify the audio file with the AudioFile object that is returned by the AudioFile.open function. The onset analysis is performed on the sum of all channels in the audio file. The arguments start and length define the time range in the audio file to be analyzed. The peakThreshold and sensThreshold arguments determine the minimum level and the weight of an onset, the minLength argument determines the minimum duration between consecutive onsets.

Available in: Controller.

Arguments

Return Values

Returns an array with the positions of the detected onsets.

Example

fname = "vstsound://271CB2CFA75E4295B1C273FA651FE11D/.Samples/g:/projects/yamahacontentserver/Download/Release/ycj/ME_Waveform/Loop145/samples/Loop145_072(2).wav"
 
af = AudioFile.open(fname)
 
onsets = af:getOnsets(0, -1, -24, 0, 10)
  
for i, pos in ipairs(onsets) do
   print(i.." ".."Onset: "..pos)
end

Jump to Top

getPeak

getPeak(start, length, rms)

Description

Function to analyze the levels in an audio file. You specify the audio file with the AudioFile object that is returned by the AudioFile.open function. The arguments start and length define the range in the audio file to be analyzed. The rms argument determines whether the peak level or the RMS level of the specified range is returned.

Available in: Controller.

Arguments

Return Values

Returns the level of the specifed range as a linear value. The example shows how to convert the value from linear to dB.

Example

function lin2db(lin)
  return 20 * math.log(lin) / math.log(10)
end

fname = "vstsound://F29C895D6D8E4D6C9BCBBA5198412192/.samples/Ambient Pad 01/Ambient Pad 01 - C3.tg3c"
af = AudioFile.open(fname)

-- Analyze the peak level in the first 1000 samples.

attpeak = af:getPeak(0, 1000, 0)

-- Analyze the RMS level in the range from 1000 samples till the end of the file.

susrms = af:getPeak(1000, -1, 1)
print("Attack Peak:", attpeak, "(", lin2db(attpeak), "dB )")
print("Sustain RMS:", susrms, "(", lin2db(susrms), "dB )")

Jump to Top

getPitch

getPitch(start, length, channel)

(Since HALion 6.3)

Description

Function to obtain the pitch of an audio file that has been analyzed with analyzePitch. The audio file you want to obtain the pitch from is specified with the AudioFile object that is returned by the AudioFile.open function. The arguments start and length define the range in the audio file that is used for obtaining the pitch. The channel argument specifies the channel of the audio file that was analyzed. The AudioFile object and the channel argument must match the call to analyzePitch. The function returns two values: The pitch as MIDI note number with decimals for cents and a boolean for voiced/unvoiced detection. If length is greater than 20 ms, the average of the pitches in the specified range is returned. If the audio file has not been analyzed in advance, getPitch returns nil.

Available in: Controller.

Arguments

Return Values

Returns two values:

• A float value representing the pitch as MIDI note number with decimals for cents,
• a boolean for voiced/unvoiced detection. The return value true means that a pitch was detected in the specified range.

If length is greater than 20 ms, the average of the pitches in the specified range is returned. If the audio file has not been analyzed in advance, getPitch returns nil.

Example

channelNames = { [0] = "All", "Left", "Right" }
  
defineParameter( "Channel", nil, 0, channelNames)
defineParameter( "Start", nil, false, function() if Start then onStart() end end)
defineParameter( "Cancel", nil, false)
  
-- Requires the Skylab content.
path = "vstsound://724ACB205EFF46F885735D1B216C37AD/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 01.vstpreset"
layer = loadPreset(path)
  
function onPitchAnalysisFinished(audioFile, channelNum)
    print("Progress: 100%")
    print(channelNames[channelNum].." channel(s) of "..audioFile.fileName.." analyzed.")
end
  
function onStart()
    zones = layer:findZones(true)
    for i, zone in ipairs(zones) do
        local samplePath = zone:getParameter("SampleOsc.Filename")
        print("File: "..samplePath)
        local afile = AudioFile.open(samplePath)
        afile:analyzePitch(onPitchAnalysisFinished, Channel)
        while afile:getPitchAnalysisProgress(Channel) < 1 do
            if Cancel then
                afile:cancelPitchAnalysis(Channel)
                break
            end
            local progressPercent = 100 * afile:getPitchAnalysisProgress(Channel)
            print(string.format("Progress: %2d%%", progressPercent))
            wait(2000)
        end
        if Cancel then
            Cancel = false
            print("Canceled!")
            break
        end
        local pitch = afile:getPitch(0, -1, Channel)
        print("Analyzed Pitch: "..pitch)
    end
    print("Done!")
    Start = false
end

Jump to Top

getPitchAnalysisProgress

getPitchAnalysisProgress(channel)

(Since HALion 6.3)

Description

Function to monitor the progress of analyzePitch. You specify the audio file with the AudioFile object that is returned by the AudioFile.open function. The channel argument specifies the channel of the audio file. The AudioFile object and the channel argument must match the call to analyzePitch. The function returns the progress as a float value between 0 and 1.

Available in: Controller.

Arguments

Return Values

Returns the progress as a float value between 0 and 1.

Example

channelNames = { [0] = "All", "Left", "Right" }
  
defineParameter( "Channel", nil, 0, channelNames)
defineParameter( "Start", nil, false, function() if Start then onStart() end end)
defineParameter( "Cancel", nil, false)
  
-- Requires the Skylab content.
path = "vstsound://724ACB205EFF46F885735D1B216C37AD/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 01.vstpreset"
layer = loadPreset(path)
  
function onPitchAnalysisFinished(audioFile, channelNum)
    print("Progress: 100%")
    print(channelNames[channelNum].." channel(s) of "..audioFile.fileName.." analyzed.")
end
  
function onStart()
    zones = layer:findZones(true)
    for i, zone in ipairs(zones) do
        local samplePath = zone:getParameter("SampleOsc.Filename")
        print("File: "..samplePath)
        local afile = AudioFile.open(samplePath)
        afile:analyzePitch(onPitchAnalysisFinished, Channel)
        while afile:getPitchAnalysisProgress(Channel) < 1 do
            if Cancel then
                afile:cancelPitchAnalysis(Channel)
                break
            end
            local progressPercent = 100 * afile:getPitchAnalysisProgress(Channel)
            print(string.format("Progress: %2d%%", progressPercent))
            wait(2000)
        end
        if Cancel then
            Cancel = false
            print("Canceled!")
            break
        end
        local pitch = afile:getPitch(0, -1, Channel)
        print("Analyzed Pitch: "..pitch)
    end
    print("Done!")
    Start = false
end

Jump to Top

/ HALion Developer Resource / HALion Script / Class Reference /

Element

The Element class is the base class for the classes Bus, Instance, Layer, Effect, MidiModule, ModulationMatrixRow, Slot and Zone.

On this page:

Element Class, findChildren, getChild, getParameter, getParameterDefinition, getParameterNormalized, hasParameter, removeFromParent, setName, setParameter, setParameterNormalized

Classes

Element Class

The different types of elements are Instance, Slot, Program, Layer, Zone, ModulationMatrixRow, MidiModule, Bus and Effect. The properties of an Element object are described by the following fields.

Available in: Controller, Processor.

Fields

Example

-- Print information about the script module.

print(this.name)
print(this.id)
print(this.type)
print(this.name)
print(this.numParams)
print(this.parent.name)
print(this.program.name)
print(this.level)
 
-- Print the names of all parameters of the parent element.

defs = this.parent.parameterDefinitions
 
for i, def in ipairs(defs) do
    print(def.name)
end

Jump to Top

Methods

findChildren

findChildren(recursive, nameOrFilterFunction)

Description

Function to find children in the specified Element object. For example, this.parent specifies the parent layer of the script module as the Element object to be searched in. If recursive is set to true, subelements will also be searched. The function returns an array with the Element objects of the found children. Particular children can be searched by name or via a filter function. If searching by name, findChildren accepts only the Element objects that match the specified name. The filter function uses the Element object of each child as argument. Only those Element objects that return true for the search criteria defined in the filter function will be accepted by findChildren. Without a name or filter function, the Element objects of all children in the searched Element object will be returned.

Available in: Controller, Processor.

Arguments

Return Values

Returns an array with the Element objects of the found children. Returns an empty table if no children are found.

Example

-- Find the MIDI module with the name "Lua Script" and print its type.

scriptModules = this.parent:findChildren(false, "Lua Script")
 
if scriptModules[1] then
    print(scriptModules[1].type)
end
 
-- Find all children and print their names.
children = this.program:findChildren(true)
 
if children[1] then
    for i, child in ipairs(children) do
        print(child.name)
    end
else
    print("Could not find any children!")
end

Jump to Top

getChild

getChild(nameOrPosition)

Description

Function to retrieve the Element object of a child in the specified Element object. For example, this.parent specifies the parent layer of the script module as the Element object to be searched in. This function does not search in subelements. A particular child can be searched by name or position. The position is the number indexing the children in the specified Element object. If several children share the same name, only the first match will be returned. If no argument is set, the function returns the first child it finds.

Available in: Controller, Processor.

Arguments

Return Values

Returns the Element object of the found child. Returns nil if no child is found.

Example

-- Locate the first child in the program and print its name.

child = this.program:getChild()
 
if child then
    print(child.name)
else
    print("Could not find a child!")
end

Jump to Top

getParameter

getParameter(nameOrID)

Description

Function to read the current value of a parameter. The parameter can be determined by name or ID.

Available in: Controller, Processor.

Arguments

Return Values

Returns the current value of the parameter or nil if the parameter doesn't exist.

Example

-- Print the value of the parent layer's level parameter.

function onLoadIntoSlot()
    print("Level = "..this.parent:getParameter("Level")) -- via name
    print("Level = "..this.parent:getParameter(38))      -- via ID
end

Jump to Top

getParameterDefinition

getParameterDefinition(nameOrID)

Description

Function to retrieve the ParameterDefinition object for a parameter. The parameter can be determined by name or ID. The ParameterDefinition object describes the properties of a parameter.

Available in: Controller, Processor.

Arguments

Return Values

Returns the ParameterDefinition object for the specified parameter.

Example

-- Print the parameter definition with corresponding
-- data type of the parent layer's level parameter.

function onLoadIntoSlot()
  
    local def = this.parent:getParameterDefinition("Level")
  
    print("Name = "..def.name..", "..type(def.name))
    print("ID = "..def.id..", "..type(def.id))
    print("Type = "..def.type..", "..type(def.type))
    print("Default = "..def.default..", "..type(def.default))
    print("Read Only = "..tostring(def.readOnly)..", "..type(def.readOnly))
    print("Min = "..def.min..", "..type(def.min))
    print("Max = "..def.max..", "..type(def.max))
    print("Unit = "..def.unit..", "..type(def.unit).."\n")
  
end

Jump to Top

getParameterNormalized

getParameterNormalized(nameOrID)

Description

Function to read the current value of a parameter in the normalized range from 0 to 1.0. The parameter can be determined by name or ID.

Available in: Controller, Processor.

Arguments

Return Values

Returns the current value of the parameter in the normalized range from 0 to 1.0 or nil if the parameter doesn't exist. If the parameter is not numeric, the function returns the same as getParameter

Example

-- Print the normalized value of the parent layer's level parameter.

function onLoadIntoSlot()
    print("Level = "..this.parent:getParameterNormalized("Level")) -- via name
    print("Level = "..this.parent:getParameterNormalized(38))      -- via ID
end

Jump to Top

hasParameter

hasParameter(nameOrID)

Description

Function to check if a parameter exists. The parameter can be determined by name or ID.

Available in: Controller, Processor.

Arguments

Return Values

Returns true if the parameter exists or false if not.

Example

-- Check if the elements in the Program Tree have filter cutoff.

function onLoadIntoSlot()
    childs = this.program:findChildren(true)
    for i, child in ipairs(childs) do
        if child:hasParameter("Filter.Cutoff") then
            print(child.name.." has filter cutoff.")
        else
            print(child.name.." has no filter cutoff.")
        end
    end
end

Jump to Top

removeFromParent

removeFromParent()

Description

Function to remove an element in the Program Tree from the parent element. The function can remove elements of the type Layer, Zone, MidiModule, Bus and Effect. It can even remove the script module that calls the function.

Available in: Controller.

Example

-- Remove the second child element.

childs = this.program:findChildren(true)
if childs[2] then
    childs[2]:removeFromParent()
end

-- Remove the program bus.

bus = this.program:getBus("Program-Bus")
if bus then
    bus:removeFromParent()
end

Jump to Top

setName

setName(name)

Description

Function to change the name of an element in the Program Tree.

Available in: Controller.

Arguments

Example

-- Print current name of the script module.

print(this.name)

-- Set the name of the script module to "My Element".

this:setName("My Element")

-- Print the new name of the script module.

print(this.name)

Jump to Top

setParameter

setParameter(nameOrID, value, undo)

Description

Function to set the value of a parameter. The parameter can be determined by name or ID. The function will have no effect if the parameter does not exist.

Available in: Controller, Processor.

Arguments

Example

-- Set the value of the Level parameter of the parent layer.

function onLoadIntoSlot()
    this.parent:setParameter("Level", 0) -- Set via name.
    this.parent:setParameter(38, 0)      -- Set via ID.
end

Jump to Top

setParameterNormalized

setParameterNormalized(nameOrID, value, undo)

Description

Function to set the value of a parameter in the normalized range from 0 to 1.0. The parameter can be determined by name or ID. This function has no effect if the parameter does not exist or if the value is of the type string.

Available in: Controller, Processor.

Arguments

Example

-- Set the normalized value of the parent layer's level parameter.

function onLoadIntoSlot()
    this.parent:setParameterNormalized("Level", 0.5) -- Set via name.
    this.parent:setParameterNormalized(38, 0.5)      -- Set via ID.
end

Jump to Top

/ HALion Developer Resource / HALion Script / Class Reference / Element /

Bus

The Bus class inherits all properties and methods of the Element class.

On this page:

Bus Class, Bus Constructor, findEffects, getEffect, insertEffect, appendEffect, removeEffect, getOutputBus, setOutpuBus

List of inherited members:

Element

Element Class, findChildren, getChild, getParameter, getParameterDefinition, getParameterNormalized, hasParameter, removeFromParent, setName, setParameter, setParameterNormalized

Classes

Bus Class

Description

The Element object of a bus can be obtained with findBusses or getBus. It has the following fields.

Available in: Controller, Processor.

Fields

Example

-- Print the names of the active output busses of the plug-in.

busses = this.program.instance:findBusses()
 
for i, bus in ipairs(busses) do
    if bus.active then
        print(bus.name)
    end
end

Jump to Top

Constructors

Bus Constructor

Bus()

(Since HALion 6.4.0)

Description

Constructor to create a new Bus object.

Available in: Controller.

Return Values

Returns a new Bus object.

Example

-- The following function creates different types of objects in the Program Tree.
-- The objects in the Program Tree do not have a name. You will see only their icons.

function createProgram()
  local inst = this.program.instance
  local prg = Program()
  local bus = Bus()
  prg:appendBus(bus)
  inst:setProgram(prg, 1)
  local layer = Layer()
  prg:appendLayer(layer)
  layer:appendZone(Zone())
  local mm = MidiModule('MIDI Player')
  layer:appendMidiModule(mm)
  local fx = Effect('Distortion')
  bus:appendEffect(fx)
end
 
createProgram()

Jump to Top

Methods

findEffects

findEffects(recursive, nameOrFilterFunction)

Description

Function to find effects in the specified Element object. For example, this.parent specifies the parent of the script module as the Element object to be searched in. To specifiy a bus to be searched in, use getBus or findBusses. If recursive is set to true, subelements will also be searched. The function returns an array with the Effect objects of the found effects. Particular effects can be searched by name or via a filter function. If searching by name, findEffects accepts only the Effect objects that match the specified name. The filter function uses the Effect object of each effect as argument. Only those Effect objects that return true for the search criteria defined in the filter function will be accepted by findEffects. Without a name or filter function, the Effect objects of all effects in the searched Element objects will be returned.

Available in: Controller, Processor.

Arguments

Return Values

Returns an array with the Effect objects of the found effects. Returns an empty table if no effects are found.

Example

-- Find all effects and print their names.
effects = this.program:findEffects(true)
 
if effects[1] then
    for i, effect in ipairs(effects) do
        print(effect.name)
    end
else
    print("Could not find any effects!")
end

Jump to Top

getEffect

getEffect(nameOrPosition)

Description

Function to retrieve the Effect object of an effect from the specified bus. You can use getBus or findBusses to specify the bus. A particular effect can be searched by name or position. The position is the number indexing the effects in the specified bus. If several effects share the same name, only the first match will be returned. If no argument is set, the function returns the first effect that it finds.

Available in: Controller, Processor.

Arguments

Return Values

Returns the Effect object of the found effect. Returns nil if no bus is found.

Example

-- Locate the first bus in the program.

bus = this.program:getBus()

if bus then
    -- Locate the first effect of the bus and print its name.
    effect = bus:getEffect()
    if effect then
        print(effect.name)
    else
        print("Could not find an effect!")
    end
else
    print("Could not find a bus!")
end

Jump to Top

insertEffect

insertEffect(effect, position)

Description

Function to insert an effect at a specific position in a destination bus. The effect to be inserted is determined by its Effect object. You can use getEffect or findEffects to determine the effect. The destination bus is determined by its Bus object. You can use getBus or findBusses to determine the destination bus. The position is the number indexing the effects in the destination bus. The new effect will be inserted before the specified position. To add the effect at the end, use appendEffect instead.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, an Element object that you retrieved from the running plug-in instance must be removed before it can be inserted again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be inserted freely, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Example

To explore the following script:

1. Download Program.vstpreset.
2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
3. Create an empty program and add a script module.
4. Paste the script into the text editor of the script module and execute the script.

-- Insert an effect from Program.vstpreset into the current program.
  
-- Get the file path for user VST presets.
path = getUserPresetPath()
  
-- Load the VST preset.
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")
  
-- Get the first effect from the loaded program.
effect = loadedProgram:getBus():getEffect()
 
-- Get the first bus of this program.
bus = this.program:getBus()
 
-- Insert the effect.
if (effect and bus) then
   bus:insertEffect(effect, 1)
end

Jump to Top

appendEffect

appendEffect(effect)

Description

Function to add an effect to the specified destination bus. The destination bus is determined by its Bus object. You can use getBus or findBusses to determine the destination bus. The effect to be added is determined by its Effect object. You can use getEffect or findEffects to determine the effect. The new effect will be added behind the existing effects. To insert an effect at a specific position in the bus, use insertEffect instead.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, an Element object that you retrieved from the running plug-in instance must be removed before it can be inserted again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be inserted freely, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Example

To explore the following script:

1. Download Program.vstpreset.
2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
3. Create an empty program and add a script module.
4. Paste the script into the text editor of the script module and execute the script.

-- Insert an effect from Program.vstpreset into the current program.
  
-- Get the file path for user VST presets.
path = getUserPresetPath()
  
-- Load the VST preset.
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")
  
-- Get the first effect from the loaded program.
effect = loadedProgram:getBus():getEffect()
  
-- Get the first bus of this program.
bus = this.program:getBus()
  
-- Append the effect.
if (insert and bus) then
    bus:appendEffect(effect)
end

Jump to Top

removeEffect

removeEffect(effectOrPosition)

Description

Function to remove an effect from a bus. You can use getBus or findBusses to define the bus that contains the effect. The effect to be removed is determined by its Effect object or its position. You can use getEffect or findEffects to determine the Effect object. The position is the number indexing the effects in the bus.

Available in: Controller.

Arguments

Example

-- Remove all effects from the program.
 
busses = this.program:findBusses(true)
 
for i, bus in ipairs(busses) do
    effects = bus:findEffects(true)
    for j, effect in ipairs(effects) do
        bus:removeEffect(effect)
    end
end

Jump to Top

getOutputBus

getOutputBus()

Description

Function to retrieve the currently assigned output bus of a zone or bus.

Available in: Controller, Processor.

Return Values

Returns the Bus object of the currently assigned output bus or nil if the default routing is used.

Example

-- Raise an error if no output bus is assigned.

zone = this.parent:getZone()

assert(zone:getOutputBus(), "No output bus assigned. The default routing is used!")

Jump to Top

setOutputBus

setOutputBus(bus)

Description

Function to assign the output of a zone or bus to the specified output bus. The sending zone or bus is determined by its Element object. The receiving output bus is specified by its Bus object. Setting the output bus to nil enables the default signal routing for the zone or bus.

❕ Output busses that are higher up in the hierarchy of the Program Tree can be assigned freely. If the sending bus and the receiving output bus have the same parent layer, the output bus must come later in the signal flow.

Available in: Controller.

Arguments

Example

-- Assign the output of the zone to the Master output bus of the plug-in.

zone = this.parent:getZone()
masterbus = this.program.instance:getBus(1)
 
zone:setOutputBus(masterbus)
 
print("Output of "..zone.name.." is assigned to "..masterbus.name..".")

Jump to Top

/ HALion Developer Resource / HALion Script / Class Reference / Element /

Effect

The Effect class inherits all properties and methods of the Element class.

On this page:

Effect Class, Effect Constructor

List of inherited members:

Element

Element Class, findChildren, getChild, getParameter, getParameterDefinition, getParameterNormalized, hasParameter, removeFromParent, setName, setParameter, setParameterNormalized

Classes

Effect Class

Description

The Element object of an effect can be obtained with findEffects or getEffect. It has the following fields.

Available in: Controller, Processor.

Fields

Example

effects = this.program:findEffects(true)

for i , effect in ipairs(effects) do
    print(effect.moduleType)
end

Jump to Top

Constructors

Effect Constructor

Effect(type)

(Since HALion 6.4.0)

Description

Constructor to create a new Effect object of the specified type.

Available in: Controller.

Arguments

Return Values

Returns a new Effect object of the specified type.

Example

-- The following function creates different types of objects in the Program Tree.
-- The objects in the Program Tree do not have a name. You will see only their icons.

function createProgram()
  local inst = this.program.instance
  local prg = Program()
  local bus = Bus()
  prg:appendBus(bus)
  inst:setProgram(prg, 1)
  local layer = Layer()
  prg:appendLayer(layer)
  layer:appendZone(Zone())
  local mm = MidiModule('MIDI Player')
  layer:appendMidiModule(mm)
  local fx = Effect('Distortion')
  bus:appendEffect(fx)
end
 
createProgram()

Jump to Top

/ HALion Developer Resource / HALion Script / Class Reference / Element /

Instance

The Instance class inherits all properties and methods of the Element class.

On this page:

findBusses, findEffects, findSlots, getBus, getSlot, getProgram, setProgram

List of inherited members:

Element

Element Class, findChildren, getChild, getParameter, getParameterDefinition, getParameterNormalized, hasParameter, removeFromParent, setName, setParameter, setParameterNormalized

Methods

findBusses

findBusses(recursive, nameOrFilterFunction)

Description

Function to find busses in the specified Element object. For example, this.parent specifies the parent of the script module as the Element object to be searched in. If recursive is set to true, subelements will also be searched. The function returns an array with the Bus objects of the found busses. Particular busses can be searched by name or via a filter function. If searching by name, findBusses accepts only the Bus objects that match the specified name. The filter function uses the Bus object of each bus as argument. Only those Bus objects that return true for the search criteria defined in the filter function will be accepted by findBusses. Without a name or filter function, the Bus objects of all busses in the searched Element obects will be returned.

Available in: Controller, Processor.

Arguments

Return Values

Returns an array with the Bus objects of the found busses. Returns an empty table if no busses are found.

Example

-- Find all busses and print their names.
busses = this.program:findBusses(true)
 
if busses[1] then
    for i, bus in ipairs(busses) do
        print(bus.name)
    end
else
    print("Could not find any busses!")
end

Jump to Top

findEffects

findEffects(recursive, nameOrFilterFunction)

Description

Function to find effects in the specified Element object. For example, this.parent specifies the parent of the script module as the Element object to be searched in. To specifiy a bus to be searched in, use getBus or findBusses. If recursive is set to true, subelements will also be searched. The function returns an array with the Effect objects of the found effects. Particular effects can be searched by name or via a filter function. If searching by name, findEffects accepts only the Effect objects that match the specified name. The filter function uses the Effect object of each effect as argument. Only those Effect objects that return true for the search criteria defined in the filter function will be accepted by findEffects. Without a name or filter function, the Effect objects of all effects in the searched Element objects will be returned.

Available in: Controller, Processor.

Arguments

Return Values

Returns an array with the Effect objects of the found effects. Returns an empty table if no effects are found.

Example

-- Find all effects and print their names.
effects = this.program:findEffects(true)
 
if effects[1] then
    for i, effect in ipairs(effects) do
        print(effect.name)
    end
else
    print("Could not find any effects!")
end

Jump to Top

findSlots

findSlots(nameOrFilterFunction)

Description

Function to find the slots of the plug-in instance. Before calling this function you must access the Instance object with this.program.instance. The function returns an array with the Slot objects of the found slots. Particular slots can be searched by name or via a filter function. If searching by name, findSlots accepts only the Slot objects that match the specified name. The filter function uses the Slot object of each slot as argument. Only those Slot objects that return true for the search criteria defined in the filter function will be accepted by findSlots. Without a name or filter function, the Slot objects of all slots in the instance will be returned.

Available in: Controller, Processor.

Arguments

Return Values

Returns an array with the Slot objects of the found slots. Returns an empty table if no slots are found.

Example

-- Print the names of all slots.

slots = this.program.instance:findSlots()
  
for i, slot in ipairs(slots) do
        print(slot.name)
end

Jump to Top

getBus

getBus(nameOrPosition)

Description

Function to retrieve the Bus object of a bus in the specified Element object. For example, this.parent specifies the parent of the script module as the Element object to be searched in. This function does not search in subelements. A particular bus can be searched by name or position. The position is the number indexing the busses in the specified Element object. If several busses share the same name, only the first match will be returned. If no argument is set, the function returns the first bus it finds.

Available in: Controller, Processor.

Arguments

Return Values

Returns the Bus object of the found bus. Returns nil if no bus is found.

Example

-- Locate the first bus in the program and print its name.

bus = this.program:getBus()
 
if bus then
    print(bus.name)
else
    print("Could not find a bus!")
end

Jump to Top

getSlot

getSlot(nameOrIndex)

Description

Function to retrieve the Slot object of a slot of the plug-in instance. Before calling this function you must access the Instance object with this.program.instance. A particular slot can be searched by name or index. The index equals the slot numbering in the Slot Rack. If no argument is set, the function returns the first slot it finds.

Available in: Controller, Processor.

Arguments

Return Values

Returns the Slot object of the found slot. Returns nil if no slot is found.

Example

-- Print the name of slot index 3.

slot = this.program.instance:getSlot(3)

print(slot.name)

Jump to Top

getProgram

getProgram(index)

Description

Function to retrieve the Program object of a program in the Program Table of the plug-in instance. Before calling this function you must access the Instance object with this.program.instance. The index corresponds to the number of the slot in the Program Table where the program is set. The function returns the Program object of the program with the specified index.

Available in: Controller.

Arguments

Return Values

Returns the Program object of the program with the specified index.

Example

-- Print the name of the program in the third slot of the Program Table.

program = this.program.instance:getProgram(3)
print(program.name)

Jump to Top

setProgram

setProgram(programOrNil, index)

Description

Function to set a program in the specified slot of the Program Table or the Slot Rack of the plug-in instance. Before calling this function, you must access the Instance object with this.program.instance. The program is determined by its Program object. To specify the slot in the Program Table, you must use the index argument. To specify the slot in the Slot Rack, you must use a Slot object, for example, via getSlot. The program can be removed from the Slot Rack by using nil as argument.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, each program can exist only once in the Program Table. Furthermore, an Element object that you retrieved from the running plug-in instance cannot be added twice to the Program Table. It must be removed before it can be added again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be added freely to the Program Table, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Example

To explore the following script:

1. Download Program.vstpreset.
2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
3. Create an empty program and add a script module.
4. Paste the script into the text editor of the script module and execute the script.

-- Set Program.vstpreset in slot 3 of the Program Table and slot 1 of the Slot Rack.
     
-- Get the file path for user VST presets.
path = getUserPresetPath()
     
-- Load the VST preset.
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")
  
-- Set loadedProgram in slot 3 of the Program Table.
this.program.instance:setProgram(loadedProgram, 3)
 
-- Set program in slot 1 of the Slot Rack.
program = this.program.instance:getProgram(3)
this.program.instance:getSlot(1):setProgram(program)
  
-- Clear slot 2 of the Slot Rack.
this.program.instance:getSlot(2):setProgram(nil)

Jump to Top

/ HALion Developer Resource / HALion Script / Class Reference / Element /

Layer

The Layer class inherits all properties and methods of the Element class.

On this page:

appendBus, appendLayer, appendLayerAsync, appendMidiModule, appendZone, findBusses, findEffects, findLayers, findMidiModules, findZones, getBus, getLayer, getMidiModule, getZone, insertBus, insertLayer, insertLayerAsync, insertMidiModule, insertZone, removeBus, removeLayer, removeMidiModule, removeZone, addQCAssignment, removeQCAssignment, getNumQCAssignments, getQCAssignmentParamId, getQCAssignmentScope, getQCAssignmentMin, getQCAssignmentMax, getQCAssignmentCurve, getQCAssignmentMode, getQCAssignmentBypass, setQCAssignmentParamId, setQCAssignmentScope, setQCAssignmentMin, setQCAssignmentMax, setQCAssignmentCurve, setQCAssignmentMode, setQCAssignmentBypass

List of inherited members:

Element

Element Class, findChildren, getChild, getParameter, getParameterDefinition, getParameterNormalized, hasParameter, removeFromParent, setName, setParameter, setParameterNormalized

Constructors

Layer Constructor

Layer()

(Since HALion 6.4.0)

Description

Constructor to create a new Layer object.

Available in: Controller.

Return Values

Returns a new Layer object.

Example

-- The following function creates different types of objects in the Program Tree.
-- The objects in the Program Tree do not have a name. You will see only their icons.

function createProgram()
  local inst = this.program.instance
  local prg = Program()
  local bus = Bus()
  prg:appendBus(bus)
  inst:setProgram(prg, 1)
  local layer = Layer()
  prg:appendLayer(layer)
  layer:appendZone(Zone())
  local mm = MidiModule('MIDI Player')
  layer:appendMidiModule(mm)
  local fx = Effect('Distortion')
  bus:appendEffect(fx)
end
 
createProgram()

Jump to Top

Methods

appendBus

appendBus(bus)

Description

Function to add a bus in the specified destination layer. The destination layer is determined by its Layer object. For example, this.parent specifies the parent layer of the script module as destination layer. The bus to be added is determined by its Bus object. You can use getBus or findBusses to determine the bus. The new bus will be added behind the existing busses. To insert a bus at a specific position in the destination layer, use insertBus instead.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, an Element object that you retrieved from the running plug-in instance must be removed before it can be inserted again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be inserted freely, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Example

To explore the following script:

1. Download Program.vstpreset.
2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
3. Create an empty program and add a script module.
4. Paste the script into the text editor of the script module and execute the script.

-- Append the bus from Program.vstpreset into the current program.
   
-- Get the file path for user VST presets.
path = getUserPresetPath()
   
-- Load the VST preset.
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")
   
-- Get the first bus from the loaded program.
bus = loadedProgram:getBus()
   
-- Append the bus.
if bus then
    this.program:appendBus(bus)
end

Jump to Top

appendLayer

appendLayer(layer)

Description

Function to add a layer in the specified destination layer. The layer to be added and the destination layer are both determined by their Layer objects. You can use getLayer or findLayers to determine the layer to be added. For example, this.parent defines the parent layer of the script module as destination layer. The new layer will be added behind the existing layers. To insert a layer at a specific position in the destination layer, use insertLayer or insertLayerAsync instead.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, an Element object that you retrieved from the running plug-in instance must be removed before it can be inserted again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be inserted freely, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Example

To explore the following script:

1. Download Program.vstpreset.
2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
3. Create an empty program and add a script module.
4. Paste the script into the text editor of the script module and execute the script.

-- Append the layer from Program.vstpreset into the current program.
    
-- Get the file path for user VST presets.
path = getUserPresetPath()
    
-- Load the VST preset.
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")
    
-- Get the first layer from the loaded program.
layer = loadedProgram:getLayer ()
    
-- Append the layer.
if layer then
    this.program:appendLayer(layer)
end

Jump to Top

appendLayerAsync

appendLayerAsync(layer, callback)

Description

Function to add a layer in the specified destination layer using a separate, parallel thread. Appending a layer in a separate thread can be necessary if the layer is too big to be added in a short time. The layer to be inserted and the destination layer are both determined by their Layer objects. You can use getLayer or findLayers to determine the layer to be inserted. For example, this.parent determines the parent layer of the script module as destination layer. The new layer will be added behind the existing layers. To insert a layer at a specific position in the destination layer, use insertLayer or insertLayerAsync instead. The function returns a LoadProgress object that can be used to monitor the load progress. After the layer is added, the callback function is called. The callback function gets the LoadProgress object as default argument.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, an Element object that you retrieved from the running plug-in instance must be removed before it can be inserted again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be inserted freely, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Return Values

Returns a LoadProgress object.

Example

-- Start with an empty program, remove any existing layers.

layers = this.parent:findLayers()
 
if layers then
   for i, layer in ipairs(layers) do
       this.parent:removeLayer(layer)
   end
end
 
-- Table with layer presets from Skylab.
layerPresets = {
   { name = "Ambient Pad 01", path = "vstsound://724ACB205EFF46F885735D1B216C37AD/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 01.vstpreset" },
   { name = "Ambient Pad 02", path = "vstsound://724ACB205EFF46F885735D1B216C37AD/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 02.vstpreset" },
   { name = "Ambient Pad 03", path = "vstsound://724ACB205EFF46F885735D1B216C37AD/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 03.vstpreset" },
   { name = "Ambient Pad 04", path = "vstsound://724ACB205EFF46F885735D1B216C37AD/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 04.vstpreset" },
}
-- Create a table with the preset names.
function getPresetNames()
   presetNames = {}
   for i, preset in ipairs(layerPresets) do
       presetNames[i] = preset.name
   end
end
 
getPresetNames()
 
-- Remove the old layer after the new one was added.
function removeOldLayer(progressInfo)
   local newPreset = progressInfo.root
   if oldPreset then
       this.parent:removeLayer(oldPreset)
       print(oldPreset.name.." removed.")
   end
   oldPreset = newPreset
end
 
-- Append the preset in a separate thread.
function appendNewLayer(progressInfo)
   if progressInfo.root then
       this.parent:appendLayerAsync(progressInfo.root, removeOldLayer)
       print("Appending "..progressInfo.root.name.."...")
   end
end
 
-- Load the preset in a separate thread.
function onSelectPresetChanged()
   progress = 0
   progressInf = loadPresetAsync(layerPresets[SelectPreset].path, appendNewLayer)
   print("Loading "..layerPresets[SelectPreset].name.."...")
end
 
-- Define a parameter for selecting the preset to be loaded.
defineParameter("SelectPreset", "Select Preset", 1, presetNames, onSelectPresetChanged)
 
-- Monitor the load progress with onIdle.
progress = 1
function onIdle()
   if progress < 1 then
       progress = progressInf.progress
       print("Progress: "..(progressInf.progress * 100).."%")
   end
end

Jump to Top

appendMidiModule

appendMidiModule(module)

Description

Function to add a MIDI module in the specified destination layer. The destination layer is determined by its Layer object. For example, this.parent specifies the parent layer of the script module as destination layer. The MIDI module to be added is determined by its MidiModule object. You can use getMidiModule or findMidiModules to determine the desired MIDI module. The new MIDI module will be added behind the existing MIDI modules. To insert a MIDI module at a specific position in the destination layer, use insertMidiModule instead.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, an Element object that you retrieved from the running plug-in instance must be removed before it can be inserted again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be inserted freely, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Example

To explore the following script:

1. Download Program.vstpreset.
2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
3. Create an empty program and add a script module.
4. Paste the script into the text editor of the script module and execute the script.

-- Append a MIDI module from Program.vstpreset into the current program.
    
-- Get the file path for user VST presets.
path = getUserPresetPath()
    
-- Load the VST preset.
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")
    
-- Get the first MIDI module from the loaded program.
module = loadedProgram:getMidiModule()
    
-- Append the MIDI module.
if module then
    this.program:appendMidiModule(module)
end

Jump to Top

appendZone

appendZone(zone)

Description

Function to add a zone in the specified destination layer. The destination layer is determined by its Layer object. For example, this.parent specifies the parent layer of the script module as destination layer. The zone to be added is determined by its Zone object. You can use getZone or findZones to determine the zone. The new zone will be added behind the existing zones. To insert a zone at a specific position in the destination layer, use insertZone instead.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, an Element object that you retrieved from the running plug-in instance must be removed before it can be inserted again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be inserted freely, because these functions create a copy of the Element objects when reading them.

Available in: Controller, Processor.

Arguments

Example

To explore the following script:

1. Download Program.vstpreset.
2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
3. Create an empty program and add a script module.
4. Paste the script into the text editor of the script module and execute the script.

-- Append a zone from Program.vstpreset into the current program.
    
-- Get the file path for user VST presets.
path = getUserPresetPath()
    
-- Load the VST preset.
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")
    
-- Get the first zone from the loaded program.
zone = loadedProgram:getZone()
    
-- Append the zone.
if zone then
    this.program:appendZone(zone)
end

Jump to Top

findBusses

findBusses(recursive, nameOrFilterFunction)

Description

Function to find busses in the specified Element object. For example, this.parent specifies the parent of the script module as the Element object to be searched in. If recursive is set to true, subelements will also be searched. The function returns an array with the Bus objects of the found busses. Particular busses can be searched by name or via a filter function. If searching by name, findBusses accepts only the Bus objects that match the specified name. The filter function uses the Bus object of each bus as argument. Only those Bus objects that return true for the search criteria defined in the filter function will be accepted by findBusses. Without a name or filter function, the Bus objects of all busses in the searched Element obects will be returned.

Available in: Controller, Processor.

Arguments

Return Values

Returns an array with the Bus objects of the found busses. Returns an empty table if no busses are found.

Example

-- Find all busses and print their names.
busses = this.program:findBusses(true)
 
if busses[1] then
    for i, bus in ipairs(busses) do
        print(bus.name)
    end
else
    print("Could not find any busses!")
end

Jump to Top

findEffects

findEffects(recursive, nameOrFilterFunction)

Description

Function to find effects in the specified Element object. For example, this.parent specifies the parent of the script module as the Element object to be searched in. To specifiy a bus to be searched in, use getBus or findBusses. If recursive is set to true, subelements will also be searched. The function returns an array with the Effect objects of the found effects. Particular effects can be searched by name or via a filter function. If searching by name, findEffects accepts only the Effect objects that match the specified name. The filter function uses the Effect object of each effect as argument. Only those Effect objects that return true for the search criteria defined in the filter function will be accepted by findEffects. Without a name or filter function, the Effect objects of all effects in the searched Element objects will be returned.

Available in: Controller, Processor.

Arguments

Return Values

Returns an array with the Effect objects of the found effects. Returns an empty table if no effects are found.

Example

-- Find all effects and print their names.
effects = this.program:findEffects(true)
 
if effects[1] then
    for i, effect in ipairs(effects) do
        print(effect.name)
    end
else
    print("Could not find any effects!")
end

Jump to Top

findLayers

findLayers(recursive, nameOrFilterFunction)

Description

Function to find layers in the specified layer. For example, this.parent specifies the parent layer of the script module as the layer to be searched in. If recursive is set to true, sublayers will also be searched. The function returns an array with the Layer objects of the found layers. Particular layers can be searched by name or via a filter function. If searching by name, findLayers accepts only the Layer objects that match the specified name. The filter function uses the Layer object of each layer as argument. Only those Layer objects that return true for the search criteria defined in the filter function will be accepted by findLayers. Without a name or filter function, the Layer objects of all layers in the searched layers will be returned.

Available in: Controller, Processor.

Arguments

Return Values

Returns an array with the Layer objects of the found layers. Returns an empty table if no layers are found.

Example

-- Find all layers and print their names.

layers = this.program:findLayers(true)
 
if layers[1] then
    for i, layer in ipairs(layers) do
        print(layer.name)
    end
else
    print("Could not find any layers!")
end

Jump to Top

findMidiModules

findMidiModules(recursive, nameOrFilterFunction)

Description

Function to find MIDI modules in the specified layer. For example, this.parent specifies the parent layer of the script module as the layer to be searched in. If recursive is set to true, sublayers will also be searched. The function returns an array with the MidiModule objects of the found MIDI modules. Particular MIDI modules can be searched by name or via a filter function. If searching by name, findMidiModules accepts only the MidiModule objects that match the specified name. The filter function uses the MidiModule object of each MIDI module as argument. Only those MidiModule objects that return true for the search criteria defined in the filter function will be accepted by findMidiModules. Without a name or filter function, the MidiModule objects of all MIDI modules in the searched layers will be returned.

Available in: Controller, Processor.

Arguments

Return Values

Returns an array with the MidiModule objects of the found MIDI modules. Returns an empty table if no MIDI modules are found.

Example

-- Find all MIDI modules and print their names.

modules = this.program:findMidiModules(true)
 
if modules[1] then
    for i, module in ipairs(modules) do
        print(module.name)
    end
else
    print("Could not find any MIDI modules!")
end

Jump to Top

findZones

findZones(recursive, nameOrFilterFunction)

Description

Function to find zones in the specified layer. For example, this.parent defines the parent layer of the script module as the layer to be searched in. If recursive is set to true, sublayers will also be searched. The function returns an array with the Zone objects of the found zones. Particular zones can be searched by name or via a filter function. If searching by name, findZones accepts only the Zone objects that match the specified name. The filter function uses the Zone object of each zone as argument. Only those Zone objects that return true for the search criteria defined in the filter function will be accepted by findZones. Without a name or filter function, the Zone objects of all zones in the searched layers will be returned.

Available in: Controller, Processor.

Arguments

Return Values

Returns an array with the Zone objects of the found zones. Returns an empty table if no zones are found.

Example

-- Find all zones and print their names.

zones = this.program:findZones(true)
 
if zones[1] then
    for i, zone in ipairs(zones) do
        print(zone.name)
    end
else
    print("Could not find any zones!")
end

Jump to Top

getBus

getBus(nameOrPosition)

Description

Function to retrieve the Bus object of a bus in the specified Element object. For example, this.parent specifies the parent of the script module as the Element object to be searched in. This function does not search in subelements. A particular bus can be searched by name or position. The position is the number indexing the busses in the specified Element object. If several busses share the same name, only the first match will be returned. If no argument is set, the function returns the first bus it finds.

Available in: Controller, Processor.

Arguments

Return Values

Returns the Bus object of the found bus. Returns nil if no bus is found.

Example

-- Locate the first bus in the program and print its name.

bus = this.program:getBus()
 
if bus then
    print(bus.name)
else
    print("Could not find a bus!")
end

Jump to Top

getLayer

getLayer(nameOrPosition)

Description

Function to retrieve the Layer object of a layer in the specified layer. For example, this.parent specifies the parent layer of the script module as the layer to be searched in. The function does not search in sublayers. A particular layer can be searched by name or position. The position is the number indexing the layers in the specified layer. If several layers share the same name, only the first match will be returned. If no argument is set, the function returns the first layer it finds.

Available in: Controller, Processor.

Arguments

Return Values

Returns the Layer object of the found layer. Returns nil if no layer is found.

Example

-- Locate the first layer in the program and print its name.

layer = this.program:getLayer()
 
if layer then
    print(layer.name)
else
    print("Could not find a layer!")
end

Jump to Top

getMidiModule

getMidiModule(nameOrPosition)

Description

Function to retrieve the MidiModule object of a MIDI module in the specified layer. For example, this.parent defines the parent layer of the script module as the layer to be searched in. This function does not search in sublayers. A particular MIDI module can be searched by name or position. The position is the number indexing the MIDI modules in the specified layer. If several MIDI modules share the same name, only the first match will be returned. If no argument is set, the function returns the first MIDI module it finds.

Available in: Controller, Processor.

Arguments

Return Values

Returns the MidiModule object of the found MIDI module. Returns nil if no MIDI module is found.

Example

-- Locate the first MIDI module in the program and print its name.

module = this.program:getMidiModule()
 
if module then
    print(module.name)
else
    print("Could not find a MIDI module!")
end

Jump to Top

getZone

getZone(nameOrPosition)

Description

Function to retrieve the Zone object of a zone in the specified layer. For example, this.parent defines the parent layer of the script module as the layer to be searched in. This function does not search in sublayers. A particular zone can be searched by name or position. The position is the number indexing the zones in the specified layer. If several zones share the same name, only the first match will be returned. If no argument is set, the function returns the first zone it finds.

Available in: Controller, Processor.

Arguments

Return Values

Returns the Zone object of the found zone. Returns nil if no zone is found.

Example

-- Get the first zone in the program and print its name.

zone = this.program:getZone()
 
if zone then
    print(zone.name)
else
    print("Could not find a zone!")
end

Jump to Top

insertBus

insertBus(bus, position)

Description

Function to insert a bus at the specified position in the destination layer. The bus to be inserted is determined by its Bus object. You can use getBus or findBusses to determine the bus. The destination layer is determined by its Layer object. For example, this.parent sets the parent layer of the script module as destination layer. The position is the number indexing the existing busses in the destination layer. The new bus will be inserted before the specified position. To add the bus at the end, use appendBus instead.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, an Element object that you retrieved from the running plug-in instance must be removed before it can be inserted again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be inserted freely, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Example

To explore the following script:

1. Download Program.vstpreset.
2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
3. Create an empty program and add a script module.
4. Paste the script into the text editor of the script module and execute the script.

-- Insert the bus from Program.vstpreset into the current program.
  
-- Get the file path for user VST presets.
path = getUserPresetPath()
  
-- Load the VST preset.
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")
  
-- Get the first bus from the loaded program.
bus = loadedProgram:getBus()
  
-- Insert the bus.
if bus then
    this.program:insertBus(bus, 1)
end

Jump to Top

insertLayer

insertLayer(layer, position)

Description

Function to insert a layer at a specific position in a destination layer. The layer to be inserted and the destination layer are both determined by their Layer objects. You can use getLayer or findLayers to determine the layer to be inserted. For example, this.parent determines the parent layer of the script module as destination layer. The position is the number indexing the existing layers in the destination layer. The new layer will be inserted before the specified position. To add the layer at the end, use appendLayer or appendLayerAsync instead.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, an Element object that you retrieved from the running plug-in instance must be removed before it can be inserted again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be inserted freely, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Example

To explore the following script:

1. Download Program.vstpreset.
2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
3. Create an empty program and add a script module.
4. Paste the script into the text editor of the script module and execute the script.

-- Insert a layer from Program.vstpreset into the current program.
   
-- Get the file path for user VST presets.
path = getUserPresetPath()
   
-- Load the VST preset.
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")
   
-- Get the first layer from the loaded program.
layer = loadedProgram:getLayer ()
   
-- Insert the layer.
if layer then
    this.program:insertLayer(layer, 1)
end

Jump to Top

insertLayerAsync

insertLayerAsync(layer, position, callback)

Description

Function to insert a layer at a specified position in a destination layer using a separate, parallel thread. Inserting a layer in a separate thread can be necessary if the layer is too big to be inserted in a short time. The layer to be inserted and the destination layer are both determined by their Layer objects. You can use getLayer or findLayers to determine the layer to be inserted. For example, this.parent determines the parent layer of the script module as destination layer. The position is the number indexing the existing layers in the destination layer. The new layer will be inserted before the specified position. To add the layer at the end, use appendLayer or appendLayerAsync instead. The function returns a LoadProgress object that can be used to monitor the load progress. After the layer is inserted, the callback function is called. The callback function gets the LoadProgress object as default argument.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, an Element object that you retrieved from the running plug-in instance must be removed before it can be inserted again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be inserted freely, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Return Values

Returns a LoadProgress object.

Example

-- Start with an empty program, remove all existing layers.
layers = this.parent:findLayers()
 
if layers then
  for i, layer in ipairs(layers) do
      this.parent:removeLayer(layer)
  end
end
 
-- Table with layer presets from Skylab.
layerPresets = {
  { name = "Ambient Pad 01", path = "vstsound://EB86867EFF8E44FEA8FE366F676E25BE/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 01.vstpreset" },
  { name = "Ambient Pad 02", path = "vstsound://EB86867EFF8E44FEA8FE366F676E25BE/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 02.vstpreset" },
  { name = "Ambient Pad 03", path = "vstsound://EB86867EFF8E44FEA8FE366F676E25BE/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 03.vstpreset" },
  { name = "Ambient Pad 04", path = "vstsound://EB86867EFF8E44FEA8FE366F676E25BE/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 04.vstpreset" },
}
 
-- Create a table with the preset names.
function getPresetNames()
  presetNames = {}
  for i, preset in ipairs(layerPresets) do
    presetNames[i] = preset.name
  end
end
 
getPresetNames()
 
-- Remove the old layer after the new one was added.
function removeOldLayer(progressInfo)
  local newPreset = progressInfo.root
  if oldPreset then
    this.parent:removeLayer(oldPreset)
    print(oldPreset.name.." removed.")
  end
  oldPreset = newPreset
end
 
-- Insert the preset in a separate thread.
function insertNewLayer(progressInfo)
  if progressInfo.root then
    this.parent:insertLayerAsync(progressInfo.root, 1, removeOldLayer)
    print("Inserting "..progressInfo.root.name.."...")
  end
end
 
-- Load the preset in a separate thread.
function onSelectPresetChanged(layerPreset)
  loadPresetAsync(layerPreset.path, insertNewLayer)
  print("Loading "..layerPreset.name.."...")
end
 
-- Define a parameter for selecting the preset to be loaded.
defineParameter("SelectPreset",  "Select Preset",  1, presetNames, function() onSelectPresetChanged(layerPresets[SelectPreset]) end)

Jump to Top

insertMidiModule

insertMidiModule(module, position)

Description

Function to insert a MIDI module at the specified position in the determined destination layer. The MIDI module to be inserted is determined by its MidiModule object. You can use getMidiModule or findMidiModules to determine the desired MIDI module. The destination layer is determined by its Layer object. For example, this.parent determines the parent layer of the script module as destination layer. The position is the number indexing the existing MIDI modules in the destination layer. The new MIDI module will be inserted before the specified position. To add the MIDI module at the end, use appendMidiModule instead.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, an Element object that you retrieved from the running plug-in instance must be removed before it can be inserted again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be inserted freely, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Example

To explore the following script:

1. Download Program.vstpreset.
2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
3. Create an empty program and add a script module.
4. Paste the script into the text editor of the script module and execute the script.

-- Insert a MIDI module from Program.vstpreset into the current program.
   
-- Get the file path for user VST presets.
path = getUserPresetPath()
   
-- Load the VST preset.
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")
   
-- Get the first MIDI module from the loaded program.
module = loadedProgram:getMidiModule()
   
-- Insert the MIDI module.
if module then
    this.program:insertMidiModule(module, 1)
end

Jump to Top

insertZone

insertZone(zone, position)

Description

Function to insert a zone at the specified position in the determined layer. The zone to be inserted is determined by its Zone object. You can use getZone or findZones to determine the desired zone. The destination layer is determined by its Layer object. For example, this.parent determines the parent layer of the script module as destination layer. The position is the number indexing the existing zones in the destination layer. The new zone will be inserted before the specified position. To add the zone at the end, use appendZone instead.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, an Element object that you retrieved from the running plug-in instance must be removed before it can be inserted again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be inserted freely, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Example

To explore the following script:

1. Download Program.vstpreset.
2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
3. Create an empty program and add a script module.
4. Paste the script into the text editor of the script module and execute the script.

-- Insert a zone from Program.vstpreset into the current program.
   
-- Get the file path for user VST presets.
path = getUserPresetPath()
   
-- Load the VST preset.
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")
   
-- Get the first zone from the loaded program.
zone = loadedProgram:getZone()
   
-- Insert the zone.
if zone then
    this.program:insertZone(zone, 1)
end

Jump to Top

removeBus

removeBus(busOrPosition)

Description

Function to remove a bus from the specified layer. For example, this.parent specifies the parent layer of the script module as the layer that contains the bus. The bus to be removed is determined by its Bus object or its position. You can use getBus or findBusses to determine the Bus object. The position is the number that indexes the busses in the specified layer.

Available in: Controller.

Arguments

Example

-- Remove all busses from the program.
    
busses = this.program:findBusses(true)

for i, bus in ipairs(busses) do
    this.parent:removeBus(bus)
end

Jump to Top

removeLayer

removeLayer(layerOrPosition)

Description

Function to remove a layer from the specified layer. For example, this.parent specifies the parent layer of the script module as the layer that contains the layer to be removed. The layer is determined by its Layer object or its position. You can use getLayer or findLayers to determine the Layer object. The position is the number indexing the layers within the specified layer.

Available in: Controller.

Arguments

Example

-- Remove all layers from the program.

layers = this.program:findLayers(true)

for i, layer in ipairs(layers) do
    layer.parent:removeLayer(layer)
end

Jump to Top

removeMidiModule

removeMidiModule(moduleOrPosition)

Description

Function to remove a MIDI module from the specified layer. For example, this.parent specifies the parent layer of the script module as the layer that contains the MIDI module. The MIDI module to be removed is determined by its MidiModule object or its position. You can use getMidiModule or findMidiModules to determine the MidiModule object. The position is the number that indexes the MIDI modules in the specified layer.

Available in: Controller.

Arguments

Example

-- Remove all MIDI modules from the program except the script module.

modules = this.program:findMidiModules(true)

for i, module in ipairs(modules) do
    if module ~= this then -- Exclude script module.
        module.parent:removeMidiModule(module)
    end
end

Jump to Top

removeZone

removeZone(zoneOrPosition)

Description

Function to remove a zone from the specified layer. For example, this.parent specifies the parent layer of the script module as the layer that contains the zone. The zone to be removed is determined by its Zone object or its position. You can use getZone or findZones to determine the Zone object. The position is the number that indexes the zones in the specified layer.

Available in: Controller.

Arguments

Example

-- Remove all zones from the program.

zones = this.program:findZones(true)

for i, zone in ipairs(zones) do
    zone.parent:removeZone(zone)
end

Jump to Top

addQCAssignment

addQCAssignment(qc, element, nameOrID, scope)

Description

Function to add a quick control assignment to the specified layer and quick control. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control that you want to edit. The quick control assignment will be added to the quick control with the index stated by the qc argument. The arguments element and nameOrID specify the parameter to be connected. The scope determines the part of the program that will be affected by the quick control assignment. You specify the scope by setting the scope argument to the Element object that corresponds to the desired part of the program.

❕ The index of the quick controls starts counting from 1. QC 1 to QC 8 have index 1 to 8. Sphere H, Sphere V and Mod Wheel have index 9, 10 and 11.

Available in: Controller.

Arguments

Example

-- Assign the octave parameter of the zone to the
-- first quick control of the script module's parent layer.

layer = this.parent
zones = layer:findZones(true)
 
layer:addQCAssignment(1, zones[1], "Pitch.Octave", layer)

Jump to Top

removeQCAssignment

removeQCAssignment(qc, assignment)

Description

Function to remove a quick control assignment from the specified layer and quick control. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control with the assignment to be removed. The assignment argument is the index of the quick control assignment to be removed. The indices of the quick controls and the assignments both start counting from 1.

Available in: Controller.

Arguments

Example

-- Remove all quick control assignments from the specified layer and qc.
 
function clearQC(layer, qc)
    local assignments = layer:getNumQCAssignments(qc)
    if assignments > 0 then
        for i = assignments, 1, -1 do
            layer:removeQCAssignment(qc, i)
        end
        print(assignments.." assignments have been removed from '"..layer.name.."', QC "..qc..".")
    else
        print("No assignments found on '"..layer.name.."', QC "..qc..".")
    end
end
 
clearQC(this.parent, 1)

Jump to Top

getNumQCAssignments

getNumQCAssignments(qc)

Description

Function to retrieve the number of assignments of a quick control on the specified layer. For example, this.parent defines the parent layer of the script module as the layer with the desired quick control. The qc argument is the index of the quick control with the requested assignments.

Available in: Controller.

Arguments

Return Values

Returns the number of assignments of the specified layer and quick control.

Example

-- Print the number of assignments of the first quick control on the parent layer.

layer = this.parent
qc = 1
 
print("Number of assignments on '"..layer.name.."', QC "..qc..": "..layer:getNumQCAssignments(qc)..".")

Jump to Top

getQCAssignmentParamId

getQCAssignmentParamId(qc, assignment)

Description

Function to retrieve the parameter ID of the parameter that is connected to the specified quick control assignment. The quick control assignment is determined by the Layer object, the index of the quick control and the index of the assignment itself. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control and the assignment argument is the index of the assignment with the requested parameter. The indices of the quick controls and the assignments both start counting from 1.

Available in: Controller.

Arguments

Return Values

Returns the parameter ID of the parameter connected to the specified quick control assignment.

Example

-- Print the parameter ID of the parameter connected to the qc assignment.

layer = this.parent
qc = 1
assignment = 1
 
paramID = layer:getQCAssignmentParamId(qc, assignment)
 
print("Parameter ID of '"..layer.name.."', QC "..qc..", assignment "..assignment..": "..paramID..".")

Jump to Top

getQCAssignmentScope

getQCAssignmentScope(qc, assignment)

Description

Function to retrieve the Element object that is set as scope for the specified quick control assignment. The quick control assignment is determined by the Layer object of the layer, the index of the quick control and the index of the assignment itself. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control and the assignment argument is the index of the assignment with the requested scope. The indices of the quick controls and the assignments both start counting from 1.

Available in: Controller.

Arguments

Return Values

Returns the element object that is set as scope for the specified quick control assignment.

Example

-- Print the scope for the qc assignment.

layer = this.parent
qc = 1
assignment = 1
 
scope = layer:getQCAssignmentScope(qc, assignment).name -- use only the name of the returned element
 
print("Scope of '"..layer.name.."', QC "..qc..", assignment "..assignment..": "..scope..".")

Jump to Top

getQCAssignmentMin

getQCAssignmentMin(qc, assignment)

Description

Function to retrieve the minimum value of the specified quick control assignment. The quick control assignment is determined by the Layer object, the index of the quick control and the index of the assignment itself. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control and the assignment argument is the index of the assignment with the requested minimum value. The indices of the quick controls and the assignments both start counting from 1.

Available in: Controller.

Arguments

Return Values

Returns the minimum value of the specified quick control assignment.

❕ The value range is always 0 to 100 %, even if the mode of the quick control assignment is set to Relative or Switch Relative.

Example

-- Print the minimum value of the qc assignment as displayed in HALion.
layer = this.parent
qc = 1
assignment = 1
 
qcMode = layer:getQCAssignmentMode(qc, assignment)
qcMin = layer:getQCAssignmentMin(qc, assignment)
 
-- Convert to bipolar range if the qc is of the type relative or switch relative.
if (qcMode == QCAssignmentMode.relative or qcMode == QCAssignmentMode.switchRelative) then
    qcMin = qcMin * 2 - 100
end
  
print("Minimum value of '"..layer.name.."', QC "..qc..", assignment "..assignment..": "..qcMin..".")

Jump to Top

getQCAssignmentMax

getQCAssignmentMax(qc, assignment)

Description

Function to retrieve the maximum value of the specified quick control assignment. The quick control assignment is determined by the Layer object, the index of the quick control and the index of the assignment itself. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control and the assignment argument is the index of the assignment with the requested maximum value. The indices of the quick controls and the assignments both start counting from 1.

Available in: Controller.

Arguments

Return Values

Returns the maximum value of the specified quick control assignment.

❕ The value range is always 0 to 100 %, even if the mode of the quick control assignment is set to Relative or Switch Relative.

Example

-- Print the maximum value of the qc assignment as displayed in HALion.

layer = this.parent
qc = 1
assignment = 1
  
qcMode = layer:getQCAssignmentMode(qc, assignment)
qcMax = layer:getQCAssignmentMax(qc, assignment)
  
-- Convert to bipolar range if the qc is of the type relative or switch relative.

if (qcMode == QCAssignmentMode.relative or qcMode == QCAssignmentMode.switchRelative) then
    qcMax = qcMax * 2 - 100
end
   
print("Maximum value of '"..layer.name.."', QC "..qc..", assignment "..assignment..": "..qcMax..".")

Jump to Top

getQCAssignmentCurve

getQCAssignmentCurve(qc, assignment)

Description

Function to retrieve the curve value of the specified quick control assignment. The quick control assignment is determined by the Layer object, the index of the quick control and the index of the assignment itself. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control and the assignment argument is the index of the assignment with the requested curve value. The indices of the quick controls and the assignments both start counting from 1.

Available in: Controller.

Arguments

Return Values

Returns the curve value of the specified quick control assignment. The value range is -100% to +100%.

Example

-- Print the curve value of the qc assignment.

layer = this.parent
qc = 1
assignment = 1
  
qcCurve = layer:getQCAssignmentCurve(qc, assignment)
   
print("Curve value of '"..layer.name.."', QC "..qc..", assignment "..assignment..": "..qcCurve..".")

Jump to Top

getQCAssignmentMode

getQCAssignmentMode(qc, assignment)

Description

Function to retrieve the mode that is set for the specified quick control assignment. The quick control assignment is determined by the Layer object, the index of the quick control and the index of the assignment itself. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control and the assignment argument is the index of the assignment with the requested mode. The indices of the quick controls and the assignments both start counting from 1.

Available in: Controller, Processor.

Arguments

Return Values

Returns the mode that is set for the specified quick control assignment as a number. The mode can be determined via names or indices. See Quick Control Assignment Modes for details.

Example

-- Print the mode of the qc assignment.
layer = this.parent
qc = 1
assignment = 1
   
qcMode = layer:getQCAssignmentMode(qc, assignment)
  
if qcMode == QCAssignmentMode.absolute then
    qcModeName = "Absolute"
elseif qcMode == QCAssignmentMode.relative then
    qcModeName = "Relative"
elseif qcMode == QCAssignmentMode.switch then
    qcModeName = "Switch"
elseif qcMode == QCAssignmentMode.switchRelative then
    qcModeName = "Switch Relative"
end
    
print("Mode of '"..layer.name.."', QC "..qc..", assignment "..assignment..": "..qcModeName..".")

Jump to Top

getQCAssignmentBypass

getQCAssignmentBypass(qc, assignment)

Description

Function to retrieve the bypass state of the specified quick control assignment. The quick control assignment is determined by the Layer object, the index of the quick control and the index of the assignment itself. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control and the assignment argument is the index of the assignment with the requested bypass state. The indices of the quick controls and the assignments both start counting from 1.

Available in: Controller.

Arguments

Return Values

Returns the bypass state of the specified quick control assignment as boolean value.

Example

-- Print the bypass state of the qc assignment.

layer = this.parent
qc = 1
assignment = 1
   
qcBypass = layer:getQCAssignmentBypass(qc, assignment)
    
print("Bypass of '"..layer.name.."', QC "..qc..", assignment "..assignment..": "..tostring(qcBypass)..".")

Jump to Top

setQCAssignmentParamId

setQCAssignmentParamId(qc, assignment, paramID)

Description

Function to set the parameter ID for connecting the corresponding parameter to the specified quick control assignment. The quick control assignment is determined by the Layer object, the index of the quick control and the index of the assignment itself. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control and the assignment argument is the index of the assignment. The indices of the quick controls and the assignments both start counting from 1. The paramID argument selects the parameter to be connected with the quick control assignment.

Available in: Controller.

Arguments

Example

-- Connect the coarse parameter of the zone to the specified quick control assignment.

layer = this.parent
zones = layer:findZones(true)
zone = zones[1]
qc = 1
assignment = 1
coarseParamID = zone:getParameterDefinition("Pitch.Coarse").id
  
layer:setQCAssignmentParamId(qc, assignment, coarseParamID)

Jump to Top

setQCAssignmentScope

setQCAssignmentScope(qc, assignment, scope)

Description

Function to set the scope for the specified quick control assignment. The quick control assignment is determined by the Layer object, the index of the quick control and the index of the assignment itself. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control and the assignment argument is the index of the assignment. The indices of the quick controls and the assignments both start counting from 1. The scope is defined by the Element object that you assign to the scope argument.

Available in: Controller.

Arguments

Example

-- Set the scope to the first zone that was found.

layer = this.parent
zones = layer:findZones(true)
zone = zones[1]
qc = 1
assignment = 1
   
layer:setQCAssignmentScope(qc, assignment, zone)

Jump to Top

setQCAssignmentMin

setQCAssignmentMin(qc, assignment, min)

Description

Function to set the minimum value of the specified quick control assignment. The quick control assignment is determined by the Layer object, the index of the quick control and the index of the assignment itself. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control and the assignment argument is the index of the assignment. The indices of the quick controls and the assignments both start counting from 1. The min argument sets the minimum value of the quick control assignment.

Available in: Controller.

Arguments

❕ The value range is always 0 to 100 %, even if the mode of the quick control assignment is set to Relative or Switch Relative.

Example

-- Set the minimum value of the quick control assignment depending on the mode.

layer = this.parent
qc = 1
assignment = 1
 
qcMode = layer:getQCAssignmentMode(qc, assignment)
 
if (qcMode == QCAssignmentMode.relative or qcMode == QCAssignmentMode.switchRelative) then
    qcMin = 25
else
    qcMin = 0
end
   
layer:setQCAssignmentMin(qc, assignment, qcMin)

Jump to Top

setQCAssignmentMax

setQCAssignmentMax(qc, assignment max)

Description

Function to set the maximum value of the specified quick control assignment. The quick control assignment is determined by the Layer object, the index of the quick control and the index of the assignment itself. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control and the assignment argument is the index of the assignment. The indices of the quick controls and the assignments both start counting from 1. The max argument sets the maximum value of the quick control assignment.

Available in: Controller.

Arguments

❕ The value range is always 0 to 100 %, even if the mode of the quick control assignment is set to Relative or Switch Relative.

Example

-- Set the maximum value of the quick control assignment depending on the mode.

layer = this.parent
qc = 1
assignment = 1
  
qcMode = layer:getQCAssignmentMode(qc, assignment)
  
if (qcMode == QCAssignmentMode.relative or qcMode == QCAssignmentMode.switchRelative) then
    qcMax = 75
else
    qcMax = 100
end
    
layer:setQCAssignmentMax(qc, assignment, qcMax)

Jump to Top

setQCAssignmentCurve

setQCAssignmentCurve(qc, assignment, curve)

Description

Function to set the curve value of the specified quick control assignment. The quick control assignment is determined by the Layer object, the index of the quick control and the index of the assignment itself. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control and the assignment argument is the index of the assignment. The indices of the quick controls and the assignments both start counting from 1. The curve argument sets the curve value of the quick control assignment.

Available in: Controller.

Arguments

Example

-- Set the curve of the quick control assignment to -100 %.

layer = this.parent
qc = 1
assignment = 1
   
layer:setQCAssignmentCurve(qc, assignment, -100)

Jump to Top

setQCAssignmentMode

setQCAssignmentMode(qc, assignment, mode)

Description

Function to set the mode of the specified quick control assignment. The quick control assignment is determined by the Layer object, the index of the quick control and the index of the assignment itself. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control and the assignment argument is the index of the assignment. The indices of the quick controls and the assignments both start counting from 1. The mode argument sets the mode of the quick control assignment.

Available in: Controller.

Arguments

Example

-- Set the mode of the quick control assignment to absolute and adjust min and max to full range.

layer = this.parent
qc = 1
assignment = 1
    
layer:setQCAssignmentMode(qc, assignment, QCAssignmentMode.absolute)
layer:setQCAssignmentMin(qc, assignment, 0)
layer:setQCAssignmentMax(qc, assignment, 100)

Jump to Top

setQCAssignmentBypass

setQCAssignmentBypass(qc, assignment, bypass)

Description

Function to set the bypass state of the specified quick control assignment. The quick control assignment is determined by the Layer object, the index of the quick control and the index of the assignment itself. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control. The qc argument is the index of the quick control and the assignment argument is the index of the assignment. The indices of the quick controls and the assignments both start counting from 1. The bypass argument sets the bypass state of the quick control assignment.

Available in: Controller.

Arguments

Example

-- Bypass the specified quick control assignment.

layer = this.parent
qc = 1
assignment = 1
    
layer:setQCAssignmentBypass(qc, assignment, true)

Jump to Top

/ HALion Developer Resource / HALion Script / Class Reference / Element / Layer /

Program

The Program class inherits all properties and methods of the Layer class.

On this page:

Program Class, Program Constructor

List of inherited members:

Layer

appendBus, appendLayer, appendLayerAsync, appendMidiModule, appendZone, findBusses, findEffects, findLayers, findMidiModules, findZones, getBus, getLayer, getMidiModule, getZone, insertBus, insertLayer, insertLayerAsync, insertMidiModule, insertZone, removeBus, removeLayer, removeMidiModule, removeZone, addQCAssignment, removeQCAssignment, getNumQCAssignments, getQCAssignmentParamId, getQCAssignmentScope, getQCAssignmentMin, getQCAssignmentMax, getQCAssignmentCurve, getQCAssignmentMode, getQCAssignmentBypass, setQCAssignmentParamId, setQCAssignmentScope, setQCAssignmentMin, setQCAssignmentMax, setQCAssignmentCurve, setQCAssignmentMode, setQCAssignmentBypass

Element

Element Class, findChildren, getChild, getParameter, getParameterDefinition, getParameterNormalized, hasParameter, removeFromParent, setName, setParameter, setParameterNormalized

Classes

Program Class

Description

The Element object of the program can be obtained with this.program. It has the following fields.

Available in: Controller, Processor.

Fields

Example

-- Print the name of the plug-in instance.

print(this.program.instance.name)
 
-- Print the name of the first slot to which the program is assigned.

if this.program.assignedSlots[1] then
    print(this.program.assignedSlots[1].name)
end

Jump to Top

Constructors

Program Constructor

Program()

(Since HALion 6.4.0)

Description

Constructor to create a new Program object.

Available in: Controller.

Return Values

Returns a new Program object.

Example

-- The following function creates different types of objects in the Program Tree.
-- The objects in the Program Tree do not have a name. You will see only their icons.

function createProgram()
  local inst = this.program.instance
  local prg = Program()
  local bus = Bus()
  prg:appendBus(bus)
  inst:setProgram(prg, 1)
  local layer = Layer()
  prg:appendLayer(layer)
  layer:appendZone(Zone())
  local mm = MidiModule('MIDI Player')
  layer:appendMidiModule(mm)
  local fx = Effect('Distortion')
  bus:appendEffect(fx)
end
 
createProgram()

Jump to Top

/ HALion Developer Resource / HALion Script / Class Reference / Element /

MidiModule

The MidiModule class inherits all properties and methods of the Element class.

On this page:

MidiModule Class, MidiModule Constructor

List of inherited members:

Element

Element Class, findChildren, getChild, getParameter, getParameterDefinition, getParameterNormalized, hasParameter, removeFromParent, setName, setParameter, setParameterNormalized

Classes

MidiModule Class

Description

The Element object of a MIDI module can be obtained with findMidiModules or getMidiModule.

Available in: Controller, Processor.

Fields

Example

print(this.moduleType)

Jump to Top

Constructors

MidiModule Constructor

MidiModule(type)

(Since HALion 6.4.0)

Description

Constructor to create a new MidiModule object of the specified type.

Available in: Controller.

Arguments

Return Values

Returns a new MidiModule object of the specified type.

Example

-- The following function creates different types of objects in the Program Tree.
-- The objects in the Program Tree do not have a name. You will see only their icons.

function createProgram()
  local inst = this.program.instance
  local prg = Program()
  local bus = Bus()
  prg:appendBus(bus)
  inst:setProgram(prg, 1)
  local layer = Layer()
  prg:appendLayer(layer)
  layer:appendZone(Zone())
  local mm = MidiModule('MIDI Player')
  layer:appendMidiModule(mm)
  local fx = Effect('Distortion')
  bus:appendEffect(fx)
end
 
createProgram()

Jump to Top

/ HALion Developer Resource / HALion Script / Class Reference / Element /

ModulationMatrixRow

The ModulationMatrixRow class inherits all properties and methods of the Element class.

On this page:

ModulationMatrixRow Class, getSource1, getSource2, setSource1,setSource2

List of inherited members:

Element

Element Class, findChildren, getChild, getParameter, getParameterDefinition, getParameterNormalized, hasParameter, removeFromParent, setName, setParameter, setParameterNormalized

Classes

ModulationMatrixRow Class

The Element object of the modulation matrix row can be obtained with getModulationMatrixRow. It has the following fields.

Available in: Controller, Processor.

Fields

Example

-- Get the element object of the first zone in the program.

zone = this.program:findZones(true)[1]

-- Get the element object of the first modulation matrix row.

modRow = zone:getModulationMatrixRow(1)

-- Print the zone name and row number of the modulation matrix row.

print(modRow.zone.name)
print(modRow.rowNumber)

Jump to Top

Methods

getSource1

getSource1()

Description

Function to retrieve the 1st modulation source of a row in the modulation matrix. The row is specified with the Zone object of the zone and the index of the modulation matrix row.

Available in: Processor.

Return Values

Returns up to three values, i.e., source, sourceInfo1 and sourceInfo2. The number of return values depends on the modulation source. See Modulation Source Types for details.

Example

-- Print modulation sources.

function printSource(source)
    if source.source == ModulationSource.midiControl then
        print("MIDI Ctrl, Controller Number: "..source.info1)
    elseif source.source == ModulationSource.quickControl then
        print("Quick Ctrl, Layer: "..source.info1.name..", QC Index: "..source.info2)
    elseif source.source == ModulationSource.modulationModule then
        print("MIDI Module,  Module: "..source.info1.name..", Output: "..source.info2)
    elseif source.source == ModulationSource.noteExpression then
        print("Note Expression, Custom NE: "..source.info1)
    elseif source.source == ModulationSource.sampleAndHold then
        print("Sample & Hold, Index: "..source.info1)
    else
        print("Standard Modulation, Index: "..source.source)
    end
end
 
-- Get the zone object of the first zone.

zone = this.program:findZones(true)[1]
 
-- Run through all 32 modulation rows of the zone and print source1 if assigned.

for i=1, 32 do
    local modRow = zone:getModulationMatrixRow(i)
    local source1 = {}
    source1.source, source1.info1, source1.info2 = modRow:getSource1()
    if source1.source ~= ModulationSource.unassigned then
        print("Modulation Row "..i..", Source 1:")
        printSource(source1)
    end
end

Jump to Top

getSource2

getSource2()

Description

Function to retrieve the 2nd modulation source of a row in the modulation matrix. The row is specified with the Zone object of the zone and the index of the modulation matrix row.

Available in: Controller.

Return Values

Returns up to three values, i.e., source, sourceInfo1 and sourceInfo2. The number of return values depends on the modulation source. See Modulation Source Types for details.

❕ The 2nd modulation source has an additional sample & hold. See Modulation Source Types for details.

Example

-- Print modulation sources.

function printSource(source)
    if source.source == ModulationSource.midiControl then
        print("MIDI Ctrl, Controller Number: "..source.info1)
    elseif source.source == ModulationSource.quickControl then
        print("Quick Ctrl, Layer: "..source.info1.name..", QC Index: "..source.info2)
    elseif source.source == ModulationSource.modulationModule then
        print("MIDI Module,  Module: "..source.info1.name..", Output: "..source.info2)
    elseif source.source == ModulationSource.noteExpression then
        print("Note Expression, Custom NE: "..source.info1)
    elseif source.source == ModulationSource.sampleAndHold then
        print("Sample & Hold, Index: "..source.info1)
    else
        print("Standard Modulation, Index: "..source.source)
    end
end
 
-- Get the zone object of the first zone.

zone = this.program:findZones(true)[1]
 
-- Run through all 32 modulation rows of the zone and print source2 if assigned.
for i=1, 32 do
    local modRow = zone:getModulationMatrixRow(i)
    local source2 = {}
    source2.source, source2.info1, source2.info2 = modRow:getSource2()
    if source2.source ~= ModulationSource.unassigned then
        print("Modulation Row "..i..", Source 2:")
        printSource(source2)
    end
end

Jump to Top

setSource1

setSource1(source, sourceInfo1, sourceInfo2)

Description

Function to set the 1st modulation source of a row in the modulation matrix. The row is specified with the Zone object of the zone and the index of the modulation matrix row.

Available in: Controller.

Arguments

Example

-- Define the modulation sources and infos in an array.

modSources = {
    { source = ModulationSource.lfo1, bipolar = 1 },
    { source = ModulationSource.midiControl, bipolar = 0, sourceInfo1 = 1 },
    { source = ModulationSource.quickControl, bipolar = 1, sourceInfo1 = this.program, sourceInfo2 = 1 },
    { source = ModulationSource.modulationModule, bipolar = 0, sourceInfo1 = this, sourceInfo2 = 1 },
    { source = ModulationSource.modulationModule, bipolar = 0, sourceInfo1 = this, sourceInfo2 = 2 },
    { source = ModulationSource.noteExpression, bipolar = 0, sourceInfo1 = 1 }
}
 
-- Define two modulation outputs for the script module.

defineModulation("50%", false)
defineModulation("100%", false)
 
-- Calculate the modulation outputs.

function calcModulation()
    return 0.5, 1
end
 
-- Get the element object of the first zone.

zone = this.program:findZones(true)[1]
 
-- Assign the modulation sources to source 1 in the modulation rows 1 to 6.

for i=1, #modSources do
    local modRow = zone:getModulationMatrixRow(i)
    modRow:setSource1(modSources[i].source, modSources[i].sourceInfo1, modSources[i].sourceInfo2)
    modRow:setParameter("Source1.Polarity", modSources[i].bipolar) -- Set the default polarity of the source.
end
 
-- Assign the sample & hold to source 2 in modulation row 1.

modRow = zone:getModulationMatrixRow(1)
modRow:setSource2(ModulationSource.sampleAndHold, 0)

Jump to Top

setSource2

setSource2(source, sourceInfo1, sourceInfo2)

Description

Function to set the 2nd modulation source of a row in the modulation matrix. The row is specified with the Zone object of the zone and the index of the modulation matrix row.

Available in: Controller.

Arguments

Example

-- Define the modulation sources and infos in an array.

modSources = {
    { source = ModulationSource.lfo1, bipolar = 1 },
    { source = ModulationSource.midiControl, bipolar = 0, sourceInfo1 = 1 },
    { source = ModulationSource.quickControl, bipolar = 1, sourceInfo1 = this.program, sourceInfo2 = 1 },
    { source = ModulationSource.modulationModule, bipolar = 0, sourceInfo1 = this, sourceInfo2 = 1 },
    { source = ModulationSource.modulationModule, bipolar = 0, sourceInfo1 = this, sourceInfo2 = 2 },
    { source = ModulationSource.noteExpression, bipolar = 0, sourceInfo1 = 1 }
}
 
-- Define two modulation outputs for the script module.

defineModulation("50%", false)
defineModulation("100%", false)
 
-- Calculate the modulation outputs.

function calcModulation()
    return 0.5, 1
end
 
-- Get the element object of the first zone.

zone = this.program:findZones(true)[1]
 
-- Assign the modulation sources to source 1 in the modulation rows 1 to 6.

for i=1, #modSources do
    local modRow = zone:getModulationMatrixRow(i)
    modRow:setSource1(modSources[i].source, modSources[i].sourceInfo1, modSources[i].sourceInfo2)
    modRow:setParameter("Source1.Polarity", modSources[i].bipolar) -- Set the default polarity of the source.
end
 
-- Assign the sample & hold to source 2 in modulation row 1.

modRow = zone:getModulationMatrixRow(1)
modRow:setSource2(ModulationSource.sampleAndHold, 0)

Jump to Top

/ HALion Developer Resource / HALion Script / Class Reference / Element /

Slot

The Slot class inherits all properties and methods of the Element class.

On this page:

findBusses, findEffects, getBus, setProgram

List of inherited members:

Element

Element Class, findChildren, getChild, getParameter, getParameterDefinition, getParameterNormalized, hasParameter, removeFromParent, setName, setParameter, setParameterNormalized

Methods

findBusses

findBusses(recursive, nameOrFilterFunction)

Description

Function to find busses in the specified Element object. For example, this.parent specifies the parent of the script module as the Element object to be searched in. If recursive is set to true, subelements will also be searched. The function returns an array with the Bus objects of the found busses. Particular busses can be searched by name or via a filter function. If searching by name, findBusses accepts only the Bus objects that match the specified name. The filter function uses the Bus object of each bus as argument. Only those Bus objects that return true for the search criteria defined in the filter function will be accepted by findBusses. Without a name or filter function, the Bus objects of all busses in the searched Element obects will be returned.

Available in: Controller, Processor.

Arguments

Return Values

Returns an array with the Bus objects of the found busses. Returns an empty table if no busses are found.

Example

-- Find all busses and print their names.
busses = this.program:findBusses(true)
 
if busses[1] then
    for i, bus in ipairs(busses) do
        print(bus.name)
    end
else
    print("Could not find any busses!")
end

Jump to Top

findEffects

findEffects(recursive, nameOrFilterFunction)

Description

Function to find effects in the specified Element object. For example, this.parent specifies the parent of the script module as the Element object to be searched in. To specifiy a bus to be searched in, use getBus or findBusses. If recursive is set to true, subelements will also be searched. The function returns an array with the Effect objects of the found effects. Particular effects can be searched by name or via a filter function. If searching by name, findEffects accepts only the Effect objects that match the specified name. The filter function uses the Effect object of each effect as argument. Only those Effect objects that return true for the search criteria defined in the filter function will be accepted by findEffects. Without a name or filter function, the Effect objects of all effects in the searched Element objects will be returned.

Available in: Controller, Processor.

Arguments

Return Values

Returns an array with the Effect objects of the found effects. Returns an empty table if no effects are found.

Example

-- Find all effects and print their names.
effects = this.program:findEffects(true)
 
if effects[1] then
    for i, effect in ipairs(effects) do
        print(effect.name)
    end
else
    print("Could not find any effects!")
end

Jump to Top

getBus

getBus(nameOrPosition)

Description

Function to retrieve the Bus object of a bus in the specified Element object. For example, this.parent specifies the parent of the script module as the Element object to be searched in. This function does not search in subelements. A particular bus can be searched by name or position. The position is the number indexing the busses in the specified Element object. If several busses share the same name, only the first match will be returned. If no argument is set, the function returns the first bus it finds.

Available in: Controller, Processor.

Arguments

Return Values

Returns the Bus object of the found bus. Returns nil if no bus is found.

Example

-- Locate the first bus in the program and print its name.

bus = this.program:getBus()
 
if bus then
    print(bus.name)
else
    print("Could not find a bus!")
end

Jump to Top

setProgram

setProgram(programOrNil, index)

Description

Function to set a program in the specified slot of the Program Table or the Slot Rack of the plug-in instance. Before calling this function, you must access the Instance object with this.program.instance. The program is determined by its Program object. To specify the slot in the Program Table, you must use the index argument. To specify the slot in the Slot Rack, you must use a Slot object, for example, via getSlot. The program can be removed from the Slot Rack by using nil as argument.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, each program can exist only once in the Program Table. Furthermore, an Element object that you retrieved from the running plug-in instance cannot be added twice to the Program Table. It must be removed before it can be added again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be added freely to the Program Table, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Example

To explore the following script:

1. Download Program.vstpreset.
2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
3. Create an empty program and add a script module.
4. Paste the script into the text editor of the script module and execute the script.

-- Set Program.vstpreset in slot 3 of the Program Table and slot 1 of the Slot Rack.
     
-- Get the file path for user VST presets.
path = getUserPresetPath()
     
-- Load the VST preset.
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")
  
-- Set loadedProgram in slot 3 of the Program Table.
this.program.instance:setProgram(loadedProgram, 3)
 
-- Set program in slot 1 of the Slot Rack.
program = this.program.instance:getProgram(3)
this.program.instance:getSlot(1):setProgram(program)
  
-- Clear slot 2 of the Slot Rack.
this.program.instance:getSlot(2):setProgram(nil)

Jump to Top

/ HALion Developer Resource / HALion Script / Class Reference / Element /

Zone

The Zone class inherits all properties and methods of the Element class.

On this page:

Zone Class, Zone Constructor, getModulationMatrixRow, getOutputBus, setOutputBus

List of inherited members:

Element

Element Class, findChildren, getChild, getParameter, getParameterDefinition, getParameterNormalized, hasParameter, removeFromParent, setName, setParameter, setParameterNormalized

Classes

Zone Class

Description

The Element object of a zone can be obtained with findZones or getZone. It has the following fields.

Available in: Controller, Processor.

Fields

Example

-- Print the key and velocity range of the first zone in the program.

zone = this.program:findZones(true)[1]

print(zone.keyLow)
print(zone.keyHigh)
print(zone.velLow)
print(zone.velHigh)

Jump to Top

Constructors

Zone Constructor

Zone()

(Since HALion 6.4.0)

Description

Constructor to create a new Zone object.

Available in: Controller.

Return Values

Returns a new Zone object.

Example

-- The following function creates different types of objects in the Program Tree.
-- The objects in the Program Tree do not have a name. You will see only their icons.

function createProgram()
  local inst = this.program.instance
  local prg = Program()
  local bus = Bus()
  prg:appendBus(bus)
  inst:setProgram(prg, 1)
  local layer = Layer()
  prg:appendLayer(layer)
  layer:appendZone(Zone())
  local mm = MidiModule('MIDI Player')
  layer:appendMidiModule(mm)
  local fx = Effect('Distortion')
  bus:appendEffect(fx)
end
 
createProgram()

Jump to Top

Methods

getModulationMatrixRow

getModulationMatrixRow(rowNumber)

Description

Function to obtain the ModulationMatrixRow object of the specified modulation matrix row. The modulation matrix row is determined by the Zone object of the zone and the index of the modulation matrix row.

Available in: Controller, Processor.

Arguments

Return Values

The ModulationMatrixRow object of the specified modulation matrix row.

Example

-- Get the element object of the first zone in the program.

zone = this.program:findZones(true)[1]

-- Get the element object of the first modulation matrix row.

modRow = zone:getModulationMatrixRow(1)

-- Print the row number of the specified modulation matrix row.

print(modRow.rowNumber)

Jump to Top

getOutputBus

getOutputBus()

Description

Function to retrieve the currently assigned output bus of a zone or bus.

Available in: Controller, Processor.

Return Values

Returns the Bus object of the currently assigned output bus or nil if the default routing is used.

Example

-- Raise an error if no output bus is assigned.

zone = this.parent:getZone()

assert(zone:getOutputBus(), "No output bus assigned. The default routing is used!")

Jump to Top

setOutputBus

setOutputBus(bus)

Description

Function to assign the output of a zone or bus to the specified output bus. The sending zone or bus is determined by its Element object. The receiving output bus is specified by its Bus object. Setting the output bus to nil enables the default signal routing for the zone or bus.

❕ Output busses that are higher up in the hierarchy of the Program Tree can be assigned freely. If the sending bus and the receiving output bus have the same parent layer, the output bus must come later in the signal flow.

Available in: Controller.

Arguments

Example

-- Assign the output of the zone to the Master output bus of the plug-in.

zone = this.parent:getZone()
masterbus = this.program.instance:getBus(1)
 
zone:setOutputBus(masterbus)
 
print("Output of "..zone.name.." is assigned to "..masterbus.name..".")

Jump to Top

/ HALion Developer Resource / HALion Script / Class Reference /

Event

The Event class describes the properties of events.

On this page:

Event Class, Event Constructor

Classes

Event Class

Description

The state of an Event object is described by the following fields.

Available in: Processor.

Fields

Fields per Event Type

Which of the fields are used depends on the Event Type.

Example

-- Print the fields of an Event object.

function onNote(event)
    print(event)
    postEvent(event)
end
 
function onRelease(event)
    print(event)
    postEvent(event)
end
  
function onController(event)
    print(event)
    postEvent(event)
end
  
function onNoteExpression(event)
    print(event)
    -- postEvent(event), not needed for note expression.
end
 
function onRetrigger(event)
    print(event)
    postEvent(event)
end
 
function onData(event)
    print(event)
    postEvent(event)
end

Jump to Top

Constructors

Event Constructor

Event(type)

Description

Constructor to create a new Event object of the specified type.

Available in: Processor.

Arguments

Return Values

Returns a new Event object of the specified type.

❕ The fields of the Event object must be set after its creation.

Example

-- Create a new note-on event.

function onNote(event)
    local newEvent = Event(EventType.noteOn)
    newEvent.note = event.note + 12
    newEvent.velocity = event.velocity
    local id = postEvent(newEvent)
    waitForRelease()
    releaseVoice(id)
end

Jump to Top

/ HALion Developer Resource / HALion Script / Class Reference /

LoadProgress

The properties of the LoadProgress class can be used to monitor the progress when loading elements of VST presets.

On this page:

LoadProgress Class

Classes

LoadProgress Class

Description

The functions loadPresetAsync, appendLayerAsync and insertLayerAsync return a LoadProgress object. The properties of the LoadProgress object are described by the following fields.

Available in: Controller.

Fields

Example

-- Start with an empty program, remove any existing layers.

layers = this.parent:findLayers()
 
if layers then
   for i, layer in ipairs(layers) do
       this.parent:removeLayer(layer)
   end
end
 
-- Table with layer presets from Skylab.
layerPresets = {
   { name = "Ambient Pad 01", path = "vstsound://724ACB205EFF46F885735D1B216C37AD/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 01.vstpreset" },
   { name = "Ambient Pad 02", path = "vstsound://724ACB205EFF46F885735D1B216C37AD/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 02.vstpreset" },
   { name = "Ambient Pad 03", path = "vstsound://724ACB205EFF46F885735D1B216C37AD/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 03.vstpreset" },
   { name = "Ambient Pad 04", path = "vstsound://724ACB205EFF46F885735D1B216C37AD/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 04.vstpreset" },
}
-- Create a table with the preset names.
function getPresetNames()
   presetNames = {}
   for i, preset in ipairs(layerPresets) do
       presetNames[i] = preset.name
   end
end
 
getPresetNames()
 
-- Remove the old layer after the new one was added.
function removeOldLayer(progressInfo)
   local newPreset = progressInfo.root
   if oldPreset then
       this.parent:removeLayer(oldPreset)
       print(oldPreset.name.." removed.")
   end
   oldPreset = newPreset
end
 
-- Append the preset in a separate thread.
function appendNewLayer(progressInfo)
   if progressInfo.root then
       this.parent:appendLayerAsync(progressInfo.root, removeOldLayer)
       print("Appending "..progressInfo.root.name.."...")
   end
end
 
-- Load the preset in a separate thread.
function onSelectPresetChanged()
   progress = 0
   progressInf = loadPresetAsync(layerPresets[SelectPreset].path, appendNewLayer)
   print("Loading "..layerPresets[SelectPreset].name.."...")
end
 
-- Define a parameter for selecting the preset to be loaded.
defineParameter("SelectPreset", "Select Preset", 1, presetNames, onSelectPresetChanged)
 
-- Monitor the load progress with onIdle.
progress = 1
function onIdle()
   if progress < 1 then
       progress = progressInf.progress
       print("Progress: "..(progressInf.progress * 100).."%")
   end
end

/ HALion Developer Resource / HALion Script / Class Reference /

ParameterDefinition

The ParameterDefinition class describes the properties of parameters.

On this page:

ParameterDefinition Class, getDisplayString

Classes

ParameterDefinition Class

Description

The ParameterDefinition object describes the properties of a parameter. It has the following fields.

Available in: Controller, Processor.

Fields

-- Print the parameter definition with corresponding data type of the parent layer's level parameter.

function onLoadIntoSlot()
 
    local def = this.parent:getParameterDefinition("Level")
 
    print("Name = "..def.name..", "..type(def.name))
    print("Long Name = "..def.longName..", "..type(def.longName))
    print("ID = "..def.id..", "..type(def.id))
    print("Type = "..def.type..", "..type(def.type))
    print("Default = "..def.default..", "..type(def.default))
    print("Min = "..def.min..", "..type(def.min))
    print("Max = "..def.max..", "..type(def.max))
    print("Read Only = "..tostring(def.readOnly)..", "..type(def.readOnly))
    print("Write Always = "..tostring(def.writeAlways)..", "..type(def.writeAlways))
    print("Automatable = "..tostring(def.automatable)..", "..type(def.automatable))
    print("Persistent = "..tostring(def.persistent)..", "..type(def.persistent))
    print("Unit = "..def.unit..", "..type(def.unit).."\n")
 
end

Jump to Top

Methods

getDisplayString

getDisplayString(value)

Description

The internal precision of parameter values is usually higher than the precision of the corresponding display string on the user interface. You can use this function to obtain the display string of the specified parameter and value. You specify the parameter with getParameterDefinition.

Available in: Controller, Processor.

Arguments

❕ The data type of the value for getDisplayString must match the data type of the corresponding parameter value.

Return Values

Returns the display string of the specified parameter and value.

Example

-- Get the display string of a value.

value = -2.471
print("value = "..value)
print("Display String = "..this.program:getParameterDefinition("Level"):getDisplayString(-2.471))

Jump to Top

/ HALion Developer Resource, / HALion Script, /

Reference

The reference pages describe the functions and features of the HALion Script language.

A-E

addLayerPassword, addQCAssignment, afterTouch, AlternateData Table, analyzePitch, appendBus, appendEffect, appendLayer, appendLayerAsync, appendMidiModule, appendZone, assignAutomation, AudioFile.open, beat2ms, Bus Constructor, Bypass Masks, calcModulation, cancelDecompose, cancelPitchAnalysis, changeNoteExpression, changePan, changeTune, changeVolume, changeVolumedB, clone, controlChange, Controller Numbers, decompose Decompose Output Modes, defineModulation, defineParameter, defineSlotLocal, Effect Constructor, endUndoBlock, Event Constructor, Event Types,

F-J

fade, findBusses, findChildren, findEffects, findLayers, findMidiModules, findSlots, findZones, forgetAutomation, getAllocatedMemory, getAutomationIndex, getBarDuration, getBeatDuration, getBeatTime, getBeatTimeInBar, getBus, getCC, getChild, getContext, getDecomposeOutputPath, getDecomposeProgress, getDecomposeSettings, getDisplayString, getEffect, getElement, getFreeVoices, getHostName, getHostVersion, getKeyProperties, getKeySwitches, getLayer, getMidiModule, getModulationMatrixRow, getMsTime, getNoteDuration, getNoteExpression, getNoteExpressionProperties, getNumQCAssignments, getOnsets, getOutputBus, getParameter, getParameterDefinition, getParameterNormalized, getPeak, getPitch, getPitchAnalysisProgress, getProcessedSamples, getProductName, getProductVersion, getProgram, getQCAssignmentBypass, getQCAssignmentCurve, getQCAssignmentMax, getQCAssignmentMin, getQCAssignmentMode, getQCAssignmentParamId, getQCAssignmentScope, getSamplingRate, getScriptExecTimeOut, getScriptVersion, getSlot, getSlotIndex, getSource1, getSource2, getTempo, getTime, getTimeSignature, getUndoContext, getUsedMemory, getUsedVoices, getUsedVoicesOfSlot, getUserPresetPath, getUserSubPresetPath, getVoices, getZone, hasParameter, insertBus, insertEffect, insertEnvelopePoint, insertEvent, insertLayer, insertLayerAsync, insertMidiModule, insertZone, isKeyDown, isNoteHeld, isOctaveKeyDown, isPlaying,

K-O

Layer Constructor, loadPreset, loadPresetAsync, messageBox, MIDI File Format Types, MidiModule Constructor, MIDI Sequence Table, Modulation Destination Types, Modulation Source Types, ms2beat, ms2samples, Note Expression Types, onAfterTouch, onController, onData, onIdle, onInit, onLoad, onLoadIntoSlot, onLoadSubPreset, onNote, onNoteExpression, onPitchBend, onRelease, onRemoveFromSlot, onRetrigger, onSave, onSaveSubPreset, onTriggerPad, onUnhandledEvent, openURL,

P-T

pitchBend, playNote, playTriggerPad, postEvent, printRaw, Program Constructor, Quick Control Assignment Modes, readMidiFile, releaseVoice, removeBus, removeEffect, removeEnvelopePoint, removeFromParent, removeLayer, removeMidiModule, removeQCAssignment, removeZone, runAsync, runSync, samples2ms, savePreset, setBypassNoteOff, setName, setOutputBus, setParameter, setParameterNormalized, setProgram, setQCAssignmentBypass, setQCAssignmentCurve, setQCAssignmentMax, setQCAssignmentMin, setQCAssignmentMode, setQCAssignmentParamId, setQCAssignmentScope, setScriptExecTimeOut, setSource1, setSource2, setZoneFMXAlgo, sortEvents, spawn, startUndoBlock, startWriteOutputToFile, stopWriteOutputToFile,

U-Z

Undo Context Types, VoiceGroupsData Table, Voice Group Steal Modes, wait, waitBeat, waitForRelease, writeMidiFile, Zone Constructor,

/ HALion Developer Resource / HALion Script / Reference /

addLayerPassword

addLayerPassword(pwd)

Description

Function that gives access to protected layers. By default, protected layers cannot be accessed by scripts. The parameters of a protected layer and any elements inside of it are hidden for scripts. This prevents someone unauthorized from parsing the Program Tree to retrieve hidden information. By calling this function with the correct password, the calling script can access the corresponding protected layers again.

❕ To hide the password in addLayerPassword, you must also protect the script module. See Managing Script Modules for details.

Available in: Controller.

Arguments

Example

-- Access the protected layer(s) which have the password "abc123".

addLayerPassword("abc123")

See also: Protecting Layers

/ HALion Developer Resource / HALion Script / Reference /

addQCAssignment

Description

Function to add a quick control assignment to the specified layer and quick control. For example, this.parent defines the parent layer of the script module as the layer that contains the quick control that you want to edit. The quick control assignment will be added to the quick control with the index stated by the qc argument. The arguments element and nameOrID specify the parameter to be connected. The scope determines the part of the program that will be affected by the quick control assignment. You specify the scope by setting the scope argument to the Element object that corresponds to the desired part of the program.

❕ The index of the quick controls starts counting from 1. QC 1 to QC 8 have index 1 to 8. Sphere H, Sphere V and Mod Wheel have index 9, 10 and 11.

Available in: Controller.

Arguments

Example

-- Assign the octave parameter of the zone to the
-- first quick control of the script module's parent layer.

layer = this.parent
zones = layer:findZones(true)
 
layer:addQCAssignment(1, zones[1], "Pitch.Octave", layer)

See also: removeQCAssignment, getNumQCAssignments, getQCAssignmentParamId, getQCAssignmentScope, getQCAssignmentMin, getQCAssignmentMax, getQCAssignmentCurve, getQCAssignmentMode, getQCAssignmentBypass, setQCAssignmentParamId, setQCAssignmentScope, setQCAssignmentMin, setQCAssignmentMax, setQCAssignmentCurve, setQCAssignmentMode, setQCAssignmentBypass, Quick Control Assignment Modes

/ HALion Developer Resource / HALion Script / Reference /

afterTouch

afterTouch(value)

Description

Function to generate channel aftertouch events.

Available in: Processor.

Arguments

Example

-- Invert aftertouch values.
function onAfterTouch(event)
    local invAT =  127 - event.value
    afterTouch(invAT)
    print("Inverse AT:", invAT)
end

See also: onAfterTouch, controlChange, pitchBend

/ HALion Developer Resource / HALion Script / Reference /

AlternateData Table

(Since HALion 6.4.10)

Description

The alternations in the Alternation List of the Layer Alternate MIDI module are managed via a predefined table: the AlternateData table. This table can be obtained by making a call to getParameter with "AlternateData" as parameter. The alternations are referenced by their index. Each alternation has the fields .keyswitch and .layer. You can change the values, but the structure of this table must remain unaltered. The values are set by making a call to setParameter. See the example below for more details.

Available in: Controller.

Fields

Example

-- Add a Layer Alternate MIDI module.
this.parent:appendMidiModule(MidiModule("Layer Alternate"))
layerAlternate = this.parent:getMidiModule("")
layerAlternate:setName("Layer Alternate")
altdata = layerAlternate:getParameter("AlternateData")
-- Create three layers with a synth zone and add them to the alternation list.
for i = 1, 3 do
    this.parent:appendLayer(Layer())
    local alternateLayer = this.parent:getLayer(i)
    alternateLayer:setName("Alt "..i)
    alternateLayer:appendZone(Zone())
    local zone = alternateLayer:getZone()
    zone:setName("Zone "..i)
    altdata[#altdata+1] = { keyswitch = -1, layer = alternateLayer }
end
layerAlternate:setParameter("AlternateData", altdata)

/ HALion Developer Resource / HALion Script / Reference /

analyzePitch

analyzePitch(callback, channel)

(Since HALion 6.3)

Description

Function to analyze the pitch of an audio file. You specify the audio file with the AudioFile object that is returned by the AudioFile.open function. The arguments callback and channel are optional. If called without a callback function, analyzePitch will be executed in the same thread. If called with a callback function as argument, analyzePitch will be executed in a separate, parallel thread. You can specify the channel to be analyzed with the channel argument. Without the channel argument, multiple channels of an audio file will be summed before the pitch is analyzed. The callback function is called with the AudioFile object as the first and the channel as the second argument after the pitch has been analyzed. The results of analyzePitch are cashed for as long as the corresponding AudioFile object exists. The function itself does not return any pitch information. You must use getPitch to obtain the analyzed pitch.

Available in: Controller.

Arguments

Example

channelNames = { [0] = "All", "Left", "Right" }
  
defineParameter( "Channel", nil, 0, channelNames)
defineParameter( "Start", nil, false, function() if Start then onStart() end end)
defineParameter( "Cancel", nil, false)
  
-- Requires the Skylab content.
path = "vstsound://724ACB205EFF46F885735D1B216C37AD/.AppData/Steinberg/Skylab/Sub Presets/Layer Presets/Ambient Pads/Ambient Pad 01.vstpreset"
layer = loadPreset(path)
  
function onPitchAnalysisFinished(audioFile, channelNum)
    print("Progress: 100%")
    print(channelNames[channelNum].." channel(s) of "..audioFile.fileName.." analyzed.")
end
  
function onStart()
    zones = layer:findZones(true)
    for i, zone in ipairs(zones) do
        local samplePath = zone:getParameter("SampleOsc.Filename")
        print("File: "..samplePath)
        local afile = AudioFile.open(samplePath)
        afile:analyzePitch(onPitchAnalysisFinished, Channel)
        while afile:getPitchAnalysisProgress(Channel) < 1 do
            if Cancel then
                afile:cancelPitchAnalysis(Channel)
                break
            end
            local progressPercent = 100 * afile:getPitchAnalysisProgress(Channel)
            print(string.format("Progress: %2d%%", progressPercent))
            wait(2000)
        end
        if Cancel then
            Cancel = false
            print("Canceled!")
            break
        end
        local pitch = afile:getPitch(0, -1, Channel)
        print("Analyzed Pitch: "..pitch)
    end
    print("Done!")
    Start = false
end

See also: getPitch, getPitchAnalysisProgress, cancelPitchAnalysis

/ HALion Developer Resource / HALion Script / Reference /

appendBus

appendBus(bus)

Description