Concepts

A streaming setup, built up piece by piece.

Profiles

One profile per use: Streaming, Work, Gaming. A profile holds all its folders and widgets. Switch between them at the top. Each device can open with its own profile.

To build a variant, for example a second streaming layout, duplicate a profile from the profile menu. The copy gets every folder, widget and setting, and is named like Streaming (copy). Automatic activation stays with the original, so set it up again for the copy if you want it.

Edit a profile from the profile menu to set its default grid size, widget spacing and corner radius. Turn Widget shadows off there for a flat deck, which also looks cleaner with very small spacing.

Folders

Inside Streaming: a start folder Home with Scenes, Audio and Chat subfolders, listed on the right. A button with Change Folder to opens a subfolder, Go Back returns.

Change Folder to, Change Profile to, Go to Parent Folder and Go Back have an optional Device setting. A button pressed on a device only moves that device. An automation has no device behind it, so with Device empty it moves every connected device. Pick a device there to move only that one. If it is not connected at that moment, the action reports an error instead of moving the others.

Widgets

The tiles in a folder:

Widget	Example
Action Button	Scenes, Go live, BRB
Slider	Mic volume
Clock	The current time and date
History Graph	CPU load over the last minutes
Weather	Today and the next days for your city. Press it for the full details
Music Player	What Spotify is playing, with play and skip. Some players offer extra settings for each widget below the player choice
Twitch Chat	Your channel’s chat with emotes and badges, offered once a Twitch account is connected
Twitch Stream Stats	Whether you are live, your viewers, chatters, followers and subscribers, the stream title, category and uptime, and a small graph, in a style you choose, offered once a Twitch account is connected
Countdown	A pizza timer that counts down and alerts you when it runs out
Stopwatch	How long the current segment of your stream has been running

Moderating from the Twitch Chat widget

Press the Twitch Chat widget to open the chat in a larger dialog. It stays at the newest message while you are at the bottom. Scroll up to read, and the chat stops moving; Jump to latest takes you back.

Tap a message to delete it, time out its sender for 1 minute, 10 minutes or 1 hour, ban or unban them. A ban asks you to confirm first. The dialog says whether the action worked, or why Twitch refused it:

• Twitch did not grant Macro Deck the permission for this action: reconnect the Twitch account in Integrations to grant the moderation permissions.
• Twitch did not allow this: reconnect the Twitch account in Integrations and try again.
• The host is locked: unlock the computer running Macro Deck, as for any other action.

Your channel’s own messages, and messages that reach your chat from another channel’s Shared Chat, offer no actions; moderate those on Twitch. Anyone who can use your deck can moderate through the dialog. To only show the chat, turn off Allow moderation in the chat dialog in the widget’s settings. Widgets that a plugin places in its own profiles open the chat without moderation. The dialog opens on the device you pressed the widget on, so a press on a hardware deck does not open it.

On a small device or a large widget, change Size (%) in the widget’s settings to make the chat text bigger or smaller. 100 is the default and values from 25 to 300 are accepted. The size applies to the widget; the chat dialog keeps its own.

The Twitch Stream Stats widget

Pick what the widget shows with Style in its settings. Each style names the size it is designed for, and keeps the same content at any other size, only larger or smaller:

Style	Shows
Overview (3x2)	Your channel name and live status, the stream thumbnail, title, category and uptime, and a row of stat tiles
Stats row (3x1)	A row of stat tiles
Live status row (3x1)	The live status and category, with one number beside them
Single value with graph (2x2)	One number, the live status and a graph of that number
Single value (1x1)	One number with a live dot

For the Overview and the Stats row, Stats chooses which tiles appear, out of viewers, chatters, followers and subscribers, and in which order: drag a row or use its arrows. Viewers, chatters and followers are on by default. Four tiles fit best in a widget one column wider than the style’s size. The Overview also has Stream details, which chooses and orders the title, category and uptime next to the thumbnail, and Show thumbnail. For the other three styles, Value chooses the number they show.

The graph follows the chosen number. It starts when the widget is first shown and begins again after Macro Deck restarts, so it fills over time; followers and subscribers change slowly, so their graph often stays flat. Offline, viewers and chatters show a dash, while followers and subscribers stay. Subscribers also show a dash while Twitch does not report them to Macro Deck.

Everything the widget shows is also a regular variable of the Twitch integration, named twitch_<account>_viewer_count, twitch_<account>_chatter_count, twitch_<account>_follower_count, twitch_<account>_subscriber_count, twitch_<account>_display_name, twitch_<account>_stream_title, twitch_<account>_stream_category, twitch_<account>_uptime_seconds, twitch_<account>_is_live and twitch_<account>_stream_thumbnail_url. Use them in your own widgets, actions and conditions. The chatter count is everyone in your chat, including you and bots, and needs one more permission: if Integrations shows that the account lacks it, reconnect the Twitch account.

Countdown and Stopwatch

A Countdown counts down from a duration you set in its settings. Tap it to start, tap again to pause and again to continue; hold it to reset it. When the time runs out the widget turns red with a pulsing ring until you tap it, which also resets it.

Set When started to Ask for the duration to choose the time each time instead. Tapping the idle countdown then opens a dialog with quick choices from 1 minute to 1 hour, or hours, minutes and seconds to set yourself. After a reset, or once a finished countdown was tapped, the next tap asks again. The dialog opens on the device you tapped. A hardware deck cannot show it, so a press there starts the duration entered last and does nothing until one was entered.

A Stopwatch starts on a tap, pauses on the next and continues on the one after. Hold it to set it back to zero. Its ring goes round once a minute.

Both widgets offer their own triggers in the widget editor, so actions can run when something happens:

Widget	Triggers
Countdown	Started (also when it continues), Paused, Reset, Time’s Up, Dismissed
Stopwatch	Started (also when it continues), Paused, Reset

They also keep variables of their own, which the widget’s own actions can use, for example in If / Else or a Set Variable that copies the time into one of your variables:

Widget	Variables
Countdown	countdown_remaining_seconds, countdown_running, countdown_finished
Stopwatch	stopwatch_elapsed_seconds, stopwatch_running

These change every second while a timer runs, so an automation on Variable Changed without a filter runs every second too. A running countdown or stopwatch starts over when Macro Deck restarts. On a hardware deck, the key shows the widget’s label and colors but not the time.

Actions and triggers

What a widget does, and when. The Scenes button runs Change Folder to on a short press:

Trigger	Example action
Short Press	Switch OBS scene
Long Press	Start the stream
Double Tap	Mute all audio
Event	Turn the mic slider’s accent red when OBS reports Streaming Started

Some widgets already do something on a short press before you add anything: pressing a Weather widget opens its details. Give such a widget a Short Press action of your own and yours runs instead. A hardware deck has no screen for the weather details, so the Weather widget does nothing there until you add an action.

Every widget with actions, sliders included, can add event triggers next to its press triggers. Give an event trigger a Name to tell several of them apart in the Events list.

Once a widget has a Double Tap action, its Short Press waits a moment to see whether a second tap follows, so a single tap runs slightly later. A double tap runs only the Double Tap action. On a slider, a double tap still moves the level with each tap.

Actions run top to bottom. If / Else, Switch, Repeat and Wait build longer flows, for example: mute the mic, wait 3 seconds, switch the scene. Run tries them out right away.

Switch picks one path by a value, so a single block replaces a chain of If / Else blocks. Put the value to look at in Switch on, usually a variable, then add a Case for each value you care about and the actions to run for it. The cases are checked from top to bottom and only the first match runs. Otherwise runs when no case matches or the variable you picked has no value. Matching works like If / Else with is: text must match exactly, so all does not match All, while numbers compare by value.

Button states

The Mic button has two states, Live and Muted, each with its own label and color. Every tap switches to the next one.

With State mapping, the state follows a variable instead, for example Discord’s Self Muted. The button then shows the truth even when you mute in Discord itself.

Some actions know their own state, for example Mute / Unmute or OBS’s scene actions. The action list marks them, and each one gets a button to let it drive this button’s states. When you add such an action, the editor offers this right away. The action then decides which states exist, and you still style each of them. The × next to Provided by brings your own states back. Plugin actions that supply an icon work the same way for the button’s icon.

Variables

Values you can show and use anywhere:

• Integration variables: the CPU load, the date, the weather, the current OBS scene.
• User variables: your own, for example a deaths counter.

Show one in a label with {{ vars.deaths }}, like the Deaths: 3 button above.

Every speaker and microphone gets its own volume and mute variable, named after the device, for example system_audio_input_usb_mic_volume_percent. An unplugged device keeps its variables; they read as unavailable until it is back. The volume actions can control the default output, the default input or one specific device.

Some integrations, such as Home Assistant, offer far more values than they list up front. These wait in a collapsed Unbound variables group at the top of the integration’s variables, on the Variables page, in every variable picker and on the integration’s own page. Open the group, or search for an entity by name or variable name, then open an entity to see its state and attributes and choose Bind on the one you want: it becomes a normal variable. If you know the entity id, for example light.office_lamp or light.office_lamp/brightness, pick the integration in the variable browser and type it under Enter a resource ID instead.

A Slider can control Home Assistant too. In the slider’s Variable field, open Unbound variables under Home Assistant, then the entity, and pick the value to adjust:

Entity	Value to pick
Light	brightness_pct, the brightness in percent, or color_temp_kelvin
Fan	percentage
Cover, valve	current_position, and current_tilt_position for a cover
Media player	volume_level
Thermostat, water heater	temperature
Thermostat, humidifier	humidity
Number, number helper	state

The slider shows the value Home Assistant reports and sends the new one when you let go. Dragging a light to zero turns it off, and dragging a light that is off turns it on. An entity with nothing to adjust right now, such as a media player in standby, ignores the slider. A value you bound before as Text is not offered: remove that variable and bind the value again.

A user variable can also read from a file, like OBS’s Read from file: choose Read from file as its source when you create it and pick the file. The variable shows the file’s content and follows every change another program or script makes to it. A trailing line break is ignored, and a number or true/false variable needs content of that kind. While the file is missing, unreadable or does not fit, the variable reads as unavailable.

Such a variable is read-only. Turn on Allow write-back to let changes made in Macro Deck, for example with a slider or Set Variable, go into the file too. File settings in the variable’s menu changes the file or write-back later. When you export widgets, a variable that reads from a file travels as an empty variable: neither its path nor the file’s content goes into the archive. Macro Deck watches the file for changes; a file on a network share may not report them.

To save any variable’s value on demand, use the Write Variable to File action. It replaces the file’s content with the current value, creates the file if needed, and needs a full path whose folder exists.

Only your own variables can read from a file. To keep a file up to date with any other variable, for example the current OBS scene or system_cpu_usage_percent, create an automation: the event Variable Changed watching that variable runs Write Variable to File for the same variable. Every change then lands in the file.

Share variables with another Macro Deck

With Macro Deck Delegate, one Macro Deck can use the variables of another one, for example to show on your streaming PC whether OBS on your gaming PC is live. Both sides have to agree:

1. On the Macro Deck that has the variable, open the variable’s menu on the Variables page and choose Share with other Macro Decks. Any global variable can be shared, your own and integration variables alike. Shared variables are marked Shared; Stop sharing in the same menu takes it back.
2. On the other Macro Deck, add or edit the Macro Deck Delegate connection to it and turn on Import shared variables. It is off by default.

The shared variables then appear there under the other computer’s name, so obs_streaming shared by a computer called Gaming-PC becomes {{ vars.gaming_pc_obs_streaming }}. Sharing and unsharing show up within a few seconds, without a restart. While the other Macro Deck is off or cannot be reached, its variables read as unavailable; once it is back, they catch up within a few minutes at most. If a name is already taken by another variable, or is longer than 64 characters with the computer’s name in front, that variable is left out, and the connection shows a warning listing it.

A shared variable that can be changed on its own Macro Deck can be changed from the other one too, for example with a slider or Set Variable, so anyone who can change variables on the importing Macro Deck can change it. A Macro Deck from before variable sharing simply shares nothing.

Scripts and automations

• Script: actions you reuse, for example Go live used by three buttons. Any device signed in to Macro Deck can also list and run every script that does not run on a widget, with its own input values. Macro Deck Companion does this from Shortcuts or Siri on iOS.
• Automation: actions that run on an event without belonging to a widget. Evening stream switches the deck to the Streaming profile every day at 18:00:

Other events: a device connects, a variable changes, OBS reports Streaming Started, a song starts playing.

Integrations and the Store

Integrations connect Macro Deck to other apps: OBS, Home Assistant, Voicemeeter, Spotify, Twitch, Discord and more. Turn on the ones you use under Integrations.

The Store offers more plugins and icon packs. Everything published there is reviewed and signed first.

Plugins and icon packs in the Store are made by the community. The first time you open the Store, a notice explains that the creator of an item is responsible for it when something fails or doesn’t work: rate the item, open an issue in its repository or report it, using the links on its page, and don’t open issues about Store items in the Macro Deck repository. Everything in the Store is subject to the Store guidelines; the notice and the bottom of every Store page open them, next to the imprint and privacy policy. Got it hides the notice for good.

Discover opens with a search box and a chip for each kind of item (All, Plugins, Icon packs) with how many there are. Under those, a chip for each Store category that has items of that kind, such as Music or Streaming, lists only that category; choose it again to see everything. Below it, every item is listed as a card showing its kind, rating, installs and whether it is New (published in the last 30 days) or recently Updated. The list is sorted by Most popular unless you pick another order or search. Once the Store has enough items, rows for Featured, Popular and New & updated appear above the list, each item in at most one row. Searching also finds items by their tags. Only available for this platform hides items that do not run on your computer, and it stays on until you turn it off; a note says how many items it hides, with Show all next to it. Going back from an item’s page returns to the list as you left it: the same search, kind, category, order and scroll position.

The ⋮ menu at the top right of the Store has Refresh Store and Store settings. Refresh Store fetches the latest catalog and opens a log of each step as it happens. Macro Deck also refreshes on its own a few seconds after it starts and then once an hour. While a refresh runs, the Store header says Refreshing… in every window, and choosing Refresh Store again opens the log of that refresh instead of starting a second one. If the store registry is being updated while a refresh runs, the log says so and Macro Deck tries again a few times over about five minutes before it reports a failure. Store settings opens Settings > Store.

Installed at the top of the Store lists the Store’s plugins and icon packs you have installed, with their version and any update waiting for them. While updates are waiting, Installed shows how many. Update one at a time from its card, or all at once with Update all. After an update downloads, the card shows Installing… while Macro Deck backs up, installs and restarts the plugin, then the version that is now installed. See Updates for update notifications and automatic updates.

Icon packs from the Store are read-only on the Icon Packs page. You can use their icons on your buttons and export the pack, but you can’t rename, import, or delete icons in it, or edit its name and details. Deleting the pack there uninstalls it from the Store. To change the icons, export the pack and import the copy as a pack of your own.

An exported pack has a size limit: at most 29,995 icons, and only so much text for the icons’ names and details. When a pack is larger, Macro Deck tells you it is too large to export; split it into smaller packs.

An item’s page shows its screenshots, description, what changed in the latest version and, in the details beside it, whether it runs on your platform. It lists Links its creator provides, such as its Homepage, the source repository, documentation or a place to report an issue. They open in your browser.

An item in a Store category lists it under Categories, and any other tags its creator gave it under Tags; select one to see every item in that category or with that tag. At the bottom, You might also like suggests items you have not installed that run on your computer: first those that share tags with it, then others from the same creator and of the same kind. Going back from a suggestion returns to the item you opened it from.

Under AI, the page shows what the creator declares about artificial intelligence: whether the item lets you interact with an AI system, generates content with AI, or contains images, sounds or texts created with AI, and which AI services it uses. Next to its name, an item that uses AI is marked Uses AI, and one that only contains content created with AI, such as an icon pack with AI-created icons, is marked Made with AI. If the creator has not declared anything, the page says so; that does not mean the item uses no AI.

For your own icon packs, select Edit on the pack under Library > Icon Packs (or Edit pack in its menu) and set AI-created icons. The setting is saved in the exported pack. When you merge a pack that contains AI-created icons into one of yours, your pack is marked as containing them too.

To install an older version, pick it under Version next to the install button. The latest version is selected by default. The button then says Install, Update to or Downgrade to that version, and a downgrade asks you to confirm first. Versions that cannot be installed on your computer stay in the list but cannot be selected. Whether a version works with your Macro Deck version is only known once it is downloaded: if it needs a newer Macro Deck, the Store says so and offers Check for updates instead of Retry. All versions under What’s new lists every version with its release notes. See Updates for how an older version affects automatic updates.

Select the publisher’s name on a card or an item’s page to see everything that publisher offers. An installed plugin’s page has Open settings, which opens its integration; its back arrow returns to the Store page. An installed icon pack’s page has Open in Library. The other way round, a plugin’s page under Integrations and a Store icon pack under Library > Icon Packs have View in Store, for the description and release notes. An installed plugin is uninstalled from the General details of its page under Integrations, or from its Store page. Uninstalling a plugin also removes the variables it provided.

A macrodeck:// link to an item opens its page in Macro Deck, and a message appears if the item is no longer in the Store. See Store links for the details, including the AppImage limitation.

The Store footer links to the Creator Portal, where you can publish your own plugins and icon packs, and to the imprint and privacy policy.

Store items show their star rating and how many times they have been installed. The install count leaves out updates and repairs, and appears once an item has been installed at least once. An item’s page lists its Ratings and reviews, which anyone can read. When the creator has answered a review, their reply appears under it as a Developer response. To rate or review an item yourself, sign in with Macro Deck Connect under Settings > Account and install the item first: only items you have installed can be rated. When you sign in, and whenever you install something while signed in, Macro Deck records your installed Store items for your account so you can rate them. If ratings or install counts cannot be reached, the Store keeps working without them.

While you are signed in, Macro Deck occasionally asks you to rate one of your installed Store items. The dialog shows the item and five stars; choose a star and Submit to send the rating, or add a written review if you like. Not now closes it without rating, and the item can come up again later. Macro Deck only asks about items you installed at least 7 days ago and have not rated yet, asks about one item at a time, and waits at least 5 days after a prompt was shown before it asks again. Updating an item does not restart the 7 days. Turn the prompt off with Ask me to rate installed extensions in Settings > Store.

To report a Store item, open its page and choose Report this item below the details. To report a review, choose Report next to it. Pick a reason and, if you like, add details; Other needs a short description. Reporting needs a Macro Deck Connect sign-in, and each review can be reported once per account. Reports go to the Macro Deck moderators and do not hide anything on their own: the item or review stays visible until a moderator has looked at it. Reporting Store items only works once the Store supports it; until then, Macro Deck tells you it is not available.

Tests

A plugin creator can invite you to test a plugin before it is reviewed. The invitation arrives by email; accept it in the Creator Portal with the same Macro Deck account you use in Macro Deck. While you are signed in under Settings > Account, Tests appears at the top of the Store next to Installed, listing every plugin you test. Each plugin starts collapsed and shows how many test builds it has; select it to see its builds, newest first.

Test builds are not reviewed or signed by Macro Deck: they come straight from the creator and may be unstable. Choosing Install or Install test build asks you to confirm that first. A test build replaces the version of the plugin you have installed, including one from the Store, and the build that is currently installed shows as Installed.

While a test build is installed, the plugin is marked Test build under Tests, Installed and Discover. If the plugin is also published in the Store, Return to Store version installs its current Store release in place of the test build.

Withdrawn versions

The Store can withdraw a single version of an item, for example when that version turned out to be unsafe. A withdrawn version is marked Withdrawn under Version and cannot be installed; the other versions stay available. If the version you have installed is withdrawn, its card is marked Version withdrawn, its page says why and may name a suggested replacement, and Macro Deck shows a warning notification. Update to the latest version from its card, or open its page to go back to the latest version with Downgrade to when the latest version is older than yours, or uninstall it.

When the latest version of an item is withdrawn, the item disappears from the Store and can no longer be installed or updated. If you have it installed, it stays under Installed, marked Removed from the Store, and its page says why; you can still uninstall it there.

Icon packs from plugins

A plugin can bring its own icon packs, for example the logos of the services it controls. They appear under Library > Icon Packs and in the icon picker as soon as the plugin is installed, marked Plugin; hover the mark to see which plugin provides the pack. Use their icons on any button, not only on the plugin’s own.

These packs are read-only, like icon packs from the Store, and you can’t delete them yourself. They update together with the plugin: an update replaces the icons that changed, and buttons keep showing the icon they use.

When you uninstall the plugin, or an update no longer includes one of its packs, the pack is deleted. If a button or an automation still uses one of its icons, the pack stays instead, becomes an ordinary icon pack you can edit or delete, and Macro Deck shows a notification that says why it was kept. An icon that is only chosen in a plugin’s own settings does not count as used. When the plugin later brings the same pack back, for example after a reinstall, it takes the pack over again: the pack becomes read-only once more and any changes you made to it in the meantime are replaced by the plugin’s icons.

While a plugin developer runs a plugin from its project, its packs appear the same way. If that plugin is never installed, the packs stay as ordinary icon packs after the developer stops it.

Devices

Every phone, tablet or browser that connects shows up in Settings > Devices. Choose there which profile each device opens with. If you delete the profile a device is showing, the device switches to the profile it opens with, or to your first profile if that one is gone too.

For a deck in a browser, choose Hide settings button in its menu there to take the settings button off its screen, and Show settings button to bring it back. The deck’s own settings have the same Hide settings button switch under Display, and both change the same setting. The device then reaches its settings with a swipe in from the left edge of the screen, which slides in a panel with the settings button. The swipe can start a little in from the edge, which helps where the system uses a swipe from the left edge for Back, such as Android gesture navigation or a Safari tab. Hiding the button is not a lock: anyone at the device can still swipe.

When you are signed in under Settings > Account, a Companion app license this computer got from a purchase is saved to your Macro Deck account, and your other computers signed in to it that have no license yet receive it within about a minute (see The Companion app stays unlicensed after a purchase).

Open source licenses

Macro Deck is built on open source software. Settings > About > Open source licenses lists every third-party component it includes, with its license and the full license text; search by name or license. On a phone or tablet, the web client’s settings offer the same list under Open source licenses. The files LICENSE, NOTICE and THIRD-PARTY-NOTICES also sit next to the Macro Deck host in the installation folder, and the Linux AppImage adds a notices file for the system libraries it bundles.