Skip to content

kunitoki/sonic-skills / skills/juce-guide

juce-guide

Unverified

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

PitfallCorrect approach
Calling apvts.getParameter() in processBlockCache getRawParameterValue() once after APVTS construction
Allocating in processBlockAllocate in prepareToPlay only
Not resetting state on prepareToPlay re-entryAlways reset unconditionally
Storing editor pointer in processorUse createEditor() factory; processor owns no editor reference
Missing JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTORAdd to every AudioProcessor and AudioProcessorEditor subclass

Use the juce-review skill to audit finished processor code for thread-safety violations.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall