Muse Visualizer

Real-time EEG visualization tools for the Muse headband, featuring ultra-high-performance plotting of raw waveforms and frequency band analysis.

Overview

Two powerful visualization scripts for analyzing EEG data from Muse headbands in real-time:

live_raw_eeg_plot.py - Ultra-fast raw EEG waveform visualization (200+ FPS capable)
live_oscillations_plot.py - Real-time frequency band analysis (Delta, Theta, Alpha, Beta, Gamma)

Both scripts use PyQtGraph for GPU-accelerated rendering and Lab Streaming Layer (LSL) for low-latency data acquisition.

Features

Raw EEG Plotter (`live_raw_eeg_plot.py`)

Ultra-high performance: Achieves 200+ FPS with PyQtGraph backend
Real-time streaming: 256 Hz sampling from Muse headband
Channel selection: Plot individual channels (TP9, AF7, AF8, TP10) or average them
Signal processing:
- Adjustable smoothing with edge artifact handling
- DC offset removal with calibration period
- Edge cropping for clean visualization
Customization:
- Custom colors per channel (hex codes)
- Adjustable line width
- Configurable Y-axis scale
- Variable time window
Minimal mode: Clean, axis-free display for recording/streaming
Heart rate monitoring: Calculate and display HR from PPG sensor (Muse 2/S)
Performance monitoring: Live FPS counter option

Frequency Band Plotter (`live_oscillations_plot.py`)

Frequency band analysis: Real-time computation of Delta, Theta, Alpha, Beta, Gamma power
Multiple display modes:
- Absolute power (µV²)
- Logarithmic scale (dB)
- Relative power (percentage of total)
Configurable FFT: Adjustable window length for spectral analysis
Update rate control: Balance between responsiveness and smoothness
Band selection: Choose which frequency bands to display
Labeled minimal mode: Color-coded band labels with cognitive state descriptions
Signal processing: Smoothing and edge cropping options
Custom color palettes: Define colors for each frequency band

Installation

Requirements

Python 3.8+
Muse headband (2016, 2, or S)
Windows: BlueMuse or Linux/Mac: muse-lsl

Install Dependencies

pip install pyqtgraph PyQt5 pylsl scipy numpy

Setup Muse Streaming

Windows (BlueMuse):

Download and install BlueMuse
Connect your Muse headband
Start streaming in BlueMuse

Mac/Linux (muse-lsl):

pip install muselsl
muselsl stream

Usage

Raw EEG Visualization

Basic usage:

python live_raw_eeg_plot.py

Advanced examples:

Average frontal channels with smoothing:

python live_raw_eeg_plot.py -c AF7 AF8 --average --smooth 100 --center --colors 47BBFF

Minimal mode for clean display:

python live_raw_eeg_plot.py --minimal -f 120 --smooth 50 -s 15 -w 8

With heart rate monitoring:

python live_raw_eeg_plot.py --heart-rate --show-fps

Full-featured setup:

python live_raw_eeg_plot.py -c AF7 AF8 --average --center --smooth 100 --crop 40 --colors 47BBFF --minimal -f 60 -s 15 -w 8 --linewidth 5

Frequency Band Analysis

Basic usage:

python live_oscillations_plot.py

Advanced examples:

Relative power (percentage) display:

python live_oscillations_plot.py --relative-power --minimal

High-speed updates with custom colors:

python live_oscillations_plot.py -c AF7 AF8 --average-channels --minimal -f 60 --smooth 5 -w 15 --linewidth 5 --relative-power --fft-window 0.5 --update-rate 250 --colors 225A8C 317CA3 3F9EB9 4EBFD0 5CE1E6

Specific bands only:

python live_oscillations_plot.py -b Alpha Beta --relative-power

Logarithmic scale:

python live_oscillations_plot.py --log-scale --show-fps

Parameters

Raw EEG Plotter

Parameter	Description	Default
`-w, --window`	Time window in seconds	5.0
`-f, --fps`	Target frame rate	60
`-s, --scale`	Y-axis scale in µV	200.0
`-c, --channels`	Channels to plot (TP9/AF7/AF8/TP10)	All
`--average`	Average selected channels	False
`--smooth`	Smoothing window size	0
`--center`	Auto-center waveform (DC offset removal)	False
`--center-duration`	Calibration period in seconds	10.0
`--crop`	Crop samples from edges	0
`--colors`	Hex color codes	Default
`--linewidth`	Line thickness	1.5 (avg), 1 (individual)
`--minimal`	Minimal UI mode	False
`--show-fps`	Display FPS counter	False
`--heart-rate`	Show heart rate from PPG	False

Frequency Band Plotter

Parameter	Description	Default
`-w, --window`	Display window in seconds	10.0
`--fft-window`	FFT computation window in seconds	2.0
`--update-rate`	Band power update rate in Hz	10.0
`-f, --fps`	Display frame rate	60
`-c, --channels`	Channels to analyze	All
`-b, --bands`	Bands to plot (Delta/Theta/Alpha/Beta/Gamma)	All
`--average-channels`	Average channels before FFT	False
`--relative-power`	Show as percentage (0-100%)	False
`--log-scale`	Use logarithmic scale (dB)	False
`--auto-scale`	Auto-adjust Y-axis	False
`--y-max`	Maximum Y-axis value	Auto
`--smooth`	Smoothing window size	0
`--crop`	Crop samples from edges	0
`--colors`	Hex color codes for bands	Default
`--linewidth`	Line thickness	2.0
`--minimal`	Minimal UI with band labels	False
`--show-fps`	Display FPS counter	False

Frequency Bands

Band	Frequency Range	Mental State	Color (Default)
Delta	0.5-4 Hz	Deep sleep	Purple (128, 0, 128)
Theta	4-8 Hz	Memory, drowsiness	Blue (0, 0, 255)
Alpha	8-13 Hz	Relaxed, calm	Green (0, 255, 0)
Beta	13-30 Hz	Focus, alertness	Yellow (255, 255, 0)
Gamma	30-50 Hz	Attention, processing	Red (255, 0, 0)

Technical Details

Raw EEG Processing

Sampling Rate: 256 Hz from Muse headband
Filtering: Optional DC offset removal with calibration
Smoothing: Uniform filter with reflect mode for edge handling
Display: PyQtGraph with GPU acceleration

Frequency Band Analysis

Method: Welch's periodogram for power spectral density
FFT Window: Configurable (default 2 seconds)
Frequency Resolution: Determined by FFT window length
Update Mechanism: Rate-limited to prevent over-smoothing
Normalization: Optional relative power (percentage of total)

Heart Rate Calculation (Raw Plotter Only)

Sensor: PPG (photoplethysmography) on Muse 2/S
Sampling: 64 Hz from PPG sensor
Processing:
- Bandpass filter: 0.5-4 Hz (30-240 BPM)
- Peak detection with prominence threshold
- Inter-beat interval calculation
- Median-based averaging for robustness
- Valid range: 30-200 BPM

Performance Tips

For smoothest display: Use --minimal mode and target 60 FPS
For responsiveness: Reduce smoothing and FFT window size
For clean traces: Increase smoothing, enable DC centering, use crop
For frequency bands: Use --relative-power for equal visibility
For artifacts: Enable --center with sufficient calibration duration

Troubleshooting

No stream found:

Ensure BlueMuse (Windows) or muse-lsl (Mac/Linux) is running
Check that Muse headband is connected and streaming
Verify LSL is properly installed: python -c "from pylsl import resolve_streams; print(resolve_streams())"

Low FPS:

Reduce window length or smoothing amount
Lower target FPS if hardware limited
Close other applications using GPU

Steppy frequency bands:

Increase --update-rate (default 10 Hz, try 30-60 Hz)
Reduce --fft-window for faster updates
Decrease --smooth parameter

PPG/Heart rate not working:

Muse 2 or Muse S required (original Muse doesn't have PPG)
Enable PPG streaming in BlueMuse: start bluemuse://setting?key=ppg_enabled!value=true
Ensure good headband fit for optical sensor contact

Examples

Meditation Monitoring

python live_oscillations_plot.py -b Alpha Theta --relative-power --minimal -w 30 --smooth 20

Track relaxation (Alpha) and deep meditation (Theta) states.

Focus Training

python live_oscillations_plot.py -b Beta Gamma --relative-power --minimal --update-rate 30

Monitor attention (Gamma) and concentration (Beta) during work.

Sleep Analysis

python live_oscillations_plot.py -b Delta Theta Alpha --relative-power -w 60 --fft-window 4

Observe transition from wakefulness (Alpha) to sleep (Delta/Theta).

Clean Recording Setup

python live_raw_eeg_plot.py -c AF7 AF8 --average --smooth 100 --center --crop 40 --minimal --colors 47BBFF --linewidth 5 -w 8 -s 15 -f 60

Production-ready minimal display for video recording or streaming.

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

MIT License - see LICENSE file for details.

Acknowledgments

Built for the Muse headband by InteraXon
Uses BlueMuse for Windows LSL streaming
Uses muse-lsl for Mac/Linux
Powered by PyQtGraph for high-performance visualization
Lab Streaming Layer (LSL) for real-time data

Citation

If you use this software in your research, please cite:

@software{muse_eeg_visualizer,
  title = {Muse EEG Visualizer},
  author = {Devon},
  year = {2026},
  url = {https://github.com/devon7y/muse-eeg-visualizer}
}

Support

For questions or issues:

Open an issue on GitHub
Check the BlueMuse documentation
Review the muse-lsl guide

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
live_oscillations_plot.py		live_oscillations_plot.py
live_raw_eeg_plot.py		live_raw_eeg_plot.py
tmpclaude-6ba9-cwd		tmpclaude-6ba9-cwd

Folders and files

Latest commit

History

Repository files navigation

Muse Visualizer

Overview

Features

Raw EEG Plotter (live_raw_eeg_plot.py)

Frequency Band Plotter (live_oscillations_plot.py)

Installation

Requirements

Install Dependencies

Setup Muse Streaming

Usage

Raw EEG Visualization

Frequency Band Analysis

Parameters

Raw EEG Plotter

Frequency Band Plotter

Frequency Bands

Technical Details

Raw EEG Processing

Frequency Band Analysis

Heart Rate Calculation (Raw Plotter Only)

Performance Tips

Troubleshooting

Examples

Meditation Monitoring

Focus Training

Sleep Analysis

Clean Recording Setup

Contributing

License

Acknowledgments

Citation

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Raw EEG Plotter (`live_raw_eeg_plot.py`)

Frequency Band Plotter (`live_oscillations_plot.py`)

Packages