Particula

Particula is an interactive music-driven particle visualizer built with WebGL (Three.js).
It reacts to sound, frequency, and rhythm to create a dynamic audiovisual experience in 3D space.

Demo

Demo video: https://youtu.be/AroTkLpfSSA
(Add the correct link once the video is uploaded.)

Running locally

Requires Node.js: https://nodejs.org

1. Open a terminal in the project folder

2. Start the built-in server:

   node server.js

   Or equivalently:

   npm start

3. Open this address in your browser:

   http://localhost:3000

Alternatively, double-click run.bat (Windows only) — it starts the server and opens Chrome automatically.

Features

• Five independent particle spheres reacting to different frequency bands
• Noise and turbulence dynamics influenced by audio input
• Beat detection with reactive wave effects
• Switch between audio player and microphone input
• Real-time parameter editing via built-in GUI
• Preset system (save, load, export, import)

Preset Parameters Explained

Here is a visual guide to the most important parameters you can tweak in presets/factory.json or via the UI:

📐 Shape and Geometry

• sphereRadius: The outer size of the sphere.
• innerSphereRadius: The hollow core inside the sphere. Set close to sphereRadius for a thin shell, or 0 for a solid filled cloud.
• particleCount & particleSize: The density of the cloud and the size of each dot. High count + small size = smooth fog. Low count + large size = starry/snow effect.
• particleLifetime: How long (in seconds) a particle exists before respawning. Low values (1-3s) create a boiling/sparking effect; high values (15s+) create smooth, lingering trails.

🔄 Movement and Rotation

• rotationSpeedMin & Max: The baseline spin speed and the maximum speed reached during loud peaks.
• rotationSmoothness: How smoothly the sphere accelerates/decelerates in response to volume changes. Higher values yield smooth momentum; lower values yield snappy, jerky movements.

🌪️ Distortion and Turbulence (Noise)

• turbulenceStrength: The force that scrambles particles in random directions. Low value = clean sphere; high value = chaotic nebula.
• noiseScale: The frequency of the ripples on the sphere. Low = large, smooth waves; high = jagged, sharp edges.
• dynamicNoiseScale: When true, loud audio peaks instantly randomize the noise scale, "shaking" the shape.
• noiseSpeed: How fast the ripple pattern flows across the sphere's surface.

🔊 Audio Reactivity (Beats)

• gainMultiplier: Artificial volume boost for the visualizer.
• beatThreshold: The energy level (0-255) the audio must surpass to be registered as a "beat".
• beatStrength: The explosive force that pushes particles outward from the center on every beat.
• baseWaveStrength: The intensity of the global shockwave effect that travels through the particles on a beat.

Collaboration

• This is the official repository of the Particula project.
• Feel free to experiment, modify, and contribute.
• If you publish a fork or derivative version, please acknowledge the original and do not use the name "Particula" without permission.
• Open a pull request, start a discussion, or fork the repo and experiment. If you build something cool, we’d love to see it – especially presets or entirely new directions.
• Share your presets: Humprt/particula#3

Ideas for Future Development

• Add a moving camera to enhance depth and immersion.
• Decouple the spheres from the center – let them float freely in 3D space.
• Try alternative shapes: rings, ellipsoids, toruses.
• Make the noise animation slow down or sync with tempo.
• Assign more particles to lower frequencies (logarithmic sound spectrum distribution).

License

MIT © 2025 Humprt Pum
Free to use and modify with attribution.

Credits

Built by a human-AI duo:
Humprt (vibe-coder) and Caroline (ChatGPT 4o)
Born from long nights, experimental tweaks, and love for sound and visual poetry.