Granular Navigation Engine — v1.3 User Guide
Navigate through grains from multiple audio files using an autoencoder‑trained latent space. The Python engine scans a folder, extracts spectral features (batch‑FFT), trains a compact autoencoder, builds a transition score matrix, and generates a path through the grain collection according to a chosen navigation mode. Praat reconstructs the final audio from the original sources.
What this does
Granular Navigation Engine treats a folder of sound files as a corpus of grains. All processing – scanning, grain slicing, feature extraction, autoencoder training, and path generation – is handled by a Python script. Praat’s role is limited to folder selection, reading the resulting path CSV, and reconstructing the audio by concatenating grains with crossfade. This clean separation keeps Praat fast and gives Python full control over the neural architecture.
Quick start
- Place a folder of audio files (.wav, .aif, .aiff, .flac) somewhere on your disk.
- In Praat, run
GranularNavigationEngine.praat. - In the directory chooser, select your folder.
- In the form, choose a Navigation_mode:
- Similarity, Smooth, Contrast, Brighter, Darker, Noisier, Harmonic, Denser, Sparser
- Set Grain_ms (e.g. 150 ms), Path_length (number of grains in output).
- Click OK. Python runs (may take a minute for large folders), writes a path CSV,
and Praat reconstructs the result as
GNE_mode_XXgr.
torch, numpy, soundfile.
The autoencoder training uses PyTorch; a CUDA‑capable GPU is not required (CPU is fine).
The script uses batch‑FFT feature extraction – all grains from a file are processed simultaneously,
making it fast even for large folders.
The nine navigation modes
| Mode | Description | Transition logic |
|---|---|---|
| similarity | Stay in acoustically similar regions. | Minimise Euclidean distance in latent space from current grain. |
| smooth | Minimise feature‑space distance (raw features, not latent). | Minimise distance in the 14‑dim feature space. |
| contrast | Jump to regions far from the recent past. | Maximise distance from the mean of the last few grains. |
| brighter | Progressively increase spectral centroid. | Follow direction vector derived from centroid → latent space. |
| darker | Progressively decrease spectral centroid. | Follow direction vector derived from centroid ← latent space. |
| noisier | Increase zero‑crossing rate (ZCR). | Follow direction vector derived from ZCR → latent space. |
| harmonic | Decrease spectral flatness (become more tonal). | Follow direction vector derived from flatness ← latent space. |
| denser | Increase RMS (louder grains). | Follow direction vector derived from RMS → latent space. |
| sparser | Decrease RMS (quieter grains). | Follow direction vector derived from RMS ← latent space. |
For directional modes (brighter … sparser), the engine solves a least‑squares problem to find a vector in latent space that best predicts the target feature. The path then maximises the projection onto that vector, blended with the raw transition score.
Pipeline — six stages
For each file: slice into grains (50% overlap), apply Hanning window to all grains simultaneously, compute 14 features (8 log‑spaced bands, centroid, spread, flatness, rolloff, ZCR, RMS).
Stage 2 – Normalisation (median / IQR, robust to outliers).
Stage 3 – Train autoencoder (16‑dim latent, 80 epochs by default).
Stage 4 – PCA projection to 2‑D (for visualisation).
Stage 5 – Build transition scores (1 / (1 + Euclidean distance) in latent space).
Stage 6 – Navigate path according to selected mode, write CSV.
Praat reconstruction – read CSV, extract grains from original files, concatenate with crossfade.
Feature set (14 dimensions)
- bands 0‑7 – log‑spaced spectral band energies (80 Hz – 8 kHz, log1p).
- centroid_hz – spectral centroid.
- spread_hz – spectral spread (standard deviation around centroid).
- flatness – geometric mean / arithmetic mean (tonal vs. noisy).
- rolloff_hz – frequency below which 85 % of energy lies.
- zcr – zero‑crossing rate.
- rms – root‑mean‑square amplitude.
Autoencoder architecture & training
Encoder
Input (14) → Linear(64) → BatchNorm → LeakyReLU(0.1) → Linear(32) → LeakyReLU → Linear(16)
Decoder
Latent (16) → Linear(32) → LeakyReLU → Linear(64) → LeakyReLU → Linear(14)
Training: Adam (lr=1e‑3, weight decay 1e‑5), CosineAnnealingLR, batch size 32.
Default 80 epochs (can be changed by editing the Praat script – epochs = 80 near the top).
Latent space: 16‑dimensional. After training, the encoder maps each grain to a point in this space.
The transition score between grains i and j is 1 / (1 + ||z_i – z_j||) – similarity in the learned manifold.
Visualization (Praat picture)
When Draw_visualization = 1, the script draws a multi‑panel plot:
- Grain timeline – coloured bars show the source file of each grain (up to 8 files, each with a distinct colour).
- Transition score curve –
transition_scorebetween consecutive grains (from the path CSV). - Embedding scatter – 2‑D PCA projection of the latent embeddings. Grains are coloured by source file. A green circle marks the start grain, red circle the end grain. The path is drawn as a line through the points.
- Mode strip – coloured bar with the navigation mode name.
- Summary panel with total grains, sources, latent dim, epochs, path length, grain size, crossfade.
FAQ / troubleshooting
Install: pip install torch numpy soundfile. On Windows, ensure Python is in PATH
(the script tries python, py, python3).
Check the Info window: if “Grains assembled” is 0, the CSV may have contained filenames that don’t match the actual files (case‑sensitive on Linux). Ensure all files are in the selected folder and have supported extensions (.wav, .aif, .aiff, .flac). Also verify that Grain_ms is not too short for your files (minimum 25 ms).
The engine cannot repeat grains (each grain is used at most once). If the total number of grains is less than Path_length, the path will stop when all grains are exhausted. Increase the corpus size or reduce path length.
For folders with thousands of grains, training may take a minute or two. Reduce epochs (edit the Praat script) or increase grain_ms to reduce the total grain count. The batch‑FFT extraction is already optimised – it’s the PyTorch training that dominates.
The path CSV includes a transition_score column (0–1) derived from latent similarity.
The “next_grain” column gives the index (1‑based) of the following grain – useful for debugging.
The architecture is defined in granular_navigation_engine.py. You can change LATENT_DIM
(currently 16) or the hidden layer sizes, but note that PCA projection to 2‑D assumes latent dim ≥ 2.
Command‑line usage of granular_navigation_engine.py
The Python engine can be run independently (batch processing):