Fluid Event Fields — Compositional Particle Synthesis

Segments a sound into discrete time-domain events (onsets or fixed grains), treats each event as a point in a (time, descriptor) plane, carries that point forward through an analytic vector field (Vortex, Sink, Source, Shear), and re-renders the events at their new positions — reordered, dispersed, duplicated, collided — as a new arrangement of the original material.

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

Contents:

What this does Quick start 5 Presets 4 Vector Fields Key Concepts Applications

What this does

This script implements a compositional event-field synthesis — a companion to FluidVectorFields.praat ("Fluid Spectral Warp"). Where that instrument continuously deforms a sound's spectral phase through a vortex/sink/source/shear field, this instrument segments the sound into discrete time-domain events (onsets or fixed grains), treats each event as a point in a (time, descriptor) plane, carries that point forward through the same analytic field, and re-renders the events at their new positions — reordered, dispersed, duplicated, collided — as a new arrangement of the original material.

FluidVectorFields vs. Fluid Event Fields: This is a compositional effect that shifts whole events (grains) through time and space, rearranging the grains into new temporal structures. It employs analytical vector fields—such as Vortex, Sink, Source, and Shear—operating at two distinct tiers: the spectral bin level and the event level.

Key Features:

5 Presets — Vortex Motion, Density Collapse, Spectral Bloom, Cyclic Return, Shear Scatter
4 Vector Fields — Vortex, Sink, Source, Shear
2 Segmentation Modes — Onset detection or Fixed grain
3 Vertical Axes — Spectral centroid, Dominant frequency, RMS energy
Collision policies — Layer, Repel, Queue
Canvas policies — Preserve, Expand, Wrap
Event duplication — probability and count
Density gain compensation — automatic level adjustment
Visualisation — field map, time-displacement scatter, event vectors, summary panel

Canvas policy: Preserve and Wrap always keep the source duration. Expand may create a longer result when events are dispersed, duplicated, or collision-resolved beyond the original boundary. The output is a new Sound object with the same sample rate and channel count as the input.

Quick start

In Praat, select exactly one Sound object.
Run script… → FluidEventFields.praat.
Choose a preset (Vortex Motion, Density Collapse, Spectral Bloom, Cyclic Return, Shear Scatter, or Custom).
If Custom, configure the 4-page form: Analysis (segmentation, grain size, vertical axis), Field (field type, strength, viscosity), Timing (canvas policy, collision policy, boundary), Output (duplication, gain compensation, seed).
Adjust Motion_amount (0–2) — scales how far events travel through the field.
Set Centre_time (0–1) — the field's centre in the time axis.
Select Normalize_mode (None, Peak, RMS).
Click OK — Python engine segments, integrates, renders, and imports the result.

Quick tip: Start with Vortex Motion for a gentle circular reordering of events. Density Collapse (Sink field, onset segmentation) pulls events toward a centre point. Spectral Bloom (Source field) disperses events outward. Cyclic Return (Vortex, duplication) creates looping textures. Shear Scatter (Shear field, Repel collision) spreads events while preserving order. Enable Draw_visualization to see the event field map and time-displacement scatter.

Important: Python dependencies required: pip install numpy scipy soundfile. The segmentation mode determines how events are extracted: Onset detection uses spectral flux to find transients; Fixed grain uses a uniform grid. The vertical axis (centroid/dominant/rms) controls which descriptor events are positioned on the vertical axis. The field integrates events forward through time — Motion_amount scales the integration distance. The output may be longer than the input if canvas policy is set to Expand.

5 Presets

Preset	Field	Segmentation	Axis	Canvas	Collision	Duplication	Character
Vortex Motion	Vortex	Fixed grain	Centroid	Preserve	Layer	none	Gentle circular reordering of events
Density Collapse	Sink	Onset	RMS	Preserve	Layer	none	Pull events toward centre
Spectral Bloom	Source	Fixed grain	Centroid	Expand	Layer	10%	Disperse events outward
Cyclic Return	Vortex	Fixed grain	Dominant freq	Wrap	Layer	25% × 2	Looping, repeating textures
Shear Scatter	Shear	Fixed grain	Centroid	Expand	Repel	none	Spread events while preserving order

4 Vector Fields

Vortex rotational

Rotates events around the centre point. Direction (Positive/Negative) controls clockwise or counter-clockwise rotation.

Use: Circular reordering, cyclical textures, swirling motion.

Sink attractive

Pulls events toward the centre point. Strength controls the pull intensity.

Use: Density collapse, clustering, convergence textures.

Source repulsive

Pushes events away from the centre point. Strength controls the push intensity.

Use: Dispersion, blooming, expansion textures.

Shear directional

Shears events horizontally based on their vertical position. Direction controls the shear direction.

Use: Rhythmic stretching, time-warping, scatter textures.

Field equations

Vortex: du = -v·f(r), dv = u·f(r), f(r) = e^{−r²/(2σ²)}

Sink: du = −u·f(r), dv = −v·f(r)

Source: du = u·f(r), dv = v·f(r)

Shear: du = tanh(v/σ)·f(u), dv = 0

where σ = 0.35 + 1.15·viscosity, r² = u² + v².

Key Concepts

Segmentation

Onset detection: Spectral flux + adaptive threshold — finds transients in the source.
Fixed grain: Uniform grid of overlapping grains — predictable, uniform events.
Pre-onset capture and post-tail allow natural attack/decay preservation.

Vertical axes

Spectral centroid: Brightness of the event's spectrum.
Dominant frequency: Peak frequency of the event.
RMS energy: Amplitude of the event.

Collision policies

Layer: Events overlap freely (no collision resolution).
Repel: Events push apart to maintain spacing.
Queue: Events are placed sequentially without overlap.

Canvas policies

Preserve: Output duration = input duration.
Expand: Output duration may grow beyond input.
Wrap: Events wrapping around the edge.

Vertical response modes: Field motion in the vertical axis can be mapped to:

Pitch: Vertical displacement → semitone shift.
Gain: Vertical displacement → amplitude change (dB).
Duration: Vertical displacement → time stretching/compression.
None: Vertical motion is purely compositional (reordering).

Applications

Compositional reordering (Vortex Motion)

Use case: Reorder events in a circular pattern — the sound's phrases are rearranged into a new sequence.

Settings: Vortex Motion preset, Motion_amount=0.8. Events rotate around the centre time, creating a new temporal arrangement.

Density collapse (Density Collapse)

Use case: Pull events toward a centre point — rhythmic convergence, density build-up.

Settings: Density Collapse preset, onset segmentation. Percussive events cluster toward the centre, creating a "collapse" texture.

Blooming / dispersion (Spectral Bloom)

Use case: Push events outward — expanding textures, spectral blossoming.

Settings: Spectral Bloom preset, fixed grain, Expand canvas. Events spread outward, lengthening the output.

Cyclic / looping textures (Cyclic Return)

Use case: Create looping, repeating textures with duplicated events.

Settings: Cyclic Return preset, Wrap canvas, duplication probability=0.25. Events wrap around the canvas and duplicate, creating a cyclic texture.

Workflow: Spoken word → Vortex reordering

Source: Spoken word recording.
Settings: Vortex Motion preset, Onset segmentation, Motion_amount=0.7.
Result: The spoken phrases are rearranged in a circular pattern — words appear in a new order, creating a "vortex" of speech.

Workflow: Drum loop → Density collapse

Source: Drum loop.
Settings: Density Collapse preset, Onset segmentation (captures hits), Motion_amount=0.9.
Result: Drum hits are pulled toward a centre point, creating a dense, clustered rhythm — like a "collapse" of the beat.

Workflow: Synth pad → Spectral bloom

Source: Sustained synth pad.
Settings: Spectral Bloom preset, Fixed grain (0.18 s), Expand canvas, Motion_amount=0.8.
Result: The pad's grains are pushed outward, creating a blooming, expanding texture that lasts longer than the original.

Troubleshooting:
• No events detected (onset segmentation): Increase sensitivity or use Fixed grain mode. The onset detector uses spectral flux; very quiet or smoothly evolving sounds may produce few events.
• Output is identical to input (identity shortcut): If field strength is low and canvas policy is Preserve, the engine bypasses processing entirely. Increase Motion_amount or change the field type.
• Output has clicks at event boundaries: Increase Event_overlap or adjust Pre-onset/Post-tail values. The fade settings control crossfade between events.
• Canvas Expand produces very long output: The Expand policy caps output at 4× the input duration. If events are dispersed widely, reduce Integration_amount or Motion_amount.
• Duplication produces too many events: Reduce Duplication_probability or Duplication_count. Each duplicate adds a gain reduction (−3 dB per generation) and extra integration.

Visualisation

When Draw_visualization is enabled, the script generates:

Event field map — normalised time (u) vs descriptor (v) space, showing field arrows (background) and event vectors (before → after).
Time-displacement scatter — original time vs final rendered time for each event. Identity line shown in grey.
Input and output waveforms — original (grey) and fluid-processed (green).
Summary panel — field type, segmentation mode, axis, canvas policy, collision policy, event counts, displacement stats, pitch/gain stats.

The event field map is the key diagnostic: it shows the field's shape and how events move through it.