Particula – Advanced Setup Guide

This guide provides everything you need to install, use, and customize the Particula visualizer.

---

📦 Requirements

• Node.js (https://nodejs.org)
• A modern web browser (Chrome or Firefox recommended)
• (Optional) VB-Cable or VB HiFi Cable for capturing system-wide audio

---

🖥️ Running Locally

1. Open a terminal in your project folder.

2. Install or verify you have Node.js (v14+). Then run:

bash npx serve .

1. Open your browser at:

http://localhost:3000

Windows shortcut: double-click run.bat to start a server and open the project automatically.

Note: You must serve files via a local server; opening index.html directly from the filesystem won't work, because Particula loads scripts from CDNs.

---

🎧 Audio Input Setup

Particula can visualize audio from two main sources:

• Audio Player: Streams files placed in the Songs/ folder.
• Microphone: Captures live sound from your mic or virtual audio cable.

On-Screen Audio Controls

When running Particula, you’ll see a small panel at the top (or a floating one), containing:

• Song Select: Dropdown of .mp3, .wav, or .ogg files from your Songs/ folder.
• Play/Pause: Toggles playback of the selected file.
• Volume Slider: Adjusts the volume of the audio element.
• Timeline Slider: Lets you seek through the loaded track.
• Use Mic / Use Player: Switch between audio files or microphone input.

If no songs appear:

• Make sure you created a Songs/ folder
• Ensure you’re running via npx serve . (not file://)

Tip: Some browsers block autoplay. Click the screen or the Play button to start audio.

---

🔌 VB-Cable Setup (Windows Only)

To make Particula react to system-wide audio (Spotify, YouTube, etc.), install a virtual cable:

Option 1: VB-Cable

1. Install VB-Audio Virtual Cable: https://vb-audio.com/Cable/
2. In Windows Sound Settings:
3. Playback (Output) → CABLE Input
4. Recording (Input) → CABLE Output
5. Enable "Listen to this device":
6. Right-click sound icon → Sound settings → More sound settings
7. Recording tab → Right-click CABLE Output → Properties → Listen tab
8. Check "Listen to this device", select your speakers/headphones
9. Confirm with OK

Option 2: VB HiFi Cable (Recommended)

1. Install HiFi Cable: https://vb-audio.com/Cable/
2. Output → Hi-Fi Cable Input
3. Input → Hi-Fi Cable Output
4. In Recording → Hi-Fi Cable Output → Properties:
5. Enable "Listen to this device"
6. Advanced → 44100 Hz, 16-bit (CD Quality)

---

⚠️ Windows Automatic Gain Control (AGC)

Windows 11 can auto-adjust mic input volume, causing fluctuations.

Why It Happens:

• Windows detects CABLE Output/Hi-Fi Cable Output as a microphone.
• AGC tries to "improve" volume.
• Particula sees unexpected amplitude changes.

Disabling AGC:

1. Press Win + R, type regedit, press Enter
2. Search (Ctrl + F) for CABLE Output or Hi-Fi Cable Output
3. Locate audio Capture entries
4. Right-click → New → DWORD (32-bit) Value
5. Name it EnableAGC → value 0
6. Restart PC

Proceed carefully. Registry edits can affect system behavior.

---

🧪 GUI Overview

Particula uses a dat.GUI panel to tweak parameters in real time. Each sphere has its own folder, plus a few global controls:

• Global Particle Count: One master setting for all sphere particle counts
• Fog Settings: Enable/disable fog, set color, and adjust near/far distances

Click outside the GUI or control panels to hide them – click again to show them.

---

🎛️ GUI Parameter Reference

Per-Sphere Parameters

1. enabled

2. Toggles visibility of the sphere's particle system.

3. particleCount

4. Sets how many particles are generated.

5. particleSize

6. Controls each particle’s rendered size.

7. particleLifetime

8. How many seconds before a particle is "reborn." Once time is up, it respawns at a new position.

9. sphereRadius

10. The maximum distance particles can occupy from the center.

11. innerSphereRadius

12. A 0–1 factor that controls how close to the center initial spawn can be.

13. rotationSpeedMin / rotationSpeedMax

14. Defines the lower/upper bound of rotation speed around the y-axis. The actual speed is tied to audio volume.

15. rotationSmoothness

16. How gently rotation speed transitions in response to volume changes.

17. volumeChangeThreshold

18. Ignores volume differences below this threshold.

19. minFrequency / maxFrequency

    • The frequency band (Hz) used for amplitude-based motions.

20. minFrequencyBeat / maxFrequencyBeat

    • The frequency band used for detecting beat spikes.

21. noiseScale

    • The scale of the Perlin noise field affecting particle movement.

22. dynamicNoiseScale

    • If true, noiseScale auto-changes after a peak event.

23. minNoiseScale / maxNoiseScale

    • Range for that dynamic noiseScale.

24. noiseStep

    • Step size for noiseScale jumps when a beat is detected.

25. noiseSpeed

    • How fast the noise "flow" evolves.

26. turbulenceStrength

    • Intensity of noise forces.

27. colorStart / colorEnd

    • Defines a color gradient for the particles.

28. peakSensitivity

    • Controls how easily peaks are triggered. If current amplitude > average * peakSensitivity, we register a peak.

29. beatThreshold

    • Raw amplitude threshold for the beat band.

30. beatStrength

    • Push intensity applied to particles when a beat is detected.

31. gainMultiplier

    • Multiplies frequency data. Raise it to make the sphere more reactive.

32. historyLength (peakDetection)

    • Number of amplitude samples stored for averaging.

33. minTimeBetweenPeaks (peakDetection)

    • Milliseconds that must pass before detecting another peak.

---

Global GUI Parameters

1. Global Particle Count

2. Forces all spheres to share the same particle count.

3. Fog

4. enabled: Toggles fog.

5. color: Fog color.
6. near / far: Adjusts how quickly fog fades in/out.

---

💾 Presets

Save your favorite sphere + global settings, then load them later or share as JSON.

• Save: Creates a named preset.
• Reset: Returns to defaults.
• Delete: Removes a preset.
• Export/Import: Backs up all presets or loads them from disk.

Presets are stored in your browser’s localStorage by default.

---

🔧 Troubleshooting

Audio not reacting?

• Ensure microphone permissions are granted.
• Check VB-Cable settings if you want system audio.
• Reload the browser after changing device inputs.

Mic input too quiet or volume shifts unexpectedly?

• Windows AGC might be active. (See above.)
• Try the HiFi Cable with manual volume control.

No songs listed in the dropdown?

• Confirm a Songs/ folder is present.
• Use a local server (npx serve .).
• Make sure your audio files end in .mp3, .wav, or .ogg.

---

🛠️ Dev Mode Tips

• main.js centralizes logic: spheres, audio analyzers, beat detection.
• Each sphere is constructed similarly; you can clone or expand that function.
• Beat detection uses a combination of averaging, thresholds, and time gating.
• Presets are stored per sphere in a structured JSON.
• If you add new parameters, update the GUI code accordingly.

---

Copy Settings to Other Spheres

In the GUI for Sphere 1, you might see a button named Copy to Spheres 2-5. Clicking it duplicates Sphere 1’s current parameters to the others.

---

📖 Usage Flow Summary

1. Open Particula in your browser via http://localhost:3000.
2. Decide if you want to play local files or capture mic/system audio.
3. Adjust sphere parameters in the GUI:
4. Turn on or off certain spheres.
5. Play with color gradients, noise, or beat detection.
6. Hide the GUI by clicking outside it; click again to show.
7. Save/Load presets as you discover interesting visuals.

Enjoy exploring Particula! For deeper modifications, read the commented sections in main.js.

---

Happy visualizing!