A music-reactive beamer lightshow application with 50+ visual effects built with Python. Transform your music into stunning visualizations with audio analysis and beat detection.
- Add a MP3 to your playlist
- Generate (a lot of) stage smoke
- Point your beamer / projector in the direction of your audience
- Start the animation
- Enjoy! 🙋♀️🙌🙋🙌🙋♂️
Effect preview on YouTube
-
50+ Visual Effects: Wide variety of music-reactive effects including:
- Scanners & Lasers (horizontal/vertical scans, rotating dots, laser planets)
- Tunnels (circle, hex, rectangular, star tunnels)
- Particles (fireflies, pixel rain, plasma field, wild shot)
- Geometric Patterns (kaleidoscope, frequency mandala, breathing grid)
- Dynamic Effects (electric arc, orbiting satellites, corner burst)
-
Buffered Audio Analysis:
- Beat detection and tracking
- Frequency band separation (bass, mids, highs)
- Onset strength analysis
- Energy-based effect modulation
-
Customizable Controls:
- Brightness adjustment
- Sensitivity control
- Flash threshold
- Effect rotation interval
- Individual effect selection/deselection
- Weights that influence effect use probability
- Multi-effect layering (1-5 simultaneous effects)
-
Effect Classification System: Prevents similar effects from playing together for better visual variety
Download the standalone EXE installer from the GitHub Releases page. No Python installation required!
# Install from PyPI
pip install openlightshow
# Run the application
openlightshowFor developers who want to modify the source code:
# Clone the repository
git clone https://github.com/digidigital/openlightshow.git
cd openlightshow
# Create virtual environment (recommended)
python -m venv venv
# Activate virtual environment
# On Linux/Mac:
source venv/bin/activate
# On Windows:
venv\Scripts\activate
# Install in development mode
pip install -e .
# Or install with development dependencies
pip install -e .[dev]
# Alternative: Install from requirements.txt
pip install -r requirements.txt
# For development with all tools
pip install -r requirements-dev.txt- Windows: Use the EXE installer (no prerequisites needed)
- Linux/Mac/Python install: Python 3.10 or higher
- FFmpeg (optional): For broader audio format support
Ubuntu/Debian:
sudo apt-get update
sudo apt-get install ffmpeg libsndfile1macOS:
brew install ffmpeg libsndfileWindows: Download FFmpeg from ffmpeg.org and add it to your PATH.
Note: Modern versions of librosa use
soundfileas the primary audio backend, which includes MP3 support via libsndfile 1.1.0+. FFmpeg is only needed for legacy format support or if you experience compatibility issues.
After installation, you can run the application in several ways:
Using the command-line script:
openlightshowUsing Python module syntax:
python -m openlightshowOr if running from source without installation:
cd /path/to/openlightshow
python -m openlightshow- Load a Track: Click "Add MP3" and select an audio file.
- Select Effects: Choose which effects to enable from the effects list
- Adjust Settings:
- Brightness: Control overall effect intensity (10-200%)
- Sensitivity: How responsive effects are to music (0-100%)
- Flash Threshold: Beat detection sensitivity (0-100%)
- Max Active: Number of simultaneous effects (1-5)
- Rotation Interval: How often effects change (1-30 seconds)
- Play: Click the play button to start the lightshow!
Effects are internally organized by categories to prevent visual conflicts. The exclude_list.toml configuration defines which effect classes cannot play together, ensuring optimal visual variety:
- Scanner Effects: Linear scanning patterns
- Tunnel Effects: Depth-based expanding/contracting shapes
- Particle Effects: Point-based dynamic systems
- Flash Effects: Beat-synchronized flashes
- Geometric Effects: Pattern-based visualizations
- Rotation Effects: Spinning and orbital animations
- Center Effects: Effects centered on screen (gobos, kaleidoscopes)
- Edge Effects: Effects along screen edges
The application uses librosa for audio analysis:
- Sample Rate: 44.1 kHz
- FFT Size: 2048
- Hop Length: 512 samples
- Frequency Bands:
- Bass: 20-200 Hz
- Mids: 200-2000 Hz
- Highs: 2000-8000 Hz
- PySide6 (>= 6.5.0): Qt6 GUI framework
- numpy (>= 1.24.0): Numerical computations
- librosa (>= 0.10.0): Audio analysis and beat detection
- soundfile (>= 0.12.0): Audio file I/O
OpenLightShow uses a fully modular plugin-based architecture. Effects are auto-discovered from the effects/ directory - just drop in a new file and it's automatically loaded!
- Create a new Python file in
src/openlightshow/effects/ - Subclass the Effect base class:
from ..effect_base import Effect
from PySide6.QtGui import QPainter, QColor
from PySide6.QtCore import QSize
class MyCustomEffect(Effect):
name = "My Custom Effect"
effect_class = "customeffect_class01" # Unique classification
def __init__(self, size: QSize):
super().__init__(size)
# Initialize your effect state
def on_beat(self):
# React to beat detection
super().on_beat()
def update(self, dt_ms, energies, sensitivity, flash_thresh):
# Update effect state
# energies = {'low': 0.0-1.0, 'mid': 0.0-1.0, 'high': 0.0-1.0}
pass
def paint(self, p: QPainter, brightness: float):
p.save()
# Draw your effect using QPainter methods
p.restore()- Restart the app - Your effect will be automatically discovered and appear in the effects list!
Visit the project website for a ready-to-use AI prompt that you can copy and paste into ChatGPT, Claude, or Copilot with your effect idea. The prompt includes the complete Effect base class structure and examples.
See Implementation_guide.md for detailed development guidelines, QPainter methods, and best practices.
If you encounter issues loading MP3 files:
-
Check libsndfile version: Ensure you have libsndfile >= 1.1.0
python -c "import soundfile; print(soundfile.__version__)" -
Install FFmpeg: As a fallback, install FFmpeg (see Prerequisites section)
-
Try WAV format: Convert your audio to WAV format as a workaround
- Reduce the number of simultaneous effects (Max Active setting)
- Lower the brightness setting
- Close other resource-intensive applications
- Increase the sensitivity slider
- Adjust the flash threshold
- Check that your audio file is being analyzed (watch the console output during track loading)
MIT License - see LICENSE file for details
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-effect) - Commit your changes (
git commit -m 'Add amazing effect') - Push to the branch (
git push origin feature/amazing-effect) - Open a Pull Request
- Built with PySide6
- Audio analysis powered by librosa
- Inspired by music visualization and VJ software
- Björn Seipel - Initial work