A cutting-edge, GPU-accelerated audio visualizer for Linux with real-time GLSL shader compilation, advanced waveform rendering, and immersive visual effects.
๐ต Features โข ๐ Installation โข โจ๏ธ Controls โข โ Support
- GPU-Accelerated Rendering: Leverages ModernGL for high-performance OpenGL rendering
- Real-time GLSL Shader Compilation: Dynamic shader loading with live error reporting
- Customizable Waveform Rendering: 100+ built-in waveforms across 12 categories
- Dynamic Warp Maps: 3D transformations, distortions, and geometric effects
- Multi-layered Effects: Glow, trails, smoke, pulse, bounce, and kaleidoscope effects
- Advanced Color Palettes: 30+ carefully crafted color schemes with smooth transitions
- Spectrogram Overlay: Spectral analysis for an added visual element**
- Real-time Audio Analysis: Advanced FFT processing with beat detection
- Multiple Audio Sources: System audio capture with device selection
- Adaptive Sensitivity: Dynamic beat detection with configurable thresholds
- Audio-reactive Parameters: All visual effects respond to audio characteristics
- Live Shader Editor: Built-in GLSL editor with syntax highlighting and error reporting
- Waveform Editor: Create and modify custom waveforms with live preview
- Warp Map Editor: Design complex 3D transformations and distortion effects with live preview
- Preset System: Save and load complete visualization configurations
- Performance Monitoring: Real-time FPS and performance statistics
- Intuitive Controls: Comprehensive keyboard shortcuts for most features
- GUI Configuration: Modern Qt-based settings interface
- Fullscreen Support: Multiple monitor support with resolution selection
- Anti-aliasing: FXAA post-processing for smooth visuals
- Mouse Interaction: Optional mouse-reactive effects
- Linux Operating System (Ubuntu/Debian/Arch/Fedora recommended)
- Python 3.8+ (3.9+ recommended)
- OpenGL 3.3+ compatible graphics card
- Audio system (ALSA/PulseAudio/JACK)
- Git for cloning the repository
Step 1: Clone and Setup Virtual Environment
# Clone the repository
git clone https://github.com/KarmaTripping/karmaviz.git
cd karmaviz
# Create virtual environment
python3 -m venv karmaviz-env
# Activate virtual environment
source karmaviz-env/bin/activate
Step 2: Install Dependencies
# Upgrade pip to latest version
pip install --upgrade pip
# Install Python dependencies
pip install -r requirements.txt
# Install Cython for performance optimizations
pip install Cython
Step 3: Build Cython Extensions
# Build optimized Cython extensions for better performance
python setup.py build_ext --inplace
# Verify Cython compilation
python -c "import modules.color_ops; print('Cython extensions loaded successfully!')"
Step 4: Run KarmaViz
# Launch KarmaViz
python main.py
# For debug mode with verbose logging
python main.py --debug
# Clone the repository
git clone https://github.com/karmatripping/karmaviz
cd karmaviz
# Install in development mode (recommended for contributors)
pip install -e .
# OR install normally
pip install .
# Build Cython extensions
python setup.py build_ext --inplace
# Run KarmaViz
python main.py
# Clone the repository
git clone https://github.com/KarmaTripping/karmaviz.git
cd karmaviz
# Install dependencies directly
pip install -r requirements.txt
# Build Cython extensions (optional, for better performance)
python setup.py build_ext --inplace
# Run KarmaViz
python main.py
Core Requirements:
pygame
- Window management and input handlingmoderngl
- OpenGL renderingnumpy
- Numerical computationsPyQt5
- GUI interfacesounddevice
- Audio capturescipy
- Audio processing
Optional (for better performance):
Cython
- Compiled color operations
Cython compilation fails:
# Install build tools
sudo apt install build-essential python3-dev # Ubuntu/Debian
sudo pacman -S base-devel python-devel # Arch Linux
sudo dnf install gcc gcc-c++ python3-devel # Fedora
# Reinstall Cython
pip uninstall Cython
pip install Cython
python setup.py build_ext --inplace
Audio dependencies missing:
# Ubuntu/Debian
sudo apt install portaudio19-dev libasound2-dev pulseaudio-dev
# Arch Linux
sudo pacman -S portaudio alsa-lib pulseaudio
# Fedora
sudo dnf install portaudio-devel alsa-lib-devel pulseaudio-libs-devel
Qt5 installation issues:
# If PyQt5 installation fails, try system package
sudo apt install python3-pyqt5 python3-pyqt5.qtopengl # Ubuntu/Debian
sudo pacman -S python-pyqt5 # Arch Linux
sudo dnf install python3-qt5 # Fedora
# Or install via pip with specific version
pip install PyQt5==5.15.7
Virtual environment activation:
# If activation fails, ensure venv module is installed
sudo apt install python3-venv # Ubuntu/Debian
# Create virtual environment with specific Python version
python3.9 -m venv karmaviz-env # Use specific Python version
Ubuntu/Debian:
# Update package list
sudo apt update
# Install system dependencies
sudo apt install python3-dev python3-pip python3-venv
sudo apt install portaudio19-dev libasound2-dev
sudo apt install libgl1-mesa-dev libglu1-mesa-dev
sudo apt install build-essential
# For Qt5 GUI support
sudo apt install python3-pyqt5 python3-pyqt5.qtopengl
# Clone and setup KarmaViz
git clone https://github.com/karmatripping/karmaviz
cd karmaviz
python3 -m venv karmaviz-env
source karmaviz-env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
python setup.py build_ext --inplace
Arch Linux:
# Install system dependencies
sudo pacman -S python python-pip python-virtualenv
sudo pacman -S portaudio mesa base-devel
sudo pacman -S python-pyqt5
# Clone and setup KarmaViz
git clone https://github.com/KarmaTripping/karmaviz.git
cd karmaviz
python -m venv karmaviz-env
source karmaviz-env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
python setup.py build_ext --inplace
Fedora/RHEL/CentOS:
# Install system dependencies
sudo dnf install python3-devel python3-pip python3-virtualenv
sudo dnf install portaudio-devel alsa-lib-devel
sudo dnf install mesa-libGL-devel mesa-libGLU-devel
sudo dnf install gcc gcc-c++ make
# For Qt5 GUI support
sudo dnf install python3-qt5
# Clone and setup KarmaViz
git clone https://github.com/KarmaTripping/karmaviz.git
cd karmaviz
python3 -m venv karmaviz-env
source karmaviz-env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
python setup.py build_ext --inplace
KarmaViz can capture audio from your microphone by default, but to visualize system audio (music, videos, etc.), you need to set up audio loopback.
Run the audio setup helper:
python setup_system_audio.py
Option 1: Enable Monitor Sources
- Install
pavucontrol
:sudo apt install pavucontrol
- Open PulseAudio Volume Control
- Go to "Recording" tab
- Show "Monitor" sources from the dropdown
- Set KarmaViz to record from your output device's monitor
Option 2: Create Loopback
# Create a loopback device
pactl load-module module-loopback latency_msec=1
# List available sources
pactl list sources short
Option 3: Using ALSA Loopback
# Load ALSA loopback module
sudo modprobe snd-aloop
# Configure ALSA to use loopback
echo "pcm.!default { type plug slave.pcm \"hw:Loopback,0,0\" }" >> ~/.asoundrc
No audio devices detected:
- Check if PulseAudio is running:
pulseaudio --check -v
- Restart PulseAudio:
pulseaudio -k && pulseaudio --start
- Install audio development packages:
sudo apt install pulseaudio-dev portaudio19-dev
Audio capture not working:
- Verify device permissions: Add user to
audio
group - Check device availability:
python -c "import sounddevice; print(sounddevice.query_devices())"
- Try different audio devices from the list shown at startup
Taskbar icon not showing:
- Ensure proper desktop environment integration
- Try running with:
SDL_VIDEO_X11_WMCLASS=KarmaViz python main.py
- Check if window manager supports system tray icons
KarmaViz can capture audio from your microphone by default, but to visualize system audio (music, videos, etc.), you need to set up audio loopback.
Run the audio setup helper:
python setup_system_audio.py
Option 1: Enable Monitor Sources
- Install
pavucontrol
:sudo apt install pavucontrol
- Open PulseAudio Volume Control
- Go to "Recording" tab
- Show "Monitor" sources from the dropdown
- Set KarmaViz to record from your output device's monitor
Option 2: Create Loopback
# Create a loopback device
pactl load-module module-loopback latency_msec=1
# List available sources
pactl list sources short
Option 3: Using ALSA Loopback
# Load ALSA loopback module
sudo modprobe snd-aloop
# Configure ALSA to use loopback
echo "pcm.!default { type plug slave.pcm \"hw:Loopback,0,0\" }" >> ~/.asoundrc
No audio devices detected:
- Check if PulseAudio is running:
pulseaudio --check -v
- Restart PulseAudio:
pulseaudio -k && pulseaudio --start
- Install audio development packages:
sudo apt install pulseaudio-dev portaudio19-dev
Audio capture not working:
- Verify device permissions: Add user to
audio
group - Check device availability:
python -c "import sounddevice; print(sounddevice.query_devices())"
- Try different audio devices from the list shown at startup
Taskbar icon not showing:
- Ensure proper desktop environment integration
- Try running with:
SDL_VIDEO_X11_WMCLASS=KarmaViz python main.py
- Check if window manager supports system tray icons
Key | Action |
---|---|
Q |
Quit application |
TAB |
Toggle configuration menu |
F11 |
Toggle fullscreen |
P |
Toggle pulse effect |
Numpad 5 |
Toggle bounce effect |
I |
Toggle mouse interaction |
S |
Toggle spectrogram overlay |
W |
Cycle GPU waveforms |
R |
Cycle rotation modes |
M |
Cycle symmetry modes |
K |
Toggle kaleidoscope effect |
L |
Toggle warp-first rendering |
Key | Action |
---|---|
T / Shift+T |
Increase/Decrease trail intensity |
G / Shift+G |
Increase/Decrease glow intensity |
F / Shift+F |
Increase/Decrease smoke intensity |
[ / ] |
Decrease/Increase pulse intensity |
โ / โ |
Increase/Decrease waveform scale |
Shift+โ / Shift+โ |
Increase/Decrease glow radius |
Key | Action |
---|---|
Numpad + / Numpad - |
Increase/Decrease animation speed |
Numpad * / Numpad / |
Increase/Decrease audio speed boost |
Numpad 3 / Numpad 1 |
Increase/Decrease palette speed |
Numpad 6 / Numpad 4 |
Increase/Decrease color cycle speed |
Key | Action |
---|---|
. / , |
Increase/Decrease beats per change |
Numpad 9 / Numpad 7 |
Increase/Decrease beat sensitivity |
Numpad 8 / Numpad 2 |
Increase/Decrease bounce intensity |
/ |
Toggle automatic transitions |
Key | Action |
---|---|
Space |
Manual warp map change |
Backspace |
Clear current warp map |
Key | Action |
---|---|
0-9 |
Load quick preset slot (0-9) |
Ctrl+0-9 |
Save current settings to quick preset slot |
Key | Action |
---|---|
F1 |
Print performance statistics |
F2 |
Clear performance statistics |
F3 |
Toggle performance monitoring |
F4 |
Show shader compilation status |
KarmaViz includes 100+ professionally crafted waveforms organized into categories:
- ๐ Basic - Classic waveform patterns
- ๐ฌ Advanced - Complex mathematical visualizations
- ๐ Cosmic - Space-inspired ethereal effects
- ๐ป Digital - Cyberpunk and tech aesthetics
- ๐งช Experimental - Cutting-edge visual experiments
- ๐ Fractal - Self-similar recursive patterns
- ๐ Futuristic - Sci-fi inspired designs
- ๐ก Lighting - Dynamic illumination effects
- ๐ Mathematical - Geometric and algebraic forms
- ๐ Motion - Kinetic and flow-based patterns
- ๐ฟ Natural - Organic and nature-inspired forms
- ๐ฑ Organic - Fluid, life-like movements
- ๐ผ Retro - Vintage and nostalgic styles
Transform your visualizations with 50+ warp maps:
- ๐ฏ Basic - Fundamental transformations
- ๐ Cosmic - Galactic distortions and stellar effects
- ๐ป Digital - Matrix-style and digital glitch effects
- ๐ Distortion - Wave and ripple transformations
- ๐งช Experimental - Avant-garde visual experiments
- ๐ Fractal - Recursive geometric patterns
- ๐ Futuristic - Advanced sci-fi transformations
- ๐ Geometric - Mathematical shape manipulations
- ๐ข Mathematical - Algorithm-based distortions
- ๐ Motion - Dynamic movement effects
- ๐ฟ Organic - Natural flow transformations
- ๐ผ Retro - Classic visual effects
- ๐ญ 3D Transformations - Dimensional manipulations
Choose from 30+ stunning color palettes or create your own using our intuitive editor:
- ๐ Rainbow - Full spectrum gradients
- ๐ Ocean Themes - Deep blues and aqua tones
- ๐ฅ Fire & Energy - Warm reds, oranges, and yellows
- ๐ธ Pastel Dreams - Soft, dreamy color combinations
- ๐ Night Sky - Dark blues with stellar accents
- ๐ Nature - Earth tones and forest greens
- ๐ Precious Metals - Gold, silver, and copper
- ๐บ Floral - Vibrant flower-inspired palettes
- ๐ญ Neon - Electric and cyberpunk colors
- ๐๏ธ Arctic - Cool blues and icy whites
- Real-time GLSL compilation
- Syntax highlighting with error detection
- Live preview with automatic updates
- Template system for quick starts
- Error reporting with line numbers
- Visual waveform design interface
- Mathematical function support
- Live audio-reactive preview
- Category organization system
- Export/import functionality
- 3D transformation designer
- Real-time distortion preview
- Mathematical expression support
- Complex effect layering
- Performance optimization tools
- Complete state saving/loading
- Quick-access slot system (0-9)
- Automatic shader compilation
- Configuration export/import
- Backup and restore functionality
- Resolution: ALl monitor supported resolutions.
- FPS: 20-120
- Anti-aliasing: FXAA post-processing
- Multi-monitor: Primary/secondary display selection
- Input Device: Uses system default output, or select alternate input in audio settings
- Sample Rate: 44.1kHz, 48kHz, 96kHz
- Buffer Size: Configurable for latency optimization
- Beat Detection: Sensitivity and threshold adjustment
- Effect Intensities: Individual control for all effects
- Color Management: Palette speed and transition settings
- Animation Speed: Global and per-preset timing
- Quality Settings: Performance vs. visual quality balance
KarmaViz is optimized for high performance:
- GPU Acceleration: All rendering on graphics card
- Threaded Compilation: Background shader processing
- Cython Extensions: Optimized color operations
- Memory Management: Efficient buffer handling
Recommended Specs:
- CPU: Intel i5-8400 / AMD Ryzen 5 2600 or better
- GPU: GTX 1060 / RX 580 or better (OpenGL 3.3+) with 2GB+ Graphics Memory
- Graphics Drivers: Latest stable releases
- RAM: 8GB+ (16GB recommended)
- Storage: SSD recommended for shader loading
- OS: Linux (Ubuntu/Debian recommended)
Audio not working:
# Linux: Check audio devices
python -c "import sounddevice; print(sounddevice.query_devices())"
# Install additional audio libraries if needed
sudo apt install pulseaudio-dev portaudio19-dev
OpenGL errors:
# Update graphics drivers
# Linux: Install mesa-utils
sudo apt install mesa-utils
glxinfo | grep "OpenGL version"
Performance issues:
- Lower FPS limit in settings
- Disable anti-aliasing
- Reduce effect intensities
- Close other GPU-intensive applications
Shader compilation errors:
- Check GPU OpenGL version (3.3+ required)
- Update graphics drivers
- Try different waveforms/warp maps
KarmaViz welcomes contributions! Here's how you can help:
- Design new waveforms (GLSL)
- Create warp map effects
- Develop color palettes
- Share preset configurations
- Bug reports with system information
- Performance optimization suggestions
- Feature requests and ideas
- Documentation improvements
- Performance optimizations
- New visual effects
- Audio processing improvements
- Cross-platform compatibility
Development Setup:
git clone https://github.com/yourusername/karmaviz.git
cd karmaviz
pip install -e .
python -m pytest tests/ # Run tests
KarmaViz represents hundreds of hours of passionate development work!
This project features:
- ๐จ 100+ hand-crafted waveforms with mathematical precision
- ๐บ๏ธ 50+ custom warp maps for stunning 3D effects
- ๐ต Advanced audio processing with real-time beat detection
- ๐ ๏ธ Professional editing tools with live preview capabilities
- โก GPU-optimized rendering for smooth 60+ FPS performance
- ๐ฎ Intuitive controls with comprehensive keyboard shortcuts
- ๐จ 30+ color palettes designed by a visual artist
- ๐ Live shader compilation with error reporting
- ๐พ Complete preset system for saving your creations
If KarmaViz has enhanced your music experience or inspired your creativity, consider supporting its continued development:
Your support helps:
- ๐ Accelerate development of new features
- ๐จ Create more visual content (waveforms, effects, palettes)
- ๐ Maintain and improve existing functionality
- ๐ Expand documentation and tutorials
- ๐ Support the open-source community
- โญ Star this repository to show your appreciation
- ๐ Report bugs and suggest improvements
- ๐จ Share your creations and presets with the community
- ๐ข Spread the word about KarmaViz to fellow music lovers
- ๐ป Contribute code or documentation improvements
Special thanks to:
- The ModernGL community for excellent OpenGL bindings
- PyQt5 developers for the robust GUI framework
- NumPy/SciPy teams for powerful numerical computing
- Pygame community for multimedia support
- All beta testers and contributors who helped shape KarmaViz
- ๐ Issues & Bugs: GitHub Issues all -e . python -m pytest tests/ # Run tests
---
## ๐ License
KarmaViz is licensed for **Personal Use Only**.
### โ
**Permitted Uses**
- Personal entertainment and visualization
- Educational purposes and learning
- Personal creative projects
- Private demonstrations
### โ **Prohibited Uses**
- Commercial performances or events
- Public performances or exhibitions
- Distribution of modified versions
- Any revenue-generating activities
For commercial licensing, please contact: **[email protected]**
See [LICENSE.md](LICENSE.md) for complete terms.
---
## โ Support the Project
**KarmaViz represents hundreds of hours of passionate development work!**
This project features:
- ๐จ **100+ hand-crafted waveforms** with mathematical precision
- ๐บ๏ธ **50+ custom warp maps** for stunning 3D effects
- ๐ต **Advanced audio processing** with real-time beat detection
- ๐ ๏ธ **Professional editing tools** with live preview capabilities
- โก **GPU-optimized rendering** for smooth 60+ FPS performance
- ๐ฎ **Intuitive controls** with comprehensive keyboard shortcuts
- ๐จ **30+ color palettes** designed by a visual artist
- ๐ **Live shader compilation** with error reporting
- ๐พ **Complete preset system** for saving your creations
### ๐ **Show Your Appreciation**
If KarmaViz has enhanced your music experience or inspired your creativity, consider supporting its continued development:
<div align="center">
[](https://buymeacoffee.com/karmaviz)
**[โ Buy me a coffee](https://buymeacoffee.com/karmaviz)**
</div>
Your support helps:
- ๐ **Accelerate development** of new features
- ๐จ **Create more visual content** (waveforms, effects, palettes)
- ๐ **Maintain and improve** existing functionality
- ๐ **Expand documentation** and tutorials
- ๐ **Support the open-source community**
### ๐ **Other Ways to Support**
- โญ **Star this repository** to show your appreciation
- ๐ **Report bugs** and suggest improvements
- ๐จ **Share your creations** and presets with the community
- ๐ข **Spread the word** about KarmaViz to fellow music lovers
- ๐ป **Contribute code** or documentation improvements
---
## ๐ Acknowledgments
**Special thanks to:**
- The **ModernGL** community for excellent OpenGL bindings
- **PyQt5** developers for the robust GUI framework
- **NumPy/SciPy** teams for powerful numerical computing
- **Pygame** community for multimedia support
- All **beta testers** and **contributors** who helped shape KarmaViz
---
## ๐ Contact
- **๐ Issues & Bugs**: [GitHub Issues](https://github.com/KarmaTripping/KarmaViz/issues)
welcomes contributions! Here's how you can help:
### ๐จ **Create Content**
- Design new waveforms (GLSL)
- Create warp map effects
- Develop color palettes
- Share preset configurations
### ๐ **Report Issues**
- Bug reports with system information
- Performance optimization suggestions
- Feature requests and ideas
- Documentation improvements
### ๐ป **Code Contributions**
- Performance optimizations
- New visual effects
- Audio processing improvements
- Cross-platform compatibility
**Development Setup:**
```bash
git clone https://github.com/yourusername/karmaviz.git
cd karmaviz
pip install -e .
python -m pytest tests/ # Run tests
KarmaViz is licensed for Personal Use Only.
- Personal entertainment and visualization
- Educational purposes and learning
- Personal creative projects
- Private demonstrations
- Commercial performances or events
- Public performances or exhibitions
- Distribution of modified versions
- Any revenue-generating activities
For commercial licensing, please contact: [email protected]
See LICENSE.md for complete terms.
KarmaViz represents hundreds of hours of passionate development work!
This project features:
- ๐จ 100+ hand-crafted waveforms with mathematical precision
- ๐บ๏ธ 50+ custom warp maps for stunning 3D effects
- ๐ต Advanced audio processing with real-time beat detection
- ๐ ๏ธ Professional editing tools with live preview capabilities
- โก GPU-optimized rendering for smooth 60+ FPS performance
- ๐ฎ Intuitive controls with comprehensive keyboard shortcuts
- ๐จ 30+ color palettes designed by a visual artist
- ๐ Live shader compilation with error reporting
- ๐พ Complete preset system for saving your creations
If KarmaViz has enhanced your music experience or inspired your creativity, consider supporting its continued development:
Your support helps:
- ๐ Accelerate development of new features
- ๐จ Create more visual content (waveforms, effects, palettes)
- ๐ Maintain and improve existing functionality
- ๐ Expand documentation and tutorials
- ๐ Support the open-source community
- โญ Star this repository to show your appreciation
- ๐ Report bugs and suggest improvements
- ๐จ Share your creations and presets with the community
- ๐ข Spread the word about KarmaViz to fellow music lovers
- ๐ป Contribute code or documentation improvements
Special thanks to:
- The ModernGL community for excellent OpenGL bindings
- PyQt5 developers for the robust GUI framework
- NumPy/SciPy teams for powerful numerical computing
- Pygame community for multimedia support
- All beta testers and contributors who helped shape KarmaViz
- ๐ Issues & Bugs: GitHub Issues
- ๐ผ Commercial Licensing: [email protected]
- โ Support Development: Buy Me A Coffee
- ๐ฌ Feedback and Suggestions: [email protected]