pluginval: a validator that loads your plugin in a separate process

What pluginval is for and who runs it

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.

Two audiences share the same binary, and they want different things from it. A plugin developer wants to know which of their own bugs will show up in someone else's DAW. A host developer wants to know whether a third party plugin will crash or misbehave before a user finds out.

There is a third audience, and the documentation addresses it directly. 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 the documentation says can drastically improve the time to fix issues. The reasoning is sound: a bug report that says the plugin crashes when opening the editor is far less useful than one that includes the specific call sequence that triggered it, and a validator that exercises a plugin systematically produces exactly that.

The highlights list is short. It tests VST, AU and VST3 plugins. It is compatible with macOS, Windows and Linux. It runs in GUI or headless mode. And validation is performed in a separate process to avoid crashing.

That last point is the design decision that makes the rest work, and it is worth pausing on. A plugin validator loads third party code that is, by definition, unreliable. Running that code inside the validator's own process means a crash takes the validator down with it, and you lose the log you needed. Isolating the load means the validator survives, captures the failure, and can tell you what happened.

The headless mode and the strictness levels

The command line mode is what makes the tool usable in a pipeline, and the basic usage is one command:

./pluginval --strictness-level 5 <path_to_plugin>

That runs all the tests up to level 5 on the plugin at the given path, and the output is fed to the console.

The exit code contract is the part that matters for CI. If all the tests pass cleanly, pluginval returns an exit code of 0. If any tests fail, the exit code is 1. That means you can check the exit code on your CI and mark the build as failing if the tests do not pass. No log parsing, no output scraping.

The strictness level is optional and can be between 1 and 10, with 5 described as generally recognised as the lowest level for host compatibility. The lower levels are generally quick tests, mainly checking call coverage for crashes, while the higher levels contain tests which take longer to run, such as parameter fuzz tests and multiple state restoration. That distinction is the practical one: a level 1 run is a cheap smoke test, and a level 10 run is a long soak that hunts for the state bugs fuzzing and restoration tend to expose.

The full option list is available with:

./pluginval -h

The documentation also points to a guide on adding pluginval to CI, and a separate guide on acceptance testing, which is the document to read before you make a passing run a release gate.

The GUI workflow for diagnosing a failure

The GUI exists for the case where the headless run told you something failed and you now need to see why.

Once the app has built for your platform it is found in /bin, and opening it starts it in GUI mode. You are presented with an empty plugin list, and you 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, which is the faster route when you already know which binary you care about.

Once the list has populated, you select a plugin and press the Test Selected button to validate it. The plugin is loaded and each of the tests run in turn, and any output from the tests is shown on the Console tab.

That Console tab is the whole point. The documentation says that if you find problems with a plugin, this output can be useful to send to the plugin developers, which is the same use case as the headless log, just with a way to watch the run happen.

The two modes are therefore complementary rather than redundant. Headless gives you a pass or fail signal in a pipeline, and the GUI gives you the trace to work from. The documentation recommends building locally in Debug once you need to debug a failed validation, because the stack traces then point into your own code rather than into an optimised build.

Building from source and the JUCE submodule route

The easiest way to get started is to grab pre-compiled binaries from the releases page, and the documentation notes that those are compiled with support for testing VST2.

Once you need to debug a failed validation, you will probably want to build locally in Debug:

cmake -B Builds/Debug -DCMAKE_BUILD_TYPE=Debug . # configure (downloads JUCE and the other dependencies)
cmake --build Builds/Debug --config Debug # build

The configure step downloads JUCE and the other dependencies, so the first build needs network access and takes a while.

The more interesting integration is adding pluginval to an existing JUCE plugin project. Instead of running it as a separate app, you can add it as a CMake target, and the documentation gives two reasons: it makes for a convenient debugging workflow, and it gives you better stack traces.

The dependency is added as a git submodule:

git submodule add -b develop [email protected]:Tracktion/pluginval.git modules/pluginval

or with CPM:

CPMAddPackage("gh:tracktion/pluginval#develop")

Then you call add_subdirectory ("modules/pluginval") in your CMakeLists.txt, and the documentation is specific about ordering: that call should be done after your call to juce_add_plugin. There is a version constraint too, since only JUCE 8 and 9 are currently supported and tested for this method.

A third party option exists for Windows users, since a Chocolatey package is maintained:

> choco install pluginval

VST2 support and the environment variable you have to set

VST2 is the awkward corner of this project and the documentation is upfront about it.

The pre-compiled binaries are built with VST2 support. The VST2 SDK, however, is no longer included in JUCE, so VST2 support is not available from a fresh clone. To enable it locally you set the VST2_SDK_DIR environment variable to point at the VST2 source directory on your system:

VST2_SDK_DIR=Builds/Debug/pluginval_artefacts/ cmake -B Builds/Debug .

Two implications follow. First, a plugin developer who needs to validate their VST2 build has to obtain the VST2 SDK separately, which is a licensing question in its own right and outside what this repository handles. Second, the path in the example is a build artefact directory, so the variable is set to where the sources ended up after the JUCE download rather than to a system location.

This is also the reason the pre-built binaries are worth taking first. Since they already carry VST2 support, a developer who just wants to validate a VST2 plugin does not have to assemble the SDK and the environment variable before the first run. Building from source is the path you take when you need to debug, and at that point the SDK question is unavoidable.

Writing your own tests and how releases are cut

The project treats a test suite as a contribution surface, and the documentation describes how to add one in four steps.

You subclass PluginTest:

    struct FuzzParametersTest  : public PluginTest

You override runTest to perform your tests, taking a UnitTest reference and an AudioPluginInstance reference:

    void runTest (UnitTest& ut, AudioPluginInstance& instance) override

You log passes or failures through the UnitTest parameter:

    ut.expect (editor != nullptr, "Unable to create editor");

And you register the test with a static instance of it in a cpp file:

   static FuzzParametersTest fuzzParametersTest;

The static instance is the mechanism, and it is a JUCE convention: the test framework discovers the test by finding the static object at startup. The documentation is encouraging about contributions, saying it is very simple to add tests and that the more tests the better, and it asks people with a case they would like tests for to write the test in a fork and open a pull request.

Releases are cut by hand. The steps are to update VERSION, update CHANGELIST.md, commit with a message like Version 1.0.5, tag it with a message of the same version, and push the tags with git push --tags.

The repository tree reflects that manual process. There is a VERSION file at the root, a CHANGELIST.md rather than the more usual CHANGELOG.md, a ROADMAP.md for what is planned, a FUNDING.md, and directories named acceptance/, validate/, tests/ and source/.

The recent tags are all from the 2.0.0 beta series, with beta1 on 2026-10-13, beta2 on 2026-10-14 and beta3 on 2026-10-14, and the last push was on 2026-10-15. Three betas in three days tells you the 2.0 line is still moving, so pin the binary you validate against.

Where pluginval is the wrong tool

The first limit is that it tests the plugin, not the host. The checks are about a plugin's own behaviour across calls, parameters and state changes. They do not tell you how a particular host drives your plugin, which is a different question that needs a different tool, and the acceptance testing guide in the docs directory is the place to look for the boundary between the two.

The second is format coverage. The highlights list VST, AU and VST3. Anything outside those three is not covered, and VST2 needs the SDK arranged by hand, as described earlier.

The third is what happens when a plugin is subtly wrong rather than obviously broken. The higher strictness levels hunt for parameter fuzz failures and state restoration problems, which is valuable, but there is no substitute for a human listening to the plugin. A validator tells you the plugin did not crash and that its parameter handling is consistent. It does not tell you the compressor sounds wrong.

The fourth is the reverse direction. If you are a plugin user, pluginval is a tool for producing a bug report, not a tool for choosing between plugins. There is no compatibility matrix here, and the documentation does not describe one.

Compare that with a host based test: a script that loads the plugin in a real host and drives it through the host's own automation and UI. The difference in approach is that a host based test tells you about the combination, including the parts of the host that misbehave, while pluginval isolates the plugin so that a failure can be attributed. For a plugin developer chasing a crash, that attribution is the whole point; for a host developer who already knows the plugin works, it is not enough.

Licence, funding and the state of the project

pluginval is released under the GPL-3.0 licence, with the text in the LICENSE file at the repository root. Strong copyleft is a meaningful constraint for a commercial plugin developer, since linking a GPL tool into a proprietary product is a different legal question from running the tool against your plugin. Read the LICENSE file yourself and take your own advice on how the terms apply to your situation, because this is not legal advice.

The project is free and open source, and the documentation says that supporting it via funding is a good way to show appreciation, speed up development and influence the roadmap. There is a FUNDING.md file with the details and a list of diamond sponsors, which tells you that the project is sponsored by commercial audio software businesses and that sponsors have a say in direction.

On the state of the tree, the default branch is develop, and the README shows build badges for both master and develop, so the project maintains a stable line and a development line. The recent releases are 2.0.0 betas, three of them inside two days, and the last push was on 2026-10-15, so the code is current.

The 2.0 series also comes with a documentation directory that has four guides, testing plugins, debugging a failed validation, adding pluginval to CI, and acceptance testing, and a Doxyfile at the root, which indicates a Doxygen setup for the source documentation.

What to verify before you adopt it is narrow and concrete. Run the level 5 strictness sweep on your own plugin in a Debug build so the traces point at your code, and run it on a plugin you know is good so you can see what a clean report looks like in your environment. Then read the acceptance testing guide to understand what a passing result does and does not certify, because that guide is where the boundary between a validator and a host test is documented.

Editorial conclusion

pluginval fits a plugin developer who needs a repeatable compatibility check across VST, AU and VST3, and a host developer who needs to know whether a third party plugin will misbehave, and it fits CI because the headless mode returns a plain exit code. It does not fit a user who wants to test a plugin for a specific host, since the checks are about the plugin rather than about how a given host drives it. Before adopting it, run the level 5 strictness sweep on your own build in Debug so the stack traces point at your code, confirm your format is one of the three it covers, and read the acceptance testing guide before you treat a passing run as a release gate.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. Tracktion/pluginval on GitHub