October 22, 2026
Step 6: Playing the Grain Cloud Live
Taking Drizel from an offline render into a live JUCE audio callback.
In Step 5, Drizel could schedule overlapping grains and write their texture to a WAV file. That proved the cloud could be rendered, but it did not yet play as an instrument.
Step 6 connects that same grain cloud to JUCE's audio callback. A WAV can now be loaded in the plugin, and the sound can be shaped while it plays. The new challenge is not just generating audio: it is doing predictable work on the audio thread while sample loading and parameter changes happen elsewhere.
This is Layer 5, the real-time engine milestone in the Drizel roadmap. It is not the later promptable-modulation layer, and passing automated tests does not yet complete all of Layer 5's exit criteria.
From file renderer to live instrument
The previous step asked for an output duration, rendered that many frames, and saved them. A plugin has no such fixed render: the host repeatedly asks for the next block of samples, and that callback has a deadline. If it blocks or does unpredictable work, the result can be an audible dropout.
So the engine keeps the existing grain cloud, but divides the surrounding work by thread. The worker loads and prepares a sample. The audio callback only renders from data that is already ready. The editor presents controls and loading status; it does not own the audio engine.
The live path
What the controls do
The first version keeps the instrument intentionally small. It plays continuously when enabled; MIDI notes are not needed. Each grain is 100 ms long, uses a Hann envelope, and spreads across stereo. The controls are:
| Control | Range | What it changes |
|---|---|---|
| Position | 0–1 | Where grains start in the sample, not a moving playhead |
| Pitch | −24 to +24 semitones | Grain playback rate, corrected for sample and output rates |
| Density | 1–100 grains/s | How often new grains are started |
| Output gain | 0–1 | Smoothed level after the cloud is mixed |
| Play | On/off | Smoothly mutes the output; the scheduler keeps running |
Position is a location in the source, rather than a cursor that scans from start to finish. Near the end of a file, reads are zero-padded instead of wrapping back to the beginning. The existing linear interpolator also retains its pitch-shifting aliasing limitations.
Keep loading away from the callback
Opening a WAV involves file access, decoding, scanning the samples, and preparing window tables. None of that belongs in the audio callback. Instead, the worker builds a complete prepared sample and cloud, then publishes that packet for the audio thread to adopt.
Ownership matters because grains borrow the sample data and window tables. Those objects must stay at a stable address and remain alive for as long as any grain might read them. The engine therefore transfers exclusive ownership through single-slot atomic mailboxes; it does not treat an atomic raw pointer as if it were safe shared ownership.
- The control side queues a file path and request revision. The worker decodes the file and prepares its data.
- The worker publishes the completed packet. If a newer request makes it obsolete, the worker can discard it.
- When the callback sees a pending packet, it fades the output down over 10 ms before taking ownership at silence.
- It retires the previous packet for the worker to reclaim, then fades back in over 10 ms.
This is a short dip, not a seamless crossfade. If the worker has not reclaimed the old packet yet, the callback postpones a swap rather than waiting, deleting data, or overwriting an uncollected retirement slot. Slow loading or reclamation can extend the dip.
A failed load is reported in the status line and leaves the currently playing sample in place. Sample preparation is bounded to 256 MiB per decoded sample, although the old, pending, and in-progress samples can temporarily coexist, so total use can exceed that single-sample limit.
Smooth changes without rebuilding the cloud
A control can change between audio blocks. Jumping directly to a new value can create an abrupt change in the sound, so the processor reads parameter targets once per block and smooths them over 20 ms as it renders frames:
current += (1.0 - std::exp(-1.0 / (sampleRate * 0.020)))
* (target - current);Position, pitch, and density are passed to the cloud as they move toward their targets. Existing grains keep the values they started with; new values affect grains launched afterwards. Output gain and Play smooth the final mix.
The cloud prepares its conservative gain at the maximum supported density of 100 grains per second. The live density control can move down from that ceiling, but cannot exceed it. This avoids changing the prepared gain abruptly while density moves, though sparse textures may consequently sound quieter.
What the callback does not do
The callback handles the actual block length supplied by the host, renders stereo output, and averages the channels for a mono destination. It also clears unused channels and checks that the output remains finite and within the configured bounds.
The rendering path avoids file I/O, locks, allocation, deallocation, logging, window creation, source scans, UI calls, and thread creation. Atomic pointer and float operations are checked for lock-freedom at compile time. A worker thread handles loading and reclamation; the processor owns the worker and engine beyond the lifetime of the editor window.
Avoiding those operations is necessary engineering for a real-time audio path, but it is not a guarantee that every host, device, and buffer size will meet its deadline. That needs measurement on the target system.
State, formats, and things still to do
The plugin stores its parameter values and the path of the selected sample in host state, not a copy of the audio. On restore it queues another background load. The file therefore needs to remain at its saved location; a missing file is reported as an error. An empty path restores a silent source.
The loader accepts supported mono or stereo PCM16, PCM24, and float32 WAV files. Grain length, alternate interpolation, MIDI, modulation routing, and a full preset or sample-browser design remain later work. The linear interpolator's aliasing limitation also remains.
Build and try it
On macOS, open drizel.jucer in Projucer, save or regenerate the Xcode project, and build the Standalone, VST3, or AU target. The project includes the WAV adapter and core headers. Alternatively, with JUCE 8.0.15 available:
cmake -S . -B build-plugin \
-DDRIZEL_JUCE_PATH=../JUCE \
-DDRIZEL_BUILD_PLUGIN=ON \
-DCMAKE_BUILD_TYPE=Release
cmake --build build-plugin --parallel 2
ctest --test-dir build-plugin --output-on-failureThe CMake plugin build is opt-in; without the plugin flag, the default configuration builds the command-line experiments and tests. Plugin products are written under build-plugin/DrizelPlugin_artefacts/ and are not installed automatically.
Load a WAV, wait for the Ready status, then try moving Position, Pitch, and Density during playback. Use a source with audible material near its beginning, or move Position to a section that contains sound.
What has been verified
The recorded checks on October 22, 2026, include a Debug CMake build against JUCE 8.0.15 with all eight CTest entries passing. Processor and editor translation units also passed a strict GCC C++17 syntax check against the JUCE headers. The engine passed AddressSanitizer and UndefinedBehaviorSanitizer checks; leak detection was disabled in that environment.
An optimized engine run rendered 480,000 frames—10 seconds at 48 kHz and maximum density—in about 0.066 seconds on a shared Linux runner. That aggregate throughput number is not a worst-case callback timing measurement.
The automated tests cover sample-rate changes, irregular frame groups, smooth muting, sample replacement, obsolete packets, invalid controls, concurrent publication and reclamation, and guards against allocating or deleting on the simulated audio thread. They exercise the framework-independent callback path, not a physical audio device. A linked plugin and host have not been validated by the syntax check.
Before calling the real-time milestone complete, the remaining work includes worst-case callback timing at 64, 128, 256, and 512 samples on the target machine; extended listening; host save and reload; rapid file swaps; device changes; and checking for zipper noise. Hardware listening and deadline measurements still matter.
From a texture to an instrument
Step 6 brings the offline grain cloud to the point where it can respond to live controls. The callback renders prepared audio; the worker owns the expensive preparation and cleanup; and ownership handoffs keep borrowed sample data alive across the boundary.
The next milestone is not simply adding more controls. First, the engine needs listening and timing tests on the machine and hosts it is meant to serve. Real-time behavior is something to measure, not infer from a successful build.
Drizel is an open-source granular synthesis project: github.com/neuralmanacle/drizel.
Series note: blog Step 6 corresponds to Layer 5, the real-time engine, in the Drizel dependency roadmap. Promptable modulation is a later Layer 6 milestone.