An easy-to-use platform for EEG experimentation in the classroom

Features

• Design, run, and analyze an experiment using real EEG data all in one desktop app
• Investigate visual event-related brain waves (ERPs)
• Supports Muse and Neurosity EEG devices

Screenshots

Prerequisites

• Node.js >= 18
• npm >= 9
• No Python installation required — EEG analysis runs via Pyodide (Python compiled to WebAssembly), which is downloaded automatically on first npm install.

Note: npm install downloads ~300 MB of Pyodide WASM files on first run. This is expected and only happens once.

macOS (Apple Silicon) — install liblsl

The node-labstreaminglayer npm package only ships an x86_64 liblsl.dylib, so arm64 Macs (M1/M2/M3/M4) need an arm64 build of liblsl from Homebrew. The dev script automatically symlinks the Homebrew binary into node_modules/ on every install.

brew install labstreaminglayer/tap/lsl

If you skip this step, npm run dev will fail at startup with Failed to load shared library: ... incompatible architecture. Intel Macs, Linux, and Windows do not need this step — the bundled binaries work as-is.

Installing from Source (for developers)

1. Clone the repo:

git clone https://github.com/makebrainwaves/BrainWaves.git
cd BrainWaves

2. Install dependencies (this also installs Pyodide and patches certain deps):

npm install

Development

Start the app with hot-reload using electron-vite:

npm run dev

Testing

npm test           # run all Vitest tests once
npm run test:watch # run tests in watch mode
npm run test-all   # lint + typecheck + build + test (full CI check)

Typecheck & Lint

npm run typecheck  # TypeScript type check (no emit)
npm run lint       # ESLint
npm run lint-fix   # ESLint + Prettier auto-fix

Packaging

Build only (no installer):

npm run build

Package for the current platform:

npm run package

Package for specific platforms:

npm run package-mac    # macOS .dmg
npm run package-win    # Windows .exe (x64)
npm run package-linux  # Linux
npm run package-all    # all platforms (requires cross-platform build tools)

For cross-platform builds, see electron-builder multi-platform docs.

To debug a production build with DevTools:

DEBUG_PROD=true npm run package

Contributing

if you are interested in fixing issues with the BrainWaves app or helping us add additional features, that's amazing! Please see our How to Contribute.

Also, read our Code of Conduct

License

MIT