alpha — things will break

BCI development shouldn't require a PhD

Open-source Python toolkit for reading EEG data, processing neural signals, and building brain-computer interfaces. Supports consumer hardware. Actually documented.

We're not pretending this is production-ready. But it works, and it's getting better every week.

$ pip install neural-ninja # coming soon
Quick Start View Source
Where We Actually Are

Project Roadmap

Honest status of what works, what's in progress, and what we're planning. No vaporware.

v0.1
Signal processing core — Bandpass, notch, CAR filters. FFT spectral analysis. Basic artifact rejection.
done
v0.2
Device drivers — OpenBCI Cyton, Ganglion, Muse 2. LSL streaming. Auto-detection.
done
v0.3
Real-time viz — WebSocket server for live EEG plots. Time-series, spectrograms, topomaps.
in progress
v0.4
ML pipelines — Motor imagery classification, P300 detection, SSVEP. PyTorch + scikit-learn.
in progress
v0.5
Experiment framework — Stimulus presentation, trial randomization, PsychoPy integration.
planned
v1.0
Stable API — Breaking changes stop. Docs are comprehensive. You can build on this without worrying.
planned
Quick Start

Five minutes to first data

Install, plug in your EEG, run the example. If it takes longer than five minutes, that's a bug and you should file an issue.

  1. Install — pip install or clone from GitHub
  2. Connect — plug in your device, auto-detect handles it
  3. Stream — three lines of Python to live data
  4. Process — chain filters, visualize, decode
Full docs on GitHub
quickstart.py 
# pip install neural-ninja  (coming soon)

from neural_ninja import Board, FilterPipeline
from neural_ninja.viz import LivePlot

# Auto-detect connected EEG device
board = Board.auto_connect()

# Build a signal processing chain
pipeline = FilterPipeline([
    ("bandpass", {"low": 1, "high": 40}),
    ("notch",    {"freq": 60}),
    ("car",      {}),  # Common Avg Ref
])

# Stream and visualize
board.start_stream()
plot = LivePlot(board, pipeline, channels=[0,1,2,3])
plot.show()

# Read filtered data
epoch = board.get_data(seconds=2)
filtered = pipeline.apply(epoch)
print(f"Shape: {filtered.shape}")
# >> Shape: (4, 500)  # 4ch, 250Hz
Tested Hardware

Devices we've actually plugged in

First-class drivers for these. Community contributions welcome for anything else. If it speaks LSL, it probably works already.

OpenBCI Cyton

8ch research-grade

8 ch · 250 Hz · 24-bit

OpenBCI Ganglion

4ch budget option

4 ch · 200 Hz · 24-bit

Muse 2

Consumer headband

4 ch · 256 Hz · 12-bit

Muse S

Sleep EEG

4 ch · 256 Hz · 12-bit

Emotiv EPOC X

14ch wireless

14 ch · 256 Hz · 14-bit

g.tec Unicorn

8ch dry electrode

8 ch · 250 Hz · 24-bit

FreeEEG32

Open-source 32ch

32 ch · 512 Hz · 24-bit

Any LSL Source

Generic driver

N ch · Custom
Open Source

We need help

This is a nights-and-weekends project that wants to be more than that. If you know signal processing, BCI paradigms, or just want better docs — PRs are open.

01

Fork & Clone

Branch from main. Read CONTRIBUTING.md. It's short.

02

Build Something

Add tests. Run make lint. Don't break existing stuff.

03

Open a PR

Describe what you did and why. We review fast.

04

Ship It

Merged code goes out in the next release. You get credit.

View on GitHub