protoplug

Lua API reference

• Index

Contents

• Callback functions
• Override functions
• Class plugin.PositionInfo

Modules

• plugin
• script
• midi
• gui
• polyGen
• stereoFx

Classes

• juce.AffineTransform
• juce.AudioFormatReader
• juce.Colour
• juce.ColourGradient
• juce.Component
• juce.FillType
• juce.Font
• juce.Graphics
• juce.Image
• juce.Justification
• juce.LagrangeInterpolator
• juce.Line
• juce.Path
• juce.Point
• juce.RectanglePlacement
• juce.Rectangle_float
• juce.Rectangle_int

Examples

• classic-filter.lua
• sine-organ.lua
• midi-chordify.lua
• sinemouse-demo.lua
• soundfile-test.lua

Module plugin

Use plugin to define the AU/VST audio plugin's behaviour.

The plugin global is available to every protoplug script after including the main protoplug header :

require "include/protoplug"

Callback functions

plugin.manageParams (paramList)	Automatically set up a list of parameters.
plugin.setParameter (index, value)	Set (automate) a parameter's value.
plugin.getParameter (index)	Get a parameter's value.
plugin.getCurrentPosition ()	Get host position info, if available.
plugin.getSampleRate ()	Get host samplerate.
plugin.isSampleRateKnown ()	Check if the samplerate is known.
plugin.addHandler (event, handler)	Add a handler for a VST/AU event.

Override functions

plugin.processBlock (samples, smax, midiBuf)	Process Audio Block.
plugin.getParameterName (index)	Return the name of a parameter.
plugin.getParameterText (index)	Return the representation of a parameter's value.
plugin.paramChanged (index)	Handle parameter changes.
plugin.getTailLengthSeconds ()	Return the tail length in seconds (effects only).

Class plugin.PositionInfo

plugin.PositionInfo.bpm	Host tempo (beats per minute)
plugin.PositionInfo.timeSigNumerator	Time signature numerator ie.
plugin.PositionInfo.timeSigDenominator	Time signature denominator ie.
plugin.PositionInfo.timeInSamples	Current position on the host's timeline (samples)
plugin.PositionInfo.timeInSeconds	Current position on the host's timeline (seconds)
plugin.PositionInfo.editOriginTime	Position of the start of the edit region on the host's timeline
plugin.PositionInfo.ppqPosition	Current position on the host's timeline (pulses-per-quarter-note)
plugin.PositionInfo.ppqPositionOfLastBarStart	Position of the last bar start (pulses-per-quarter-note).
plugin.PositionInfo.frameRate	Video frame rate
plugin.PositionInfo.isPlaying	Is playing
plugin.PositionInfo.isRecording	Is recording
plugin.PositionInfo.ppqLoopStart	Position of the loop start (pulses-per-quarter-note).
plugin.PositionInfo.ppqLoopEnd	Position of the loop end (pulses-per-quarter-note).
plugin.PositionInfo.isLooping	Is looping

Callback functions

Functions that your script can call.

plugin.manageParams (paramList)

Automatically set up a list of parameters. Call this function with a table containing parameter definitions as argument, and it will perform the repetitive task of defining all the parameter-related overrides.

The format of the parameter list is demonstrated in classic-filter.lua

Parameters:

• paramList a table with parameter definitions (see example)

plugin.setParameter (index, value)

Set (automate) a parameter's value. The value must be normalized to be between 0 and 1.

Parameters:

• index parameter index (0-126)
• value parameter value (0-1)

plugin.getParameter (index)

Get a parameter's value. The values are between 0 and 1, but different minimums and maximums can be easily simulated using plugin.manageParams.

Parameters:

• index parameter index (0-126)

plugin.getCurrentPosition ()

Get host position info, if available. Only call this from within processBlock.

Returns:

plugin.PositionInfo current position info, or nil depending on the host.

plugin.getSampleRate ()

Get host samplerate. The value is unknown until the plugin prepareToPlay event has been emitted. The value is always known in processBlock. An error is caused if an attempt is made to access the sample rate prematurely.

Returns:

current samplerate.

See also:

plugin.addHandler

plugin.isSampleRateKnown ()

Check if the samplerate is known.

Returns:

boolean

plugin.addHandler (event, handler)

Add a handler for a VST/AU event. The following events are available :

• "prepareToPlay" - Emitted before the first call to processBlock, when the samplerate is known.

Parameters:

• event string the event to handle
• handler function a function to add the event's handlers

See also:

• script.addHandler
• gui.addHandler

Override functions

Define these functions and the host will call them.

plugin.processBlock (samples, smax, midiBuf)

Process Audio Block. Override this function to input and output audio and MIDI data.

This override is handled automatically if stereoFx or polyGen are used. Use this function to handle the raw data instead.

Parameters:

• samples a C float** pointing to two channels of samples, serving as input and output
• smax the maximum sample index (nSamples - 1)
• midiBuf midi.Buffer the MIDI data for this block, serving as input and output

Usage:

 function plugin.processBlock (samples, smax) -- let's ignore midi for this example
     for i = 0, smax do
         samples[0][i] = sin(myTime) -- left channel
         samples[1][i] = sin(myTime) -- right channel
         myTime = myTime + myDelta
     end
 end

plugin.getParameterName (index)

Return the name of a parameter.

This override is handled automatically if manageParams is used.

Parameters:

• index parameter index (0-126)

Returns:

string the parameter's name

plugin.getParameterText (index)

Return the representation of a parameter's value. Override this function to choose how each parameter's value should be displayed by the host. The parameter's current value can be obtained using plugin.getParameter

This override is handled automatically if manageParams is used.

Parameters:

• index parameter index (0-126)

Returns:

string a string representation of the parameter's current value

plugin.paramChanged (index)

Handle parameter changes. Override this function to do something when a parameter changes The parameter's current value can be obtained using plugin.getParameter

This override is handled automatically if manageParams is used.

Parameters:

• index parameter index (0-126)

plugin.getTailLengthSeconds ()

Return the tail length in seconds (effects only). Override this function to define the effect's audio tail length.

Returns:

the tail length in seconds

Class plugin.PositionInfo

A container type for host-related information as returned by plugin.getCurrentPosition

Is a JUCE AudioPlayHead::CurrentPositionInfo

plugin.PositionInfo.bpm

Host tempo (beats per minute)

plugin.PositionInfo.timeSigNumerator

Time signature numerator ie. 3/4

plugin.PositionInfo.timeSigDenominator

Time signature denominator ie. 3/4

plugin.PositionInfo.timeInSamples

Current position on the host's timeline (samples)

plugin.PositionInfo.timeInSeconds

Current position on the host's timeline (seconds)

plugin.PositionInfo.editOriginTime

Position of the start of the edit region on the host's timeline

plugin.PositionInfo.ppqPosition

Current position on the host's timeline (pulses-per-quarter-note)

plugin.PositionInfo.ppqPositionOfLastBarStart

Position of the last bar start (pulses-per-quarter-note). (or zero if unavailable.)

plugin.PositionInfo.frameRate

Video frame rate

plugin.PositionInfo.isPlaying

Is playing

plugin.PositionInfo.isRecording

Is recording

plugin.PositionInfo.ppqLoopStart

Position of the loop start (pulses-per-quarter-note). (or zero if unavailable.)

plugin.PositionInfo.ppqLoopEnd

Position of the loop end (pulses-per-quarter-note). (or zero if unavailable.)

plugin.PositionInfo.isLooping

Is looping