# NeuroSkill™

> Open-source, local-first, real-time EEG analysis desktop application for Muse and OpenBCI devices.

NeuroSkill™ is a Tauri 2 desktop application (Rust backend + Svelte 5 frontend) that connects to Muse 2/S EEG headsets via Bluetooth Low Energy, or to OpenBCI boards (Ganglion, Cyton, Cyton+Daisy, Galea) via BLE, USB serial, WiFi Shield, or UDP, and provides real-time brain signal analysis with 60+ computed metrics, GPU-accelerated neural embeddings, vector similarity search, automatic sleep staging, and a local WebSocket API.

## Key Facts

- **Architecture**: Rust (Tauri 2) + Svelte 5 + wgpu (GPU compute) + SQLite + HNSW
- **Version**: 0.0.9
- **Hardware**: Muse 2 / Muse S (4-ch EEG: TP9, AF7, AF8, TP10 + PPG + 9-axis IMU, BLE, 256 Hz) · OpenBCI Ganglion (4ch, BLE/WiFi, 200 Hz) · Cyton (8ch, USB/WiFi, 250–1000 Hz) · Cyton+Daisy (16ch, USB/WiFi, 125 Hz) · Galea (24ch, UDP, 250 Hz)
- **Sample Rate**: 256 Hz EEG, ~4 Hz metric updates, 5-second embedding epochs
- **Metrics**: 60+ including band powers (δ θ α β γ), brain scores (focus, relaxation, engagement, meditation, cognitive load, drowsiness, mood), cross-band ratios (TAR, BAR, DTR, TBR), spectral shape (PSE, APF, SEF95, centroid, BPS, SNR), connectivity (FAA, coherence, mu suppression, laterality, PAC), complexity (Hjorth, permutation entropy, Higuchi FD, DFA, sample entropy), PPG/HRV (HR, RMSSD, SDNN, pNN50, LF/HF, respiratory rate, SpO₂, perfusion index, Baevsky stress index), events (blinks, jaw clenches, head pitch/roll, stillness, nods, shakes), headache & migraine research correlates (headache_index, migraine_index), consciousness metrics (consciousness_lzc, consciousness_wakefulness, consciousness_integration)
- **Embeddings**: ZUNA transformer encoder (wgpu) → 32-D vectors stored in daily HNSW indices (M=16, ef=200, cosine distance)
- **Sleep**: Automatic Wake/N1/N2/N3/REM staging for sessions ≥ 30 minutes (AASM band-power rules)
- **API**: Local JSON WebSocket server (mDNS: _neuroskill._tcp). 3 outbound events (eeg-bands ~4 Hz, muse-status ~1 Hz, label-created). 9 inbound commands (status, label, search, sessions, compare, sleep, calibrate, umap, umap_poll) — `umap`/`umap_poll` power Brain Nebula™
- **Privacy**: 100% local. No cloud, no accounts, no telemetry, no analytics. Data in CSV + SQLite + HNSW. One optional manual update check (Ed25519 verified)
- **Platform**: Tested on macOS 12+. Should work on Linux (BlueZ) — Linux download not yet released. Windows untested.
- **Languages**: English, Deutsch, Français, Українська, עברית (RTL)
- **License**: GPLv3
- **References**: 61 peer-reviewed papers backing all computed metrics

## Sections

- [Demo](#demo): Full walkthrough video — Bluetooth connection to embedding search
- [How It Works](#how): 4-step flow — Connect → Observe → Record & Label → Search & Compare
- [Quick Start](#quickstart): Up and running in under 90 seconds — download, pair, go
- [Download](#download): macOS download, paper link
- [Features](#features): 12 capabilities including GPU processing, ZUNA embeddings, HNSW search, sleep staging, Brain Nebula™, session comparison, WebSocket API, command palette, multilingual, accessible, private, open formats
- [Comparison](#compare): Feature table vs. Muse Direct, BrainFlow, and OpenBCI GUI
- [Signal Quality](#signal-quality): Per-channel impedance, artifact detection, electrode fit guidance
- [Metrics Catalogue](#metrics): 10 categories, 60+ metrics with formulas, units, ranges, and explanations
- [Electrodes](#electrodes): TP9/AF7/AF8/TP10 placement, brain regions, what each electrode measures, PPG and IMU sensors
- [Windows](#windows): 10 built-in windows — Dashboard, Calibration, Compare, Label, Search, History, Settings, API Status, Help, Setup Wizard
- [API](#api): WebSocket protocol, events, 9 commands, Python and Node.js examples
- [Science References](#science): All 61 papers with authors, journals, and which metrics they back
- [Use Cases](#use-cases): 12 expanded use cases across age groups (6–90+) with specific usage instructions
- [Platform Support](#platforms): macOS (tested), Linux (experimental — download not yet available), Windows (untested)
- [Privacy](#privacy): 8 privacy guarantees
- [Security](#security): What is and isn't in place — sandboxing, signatures, local-only network
- [FAQ](#faq): All 27 questions from the app's Help tab
- [Newsletter](#newsletter): Release announcements signup

## Important Caveats

- NOT a medical device. Not FDA/CE cleared. Not for clinical diagnosis or treatment.
- Consumer/prosumer EEG (4–24 channels depending on device) — not comparable to clinical polysomnography.
- Sleep staging is approximate (4 dry electrodes vs. clinical 19+ wet electrodes).
- SpO₂ from Muse PPG is uncalibrated — trend monitoring only.
- TBR is an ADHD research biomarker (FDA-cleared as diagnostic *aid*) — never a standalone diagnostic.
- For non-commercial research and educational use only.

## Links

- Website: https://skill.example.com
- Download: https://skill.example.com/#download
- Paper: https://doi.org/PAPER_DOI_HERE
- SKILL.md: https://skill.example.com/SKILL.md