October 19, 2026
Step 5: From One Grain to a Texture
A simple guide to scheduling, overlapping, and mixing tiny pieces of sound.
In Step 4, I brought the earlier building blocks together into a single grain: a small piece of a recording, played through an amplitude window so its beginning and end fade smoothly.
That gave me one short sound. The next question is: what happens when another grain begins before the first one finishes?
This is where Step 5 begins. The implementation now schedules multiple grains, keeps track of the ones still playing, and mixes their outputs into a stereo texture. It also introduces controlled variation, so every grain does not have to start at the same position or play at the same pitch.
The aim of this step is an offline WAV render. Real-time plugin playback comes later.
1. What a grain already knows how to do
A grain is a small player with its own state. It knows where to read from the source, how quickly to move through it, how long to play, and how loud its output should be.
For each output frame, the player:
- Reads the source at its current position, using interpolation when that position falls between stored samples.
- Multiplies the reading by its current window value.
- Applies gain and panning to produce left and right samples.
- Advances its source position and window age.
The source position tells us where we are reading from the recording. The window age tells us how far this grain has progressed through its own lifetime.
These are different things. A grain can move through the source twice as quickly while keeping the same 100 ms envelope. Step 5 reuses this player. The new work is deciding when to start players and how to combine their output.
2. Two timelines: where a grain reads and when it plays
This distinction helped me understand the scheduler:
| Question | Timeline | Example |
|---|---|---|
| Where does the grain begin reading? | Source recording | 500 ms into the input WAV |
| When does the grain begin playing? | Output recording | 150 ms into the generated texture |
A grain launched at output time 150 ms might read from source time 500 ms. The next grain might begin at output time 200 ms and read from source time 530 ms.
The output moves forward one frame at a time. The starting positions chosen within the source can move around independently. In this version, grains are chosen around a fixed source position. There is no automatic scan through the whole recording yet.
3. Density: how often a grain begins
Density means the number of grains we aim to launch per second. If the density is 20 grains per second, the nominal time between launches is:
interval = 1 / density
= 1 / 20 seconds
= 0.05 seconds
= 50 millisecondsAt an output sample rate of 48,000 frames per second:
interval in frames = 48,000 / 20
= 2,400 framesWith timing variation disabled, the scheduler therefore begins a grain every 2,400 output frames. Density describes starts, not the number of grains currently playing. A grain may finish before the next begins, or several may stay active together. That depends on duration.
4. Duration and density create overlap together
Suppose every grain lasts 100 ms and a new grain begins every 50 ms. Their lifetimes look like this:
| Grain | Starts at | Finishes at | Overlaps with |
|---|---|---|---|
| A | 0 ms | 100 ms | B |
| B | 50 ms | 150 ms | A, then C |
| C | 100 ms | 200 ms | B, then D |
| D | 150 ms | 250 ms | C, then the next grain |
At 75 ms, grain A is 75 ms into its life and grain B is 25 ms into its life. Both contribute to the same output frame. A useful estimate is:
average active grains ≈ density × grain duration in secondsFor 100 ms grains:
| Density | Nominal interval | Approximate average overlap |
|---|---|---|
| 5 grains/second | 200 ms | 0.5 grains |
| 20 grains/second | 50 ms | 2 grains |
| 80 grains/second | 12.5 ms | 8 grains |
An average of 0.5 does not mean half a grain is playing. It means that, over time, the system spends part of its time with a grain active and part with none.
These estimates describe steady operation without dropped events. Random lengths, timing variation, startup, and shutdown affect the moment-to-moment count. Low density can leave gaps between sounds. Increasing density gives grains more opportunities to overlap and form a sustained texture. The exact result still depends on the source and the grain settings.
5. Overlap-add: adding sounds at the same moment
The mixer has a straightforward job: ask each grain for its next frame and add the results. For one output channel:
output[n] = grainA[n] + grainB[n] + grainC[n] + ...Here, n is the current output-frame index. Each contribution already includes that grain's interpolation, window, gain, and pan. For example, imagine these left-channel contributions at one instant:
| Grain | Contribution |
|---|---|
| A | +0.20 |
| B | +0.15 |
| C | −0.10 |
| Mixed output | +0.25 |
Audio samples are signed amplitudes. Positive and negative contributions can partly cancel, while contributions with the same sign can reinforce each other. Overlap therefore does not guarantee that every output sample becomes larger. The right channel is summed separately.
This is overlap-add: grains overlap in time, and their amplitudes are added at each output frame.
The windows still matter. Each grain fades in and out instead of appearing at full amplitude and stopping abruptly. However, arbitrary grain positions, lengths, and launch times do not produce a guaranteed flat sum. Smooth individual envelopes and constant overall loudness are separate concerns.
6. One call produces one stereo frame
The cloud's main operation is:
const auto frame = cloud.next();auto lets C++ infer the returned type. frame contains two values: frame.left and frame.right. One call advances the whole cloud by one output frame. It does not return a complete grain or a complete audio block. At 48 kHz, 48,000 calls produce one second of stereo output. An individual grain also advances by one frame whenever the cloud asks it for its next contribution.
The work inside a cloud tick follows this flow:
One output frame through the grain cloud
- Begin one output frame
- If a launch is due, look for a free pool slot
- Start a grain or drop the launch if the pool is full
- Advance the trigger countdown
- Read and sum the next frame from every grain
- Return the left and right samples
Inactive grains return silence, so the mixer can visit the same fixed collection every time.
7. Scheduling without accumulating timing errors
Some launch intervals fit neatly into whole output frames. Others do not. At 48 kHz, a density of 7 grains per second gives:
48,000 / 7 ≈ 6,857.142857 frames between launchesThe engine cannot begin a grain partway between output frames. But rounding every interval to 6,857 would repeatedly discard the fractional remainder.
Instead, the scheduler keeps a floating-point countdown. Each output frame reduces it by one. When a launch is due, the scheduler adds the next interval to the existing countdown, preserving the small remainder.
This spreads the necessary whole-frame timing adjustments over time. An event lands on an available output frame while the long-term spacing stays close to the requested density.
The first grain is scheduled at frame zero. With a practical Hann window, its initial amplitude is zero: launching a grain and immediately producing a nonzero sample are not the same event.
8. The grain pool: reuse a fixed number of players
Drizel uses a pool of 64 grain slots by default. A slot holds playback state: source pointers, read position, remaining duration, window age, and gain information. It does not contain a separate copy of the source recording. When a grain finishes, its slot becomes available for another launch.
The C++ storage is:
std::array<Grain, Capacity> grains_ {};std::array holds a fixed number of objects. Grain is the object type, and Capacity is the number of slots chosen at compile time. The braces initialize the collection with inactive grains.
This makes the maximum voice count explicit. It also avoids creating and destroying heap-allocated grain objects during rendering.
If all slots are occupied, the current policy is drop new: skip the incoming grain and let the existing ones finish their envelopes.
There is a musical trade-off. At very high requested densities, fewer grains will actually start. But the engine keeps its capacity limit and avoids abruptly cutting an existing grain to make room. The renderer reports accepted launches, dropped launches, and the highest active count, so this behavior is visible.
9. Variation: making successive grains different
Scheduling identical grains at a perfectly regular interval creates a repeating pattern. Step 5 adds several ways for neighboring grains to differ. The command-line experiment uses these settings:
| Parameter | Variation | What changes |
|---|---|---|
| Source position | Up to ±50 ms around the centre | Which part of the recording is read |
| Pitch | Up to ±3 semitones | How quickly the grain moves through the source |
| Pan | ±0.75 around centre | Where the grain sits between left and right |
| Duration | 75, 100, or 125 ms | How long the grain remains active |
| Launch interval | ±20% around the nominal interval | How regularly grains begin |
Starting positions and pan values are clamped to their permitted ranges. Once a grain starts, reads beyond the source boundary follow the existing zero-padding policy.
Timing jitter
If the nominal interval is 50 ms, ±20% jitter gives intervals from approximately 40 to 60 ms before output-frame quantization. This changes when grains begin; it does not alter the audio sample rate.
Density remains a nominal control: a finite randomized render can contain slightly more or fewer launches than density multiplied by duration.
Length variation without new allocations
A longer grain needs a longer envelope. Building that envelope at launch time would allocate memory and calculate its window values during playback.
Instead, preparation creates three Hann tables: short, centre, and long. Each grain borrows one of them. The current length variation is deliberately discrete. It chooses from three prepared durations, rather than every possible duration in a range.
Random choices happen at launch
A grain receives its position, pitch, pan, and length when it starts. Those choices stay fixed during that grain's lifetime. This is per-grain variation. Continuously moving a parameter while a grain plays would be an additional modulation feature.
10. A seed makes randomness repeatable
The generator uses a seed to initialize its sequence of random values. With the same input, settings, seed, and build, the renderer makes the same choices and produces the same output. That is useful when comparing changes: a difference in the sound can be traced to the setting or code being changed, rather than a completely different random sequence.
Changing the seed produces another arrangement of variations. The tests check both behaviors: exact replay with the same seed, and different output with another seed. Exact bit-for-bit equality across different platforms is not promised because mathematical functions can round differently.
11. More grains require a gain policy
When several grains reinforce one another, their sum can become large. The mixer therefore needs a deliberate gain policy.
This implementation calculates a conservative gain during preparation using the longest possible grain, the shortest possible launch interval, the pool capacity, the source's measured peak amplitude, and the selected interpolation method. The first three estimate an upper bound on simultaneous grains.
For the default 20-grain-per-second experiment:
nominal interval = 50 ms
shortest interval with 20% jitter = 40 ms
longest grain = 125 ms
estimated maximum overlap = ceil(125 / 40)
= 4 grainsceil means round upward. Although the nominal average overlap is around two, the conservative bound allows for four. With a master gain of 0.8, linear interpolation, and a source peak no higher than 1:
per-grain gain = 0.8 / 4
= 0.2Windows and panning can reduce the actual output further. Hermite interpolation receives additional headroom because its curve can overshoot the stored sample values. Source peaks above 1 also reduce the prepared gain.
The gain stays fixed throughout the render. Dividing by the current active count could change the level of already-playing grains whenever another grain starts or finishes—even when the new grain's window is still at zero.
This policy favors predictable peak headroom. It does not guarantee equal perceived loudness between densities, and a dense render may sound quieter. It is also not a limiter: no separate stage reacts to output peaks during playback.
12. Preparation and playback have different jobs
The implementation separates work that happens once from work repeated for every frame.
| Preparation | Playback |
|---|---|
| Validate settings and source values | Check whether a launch is due |
| Measure the source peak | Select per-grain variations |
| Build the three window tables | Reuse an available grain slot |
| Calculate conservative gain | Advance and mix grain outputs |
| Initialize the random seed | Return one stereo frame |
File loading, output-buffer allocation, and WAV writing belong to the surrounding offline experiment. The rendering path has no heap allocation, file I/O, locks, or logging. Source audio and prepared windows must stay alive and unchanged while the grains borrow them.
These are useful foundations for later real-time work. They do not prove that the current implementation meets an audio callback deadline on a target machine. That still needs measurement and integration testing.
13. Let the final grains finish
Stopping new launches should not instantly silence grains that are still playing. The experiment handles these as separate events:
- During the requested duration, call
cloud.next()to schedule and mix. - After that duration, call
cloud.next(false)to mix without starting new grains. - Continue long enough for the longest possible grain to finish.
With the experiment's 125 ms maximum grain length, a five-second request writes 5.125 seconds of audio. At 48 kHz, that is:
5.125 × 48,000 = 246,000 stereo framesThe added tail lets the final envelopes complete naturally.
14. What changed in the code
| File | Responsibility |
|---|---|
src/audio/GrainCloud.h | Settings, preparation, fixed pool, scheduler, variations, and mixer |
experiments/grain-cloud/main.cpp | Load a WAV, render the cloud, finish its tail, and save a WAV |
tests/GrainCloudTests.cpp | Check timing, overlap sums, capacity, tails, repeatability, and gain bounds |
CMakeLists.txt | Build the experiment and register its tests |
docs/grain-cloud.md | Explain contracts, formulas, commands, and limitations |
The existing Grain player remains the unit doing sample reading and windowing. The cloud coordinates many instances of it.
15. What has been checked
The prepared implementation passed all seven CTest targets in a Linux Release build using GCC 13.3 and JUCE 8.0.15. The new core tests also passed AddressSanitizer and UndefinedBehaviorSanitizer checks, with leak detection disabled in that execution environment.
The checks include:
- Comparing mixed output against an explicit sum of overlapping Hann windows.
- Checking integer and fractional trigger intervals.
- Forcing pool overflow and verifying the drop-new counts.
- Stopping launches and confirming that the remaining grains drain to silence.
- Replaying the same seed exactly.
- Checking output peak bounds with randomized settings and Hermite interpolation.
I rendered the examples from the project's input.wav using the drizel_grain_cloud executable. The source is 48 kHz stereo. Each render uses a 500 ms source centre, seed 42, and five seconds of triggering followed by the 125 ms grain tail. The output is 48 kHz stereo float WAV.
| Density | Started | Dropped | Maximum active | Output peak |
|---|---|---|---|---|
| 5 grains/s | 25 | 0 | 1 | 0.353603 |
| 20 grains/s | 100 | 0 | 3 | 0.0960431 |
| 80 grains/s | 398 | 0 | 11 | 0.0446149 |
| 1,000 grains/s | 3,169 | 1,832 | 64 | 0.0196274 |
Each render used five seconds of triggering plus the tail. The outputs had the expected frame count, finite samples, bounded peaks, and silent endpoints. The highest-density run demonstrates the pool policy: active grains stop at 64 even when the scheduler requests more.
These examples use input.wav as the source, so the sound and source material are the same as in the command-line experiment. Listening on the target Mac and measuring worst-case real-time performance remain open.
16. A small listening experiment
After applying Step 5, build and run the tests:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build --output-on-failureThis uses the project's existing JUCE setup. A fresh build may also need -DDRIZEL_JUCE_PATH=/path/to/JUCE.
Then render three densities from the same input:
./build/drizel_grain_cloud input.wav sparse.wav 5 5 500 42
./build/drizel_grain_cloud input.wav medium.wav 5 20 500 42
./build/drizel_grain_cloud input.wav dense.wav 5 80 500 42After the output filename, the arguments are:
seconds density source_position_ms seed
5 20 500 42Choose a source position inside your recording. The example uses 500 ms; use an earlier position for a short file. Each output filename must be new.
Listen for how clearly individual grains stand out, when the sound becomes more continuous, how the stereo placement changes, and how the final grains fade away. Compare loudness separately from texture because the conservative gain changes with the overlap bound.
Repeating the same command with a new output filename should reproduce the same result. Changing the seed should produce a different arrangement.
What this step adds to Drizel
Drizel can now coordinate many small players into one offline stereo render. Each grain still reads, interpolates, windows, and advances independently. The scheduler gives it a starting time, the pool gives it a reusable slot, and the mixer gives it a place in the combined output.
There is more to do: listen on the target machine, profile the busiest cases, and eventually bring the engine into the plugin's audio callback with suitable controls and smoothing.
For this step, the central connection is now in place: a texture emerges from many short sounds sharing an output timeline.
Drizel is an open-source granular synthesis project: github.com/neuralmanacle/drizel.
Series note: blog Step 5 corresponds to Layer 4, “Many grains,” in the dependency roadmap. Layer 5 of that roadmap is the later real-time engine milestone.