grainloom

A small, dependency-light toolkit for granular, spectral and textural sound design in Python. Grainloom gives you grains, spectral freezing and morphing, texture/ambience generators, and a short chain of characterful effects — the building blocks for pads, drones, transitions and glitchy detail.

Built on nothing heavier than NumPy.

Install

pip install grainloom

Or from a checkout:

pip install -e .

Quick start

import grainloom as gl
from grainloom.effects import Reverb, Saturation

# a source to chew on
tone = gl.oscillators.saw(110.0, 2.0)

# scatter it into a shifting cloud of grains
cloud = gl.GranularCloud(tone, grain_ms=90, density=35, pitch_jitter=3.0, seed=1)
grains = cloud.render(6.0)

# push it through a couple of effects
chain = gl.EffectChain().add(Saturation(drive=2.0)).add(Reverb(room=0.8, mix=0.3))
out = chain.process(grains).normalized(0.9)

gl.write_wav("cloud.wav", out)

What's in the box

• Granular synthesis — Grain, GranularCloud, granulate, and granular_stretch for time-stretching without pitch change.
• Spectral tools — spectral_freeze, spectral_morph, spectral_blur, plus raw stft/istft.
• Textures — drone, ambience and shimmer generators for beds and pads.
• Effects — delay, Schroeder reverb, chorus, saturation, bit-crush, one-pole filter and tremolo, composable via EffectChain.
• Sources — sine/saw/square/triangle oscillators and white/pink/brown noise.
• I/O — read and write 16-bit WAV files with only the standard library.

Command line

grainloom granulate input.wav -o cloud.wav --density 40 --seconds 8
grainloom freeze input.wav -o drone.wav --at 0.4 --seconds 12
grainloom texture ambience -o bed.wav --seconds 20

Documentation

• Usage guide
• Architecture
• Design notes
• API reference

See examples/ for runnable scripts.

License

MIT — see LICENSE.

Status

Early but usable. The public API may still shift before 1.0 — see the changelog for what has changed, and CONTRIBUTING if you want to help shape it.