Skip to content

kunitoki/sonic-skills / skills/yup-review

yup-review

Verified

Reviews YUP audio plugin code for YUP-specific correctness issues: AudioProcessor lifecycle, AudioParameterBuilder and AudioParameterHandle usage, editor gestures, AudioBusLayout handling, CLAP/VST3 wrapper contracts, state recall, and MIDI safety. Use when the user asks to review a YUP plugin, check a processBlock, audit parameter smoothing, or asks "is this YUP code safe?". Trigger when you see yup::AudioProcessor, yup_audio_plugin, AudioParameterBuilder, AudioParameterHandle, AudioProcessorEditor, or createPluginProcessor in the code.

FileKindSize
SKILL.mdskill md6.3 KB
references/yup-violations.mdmarkdown10.5 KB

references/yup-violations.md

View on GitHub
# YUP Violation Catalogue

Full reference for `yup-review`. Each section shows the BAD pattern, why it is wrong, and the GOOD replacement.

---

## 1. Parameter Handle Patterns

### Using AudioParameterHandle before prepareToPlay

`yup::AudioParameterHandle` stores a raw parameter pointer and a smoother configured with the current sample rate. A default-constructed handle is not usable.

**BAD**
```cpp
class MyPlugin : public yup::AudioProcessor
{
    yup::AudioParameter::Ptr gainParam;
    yup::AudioParameterHandle gain;

    void processBlock (yup::AudioSampleBuffer& buffer, yup::MidiBuffer&) override
    {
        gain.updateNextAudioBlock(); // parameter pointer may still be null
        buffer.applyGain (gain.getCurrentValue());
    }
};
```

**GOOD**
```cpp
void prepareToPlay (float sampleRate, int maxBlockSize) override
{
    ignoreUnused (maxBlockSize);
    gain = yup::AudioParameterHandle (*gainParam, sampleRate);
}

void processBlock (yup::AudioSampleBuffer& buffer, yup::MidiBuffer&) override
{
    if (gain.updateNextAudioBlock())
    {
        const auto start = gain.getCurrentValue();
        const auto end = gain.skip (buffer.getNumSamples());
        buffer.applyGainRamp (0, buffer.getNumSamples(), start, end);
    }
    else
    {
        buffer.applyGain (gain.getCurrentValue());
    }
}
```

### Recreating handles in processBlock

Constructing the handle in the callback resets the smoother and makes automation zipper or stick.

**BAD**
```cpp
void processBlock (yup::AudioSampleBuffer& buffer, yup::MidiBuffer&) override
{
    yup::AudioParameterHandle gain (*gainParam, getSampleRate());
    gain.updateNextAudioBlock();
    buffer.applyGain (gain.getCurrentValue());
}
```

**GOOD**
Construct handles once in `prepareToPlay`, then update once per block.

---

## 2. Host Notification and Gestures

### setValueNotifyingHost from audio thread

`setValueNotifyingHost()` calls parameter listeners. Use it for UI/host-control paths, not for audio-rate processing.

**BAD**
```cpp
void processBlock (yup::AudioSampleBuffer&, yup::MidiBuffer& midi) override
{
    for (const auto metadata : midi)
        if (metadata.getMessage().isController())
            gainParam->setValueNotifyingHost (metadata.getMessage().getControllerValue() / 127.0f);
}
```

**GOOD**
```cpp
void processBlock (yup::AudioSampleBuffer&, yup::MidiBuffer& midi) override
{
    for (const auto metadata : midi)
        if (metadata.getMessage().isController())
            gainParam->setNormalizedValue (metadata.getMessage().getControllerValue() / 127.0f);
}
```

For editor controls, notify the host and bracket drags:

```cpp
slider->onDragStart = [this] (const yup::MouseEvent&) { gainParam->beginChangeGesture(); };
slider->onValueChanged = [this] (float value) { gainParam->setValueNotifyingHost (value); };
slider->onDragEnd = [this] (const yup::MouseEvent&) { gainParam->endChangeGesture(); };
```

---

## 3. Realtime Allocation and Logging

YUP core types such as `yup::String`, `yup::MemoryBlock`, file/network classes, JSON/XML helpers, `Logger`, and `YUP_DBG` can allocate or perform I/O. Keep them out of `processBlock` and DSP helpers called by it.

**BAD**
```cpp
void processBlock (yup::AudioSampleBuffer& buffer, yup::MidiBuffer&) override
{
    yup::String message = "samples=" + yup::String (buffer.getNumSamples());
    yup::Logger::writeToLog (message);
}
```

**GOOD**
```cpp
std::atomic<int> lastBlockSize { 0 };

void processBlock (yup::AudioSampleBuffer& buffer, yup::MidiBuffer&) override
{
    lastBlockSize.store (buffer.getNumSamples(), std::memory_order_relaxed);
}
```

The editor or a background diagnostic thread can format and log the value later.

---

## 4. MIDI and Voice Storage

### Allocating voices on note-on

Dynamic containers can grow during note-on bursts. Preallocate a bounded voice pool in `prepareToPlay`.

**BAD**
```cpp
void processBlock (yup::AudioSampleBuffer&, yup::MidiBuffer& midi) override
{
    for (const auto metadata : midi)
        if (metadata.getMessage().isNoteOn())
            voices.push_back (Voice { metadata.getMessage().getNoteNumber() }); // may allocate
}
```

**GOOD**
```cpp
static constexpr int maxVoices = 32;
std::array<Voice, maxVoices> voices {};

Voice* allocateVoice (int note)
{
    for (auto& voice : voices)
    {
        if (! voice.active)
        {
            voice.note = note;
            voice.active = true;
            voice.phase = 0.0f;
            return &voice;
        }
    }

    return stealQuietestVoice (note);
}
```

### Mutating MidiBuffer while iterating

Do not add/remove events from the same `MidiBuffer` iterator is traversing. Use a preallocated outgoing event buffer or collect bounded events, then rewrite after iteration.

**BAD**
```cpp
for (const auto metadata : midi)
    if (metadata.getMessage().isNoteOn())
        midi.addEvent (yup::MidiMessage::noteOff (1, metadata.getMessage().getNoteNumber()), 0);
```

**GOOD**
```cpp
std::array<yup::MidiMessage, 64> pendingNoteOffs {};
int pendingCount = 0;

for (const auto metadata : midi)
{
    if (metadata.getMessage().isNoteOn() && pendingCount < static_cast<int> (pendingNoteOffs.size()))
        pendingNoteOffs[pendingCount++] = yup::MidiMessage::noteOff (1, metadata.getMessage().getNoteNumber());
}

midi.clear();
for (int i = 0; i < pendingCount; ++i)
    midi.addEvent (pendingNoteOffs[i], 0);
```

---

## 5. Locking and Thread Synchronisation

### yup::CriticalSection on the audio thread

`yup::CriticalSection` wraps a platform mutex. Locking it on the audio thread causes priority
inversion. Even `tryEnter()` is unsafe: if it succeeds, the destructor (or `exit()`) must
interact with the OS scheduler to wake any waiting thread — a system call.

**BAD**
```cpp
yup::CriticalSection cs;

void processBlock (yup::AudioSampleBuffer& buffer, yup::MidiBuffer&) override
{
    if (cs.tryEnter()) {
        // ... access shared data ...
        cs.exit();  // <-- may do a syscall to wake waiting threads
    }
}
```

**GOOD — use atomics or lock-free queues instead**
```cpp
std::atomic<float> sharedGain { 1.0f };

void processBlock (yup::AudioSampleBuffer& buffer, yup::MidiBuffer&) override
{
    const float g = sharedGain.load (std::memory_order_relaxed);
    buffer.applyGain (g);
}
```

### Spinlocks — last resort

If you must use a spinlock (e.g., for a shared voice pool or audio graph that another thread
modifies), the audio thread calls only `try_lock()` + fallback. The non-audio thread uses
progressive back-off to avoid burning CPU. See `audio-dsp-review/references/realtime-violations.md`
Section 2 for the full `audio_spin_mutex` implementation.

**Prefer immutable patterns over any spinlock.** Build a new data structure off the audio
thread and atomically swap a pointer. The audio thread always reads a consistent snapshot
without any lock.

---

## 6. Bus Layout and Channel Access

YUP exposes fixed bus layout through `yup::AudioBusLayout`, but `processBlock` still receives a buffer from the wrapper/host. Guard channel access unless the layout and format guarantee it.

**BAD**
```cpp
float* left = buffer.getWritePointer (0);
float* right = buffer.getWritePointer (1); // crashes for mono output
```

**GOOD**
```cpp
const int channels = buffer.getNumChannels();
const int samples = buffer.getNumSamples();

for (int ch = 0; ch < channels; ++ch)
{
    auto* out = buffer.getWritePointer (ch);
    for (int n = 0; n < samples; ++n)
        out[n] = renderSampleForChannel (ch);
}
```

If the algorithm requires stereo, declare stereo output in the processor constructor and validate that assumption in tests.

---

## 7. Lifecycle Reset and Flush

`prepareToPlay` can be called repeatedly on sample-rate or block-size changes. CLAP reset calls `flush()`. Both must leave the processor in a deterministic state.

Checklist:
- Reset all oscillators, filters, delay lines, envelopes, meters, FFT overlap buffers, and phase counters.
- Rebuild `AudioParameterHandle`s with the current sample rate.
- Clear or reinitialise voice state and pending MIDI.
- Resize scratch buffers to worst-case `maxBlockSize` outside the audio callback.
- In `flush()`, stop held voices and clear tails/pending events without freeing memory needed for the next block.

**BAD**
```cpp
void prepareToPlay (float sampleRate, int maxBlockSize) override
{
    ignoreUnused (sampleRate, maxBlockSize);
    gain = yup::AudioParameterHandle (*gainParam, sampleRate);
    // Filter history, delay buffers, held voices left untouched.
}
```

**GOOD**
```cpp
void prepareToPlay (float sampleRate, int maxBlockSize) override
{
    this->sampleRate = sampleRate;
    scratch.setSize (2, maxBlockSize);
    gain = yup::AudioParameterHandle (*gainParam, sampleRate);
    filter.reset();
    delay.clear();
    clearVoices();
}

void flush() override
{
    clearVoices();
    delay.clear();
    pendingMidi.clear();
}
```

---

## 7. State and Presets

Hosts rely on `loadStateFromMemory` and `saveStateIntoMemory` for session recall. Leaving them as `Result::fail ("Not implemented")` is only acceptable for throwaway examples.

**BAD**
```cpp
yup::Result saveStateIntoMemory (yup::MemoryBlock&) override
{
    return yup::Result::fail ("Not implemented");
}
```

**GOOD**
Serialise all parameter IDs/values and preset data into a versioned format, validate on load, then set parameters from the state callback:

```cpp
yup::Result loadStateFromMemory (const yup::MemoryBlock& data) override
{
    auto state = parseState (data);
    if (! state.valid)
        return yup::Result::fail ("Invalid plugin state");

    gainParam->setValue (state.gain);
    currentPreset = state.currentPreset;
    return yup::Result::ok();
}
```

If state restore swaps large shared DSP data, build it off the audio thread and publish it through a short lock-free or bounded handoff.

---

## 8. Recommended YUP Patterns Summary

| Concern | Recommended pattern |
|---------|---------------------|
| Parameter creation | `AudioParameterBuilder` in processor constructor; stable unique IDs |
| Audio-thread parameter reads | `AudioParameterHandle` initialised in `prepareToPlay`, updated once per block |
| UI parameter edits | `beginChangeGesture` / `setValueNotifyingHost` / `endChangeGesture` |
| Preset/state changes | `setValue` or `setNormalizedValue` from non-audio callbacks, then handle picks up change |
| Audio-to-UI meters | Atomics or preallocated SPSC queue; editor `Timer` polls |
| MIDI voice management | Preallocated bounded voice pool; no allocation on note-on |
| Bus handling | Explicit `AudioBusLayout`; channel-count guards in `processBlock` |
| Reset | Full reset in `prepareToPlay`; tail/voice clear in `flush()` |
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall