1 of 11

Records

After you opened a with a headset, you can create a record. A record is a permanent object to store data from an EMOTIV headset. You can associate a to a record. You can add one or more to a record.

Unlike a , a record is a permanent object. It is stored on the hard drive and then can be synchronized to the EMOTIV cloud. The configuration can let you decide if the records of a user are uploaded to the cloud or not.

Record lifetime

createRecord

This method is to create a new record.

You must create and activate a session before you call this method. See for details.

stopRecord

This method is to stop a record that was previously started by . This will set the end date time of the record to the current date time.

Parameters

updateRecord

This method is to update a record. You can update its title, description and its tags.

Your application cannot update a record that was created by another application.

Parameters

Name

Result

The result is a .

Examples

Update the tags and the description.

deleteRecord

This method is to delete one or more records.

The records will be deleted from the local computer, but also from the EMOTIV account of the user in the cloud, and from any computer where the user is logged in.

Your application cannot delete a record that was created by another application.

Deleting a record is irreversible. There is no way to recover a deleted record.

exportRecord

This method is to export one or more records to EDF or CSV files.

You can export the raw EEG data, the motion data, the performance metrics and the band powers. The available data streams depend on the license of the record. You can check the field licenceScope in the Record object to know which data streams are available.

By default, you can only export the records that were created by your application. If you want to export a record that was created by another application (e.g. Emotiv PRO or EMOTIV LABS) then you must provide the license id of this application in the parameter licenseIds.

In order to export a record created by EMOTIV LABS, the current Cortex user must be the owner of the LABS experiment.

You must before you can export it. If you want to export a record immediately after you stop it then you must wait for the before you try to export.

The format of the exported files is described in .

This method was added in Cortex 2.1.1 to all desktop versions of Cortex. It was added to iOS and Android in Cortex 2.7.0

Parameters

Data streams

The parameter streamTypes must contain one or more values, chosen from this list: "EEG", "MOTION", "PM", "BP". If the format is "EDF" then only "EEG" and "MOTION" are available.

Format and version

Depending on the parameters format and version Cortex will create different files.

Format EDF, no version

This format is identical to the one used in Cortex 1.x

1 EDF file for the EEG and CQ data
1 EDF file for the motion data
1 JSON file for the markers

Format EDFPLUS/BDFPLUS, no version (available since Cortex version 3.7.5)

1 EDF+/BDF+ file for the EEG, CQ and Motion data
1 JSON file for the markers
1 CSV file for the markers if the parameter includeMarkerExtraInfos is true

Format CSV, version V1

This format is identical to the one used in Cortex 1.x

1 CSV file for the EEG and CQ data
1 CSV file for the band powers
1 CSV file for the motion data

Format CSV, version V2

This format is the new format of Cortex 2.x

1 CSV file for all the data streams (EEG, CQ, band powers, motion, PM)
1 JSON file for the markers
1 CSV file for the markers if the parameter includeMarkerExtraInfos is true

Result

The result is an object that includes these fields:

In case of success, you get an object with these fields:

In case of failure, you get an object with these fields:

Examples

EDF

CSV V1

CSV V2

queryRecords

This method returns a list of records owned by the current user. By default, you only get the records created by your application. To query the records from another application, you must filter by the license id of this application.

Parameters

Name

Type

Required

Depending on the query, this method may return a lot of records. To avoid performance issues, you should always set an offset and a limit.

query

The query object can contain one or more of these fields:

orderBy

The orderBy parameters is an array of objects, similar to the orderBy clause of a SQL request.

Each object must have a single attribute. The key of the attribute is the name of record's field you want to order by. The value of the attribute must be "ASC" or "DESC", to order is ascending or descending order.

For example, to order the records by their start date, in descending order, you must use the object {"startDatetime":"DESC"}. To sort the records by title, in alphabetical order, you must use {"title":"ASC"}.

You can order the records by these fields: title, description, startDatetime, modifiedDatetime, duration, subjectName, applicationId. The option to order by applicationId was added in Cortex 2.5.0

limit and offset

These parameters are to implement pagination. It useful if you want to display the records in a UI. You must order the results to use these parameters.

First you should call this method with an offset of zero, and a limit of X. In the response, check the value of count. If count is greater than the limit, then you should call this method again with an offset of X. And then with an offset of 2*X, 3*X... until you get all the records for your query.

Result

The result is an object that includes these fields:

Examples

Get the 10 most recent records created by EmotivPRO.

Get some records using a keyword.

getRecordInfos

This method returns a list of records, selected by their id.

Parameters

Name

Type

Required

Description

Result

The result is an array of , including the markers of each record.

Examples

configOptOut

This method is to configure the opt-out feature for the records. This feature lets you decide if the records created by your application on the local machine are uploaded to the EMOTIV cloud or not.

If the opt-out is on (ie the parameter newOptOut is true) then the records created on this machine will not be uploaded to the cloud. If the opt-out is off (ie the parameter newOptOut is false) then the records created on this machine will be uploaded to the cloud.

Please note that changing the opt-out configuration has no effect on the records previously created on the local computer. It only affects the records created after the change. Changing the opt-out configuration is not retroactive.

The opt-out configuration is linked to your application. Changing the configuration only affects the records created by your application. This has no effect on the records created by other applications.

The opt-out configuration is also linked to the EmotivID of the user. The opt-out can be turned on or off for each EmotivID. It is off by default.

You can check the field localOnly of a to know if this record will stay on the local machine, or if it will be uploaded to the EMOTIV cloud.

Some don't let you change the opt-out configuration and force the opt-out to be always on or always off. See the possible configurations below for details.

This method was added in Cortex 2.2.1

Parameters

Result

The result is an object describing the current opt-out configuration. It includes these fields:

Possible Configurations

Here is an overview of the possible configurations:

Examples

Get the current configuration

Change the configuration

requestToDownloadRecordData

This method is to ask Cortex to download the EEG/motion/CQ/detections data of a record from the EMOTIV cloud.

Use case

Suppose that the user has installed Cortex on 2 computers, named computer A and computer B. On computer A, the user creates a record, and Cortex uploads this record to the EMOTIV cloud.

Then, on computer B, Cortex automatically downloads the metadata of this record, ie its name, description, start time, end time, etc... So this record is visible when you call methods like or

Record object

Some methods of the API return one or more record objects, for example queryRecords.

Description

A record object includes these fields:

Name

Depending on how you get the record, it may contains an additional field for the markers:

syncStatus

Record object returned from getRecordInfos has an additional field syncStatus:

Available values for status:

"pending": the record is waiting for being downloaded.
"downloading": the record's data is being downloaded. Check progress in percent field.
"downloaded": the record's data is on both the Emotiv Cloud and the local machine.

For example:

A record is created but waiting for being uploaded to the Emotiv Cloud:

A record is waiting for downloaded from the Emotiv Cloud:

A record is created and is uploading to the Emotiv Cloud:

Examples

exportRecord

This method is to export one or more records to EDF or CSV files.

In order to export a record created by EMOTIV LABS, the current Cortex user must be the owner of the LABS experiment.

You must before you can export it. If you want to export a record immediately after you stop it then you must wait for the before you try to export.

The format of the exported files is described in .

This method was added in Cortex 2.1.1 to all desktop versions of Cortex. It was added to iOS and Android in Cortex 2.7.0

Parameters

Data streams

The parameter streamTypes must contain one or more values, chosen from this list: "EEG", "MOTION", "PM", "BP". If the format is "EDF" then only "EEG" and "MOTION" are available.

Format and version

Depending on the parameters format and version Cortex will create different files.

Format EDF, no version

This format is identical to the one used in Cortex 1.x

1 EDF file for the EEG and CQ data
1 EDF file for the motion data
1 JSON file for the markers

Format EDFPLUS/BDFPLUS, no version (available since Cortex version 3.7.5)

1 EDF+/BDF+ file for the EEG, CQ and Motion data
1 JSON file for the markers
1 CSV file for the markers if the parameter includeMarkerExtraInfos is true

Format CSV, version V1

This format is identical to the one used in Cortex 1.x

1 CSV file for the EEG and CQ data
1 CSV file for the band powers
1 CSV file for the motion data

Format CSV, version V2

This format is the new format of Cortex 2.x

1 CSV file for all the data streams (EEG, CQ, band powers, motion, PM)
1 JSON file for the markers
1 CSV file for the markers if the parameter includeMarkerExtraInfos is true

Result

The result is an object that includes these fields:

In case of success, you get an object with these fields:

In case of failure, you get an object with these fields:

Examples

EDF

CSV V1

CSV V2

{ "id": 1, "jsonrpc": "2.0", "result": { "count": 9, "limit": 2, "offset": 0, "records": [ { "applicationId": "com.xxx.cortex-examples", "applicationVersion": "1.0", "description": "", "endDatetime": "2020-03-09T15:59:34.794356+07:00", "experimentId": 0, "headbandPosition": null, "licenseId": "xxx", "licenseScope": [ "pm", "eeg" ], "localOnly": false, "markers": [ { "endDatetime": "2020-03-09T15:59:09.680802+07:00", "extras": {}, "label": "test1", "port": "Cortex Example", "startDatetime": "2020-03-09T15:59:09.680802+07:00", "type": "instance", "uuid": "ba8ed3a9-3e0b-4a17-9227-96ae05fa1767", "value": 41 }, { "endDatetime": "2020-03-09T15:59:25.873059+07:00", "extras": {}, "label": "test2", "port": "Cortex Example", "startDatetime": "2020-03-09T15:59:16.867054+07:00", "type": "interval", "uuid": "2cfe93cc-f242-49d6-8165-7b13147e7c10", "value": 42 } ], "ownerId": "94f7c5ed-3d24-4c29-8243-96aa7db80d4a", "startDatetime": "2020-03-09T15:59:04.344671+07:00", "subject": { "subjectName": "Bob" }, "tags": [], "title": "Cortex Examples C++", "uuid": "b26f35c3-42ee-4612-a9b9-09af04c2ba37" }, { "applicationId": "com.xxx.cortex-examples", "applicationVersion": "1.0", "description": "", "endDatetime": "2020-03-09T15:58:37.792248+07:00", "experimentId": 0, "headbandPosition": null, "licenseId": "xxx", "licenseScope": [ "pm", "eeg" ], "localOnly": false, "markers": [ { "endDatetime": "2020-03-09T15:58:12.875515+07:00", "extras": {}, "label": "test1", "port": "Cortex Example", "startDatetime": "2020-03-09T15:58:12.875515+07:00", "type": "instance", "uuid": "e22d46a0-480a-452a-a65e-d6b4448e3f7b", "value": 41 }, { "endDatetime": "2020-03-09T15:58:28.872019+07:00", "extras": {}, "label": "test2", "port": "Cortex Example", "startDatetime": "2020-03-09T15:58:20.873850+07:00", "type": "interval", "uuid": "c8fd9191-43da-4e28-970d-bf9f24404c8a", "value": 42 } ], "ownerId": "94f7c5ed-3d24-4c29-8243-96aa7db80d4a", "startDatetime": "2020-03-09T15:58:08.036369+07:00", "subject": { "subjectName": "Marie" }, "tags": [], "title": "Cortex Examples C++", "uuid": "33d2c56a-4cdf-4e2b-a5bb-db127f838248" } ] } }

Records

hashtagRecord lifetime

createRecord

hashtag

stopRecord

hashtagParameters

updateRecord

hashtagParameters

hashtagResult

hashtagExamples

deleteRecord

exportRecord

hashtagParameters

hashtagData streams

hashtagFormat and version

hashtagFormat EDF, no version

hashtagFormat CSV, version V1

hashtagFormat CSV, version V2

hashtagResult

hashtagExamples

hashtagEDF

hashtagCSV V1

hashtagCSV V2

queryRecords

hashtagParameters

hashtagquery

hashtagorderBy

hashtaglimit and offset

hashtagResult

hashtagExamples

getRecordInfos

hashtagParameters

hashtagResult

hashtagExamples

configOptOut

hashtagParameters

hashtagResult

hashtagPossible Configurations

hashtagExamples

hashtagGet the current configuration

hashtagChange the configuration

requestToDownloadRecordData

hashtagUse case

Record object

hashtagDescription

hashtagsyncStatus

hashtagExamples

exportRecord

hashtagParameters

hashtagData streams

hashtagFormat and version

hashtagFormat EDF, no version

hashtagFormat CSV, version V1

hashtagFormat CSV, version V2

hashtagResult

hashtagExamples

hashtagEDF

hashtagCSV V1

hashtagCSV V2

updateRecord

hashtagParameters

hashtagResult

hashtagExamples

Records

hashtagRecord lifetime

createRecord

hashtag

stopRecord

hashtagParameters

deleteRecord

requestToDownloadRecordData

hashtagUse case

hashtagResult

hashtagExamples

hashtagResult

hashtagExample

hashtagResult

hashtagExamples

hashtagParameters

hashtagResult

Record lifetime

Parameters

Parameters

Result

Examples

Parameters

Data streams

Format and version

Format EDF, no version

Format CSV, version V1

Format CSV, version V2

Result

Examples

EDF

CSV V1

CSV V2

Parameters

query

orderBy

limit and offset

Result

Examples

Parameters

Result

Examples

Parameters

Result

Possible Configurations

Examples

Get the current configuration

Change the configuration

Use case

Description

syncStatus

Examples

Parameters

Data streams

Format and version

Format EDF, no version

Format CSV, version V1

Format CSV, version V2

Result

Examples

EDF

CSV V1

CSV V2

Parameters

Result

Examples

Record lifetime

Parameters

Use case

Result

Examples

Result

Example

Result

Examples

Parameters

Result

Example

Parameters

query

orderBy

limit and offset

Result

Examples

Description

syncStatus

Examples

Parameters

Result

Examples

Parameters

Result

Possible Configurations

Examples

Get the current configuration

Change the configuration