Plugalyzer

A command-line VST3, AU, LADSPA and LV2 host meant to ease debugging of audio plugins and instruments by making it possible to run them in non-realtime outside of a conventional DAW.

It processes audio and MIDI from input files using the desired plugin, writing the result to an output file.
Plugins with multiple input buses (such as sidechains) are supported.

Table of Contents

• Usage
  • Process audio files
    • Bus layouts
    • Parameter automation
    • Processing limitations
  • List plugin parameters
    • Limitations
• Installation

Usage

The general usage of plugalyzer follows the pattern plugalyzer [command] [options...].
Using the --help flag, detailed usage information can be obtained for every command.

Process audio files

The process command processes the given audio and/or MIDI files using the given plugin in non-realtime, writing the processed audio to an output file.

| Option | Description | Required | |------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------| | --plugin=<path> | Path to, or identifier of the plugin to use. | Yes | | --input=<path> | Path to an audio input file.<br>To supply multiple input files, provide the --input argument multiple times. | Yes, unless --midiInput is set | | --midiInput=<path> | Path to a MIDI input file. | No | | --output=<path> | Path to write the processed audio to. | Yes | | --overwrite | Overwrite the output file if it exists.<br>If this option is not set, processing is aborted if the output file exists. | No | | --sampleRate=<number> | The sample rate to use for processing.<br>Only allowed if no audio input is provided.<br>Defaults to 44100. | No | | --blockSize=<number> | The amount of samples to send to the audio plugin at once for processing.<br>Defaults to 1024. | No | | --outChannels=<number> | The amount of channels to use for the plugin's output bus. Defaults to the amount of channels of the first input file. | No | | --bitDepth=<number> | The output file's bit depth.<br>Defaults to the bit depth of the first input file, or 16 if no audio input is provided.<br>Must be 8, 16, 24 or 32. | No | | --paramFile=<path> | Specifies a JSON file to read parameter and automation data from. For more information, refer to Parameter automation | No | | --param=<name>:<value>[:n] | Sets the plugin parameter with the given name or index to the given value.<br>Both name and value can be quoted using single or double quotes.<br>If the :n suffix is given, the value is treated as a normalized value between 0 and 1, otherwise the string will be converted to the normalized value.<br>To set multiple parameters, supply the --param argument multiple times.<br>Use the listParameters command to list all available parameters. | No | | --preset=<path> | Can be used to supply a .vstpreset file to VST3 plugins. | No |

Example usage for a plugin with a main and a sidechain input bus:

plugalyzer process                    \
  --plugin=/path/to/my/plugin.vst3    \
  --input=main_input.wav              \
  --input=sidechain_input.wav         \
  --output=out.wav                    \
  --param="Wet/Dry Mix":0.2:n         \
  --param=Distortion:Off

Parameter automation

Aside from the --param option, plugin parameters can also be supplied via JSON file using the --paramFile option.
This JSON file also allows for automation by supplying multiple keyframes that are linearly interpolated between.

The JSON file's main object contains an entry for each parameter.

Parameter values can either be a (floating-point) number or a string.
Numbers are interpreted as normalized parameter values between 0 and 1.
Strings are passed to the parameter's getValueForText function to convert them to normalized values.
Note that string values can only be supplied for parameters that support text-to-value conversion.

Keyframe times can be specified in the following formats:

• a string containing an integer number is interpreted as a sample index.
• a string suffixed with s is interpreted as an amount of seconds.
• a string suffixed wit