Turn your music into mesmerizing water visuals.
Drop in a track. Pick a vibe. Get a video.
# 1. Install
npm install
# 2. Render your track
npm run render my-song.mp3
# 3. Find your video in ./output/video.mp4That's it. Your video is ready to upload.
Prefer clicking over typing? Open the visual builder:
npm run webThen go to http://localhost:3000 in your browser.
Features:
- Browse songs from your
audio/folder - Preview themes visually
- Generate rendered previews (10s, 15s, or 30s)
- Copy export command for full render
| Theme | Vibe | Colors |
|---|---|---|
| neon-water | Synthwave / Vaporwave | Cyan, Blue, Magenta |
| ocean-deep | Calm / Underwater | Teal, Navy, Turquoise |
| solar-flare | Intense / Fiery | Orange, Red, Yellow |
| aurora | Ethereal / Northern Lights | Green, Blue, Purple |
Preview themes:
npm run themes# YouTube (default)
npm run render my-song.mp3
# Instagram Square
npm run render my-song.mp3 -- -w 1080 -h 1080
# TikTok / Reels (Vertical)
npm run render my-song.mp3 -- -w 1080 -h 1920
# 4K
npm run render my-song.mp3 -- -w 3840 -h 2160npm run render <audio-file> -- [options]| Option | What it does | Default |
|---|---|---|
-o, --output |
Where to save the video | ./output/video.mp4 |
-t, --theme |
Visual theme | neon-water |
-w, --width |
Video width in pixels | 1920 |
-h, --height |
Video height in pixels | 1080 |
-f, --fps |
Frames per second | 30 |
-s, --seed |
Random seed (same seed = same result) | 42 |
-q, --quality |
Quality (lower number = better) | 18 |
# Solar flare theme, high quality
npm run render drop.wav -- -t solar-flare -q 15
# 60fps smooth motion
npm run render beat.mp3 -- -f 60
# Same visuals every time (reproducible)
npm run render song.mp3 -- -s 12345
# Full custom
npm run render track.m4a -- -t aurora -w 1920 -h 1080 -f 30 -o my-video.mp4See what the tool detects in your track:
npm run analyze my-song.mp3Shows you:
- BPM - Detected tempo
- Beats - Where the beats land
- Energy - Loudness over time
- Brightness - High frequency content
| Your Music | What Happens Visually |
|---|---|
| Loud parts | More turbulence, faster particles |
| Kick drums / beats | Bursts of particles, ripples |
| High frequencies | Warmer colors, more glow |
| Complex textures | Denser particle clouds |
| Transients / hits | Color splashes |
- MP3
- WAV
- M4A / AAC
- FLAC
- OGG
- Basically anything FFmpeg can read
Node.js 18+
- Download: https://nodejs.org
FFmpeg
- Mac:
brew install ffmpeg - Ubuntu/Debian:
sudo apt install ffmpeg - Windows: https://ffmpeg.org/download.html
- Tracks with clear beats → More reactive visuals
- Dynamic range → Quiet vs loud = visual variety
- Test at 720p first → Much faster, then do final at 1080p
- Use seed flag → Get the same result every time
"FFmpeg not found" → Install FFmpeg and restart your terminal
Rendering is slow
→ Use 720p for testing: -w 1280 -h 720
Video is too dark
→ Try solar-flare theme or a track with more high frequencies
Out of memory → Close other apps, or use lower resolution
neon-water-2/
├── audio/ ← Put your audio files here
├── output/ ← Rendered videos appear here
│ └── preview/ ← Preview videos
├── src/ ← TypeScript source code
│ ├── audio/ ← Audio analysis (loader, analyzer, beat detection)
│ ├── rendering/ ← Video rendering (headless browser, encoder)
│ └── config/ ← Themes and settings
└── web/ ← Web interface
- Audio Analysis - Reads your track, extracts beats and energy
- Feature Mapping - Converts audio → visual parameters
- Fluid Simulation - GPU-powered water/smoke
- Particles - Glowing dots that react to rhythm
- Bloom - That nice glow effect
- Encoding - Combines frames + audio → MP4
Want to understand the codebase, extend features, or contribute?
Read the Architecture Documentation →
Covers:
- System architecture and data flow
- Audio analysis pipeline (Meyda, beat detection)
- Rendering pipeline (Playwright, Three.js, fluid simulation)
- How to add themes, features, and effects
- Performance considerations
MIT - Do whatever you want with it.
Made for musicians who want visuals without the complexity.