https://github.com/pomilon/sonir
A modular, physics-based audio visualizer engine. Turns music into deterministic 2D geometric worlds using signal processing and AI stem separation.
https://github.com/pomilon/sonir
audio-visualizer creative-coding demucs dsp generative-art librosa music-visualization physics-based pygame python
Last synced: about 1 month ago
JSON representation
A modular, physics-based audio visualizer engine. Turns music into deterministic 2D geometric worlds using signal processing and AI stem separation.
- Host: GitHub
- URL: https://github.com/pomilon/sonir
- Owner: Pomilon
- License: mit
- Created: 2025-12-21T17:38:14.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-02-03T11:08:29.000Z (5 months ago)
- Last Synced: 2026-02-04T00:39:35.351Z (5 months ago)
- Topics: audio-visualizer, creative-coding, demucs, dsp, generative-art, librosa, music-visualization, physics-based, pygame, python
- Language: Python
- Homepage:
- Size: 20.5 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Sonir
Sonir is a modular, physics-based audio visualizer engine written in Python. It turns audio tracks into dynamic 2D geometric worlds where a projectile travels at constant speed, bouncing off walls generated by musical onsets.
## Disclaimer
**Sonir is experimental.** While it has been tuned to handle a wide variety of musical genres, please keep the following in mind:
* **Not Universal:** It may not perfectly sync with every single track. Songs with extremely complex polyrhythms, low dynamic range, or muddy mixes may result in less accurate wall generation.
* **Physics Constraints:** The "flight path" is deterministic. In rare edge cases with extremely rapid onsets, the projectile physics might behave unexpectedly.
* **Intended Use:** This is a creative coding project designed for visual art, not a precision-grade rhythm game engine.
## Features
- **Physics-Based Visualization**: A deterministic engine that maps musical timing (onsets) to a 2D flight path. Now includes file-hash based seeding for 100% reproducible layouts.
- **Multiple Modes**:
- **Stem Mode**: Automatic separation of Drums, Bass, Other, Vocals (using Demucs).
- **Dynamic Mode**: Hybrid analysis using Harmonic-Percussive Source Separation (HPSS) + Frequency Band Splitting.
- **Frequency Modes**: `Dual` (2-band), `Triple` (3-band), and `Quad` (4-band) splitters.
- **Genre Specific**: Dedicated modes for `Electronic` (Kick/Top), `Percussion` (Kick/Snare/Hats), `String` (Violin focus), `Piano`, and `LoFi` (Kick/Chill/Vinyl).
- **Cinematic**: A 5-viewport center-focus layout.
- **Custom**: User-defined frequency bands and colors via JSON config.
- **High-Quality Visuals**:
- **"Juice" Effects**: Screen Shake, Impact Particles, Motion Trails, and Neon Glow.
- **Dynamic Backgrounds**: Pulsing starfields and reactive environments.
- **Cinema Camera**: Dynamic camera movement that leads the action.
- **Theming**: 5 built-in color themes (`neon`, `cyberpunk`, `noir`, `sunset`, `matrix`).
- **Flexible Output**:
- **Real-time Preview**: High-performance playback window (configurable resolution) with interactive controls:
- `SPACE`: Pause/Resume
- `Arrows`: Seek -5s/+5s
- `F`: Toggle Fullscreen
- `H`: Toggle UI
- `R`: Reset Playback
- **Video Export**: Drift-free 60FPS MP4 export (H.265/HEVC by default) with customizable Aspect Ratios (`16:9`, `9:16`, `1:1`, etc).
## Gallery
Piano Sample (Piano Mode)
Crystal Caverns (Stem Mode)
Cyber Chase (Stem Mode)
## Installation
1. **Clone the repository:**
```bash
git clone https://github.com/Pomilon/Sonir.git
cd Sonir
```
2. **Install Python dependencies:**
```bash
pip install -r requirements.txt
```
3. **System Dependencies:**
- **FFmpeg**: Required for the `--export` video generation feature.
- Linux: `sudo apt install ffmpeg`
- macOS: `brew install ffmpeg`
- Windows: Download from [ffmpeg.org](https://ffmpeg.org/download.html) and add to PATH.
- **Demucs** (Optional): If you want to use `Stem Mode`, you need pre-separated tracks.
```bash
pip install demucs
```
## Usage
The unified entry point is `main.py`.
### 1. Basic Modes
**Piano Mode (Single View)**
```bash
python main.py --audio "piano.mp3" --mode piano
```
**Online Stream Support (YouTube/SoundCloud)**
Directly visualize audio from a URL. The audio will be downloaded and cached automatically.
```bash
python main.py --audio "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --mode electronic
```
**Stem Mode (Source Separation)**
*Automatically runs Demucs to split the track into 4 stems.*
```bash
python main.py --audio "song.mp3" --mode stem
```
**Genre-Specific**
```bash
# For Dynamic Analysis (HPSS + Bands)
python main.py --audio "song.mp3" --mode dynamic
# For Electronic/Dance
python main.py --audio "edm.mp3" --mode electronic
# For Drum Covers
python main.py --audio "drums.mp3" --mode percussion
# For Classical/Solo
python main.py --audio "concerto.mp3" --mode string
```
**Customization (Themes & Layouts)**
**Vertical Video (TikTok/Shorts) with Cyberpunk Theme**
```bash
python main.py --audio "song.mp3" --mode cinematic --aspect 9:16 --theme cyberpunk
```
**Custom Resolution (Overrides Aspect Ratio)**
Set a fixed window size (e.g., for specific projector or screen setups).
```bash
python main.py --audio "song.mp3" --mode quad --resolution 1920x1080
```
**Square Video (Instagram) with Noir Theme**
```bash
python main.py --audio "jazz.mp3" --mode triple --aspect 1:1 --theme noir
```
**Background Modes**
Choose from `stars` (default), `grid` (synthwave), `gradient`, `tunnel`, or `flow`.
```bash
python main.py --audio "song.mp3" --bg grid --theme cyberpunk
```
### 3. Custom Configuration
You can define your own frequency bands and colors using **Custom Mode**. Create a JSON file (e.g., `my_config.json`):
```json
{
"bands": [
{
"name": "deep_bass",
"low": 20,
"high": 100,
"wait": 2,
"color": [255, 0, 0]
},
{
"name": "sparkle",
"low": 8000,
"high": 16000,
"wait": 1,
"color": [200, 255, 255]
}
]
}
```
Run with:
```bash
python main.py --audio "song.mp3" --mode custom --config my_config.json
```
## Gamification
Turn any visualization into a playable game level with the `--gamify` flag.
### 1. Rhythm Game
An interactive version of the physics simulation. Press the key for a viewport exactly when the square hits a wall.
* **Controls**: Automatically mapped based on the number of viewports (e.g., `D` / `K`, `Left` / `Right`, or `Space` for single track).
* **Features**: Scoring, Combo system, Health bar (with passive drain), and precision hit windows.
```bash
python main.py --audio "song.mp3" --mode dual --gamify rhythm
```
**Modifiers (`--modifiers`):**
* `death`: Sudden Death. One miss or ghost tap ends the game.
* `chaos`: Viewports shuffle positions every 5-8 seconds. Keybindings follow the visual location!
* `focus`: Forces you to switch attention between tracks periodically.
```bash
# Ultimate Challenge
python main.py --audio "song.mp3" --mode quad --gamify rhythm --modifiers death chaos
```
### 4. Export to Video
Add `--export` to render a high-quality MP4. You can customize the encoder (`--encoder`) and quality (`--crf`).
*Note: If the output filename already exists, Sonir will automatically rename the new file (e.g., `visualizer_1.mp4`) to prevent overwriting.*
```bash
# Default H.265 Export
python main.py --audio "song.mp3" --mode stem --export --output "visualizer.mp4"
# Customize Encoding
python main.py --audio "song.mp3" --mode stem --export --encoder libx264 --crf 18
```
### 5. Advanced Flags
- `--no-shake`: Disable screen shake.
- `--no-particles`: Disable impact particles.
- `--no-trails`: Disable motion trails.
- `--no-glow`: Disable neon glow.
- `--no-bg`: Disable dynamic background.
- `--no-cam`: Disable cinema camera movement.
- `--no-ui`: Hide the progress bar overlay.
- `--crt`: Enable CRT/Scanline post-processing effect.
- `--aberration`: Enable Chromatic Aberration (RGB split).
- `--noise`: Enable Film Grain/Noise overlay.
- `--vhs`: Enable full VHS suite (CRT + Aberration + Noise + Vignette).
## Project Structure
- `sonir/core.py`: Deterministic physics engine.
- `sonir/analyzer.py`: Audio analysis (STFT, Onset Detection).
- `sonir/renderer.py`: Pygame rendering engine (Real-time & Headless).
- `sonir/config.py`: Centralized configuration (Colors, Speed, Resolution).