| name | juce-guide |
| description | Step-by-step guide for building a JUCE audio plugin from scratch. Use when the user asks "how do I create a JUCE plugin", "set up a JUCE project", "add parameters to my JUCE plugin", "package my VST3", or "how do I wire up APVTS". Trigger on phrases like "create a JUCE plugin", "JUCE CMake setup", "AudioProcessor skeleton", "add APVTS parameters", or "codesign my plugin on macOS".
|
JUCE Audio Plugin — Build Guide
Five steps from empty folder to distributable plugin. Do each step in order; skip none.
Step 1 — Project setup (CMake + JUCE)
- Add JUCE as a git submodule or FetchContent target; call
add_subdirectory(JUCE).
- Use
juce_add_plugin(MyPlugin FORMATS VST3 AU Standalone ...) to declare the plugin target.
- Set
PLUGIN_MANUFACTURER_CODE, PLUGIN_CODE, IS_SYNTH, NEEDS_MIDI_INPUT in the same call.
- Link
juce::juce_audio_processors juce::juce_audio_utils juce::juce_dsp to the target.
Step 2 — AudioProcessor skeleton
- Subclass
juce::AudioProcessor; override prepareToPlay, releaseResources, processBlock.
- In
prepareToPlay: store sampleRate and maximumBlockSize, allocate internal buffers, reset all state (filters, envelopes, delay lines — unconditionally).
- In
processBlock: read only pre-cached raw parameter pointers; never allocate, never call JUCE String ops or DBG().
- Implement
getStateInformation / setStateInformation using apvts.copyState() and apvts.replaceState() with a MemoryOutputStream / MemoryBlock.
Step 3 — Parameters via APVTS
- Declare a static
createParameterLayout() method that returns AudioProcessorValueTreeState::ParameterLayout.
- Construct
apvts(*this, nullptr, "Parameters", createParameterLayout()) as a member.
- After constructing APVTS, cache raw pointers once:
gainParam = apvts.getRawParameterValue("Gain").
- In
processBlock, dereference with gainParam->load() — no APVTS calls on the audio thread.
- Use
AudioProcessorValueTreeState::ParameterAttachment (or SliderAttachment) in the editor, never in the processor.
Step 4 — Editor and UI
- Subclass
juce::AudioProcessorEditor; call setSize(w, h) in the constructor.
- Override
paint for background / labels; override resized to lay out components with setBounds.
- Declare
juce::Slider members; attach each via juce::AudioProcessorValueTreeState::SliderAttachment.
- Keep all UI state in the editor — the processor must function correctly with no editor open.
- The editor holds a reference to the processor (passed in constructor); never store a raw editor pointer in the processor.
Step 5 — Build, test, package
- Configure:
cmake -B build -DCMAKE_BUILD_TYPE=Release
- Build:
cmake --build build --config Release
- Locate artefacts under
build/MyPlugin_artefacts/Release/.
- macOS codesign:
codesign --deep --force --sign "Developer ID Application: ..." MyPlugin.vst3 then spctl --assess --verbose MyPlugin.vst3.
- Notarize for distribution:
xcrun notarytool submit MyPlugin.pkg --apple-id ... --wait.
- Validate in a DAW host or use the JUCE
AudioPluginHost utility (extras/AudioPluginHost).
Common pitfalls
| Pitfall | Correct approach |
|---|
Calling apvts.getParameter() in processBlock | Cache getRawParameterValue() once after APVTS construction |
Allocating in processBlock | Allocate in prepareToPlay only |
Not resetting state on prepareToPlay re-entry | Always reset unconditionally |
| Storing editor pointer in processor | Use createEditor() factory; processor owns no editor reference |
Missing JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR | Add to every AudioProcessor and AudioProcessorEditor subclass |
Use the juce-review skill to audit finished processor code for thread-safety violations.
