Expert guidance for real-time audio plugin development with JUCE 8. Enforces RT-safe DSP patterns, STFT masking pipeline, and lock-free threading. Ensures zero-allocation processBlock and sub-5ms paint-to-audio latency.
Expert guidance for developing SpectralCanvas Pro, a real-time audio plugin with spectrogram painting to STFT masking. Enforces strict RT-safety, zero-allocation DSP, and lock-free threading patterns.
This skill provides expert assistance for working with the SpectralCanvas Pro codebase, a JUCE 8-based audio plugin featuring:
You MUST enforce these rules in ALL audio thread code:
1. **Zero heap allocations** in `processBlock()` - preallocate all buffers in `prepareToPlay()`
2. **No mutex locks** on audio thread - use lock-free SPSC queues only
3. **No vector resizing** during processing - fixed-size containers only
4. **Wrap processBlock with** `juce::ScopedNoDenormals`
5. **Set latency to** `FFT_SIZE - HOP_SIZE` (384 samples) and assert it
6. **Copy only one column** (NUM_BINS floats) per delta - never whole tiles
Always use these from `Source/Core/AtlasIds.h`:
```cpp
FFT_SIZE = 512
HOP_SIZE = 128
NUM_BINS = 257 // FFT_SIZE/2 + 1
TILE_HEIGHT = 257 // NUM_BINS
TILE_WIDTH = 512
```
Three-thread lock-free design:
```
Audio Thread ←→ UI Thread ←→ GPU Thread
(STFT) (Painting) (Rendering)
↕ ↕ ↕
MaskAtlas ← MaskDeltaQueue → RenderQueue
```
**Key Data Flow:**
UI Painting → MaskDeltaQueue → HopScheduler → MaskAtlas → RealtimeSpectral → Audio Output
Before making ANY changes:
**Read essential documentation:**
**Identify protection level:**
For changes affecting >3 files or architecture:
1. Enter plan mode with clear objectives
2. Map thread boundaries and data flow
3. Identify all RT-safety requirements
4. Design lock-free communication patterns
5. Plan buffer preallocation strategy
6. Document performance impact
**For DSP/Audio Changes:**
1. Preallocate ALL buffers in `prepareToPlay()`:
```cpp
void prepareToPlay(double sampleRate, int samplesPerBlock) {
fftBuffer.resize(FFT_SIZE, 0.0f);
windowBuffer.resize(FFT_SIZE, 0.0f);
// Never resize after this point
}
```
2. Use RT-safe patterns from `Source/Core/`:
- Lock-free SPSC queues for thread communication
- Atomic operations for simple state
- Double-buffering with atomic flip for complex state
3. Preserve phase in STFT processing:
- Scale FFT bins uniformly by mask magnitudes
- Never modify phase components
- Use proper windowing (Hann) and overlap-add
4. Process as mono internally, replicate to all output channels
**For UI Changes:**
1. Paint operations write to MaskDeltaQueue (lock-free)
2. Limit delta rate to prevent queue overflow
3. Use 60fps timer for painting updates
4. All brush tools write column deltas, not tiles
**For GPU Changes:**
1. Maintain 60fps target with WARP fallback
2. Handle device loss gracefully
3. Use debug layer in development builds
4. Particle systems must be toggleable
REQUIRED before ANY commit:
```bash
cmake -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_RT_SAFETY=ON
cmake --build build --config Debug
build/Tests/RTSafetyTest
pluginval --strictness-level 8 build/SpectralCanvasPro_artefacts/RelWithDebInfo/VST3/SpectralCanvasPro.vst3
ctest --test-dir build -V
```
**Manual test checklist:**
Enforce these targets:
Use HUD instrumentation to verify delta drain rates and frame timing.
**Standard build:**
```bash
cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo -DSCP_INSTALL_SHADERS=ON
cmake --build build --config RelWithDebInfo
```
**Debug build with RT checks:**
```bash
cmake -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_RT_SAFETY=ON
cmake --build build --config Debug
```
**Clean build:**
```bash
rm -rf build
cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build
```
**Audio Dropouts:**
1. Check processBlock() for new allocations (use RT-safety tests)
2. Verify queue capacities aren't exceeded
3. Disable non-essential features temporarily
4. Check HUD for delta drain overruns
**GPU Issues:**
1. Force WARP fallback: `D3D_DRIVER_TYPE_WARP`
2. Disable particle system: `particlesEnabled_ = false`
3. Enable D3D11 debug layer for leak detection
4. Check for resource leaks in shutdown
**Build Failures:**
1. Clean build directory completely
2. Verify JUCE version is 8.0.8
3. Update submodules: `git submodule update --recursive --init`
4. Check CMake cache for stale paths
Before approving any changes, verify:
For advanced DSP questions, refer to the knowledge system:
Ground all technical decisions in authoritative sources while maintaining RT-safety requirements.
```
Title: ≤6 words, imperative mood
Body: What changed, why, and RT-safety guarantees.
Include performance impact and validation results.
Example:
Enable RT STFT masking
Implements double-buffered MaskAtlas with atomic flip, HopScheduler
draining ≤16 UI column-deltas per block, and preallocated RealtimeSpectral
STFT→mask→iSTFT→OLA path. Verified zero allocations in processBlock and
correct latency reporting. Passes pluginval strictness level 8.
```
**Phase 4 (HEAR):** COMPLETE - RT-safe STFT masking pipeline operational
This is a passion project focused on making spectral manipulation immediate, musical, and expressive. Every decision must serve that goal while maintaining uncompromising RT-safety. When in doubt, prioritize:
1. RT-safety over features
2. Latency over visual polish
3. Simplicity over configurability
4. Measurements over assumptions
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/spectralcanvas-pro-juce-development/raw