Plugins
Plugins extend OpenAVC with system-wide integrations, control surfaces, sensors, and utility services. Unlike drivers (which translate a single device protocol), plugins operate across the entire system, connecting to external platforms, adding physical control surfaces, or bridging other ecosystems.
Plugins vs Drivers
| Drivers | Plugins | |
|---|---|---|
| Scope | One device, one protocol | System-wide |
| Purpose | Translate commands and state for a specific piece of hardware | Add capabilities that span devices, connect external systems, or add physical interfaces |
| Examples | PJLink projector, Extron switcher, Samsung display | MQTT bridge, Elgato Stream Deck, Dante DDM, occupancy analytics |
Rule of thumb: If it talks to one device over TCP/serial/HTTP, it’s a driver. If it bridges systems, adds a control surface, or provides a service, it’s a plugin.
Installing Plugins
From the Community Repository
- Open the Plugins view in the Programmer IDE sidebar
- Click the Browse tab
- Find the plugin you want (use search or filter by category)
- Click Install
The plugin is downloaded and saved to plugin_repo/. It appears in the Installed tab as disabled. A plugin that needs a newer OpenAVC shows Needs OpenAVC v<version> over a greyed Install: update OpenAVC, then install it. A refused update leaves the installed version in place.
Installs come from the official plugin repository and nowhere else. A plugin installs as a directory, and every file is checked against the SHA-256 the repository publishes for it before being written: a file that doesn’t match, one the repository doesn’t publish, and one it publishes that never arrives all stop the install, leaving nothing behind. A plugin runs inside the server with the capabilities it declares, so read what those are before enabling one — see the network and security guide for what the check does and does not prove.
Category Filters
| Category | What It Contains |
|---|---|
| Control Surfaces | Physical button panels, fader banks, keypads (Stream Deck, X-Keys, MIDI) |
| Integrations | Protocol bridges and external platform connections (MQTT, Dante, Home Assistant) |
| Sensors | Environmental inputs (occupancy, temperature, ambient light) |
| Utility | Analytics, voice control bridges, logging services |
Platform Compatibility
Plugins declare which platforms they support. The Browse view filters by your current platform by default. Use the “Show all platforms” toggle to see plugins for other platforms. These show a “Not available for [platform]” badge.
| Platform | Description |
|---|---|
| Windows x64 | Windows development machines, AV rack PCs |
| Linux x64 | Docker, VM, rack servers |
| Linux ARM64 | Raspberry Pi 4/5, ARM servers |
| All | Pure Python plugins with no platform-specific dependencies |
Enabling and Configuring Plugins
Enable a Plugin
- Go to the Plugins view, Installed tab
- Click the plugin in the list, then click Enable in the detail view
If the plugin requires configuration before it can start (for example, an MQTT broker URL), a Setup Dialog appears with the required fields. Fill them in and click Save.
If the plugin has sensible defaults for all settings, it starts immediately.
A plugin that needs a port of its own, such as the Video Panel’s UDP 8189, has that port opened in the host firewall while it runs; on Windows the rule is named like OpenAVC plugin UDP 8189. The Network and Security Cut Sheet covers the cases where the port cannot be opened automatically.
Configure a Plugin
Click a plugin in the Installed list to open its detail view. The Configuration section shows all available settings, auto-rendered from the plugin’s configuration schema.
Settings include standard field types (text, numbers, toggles, dropdowns) and OpenAVC-specific types:
| Field Type | Schema Type | Description |
|---|---|---|
| Text | string | Free-form string input |
| Integer | integer | Whole number with optional min/max |
| Decimal | float | Decimal number with optional min/max/step |
| Toggle | boolean | On/off boolean |
| Dropdown | select | Select from a list of options |
| State Key | state_key | Pick a state key from the system (e.g., device.projector.power) |
| Macro | macro_ref | Pick a macro from the project |
| Device | device_ref | Pick a device from the project |
Configuration changes are auto-saved. If the plugin is running, it restarts automatically with the new settings.
Disable a Plugin
Select the plugin in the list and click Disable. The plugin stops and all its runtime effects (state keys, event subscriptions, background tasks) are cleaned up automatically. State keys under plugin.<id>.* are fully deleted from the state store (not just set to None), so they will not appear in state snapshots while the plugin is stopped. Configuration is preserved, and re-enabling restores everything.
Plugin Status
Each plugin shows a status indicator:
| Status | Icon | Meaning |
|---|---|---|
| Running | Green circle | Plugin is active and healthy |
| Stopped | Gray circle | Plugin is disabled (config preserved) |
| Error | Red circle | Plugin crashed or failed its health check |
| Missing | Yellow triangle | Project references a plugin that isn’t installed |
| Incompatible | Orange triangle | Plugin is installed but doesn’t support the current platform |
Error Recovery
If a plugin crashes or repeatedly fails its health check, OpenAVC automatically disables it after 10 consecutive callback failures to protect system stability. The plugin shows an “Error” status with a description of the failure. You can view the error details in the plugin’s detail view and re-enable the plugin after addressing the issue.
Missing Plugins
When you open a project that uses a plugin you don’t have installed, the plugin list shows it with a yellow warning icon and “(not installed)” label. The detail view shows a banner:
Plugin Required. This project uses “MQTT Bridge” which is not installed.
Two options:
- Install from Community. Opens the Browse tab to find and install the plugin.
- Remove Plugin Config. Removes the plugin reference from the project.
After installing a missing plugin, click Activate to start it without restarting the server.
Surface Configurator
Control surface plugins (Stream Deck, MIDI controllers, X-Keys) include a visual Surface Configurator. This is a graphical editor that mirrors the physical layout of your hardware.
Grid Surfaces
For button grids like the Elgato Stream Deck. The configurator shows the exact layout (e.g., 4 columns x 2 rows for Neo). Click any button to configure it:
- Label. Text shown on the button.
- Button Mode. How the button behaves (see below).
- Press Action. What happens when pressed (macro, device command, set variable, navigate page).
- Visual Feedback. State-driven appearance changes: pick a state key, set a condition, and choose active/inactive colors and labels.
Grid surfaces support pages. Tab through multiple pages of button assignments using the page tabs at the top.
Button Modes
| Mode | Behavior | Use Case |
|---|---|---|
| Tap | Fires action on press (default) | Most buttons |
| Toggle | Fires On or Off action based on current state | Power on/off, mute/unmute |
| Hold Repeat | Fires action repeatedly while held (configurable interval) | Volume ramp, camera pan/tilt |
| Tap / Hold | Short press = tap action, long press = long press action | Quick vs advanced action |
Toggle is state-aware. You pick a state key to watch, set the value that means “on,” and configure separate On and Off actions. The button reads the state to decide which action to fire. You can also set On Label and Off Label so the button text changes automatically (e.g., “ON” when active, “OFF” when inactive).
Conditional Labels
The Visual Feedback section supports separate label text for active and inactive states. Toggle mode also has its own On/Off labels built in. Both update the physical button display in real time as state changes.
Strip Surfaces
For linear controllers like MIDI fader banks. Shows a horizontal row of faders. Each fader can be bound to a state key for position feedback.
Custom Surfaces
For controllers with mixed control types (buttons, faders, encoders). Controls are positioned freely on a canvas. Each control type has its own configuration:
| Control | Configuration |
|---|---|
| Button | Press action, label, button mode, visual feedback (colors + conditional labels) |
| Fader | State key binding, min/max range, label |
| Encoder | Increment/decrement macros, label |
| Indicator | State key binding, color map, label (read-only) |
Routing Matrices
For audio/video routing plugins (Dante, NDI). Shows a grid of inputs (columns) and outputs (rows). Click a crosspoint to route or unroute. Rows and columns are populated dynamically from live state.
Updating Plugins
When the community repository has a newer version of an installed plugin, its row in the Installed tab shows Update to v<version>, the top of the list counts the updates available, and the plugin’s page shows the installed and available versions with an Update button. The plugin’s card in the Browse tab shows Update too. A newer version that needs a later release of OpenAVC shows Needs OpenAVC v<version> instead of the button.
Updating keeps the plugin’s settings. A running plugin is stopped, updated and started again. If the new version cannot be installed or does not load, the previous version is put back.
For a few minutes after a plugin is updated in the repository, GitHub can serve the new files alongside the previous list of hashes, or the other way around. OpenAVC checks a download that doesn’t match against a fresh copy of the list before refusing it. If they still disagree, the update is refused with “This plugin was updated a few minutes ago and cannot be installed yet. Try again in five minutes.” The refresh button at the top of the Plugins view fetches the repository’s list from GitHub again.
Uninstalling Plugins
- Go to the Installed tab
- Click Uninstall on the plugin
If the plugin is currently running, it is automatically stopped before being removed. The plugin files are removed from plugin_repo/ and its configuration is removed from the project. On Windows its firewall rule is removed too, and uninstalling OpenAVC removes any that are left.
Project Portability
Plugins are tracked in the project file just like drivers. When you export a project, installed plugins are bundled in the export. When you import a project on another machine:
- Bundled plugins are installed automatically
- Plugins not bundled show as “Missing” with an option to install from the community repository
- Platform-incompatible plugins show a warning (e.g., “Plugin ‘Stream Deck’ is not compatible with Linux ARM64”)
Using AI Assistants
If you use an AI coding assistant (Claude, ChatGPT, Copilot, etc.), you can point it to the AGENTS.md file in the community plugin repository. It contains the complete Plugin API, manifest format, configuration schema, and examples in a format optimized for LLM agents. The repository also includes a validate.py script that your assistant can use to check its work.
See Also
- Creating Plugins. Developer guide for building your own plugins
- Devices and Drivers. Adding and managing hardware
- Creating Drivers. Building device drivers