Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Overview

If you’re a developer starting to work with the OpenAction API to create custom actions for a programmable control surface, you’re going to be creating a plugin, which is a concept hopefully familiar to you as a user of an OpenAction server (like OpenDeck). This page hopes to cover other key concepts of the API that aren’t as visible to the end user.

Plugin structure

In its distributed form, an OpenAction plugin is a regular filesystem directory (with a name ending in .sdPlugin, for backwards-compatibility with the Stream Deck SDK).

This directory contains everything that the plugin needs, including:

  • A plugin manifest file (manifest.json), which describes the plugin and its actions to the server
  • Your plugin’s compiled executable file(s) (or script files, if using an interpreted language)
  • Icons and images used by the plugin
  • Property inspector (action settings UI) files, if needed

All of the user’s installed plugins are stored together in a directory on their system, which varies depending on the OpenAction server and operating system being used. If you’re using OpenDeck, you can locate this directory by clicking the “Open config directory” button in the OpenDeck settings view, then opening the plugins folder within.

This is what a user’s plugins directory might look like, with two plugins installed:

plugins/
├── com.example.coolplugin.sdPlugin/
│   ├── manifest.json                            # Plugin manifest file
│   ├── oacoolplugin-x86_64-pc-windows-msvc.exe  # Compiled executables
│   ├── oacoolplugin-aarch64-apple-darwin
│   ├── oacoolplugin-x86_64-apple-darwin
│   ├── oacoolplugin-x86_64-unknown-linux-gnu
│   ├── oacoolplugin-aarch64-unknown-linux-gnu
│   ├── icon.svg                                 # Plugin icon
│   ├── actions/                                 # Action icons
│   │   └── funaction.svg
│   └── pi/                                      # Action property inspectors
│       └── funaction.html
├── com.example.lesscoolplugin.sdPlugin/         # Another plugin
│   ├── manifest.json
│   ├── oalesscoolplugin-x86_64-pc-windows-msvc.exe
│   ├── icon.svg
│   └── actions/
│       └── lessfunaction.svg

Actions, instances and contexts

An OpenAction plugin can contain multiple actions, each of which provides different functionality to the user. For example, a plugin for controlling media playback might include actions for play/pause, previous, and next.

When a user adds an action to their control surface (for example, by dragging it onto a button on one of their OpenDeck profiles), this creates an instance of that action. Multiple instances of the same action can exist independently, each with its own settings and state.

Every action instance is identified by a unique context string, which is generated by the OpenAction server when the instance is created. This context is used in all communication between clients and the server to identify the instance an event pertains to. It is different from the action’s UUID, which identifies all instances of that action.

When the user edits the appearance (state) or settings of an instance, the OpenAction server persists these changes, and notifies the plugin of the changes. Because each instance becomes an independent copy of the action template, you may need to completely remove and re-add your instances when making changes to the action in your plugin’s manifest file.

Property inspectors

Many actions need the user to be able to configure settings specific to that action instance. This is done through a property inspector, which is a user interface provided as part of the plugin.

Property inspectors are implemented using web technologies (HTML, CSS, and JavaScript), so that the OpenAction server can embed them in a webview. This is both due to the flexibility of web technologies for building user interfaces, and behaving in a consistent manner across different platforms.

Property inspectors themselves are also direct consumers of the OpenAction API, making them the other kind of OpenAction client (alongside plugins). All communication between the property inspector and the plugin happens through the OpenAction server.

However, property inspectors only have access to a limited subset of the events of the OpenAction API, primarily those related to reading and writing settings for the action instance they are associated with.

Next steps

Now, you should have an understanding of the key concepts of the OpenAction API. The next page covers the requirements of the plugin manifest file, the creation of which being the first step in creating a plugin.