Skip to content
Macro DeckMacro Deck Docs

Features

A plugin adds features by implementing small SDK interfaces on its integration. Implement only what you need - every plugin starts with actions.

public sealed class ObsIntegration : IPluginIntegration, IVariableProvider, IEventProvider
{
  public IReadOnlyList<IActionDefinition> Actions { get; } = [new StartRecordingAction()];
  // IVariableProvider and IEventProvider members, see their pages.
}

Buttons

Section titled “Buttons”
Feature Contract Use it to
Actions IActionDefinition, IActionExecutor Do something when a button is pressed or a flow runs.
Button states IStateProviderActionDefinition Show on/off, muted, recording and similar states on a button.
Button icons IIconProviderActionDefinition Draw album art, avatars or weather imagery on a button.

Data

Section titled “Data”
Feature Contract Use it to
Variables IVariableProvider Expose live values such as {{ vars.music_track }}.
Events IEventProvider, IEventPublisher Let users trigger automation when something happens.
Deck and clients IIntegrationContext.Deck Navigate folders and profiles, and find out which folder each client has open.
Music players IMusicPlayerProvider Drive the Music Player widget and reuse Macro Deck’s ready-made music actions.
Weather IWeatherProvider Supply weather stations to Macro Deck’s weather features.
Virtual profiles IProfileProvider Offer profiles the plugin generates.

Setup and maintenance

Section titled “Setup and maintenance”
Feature Contract Use it to
Setup flows IConfigFlowProvider, IConfigFlow Ask for connection details, API keys or an OAuth login.
Integration issues IIntegrationIssueProvider Tell the user what is wrong and how to fix it.
Settings migrations IMigrationProvider Take over a user’s setup from Macro Deck 2.
Localization MacroDeck.Localization Ship every user-facing string in every language.
Logging ILogger Write diagnostics the user can send you.
Testing MacroDeck.Plugin.Testing Test your integration without a running Macro Deck.

Hardware and surfaces

Section titled “Hardware and surfaces”
Feature Contract Use it to
Devices IDeviceProvider Connect hardware or custom clients as Macro Deck devices.
Layouts ILayoutProvider Describe a device’s regions and geometry.
Macro Deck UI IUiProvider Draw configuration views, widgets and folder views.
Widget types IWidgetTypeProvider Add deck widgets beside Macro Deck’s own.
Folder views IFolderViewProvider Replace a folder’s button grid with your own rendering.
Screensavers IScreenSaverProvider Show something of your own on a device that has sat idle.

Host APIs

Section titled “Host APIs”

IIntegrationContext gives an integration access to what Macro Deck owns: Deck navigation and client positions, Scripts, Widgets, Notifications, variables, configuration and events. In a plugin every call crosses the plugin protocol, so don’t call them in a hot loop.

Ids

Section titled “Ids”

Action, event and variable ids are yours to choose and stay stable once shipped - profiles and configuration store them.

public sealed class StartRecordingAction : IActionDefinition
{
  public string Id => "start-recording"; // local id: lowercase kebab-case
  // ...
}
  • Pass the local id. Macro Deck qualifies it with your plugin’s identity; never pass an owner::local value to an API that expects a local id.
  • Runtime resource ids that come from provider state (entities, sources, topics) may use a broader grammar, but must not contain ::.

See also

Section titled “See also”