pluginval

by Tracktion

Tracktion / pluginval

Cross platform plugin testing and validation tool

138 Stars 19 Forks Last release: about 2 months ago (v0.2.9) GNU General Public License v3.0 184 Commits 19 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

pluginval

master: Build Status Build Status

develop: Build Status Build Status

pluginval

pluginval is a cross-platform plugin validator and tester application. It is designed to be used by both plugin and host developers to ensure stability and compatibility between plugins and hosts.

If you are a plugin user looking to report a problem with a plugin to the developers, you can use

pluginval
to create a detailed log which can drastically improve the time to fix issues. Please follow the instructions here to get started: Testing plugins with pluginval
Highlights:
  • Test VST/AU/VST3 plugins
  • Compatible with macOS/Windows/Linux
  • Run in GUI or headless mode
  • Validation is performed in a separate process to avoid crashing

Installation

Either grab one of the pre-compiled binaries from the Releases page or clone the repo and build from sources. The projects are generated by the Projucer so you may have to build that first to generate the various project files. The easiest way to do this is to run one of the build scripts in the

install
directory.
Mac:
$ git clone --recurse-submodules https://github.com/Tracktion/pluginval.git
$ cd pluginval/install
$ ./mac_build
Windows:
> git clone --recurse-submodules https://github.com/Tracktion/pluginval.git
> cd pluginval\install
> ./windows_build.bat

Third-party Installation

Chocolatey (Windows):
> choco install pluginval

You can find the chocolatey package of pluginval here, and the source of the chocolatey package here, currently maintained by Xav83.

N.B. Enabling VST2 Testing:

The VST2 SDK is no longer included in JUCE so VST2 support isn't available out from a fresh clone. To enable VST2 testing do one of the following: 1. Before running one of the

install/platform
scripts, set the
VST2_SDK_DIR
environment variable to point to the VST2 source directory on your system. This will then modify the
pluginval.jucer
file automatically. E.g.
sh
$ git clone --recurse-submodules https://github.com/Tracktion/pluginval.git
$ cd pluginval/install
$ export VST2_SDK_DIR=~/SDKs/vstsdk2.4
$ ./mac_build
or ```shell

git clone --recurse-submodules https://github.com/Tracktion/pluginval.git cd pluginval\install set VST2SDKDIR=C:\SDKs\vstsdk2.4 ./windows_build.bat ```

  1. Manually open then
    pluginval.jucer
    , select the
    juce_audio_processors
    module and change the
    JUCE_PLUGINHOST_VST
    to
    Enabled
    . Now you'll have to either have the VST2 SDK path in your Projucer Global Settings, or you'll need to add it to the
    pluginval.jucer
    Header Search Paths
    setting.

Running in GUI Mode

Once the app has built for your platform it will be found in

/bin
. Simply open the app to start it in GUI mode. Once open, you'll be presented with an empty plugin list. Click "Options" to scan for plugins, making sure to add any directories required. Alternatively, you can drag a plugin file and drop it on the list to add only that plugin.

Once the list has populated, simply select a plugin and press the "Test Selected" button to validate it. The plugin will be loaded and each of the tests run in turn. Any output from the tests will be shown on the "Console" tab. If you find problems with a plugin, this can be useful to send to the plugin developers.

Running in Headless Mode

As well as being a GUI app,

pluginval
can be run from the command line in a headless mode. This is great if you want to add validation as part of your CI process and be notified immediately if tests start failing.
Basic usage is as follows:
./pluginval --strictnessLevel 5 --validate 

This will run all the tests up to level 5 on the plugin at the specified path. Output will be fed to the console. If all the tests pass cleanly,

pluginval
will return with an exit code of
0
. If any tests fail, the exit code will be
1
. This means you can check the exit code on your various CI and mark builds a failing if all tests don't pass.

strictnessLevel
is optional but can be between 1 & 10 with 5 being generally recognised as the lowest level for host compatibility. Lower levels are generally quick tests, mainly checking call coverage for crashes. Higher levels contain tests which take longer to run such as parameter fuzz tests and multiple state restoration.
You can also list all the options with:
./pluginval -h

Guides

Contributing

If you would like to contribute to the project please do! It's very simple to add tests, simply: 1) Subclass

PluginTest
    struct FuzzParametersTest  : public PluginTest
2) Override
runTest
to perform any tests
    void runTest (UnitTest& ut, AudioPluginInstance& instance) override
3) Log passes or failures with the
UnitTest
parameter
    ut.expect (editor != nullptr, "Unable to create editor");
4) Register your test with a static instance of it in a cpp file:
   static FuzzParametersTest fuzzParametersTest;

If you have a case you would like tests, please simply write the test in a fork and create a pull request. The more tests the better!

License

Licensing is under the

GPLv3
as we want
pluginval
to be as transparent as possible. If this conflicts with your requirements though please let us know and we can accommodate these.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.