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
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
Usage: recordMentalState or {"command": "recordMentalState"}
RunEraseMentalState - Stops recognition
Arguments
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
Returns
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"}