Logo
← Back

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:

  1. Reads the source at its current position, using interpolation when that position falls between stored samples.
  2. Multiplies the reading by its current window value.
  3. Applies gain and panning to produce left and right samples.
  4. 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:

QuestionTimelineExample
Where does the grain begin reading?Source recording500 ms into the input WAV
When does the grain begin playing?Output recording150 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 milliseconds

At an output sample rate of 48,000 frames per second:

interval in frames = 48,000 / 20
                   = 2,400 frames

With 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:

GrainStarts atFinishes atOverlaps with
A0 ms100 msB
B50 ms150 msA, then C
C100 ms200 msB, then D
D150 ms250 msC, 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 seconds

For 100 ms grains:

DensityNominal intervalApproximate average overlap
5 grains/second200 ms0.5 grains
20 grains/second50 ms2 grains
80 grains/second12.5 ms8 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:

GrainContribution
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

  1. Begin one output frame
  2. If a launch is due, look for a free pool slot
  3. Start a grain or drop the launch if the pool is full
  4. Advance the trigger countdown
  5. Read and sum the next frame from every grain
  6. 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 launches

The 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:

ParameterVariationWhat changes
Source positionUp to ±50 ms around the centreWhich part of the recording is read
PitchUp to ±3 semitonesHow quickly the grain moves through the source
Pan±0.75 around centreWhere the grain sits between left and right
Duration75, 100, or 125 msHow long the grain remains active
Launch interval±20% around the nominal intervalHow 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 grains

ceil 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.2

Windows 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.

PreparationPlayback
Validate settings and source valuesCheck whether a launch is due
Measure the source peakSelect per-grain variations
Build the three window tablesReuse an available grain slot
Calculate conservative gainAdvance and mix grain outputs
Initialize the random seedReturn 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:

  1. During the requested duration, call cloud.next() to schedule and mix.
  2. After that duration, call cloud.next(false) to mix without starting new grains.
  3. 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 frames

The added tail lets the final envelopes complete naturally.

14. What changed in the code

FileResponsibility
src/audio/GrainCloud.hSettings, preparation, fixed pool, scheduler, variations, and mixer
experiments/grain-cloud/main.cppLoad a WAV, render the cloud, finish its tail, and save a WAV
tests/GrainCloudTests.cppCheck timing, overlap sums, capacity, tails, repeatability, and gain bounds
CMakeLists.txtBuild the experiment and register its tests
docs/grain-cloud.mdExplain 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.

DensityStartedDroppedMaximum activeOutput peak
5 grains/s25010.353603
20 grains/s100030.0960431
80 grains/s3980110.0446149
1,000 grains/s3,1691,832640.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.

Source audio — input.wav
Sparse — 5 grains per second
Medium — 20 grains per second
Dense — 80 grains per second
Pool-limit demonstration — 1,000 grains per second

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-failure

This 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 42

After the output filename, the arguments are:

seconds   density   source_position_ms   seed
5         20        500                  42

Choose 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.

Video explanation

Command Palette

Search for a command to run...