NeuroPlayPro API reference 1.9.1

1. Intro

NeuroPlayPro software works as a server and is available for HTTP requests and WebSockets connection.

This page provides live data requests - press Run near each command.

HTTP interaction parts are marked with blue outlines.
NeuroPlayPro is available across your local network as HTTP server at "http://127.0.0.1:2336"

WebSockets interaction parts are marked with green outlines.
WebSocket server is available on port "1336"
The server works in two modes:
- JSON (e.g. '{"command":"meditation"}')
- simple text (e.g. "meditation") which corresponds to HTTP commands

All commands are case insensitive (e.g. "RAWDATA", "rawData", "RawData").

NeuroPlayPro server's output will be in JSON format, which will always have "result" and "time", where "result" will be true if the command was performed successfully.
{ "result": true, "time": "2020-10-25 10:20:30" }

2. Device

Data frequency depends on the number of selected channels. For devices with higher amount of supported channels it is possible to select less channels for greater data frequency.

Channels	Frequency	Names
8 channels	125 Hz	O1, P3, C3, F3, F4, C4, P4, O2
6 channels	125 Hz	O1, T3, Fp1, Fp2, T4, O2
1 channel	1000 Hz	O1

RunStartSearch - Starts device searching procedure

Usage: startSearch or {"command": "startSearch"} RunStopSearch - Stops device searching procedure

Usage: stopSearch or {"command": "stopSearch"} Example outputRunListDevices - Get a list of available devices.

Returns

• devices - list of available devices

Usage: listDevices or {"command": "listDevices"} Example outputRunDeviceCount - Returns the amount of found devices during search

Returns

• deviceCount - number of devices

Usage: deviceCount or {"command": "deviceCount"} RunGetDeviceInfo - Get device information about a single device

Arguments

• SN - Serial number of NeuroPlay device
• index - Index of NeuroPlay device (from 'listDevices' command)

Returns

• info - device information

Usage: getDeviceInfo or {"command": "getDeviceInfo"} RunStartDevice - Starts device by serial number (use 'startDevice?SN=XXXX') or by index from 'listdevices' command (use 'startDevice?index=X')

Arguments

• SN - Serial number of NeuroPlay device
• channels - [Optional] Number of channels (less channels - higher data frequency)
• index - Index of NeuroPlay device (from 'listDevices' command)

Usage: startDevice or {"command": "startDevice"} Example outputRunCurrentDeviceInfo - Information about current device, e.g. current sampling rate (frequency), channel names and signal quality

Returns

• BSF - band-stop filter (BSF) value
• BSF2 - secondary BSF value (Hz)
• HPF - high-pass filter (HPF) value (Hz)
• LPF - low-pass filter (LPF) value (Hz)
• currentChannels - number of channels
• currentChannelsNames - list of channels names
• currentFrequency - current device frequency
• device - device information
• isRecording - shows if recording is in progress
• quality - per channel quality array in percents, where <20 - bad signal, <90 - average quality, >90 - good (acceptable) signal
• recordDuration - duration of the current record
• searching - is the application currently searching for devices

Usage: currentDeviceInfo or {"command": "currentDeviceInfo"} RunCurrentDevicesInfo - Information about all current devices, e.g. current sampling rate (frequency), channel names and signal quality

Returns

• devices - is the application currently searching for devices

Usage: currentDevicesInfo or {"command": "currentDevicesInfo"} RunMakeFavorite - Makes selected device favorite

Arguments

• value - name of the device you want to make favorite

Usage: makeFavorite or {"command": "makeFavorite"} RunGetFavoriteDeviceName - Returns favorite device name

Returns

• device - favorite device name

Usage: getFavoriteDeviceName or {"command": "getFavoriteDeviceName"} RunSetMontage

Arguments

• channelnames - Array of channels names

Usage: setMontage or {"command": "setMontage"}

3. Storage time and 'Data grab mode'

All data comes channel-wise. To get channel names use the "CurrentDeviceInfo" command.Data samples are stored for 'StorageTime' seconds, 10 seconds by default.'Grab...' commands get data and clear the queue, so the next time it is called - it returns only newly added samples.Some commands (e.g. RawData and '...History') require enabled 'Data Grab Mode' in which the software stores data for several seconds. By default this feature is off for memory/processor optimisations.

RunEnableDataGrabMode - Enables grab mode

Usage: enableDataGrabMode or {"command": "enableDataGrabMode"} RunDisableDataGrabMode - Disables grab mode

Usage: disableDataGrabMode or {"command": "disableDataGrabMode"} RunSetDataStorageTime - Sets storage time (seconds) for data (including the data for 'DataGrabMode')

Arguments

• value - 1-3600 seconds

Usage: setDataStorageTime or {"command": "setDataStorageTime"} RunGetDataStorageTime - Current storage time (seconds) for data (including the data for 'DataGrabMode')

Returns

• storageTime - Amount of storage time in seconds

Usage: getDataStorageTime or {"command": "getDataStorageTime"}

Filters

Original data from the device is processing by several filters:

• Low-pass filter (LPF) - minifies occurence of signals below it's value in Hz. Default is 40 Hz.
• Hi-pass filter (HPF) - minifies occurence of signals over it's value in Hz. Default is 2 Hz.
• Band stop filter (BSF) - strictly minifies signals equal to it's value in Hz. Default is 50 Hz.

If a filter value is "0" - it is turned off.

RunGetFilters - Returns filters' values

Returns

• BSF - BSF
• BSF2 - BSF
• HPF - HPF
• LPF - LPF

Usage: getFilters or {"command": "getFilters"} RunSetFilters - Sets filter settings

Usage: setFilters or {"command": "setFilters"} RunSetLPF - Low-pass filter

Arguments

• value - Floating point value of filter (0..100 Hz)

Usage: setLPF or {"command": "setLPF"} RunSetBSF - Band-stop filter

Arguments

• value - Floating point value of filter (0..100 Hz)

Usage: setBSF or {"command": "setBSF"} RunSetHPF - High-pass filter

Arguments

• value - Floating point value of filter (0..100 Hz)

Usage: setHPF or {"command": "setHPF"}

Data samples

RunFilteredData - Get channel-wise filtered samples (not more than 'StorageTime' ago) (if the device is on)

Usage: filteredData or {"command": "filteredData"} RunGrabFilteredData - Grab (clear queue) channel-wise filtered samples (not more than 'StorageTime' ago) (if the device is on and 'DataGrabMode' is enabled)

Usage: grabFilteredData or {"command": "grabFilteredData"} RunRawData - Grab (clear queue) channel-wise unfiltered device samples (not more than 'StorageTime' ago) (if the device is on)

Usage: rawData or {"command": "rawData"} RunGrabRawData - Get channel-wise unfiltered device samples (not more than 'StorageTime' ago) (if the device is on and 'DataGrabMode' is enabled)

Usage: grabRawData or {"command": "grabRawData"} RunAddEDFAnnotation - Adding annotation to EDF

Arguments

• duration - Duration in msecs
• pos - Position in msecs
• text - Text for annotation

Usage: addEDFAnnotation or {"command": "addEDFAnnotation"}

Spectrum

Spectrum is calculated via FFT of the filtered data. The dimension is in uV

RunLastSpectrum - Returns last calculated spectrum in uV

Returns

• deviceFrequencyHz - Current device frequency
• frequencyStepHz - Spectrum discrete step
• hanningPercent - Spectrum discrete step
• spectrum - Channel-wise data of spectrum in uV
• windowSeconds - Data window size
• windowStepSeconds - Spectrum calculation step (time diff until next calculation)

Usage: lastSpectrum or {"command": "lastSpectrum"} RunGrabSpectrum - Returns spectrum history and clears the buffer. The buffer contains data not older than 'StorageTime' seconds. Data grab mode should be enabled via 'EnableDataGrabCommand'

Returns

• deviceFrequencyHz - Current device frequency
• frequencyStepHz - Spectrum discrete step
• hanningPercent - Spectrum discrete step
• spectrum - Array of { t: timestamp, d: data } of channel-wise spectrum in uV
• windowSeconds - Data window size
• windowStepSeconds - Spectrum calculation step (time diff until next calculation)

Usage: grabSpectrum or {"command": "grabSpectrum"} RunGetSpectrum - Returns spectrum history not older than 'StorageTime' seconds. Data grab mode should be enabled via 'EnableDataGrabCommand'

Returns

• deviceFrequencyHz - Current device frequency
• frequencyStepHz - Spectrum discrete step
• hanningPercent - Spectrum discrete step
• spectrum - Array of { t: timestamp, d: data } of channel-wise spectrum in uV
• windowSeconds - Data window size
• windowStepSeconds - Spectrum calculation step (time diff until next calculation)

Usage: getSpectrum or {"command": "getSpectrum"}

Rhythms

By default the software calculated standard rhythms (alpha, beta, delta, gamma, theta) and outputs their respective percentage (of overall spectrum) values.

RunRhythms - Get last 'alpha', 'beta', 'delta', 'gamma', 'theta' and 't' for timestamp for every device channel (if the device is on and metering started)

Returns

• alpha - alpha rhythm
• beta - beta rhythm
• delta - delta rhythm
• gamma - gamma rhythm
• t - timestamp
• theta - theta rhythm

Usage: rhythms or {"command": "rhythms"} RunRhythmsHistory - Get timestamped list of 'alpha', 'beta', 'delta', 'gamma', 'theta' and 't' for timestamp for every device channel (if the device is on and metering started and 'DataGrabMode' is enabled)

Usage: rhythmsHistory or {"command": "rhythmsHistory"}

Recording

The software starts recording filtered data to EDF and other data (rhythms, meditation/concentration) to NPD file (stands for "NeuroPlayData", really just a "CSV")

RunStartRecord - Starts data recording

Arguments

• path - Filepath of the main .edf file

Usage: startRecord or {"command": "startRecord"} RunStopRecord

Returns

• baseName - File basename
• files - An array of recorded files [{'type': 'edf', 'data': 'BINARY_IN_BASE64'}]

Usage: stopRecord or {"command": "stopRecord"} RunPauseRecord

Usage: pauseRecord or {"command": "pauseRecord"} RunContinueRecord

Usage: continueRecord or {"command": "continueRecord"} RunAddFileToRecord

Usage: addFileToRecord or {"command": "addFileToRecord"} RunGetUserRecords - Returns user's records

Returns

• files - Array of records files

Usage: getUserRecords or {"command": "getUserRecords"} RunRecords - Returns records

Returns

• files - Array of records files

Usage: records or {"command": "records"}

4. BCI: meditation, concentration, mental states

Standard BCI modes in NeuroPlayPro are:

Meditation

Percentage of how much the user is relaxed, meditated (high alpha)

Example outputRunMeditation - Get current 'meditation' percentage ('-1' if the device is unavailable)

Returns

• meditation - Percent of 'meditation'

Usage: meditation or {"command": "meditation"} Example outputRunMeditationHistory - Get timestamped list of 'meditation' percentages (if the device is on and metering started and 'DataGrabMode' is enabled)

Usage: meditationHistory or {"command": "meditationHistory"}

Concentration

Percentage of how much the user is focused

Example outputRunConcentration - Get current 'concentration' percentage ('-1' if the device is unavailable)

Returns

• concentration - Percent of 'concentration'

Usage: concentration or {"command": "concentration"} Example outputRunConcentrationHistory - Get timestamped list of 'meditation' percentages (if the device is on and metering started and 'DataGrabMode' is enabled)

Usage: concentrationHistory or {"command": "concentrationHistory"}

Mental states

Discrete brain state recognition (states are recorded for every user and every session separately)

RunMentalStateStatus - Mental state recognition status

Returns

• canBeTrained - Is recorded data sufficient to begin training
• isRecognizing - Is recognition on
• lastState - Last recognized state
• maxStates - Amount of available states to be used
• recognitionState - Current recongition mode state
• recordedStates - Current available mental state records
• trainingError - [Optional] A list of pretraining and training errors

Usage: mentalStateStatus or {"command": "mentalStateStatus"} RunRecordMentalState - Starts recording a mental state file (10 seconds by default). Stops recognition if need be.

Arguments

• index - Index of state

Usage: recordMentalState or {"command": "recordMentalState"} RunEraseMentalState - Stops recognition

Arguments

• index - Index of state

Usage: eraseMentalState or {"command": "eraseMentalState"} RunStartMentalStateRecognition - Starts mental state recognition training process

Usage: startMentalStateRecognition or {"command": "startMentalStateRecognition"} RunStopMentalStateRecognition - Stops recognition

Usage: stopMentalStateRecognition or {"command": "stopMentalStateRecognition"} RunGetMentalStateFile - Returns a mental state file as is (HTTP only) or encoded in base64 (for WebSockets or if argument 'base64=true' is provided)

Arguments

• base64 - [Optional] Returns encoded in base64 format (HTTP and WebSockets), otherwise as a file (HTTP only)
• index - Index of state

Usage: getMentalStateFile or {"command": "getMentalStateFile"}

Shorthand

Example outputRunBCI - Get all available control values, by default the 'meditation' and 'concentration' values

Returns

• concentration - Percent of 'concentration'
• meditation - Percent of 'meditation'

Usage: bci or {"command": "bci"} RunBCIs - Get all available control values, by default the 'meditation' and 'concentration' values for all nodes

Returns

• results - Array of BCI results for all nodes

Usage: bCIs or {"command": "bCIs"}

5. Miscellaneous

Example outputRunHelp - Returns all available commands with their descriptions and arguments

Usage: help or {"command": "help"} RunVersion - Returns version of NeuroPlayPro software

Returns

• version - Application version

Usage: version or {"command": "version"} Example outputRunControlOptions - Provides information about all proportional and discrete controls available. These values can be fetched by the 'bci' command

Returns

• controls - An array of {'name':'CONTROLNAME', 'type':'proportional'/'discrete'}

Usage: controlOptions or {"command": "controlOptions"} RunClose - Closes the applcation

Usage: close or {"command": "close"} RunAddLogItem - Log the text

Arguments

• text - Message to log
• type - [Optional] Type of message

Usage: addLogItem or {"command": "addLogItem"} RunScreenInfo

Returns

• screens - Array of screens infos

Usage: screenInfo or {"command": "screenInfo"} RunGetAllSettings - Get all the settings

Returns

• settings - Application settings
• virtualDeviceSettings - Virtual device settings

Usage: getAllSettings or {"command": "getAllSettings"} RunGetSettings - Returns settings for a key

Arguments

• key - Key for the value

Returns

• value - Requested value

Usage: getSettings or {"command": "getSettings"} RunSetSettings - Sets the setting value by key

Arguments

• key - Key for the value
• value - New value

Usage: setSettings or {"command": "setSettings"}