vst_playground

A collection of VST3 plugins built with JUCE and CMake, compiled in the cloud via GitHub Actions. No local Xcode or Visual Studio required.

---

Plugins

Plugin	Description	Knobs	Download
reverse_reverb	Reverses audio in a window and applies reverb for a swell effect	Room Size, Wet Mix, Window (ms)	Latest release
pitch_wobble	Applies subtle random pitch deviations for an organic, human feel	Depth (cents), Rate (Hz), Smoothness	Latest release
through_the_wall	Simulates sound passing through a wall with LPF, reverb, and comb filtering	Wall Thickness, Room Bleed, Wall Rattle, Distance	Latest release
drum_smash	Lo-fi drum character processor with saturation, bit crushing, compression and reverb	21 parameters across 8 sections	Latest release
break_scientist	Detects drum hits and displaces them in time (swing, humanize, drag) with velocity variance	6 parameters	Latest release
choir_box	Phase-vocoder harmonizer: up/down pitch-shifted voices with detune spread, panning and a saturation stage	11 parameters	Latest release
lizard_suite	Four lo-fi modules in series: Dust (sampler grit) → Chew (tape dropouts) → Murk (dark reverb) → Vinyl (noise bed)	14 parameters across 4 modules	Latest release
lizard_tape	Lo-fi tape/cassette: asymmetric saturation → wow & flutter → HF roll-off → program-dependent hiss	Drive, Bias, Wow Depth/Rate, Flutter Depth/Rate, Tone, Hiss, Mix, Output	Latest release

Each release page contains a Mac (.zip with .vst3 bundle) and Windows (.zip with .vst3 folder) download. See Installing a Built Plugin below.

The project site (plugin pages, install guide and the install_lizard_vst.py installer script) lives in docs/ and is deployed to GitHub Pages by the Deploy Pages workflow on every push to main that touches docs/.

---

Repo Structure

vst_playground/
├── JUCE/                        ← JUCE as a git submodule (shared by all plugins)
├── shared/                      ← editor/processor helpers used by every plugin
├── <plugin_name>/               ← one folder per plugin (see table above)
│   ├── Source/
│   │   ├── PluginProcessor.h/.cpp
│   │   ├── PluginEditor.h/.cpp
│   │   └── DSP/                 ← JUCE-free DSP cores (newer plugins)
│   ├── test/                    ← standalone g++ tests for the DSP cores
│   └── CMakeLists.txt
├── tests/                       ← Catch2 tests for every processor
├── docs/                        ← GitHub Pages site
└── .github/
    └── workflows/
        ├── build.yml            ← builds + releases changed plugins (or one, manually)
        ├── tests.yml            ← runs all tests on push / PR
        └── pages.yml            ← deploys docs/ to GitHub Pages

Each plugin is a self-contained folder with its own CMakeLists.txt. JUCE lives once at the repo root as a submodule and is referenced by all plugins via a relative path (../JUCE).

---

JUCE Submodule

JUCE is included as a git submodule rather than being downloaded per-plugin via FetchContent. This keeps builds faster and avoids redundant clones.

First-time clone

git clone --recurse-submodules https://github.com/Ricardo-Silva91/vst_playground.git

If you already cloned without submodules

git submodule update --init --recursive

Updating JUCE

cd JUCE
git checkout 7.0.9   # or whichever tag you want
cd ..
git add JUCE
git commit -m "chore: bump JUCE to 7.0.9"

How each plugin's CMakeLists.txt references it

Instead of FetchContent, each plugin uses:

add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../JUCE JUCE_build)

This means all plugins share the same JUCE source. GitHub Actions checks out the submodule automatically (see workflow notes below).

---

Building in the Cloud (GitHub Actions)

Builds are triggered in two ways:

1. Push to main (automatic)

Every push to main (including a merged PR) builds and releases each plugin whose folder changed in that push, for both platforms:

• a change inside pitch_wobble/ builds pitch_wobble
• a change in shared/ or a JUCE submodule bump builds every plugin
• changes to Markdown files only, or outside plugin folders (docs/, tests/, …), build nothing

The commit message doesn't matter, though Conventional Commits scopes like fix(pitch_wobble): … are still a good habit.

2. Manual trigger (workflow_dispatch)

Go to Actions → Build VST → Run workflow on GitHub. You'll get a dropdown to pick which plugin to build and which platforms to target.

---

Installing a Built Plugin

Download the zip for your platform from the plugin's release page (links in the table above).

macOS

1. Unzip the downloaded *_Mac.zip — this preserves the macOS bundle structure
2. Copy the .vst3 bundle to:

   /Library/Audio/Plug-Ins/VST3/
   

3. Remove the quarantine flag (required to bypass Gatekeeper):

   sudo xattr -cr /Library/Audio/Plug-Ins/VST3/YourPlugin.vst3
   

4. Rescan plugins in your DAW

Windows

1. Unzip the *_Windows.zip artifact
2. Copy the .vst3 folder to:

   C:\Program Files\Common Files\VST3\
   

3. Rescan plugins in your DAW (in FL Studio: Options → Manage plugins → Find more plugins)

---

Known Issues & Fixes

#include <JuceHeader.h> causes build failure

Projucer-style includes don't work with CMake. Every source file must include JUCE modules directly:

// ❌ Don't use this
#include <JuceHeader.h>

// ✅ Use direct module includes instead
#include <juce_audio_processors/juce_audio_processors.h>
#include <juce_dsp/juce_dsp.h>

macOS bundle structure gets corrupted by the artifact zip

GitHub Actions' upload-artifact re-zips files and destroys the .vst3 bundle's internal directory structure. The fix is to manually zip the bundle before uploading:

- name: Zip VST3 bundle
  run: |
    cd build
    zip -r MyPlugin.vst3.zip MyPlugin.vst3
- uses: actions/upload-artifact@v4
  with:
    path: build/MyPlugin.vst3.zip   # upload the zip, not the raw bundle

Then unzip locally before installing (see Installing section above).

---

Adding a New Plugin

1. Create a new folder at the repo root (e.g. my_plugin/)
2. Add Source/PluginProcessor.h, Source/PluginProcessor.cpp, Source/PluginEditor.h, Source/PluginEditor.cpp
3. Add a CMakeLists.txt — reference JUCE as ../JUCE:

   add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../JUCE JUCE_build)
   

4. Add the folder name to the options: list in .github/workflows/build.yml:

   options:
     - reverse_reverb
     - pitch_wobble
     - my_plugin      ← add this
   

5. Push to main (or merge a PR) — the new folder triggers its first build.
6. Once the build completes, a release will be created at:

   https://github.com/Ricardo-Silva91/vst_playground/releases/tag/my_plugin-latest
   

   Add a download link for it in the Plugins table above.