{"id":35113732,"url":"https://github.com/pomilon/sonir","last_synced_at":"2026-05-18T20:03:47.186Z","repository":{"id":329820434,"uuid":"1120667083","full_name":"Pomilon/Sonir","owner":"Pomilon","description":"A modular, physics-based audio visualizer engine. Turns music into deterministic 2D geometric worlds using signal processing and AI stem separation.","archived":false,"fork":false,"pushed_at":"2026-02-03T11:08:29.000Z","size":21470,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-04T00:39:35.351Z","etag":null,"topics":["audio-visualizer","creative-coding","demucs","dsp","generative-art","librosa","music-visualization","physics-based","pygame","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Pomilon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-21T17:38:14.000Z","updated_at":"2026-02-03T11:08:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Pomilon/Sonir","commit_stats":null,"previous_names":["pomilon/sonir"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Pomilon/Sonir","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pomilon%2FSonir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pomilon%2FSonir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pomilon%2FSonir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pomilon%2FSonir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Pomilon","download_url":"https://codeload.github.com/Pomilon/Sonir/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pomilon%2FSonir/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33189279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T09:27:30.708Z","status":"ssl_error","status_checked_at":"2026-05-18T09:27:28.300Z","response_time":71,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-visualizer","creative-coding","demucs","dsp","generative-art","librosa","music-visualization","physics-based","pygame","python"],"created_at":"2025-12-27T20:20:10.008Z","updated_at":"2026-05-18T20:03:47.181Z","avatar_url":"https://github.com/Pomilon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sonir\n\nSonir 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.\n\n## Disclaimer\n\n**Sonir is experimental.** While it has been tuned to handle a wide variety of musical genres, please keep the following in mind:\n\n*   **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.\n*   **Physics Constraints:** The \"flight path\" is deterministic. In rare edge cases with extremely rapid onsets, the projectile physics might behave unexpectedly.\n*   **Intended Use:** This is a creative coding project designed for visual art, not a precision-grade rhythm game engine.\n\n\n## Features\n\n- **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.\n- **Multiple Modes**:\n  - **Stem Mode**: Automatic separation of Drums, Bass, Other, Vocals (using Demucs).\n  - **Dynamic Mode**: Hybrid analysis using Harmonic-Percussive Source Separation (HPSS) + Frequency Band Splitting.\n  - **Frequency Modes**: `Dual` (2-band), `Triple` (3-band), and `Quad` (4-band) splitters.\n  - **Genre Specific**: Dedicated modes for `Electronic` (Kick/Top), `Percussion` (Kick/Snare/Hats), `String` (Violin focus), `Piano`, and `LoFi` (Kick/Chill/Vinyl).\n  - **Cinematic**: A 5-viewport center-focus layout.\n  - **Custom**: User-defined frequency bands and colors via JSON config.\n- **High-Quality Visuals**:\n  - **\"Juice\" Effects**: Screen Shake, Impact Particles, Motion Trails, and Neon Glow.\n  - **Dynamic Backgrounds**: Pulsing starfields and reactive environments.\n  - **Cinema Camera**: Dynamic camera movement that leads the action.\n  - **Theming**: 5 built-in color themes (`neon`, `cyberpunk`, `noir`, `sunset`, `matrix`).\n- **Flexible Output**:\n  - **Real-time Preview**: High-performance playback window (configurable resolution) with interactive controls:\n    - `SPACE`: Pause/Resume\n    - `Arrows`: Seek -5s/+5s\n    - `F`: Toggle Fullscreen\n    - `H`: Toggle UI\n    - `R`: Reset Playback\n  - **Video Export**: Drift-free 60FPS MP4 export (H.265/HEVC by default) with customizable Aspect Ratios (`16:9`, `9:16`, `1:1`, etc).\n\n## Gallery\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch3\u003ePiano Sample (Piano Mode)\u003c/h3\u003e\n  \u003cvideo src=\"https://github.com/user-attachments/assets/96d18fc1-8b7b-410f-9b51-fad4c8d5ce9f\" width=\"100%\" controls preload=\"metadata\"\u003e\u003c/video\u003e\n\n  \u003ch3\u003eCrystal Caverns (Stem Mode)\u003c/h3\u003e\n  \u003cvideo src=\"https://github.com/user-attachments/assets/cdd473af-ab06-4710-93ba-5702d62a9a15\" width=\"100%\" controls preload=\"metadata\"\u003e\u003c/video\u003e\n  \n  \u003ch3\u003eCyber Chase (Stem Mode)\u003c/h3\u003e\n  \u003cvideo src=\"https://github.com/user-attachments/assets/8276acdc-4a3e-4bf2-bb45-953abdf393bd\" width=\"100%\" controls preload=\"metadata\"\u003e\u003c/video\u003e\n\u003c/div\u003e\n\n## Installation\n\n1. **Clone the repository:**\n\n```bash\ngit clone https://github.com/Pomilon/Sonir.git\ncd Sonir\n```\n\n2. **Install Python dependencies:**\n\n```bash\npip install -r requirements.txt\n```\n\n3. **System Dependencies:**\n   - **FFmpeg**: Required for the `--export` video generation feature.\n     - Linux: `sudo apt install ffmpeg`\n     - macOS: `brew install ffmpeg`\n     - Windows: Download from [ffmpeg.org](https://ffmpeg.org/download.html) and add to PATH.\n   - **Demucs** (Optional): If you want to use `Stem Mode`, you need pre-separated tracks.\n\n     ```bash\n     pip install demucs\n     ```\n\n## Usage\n\nThe unified entry point is `main.py`.\n\n### 1. Basic Modes\n\n**Piano Mode (Single View)**\n```bash\npython main.py --audio \"piano.mp3\" --mode piano\n```\n\n**Online Stream Support (YouTube/SoundCloud)**\nDirectly visualize audio from a URL. The audio will be downloaded and cached automatically.\n```bash\npython main.py --audio \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\" --mode electronic\n```\n\n**Stem Mode (Source Separation)**\n*Automatically runs Demucs to split the track into 4 stems.*\n```bash\npython main.py --audio \"song.mp3\" --mode stem\n```\n\n**Genre-Specific**\n```bash\n# For Dynamic Analysis (HPSS + Bands)\npython main.py --audio \"song.mp3\" --mode dynamic\n\n# For Electronic/Dance\npython main.py --audio \"edm.mp3\" --mode electronic\n\n# For Drum Covers\npython main.py --audio \"drums.mp3\" --mode percussion\n\n# For Classical/Solo\npython main.py --audio \"concerto.mp3\" --mode string\n```\n\n**Customization (Themes \u0026 Layouts)**\n\n**Vertical Video (TikTok/Shorts) with Cyberpunk Theme**\n```bash\npython main.py --audio \"song.mp3\" --mode cinematic --aspect 9:16 --theme cyberpunk\n```\n\n**Custom Resolution (Overrides Aspect Ratio)**\nSet a fixed window size (e.g., for specific projector or screen setups).\n```bash\npython main.py --audio \"song.mp3\" --mode quad --resolution 1920x1080\n```\n\n**Square Video (Instagram) with Noir Theme**\n```bash\npython main.py --audio \"jazz.mp3\" --mode triple --aspect 1:1 --theme noir\n```\n\n**Background Modes**\nChoose from `stars` (default), `grid` (synthwave), `gradient`, `tunnel`, or `flow`.\n```bash\npython main.py --audio \"song.mp3\" --bg grid --theme cyberpunk\n```\n\n### 3. Custom Configuration\n\nYou can define your own frequency bands and colors using **Custom Mode**. Create a JSON file (e.g., `my_config.json`):\n\n```json\n{\n  \"bands\": [\n    {\n      \"name\": \"deep_bass\",\n      \"low\": 20,\n      \"high\": 100,\n      \"wait\": 2,\n      \"color\": [255, 0, 0]\n    },\n    {\n      \"name\": \"sparkle\",\n      \"low\": 8000,\n      \"high\": 16000,\n      \"wait\": 1,\n      \"color\": [200, 255, 255]\n    }\n  ]\n}\n```\n\nRun with:\n```bash\npython main.py --audio \"song.mp3\" --mode custom --config my_config.json\n```\n\n## Gamification\n\nTurn any visualization into a playable game level with the `--gamify` flag.\n\n### 1. Rhythm Game\nAn interactive version of the physics simulation. Press the key for a viewport exactly when the square hits a wall.\n*   **Controls**: Automatically mapped based on the number of viewports (e.g., `D` / `K`, `Left` / `Right`, or `Space` for single track).\n*   **Features**: Scoring, Combo system, Health bar (with passive drain), and precision hit windows.\n\n```bash\npython main.py --audio \"song.mp3\" --mode dual --gamify rhythm\n```\n\n**Modifiers (`--modifiers`):**\n*   `death`: Sudden Death. One miss or ghost tap ends the game.\n*   `chaos`: Viewports shuffle positions every 5-8 seconds. Keybindings follow the visual location!\n*   `focus`: Forces you to switch attention between tracks periodically.\n\n```bash\n# Ultimate Challenge\npython main.py --audio \"song.mp3\" --mode quad --gamify rhythm --modifiers death chaos\n```\n\n\n### 4. Export to Video\n\nAdd `--export` to render a high-quality MP4. You can customize the encoder (`--encoder`) and quality (`--crf`).\n*Note: If the output filename already exists, Sonir will automatically rename the new file (e.g., `visualizer_1.mp4`) to prevent overwriting.*\n\n```bash\n# Default H.265 Export\npython main.py --audio \"song.mp3\" --mode stem --export --output \"visualizer.mp4\"\n\n# Customize Encoding\npython main.py --audio \"song.mp3\" --mode stem --export --encoder libx264 --crf 18\n```\n\n### 5. Advanced Flags\n\n- `--no-shake`: Disable screen shake.\n- `--no-particles`: Disable impact particles.\n- `--no-trails`: Disable motion trails.\n- `--no-glow`: Disable neon glow.\n- `--no-bg`: Disable dynamic background.\n- `--no-cam`: Disable cinema camera movement.\n- `--no-ui`: Hide the progress bar overlay.\n- `--crt`: Enable CRT/Scanline post-processing effect.\n- `--aberration`: Enable Chromatic Aberration (RGB split).\n- `--noise`: Enable Film Grain/Noise overlay.\n- `--vhs`: Enable full VHS suite (CRT + Aberration + Noise + Vignette).\n\n## Project Structure\n\n- `sonir/core.py`: Deterministic physics engine.\n- `sonir/analyzer.py`: Audio analysis (STFT, Onset Detection).\n- `sonir/renderer.py`: Pygame rendering engine (Real-time \u0026 Headless).\n- `sonir/config.py`: Centralized configuration (Colors, Speed, Resolution).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpomilon%2Fsonir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpomilon%2Fsonir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpomilon%2Fsonir/lists"}