@elata-biosciences/eeg-web

Web wrapper for the Elata EEG WASM bindings.

New to the SDK? npm create @elata-biosciences/elata-demo my-app is the recommended start. You can also run npx @elata-biosciences/create-elata-demo my-app. Either path scaffolds a working app with synthetic mode, correct Vite config, and WASM imports already set up — no hardware required to get started.

What This Package Is

@elata-biosciences/eeg-web is intentionally a thin wrapper:

• dist/index.js and dist/index.d.ts provide stable init helpers, wrapper utilities, and compatibility re-exports
• the full EEG API surface is still generated by wasm-bindgen, but app code should prefer the package helpers when they exist
• generated WASM assets are shipped in wasm/

This package does not implement Bluetooth device connection logic by itself.

When To Use It

Abstraction level: raw EEG primitives. This package gives you EEG-focused WASM classes and functions you call directly — you own the orchestration.

Use @elata-biosciences/eeg-web when you want:

• browser-side EEG WASM APIs
• Elata signal processing and model functions in JavaScript or TypeScript
• shared types used by higher-level browser integrations

Use @elata-biosciences/eeg-web-ble in addition if you also need browser BLE headset transport (built-in Muse support today; additional devices via the same package with contributor extensions — see docs/contributing-eeg-transports.md).

Install

pnpm add @elata-biosciences/eeg-web
npm install @elata-biosciences/eeg-web

Requirements

• Node.js >= 20 for server-side usage and local repo tooling
• modern browser with WebAssembly support for in-browser usage

Usage

import { initEegWasm, band_powers } from "@elata-biosciences/eeg-web";

await initEegWasm();
const powers = band_powers(eegData, 256);
console.log(powers.alpha);

EEG Preprocessing

@elata-biosciences/eeg-web now exposes the browser wrapper around the Rust EEG preprocessing pipeline. The DSP implementation lives in crates/eeg-signal and is surfaced through eeg-wasm; this package provides the stable TypeScript API for using it in browser code.

Default processing stages:

• notch filtering at 60 Hz plus 120 Hz
• detrending via 0.5 Hz high-pass cleanup
• common-average rereferencing

The wrapper preserves both views of the signal when processing is enabled:

• frame.eeg: processed EEG
• frame.eegRaw: raw transport samples when available
• frame.eegProcessing: metadata describing the applied stages

Example:

import {
  createEegPreprocessor,
  getEegChannelSamples,
  processHeadbandFrame,
} from "@elata-biosciences/eeg-web";

const processor = await createEegPreprocessor({
  notch: { mainsHz: 60 },
  detrend: { mode: "highpass", cutoffHz: 0.5 },
  reference: { mode: "common-average" },
});

const processedFrame = processor.processFrame(frame);
const processedCh0 = getEegChannelSamples(processedFrame, 0);
const rawCh0 = getEegChannelSamples(processedFrame, 0, "raw");

processor.dispose();

Available configuration surfaces:

• enabled: false to bypass processing entirely
• preserveRaw: false to omit eegRaw
• notch: false to disable mains suppression
• notch.mainsHz: 50 | 60 | null
• reference.mode: "none" | "common-average" | "custom-average"
• reference.channels for a custom rereference subset
• detrend.mode: "off" | "highpass" | "linear"

Helper functions:

• createEegPreprocessor(options)
• processHeadbandFrame(frame, options)
• getEegSignalBlock(frame, source)
• getEegChannelSamples(frame, channelIndex, source)
• getEegInterleavedSamples(frame, source)

Recommended Vs Advanced

Recommended:

• For browser rPPG app integration, use createRppgSession() from @elata-biosciences/rppg-web.

Advanced:

• The generated wasm-bindgen exports are still re-exported for compatibility and SDK debugging, but they are easier to misuse.
• Avoid instantiating generated wrappers directly unless you are intentionally debugging the SDK itself or need a surface the stable helpers do not expose yet.

Key Exports

• initEegWasm and initEegWasmSync
• createRppgPipeline
• createEegPreprocessor
• processHeadbandFrame
• band_powers
• getEegSignalBlock
• getEegChannelSamples and getEegInterleavedSamples
• WasmAlphaBumpDetector
• WasmAlphaPeakModel
• WasmCalmnessModel
• AthenaWasmDecoder
• generated wasm-bindgen exports for advanced or compatibility use

Device Support

Contract: live headset data in browser apps should flow through a HeadbandTransport implementation (from this package’s types) that emits HeadbandFrameV1. That is the stable boundary for signal processing and demos.

Shipped in @elata-biosciences/eeg-web-ble today:

• Muse 2 and Muse S classic BLE devices
• Muse S Athena protocol v2 devices
• the synthetic Muse-compatible BLE bridge for testing

Additional headsets belong in eeg-web-ble (or a sibling transport package) as long as they implement the same transport contract. In this monorepo, eeg-web-ble separates src/transport/ (BleTransport) from src/devices/muse/ (built-in Muse protocol). See docs/contributing-eeg-transports.md.

Build And Dev Notes

From the repo root:

./run.sh build eeg

This builds elata-eeg-wasm, runs wasm-bindgen, syncs generated files into packages/eeg-web/wasm, and builds the TypeScript wrapper.

For local iteration against an existing app, use:

./run.sh sync-to ../my-app

sync-to is a local repo-development helper for eeg-web. It is not the recommended path for starting a new app.

Package Layout

• src/*.ts: source edited in this repo
• dist/*.js: emitted runtime files for consumers
• dist/*.d.ts: emitted type declarations
• wasm/*: generated wasm-bindgen artifacts re-exported by this package

Troubleshooting

• If initEegWasm() fails in a browser app, verify your bundler is serving the packaged wasm/ assets.
• If you see a deprecated init warning, keep calling initEegWasm() or initEegWasmSync() rather than passing raw input into generated init exports directly. The wrapper now normalizes the newer object shape for you.
• If you are testing local repo changes in another app, prefer ./run.sh sync-to ../my-app instead of manually copying build outputs.
• If you need device connection, this package alone is not enough; add @elata-biosciences/eeg-web-ble, another HeadbandTransport, or a bridge-backed transport.

Release Notes

For release order, dist-tags, and recovery guidance, see docs/releasing.md.