System
Included with Macro DeckControl your computer from your deck: apps, volume, commands, notifications, sleep and shutdown.
The System integration page with the switch turned on and no configuration options
- Launch, focus or close applications, files, folders and websites
- Volume and mute for the default or any audio device
- Run commands and save their output into a variable
- Lock, sleep, hibernate, restart or shut down
- CPU, RAM, GPU, disk, time and focused app as variables
The System integration controls the computer Macro Deck runs on. It comes with Macro Deck, is turned on from the start and needs no setup, on Windows, macOS and Linux.
What you can do
- Apps, files and websites: Launch Application starts an app, and its Mode can also bring a running app to the front (Start or Focus) or close it on a second press (Start / Stop Toggle). Open File, Open Folder and Open Website open things with their default app. Kill Application ends a process by name.
- Audio: Increase Volume, Decrease Volume, Set Volume and Mute / Unmute work on the default output, the default input or one specific device. A button with Mute / Unmute shows whether the device is muted.
- Commands: Run Command runs a command line in the default shell, PowerShell or Bash and can save what it prints into a variable.
- Notifications: Send Notification shows a notification of your operating system. Show Macro Deck notification shows a message inside Macro Deck on all connected screens.
- Power: Lock Computer, Sleep, Hibernate, Restart and Shut Down.
Variables
The integration reports the state of your computer as variables: CPU, RAM and GPU usage, every disk's size, free space and activity, the volume and mute state of every speaker and microphone, the date and time, the computer name and operating system, whether the screen is locked, and the application in front. Show them in labels, graph them with a History Graph or Gauges widget, or react to them in automations.
Example setups
- A mic button with Mute / Unmute on your headset microphone that shows whether it is muted.
- A slider bound to
system_volume_percentthat sets the speaker volume. - A Gauges widget with
system_cpu_usage_percent,system_ram_usage_percentandsystem_gpu_0_usage_percent. - A button that runs Launch Application with Start or Focus for your music player.
- A "good night" button that runs Lock Computer, or Shut Down after a Wait.
- A flow that runs Run Command with a script and writes the result into a variable shown on the button.
New audio devices and disks get their variables within a few seconds of being plugged in.
What you need
- Macro Deck 3 on Windows, macOS or Linux
- On Linux: pactl or amixer for volume, notify-send for notifications, systemd for the power actions
- On Linux, GPU usage needs the amdgpu driver or nvidia-smi
- On macOS, permission for Macro Deck to control System Events for Restart and Shut Down
Set it up
Step 1: Check that the integration is turned on
In Macro Deck, click Integrations in the sidebar and click System. The switch at the top right is on by default; turn it on if it is off. There is nothing to set up: the Overview tab shows No configuration options available for this integration. If something is missing on your computer, for example a volume backend on Linux, the page lists it as an issue.
Step 2: Add a System action to a button
On the Deck page, click a button. The deck must be unlocked: when the Lock button shows at the top right, it is. The editor opens with Short Press selected. Click + Add action, select System on the left of the Add action dialog and pick an action, for example Mute / Unmute or Launch Application.
Step 3: Fill in the action
Each action asks only for what it needs:
- Launch Application: the Application, optional Arguments and Working Directory, and the Mode.
- Volume actions: the Audio device, and the Amount (%) or Volume (%).
- Run Command: the Shell and the Command, optionally Save output to variable.
Step 4: Show a value on the button
To show a value, type a variable into the button's label, for example
CPU {{ vars.system_cpu_usage_percent }} %. The Variables tab of the System page lists every System variable with its current value.Step 5: Press the button
Save and press the button, or click Run in the editor to try the actions right away.
Actions17
Put these on a button or run them from a flow.
- Launch Application
- Starts an application, or toggles/focuses a running instance.
- Open Website
- Opens a website in the default browser.
- Open File
- Opens a file with its default application.
- Open Folder
- Opens a folder in the native file manager.
- Kill Application
- Ends a running process by its name, optionally asking it to close its window first.
- Increase Volume
- Raises the volume of the selected audio device.
- Decrease Volume
- Lowers the volume of the selected audio device.
- Mute / Unmute
- Toggles the mute state of the selected audio device and shows it on the button.
- Set Volume
- Sets the volume of the selected audio device to a specific level.
- Send Notification
- Shows a native notification of your operating system.
- Show Macro Deck notification
- Shows a message in Macro Deck on the connected devices and apps, as a short message or a dialog.
- Run Command
- Runs a command line in the selected shell and can save its output into a variable.
- Lock Computer
- Locks the screen, so you need your password or PIN to get back in.
- Sleep
- Puts the computer to sleep.
- Hibernate
- Saves the session to disk and powers off completely (Windows and Linux).
- Restart
- Restarts the computer, with Force to ignore apps that would block it.
- Shut Down
- Shuts the computer down, with Force to ignore apps that would block it.
Variables12
Show these values on buttons and widgets, or use them in conditions.
system_volume_percent,system_muted- Volume in percent and mute state of the default output device.
system_input_volume_percent,system_input_muted- Volume in percent and mute state of the default input device.
system_audio_output_<device>_*,system_audio_input_<device>_*- Volume in percent (
_volume_percent) and mute state (_muted) of every speaker and microphone, for examplesystem_audio_input_usb_mic_muted. system_cpu_usage_percent,system_cpu_name- Processor load in percent and the processor model.
system_ram_usage_percent,system_ram_used_gb,system_ram_total_gb- Memory in use in percent, used memory and total memory in GB.
system_gpu_<n>_usage_percent,system_gpu_<n>_name- Load in percent and name of each graphics card, numbered from
0, up to eight cards. system_disk_<n>_*- Name, mount point, file system, size, used and free space, usage, read and write speed and activity of each disk, numbered from
0, up to eight disks. system_date,system_time,system_datetime- The current date, time, and date and time as text.
system_timestamp_unix,system_day_of_week,system_hour,system_minute- Parts of the current time: the Unix timestamp, the day of the week, the hour and the minute.
system_pc_name,system_os- The computer name and the operating system.
system_locked- Whether the computer is locked (Windows and macOS).
system_focused_app,system_focused_app_path,system_focused_app_bundle_id- The application in front, with its path and bundle ID.
Frequently asked questions
Can I control the volume of one specific device?
Yes. Every volume action has an Audio device field with the default output, the default input and every device Macro Deck has seen. A device that is unplugged stays in the list and its variables read as unavailable until it is back.
Can I set the volume with a slider?
Yes. Bind a slider to a volume variable such as system_volume_percent. You can also set volume and mute variables with Set Variable. To switch mute on and off with one button, use Mute / Unmute.
Why does Restart or Shut Down fail on macOS?
macOS asks for permission first. Allow Macro Deck under System Settings > Privacy & Security > Automation > System Events. Force has no effect on macOS, and macOS has no Hibernate.
Why are volume, notifications or the power actions missing on Linux?
They need tools that some distributions do not install: pactl (PulseAudio or PipeWire) or amixer for volume, notify-send for notifications and systemctl or loginctl for the power actions. The System page under Integrations lists what is missing.
How long does Run Command wait?
Up to Timeout (seconds), 30 by default, and 0 waits until the command exits. A command still running after that keeps running, unless you save its output to a variable.
Are my Windows Utils buttons from Macro Deck 2 carried over?
Most of them. When you migrate from Macro Deck 2, actions such as start application, open file or folder, command line and volume become System actions, and hotkeys and typed text become Keyboard actions.
More in Your computer
Keyboard
Included with Macro DeckPress shortcuts, type text and run key sequences on your computer from a button.
Mouse
Included with Macro DeckClick, move the pointer, drag and scroll on your computer from a button.
ADB / Android Debug Bridge
Included with Macro DeckControl an Android phone or tablet over USB or Wi-Fi: wake it, start apps, tap, type and take screenshots.
Steam
Included with Macro DeckStart and close Steam games, and show what you play, your friends and your library on your deck.