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)

piano_sample.mp4

Crystal Caverns (Stem Mode)

crystal_caverns.mp4

Cyber Chase (Stem Mode)

cyber_chase.mp4

Installation

1. Clone the repository:

git clone https://github.com/Pomilon/Sonir.git
cd Sonir

2. Install Python dependencies:

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 and add to PATH.

   • Demucs (Optional): If you want to use Stem Mode, you need pre-separated tracks.

     pip install demucs

Usage

The unified entry point is main.py.

1. Basic Modes

Piano Mode (Single View)

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.

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.

python main.py --audio "song.mp3" --mode stem

Genre-Specific

# 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

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).

python main.py --audio "song.mp3" --mode quad --resolution 1920x1080

Square Video (Instagram) with Noir Theme

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.

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):

{
  "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:

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.

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.

# 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.

# 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).