Validate Pluginval

pluginval

Cross-platform validator for VST3 and AudioUnit plugins.

Plugin Install Locations

pluginval accepts a direct path. These are the standard install locations by format.

AudioUnit (.component) — macOS only:

VST3 (.vst3):

Instructions

1. Install pluginval (see Installation below)
2. Locate the built plugin (.vst3 or .component) in your build output directory or one of the standard locations above
3. Run at strictness level 5 (recommended minimum):
   • macOS: /Applications/pluginval.app/Contents/MacOS/pluginval --strictness-level 5 /path/to/plugin
   • Windows: pluginval.exe --strictness-level 5 "C:\path\to\plugin.vst3"
   • Linux: pluginval --strictness-level 5 /path/to/plugin.vst3
4. If it crashes on a multi-bus VST3, use validate-vst3 instead
5. For CI, add --skip-gui-tests for headless environments

Installation

Download from GitHub Releases.

Verify installation:

bashCopy code
# macOS
/Applications/pluginval.app/Contents/MacOS/pluginval --help

# Windows
pluginval.exe --help

# Linux
pluginval --help

Basic Usage

bashCopy code
# macOS
/Applications/pluginval.app/Contents/MacOS/pluginval --strictness-level 5 /path/to/plugin

# Windows
pluginval.exe --strictness-level 5 "C:\path\to\plugin.vst3"

# Linux
pluginval --strictness-level 5 /path/to/plugin.vst3

Strictness Levels

At levels 5+, pluginval automatically runs auval for AudioUnits and VST3 validator for VST3.

Command Line Options

bashCopy code
# Set strictness level (1-10)
--strictness-level 5

# Skip GUI tests (useful for headless CI)
--skip-gui-tests

# Set timeout in milliseconds (use "-1" to disable)
--timeout-ms 30000

# Output logs to directory
--output-dir /path/to/logs

# Set log filename (within output-dir or current directory)
--output-filename results.log

# Repeat tests multiple times
--repeat 3

# Randomize test order
--randomise

# Use specific random seed (for reproducibility)
--seed 0x374115a

# Verbose output
--verbose

# Custom sample rates (comma-separated, default: 44100,48000,96000)
--sample-rates 44100,48000,96000,192000

# Custom block sizes (comma-separated, default: 64,128,256,512,1024)
--block-sizes 64,128,256,512,1024

# Provide a data file for test configuration
--data-file /path/to/config.txt

# Disable specific tests (file with one test name per line)
--disabled-tests /path/to/disabled.txt

# Specify path to VST3 validator (run as part of test process)
--vst3validator /path/to/validator

Environment Variables

All command line options can be set as environment variables by removing the -- prefix, converting dashes to underscores, and uppercasing. Command line options override environment variables.

bashCopy code
# Examples
export STRICTNESS_LEVEL=5
export SKIP_GUI_TESTS=1
export TIMEOUT_MS=30000
export SAMPLE_RATES="44100,48000,96000"
export BLOCK_SIZES="64,128,256,512,1024"

CI Integration

macOS / Linux

bashCopy code
pluginval --strictness-level 5 --skip-gui-tests --timeout-ms 60000 /path/to/plugin.vst3

if [ $? -ne 0 ]; then
  echo "Plugin validation failed!"
  exit 1
fi

Windows (PowerShell)

powershellCopy code
& pluginval.exe --strictness-level 5 --skip-gui-tests --timeout-ms 60000 "C:\path\to\plugin.vst3"

if ($LASTEXITCODE -ne 0) {
    Write-Error "Plugin validation failed!"
    exit 1
}

Reproducing Failures

pluginval uses randomness for some tests. To reproduce a failure:

1. Note the random seed from the log (e.g., Random seed: 0x374115a)
2. Re-run with that seed:

bashCopy code
/Applications/pluginval.app/Contents/MacOS/pluginval --seed 0x374115a -s 5 /path/to/plugin

Known Limitations

No CLAP Support

Use clap-validator for CLAP plugins.

Multi-Bus VST3 Plugins May Crash

Plugins with multiple audio buses (multi-output instruments, sidechain effects) may crash pluginval during VST3 validation.

Workaround:

1. Use the official Steinberg VST3 validator instead
2. Test the AU version with pluginval (usually works)
3. Verify with auval for AU format