Skip to content
itayinbarrPublic

About

A modern JavaScript library for connecting to Muse EEG devices using Web Bluetooth API. This project aims to provide a maintained alternative to muse-js which is no longer actively maintained.

Resources

Stars

23 stars

Watchers

4 watching

Forks

Latest commit

 

History

17 Commits

Folders and files

Repository files navigation

web-muse

A modern JavaScript library for connecting to Muse EEG devices using Web Bluetooth API. This project aims to provide a maintained alternative to muse-js which is no longer actively maintained.

Why web-muse?

  • 🔄 Active Development: Unlike muse-js, web-muse is actively maintained and works with current Muse firmware
  • 🌐 Web Bluetooth: Direct browser connection without additional software
  • ⚛️ React Integration: Built-in React hooks and context for easy integration
  • 🧪 Mock Data: Development support with mock data capabilities
  • 📊 Signal Processing: Built-in EEG processing utilities

Features

  • Direct connection to Muse EEG devices via Web Bluetooth
  • Real-time EEG data streaming at 256Hz
  • Built-in signal processing utilities
  • React hooks and context for easy integration
  • Mock data mode for development and testing (no device required!)
  • Muse S Athena (MS-03, 2025) support, detected automatically, including fNIRS optics
  • Support for:
    • EEG data (4 channels; 8 on the Athena with 8-channel presets)
    • PPG data (3 channels, Muse 2)
    • Optics / fNIRS data (4, 8 or 16 channels, Muse S Athena)
    • Accelerometer data
    • Gyroscope data
    • Battery level monitoring

Installation

Local Development

  1. Clone the repository:
git clone https://github.com/itayinbarr/web-muse.git
cd web-muse
  1. Install dependencies:
npm install
  1. Build the library:
npm run build

Using in Your Project

You can install web-muse directly from your local clone using one of these methods:

Method 1: Using npm link

# In web-muse directory
npm link

# In your project directory
npm link web-muse

Method 2: Direct local path in package.json

Add this to your project's package.json:

{
  "dependencies": {
    "web-muse": "file:../path/to/web-muse"
  }
}

Then run npm install

Method 3: Using GitHub URL

Add this to your project's package.json:

{
  "dependencies": {
    "web-muse": "github:itayinbarr/web-muse"
  }
}

Then run npm install

Quick Start

Basic Usage (Vanilla JavaScript)

import { connectMuse } from "web-muse";

async function connectToMuse() {
  // Connect to a real Muse device
  const muse = await connectMuse();
  console.log("Connected to Muse device:", muse);

  // Start receiving EEG data
  setInterval(() => {
    const eegData = muse.eeg.map((buffer) => buffer.read());
    console.log("EEG Data:", eegData);
  }, 1000 / 256); // 256Hz sampling rate
}

// To record every sample with its packet sequence number and arrival time,
// subscribe instead of polling (see docs/API.md):
// muse.onEEG(({ channel, seq, samples, receivedAt }) => { ... });

// Or use mock mode for development (no device required!)
async function connectToMuseMock() {
  const muse = await connectMuse({ mock: true });
  console.log("Connected in mock mode:", muse);

  // Same API - works identically to real device
  setInterval(() => {
    const eegData = muse.eeg.map((buffer) => buffer.read());
    console.log("Mock EEG Data:", eegData);
  }, 1000 / 256);
}

React Usage

import { useEEG, EEGProvider } from "web-muse/react";

// Wrap your app with the provider
function App() {
  return (
    <EEGProvider>
      <YourComponent />
    </EEGProvider>
  );
}

// Use the hook in your components
function YourComponent() {
  const { isConnected, connectMuse, rawEEG } = useEEG();

  const handleConnectReal = async () => {
    await connectMuse();
  };

  const handleConnectMock = async () => {
    await connectMuse({ mock: true });
  };

  return (
    <div>
      {!isConnected ? (
        <>
          <button onClick={handleConnectReal}>Connect to Real Device</button>
          <button onClick={handleConnectMock}>Use Mock Data</button>
        </>
      ) : (
        <div>EEG Data: {JSON.stringify(rawEEG)}</div>
      )}
    </div>
  );
}

Muse S Athena (MS-03)

The 2025 Muse S ("Athena", USB-C, model MS-03) uses a different Bluetooth protocol from earlier headbands: every sensor is multiplexed onto a single characteristic as tagged, bit-packed subpackets. web-muse detects it on connect and decodes it into the same API, so muse.eeg, onEEG and the React hooks work unchanged. Decoding Athena data with the Muse 2 format yields noise; that was the cause of the earlier, unsupported behaviour.

import { connectMuse, ATHENA_PRESETS } from "web-muse";

// p1035 (default): 4 EEG channels + 4 optics channels
// p1041: 8 EEG channels + 16 optics channels, p21: EEG only
const muse = await connectMuse({ preset: "p1035" });

if (muse.isAthena) {
  muse.onOptics(({ index, channels, names }) => {
    // names: ["LI_730", "RI_730", "LI_850", "RI_850"] (left/right inner, 730/850 nm)
    // channels: raw 20-bit samples per channel, 64 Hz
  });
  muse.onMotion(({ accelerometer, gyroscope }) => {}); // g and deg/s, 52 Hz
  console.log(muse.stats); // { notifications, droppedSubpackets, skippedBytes }
}

Validated on a Muse S Athena with firmware 3.1.15: no dropped packets over 2-minute recordings, and the expected eyes-closed alpha peak (~9 Hz at TP9/TP10, about 5x stronger than with eyes open).

EEG is 14-bit at 256 Hz, converted to microvolts as (raw - 8192) * 1450 / 16383. When the headband is not on a head, channels sit at the rails (about ±725 µV); that is expected. The protocol decoder is in src/lib/athena.js and can be used on its own (parseAthenaNotification).

Mock Mode for Development

Mock mode allows you to develop and test your application without a physical Muse device. It plays back pre-recorded EEG data in a loop, providing realistic data for development and testing.

Using Mock Mode

Vanilla JavaScript:

import { connectMuse } from "web-muse";

// Connect with mock data
const muse = await connectMuse({ mock: true });

// Optionally specify a custom CSV file
const muse = await connectMuse({
  mock: true,
  mockDataPath: "/path/to/your/data.csv",
});

Direct Instantiation:

import { Muse } from "web-muse";

const muse = new Muse({ mock: true });
await muse.connect();

Mock Data Format

The default mock data is located at assets/resting-state.csv and contains real EEG recordings from a Muse device. The format is:

Timestamp (ms),TP9 (left ear),AF7 (left forehead),AF8 (right forehead),TP10 (right ear)
5,-0.48828125,0,-0.48828125,-0.48828125
7,0,-0.48828125,-0.48828125,0
...

You can provide your own CSV file in the same format for custom mock data scenarios.

Development

# Install dependencies
npm install

# Run tests (Node 20+)
npm test

Requirements

  • A Muse headband (tested with Muse 2, Muse S and Muse S Athena)
  • A Web Bluetooth-compatible browser:
    • Chrome (desktop & android)
    • Edge (desktop)
    • Opera (desktop & android)
    • Samsung Internet (android)

Note: Safari and iOS devices do not currently support Web Bluetooth.

Browser Support

Web Bluetooth API is required. Check browser compatibility.

Documentation

License

MIT

Acknowledgments

  • Thanks to muse-js for pioneering Web Bluetooth support for Muse devices
  • Thanks to Interaxon for creating the Muse headband
  • The Muse S Athena protocol follows the reverse engineering in OpenMuse, BrainFlow and Polobase/muse.js

About

A modern JavaScript library for connecting to Muse EEG devices using Web Bluetooth API. This project aims to provide a maintained alternative to muse-js which is no longer actively maintained.

Resources

Stars

23 stars

Watchers

4 watching

Forks

Releases

Packages

Contributors

Languages