🧠 neuro-rec

Real-time content recommendation driven by brainwaves — reads EEG emotion states from an Emotiv headset and surfaces personalized video suggestions on the fly.

Built on the Emotiv Cortex SDK, the system runs as a microservice pair: one service processes raw EEG signals into emotion states, the other maps those states to a continuously-updated recommendation feed.

How it works

1. EEG → Emotion — Emotiv headset streams 7 affective metrics (engagement, excitement, stress, relaxation, focus, interest, arousal). A weighted model maps them to 9 emotion classes: Happy · Sad · Angry · Tired · Relaxed · Surprised · Disgusted · Pleased · Neutral
2. Emotion → Content — Each emotion maps to a content category with intensity thresholds (>40% required to trigger a switch). A user-learning layer tracks likes, skips, and shares to personalise over time
3. Optional: EEG → Music — Parallel audio service uses Google Lyria to generate ambient music matching the current emotion state

Architecture

Emotiv Headset
      │  Cortex SDK (WebSocket)
      ▼
brain_processor.py  ──(HTTP)──▶  recommendation_service.py  ──▶  Client / Frontend
      │                                  │
      └──(HTTP)──▶  audio_service.py     └─ user_learning.py (feedback loop)
                   (Google Lyria)

Stack

• Hardware: Emotiv EPOC X / EPOC Flex (Cortex SDK v3)
• EEG processing: Python · numpy · websocket-client
• Services: Flask (port 8081) · FastAPI/Uvicorn (port 8080)
• Music generation: Google Lyria real-time API
• Audio playback: sounddevice (48 kHz stereo)

Quick start

# 1. Install dependencies
pip install -r EEG/requirements.txt
pip install -r recommandation/requirements.txt

# 2. Add your keys to .env
EMOTIV_CLIENT_ID=...
EMOTIV_CLIENT_SECRET=...
GOOGLE_API_KEY=...          # optional – for music generation

# 3. Run
python start_recommendation_only.py   # recommendation only
python start_integrated_system.py     # + music generation

Requires the Emotiv Cortex App running locally and a connected Emotiv headset.