Soundy Bits

A real-time audio visualization application built with Rust and Bevy 0.17.2, featuring multiple visualization modes, GPU-accelerated effects, and support for both audio file playback and live microphone input.

Note: This project includes some Raylib proof-of-concept examples in the examples/ directory. The main application uses Bevy for optimal performance and modern rendering.

Features

Visualization Modes

Press M to cycle through visualization modes:

1. Spectrum - Linear audio spectrum with 64 frequency bars (single draw call via Mesh2d)

   • Optional vertical mirroring from center
   • Configurable opacity (0.0-1.0)
   • Frequency boost (0.5-10.0x) for enhanced mid/high visibility

2. Orbit - Audio-reactive orbital system with center hub (single draw call via Mesh2d)

   • Center hub pulses with bass energy
   • 6-24 orbital triangular elements
   • Orbit radius expands with bass (configurable sensitivity 0.0-2.0)
   • Rotation speed driven by mid frequencies (configurable sensitivity 0.0-2.0)
   • Element sizes react to high frequencies
   • Stereo mode: Dual side-by-side orbit systems

3. Waveform - Oscilloscope-style time-domain display

   • Standard: Horizontal waveform (1024 samples)
   • Radial: Circular "shooting out" pattern (512 samples)
   • Configurable scale (0.5-2.0x) for amplitude/radius
   • Stereo mode: Top/bottom split for L/R channels

4. Background - Spiral and galaxy sprite patterns

   • Spiral pattern: 10-100 sprites with configurable speed, tightness, size
   • Galaxy sprites: 5-50 rotating galaxies with 2-6 spiral arms
   • Both respond to bass/mid frequencies with configurable sensitivity
   • Three color modes: Rainbow, Energy Bands, Monochrome

Background Effects (Available in all modes)

Tilemap - Scrolling spectrogram background layer

• Can be enabled in any visualization mode (toggle with 'B' key or background settings panel)
• Scrolling frequency waterfall visualization (bass at bottom, highs at top)
• Simplified controls: 7 essential settings
  • Opacity, Bass/Mid/High sensitivity, Beat flash, Color mode, Scroll speed
• Hardcoded optimal defaults for best visual quality
• Ultra-efficient GPU shader-based rendering

Audio Sources

• File Playback: Load MP3, OGG, WAV, or FLAC files
  • Playlist System: Load multiple files, drag-and-drop to reorder
  • Auto-scroll: Playlist automatically centers the active track when changed
  • Position memory: Window position persisted across sessions
  • Shuffle modes: Off, Fair (all tracks once), Random
  • Repeat modes: Repeat track, Repeat playlist
  • Auto-advance to next track on completion
• Microphone Input: Real-time visualization from default microphone
  • Cross-platform support (Windows/Linux/macOS)

Visual Effects

• Blur: Spatial blur shader (configurable radius 1.0-20.0)
• Glow: Radial glow/bloom effect (radius 0.1-10.0, intensity 1.0-4.0)
• Streak: Vertical energy beam trails (length 10.0-200.0, fade 0.5-0.95)
• Chromatic Aberration: Color separation effect (intensity 0.0-0.5)
• Edge Spectrum: GPU-accelerated spectrum along all window edges
  • Smooth interpolated bars with corner blending
  • Configurable width (50-300 pixels)
  • Three color modes: Rainbow, Energy Bands, Monochrome
• Energy Color: Dynamic hue shifts based on bass/high frequency energy
  • Bass shifts toward red (+120°), high toward blue (-120°)
  • Adjustable intensity (0.0-2.0)
• Stereo Visualization: Dual L/R channel rendering with harmonic color separation
  • Adjustable hue offset (0-60°)

Corner Visualizations

Available in Orbit and Waveform modes. Press C to cycle:

• None: Empty center (default)
• Beat Pulse: Pulsing circle driven by bass energy with color shifts
• Frequency Rings: 3 concentric rings (bass/mid/high)
• Lissajous: Stereo phase plot (when stereo enabled)

Settings Persistence

TOML-based config with three-level system (saves every 2 seconds + on exit):

• Linux: ~/.config/soundy-bits/config.toml
• Windows: %APPDATA%\soundy-bits\config\config.toml
• macOS: ~/Library/Application Support/soundy-bits/config.toml

Three-Level Config System:

1. System Settings ([system] section) - Never included in presets

   • Window settings: VSync, fullscreen state, last resolution
   • Anti-aliasing: MSAA, FXAA, SMAA, CAS settings
   • Music/Playlist: Auto-load, playlist files, current track, repeat/shuffle
   • UI state: Debug info visibility, UI hidden state, playlist window position

2. Global Settings ([global] section) - Included in presets

   • Current visualization mode
   • Visual effects: Blur, glow, streak, chromatic, edge spectrum
   • Stereo settings, energy color, corner visualizations

3. Mode Settings ([spectrum], [orbit], [waveform], [background], [tilemap]) - Included in presets

   • Mode-specific settings (e.g., freq_boost, mirror, orbit_speed)
   • Optional overrides for global settings (e.g., blur_radius, glow_intensity)
   • Enable "Auto-Save Mode Overrides" to save adjustments per mode
   • Example: Spectrum with heavy blur, Orbit with intense glow, Waveform clean

Benefits:

• Presets only contain visual settings (shareable, portable)
• System settings persist across preset loads (music, window state, playlist)
• Each mode can have completely different visual settings

Preset System

• L key - Load preset from file dialog (TOML format)
• P key - Save preset to file dialog (TOML format)
• Store presets anywhere, share with others
• Manual editing supported - TOML format is human-readable

Keyboard Shortcuts

Global:

Key	Action
M	Cycle visualization modes (Spectrum → Orbit → Waveform → Background)
O	Load audio file (MP3, OGG, WAV, FLAC)
I	Toggle microphone input
Space	Play/pause audio
L	Load preset config
P	Save preset config
H	Hide/show UI
F	Toggle fullscreen (cursor auto-hides after 2s of inactivity)
D	Toggle debug info
ESC	Exit application

Playback Controls:

Key	Action
Left Arrow / Media Previous	Previous track (respects shuffle mode)
Right Arrow / Media Next	Next track (respects shuffle mode)
Up Arrow	Increase volume (hold for continuous adjustment)
Down Arrow	Decrease volume (hold for continuous adjustment)
X	Cycle shuffle mode (Off → Fair → Random → Off)

Mode-Specific:

Key	Action	Modes
S	Toggle streak effect	All
E	Toggle edge spectrum	All
R	Toggle mirror mode	Spectrum
W	Toggle radial waveform	Waveform
C	Cycle corner visualizations	Orbit, Waveform
T	Toggle stereo mode	All (when stereo audio available)
B	Toggle background effects	All

Mouse Controls

• Click buttons to toggle modes and effects
• Drag sliders to adjust parameters in real-time
• Playlist:
  • Drag tracks to reorder
  • Drag tracks outside window to remove
  • Click track to play it
  • Click "Add Files" to add more tracks to playlist

Installation

Prerequisites

Install Rust

Download from https://rustup.rs/ and follow the prompts.

Platform-Specific Requirements

Windows:

• Visual Studio Build Tools 2022 with C++ build tools
• Download from Microsoft's website

Linux (Debian/Ubuntu):

sudo apt update
sudo apt install build-essential pkg-config libasound2-dev libudev-dev libwayland-dev

Linux (Arch/Manjaro):

sudo pacman -S base-devel alsa-lib systemd-libs wayland

Runtime Dependencies (Linux): The compiled binary requires:

• libasound2 - ALSA audio library
• libudev1 - Device management
• libwayland-client0 - Wayland display protocol
• libffi8 - Foreign function interface
• Standard system libraries (glibc, libgcc, libm, libcap)

Verify Installation

rustc --version
cargo --version

Usage

Quick Start

# Build and run (optimized)
cargo run --release

# Development
cargo run
cargo build
cargo clean

Using Just (optional task runner)

Install Just from GitHub releases, then:

just           # Build and run optimized
just build     # Maximum optimizations
just clean     # Clean artifacts

Configuration

The application uses a TOML configuration file with mode-specific override support.

See CONFIG.md for complete configuration documentation including:

• TOML structure and mode-specific overrides
• Platform-specific config file locations
• All available settings with ranges and defaults
• Example presets and configurations
• Tips for backup, reset, sharing

License

MIT License - See LICENSE file for details.