Sound to Grain — User Guide

Extracts fixed-length grains from random source positions, optionally reverses them, and concatenates them into mono or stereo outputs with several left/right independence strategies.

Author: Shai Cohen Affiliation: Department of Music, Bar-Ilan University, Israel Version: 2.3 (2026) License: MIT License Repo: GitHub

What this does

Sound to Grain creates a new sequence from one selected Sound. The left-side grain positions are chosen randomly from the legal source range. Depending on the output mode, the right channel can use the same source positions, independent random positions, the same grains in a shuffled order, or a time-offset version of the left positions.

source → random grain positions → Praat extraction window → optional per-grain reversal → L/R ordering according to output mode → sequential concatenation → mono or stereo result → target peak 0.95

Grains are concatenated one after another. There is no overlap-add, density scheduling, automatic crossfade, or silence inserted between grains.

Quick start

Select exactly one Sound object.
Run Sound_to_Grain.praat.
Choose Custom or one of the six named presets.
Set the number and length of grains.
Choose Hanning, Rectangular, or Triangular extraction.
Choose one of the five output modes.
Optionally enable probabilistic grain reversal.
Run the script. The result is named <source>_grains_<preset>.

Play_result controls final playback. Draw_visualization controls the Picture output. Individual grains are not previewed during extraction.

Output modes

Mode	Left channel	Right channel
Mono	Random grain positions.	No right channel.
Stereo — same grains L/R	Random positions.	Same source positions and same reversal decisions as L, using source channel 2 when available.
Stereo — independent random positions	Random positions.	Independent random source positions and independent reversal decisions.
Stereo — independent shuffled order	Randomly extracted grains, concatenated in extraction order.	Grains extracted at the same source positions as L but concatenated in an independent Fisher–Yates permutation; reversal decisions are independent.
Stereo — independent time offset	Random positions.	Each L source position plus `Time_offset_s`, wrapped into the legal source-start range; reversal decisions are independent.

Random source positions

maxStart = sourceDuration - Grain_length_s if maxStart > 0: start ~ Uniform(0, maxStart) else: start = 0

A grain can therefore begin anywhere that allows the complete requested grain to fit inside the source. Repeated or nearly repeated source positions are possible.

Input-channel behavior

The script works through private zero-based source copies, so a Sound whose time domain does not begin at 0 is handled without changing the original object.

Input	Mono output	Stereo output modes
Mono	Mono source used directly.	The mono source supplies both L and R.
Stereo	Converted to mono before grain extraction.	Channel 1 supplies L; channel 2 supplies R.
3+ channels	Converted to mono.	Only channels 1 and 2 are used; channels 3+ are not included.

In Stereo — same grains L/R, “same grains” means the same temporal source positions and reversal pattern. With stereo input, L and R still contain their corresponding original source channels rather than duplicate mono audio.

Grain extraction windows

Each grain is created with Praat Extract part using the selected window shape and relative width 1.

Window_type	Behavior
Hanning	Praat Hanning-window extraction over the grain.
Rectangular	Untapered rectangular extraction.
Triangular	Praat triangular-window extraction.

These are per-grain extraction windows. They do not create overlap or crossfades between adjacent grains in the final sequence.

Probabilistic reversal

When Enable_reversal is active, each eligible grain receives a random integer draw from 1 to 100. The grain is reversed when that draw is less than or equal to the corresponding reversal-percent value.

Left channel

Every L grain uses Left_reversal_percent.

Right channel

Same L/R: R copies the actual L reversal decision.
Random / Shuffle / Offset: R receives an independent draw using Right_reversal_percent.

The percentages are target probabilities, not exact quotas. The actual number reversed in one run can differ. Values are not explicitly clamped to 0–100 by the script.

Stereo Shuffle

In shuffle mode, the right-channel order is generated with an ascending Fisher–Yates permutation:

order = [1, 2, ..., N] for i = 1 ... N-1: j = randomInteger(i, N) swap(order[i], order[j])

The right-channel accumulator is then built explicitly in that stored order. The left channel remains in ordinary extraction order.

The grain map also follows the actual shuffled R order, including the reversal state belonging to the grain that occupies each output position.

Time-offset mode

For every L source start, the R start is initially:

rightStart = leftStart + Time_offset_s

If the result exceeds the legal source-start interval, it wraps:

rightStart = rightStart - floor(rightStart / maxStart) × maxStart

If Grain_length_s == sourceDuration, then maxStart = 0 and the only legal source position for both channels is 0.

The offset is a source-read offset, not a delay between output channels. L and R grains are still concatenated in corresponding output slots.

Presets

Preset	Grains	Length	Window	Mode	Reversal
Quick Texture	15	200 ms	Hanning	Mono	Off
Dense Cloud	50	150 ms	Hanning	Mono	On, L/R targets 30/30%
Micro Grains	80	50 ms	Rectangular	Mono	Off
Long Segments	10	800 ms	Hanning	Mono	Off
Stereo Scatter	25	250 ms	Hanning	Independent random positions	On, L/R targets 40/60%
Stereo Shuffle	30	200 ms	Hanning	Independent shuffled order	On, L/R targets 30/70%

Named presets overwrite grain count, grain length, window, output mode and reversal settings shown above. They do not change Time_offset_s, Draw_visualization, or Play_result.

Parameters & effective limits

Parameter	Default	Exact role
Preset	Custom	Custom plus six named configurations.
Number_of_grains	20	Internally replaced by `floor(value)`; resulting value must be at least 1.
Grain_length_s	0.3 s	Positive; may equal but may not exceed the source duration.
Window_type	Hanning	Hanning, Rectangular, or Triangular extraction.
Output_mode	Mono	One of the five channel/independence strategies described above.
Time_offset_s	0.1 s	Positive source-read offset used only by mode 5.
Enable_reversal	Off	Enable probabilistic per-grain reversal.
Left_reversal_percent	50	Threshold used for L reversal draws.
Right_reversal_percent	50	Threshold used for independent R reversal draws where applicable.
Draw_visualization	On	Draw extraction map, report, waveform comparisons and summary.
Play_result	On	Play the final result.

Concatenation, duration & level

Assembly

The left output is assembled by concatenating L grains in extraction order. Stereo modes build a corresponding R sequence; only Shuffle changes its order.

There is no intentional overlap between successive grains.

Duration

nominal output duration = floor(Number_of_grains) × Grain_length_s

The script measures the actual concatenated duration and reports it in the Info window and visualization.

Final level

After assembly, every non-silent result receives:

Scale peak: 0.95

This is target peak normalization. A quiet non-zero result can be amplified to the 0.95 sample-peak target.

Visualization

The v2.3 Picture view contains:

Grain extraction map: source position on the x-axis and grain/output index vertically. Stereo modes show L above R.
Parameter report: grain count/length/window, output mode, reversal counts and final output statistics.
Zoom overlay: first up-to-500 ms of original and result on one shared local amplitude scale.
Full waveform comparison: original and result on one shared global amplitude scale.
Summary bar: preset, mode, grain settings, input/output duration and measured output peak.

Grain-map colors

Color indicates reversal status, not frequency, amplitude, or source identity. In stereo mode L and R use separate base colors so the two channel rows remain distinguishable.

Shuffle map

For Stereo Shuffle, the lower R map is drawn in the actual output permutation. Its source-position bar and reversal color follow the grain that really occupies that R output slot.

Waveform comparison

Both waveform panels use mono display copies when the audio is stereo. They therefore compare overall waveform shape/level, while the grain map carries the L/R structural information.

The original and result share the same y-axis scale in the full comparison. The zoom panel also shares one scale between the two signals, calculated specifically for the displayed first 500 ms or less.

Output behavior

Name: <source>_grains_<presetName>.
Sample rate: unchanged from the source.
Mono mode: mono result.
Stereo modes: two-channel result.
Original Sound: unchanged.
Random seed: no user control; random grain positions, reversal draws and shuffle permutation can vary between runs.
Final peak: normalized to 0.95 when non-silent.

The Info window reports the source, preset, grain settings, output mode, requested reversal percentages, extraction progress, actual reversal counts, result name and measured duration.