Skip to content
Macro 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.
Messaging between plugins IIntegrationContext.Messages Talk to other plugins and integrations by topic: events, commands and requests.
Deck and clients IIntegrationContext.Deck Navigate folders and profiles, and find out which folder each client has open.
Music players IMusicPlayerProvider, IIntegrationContext.MusicPlayers Drive the Music Player widget and reuse Macro Deck’s ready-made music actions, and read every provider’s players and album colours.
Weather IWeatherProvider Supply weather stations to Macro Deck’s weather features.
Calendars ICalendarProvider Supply calendar accounts and events to Macro Deck’s calendar widgets, triggers and Join Meeting action.
Email inboxes IEmailInboxProvider Supply email inboxes to Macro Deck’s email widget, variables and triggers.
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.
Notifications INotificationService Show a toast or a dialog on every client and get the user’s answer.
Settings migrations IMigrationProvider Take over a user’s setup from Macro Deck 2.
Integration storage IIntegrationContext.Storage Keep small documents of your own, such as devices you have seen, across restarts.
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.
Android devices IAndroidDeviceManager Run shell commands, copy files and install apps on Android devices through Macro Deck’s ADB connection.
Batteries IBatteryProvider, IIntegrationContext.Batteries Report the battery levels of phones, headphones, controllers and other devices, and read every provider’s devices.
Companion devices ICompanionDeviceApi Read what the phones and tablets connected through the Companion app report, send them commands and take screenshots.
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.
Video streams IVideoStreamIntegration, IVideoStreamProvider Offer live video, such as cameras or OBS scenes, for Macro Deck to show.

Host APIs

Section titled “Host APIs”

IIntegrationContext gives an integration access to what Macro Deck owns: Deck navigation and client positions, Scripts, Widgets, NotificationService, Notifications, variables, configuration, events, messaging, battery devices, music players, images for your own UI, storage, the user’s time format and the User-Agent for outgoing requests. In a plugin every call crosses the plugin protocol, so don’t call them in a hot loop. Android devices and Companion devices can also be taken from dependency injection, as IAndroidDeviceManager and ICompanionDeviceApi.

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”