muse-js JavaScript Library

Since muse-js relies on the Web Bluetooth API, you must use a package like bleat to emulate Web Bluetooth in a Node.js environment. This requires noble to handle the underlying Bluetooth hardware. You should wait for the noble state to be poweredOn before attempting to request a device and connecting the MuseClient to the GATT server.

const noble = require('noble');
const bluetooth = require('bleat').webbluetooth;

async function connect() {
    let device = await bluetooth.requestDevice({
        filters: [{ services: [MUSE_SERVICE] }]
    });
    const gatt = await device.gatt.connect();
    const client = new MuseClient();
    await client.connect(gatt);
    await client.start();
    // Now do whatever with muse client...
}

noble.on('stateChange', (state) => {
    if (state === 'poweredOn') {
        connect();
    }
});

To use muse-js in a web environment, import MuseClient, instantiate it, connect, and start the stream. You can subscribe to eegReadings, telemetryData, and accelerometerData using an observer pattern to receive real-time data from the headset.

import { MuseClient } from 'muse-js';

async function main() {
  let client = new MuseClient();
  await client.connect();
  await client.start();
  client.eegReadings.subscribe(reading => {
    console.log(reading);
  });
  client.telemetryData.subscribe(telemetry => {
    console.log(telemetry);
  });
  client.accelerometerData.subscribe(acceleration => {
    console.log(acceleration);
  });
}

main();

The MuseClient provides an eventMarkers stream that allows you to inject custom, timestamped events into your data stream. Subscribe to the eventMarkers stream to receive these events, and use the injectMarker(value, [timestamp]) method to send them.

async function main() {
    let client = new MuseClient();
    client.eventMarkers.subscribe((event) => {
        console.log(event);
    });
    client.injectMarker("house")
    client.injectMarker("face")
    client.injectMarker("dog")
}

Muse 2016 EEG headsets support an additional Auxiliary electrode via the Micro USB port. To receive data from this channel, set the enableAux property to true on your MuseClient instance before calling the connect() method.

async function main() {
  let client = new MuseClient();
  client.enableAux = true;
  await client.connect();
}

Muse 2 and Muse S headsets include PPG/optical blood sensors providing three signal streams: ppg1, ppg2, and ppg3.

Warning: PPG is not present on Muse 1/1.5. Enabling it on those models may cause unexpected consequences.

To use PPG, set enablePpg = true on the MuseClient instance before calling connect(), then subscribe to ppgReadings.

async function main() {
  let client = new MuseClient();
  client.enablePpg = true;
  await client.connect();
}

// Subscribing to readings
client.ppgReadings.subscribe((ppgreading) => {
    console.log(ppgreading);
});

You can enable additional sensors on the MuseClient instance before calling connect():

• enablePpg: Set to true to enable the Photoplethysmography (PPG) optical sensor. This changes the device preset to p50.
• enableAux: Set to true to enable the auxiliary EEG channel. This changes the device preset to p20.

By default, enablePpg and enableAux are false.

const client = new MuseClient();
client.enablePpg = true;
client.enableAux = true;
await client.connect();

Use parseControl to transform an Observable<string> of raw control characters into an Observable of parsed JSON objects. This function handles character buffering and splits data based on the } delimiter to ensure complete JSON objects are emitted.

import { parseControl } from './muse-parse';
import { Observable } from 'rxjs';

// controlStream is an Observable<string> emitting raw characters
const controlStream$ = parseControl(controlStream);

controlStream$.subscribe(jsonObject => {
  console.log('Parsed control command:', jsonObject);
});

MuseClient exposes several RxJS Observables for real-time data. You can subscribe to these to process sensor readings:

Note: ppgReadings is only available if enablePpg is set to true before connecting.

Use decodeEEGSamples to convert raw Uint8Array Bluetooth data into meaningful EEG readings. The function handles the 12-bit unsigned decoding and applies the necessary scaling factor to convert the raw values into a usable range.

import { decodeEEGSamples } from './muse-parse';

// rawData is a Uint8Array received from the Bluetooth device
const eegReadings = decodeEEGSamples(rawData);

Use parseTelemetry to extract device status information from a DataView. This returns a TelemetryData object containing:

• sequenceId: uint16
• batteryLevel: float (0.0 to 1.0)
• fuelGaugeVoltage: float
• temperature: uint16

import { parseTelemetry } from './muse-parse';

// data is a DataView of the telemetry packet
const telemetry = parseTelemetry(data);
console.log(telemetry.batteryLevel);

You can manually inject event markers into the eventMarkers stream. This is useful for synchronizing external events with the sensor data stream.

// Inject a marker with a value and a specific timestamp
await client.injectMarker('stimulus_start', Date.now());

await client.injectMarker('event_name', Date.now());