Sound Atom Composer — User Guide

Offline analysis → dictionary → selection/transform → resynthesis: extracts parametric "atoms" (pitched micro‑events) from a corpus, builds a dictionary, then recomposes a new stereo texture via additive resynthesis.

Author: Shai Cohen Affiliation: Department of Music, Bar-Ilan University, Israel Version: 1.0 (2025) License: MIT License Repo: https://github.com/ShaiCohen-ops/Praat-plugin_AudioTools

Contents:

What this does Quick start Granular Concepts Presets & Parameters Processing Workflow Applications Troubleshooting

What this does

This script implements an analysis–dictionary–resynthesis workflow: it scans a folder of sounds, extracts small pitched micro‑events ("atoms") using pitch (f0) and intensity (energy), stores them in a dictionary, then recombines them into new textures via additive (sine) resynthesis. Instead of replaying source grains, it recomposes a spectral sketch of the corpus using learned pitch/energy behaviors.

Key Features:

Corpus analysis – Scans real recordings to find salient pitched moments (f0 + energy)
Dictionary-based selection – Filters atoms by frequency band, energy threshold, and count
3 built‑in presets – Time stretch, pitch‑shifted cloud, shuffle texture
Full parameter control – Fine‑tune analysis, selection, and synthesis
Stereo spatialization – Random panning and time‑jitter for width
Windowed additive atoms – Smooth fade‑in/out for each resynthesized sine atom

What are sound atoms? Atoms are parametric micro‑events detected at salient moments (high energy + defined pitch). Each atom stores descriptors—time, duration, frequency (f0), and amplitude (energy)—and is later rendered as a windowed sine component. By selecting, transforming, and recombining hundreds of atoms, new textures emerge that keep a spectral/behavioral connection to the corpus (without replaying the original samples).

Technical Implementation: (1) Corpus ingestion: Loads multiple WAV files for analysis (each processed independently). (2) Atom detection: Computes pitch (f0) and intensity (energy) and stores salient frames as atoms. (3) Atom dictionary: A table of descriptors (file, time, duration, frequency, amplitude). (4) Selection & transformation: Filter by frequency band, cap by max_atoms, optionally transpose and shuffle. (5) Resynthesis: Render each atom as a windowed sine into stereo buffers with random pan and slight timing jitter. (6) Output: Normalize and play the recomposed stereo texture.

Quick start

Prepare a folder with WAV files as source material (voice, instruments, field recordings).
In Praat, run the script: Run script… → Sound_atom_composer.praat.
Choose a Preset style or select "Custom" to adjust all parameters manually.
When prompted, select the folder containing your WAV files.
The script will analyze the audio, extract atoms, and synthesize a new granular texture.
The output appears as Sound Granular_Output (stereo).

Quick tip: Start with the Glitch Cloud preset for immediate, interesting results. Use 3‑10 short WAV files (2‑5 seconds each) of harmonically rich material (voice, strings, winds). The output will be a 10‑second stereo texture. Enable Randomize order for maximum variety. For subtle time‑stretching without pitch change, use the Time Stretch preset.

Important: This is a descriptor‑based resynthesis process — the quality of results depends on clear pitched material in your source audio. Noisy, unpitched, or very short (<1 s) files may yield fewer usable atoms. Large numbers of atoms (>500) increase processing time. The script creates a temporary concatenated file in memory — very long source banks (>60 s) may require significant RAM. Always check the Info window for atom count and progress.

Atom Dictionary Concepts

Atom Detection Criteria

An atom (pitched micro‑event) is stored if ALL conditions are met: 1. ENERGY: intensity(t) > min_energy (default 30 dB) 2. PITCH: min_freq ≤ f0(t) ≤ max_freq (default 50–4000 Hz) 3. DURATION: fixed step size (time_step, default 0.05 s) This ensures atoms are extracted from acoustically salient, pitched moments of the source audio.

Atom Properties

Each stored atom has: • time: source position (seconds) • duration: grain length = time_step × atom_duration_multiplier • frequency: detected pitch (Hz) • amplitude: intensity value (dB) During synthesis, these control: • Playback rate: based on transpose_semitones • Grain window: Gaussian envelope centered on grain • Spatial position: random pan (L/R balance) and jitter

Resynthesis Engine (Additive)

For each atom i (1…numAtoms): source_time = atom.time dest_time = (i-1) × (output_duration / numAtoms) + jitter play_rate = 2^(transpose_semitones / 12) effective_duration = atom.duration / play_rate # Additive atom (windowed sine): atom(t) = sin(2π × frequency × (t - start)) # Window (Hanning/Gaussian‑style smoothing): window(t) = exp(-0.5 × ((t - center) / width)^2) where width = effective_duration / 4 # Final grain: output_grain(t) = grain_sample(t) × window(t) × gain × amplitude_scale

Processing Pipeline (analysis → dictionary → transform → resynthesis)

1. CORPUS INGESTION
• Select folder of WAV files
• Iterate through files (each analyzed independently)
• No concatenated source bank required for resynthesis
2. ATOM ANALYSIS
• Compute Intensity (energy)
• Compute Pitch (f0)
• Scan time steps
• Store qualifying moments in Atom Dictionary
3. ATOM SELECTION & ORDERING
• Limit to max_atoms
• Randomize order if enabled
4. RESYNTHESIS
• Create empty stereo buffers
• For each atom:
– Calculate destination time
– Apply pitch transposition
• Render windowed sine atom
• Apply smoothing window
• Spatialize with random pan/jitter
• Mix into buffers
5. FINALIZATION
• Combine L/R to stereo
• Normalize peak
• Cleanup temporary objects
• Play result

Presets & Parameters

Built‑in Presets

Preset	Description	Key Settings
Deep Drone (Low freq, dense, slow)	Dense low‑frequency atoms, slower pacing, good for drones and weighty beds	• max_atoms: 1500 • transpose: −12 semitones • output: 15 s • duration_mult: 2.0
Glitch Cloud (High freq, random, fast)	High‑frequency, shuffled atoms with aggressive transposition for glitchy clouds	• max_atoms: 800 • transpose: +24 semitones • randomize: yes • output: 5 s
Crystalline (Mid‑High, sparse, transposed)	Sparser mid‑high selection with upward transposition for bright, crystalline strands	• max_atoms: 100 • transpose: +12 semitones • randomize: no • duration_mult: 1.5

Custom Parameters

Parameter	Default	Range	Description
Analysis
Time_step	0.05	0.01–0.2	Time between analysis points (seconds)
Min_energy	30	0–100	Minimum intensity (dB) for atom selection
Selection
Min_freq	50	20–1000	Minimum pitch for atom selection (Hz)
Max_freq	4000	200–5000	Maximum pitch for atom selection (Hz)
Max_atoms	400	10–2000	Maximum number of atoms to use
Transformation
Transpose_semitones	0	-24 to +24	Pitch transposition in semitones
Randomize_order	✓	on/off	Randomize atom playback order
Synthesis
Output_duration	10.0	1–60	Duration of output texture (seconds)
Atom_duration_multiplier	1.5	0.5–3.0	Multiply atom duration (longer = more overlap)
Amplitude_scale	1.0	0.1–2.0	Overall output volume scaling

Parameter interactions:

Time_step × Max_atoms: Smaller time_step = more potential atoms, but too many may cause dense, muddy output.
Atom_duration_multiplier: Values >1.0 create overlapping grains (smoother texture). Values <1.0 create gaps between grains (stuttered effect).
Transpose_semitones: Positive values = higher pitch, faster playback. Negative values = lower pitch, slower playback. 0 = original pitch.
Min_energy: Higher values select only loudest moments; lower values include quieter material.

Processing Workflow

Step 1: Source Preparation

Input requirements: • Folder containing WAV files (any sample rate, will be resampled to 44100 Hz)
• Recommended: 3‑10 files, 2‑10 seconds each
• Harmonically rich material works best (voice, instruments)
• Avoid files with long silences at beginning/end
What happens: • All files are loaded into Praat
• Each file is analyzed independently; atoms store a file reference + time
• Files are unloaded after analysis to keep memory use low
• This treats the folder as a single corpus (a shared atom pool)

Step 2: Atom Analysis

Analysis process: • Intensity (energy) contour computed
• Pitch contour computed (75–600 Hz range)
• System scans at time_step intervals
• At each point checks: energy > min_energy AND pitch within min_freq‑max_freq
• Qualifying points become "atoms"
Output: Atom Dictionary table with columns: • time (source position)
• duration (time_step × multiplier)
• frequency (detected pitch)
• amplitude (energy value)

Step 3: Atom Selection & Ordering

Selection: • If more atoms than max_atoms, truncate to max_atoms
• Atoms are taken in analysis order (or random if enabled)
Randomization: • When Randomize_order = 1, atom sequence is shuffled
• Creates non‑chronological texture
• Maintains atom properties (pitch, duration)

Step 4: Granular Synthesis

Synthesis engine: • Creates two mono buffers (L and R)
• For each atom:
1. Calculate destination time in output
2. Add random jitter (±10 ms) to R channel
3. Compute playback rate from transpose_semitones
4. Render a sine component from each atom’s frequency and amplitude
5. Apply Gaussian envelope (smooth fade in/out)
6. Apply random pan (L/R balance)
7. Mix into buffers
Spatialization: • Random pan per atom (some left, some right)
• Time jitter on right channel (∼10 ms delay)
• Creates stereo width and movement

Step 5: Finalization

Final steps: • Combine L and R buffers to stereo sound
• Normalize peak to 0.99 (prevent clipping)
• Remove temporary objects (SourceBank, buffers, tables)
• Rename output to "composed_stereo_smooth"
• Auto‑play if enabled
Output characteristics: • Duration: exactly output_duration seconds
• Format: stereo, 44100 Hz
• Content: granular texture based on source atoms

Applications

Sound Design & Textural Creation

Use case: Generating evolving pads, atmospheres, and backgrounds from source recordings.

Technique: Use vocal/instrument snippets with Time Stretch preset.

Example: Extract atoms from vocal phrases, apply +7 semitone transposition, randomize order, create ethereal vocal pad.

Audio Time‑Stretching with Texture

Use case: Slowing down audio while maintaining pitch, but adding granular character.

Technique: Time Stretch preset with atom_duration_multiplier = 2.0.

Result: 2× slower version with overlapping grain texture, not just time‑expansion.

Source Deconstruction & Recomposition

Use case: Taking familiar sounds and rearranging them into new musical material.

Workflow:

Record short musical phrases (piano, guitar, voice)
Process with Shuffle Texture preset
Result maintains harmonic content but in randomized order
Use as background texture or compositional starting point

Experimental Vocal Processing

Use case: Transforming speech or singing into granular clouds.

Technique: Use spoken word recordings with Pitch Shifted Cloud preset.

Example: Speech atoms pitched up +12 semitones, dense overlapping = "angelic" vocal texture.

Practical Workflow Examples

🎵 Ambient Pad from Piano Samples

Goal: Create evolving ambient texture from piano notes.

Settings:

Source: 5–10 piano notes/chords (WAV)
Preset: Custom
Time_step: 0.03
Max_atoms: 800
Transpose: -5 semitones
Randomize: Yes
Output_duration: 15.0
Duration_multiplier: 1.8

Result: Slow, evolving piano pad with subtle pitch shift and granular movement.

🗣️ Vocal Granular Cloud

Goal: Transform spoken word into ethereal texture.

Settings:

Source: Short spoken phrases (3–5 seconds each)
Preset: Pitch Shifted Cloud
Modify: Transpose = +7 (not +12)
Max_atoms: 500
Amplitude_scale: 1.2

Result: Bright, shimmering texture with recognizable vocal character but unintelligible words.

⏳ Time‑Stretched Field Recording

Goal: Slow down environmental sound while adding texture.

Settings:

Source: 10‑second field recording (rain, traffic, nature)
Preset: Time Stretch
Modify: Output_duration = 30.0 (3× stretch)
Min_energy: 20 (include quieter moments)
Randomize: No (preserve some chronology)

Result: Slowed environmental texture with granular overlaps, ideal for background ambiance.

Troubleshooting

Problem: "No WAV files found"
Cause: Folder doesn't contain .wav files (case sensitive).
Solution: Ensure files have .wav extension (not .WAV, .Wav). Check folder path.

Problem: Very few atoms detected (< 20)
Cause: Source material doesn't meet criteria (too quiet, unpitched).
Solution: Lower min_energy (try 10), widen frequency range (min_freq=20, max_freq=5000), use more pitched source material.

Problem: Output is mostly silence
Cause: Amplitude_scale too low, or atoms very quiet.
Solution: Increase Amplitude_scale (1.5–2.0), check atom amplitude values in Atom Dictionary table.

Problem: Processing very slow
Cause: Too many atoms (max_atoms > 1000) or long source files.
Solution: Reduce max_atoms (≤500), use shorter source files, increase time_step (0.1).

Problem: "Formula error" during synthesis
Cause: Praat version compatibility or corrupted source files.
Solution: Ensure Praat ≥6.3, check that WAV files play normally in Praat, try different source files.

Optimization Tips

For best results:

Source files: 44.1 kHz, 16‑bit WAV, 2‑10 seconds each, normalized to -3 dB peak.
Atom count: 200–600 atoms gives good density without excessive processing.
Memory: Total source duration < 60 seconds for reasonable memory use.
Real‑time preview: Start with short output_duration (5 s) to test settings.
Parameter exploration: Change one parameter at a time, note the effect.