# Granulator

> Replays windowed grains of the live input: up to 32 at once, scheduled from the node path, with freeze, reverse and pitch.

Source: https://docs.tune.toys/nodes/std.granulator/

Granulator chops the live input into short windowed grains and replays them from the recent past, turning any sound into clouds, stutters, shimmering textures or a frozen drone.

## What it does

The input is written into a circular buffer prepared for the largest admitted Position plus Spray plus the longest grain at its fastest read. New grains start at Density per second, or on a grid of Beats locked to the shared transport. Each grain reads Grain size of audio from Position behind the live input (plus a random Spray), transposed by Pitch and a random Pitch spray, backwards with the Reverse probability, and balanced across the channels by a random amount up to Width. A Hann window fades every grain in and out. Up to 32 grains sound at once; a grain that finds every voice busy is skipped. The sum is normalized by the energy of the windows that are sounding, so dense clouds keep a steady level.

Every random choice comes from a generator seeded by the node's path, so the same Toy sounds identical on every host and in offline renders. Freeze stops writing the buffer: grains keep replaying what it holds, even after the input falls silent.

## When to use it

Use it for ambient textures from any source, glitchy stutters on drums, octave shimmer, or a held freeze drone under a performance. For clean repeats use [Delay](https://docs.tune.toys/nodes/std.delay/); for a smooth wash use [Reverb](https://docs.tune.toys/nodes/std.reverb/).

## Ports

<!-- ports:start -->

| Port    | Direction | Signal | Lanes                   |
| ------- | --------- | ------ | ----------------------- |
| `audio` | Input     | Audio  | Inferred from the cable |
| `audio` | Output    | Audio  | Inferred from the cable |

<!-- ports:end -->

## Parameters

<!-- parameters:start -->

| Parameter     | Label       | Range      | Default | Unit  | Scale  | Notes                                                                                                                                 |
| ------------- | ----------- | ---------- | ------- | ----- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `size_ms`     | Grain size  | 10 to 1000 | 90      | ms    | log    | Length of each grain's Hann window, fixed when the grain starts.                                                                      |
| `density_hz`  | Density     | 0.5 to 200 | 16      | Hz    | log    | New grains per second when Beats is 0. A grain that finds all 32 voices busy is skipped.                                              |
| `position_ms` | Position    | 0 to 2000  | 120     | ms    | linear | How far behind the live input each grain starts reading. The buffer is sized for the largest admitted value.                          |
| `spray_ms`    | Spray       | 0 to 1000  | 40      | ms    | linear | Random extra distance back for each grain.                                                                                            |
| `pitch`       | Pitch       | -24 to 24  | 0       | st    | linear | Grain transposition in semitones.                                                                                                     |
| `pitch_spray` | Pitch spray | 0 to 24    | 0       | st    | linear | Random transposition of each grain up to this many semitones either way; the total stays within ±24.                                  |
| `reverse`     | Reverse     | 0 to 1     | 0       |       | linear | Probability that a grain plays backwards.                                                                                             |
| `width`       | Width       | 0 to 1     | 0.5     |       | linear | Random balance of each grain across the channels.                                                                                     |
| `freeze`      | Freeze      | 0 to 1     | 0       |       | linear | Stops writing the live buffer so grains keep replaying what it holds. A frozen buffer reports an infinite tail. Choices: 0 Off, 1 On. |
| `beats`       | Beats       | 0 to 16    | 0       | beats | linear | Beats between grains, phase-locked to the shared transport. 0 uses Density instead.                                                   |
| `mix`         | Mix         | 0 to 1     | 0.5     |       | linear | Dry/wet blend.                                                                                                                        |

<!-- parameters:end -->

### Grain size (`size_ms`)

The length of each grain's window, from 10 to 1000 ms. It is fixed when the grain starts. Short grains sound buzzy and rhythmic, long grains smooth and smeared.

### Density (`density_hz`)

New grains per second, from 0.5 to 200, when `beats` is 0. Density times Grain size is roughly how many grains overlap.

### Position (`position_ms`)

How far behind the live input each grain starts reading, from 0 to 2000 ms. Grains that play faster than the input start far enough back that they never catch up with it.

### Spray (`spray_ms`)

A random extra distance back for each grain, up to this many milliseconds, which scatters the cloud in time.

### Pitch (`pitch`)

Grain transposition in semitones, from -24 to 24.

### Pitch spray (`pitch_spray`)

A random transposition of each grain up to this many semitones either way. The total stays within ±24.

### Reverse (`reverse`)

The probability that a grain plays backwards, from 0 (never) to 1 (always).

### Width (`width`)

How far each grain is randomly balanced across the channels. At 0 every grain sits in the middle.

### Freeze (`freeze`)

Off or On. On stops writing the live buffer, so the grains keep replaying what it holds. A Toy that can freeze reports an infinite tail.

### Beats (`beats`)

Beats between grains, phase-locked to the shared transport: 0.25 starts a grain every sixteenth note. At 0 grains follow `density_hz`. While the transport is stopped, synced grains do not start.

### Mix (`mix`)

Dry and grain blend.

## Tips

- Raise Spray and Width with a long Grain size for a wide ambient cloud.
- Pitch 12 with a little Pitch spray gives an octave shimmer; add Reverse for a backwards bloom.
- Freeze a chord, then play over the top of the drone it leaves.
- Large Position, Spray and Grain size values make the prepared buffer larger: up to 8 seconds per channel.

## See also

[Delay](https://docs.tune.toys/nodes/std.delay/), [Reverb](https://docs.tune.toys/nodes/std.reverb/), [Chorus](https://docs.tune.toys/nodes/std.chorus/).