Plugins

Plugins are the heart of the GUI’s functionality. They make it possible to swap in different data sources, rapidly reconfigure real-time processing pipelines, and add features without needing to learn about the entire application. Now, with the addition of the Plugin Installer, it’s easier than ever to incorporate new plugins into your signal chains.

The GUI comes with a number of “built-in” plugins, which appear automatically when you launch the GUI. Other officially supported plugins are hosted in a centralized repository, and can be downloaded and upgraded via the Plugin Installer. This is how we want to distribute all newly created plugins in the future, to make it easier to upgrade individual plugins whenever new changes become available.

A list of third-party plugins is available on the Open Ephys wiki. We plan to migrate many of these to the centralized repository in the near future. To learn how to build your own plugin, check out Creating a new plugin.

General Plugin Features

Plugins interact with one another in two primary ways:

  1. Prior to starting data acquisition, plugins pass configuration objects through the signal chain, so downstream plugins know the number of incoming channels to expect. Plugins can generate continuous data or events (including TTL events, messages, and spikes).

  2. While acquisition is active, plugins can modify continuous data buffers or add to the event data buffers. The size of these buffers (in ms) is determined by the computer’s audio card, and can be configured through the Audio Settings interface in the GUI’s main control panel.

Each plugin has a 3-digit identifier, starting at 100. Channels processed by individual plugins are grouped into streams, a set of channels that are sampled synchronously, and which are guaranteed to have the same number of samples in each buffer. Most source plugins generate only one stream, but some plugins (such as Neuropixels) have separate streams for different devices (e.g., individual probes) that may have slightly different sample rates.

When you drop a plugin onto the signal chain, you’ll see an editor for any user-configurable settings. The generic plugin settings editor interface looks like this:

Overview of the Generic Plugin interface

The blank region usually includes widgets for changing available settings. All plugins contain a “stream selector” containing information about all streams that pass through the plugin. For many plugins, the active parameters will only be applied to the currently selected stream.

Types of Plugins

  • Sources: bring data into the signal chain. Acquisition won’t start unless every signal chain has at least one source.

  • Filters: alter the data in some way, either by changing the continuous data or adding TTL events, messages, or spikes to the event buffer.

  • Sinks: send data to an external source, such as a display, stimulator, etc., without altering the underlying data streams. Data should pass through Sinks unchanged.

  • Utilities: allow the signal chain to be split or merged, or to control the recording state by intercepting TTL events.

  • Record Engines: define new data formats that can be saved by a Record Node. These plugins do not appear in the processor list, but instead show up in drop-down menus inside the global record options panel or individual Record Nodes.

  • File Sources: define new data formats that can be read by a File Reader. These plugins do not appear in the processor list, but instead define the file extensions that the File Reader can accept (e.g., .oebin).

Plugin Installer

The Plugin Installer is a simple graphical user interface that allows the user to download and install plugins that are not included by default. All available plugins are hosted in the Open Ephys Plugins GitHub Account. All the plugins on here are either developed by the Open Ephys team or community-developed plugins that have been forked, polished, and released.

To open Plugin Installer, go to File > Plugin Installer, or press the shortcut keys Ctrl+P (⌘P on macOS). This brings up the interface below:

Overview of the Plugin Installer interface

Note

The Plugin Installer requires a network connection in order to function. You will not be able to install plugins unless you have access to the internet.

Layout

The top bar of the Plugin Installer allows the user to:

  • Sort the plugins alphabetically in ascending (A to Z) or descending (Z to A) order.

  • Filter plugins by those that are available, plugins that are installed by Plugin Installer, or the installed plugins that have updates.

  • Filter the plugins by type: Source, Filter, Sink, or Other.

Next is the plugin list, which, as the name implies, shows the list of plugins available on the basis of the selections made in the control panel.

Lastly, the plugin information panel gives information regarding the selected plugin. This information includes the name of the plugin, owner, list of (compatible) versions available, last updated, description, and any external dependencies.

Screenshot of the Plugin Installer

Installing Plugins

To install a plugin, simply select the desired plugin from the plugin list, the plugin info panel will fetch the information of that plugin and display it. Then, select the desired version of that plugin from the drop-down menu, and click on Install. If everything works fine, a success message will appear. Now, the plugin should be loaded in the GUI, and it will show up in the Processor List of the main GUI window. If there is an error while installing the plugin, an error message should pop-up saying what kind of error it was. The error message will also be printed to the debug console.

Note

Plugins downloaded via Plugin Installer won’t load into the main GUI if plugin-GUI is built from source in Debug mode. Please make sure plugin-GUI is built in Release mode before installing any plugins.

Screenshot of the Plugin Installer after successful installation

Upgrading / Downgrading

To check if any of the installed plugins have a newer version available, click on the Updates checkbox in the control panel. To upgrade that plugin, select the newest version of that plugin in the info panel, and the “Installed” button should change to “Upgrade“. Click on Upgrade, and this should upgrade the plugin to the version that you selected.

To downgrade a plugin to an older version (if available), click on the “Installed” checkbox in the Plugin Installer control panel, click on the plugin you want to downgrade, select the older version from the “Version” drop-down menu. This should change the “Installed” button text to “Downgrade”. Click on Downgrade, and this should downgrade the plugin to the version that you selected.

Uninstalling Plugins

To remove a plugin, simply click the “Uninstall” button. This will delete the plugin binary file, and remove the plugin from the Processor List.