FAQ

  • NB: Document was last updated on 10.06.2021 (latest OpenViBE was 3.1.0)

    General

    OpenViBE is a software platform that enables to design, test and use Brain-Computer Interfaces (BCIs). OpenViBE can also
    be used as a generic realtime EEG acquisition, processing and visualization system.

    In more detail, BCIs are communication systems that enable users to send commands to computers only by means of their
    brain activity. One potential application of BCIs is to provide alternative communication channels for disabled people,
    but BCIs can also be attempted for rehabilitation or neurofeedback training. Although an exciting and active research
    field, further improvements in BCI techniques are needed before they can be considered as viable alternatives for
    traditional controllers such as mouse or keyboard. Currently BCI techniques often rely on EEG (electroencephalogram)
    signals, but are not limited to such.

    Initially, OpenViBE stood for “Open Virtual Brain Environment”, as it was intended to provide BCI-based control of
    Virtual Reality (VR) platforms. We no longer want to limit the use of OpenViBE to Virtual Environments. So you could now
    just take OpenViBE as a noun, it is no longer an acronym :)

    • Version 0.16.0 and later: Fully AGPL-3, see the description here.
    • Version 0.15.0 and earlier: basically L-GPL, see Licence for details about this license. Some
      OpenViBE plugins are based on GPL libraries. Consequently, those plugins are GPL.

    OpenViBE development began in 2006 and keeps being developed in the scope of various projects and by various contributors. Today, OpenViBE offers many complete example processing pipelines for BCI
    and EEG contexts. OpenViBE has been successfully used by various authors in different contexts, including motor imagery
    interactions and neurofeedback experiments. Examples of successful implementations of many well-known BCI paradigms
    exist. The modular plugin architecture allows the integration of new functionalities while limiting the number of
    necessary changes to the APIs. Additionally, external contributions enlarging OpenViBE functionalities are warmly
    welcomed.

    Since 2015, from OpenViBE v1.0.0, we have considered OpenViBE kernel and main tools as stable. Some individual modules
    may remain in a prototype stage or categorized as unstable (for definition see here).

    Later in 2016-2018, OpenViBE v2.0.0 and v2.0.1 SDK and Designer components were further developed between Inria and
    Mensia Technologies using processes compatible with medical certification goals and strict quality assurance. This
    allowed the making of a ADHD home
    treatment solution
    based on OpenViBE technology.

    In 2018, we intend to migrate OpenViBE to a new, even more open consortium based
    management/development model. If you are interested in the future progress of OpenViBE, your lab/organization could
    consider joining the consortium or supporting it otherwise.

    A new stable version of OpenViBE is typically released twice per year, but enthusiasts are
    welcome to checkout development snapshots from our code repository at any time.

    There are many ways in which you can participate in the OpenViBE scene:

    • provide funding and vision : consider joining the OpenViBE consortium
    • develop stuff : you can implement and contribute new boxes, new algorithms, new drivers
    • show-case your work : you can show-case scenarios, processing pipelines and videos to the community (e.g. forum,
      youtube)
    • provide better docs : you can enhance the existing documentation, write new tutorials, or blogs
    • test things : you can test new features, new operating systems, new hardware, and report the findings (e.g.
      forum, tracker)
    • communicate : you can discuss related matters on the forum and answer questions of others
    • wrap it up : you can build RPMs, DEBs or whatever package your linux distro uses

    For any contributions intended to be a part of the OpenViBE source tree, you should start by reading the contribution rules. It is also
    possible to highlight your OpenViBE-compatible software/plugins/etc without integration to the main tree. In this case,
    you can use the forum or publish an article about your contribution on the community website.
    If you still have questions, you can also Contact us.

    Please use the following refence to cite OpenViBE in your publications :

    Y. Renard, F. Lotte, G. Gibert, M. Congedo, E. Maby, V. Delannoy, O. Bertrand, A. Lécuyer, “OpenViBE: An Open-Source
    Software Platform to Design, Test and Use Brain-Computer Interfaces in Real and Virtual Environments”, Presence :
    teleoperators and virtual environments, vol. 19, no 1, 2010

    We have collected an incomplete, a somewhat selected list of publications. Don’t hesitate
    to submit yours.

    Fabien Lotte has collected an excellent list of introductory papers, including links. You can find the bibliography here.

    Using OpenViBE

    First, make sure you are using the latest official version of OpenViBE, and not either an old
    version or a third party version.

    A good place to start learning about the platform is to read the existing documentation. Several documents and tutorials are
    dedicated to explaining the use of the platform and its associated tools.

    If still having problems after carefully studying the documentation, one option is to try to contact the community to
    discuss the problem at the OpenViBE forums.

    Several different forks of OpenViBE exist currently. These include NeuroRT and OpenViBE for Brain Products from Mensia
    Technologies (made with a dual license from Inria). Some other derived versions are community efforts that you can find
    on the internet.

    The OpenViBE core dev team cannot answer questions or fix bugs related to versions from third parties. Queries
    regarding such versions should be directed to the providers of those versions. If you write questions about such
    versions on the forum, please explicitly mention it in the post, as otherwise the assumption is
    that you are using the official OpenViBE, which may or may not behave in the same way.

    If you encounter some issue with a third party version AND can reproduce it with the latest
    official OpenViBE version
    , please report it to us. However, even if we fix
    the issue for the mainstream OpenViBE, we cannot say if the fix will get merged to some third party version.

    Sometimes it’s not clear how some particular task can be achieved with OpenViBE. Here the starting point is to read the
    documentation and think how the task could be done with the
    existing boxes. Studying the box tutorials bundled with OpenViBE may help.

    Finally, it can be that OpenViBE simply doesn’t currently provide the capabilities to do what you want. In this case,
    the main way to address the problem is to implement the missing faculties, perhaps by modifying the existing components
    — OpenViBE is open source after all. You can do new features by using either C++, Python, Lua or Matlab. The different approaches have their different pros and
    cons. The existing OpenViBE boxes are implemented in C++ for speed.

    You can also try to contact the community and ask for ideas on the OpenViBE forums. However, if you are a knowledgeable programmer,
    it may be faster to do the work yourself.

    If you have a problem with a scenario you’re working on, please see these instructions for troubleshooting scenarios.

    If you found a bug, please first test that the bug occurs with the latest OpenViBE release or GIT version as available
    from the official OpenViBE website. We do not support older versions
    or third party versions. If the bug occurs with the latest official version, please
    take a few minutes to fill a bug report on our bug tracker. Please do not
    submit patches without reading the contribution rules.

    Before posting about a bug on the forum, please check that your bug is not already listed on the tracker.

    If you really want the bug fixed, it is not enough to briefly tell us that there is one. OpenViBE engineers will need
    the following to attempt to fix the bug:

    • Detailed information of the conditions in which the bug occured. Please describe your OpenViBE
      version
      . Your hardware, operating system, their versions, 32 or 64 bits, and your compiling
      toolchain (if you compiled Openvibe yourself) may all have relevance as well.
    • Please provide detailed steps to reproduce the problem. These steps need to be precisely
      described to allow an engineer to get to the same starting point and observe the issue.
    • If possible, please try to narrow down the possible scope of the problem. If the problem
      occurred with a scenario that you had made or edited yourself and are convinced that the bug is in OpenViBE:
      First, please prune the scenario to the smallest/simplest possible one that reproduces the issue. Then, send us
      the pruned scenario with all the materials that it needs to run. We need the scenario .xml as well as all the
      data and config files that the used boxes rely on.

    Overall, the more information you provide in your bug report, the easier it is for us to try to solve the bug. Note that
    we may be unable to provide support regarding contributed code. For example, many device drivers belong to this
    category. You can see if we can help with a driver from the supported hardware page.
    In the cases where the bug concerns contributed code, we kindly request you to contact the contributing author.

    To learn how to send data or stimulations out from OpenViBE, please see this overview.

    Normally OpenViBE Designer and Acquisition Server GUIs are visible when OpenViBE is used. Sometimes advanced users or
    companies would like to use OpenViBE as a (hidden/embedded) library inside some other application. Currently the closest
    example of this kind OpenViBE kernel use can be seen in the stand-alone scenario
    player
    (openvibe-scenario-player) that does not have a GUI. It is included among the v2.0.0 and
    later source code. Your custom solution could be adapted from the player code. If you also need signal acquisition,
    you’d need to extract the relevant parts from the Acquisition Server codebase.

    If you’re satisfied just getting a scenario played without the graphical Designer interface, that is possible with the
    usual tools. To run a scenario without the user interface, you can use

    # openvibe-designer --no-gui --play scenario.xml
    

    Likewise, Acquisition Server can be started without a GUI,

    # openvibe-acquisition-server --define AcquisitionServer_NoGUI true
    

    If Acquisition Server state (e.g. start, stop, etc) needs to be controlled from the outside by your application, at the
    moment you would need to implement this.

    However, note the consequences of the OpenViBE’s AGPL3 License have for an application relying on
    it: by default, the source code of your app must be made public etc. If you are interested in building a commercial,
    closed-source application on top of OpenViBE, consider contacting Mensia
    Technologies
    that can provide custom versions of OpenViBE with custom licenses for such purposes.

    CSV (Comma-Separated Values) is a text-based file format for exchange of data. Generally CSV files are used to pass data
    to-from tools such as spreadsheet software (openoffice, excel, …) or scientific programming environments (such as R or
    Matlab). These tools can also be used to add , remove or otherwise manipulate columns from such files.

    Unfortunately the basic CSV definition is too limited to conveniently pass all the different kinds of streams used in
    OpenViBE. For this reason, the CSV files read/written by OpenViBE are somewhat different from the simple definition and
    they typically contain some extra information depending on the stream type. Sampling rate is an example piece of numeric
    information that needs some specific convention in order to be inserted to a CSV (unless duplicating it for every row).

    For OpenViBE 2.0 and later, you can read about OpenViBE’s conventions regarding CSV from here. Boxes reading/writing the 1.x style files are also available but
    marked as deprecated.

    For OpenViBE 1.3 and earlier, the main OpenViBE-specific modification was that for signal streams, OpenViBE CSV
    specified the sampling rate as a number at the end of the first line. This adds one extra column to the first line, but
    not to the others. This confuses other programs, as other programs do not understand CSV like this. When importing
    OV-written CSV data to other programs, you must remove the column. For this little trick, you can use almost any text
    editor. When importing CSV to openvibe, you should add the sampling rate column likewise. Also, the first column should
    be time, increasing as is compatible with the sampling rate. Note that especially with the 1.3 style CSV boxes,
    importing from the CSV format into OpenViBE may have issues with the time precision of samples, unless the timing in the
    file is ignored and the samples are treated as a consecutive block starting at time 0 (see the box documentation).

    You can find more information about CSV reading and writing in the corresponding box documentation. Please see CSV Reader and CSV Writer box
    documentation for more details.

    If any box says “update”, it is important that you drag a new version of the same box in the place of the old one and
    configure the new box again. Otherwise the scenario may work incorrectly. This happens when the box algorithm parameters
    or inputs/outputs have changed from the previous version. In this case OpenViBE is able to find out that a box has
    changed, but it doesn’t know the correspondence between old and new parameters and unfortunately cannot update the box
    automatically.

    Quick answer: You should use OpenViBE’s own “.ov” format. For details, please see here.

    By default OpenViBE on Windows installs under C:\Program Files (x86)\. As Windows folder security wants to
    prevent users from changing anything under this folder, you do not have write access to this directory or its
    subdirectories. Often when running scenarios in Designer, they try to write their results under the folder that the
    scenario was opened from (to ensure easy portability of the scenario and data). This is not possible without write
    access. To fix this problem, please copy the scenario materials in question to a folder that you have write access to
    and open it from there before running it. The lack of write access is most usually the source of the problem if you get
    an error message like ‘Error opening file’.

    OpenViBE is primarily an online architecture for streaming signal processing, data recording, and online realtime
    experiments. This means that most of the time data is processed by boxes (DSP plugins) as small chunks of samples. These
    boxes do not usually maintain a ‘global’ view of the data. Although some plugins exist to compute statistics, and some
    boxes may be able to take in very large epochs of data at one go, for advanced ‘offline’ analysis, we currently
    recommend using Python, Matlab or R to investigate your recorded datasets.

    It is also common practice to make OpenViBE export the results (e.g. classifier predictions) to a file and then analyse
    them with dedicated statistical software.

    To test methods in controllable conditions (i.e. artificially generated data), you could try out the simBCI platform that we have developed.

    Systems, devices and drivers

    Please see the list here.

    Please see the list here.

    There are NO near-term plans for supporting Macintosh, Android or more Linux variants. You may be able to run OpenViBE
    on unsupported systems, but may have to solve challenges in order to do so.

    We have no current plans to add new drivers or support new hardware. However, we are happy to accept driver
    contributions (see here for details). There are also various tutorials to help in this. The source codes
    of the existing drivers can also be used as a starting point.

    Many OpenViBE drivers are provided as contributions by the community. Your best option may be to try to contact the
    contributor of the driver. See the rightmost column in the Supported Hardware matrix
    for possible contact regarding each driver. Note that the driver contributors are under no obligation to answer any
    questions, and they may not follow the forum regularly.

    All devices have different specifications like number of electrodes, sampling frequency or quality of signal. You should
    try to get the best device which suits your needs for the price you are ready to pay. We can not recommend one brand
    over another, however our forum user Stefanj has compiled a list of more affordable hardware in this list. This list does not include
    the more expensive medical hardware though.

    Please see the documentation page dedicated to the Emotiv
    driver.

    Since OpenViBE 0.14.0, it’s possible to acquire EEG signals from multiple EPOC headsets on the same computer with
    OpenViBE, thanks to TPAC, one of our contributors on the forum.

    Here is the procedure for 2 headsets :

    • Plug the 2 USB dongles in your computer (from Research Edition Headsets).
    • Launch 2 Acquisition Servers.
    • Configure the two Emotiv EPOC drivers with different User ID (0 for the first headset, and 1 for the second
      headset).
    • Configure the 2 servers so they send the data on different connection ports, e.g. 1024 and 1025.
    • Connect and play the acquisitions. You are now able to acquire the 2 signals through acquisition client boxes
      (with connection ports 1024 and 1025).

    Several users reported having problems connecting the Neurosky MindWave or MindSet headsets to OpenViBE. Often the
    problem seems related to the bluetooth connection or pairing.

    The Neurosky driver in OpenViBE can theoretically communicate with any device that uses the Thinkgear protocol from
    Neurosky. This includes the MindSet and the MindWave. As recommended in the MindSet documentation (Feb. 2011) we use low
    value COM port for the Bluetooth connection. The driver searches for headsets on COM ports from 1 to 16. Please verify
    that your device is installed on a COM port lower than 16.

    Check that the headset is paired via the intended bluetooth adapter

    If you have a bluetooth dongle from Neurosky on the same computer with an other bluetooth adapter, sometimes a wrong
    adapter might be used. As reported by Marco (mmarchesi) on our forums:

    “I’ve discovered an unusual COM driver configuration in my Device Manager on Windows (Control Panel -> Hardware
    and Sound -> Device Manager).

    Windows tries to work with an internal “USB-SERIAL CH340” driver instead of the correct Mindwave USB Adaptor
    (typically installed in “C:/Program Files/NeuroSky/MindWave Driver” folder. This issue has been reported as well
    last December:

    http://support.neurosky.com/kb/mindwave/thinkgear-connector-is-disconnecting-often

    So, once I have changed the driver, the acquisition server worked perfectly with Mindwave!”

    Please check your Window Device Manager and other Windows configuration that the headset is connected via the correct
    adapter.

    Check that the COM ports match exactly

    Sometimes with e.g. Mindwave Mobile and laptop’s internal bluetooth adapter, the driver appears to connect to the
    headset, but reading data from the device fails. This can happen if the Acquisition Server (AS) and Windows do not agree
    on the COM port. This COM port can apparently change from connection to another. Verify that the AS COM port and the
    port reported in the properties of the ‘Mindwave Mobile’ bluetooth peripheral match. If the correct port can not be
    selected in the AS Driver Properties, try uninstalling all the Neurosky bluetooth peripherals and pair the device again.

    Compiling and installing OpenViBE

    First, make sure you followed the right install procedure described in build instructions. You can try to ask for advice on the forum if problems persist.

    N.B. These instructions are for 0.15.0 and earlier

    Well, it is almost possible yes :)

    After you have made a project for OpenViBE under Eclipse, you can us the OpenViBE command files with the Eclipse’s
    function “External Tools”.

    All configuration is located in the menu “Run > External Tools > External Tools Configuration…”. First, make a
    new “Program” and choose a name for it.

    • Example: “Openvibe-Build”

    In the tab “Main”, fill next fields (for Linux):

    • Location: “${workspace_loc:/openvibe/trunk/scripts/linux-build}”
    • Working directory: “${workspace_loc:/openvibe/trunk/scripts}”

    For Windows, it is the same process but the value of fields change.

    • Location: “${workspace_loc:/openvibe/trunk/scripts/win32-build.cmd}”
    • Working directory: “${workspace_loc:/openvibe/trunk/scripts}”

    Now, if you want run OpenViBE under Eclipse it is the same process. For Linux, only one “Program” is necessary. Create a
    new “Program” with a different name and fill fields.

    • Example name : “openvibe-linux-test”
    • Location: “${workspace_loc:/openvibe/trunk/scripts/linux-test}”
    • Working directory: “${workspace_loc:/openvibe/trunk/scripts}”

    For Windows, if you want lauch the “Acquisition Server” and the “Designer”, you must create 2 “Programs”:

    • Example name : “openvibe-test-acquisition-server”
    • Location: “${workspace_loc:/openvibe/trunk/dist/test-acquisition-server.cmd}”
    • Working directory: “${workspace_loc:/openvibe/trunk/dist}”

    And for the “Designer”:

    • Example name : “openvibe-test-designer”
    • Location: “${workspace_loc:/openvibe/trunk/dist/test-designer.cmd}”
    • Working directory: “${workspace_loc:/openvibe/trunk/dist}”

    Then, you can launch the builder and runners with this same menu “Run > External Tools > External Tools
    Configuration…”. Select the “Program” you want execute and use the button “Run” at the down of the dialog box.

    This ” No such file or directory” error on windows is frequent for users using source code packages. This problem comes
    from Windows that can’t handle files in a too long path. Please avoid using too long path to put the source code in, and
    your compilation problem should be solved.

    Bad example :
    C:\my-work\bci-project\openvibe\source-code\openvibe-0.13.1-svn3210-src\openvibe-0.13.1-svn3210-src\<openvibe
    sources>

    Good example : C:\my-work\openvibe-0.13.1-svn3210-src\<openvibe
    sources>

    In the past, this issue occurred due to the installation of .Net framework 4.5 which breaks CMake somehow. If you
    encounter this issue, first check that you have the latest service pack (SP) for your Visual Studio.

    v0.16.0 and later:

    Building with win32-build script uses only one core due to way the Microsoft compiler works. Building with
    Visual Studio IDE can use more cores and speeds up the build. See build instructions
    for details. If you know your way around OpenViBE, after building OpenViBE once, you can also disable components from
    building by editing the main level CMakeLists.txt. However, due to the new way dependencies between
    OpenViBE components are handled in 0.16.0 and later, checking that all the projects are up-to-date should be relatively
    quick.

    Instructions for v0.15.0 and earlier:

    You have to build the whole software at least once…

    Then suppose you are working on a classification plugin, simply edit your win32-init_env_command.cmd or
    linux-init_env_command and remove all the projects of the build order (at the end of the file) except the
    openvibe classification plugin project.

    Now when you call win32-build.cmd or linux-build, only your project will be checked, compiled and
    installed.

    Warning: You should use this functionality with care because it does not guarantee a perfect behavior.
    For example, if you are modifying the toolkit, all the projects depending on the toolkit will have to be rebuilt.
    Additionnaly, if you clean everything with win32-clean.cmd or linux-clean, you will have to reactivate
    all the projects back in win32-init_env_command.cmd or linux-init_env_command to have a new working
    environment. You’ve been warned, use with care !

    On Linux, all dependencies are installed by the linux-install_dependencies script.

    Most of the dependencies are installed natively – i.e.: using the package system which comes with the system. This is
    apt-get on Ubuntu and rpm on Fedora. If no native package system is found the script will attempt do download and
    install the dependencies manually.

    For most up-to-date list for your distribution, it is best to inspect the linux-install_dependencies script
    carefully. The most critical ones tend to include boost (everything), libexpat (xml parsing), gtk (for GUIs), and ogre
    (for 3D visualizations and demos).

    The latest stable version of the required dependencies will be installed by the script.

    Once the native dependencies are installed, the script will proceed to download, compile and install dependencies of
    which OpenViBE needs a specific version. These are installed into the scripts/software/ directory on
    v0.15.0 and earlier, and dependencies/ on >= v0.16.0 and later.

    Most of the dependencies are installed by native package systems (such as apt-get or rpm), in order to use these you
    will need root privileges.

    Miscellaneous questions

    OpenViBE provides Designer plugins to import and/or export several file formats of other platforms (BCI2000, GDF, CSV,
    EDF, BrainAmp/VHDR). The complete list is here. In addition to drivers as the
    primary data source, the Acquisition Server can receive data from the FieldTrip buffer and LabStreamingLayer (LSL), and
    send it out to LSL. Data and stimulations can be sent out from Designer to Matlab, Python, VRPN, TCP/IP, and LSL. Data
    and stimulations can be received by Designer from Acquisition Server, Matlab, Python, and VRPN. Stimulations (markers)
    can be additionally sent and received to/from Lua. For more information on these communication methods, see this document.

    Other connections are not planned yet, but feel free to Contact us if you think a connection with your software could be a
    plus.

    Boxes and drivers that are marked as unstable are new or otherwise not often used by the core development team.
    In the case of drivers, we might not even have access to the device in question. The unstable components might only work
    properly in specific circumstances, or they might work perfectly well — we do not know.

    If you have issues with components marked as unstable, feel free to ask about them on the forum.
    However, the label ‘unstable’ does not indicate an issue in itself!

    Sometimes Unstable boxes are not shown in Designer. In order to make them appear, you can either
    click the ‘show unstable’ button in Designer — or edit the configuration file and add it this line:

    Designer_ShowUnstable = true

    Your configuration file is $HOME/.config/openvibe/openvibe-designerrc under Linux and
    %APPDATA%/openvibe/openvibe-designer.conf under Windows.

    This message can be printed when a DLL file should be loaded and can not be found. The d3dx9_33.dll, d3dx9_38.dll,
    d3dx9_42.dll and d3dx9_43.dll files are part of DirectX (Microsoft 3D acceleration API) which is used by Ogre3D. The
    best thing to do is to actually install DirectX on your computer. You can find it searching for Direct X redist on
    google (or following this link http://www.google.fr/search?q=directx+redist+site%3Amicrosoft.com).
    Be careful to get the matching DirectX version. Some systems, like Windows 10, may not by default provide the DirectX9
    typically used by Ogre.

    Sometimes the same problem can also result simply in a message “Ogre initialization failed, 3D rendering
    disabled
    ” on Designer startup. This issue may also be fixable by installing DirectX.

    Note that Ogre is only used for 3D visualizations and some of the demos. Acquisition and signal processing in OpenViBE
    should work just fine without it.

    Your screen is probably configured with a bad color depth. You should consider changing the color depth to 24 or 32
    bits. In order to do that, right click on the desktop, chose “properties” and go in the “parameters” tab. You can change
    the color depth on the right side of this panel. Restart OpenViBE when the change is done.

    Make sure you have the latest and best drivers for your graphics hardware. For example, on one computer we noted a
    significant speed-up and increase in Designer responsiveness on Ubuntu 12.04 after we switched from the default open
    source display drivers to the nvidia proprietary drivers.

    Please read all the information in the matlab tutorial very carefully, including the section on requirements.

    In order to get MATLAB filter to work properly on Linux, you need csh to be installed. This is not always
    the case, notably on Ubuntu distributions.

    Before launching Designer, you must export LD_LIBRARY_PATH to include the path where the Matlab .so files are installed.

    Boxes displayed in dark red are boxes that are unavailable.
    To resolve this problem :

    • It is possible that you have launched the designer from the designer folder and not extras, the boxes present in extra are therefore unavailable (this separate compilation system is doomed to disappear, but for the moment confusion is possible).
    • If it is the python box, you may have this log in the terminal:
      [INF] Added 0 plugin object descriptor(s) from [....... / openvibe-plugins-contrib-python3.dll]
      Your python install is either missing or the wrong version for OpenViBE. For details, please visit https://openvibe.inria.fr/tutorial-using-python-with-openvibe/

    You may have this log in the terminal:
    [INF] Added 0 plugin object descriptor(s) from [....... / openvibe-plugins-contrib-python3.dll]
    Your python install is either missing or the wrong version for OpenViBE. For details, please visit https://openvibe.inria.fr/tutorial-using-python-with-openvibe/