Page tree
Skip to end of metadata
Go to start of metadata

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

.isAuxBusReturns true if this is an aux bus and false if it is not.boolean
.auxNumberThe number of the corresponding aux bus.number
.numChannelsThe number of output channels of the bus.number
.activeReturns true if the bus is active and false if it is not active.boolean

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

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 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 through 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

recursiveIf set to false, only the specified Element object will be searched. If set to true, subelements will also be searched. The default is false.boolean
nameOrFilterFunctionThe name of the effects searched for or a filter function. Only the Effect objects that match the name or return true for the search criteria of the filter function will be accepted. Set this to nil to deactivate any name filter or search criteria.string or function, optional

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

nameOrPositionThe name or position of the effect. Set this to nil to deactivate the search filter.string or number, optional

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.

Available in: Controller.

Arguments

effectThe element object of the effect that you want to insert.Effect
positionThe position where the effect is inserted.number

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

effectThe Element object of the insert that you want to append.Effect

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

insertOrPositionThe Element object or the position of the effect to be removed.Effect or number

Example

-- remove all effects from the program

busses = this.program:findBusses(true) 	-- find all busses in the program

for i, bus in ipairs(busses) do
    effects = bus:findEffects(true) 	-- find all effects of the bus
	for j, effect in ipairs(effects) do
		bus:removeEffect(effect) 		-- and remove them
	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

busThe Bus object of the bus that you want to assign, or nil.Bus or nil

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

  • No labels

1 Comment