# 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

generated by LDoc 1.4.2