FAQ

Frequently Asked Questions

  • NB: Document was last updated on 01.Mar.2017 (latest OpenViBE was 1.3.0)

    General

    What is OpenViBE ?

    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.

    What does the ViBE stand for ?

    Intially, 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 :)

    What is the license of OpenViBE ?

    • 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.

    What is the current status of OpenViBE ?

    OpenViBE development began in 2006 and keeps being developed in the scope of various projects and by various contributors. Today, OpenViBE offers several complete processing pipelines. It 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 should facilitate the integration of new functionalities while limiting the number of necessary changes to the APIs. Additionally, external contributions enlarging OpenViBE functionalities are warmly welcomed.

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

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

    I have problems using OpenViBE, what should I do ?

    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.

    I want to do something specific with OpenViBE but I don’t know how?

    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.

    I think I found a bug, what should I do ?

    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, involved hardware, your operating system and version, 32 or 64 bits, and your compiling toolchain (if you compiled Openvibe yourself).
    • Please describe detailed steps to reproduce the problem.
    • If the problem occurred with a scenario: 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 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, such as some device drivers. You can see if a driver falls to this category from the supported hardware page. In the cases where the bug concerns contributed code, we kindly request you to contact the contributing author.

    I have a question about a third-party version of OpenViBE?

    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.

    How can I contribute to OpenViBE ?

    There are many ways in which you can contribute to OpenViBE :

    • development : you can implement new boxes, new algorithms, new drivers
    • bci design : you can submit new scenarios and processing pipelines
    • documentation : you can enhance the existing documentation or write new tutorials
    • testing : you can help test new features, new operating systems, new hardware, and send us feedback or bug reports
    • support : you can provide discuss related matters on the forum and answer questions of others
    • packaging : you can build RPMs, DEBs or whatever package your linux distro uses

    For 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 publish an article about your contribution on the community website. If you still have questions, you can also Contact us.

    I am a scientist and I want to cite OpenViBE, how should I proceed ?

    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

    What scientific work is there based on OpenViBE?

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

    How can I learn more about BCI?

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

    Systems, devices and drivers

    Which Operating Systems work with OpenViBE?

    Please see the list here.

    Which EEG devices work with OpenViBE?

    Please see the list here.

    Are you going to support X …?

    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.

    I have a problem with device or driver Y …?

    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.

    Which EEG device should I buy?

    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.


    How can I use the Emotiv EPOC?

    Please see the documentation page dedicated to the Emotiv driver.

    How can I acquire from multiple Emotiv EPOC on the same computer ?

    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).

    I can’t connect (or get data from) my Neurosky MindSet/MindWave headset

    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

    I have problems compiling OpenViBE, what should I do ?

    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.

    Is it possible to build and run OpenViBE with Eclipse ?

    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.

    Compilation crashes on Windows with : fatal error C1083: Cannot open compiler generated file: ‘some-file’: No such file or directory

    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>

    On Windows, build fails with “nmake failed to compile a simple program”

    This issue is due to the installation of .Net framework 4.5 which breaks CMake somehow.

    The easiest solution is to install SP1 for Visual C++ 2010

    Compiling OpenViBE takes far too long especially on Windows, what could I do to speed it up ?

    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 !

    How are the dependencies handled on Linux ?

    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.

    What dependencies will be installed on Linux ?

    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.

    Why do I need root privileges to install OpenViBE on Linux ?

    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

    Are there any connections with other BCI platforms ?

    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.

    How can I control an external application or a device?

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

    How can I use OpenViBE hidden inside my application?

    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 this kind of library use is not possible with the distributed version of OpenViBE without coding effort. In principle, you could extract the necessary code to do this by investigating how OpenViBE Designer plays scenarios and adapting the relevant parts. If you also need signal acquisition, you’d need to take parts from the Acquisition Server. If you’re satisfied just getting a scenario played without the graphical Designer interface, that is possible. 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, this needs to be implemented as well.

    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.

    What does ‘unstable’ mean?

    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!

    Some boxes do not appear in the Designer box tree

    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.


    I have problems reading or writing CSV from (or to) another application

    OpenViBE CSV format for signals has a few small differences to the format in general. Due to a design choice in the past, OpenViBE CSV specifies 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. Please see CSV Reader and CSV Writer box documentation for more details. If you wish to do more complicated manipulations on the CSV files, you can try to use tools such as spreadsheet software (openoffice, excel, …) or scientific programming environments (such as R) to add or remove columns.

    I updated OpenViBE from a previous version and now some boxes says ‘update’?

    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.

    Which file format should I use with OpenViBE?

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

    I get a write error running a scenario?

    By default OpenViBE on Windows installs under C:\Program Files (x86)\. As an user, 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 scenario was opened from (to ensure easy portability of the setup). This is not possible without write access. In this case, please copy the scenario in question to a folder you have write access to and open it from there before running. The lack of write access is most usually the source of the problem if you get an error message like ‘could not open file [blah] for writing.’.

    On Windows, launching OpenViBE complains about missing d3dx9 dll files ?

    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.

    On Windows, I can drag and drop the boxes but I can’t select / click / connect / configure anything, what should I do ?

    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.

    Designer feels slow

    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.

    How do I use the MATLAB boxes ?

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

    On Linux, MATLAB filter keeps saying ‘Can’t start MATLAB engine’, what do I do ?

    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.

    On Linux, loading the Matlab plugin says ‘error:libmx.so: cannot open shared object file: No such file or directory’?

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