eeg streaming

The Systems Engine provides capabilities for streaming EEG data from Instinct headsets. This document explains the key concepts, configuration options, and usage patterns for EEG streaming.

overview

EEG streaming refers to the real-time acquisition and transmission of electroencephalography data from the headset to the Systems Engine and optionally to client applications. The streaming process involves:

1. Configuring the EEG acquisition parameters
2. Initializing the hardware
3. Starting the continuous data flow
4. Processing the incoming data
5. Making the data available through standardized interfaces

eeg signal characteristics

Before configuring streaming, it's important to understand the characteristics of EEG signals:

• Amplitude: Typically 10-100 microvolts (µV)
• Frequency range: Generally 0.1-100 Hz, with specific bands of interest:
  • Delta (0.5-4 Hz) - Associated with deep sleep
  • Theta (4-8 Hz) - Associated with drowsiness, meditation
  • Alpha (8-13 Hz) - Associated with relaxation, closed eyes
  • Beta (13-30 Hz) - Associated with active thinking, focus
  • Gamma (>30 Hz) - Associated with cognitive processing
• Spatial distribution: Different brain regions produce different patterns
• Temporal dynamics: Signal changes over time based on brain activity

stream configuration

Before starting an EEG stream, you can configure various parameters:

channel selection

You can specify which EEG channels (electrodes) to include in the stream:

{
  "channels": [
    "Fp1",
    "Fp2",
    "F7",
    "F3",
    "Fz",
    "F4",
    "F8",
    "T3",
    "C3",
    "Cz",
    "C4",
    "T4",
    "T5",
    "P3",
    "Pz",
    "P4",
    "T6",
    "O1",
    "O2"
  ]
}

You can select:

• A subset of electrodes for specific use cases
• Reference and ground electrodes
• Additional non-EEG channels (e.g., auxiliary inputs)

sampling rate

The sampling rate determines how many data points are collected per second:

{
  "sampleRate": 250
}

Common sampling rates include:

• 250 Hz: Adequate for most applications
• 500 Hz: Higher temporal resolution
• 1000 Hz: Research-grade temporal resolution
• 2000 Hz: Very high temporal resolution for specialized applications

Higher sampling rates provide better temporal resolution but consume more bandwidth and storage.

digital signal processing (dsp)

Various digital filters can be applied to the EEG data during streaming:

{
  "filters": {
    "highpass": 0.5,
    "lowpass": 50,
    "notch": 60
  }
}

Common filter types include:

• Highpass filter: Removes low-frequency drift (e.g., 0.5 Hz)
• Lowpass filter: Limits high-frequency content and noise (e.g., 50 Hz)
• Notch filter: Removes power line interference (50 or 60 Hz)
• Band-pass filter: Combination of highpass and lowpass

buffer size

The buffer size controls how much data is accumulated before transmission:

{
  "bufferSize": 20
}

This value is typically specified in number of samples or time (milliseconds).

starting a stream

To start an EEG stream:

POST /stream/start

Example request:

{
  "sampleRate": 250,
  "channels": [
    "Fp1",
    "Fp2",
    "F7",
    "F3",
    "Fz",
    "F4",
    "F8",
    "C3",
    "Cz",
    "C4",
    "P3",
    "Pz",
    "P4",
    "O1",
    "O2"
  ],
  "filters": {
    "highpass": 0.5,
    "lowpass": 50,
    "notch": 60
  },
  "bufferSize": 20,
  "metadata": {
    "subject": "subject-001",
    "session": "session-001",
    "experimenter": "researcher-name"
  }
}

The response includes a unique stream identifier:

{
  "success": true,
  "streamId": "eeg-stream-123456",
  "config": {
    "sampleRate": 250,
    "channels": ["Fp1", "Fp2", "..."],
    "filters": {
      "highpass": 0.5,
      "lowpass": 50,
      "notch": 60
    }
  },
  "status": "streaming"
}

accessing stream data

The Systems Engine provides multiple ways to access the streaming EEG data:

websocket interface

The most common method is through a WebSocket connection:

ws://localhost:42069/stream/{streamId}

Data is typically streamed in JSON format:

{
  "timestamp": 1620000000000,
  "data": [
    [-12.5, 25.3, 15.7, -5.2, ...],  // Sample 1
    [-11.8, 24.9, 16.1, -5.5, ...],  // Sample 2
    ...
  ],
  "channels": ["Fp1", "Fp2", "F7", "..."]
}

http polling

For applications where WebSockets aren't suitable, you can poll for data:

GET /stream/{streamId}/data?limit=100

This endpoint returns the most recent data (up to the specified limit).

direct piping to streams engine

You can connect the EEG stream directly to a Streams Engine pipeline for processing:

POST /stream/{streamId}/pipe

Example request:

{
  "target": {
    "host": "localhost",
    "port": 42069,
    "streamId": "processing-stream-123"
  },
  "format": "edf",
  "metadata": {
    "includeChannelMetadata": true
  }
}

stream metadata

Streams include metadata to provide context for the EEG data:

{
  "metadata": {
    "device": {
      "type": "Instinct EEG-32",
      "serialNumber": "IN-32-12345",
      "firmware": "v2.1.3"
    },
    "acquisition": {
      "startTime": 1620000000000,
      "sampleRate": 250,
      "channels": ["Fp1", "Fp2", "..."],
      "filters": {
        "highpass": 0.5,
        "lowpass": 50,
        "notch": 60
      }
    },
    "subject": {
      "id": "subject-001",
      "demographic": {}
    },
    "experiment": {
      "id": "experiment-001",
      "session": "session-001",
      "condition": "resting-state"
    }
  }
}

stopping a stream

To stop an active EEG stream:

POST /stream/{streamId}/stop

Example response:

{
  "success": true,
  "streamId": "eeg-stream-123456",
  "status": "stopped",
  "duration": 300.5,
  "samples": 75125
}

stream events

The streaming interface also provides events related to EEG data:

impedance updates

If impedance monitoring is enabled during streaming:

{
  "type": "impedance",
  "timestamp": 1620000010000,
  "data": {
    "Fp1": 10.2,
    "Fp2": 8.5,
    "...": "..."
  }
}

quality indicators

Stream quality monitoring events:

{
  "type": "quality",
  "timestamp": 1620000020000,
  "data": {
    "overall": 0.92,
    "channels": {
      "Fp1": 0.87,
      "Fp2": 0.95,
      "...": "..."
    }
  }
}

system events

System-related events affecting the stream:

{
  "type": "system",
  "timestamp": 1620000030000,
  "eventType": "battery_low",
  "level": "warning",
  "message": "Headset battery below 20%"
}

stream status

You can check the status of an active stream:

GET /stream/{streamId}/status

Example response:

{
  "streamId": "eeg-stream-123456",
  "status": "streaming",
  "startTime": 1620000000000,
  "duration": 125.5,
  "samples": 31375,
  "sampleRate": 250,
  "channels": ["Fp1", "Fp2", "..."],
  "dataRate": {
    "samplesPerSecond": 250,
    "bytesPerSecond": 12000
  },
  "clients": 3,
  "recording": true,
  "recordingId": "rec-789012"
}

multiple streams

The Systems Engine supports multiple simultaneous streams with different configurations:

• Different channel subsets
• Different sampling rates
• Different filter settings
• Different data formats

This allows for specialized processing of the same EEG data.

performance considerations

When working with EEG streams:

1. Bandwidth: Higher sampling rates and more channels require more bandwidth
2. Latency: Buffer size affects the trade-off between latency and network efficiency
3. Processing Power: Real-time filtering and analysis require computational resources
4. Storage: Extended streaming sessions can generate large amounts of data

best practices

1. Select Appropriate Sampling Rate: Choose based on the frequencies of interest in your application
2. Filter Appropriately: Apply filters to improve signal quality but avoid distortion
3. Monitor Impedance: Check electrode impedances before and during streaming
4. Buffer Management: Set buffer sizes appropriate for your application's latency requirements
5. Error Handling: Implement robust error handling for connection issues
6. Multiple Clients: Be aware of the performance impact when multiple clients consume the same stream

next steps

• Learn about Impedance Checking
• Explore the System Operations API