/juce-guide

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.