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.

Sonir is an original software project created and maintained by Pomilon.

It has come to my attention that automated accounts (such as yobo1889) are scraping this code and re-uploading it as their own repositories, bypassing GitHub's official fork feature. These unauthorized mirrors:

• Misrepresent ownership of the original source code.
• Often contain outdated or broken versions of the engine.
• Are not authorized to redistribute this work without proper attribution.

If you are viewing this on any profile other than Pomilon, you are looking at an unauthorized mirror. Please always refer to the official Sonir repository for the latest updates, features, and security patches.

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.

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

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

The unified entry point is main.py.

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

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

Turn any visualization into a playable game level with the --gamify flag.

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

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

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

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