Autonomous Procedural 3D Concert Stage Simulator & Neural Music Visualizer
A stadium-scale music festival concert simulator that orchestrates real-time, procedural 3D audiovisual performances. Powered by Meta Demucs v4 neural 4-stem source separation, Apple Silicon Metal Performance Shaders (MPS), Shazam acoustic recognition, synchronized YouTube 4K stage video playback, and intelligent concert lighting choreography.
Note
Audio & Visual Demo Showcase:
- Song & Music Video: Abandoned - Destroyer Of Worlds (Oppenheimer Remix) [Music Video]
- Creator / Channel: Abandoned (@AbandonedOfficial)
- Full music and visual credit to Abandoned for the audio composition and official music video featured in this demonstration.
Important
Synwave is an evolving open-source project, and I know it still has bugs and areas that need improvement. Contributions, bug reports, suggestions, and pull requests are very welcome. Help me fix the existing issues and turn Synwave into a polished, reliable product!
- 🎬 Live Demo Preview
- 🌟 Project Overview
- 🏗️ Architectural Block Diagram
- ✨ Key Features
- ⌨️ Controls & Keyboard Shortcuts
- 🚀 Installation & Development Setup
- 🔑 YouTube Data API v3 Configuration
- 🛠️ Technologies & Official Repositories
- 📜 Third-Party Libraries, Licenses & Attribution
- 🐛 Known Issues & Roadmap
- 🤝 How to Contribute
- 📄 License
Synwave transforms any local audio file into a stadium-scale procedural concert experience. Rather than drawing simple 2D FFT spectrogram bars or unanchored wandering particles, Synwave acts as an autonomous concert lighting designer and stage director.
It places the user in the front-row audience facing a colossal festival stage modeled after real-world arena spectacles (Ultra Music Festival, Tomorrowland, EDC).
When an audio file is loaded, Synwave executes an acoustic intelligence pipeline:
- Acoustic Fingerprinting & Track Resolution: Resolves song identity, artist, and album via ShazamIO in
< 1.5sand caches the match. - Neural Source Separation (Meta Demucs v4): Isolates the audio into 4 discrete acoustic stems (
drums,bass,instruments,vocals) accelerated by Apple Silicon MPS hardware. - Tri-STEM Peak Drop Pinpointing: Identifies the precise climactic segments where drums, bass, and instruments simultaneously exceed their track averages.
- Synchronized 4K Stage Video: Resolves the official music video via YouTube Data API v3, hosting it inside an aperture screen driven by the lossless local audio clock.
- Procedural 3D Stage Choreography: Directs moving-head spotlights, an expansive 22-pattern 360° laser choreography rig, camera sub-bass FOV zooms, and vertical-sync full-window blinder washes.
Synwave is structured into a four-tier decoupled architecture separating acoustic intelligence, real-time audio analysis, stage choreography, and hardware-accelerated presentation.
flowchart TD
subgraph INGEST["1. INGEST & ACOUSTIC INTELLIGENCE LAYER"]
A["Local Audio File\n(MP3, WAV, FLAC, M4A)"] --> B["SHA-256 Fingerprint Generator"]
B --> C{"3-Tier STEM Cache"}
C -->|"Hit (< 10ms)"| D["Decoded Stem Data Store"]
C -->|"Miss"| E["FastAPI Daemon (:8765)"]
subgraph DAEMON["Python Microservice (Apple Silicon MPS / CUDA)"]
E --> F["ShazamIO Recognition Engine"]
E --> G["Meta Demucs v4 (htdemucs)"]
G --> H["4-Stem Isolation\n(Drums, Bass, Inst, Vocals)"]
H --> I["25 FPS RMS Envelopes &\nStatic Track Averages"]
H --> J["Kick Comb Filter & Transient Onsets"]
end
F --> K["Track Identity (Title, Artist, BPM)"]
I --> D
J --> D
end
subgraph ANALYSIS["2. REAL-TIME FEATURE & DROP PINPOINTING ENGINE"]
A --> L["Web Audio API AudioContext"]
L --> M["Master Hardware Audio Clock (t)"]
L --> N["AnalyserNode (2048 FFT)"]
D & N --> O["Tri-STEM Peak Drop Gate"]
O -->|"D > D_avg && B > B_avg && I > I_avg"| P["isTriStemDropActive (Drops Only)"]
N --> Q["Sub-Bass Filter\n(20 - 100 Hz)"]
N --> R["Transient Kick Edge Detector\n(40 - 150 Hz, 180ms Lockout)"]
N --> S["Mid-Range Spectral Engine\n(250 Hz - 4 kHz: Centroid, Flux, Dispersion)"]
D --> T["BeatGrid & Phrase Engine"]
end
subgraph DIRECTOR["3. STAGE DIRECTOR & CHOREOGRAPHY PIPELINE"]
K --> U["YouTube Data API v3"]
U --> V["Official Stage Video ID & Thumbnail Palette"]
V --> W["laserColorUtils: Direct Palette Normalization"]
P & S & W --> X["22-Pattern 360° 3D Laser Engine\n(85m End-to-End Beams, Zenith to Pit)"]
T & K --> Y["Symmetrical BPM Moving-Head Lights\n(2 to 12 Fixtures, Monotonic 70-160 BPM)"]
Q --> Z["Audience Camera FOV Punch\n(60° to 63.5° Dynamic Zoom)"]
R --> AA["YouTube Iframe Screen Shake\n(Isolated Kick Transform)"]
R & P & W --> AB["Direct-DOM Full-Window Blinder\n(0.96 Peak Opacity, Compulsory White + Palette)"]
end
subgraph PRESENTATION["4. PRESENTATION & RENDERING LAYER"]
M --> AC["Continuous 100ms Video Drift Alignment\n(|Δt| > 140ms ➔ seekTo)"]
AC --> AD["YouTube 4K Stage Video Aperture\n(z-index: 1, pointer-events: auto, volume: 0)"]
X & Y & Z --> AE["Three.js r186 WebGL2 Scene Graph\n(z-index: 2, pointer-events: none)"]
AA --> AD
AB --> AF["Festival Window Blinder Overlay\n(z-index: 15, Direct DOM Mutation)"]
AD & AE & AF --> AG["Glassmorphic HUD & Control Dock\n(z-index: 25: Console [C], Telemetry [D], Info [i])"]
end
====================================================================================================
SYNWAVE SYSTEM TOPOLOGY
====================================================================================================
[ Local Audio File ] ─────────► [ SHA-256 Fingerprint Engine ]
│
┌────────────────────────────┴───────────────────────────┐
▼ (Cache Hit < 10ms) ▼ (Cache Miss)
[ 3-Tier Stem Cache ] [ FastAPI Daemon (:8765) ]
• Tier 1: In-Memory Map • ShazamIO Song Recognition
• Tier 2: Browser IndexedDB • Meta Demucs v4 (htdemucs on MPS)
• Tier 3: Local Disk Cache • Static Averages (D_avg, B_avg, I_avg)
│ • Kick Onsets & Comb Filtering
└────────────────────────────┬───────────────────────────┘
│
▼
[ Real-Time Audio Engine ]
• Web Audio API Master Clock (t)
• 2048-Point FFT Spectral Decomp
• Tri-STEM Peak Drop Activation:
(D > D_avg) ∧ (B > B_avg) ∧ (I > I_avg) ∧ (Joint ≥ Thresh)
│
┌───────────────────────────────────┼───────────────────────────────────┐
▼ ▼ ▼
[ Sub-Bass (20-100Hz) ] [ Kick Transient (40-150Hz) ] [ Mid-Range Spectral (250Hz-4kHz) ]
FOV Camera Punch (60°-63.5°) Screen Shake & Blinder Trigger 22-Pattern 360° 3D Laser Engine
│ │ │
└───────────────────────────────────┼───────────────────────────────────┘
│
▼
[ Show Director & Visual Engine ]
• Authentic Multi-Color Laser Palette Mapping
• 22-Pattern 360° 3D Concert Laser Choreographies
• Symmetrical BPM-Synchronized Moving Heads (2-12)
• Full-Window Blinder Wash (0.96 Opacity, White + Song Colors)
│
┌────────────────────────────────────┴───────────────────────────────────┐
▼ ▼
[ Three.js r186 Scene Graph ] [ YouTube 4K Stage Screen ]
• Transparent WebGL2 Canvas (z: 2) • 16:9 Stage Aperture (z: 1)
• 85m End-to-End Laser Rays (360° 3D) • Muted Video Playback (vol: 0)
• Stage Truss & Jumbotron Bezels • Master Clock Continuous Sync Loop
• Billboard Dust & Atmosphere • Zero Synwave Text Overlays
====================================================================================================
-
Shazam-First Prerequisite Pipeline: Recognition executes before neural separation. Tracks are identified in
< 1.5sand cached in persistent storage (synwave_shazam_cache_v2). The recognized song title and artist are instantly displayed in the loading interface. -
Meta Demucs v4 HTDemucs (
demucs_service.py): Isolates local audio into four discrete high-fidelity stems:drums,bass,instruments, andvocals. Running on Apple Silicon Metal Performance Shaders (MPS) or NVIDIA CUDA, it computes 25 FPS normalized RMS envelopes, static track-wide averages ($\bar{A}_D, \bar{A}_B, \bar{A}_I$ ), and transient kick onsets. -
3-Tier Persistent Stem Cache:
- Tier 1 (Memory): Synchronous JS Map for zero-latency in-session lookups.
-
Tier 2 (IndexedDB): Browser-persistent object store (
synwave_stems_db) allowing instant song switches and page reloads without re-computation or storage quotas. -
Tier 3 (Server Disk): Cached JSON envelopes and recognition in
.synwave_cache/stems/{sha256}.jsonand.synwave_cache/shazam/{hash}.json. The lightweight/api/check-stems-cacheand/api/check-shazam-cachepre-flight endpoints bypass audio file re-uploads entirely.
-
Pinpointed Tri-STEM Peak Drop Gate (
AudioEngine.ts): Lasers and climactic visuals are gated strictly by the song's true drop segment. A frame qualifies as a drop if and only if:$$D(t) > \bar{A}_D ;\land; B(t) > \bar{A}_B ;\land; I(t) > \bar{A}_I ;\land; J(t) \ge \text{Threshold}$$ This mathematical gate completely eliminates false activations during vocal buildups, quiet intros, and acoustic breakdowns. -
Isolated Sub-Bass Bandpass (
$20-100\text{Hz}$ ): Directly drives camera FOV zoom punch ($60^\circ \to 63.5^\circ$ ), physically vibrating the audience perspective without harmonic distortion from vocals or guitars. -
Transient Kick Detection (
$40-150\text{Hz}$ ): Comb-filtered kick detector with a 180ms refractory lockout drives 2D pixel displacement strictly on the YouTube stage screen element. -
Mid-Range Spectral Engine (
$250\text{Hz}-4\text{kHz}$ ): Computes mid-range spectral centroid ($C_{\text{mid}}$ ), spectral flux ($F_{\text{mid}}$ ), and dispersion ($D_{\text{mid}}$ ) fused with Demucs instrumental data to steer intelligent concert laser choreographies without bass interference.
-
22-Pattern 360° 3D Laser Choreography Engine (
laserChoreography.ts):- Generates 3-dimensional spherical vectors projecting upward to the stadium zenith (
$Y \in [14, 26]$ ), downward to the stage pit ($Y \in [-10, 0]$ ), across wide peripheral horizons ($X \in [-35, +35]$ ), and directly forward past the audience camera ($Z \in [0, 25]$ ). - Normalizes rays to an 85-meter length (
FULL_WINDOW_BEAM_LENGTH = 85.0), guaranteeing beams pierce from nozzle origins through and beyond the browser window boundaries. - Features 22 distinct geometric choreographies (Audience Scan Wave, Cathedral Scissor, Double-Helix Spiral, Stadium Fan, Rotating Pinwheel, Tunnel Perspective, etc.) smoothly blended via Hermite cubic smoothstep curves (
$0.50\text{s}$ ).
- Generates 3-dimensional spherical vectors projecting upward to the stadium zenith (
-
Authentic Multi-Color Laser Palette Mapping (
laserColorUtils.ts):- Songs featuring multiple vibrant colors map those exact hues directly to alternating laser stations (Tone 1 = Primary, Tone 2 = Secondary).
- Eliminates forced 180° opposite hue inversion, preserving authentic visual harmony with the song's album artwork and music video.
-
Symmetrical BPM Spotlights (
StageLightsEffect.ts): Symmetrically frames the YouTube screen across Top, Left, and Right fixtures, scaling dynamically from 2 to 12 fixtures based on detected BPM ($70-160\text{ BPM}$ ). -
Full-Window Screen Flash Blinder (
VisualEngine.ts):- Full-window elliptical radial gradient wash covering
$100\text{vw} \times 100\text{vh}$ atz-index: 15. - Driven by direct DOM mutation on
#festival-window-blinder, delivering vertical-sync accuracy without React component re-renders. - Synchronized with kick transients; compulsory pure white (
#FFFFFF) on downbeats, cycling through song palette colors with white-hot filament cores.
- Full-window elliptical radial gradient wash covering
-
Three.js r186 WebGL2 Canvas (
z-index: 2): Transparent canvas overlaying the stage video with additive volumetric laser blending, stage trusses, moving heads, and atmosphere dust. -
Synchronized 4K YouTube Stage Aperture (
z-index: 1):- Muted video playback (
volume = 0) complying with browser autoplay policies while local lossless audio serves as the master clock. - Continuous 100ms drift monitor: if video drifts
$> 140\text{ms}$ from master audio, micro-seeks snap the playhead back into phase. - Clean video aperture: zero Synwave-generated text overlays, badges, or titles over the video; captions disabled by default (
cc_load_policy: 0,controls: 0).
- Muted video playback (
-
Responsive Glassmorphic HUD (
z-index: 25): Floating docks, Audio-to-Visual Routing Console (C), Real-Time Telemetry HUD (D), and YouTube metadata modal (i).
- 22-Pattern 360° 3D Concert Laser Choreography: Three laser stations mounted above the stage fire 85-meter end-to-end beams across all 3 dimensions—zenith skyward sweeps, deck sweeps, wide stadium fans, and audience fly-throughs.
- Authentic Multi-Color Laser Palette Mapping: Multi-color songs directly use their authentic album colors across laser stations without forced 180° complementary inversion.
- Pinpointed Tri-STEM Peak Drop Activation: Lasers activate exclusively during true musical drops where Drums, Bass, and Instruments simultaneously exceed track averages, staying cleanly off during intros, verses, and breakdowns.
-
Full-Window Screen Flash Blinder:
High-intensity
$100\text{vw} \times 100\text{vh}$ blinder wash with 0.96 peak opacity, direct DOM mutation, and compulsory pure white downbeats cycling through song palette colors. - High-Precision Audio-Video Drift Synchronization: A 100ms continuous monitoring loop locks the YouTube stage video to the master Web Audio clock, snapping buffered video into lip-sync and percussive phase.
-
3-Tier Persistent STEM Cache:
Subsequent plays of analyzed songs load in
< 10msfrom Memory, IndexedDB, or local disk, eliminating redundant neural compute. -
Shazam-First Track Recognition:
Acoustic fingerprinting resolves track title and artist in
< 1.5sbefore neural separation, displaying verified metadata throughout the loading experience. -
Clean Stage Video Aperture:
The YouTube concert screen is completely free of text overlays, status badges, or forced closed captions (
cc_load_policy: 0). -
Dual-Layer Audio Impact:
Deep sub-bass (
$20-100\text{Hz}$ ) drives camera FOV zoom punch ($60^\circ \to 63.5^\circ$ ), while percussive kicks shake the YouTube stage screen in 2D space. - Symmetrical BPM-Scaled Moving Heads: Moving-head spotlights scale dynamically from 2 to 12 fixtures framing the screen based on verified track tempo.
-
Freeze-on-Pause Engine:
Pausing playback instantly halts visual time accumulators (
deltaSeconds = 0). Moving heads, beams, and lasers freeze in place without snapping. -
Interactive Routing Console & Telemetry HUD:
Press
Cfor real-time calibration of shake, blinders, decay, and photosensitive safety mode. PressDfor live FFT, stem energy, and MPS hardware telemetry.
| Key / Shortcut | Action | Description |
|---|---|---|
Space |
Play / Pause | Toggle playback (with input focus protection and iframe focus recovery). |
F |
Toggle Fullscreen | Enter or exit native edge-to-edge fullscreen mode. |
Double-Click |
Toggle Fullscreen | Double-clicking anywhere on the 3D stage toggles fullscreen. |
C |
Routing Console | Open or close the Audio-to-Visual Routing Console. |
D |
Telemetry HUD | Toggle the Real-Time Synchronization & Diagnostics Overlay. |
M |
Reduced Flash Mode | Toggle photosensitive safety blinder strobe reduction. |
Arrow Left |
Seek -5 Seconds | Scrub playback backward by 5 seconds. |
Arrow Right |
Seek +5 Seconds | Scrub playback forward by 5 seconds. |
Digit 1 |
Festival Profile | Re-engage the Festival Mainstage choreography profile. |
Ensure you have the following installed on your machine:
- Node.js: v18.0.0 or later (v20+ recommended)
- npm: v9.0.0 or later
- Python: v3.10, v3.11, or v3.12 (with
venvsupport) - macOS / Linux / Windows:
- macOS (Apple Silicon M1/M2/M3/M4): Supported with native Metal Performance Shaders (MPS) hardware acceleration.
- Windows / Linux: Supported with NVIDIA CUDA or CPU fallback.
- ffmpeg (recommended): For broader local audio format decoding.
git clone https://github.com/K-692/Synwave.git
cd Synwavenpm installSynwave uses a local FastAPI microservice for Shazam acoustic fingerprinting and Meta Demucs neural stem separation.
# 1. Create a dedicated Python virtual environment
python3 -m venv .venv
# 2. Activate the virtual environment
# On macOS / Linux:
source .venv/bin/activate
# On Windows (cmd.exe):
# .venv\Scripts\activate.bat
# On Windows (PowerShell):
# .venv\Scripts\Activate.ps1
# 3. Upgrade pip and install required dependencies
pip install --upgrade pip
pip install -r requirements.txtSynwave requires a Google Cloud YouTube Data API v3 key to search and synchronize official stage videos.
You can configure the key in either of two ways:
- Via Environment File (Recommended for Development):
Open
cp .env.example .env
.envin your text editor and paste your key:VITE_YOUTUBE_API_KEY=AIzaSy...
- Via In-App Startup Gate: Launch the app without a key, and Synwave will present the interactive startup gate modal where you can paste and validate your key directly.
(See YouTube Data API v3 Configuration below for a 2-minute setup guide).
Run the unified startup script that launches both the Python audio intelligence microservice and the Vite frontend dev server with one command and automatic graceful shutdown (Ctrl+C):
# Using the executable shell script
./start.sh
# Or via npm
npm start
# (or npm run dev)- Frontend:
http://localhost:5173 - Python Audio Microservice:
http://127.0.0.1:8765
Open http://localhost:5173 in your browser.
If you prefer running services in separate terminals:
Terminal 1 — Python Microservice:
source .venv/bin/activate
python3 shazam_server.pyMicroservice starts on http://127.0.0.1:8765.
Terminal 2 — Vite Frontend Server:
npm run dev:frontendFrontend starts on http://localhost:5173.
To check TypeScript types and build the production bundle:
npm run buildTo run the fast linter:
npm run lintGoogle Cloud provides 10,000 free quota units per day for YouTube Data API v3 per project without requiring billing:
- Visit the Google Cloud Console.
- Create a new project (e.g.,
Synwave-Visualizer). - Navigate to APIs & Services > Library, search for YouTube Data API v3, and click Enable.
- Navigate to APIs & Services > Credentials, click Create Credentials > API key.
- Copy the generated API key (format starts with
AIzaSy...). - Paste the key into Synwave's startup modal or your
.envfile.
- Lightweight Key Validation: Synwave verifies keys via
videoCategories.list, which costs only 1 unit. - Track Video Search: Resolving a song name to its official YouTube video costs 100 units per unique track query (
search.list). - Embed Restrictions: Some official music videos may have third-party embedding disabled by rights holders or may be geo-restricted. If an iframe fails to embed, Synwave maintains full 3D procedural lighting and local audio playback.
- Browser Autoplay Policies: Browsers prevent unmuted audio autoplay. Synwave complies by setting YouTube video volume strictly to 0 and driving audio exclusively through Web Audio API.
| Technology | Role in Synwave | Official Repository / Website |
|---|---|---|
| React 19 | Modern UI components, hooks, reactive state management | facebook/react |
| Three.js (r186) | 3D scene graph, procedural geometry, lighting shaders, WebGL2 | mrdoob/three.js |
| Meta Demucs v4 | Neural music source separation (Hybrid Transformer HTDemucs) | adefossez/demucs |
| PyTorch | Deep learning runtime with Apple Silicon MPS acceleration | pytorch/pytorch |
| ShazamIO | Asynchronous song recognition & acoustic fingerprinting | shazamio/ShazamIO |
| FastAPI | High-performance Python microservice handling AI tasks | fastapi/fastapi |
| Uvicorn | Lightning-fast ASGI web server implementation | encode/uvicorn |
| TypeScript | Type safety, rigorous interfaces, and compile-time correctness | microsoft/TypeScript |
| Vite | Next-generation frontend tooling and HMR dev server | vitejs/vite |
| Lucide Icons | Minimalist modern icon set for controls and navigation | lucide-icons/lucide |
| Web Audio API | Hardware-synchronized audio clock, multi-band FFT analyser | W3C Web Audio API Spec |
| YouTube Data API v3 | Official music video search, thumbnail color palettes, metadata | Google YouTube Data API |
All third-party libraries incorporated into Synwave are free and open-source software. We gratefully acknowledge and credit the original authors and maintainers:
| Library | Version | License | Authors / Maintainers | Repository Link |
|---|---|---|---|---|
react |
^19.2.8 |
MIT | Meta Platforms, Inc. & React Contributors | facebook/react |
react-dom |
^19.2.8 |
MIT | Meta Platforms, Inc. & React Contributors | facebook/react |
three |
^0.186.1 |
MIT | Ricardo Cabello (Mr.doob) & Three.js Authors | mrdoob/three.js |
@types/three |
^0.186.0 |
MIT | DefinitelyTyped Contributors | DefinitelyTyped |
lucide-react |
^1.59.0 |
ISC | Lucide Contributors & Feather Icons Authors | lucide-icons/lucide |
vite |
^8.3.0 |
MIT | Evan You & Vite Contributors | vitejs/vite |
@vitejs/plugin-react |
^6.1.1 |
MIT | Vite Contributors | vite-plugin-react |
typescript |
~6.0.2 |
Apache-2.0 | Microsoft Corporation | microsoft/TypeScript |
oxlint |
^1.81.0 |
MIT | Boshen & Oxc Project Contributors | oxc-project/oxc |
| Package | Version | License | Authors / Maintainers | Repository Link |
|---|---|---|---|---|
demucs |
^4.1.0 |
MIT | Alexandre Défossez (Meta AI Research) | adefossez/demucs |
torch |
^2.2.0 |
BSD-3-Clause | Meta Platforms, Inc. & PyTorch Contributors | pytorch/pytorch |
shazamio |
^0.8.1 |
MIT | DotX12 & ShazamIO Contributors | shazamio/ShazamIO |
fastapi |
^0.115.0 |
MIT | Sebastián Ramírez (tiangolo) | fastapi/fastapi |
uvicorn |
^0.30.0 |
BSD-3-Clause | Encode & Uvicorn Contributors | encode/uvicorn |
numpy |
^1.26.0 |
BSD-3-Clause | Travis Oliphant & NumPy Developers | numpy/numpy |
certifi |
^2024.0.0 |
MPL-2.0 | Kenneth Reitz & Mozilla | certifi/python-certifi |
aiofiles |
^23.2.0 |
Apache-2.0 | Tin Tvrtković & aiofiles Contributors | Tinche/aiofiles |
python-multipart |
^0.0.12 |
Apache-2.0 | Andrew Chen Wang & Kludex | Kludex/python-multipart |
| Asset / File | Title & Description | Creator / Channel | Attribution & Links |
|---|---|---|---|
demo/demo.mp4 |
Destroyer Of Worlds (Oppenheimer Remix) [Music Video] | Abandoned | Official YouTube Channel: @AbandonedOfficial Music composition and official music video rights belong to Abandoned. Used with credit for non-commercial open-source visualization demonstration. |
Here are the currently known bugs and areas under active improvement:
- First-Run Demucs Weights Download Latency:
On the very first track analyzed, Demucs downloads the
htdemucsneural weights (~80MB) from GitHub releases. This may take 20–45 seconds depending on network bandwidth. Subsequent tracks with the same model run much faster, and cached songs load in< 10ms. - YouTube Video Embed Restrictions:
Certain record labels disable third-party iframe embeds for select official music videos on YouTube (resulting in error
150or101). When this occurs, Synwave maintains local audio playback and procedural 3D stage effects while logging a descriptive fallback notice. - Daily YouTube API Quota Ceiling (10,000 units/day): Heavy multi-song testing can consume the daily quota (100 units per new track search). Quotas reset at midnight PST. We plan to add a local metadata search fallback for offline sessions.
- WebGL Context Loss on Display Sleep: On some operating systems, waking a machine from deep sleep or switching external display adapters can trigger a WebGL context loss. Reloading the page restores normal operation.
- Multi-Window High-DPI Canvas Resizing: Dragging the browser window across displays with different device pixel ratios (e.g., Retina Mac to standard 1080p monitor) occasionally requires a canvas refresh.
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project: Click the Fork button on the top right of the Synwave Repository.
- Create your Feature Branch:
git checkout -b feature/AmazingChoreography
- Set Up Development Environment: Follow the Installation & Development Setup guide above.
- Commit your Changes:
git commit -m 'feat: add moving-head gobos to stage lights' - Verify Types and Build:
Make sure
npm run build npm run lint
npm run buildexits with code 0 before submitting. - Push to the Branch:
git push origin feature/AmazingChoreography
- Open a Pull Request: Submit your pull request detailing the changes made, screenshots/recordings of visual modifications, and any testing performed.
- Modularity: Keep 3D visual effects isolated in
src/visualizer/effects/and audio processors insrc/audio/. - Comments & Cleanliness: Add clear comments explaining non-trivial trigonometric sweeps or shader parameters.
- WebGL Hygiene: Always dispose of unused geometries, materials, and textures when destroying or reloading visual effects to avoid GPU memory leaks.
- Security: Never commit real API keys, credentials, or personal audio files to git.
Distributed under the MIT License. See LICENSE for full legal text.
Built with ❤️ for concertgoers, electronic music producers, and 3D visual artists.