Brainwaves Template
Overview
The Brainwaves template demonstrates how to build a comprehensive brain mapping and movement analytics platform using Moose. It features real-time collection, analysis, and visualization of brainwave data from EEG devices like the Muse Headband, with support for both live device streaming and simulation using datasets.
Features
- Real-time brainwave data collection and analysis from EEG devices
- Live terminal dashboard with interactive charts and visualizations
- Session-based data logging and tracking
- Movement and relaxation state analysis
- Dual-application architecture (DAS + Brainmoose backend)
- Optional OpenAI-powered insights and analysis
- Support for both live device streaming and CSV simulation
Architecture
DAS: Data Acquisition Server
The Data Acquisition Server is a Node.js/TypeScript application that handles:
-
Real-time Data Ingestion
- UDP/OSC data collection from Muse devices or simulators
- Session-based CSV logging with unique identifiers
-
Live Analysis & Visualization
- Terminal dashboard with real-time charts and tables
- Brainwave band analysis (Alpha, Beta, Delta, Theta, Gamma)
- Movement detection using accelerometer and gyroscope data
-
Data Forwarding
- Automatic forwarding to Moose backend for storage and analytics
Brainmoose: Analytics & API Backend
The Moose-powered backend provides:
- Modular data ingestion and storage pipeline
- Advanced analytics blocks for movement scoring
- RESTful APIs for querying session insights
- Optional OpenAI GPT-4o integration for enhanced analysis
- ClickHouse-based data warehouse for complex queries
Getting Started
Prerequisites
Node.js 20+ Moose CLI Optional: Muse Headband EEG device
bash -i <(curl -fsSL https://fiveonefour.com/install.sh) moose
- Create a new Moose project from the template:
moose init moose-brainwaves brainwaves
cd moose-brainwaves
- Install dependencies for both applications:
# Install DAS dependencies
cd apps/das
npm install
# Install Brainmoose dependencies
cd ../brainmoose
npm install
- Start with simulation (no device required):
# Download sample data
cd ../das
./download.sh
# Start DAS
npm run dev -- --sessionId=MyTestSession
- In another terminal start the Moose analytics backend:
cd {project_root}/apps/brainmoose
moose dev
- In another terminal run the simulation (no device required):
cd {project_root}/apps/das
./sim.sh brain_data_coding.csv
API Endpoints
The template exposes key API endpoints for accessing brainwave analytics:
/consumption/sessionInsights
- Parameters: sessions (comma-separated sessionId|sessionLabel pairs)
- Returns: Movement scores and session analytics for specified sessions
Data Models
Brain Data Schema
interface BrainData {
timestamp: DateTime;
bandOn: boolean;
acc: {
x: number;
y: number;
z: number;
};
gyro: {
x: number;
y: number;
z: number;
};
alpha: number;
beta: number;
delta: number;
theta: number;
gamma: number;
ppm: {
channel1: number;
channel2: number;
channel3: number;
};
sessionId: string;
}
Analytics & Insights
The template includes sophisticated analytics for:
Movement Analysis
- Accelerometer-based movement scoring
- Gyroscope rotation detection
- Combined movement metrics calculation
Brainwave Band Analysis
- Alpha wave relaxation indicators
- Beta wave focus measurements
- Delta, Theta, and Gamma band processing
- Real-time state classification
Session Scoring
Example movement score calculation:
SELECT
sessionId,
SUM(sqrt((arrayElement(acc, 1)^2) + (arrayElement(acc, 2)^2) + (arrayElement(acc, 3)^2))) AS acc_movement_score,
SUM(sqrt((arrayElement(gyro, 1)^2) + (arrayElement(gyro, 2)^2) + (arrayElement(gyro, 3)^2))) AS gyro_movement_score
FROM Brain_0_0
WHERE sessionId = '1735785243'
GROUP BY sessionId;
Device Support
Muse Headband Integration
- Direct OSC data streaming support
- Real-time EEG signal processing
- Multi-channel brainwave analysis
Simulation Support
- CSV data playback for testing
- Sample datasets included
- Configurable replay speeds
Customization
You can customize the template by:
- Extending brainwave analysis algorithms
- Adding new visualization components to the terminal UI
- Implementing custom movement detection logic
- Integrating additional EEG devices or data sources
- Enhancing the OpenAI analysis prompts and insights
- Creating custom API endpoints for specific analytics needs
Educational Resources
Learn More
Listen to these ~15 minute podcasts generated using NotebookLM: