Open Ephys Plugin API

Overview

The Open Ephys Plugin API consists of all of the classes and methods that are accessible by plugins. In order to extend the functionality of the GUI, one only needs to understand the interfaces that compose the API for a particular plugin type. And because plugins are compiled independently from the core application, it is straightforward to share this new functionality with other users.

The Plugin API defines how plugins can interact with the rest of the GUI, and also provides some convenient functions for building user interfaces and processing data. Classes and methods that are part of the Plugin API are indicated in the source code by the PLUGIN_API macro.

Detailed information about the five different types of plugins that can be created is available on the following pages:

• Processor Plugins
• Visualizer Plugins
• Data Threads
• Record Engines
• File Sources

Some general features of the plugin API are covered below:

Logging

When plugins need to log information, they should ideally use the GUI’s built-in logger class, defined in Utils.h. This is preferred to calling std::cout or printf, because the logger class will print output to the console as well as to a log file that is created each time the GUI is run.

The two primary methods are:

• LOGC (“log console”): prints info to the console and also saves it to a log file

• LOGD (“log debug”): prints info to the console in debug mode, and saves it to a log file in release mode

These are used by calling, e.g.:

LOGC(arg1, arg2, arg3, ...);

where the arguments are strings, integers, floats, etc. – any values that can be converted to strings by std::cout. There is no limit to the number of arguments that can be used.

In addition, there are several other logging methods that are reserved for specific cases:

• LOGA (“log action”): writes a line in the log file whenever the user performs an action (e.g. pressing a button, updating a label, etc.).

• LOGB (“log buffer”): logs messages inside a plugin’s process() callback (never do this in release mode).

• LOGE (“log error”): prints the console output via std::cerr instead of std::cout.

• LOGF (“log file”): prints to the log file only.

• LOGG (“log graph”): logs messages related to constructing the GUI’s processor graph.

Core Services

All types of plugins can access the CoreServices class, which includes the following general-purpose methods:

String CoreServices::getGUIVersion()

Returns:

The version of the host application as a string. This can be useful if certain aspects of a plugin’s functionality requires a minimum version of the GUI.

File CoreServices::getDefaultUserSaveDirectory()

Returns:

A Juce File object that specifies the location where files are saved by default (typically in the “Documents” directory). This is useful if a plugin needs to save custom data files.

File CoreServices::getSavedStateDirectory()

Returns:

A Juce File object that specifies the location where the GUI’s configuration files are stored. This is useful if a plugin needs to save a custom settings file (although it’s recommended to use the GUI’s built-in XML settings file whenever possible).

void CoreServices::saveRecoveryConfig()

Triggers the GUI to save the recovery configuration file (recoveryConfig.xml). This file is re-generated automatically whenever the signal chain is updated, but a plugin may wish to re-generate it when its internal parameters have changed, so these can be properly re-loaded in the event of a crash.

void CoreServices::updateSignalChain(GenericEditor *editor)

Updates all processors downstream of the specified GenericEditor. This should be called whenever a plugin adds or remove continuous, spike, or event channels, or changes the properties of these channels (such as their name or other metadata).

Parameters:

editor – A pointer to the editor of the processor that has been modified.

void CoreServices::highlightEditor(GenericEditor *editor)

Highlights a plugin’s editor in the Editor Viewport, without updating the signal chain. This will also make the editor visible if it’s not currently seen by the user.

Parameters:

editor – The editor to highlight.

void CoreServices::loadSignalChain(String path)

Loads a signal chain from the specified absolute path. Note that this will delete all existing plugins from the signal chain.

Parameters:

path – The path to a valid XML Open Ephys settings file.

bool CoreServices::getAcquisitionStatus()

Returns:

true if acquisition is active. If a plugin needs to check this frequently, it’s recommended to store a local variable that’s updated inside the GenericProcessor::startAcquisition() and GenericProcessor::stopAcquisition() methods.

void CoreServices::setAcquisitionStatus(bool enable)

Turns acquisition on and off. This could be used to start and stop acquisition when a particular external trigger is received.

Parameters:

enable – Set to true to start acquisition, and false to stop acquisition.

bool CoreServices::getRecordingStatus()

Returns:

true if recording is active. If a plugin needs to check this frequently, it’s recommended to store a local variable that’s updated inside the GenericProcessor::startRecording() and GenericProcessor::stopRecording() methods.

void CoreServices::setRecordingStatus(bool enable)

Turns recording on and off. This could be used to start and stop recording when a particular external trigger is received.

Parameters:

enable – Set to true to start recording, and false to stop recording.

void CoreServices::sendStatusMessage(const String &text)

Displays a message to the user in the Message Center (located at the bottom of the GUI’s main window). These messages will not be saved by the Record Node; to write messages that are saved, but not displayed to the user, call GenericProcessor::broadcastMessage() while recording is active.

Parameters:

text – The message to display.

int64 CoreServices::getSoftwareTimestamp()

Returns:

The current software timestamp (milliseconds since midnight Jan 1st 1970 UTC).

float CoreServices::getSoftwareSampleRate();

Returns:

The ticker frequency of the software timestamp clock (1000 Hz).

File CoreServices::getRecordingParentDirectory()

Returns:

The default recording directory.

void CoreServices::setRecordingParentDirectory(String dir)

Sets new default recording directory. This will only affect new Record Nodes, and will not be applied to Record Nodes that are already in the signal chain. To set the recording directory for existing Record Nodes, use CoreServices::RecordNode::setRecordingDirectory() (see below).

Parameters:

dir – Absolute path of the new recording directory.

void CoreServices::RecordNode::setRecordingDirectory(String dir, int nodeId, bool applyToAll = false)

Sets a new recording directory for one or all existing Record Nodes.

Parameters:

• dir – The absolute path of the new recording directory.

• nodeId – The ID of the Record Node (if only one is being updated).

• applyToAll – Set to true to apply the new directory to all Record Nodes.

Array<int> CoreServices::getAvailableRecordNodeIds()

Returns:

An array of IDs for Record Nodes currently in the signal chain.

void CoreServices::setRecordingDirectoryBasename(String dir)

Sets new basename for the recording directory (does not affect prepend/append text).

Parameters:

dir – The recording directory basename (overrides the auto-generated date string).

String CoreServices::getRecordingDirectoryName()

Returns:

The full name of the current recording directory (or empty string if no recording has been started yet).

void CoreServices::createNewRecordingDirectory()

Instructs all Record Ndodes to create a new directory the next time recording is started.

String CoreServices::getRecordingDirectoryPrependText()

Returns:

The text that will be prepended to the basename of newly created recording directories.

String CoreServices::getRecordingDirectoryAppendText()

Returns:

The text that will be appended to the basename of newly created recording directories.

void CoreServices::setRecordingDirectoryPrependText(String text)

Sets the text to be prepended to the basename of newly created recording directories.

Parameters:

text – The text to prepend.

void CoreServices::setRecordingDirectoryAppendText(String text)

Sets the text to be appended to the basename of newly created recording directories.

Parameters:

text – The text to append.

bool CoreServices::allRecordNodesAreSynchronized()

Returns:

true if all Record Nodes are in a “synchronized” state. A Record Node is synchronized if it only has one data stream as input, or if all of its incoming streams share a hardware sync line that has received at least two events.