Stream Deck — Down the Rabbit Hole, Part 3

At the end of Part 2, I had a really useful set of buttons, many with nice button faces, and I was looking into how to get live information to display on a button. I knew there were plugins that did this for their specific functions, but I could not figure out how I could get my own information shown.

I posted a question on the Mac Power Users forums and was pointed to an application called Better Touch Tool, or “BTT” for short. I’d looked at this software before, and even trialled it, but I didn’t really see myself using custom gestures on my mouse or trackpad, which were its flagship feature. However, now I was being told it could handle Stream Deck buttons! I checked it out and was amazed at the feature set included in this software.

At its core, BTT has many types of triggers and many types of actions and you can wire these together in any way you can imagine. The triggers include the aforementioned custom gestures, but also keyboard shortcuts, text snippets, Siri remotes, MIDI device controls, a BTT remote app on your phone, the MacBook Pro TouchBar, and, as of a recent version, the Stream Deck. Actions include… well… seemingly everything.

There are 15 different categories, with actions like sending a key press to a specific application (a requirement I mentioned in part 2), performing a mouse click, hiding an application, running a script, opening a URL, resizing a window, and putting the computer to sleep. In all there are over 150 defined actions and while many are very specific — like “press F19” — some are very flexible — like “run a script” or “send a key to an application”.

BTT addresses the Stream Deck in one of two ways. You can either install a native Stream Deck plugin, which BTT will then communicate with, or you can quit the Stream Deck software altogether and have BTT completely control the Stream Deck. I dipped my toes in the water with the plugin until I got an idea of what could be achieved, then very quickly went all in with full control. Because I made this leap fairly early in my Stream Deck journey, there may be things I mention here, in the context of BTT, which are in fact possible with the native Stream Deck software.

The BTT interface is fairly straightforward. Where I disliked the clunkiness of the Stream Deck software, BTT is a lot more obvious to me, though it does have some quirky bugs you will almost certainly have to work around. One is when deleting actions from a trigger; it doesn’t seem to like deleting more than one at a time. I must get around to reporting that one.

The application is hierarchical in the way it works. On the left is a list of applications. There is a special entry of “All” which contains triggers and actions that will apply regardless of the currently focused application. Then you can set up triggers that only appear when the named application is focused. A good example of the usefulness of this is having buttons on my Stream Deck to set Finder tags, which only make sense when Finder is the focused application. On the other hand, my light controls make sense no matter which application has the focus.

The next level is the trigger types. There are separate sections for Stream Deck, TouchBar, Keyboard, Mouse, etc. This makes a lot of sense as the different trigger types have quite different requirements. There is no need, for example, to have an icon for a keyboard shortcut like there is for a Stream Deck button.

Next is the “Groups and Top Level Triggers”. I should preface here that I’ve mostly only worked with Stream Deck and TouchBar triggers thus far. Groups on the Stream Deck manifest as a button which, when pressed, opens up a whole new set of buttons. I have all my light controls in a group, for example.

The first action to set up a Stream Deck button is to add a trigger which, broadly speaking, represents a single button. You then get to configure the button, including some rules for when it will appear, such as based on modifier keys being held down, or only on certain Stream Deck devices if you have more than one. You can also position the button explicitly or leave it to BTT to flow into an available spot on the device.

The other aspect to buttons is their appearance. Delightfully, BTT has built in support for SF Symbols, so you can easily create decent looking buttons with very little work. You can also put regular text on them and there are controls for colours and sizing and positioning of the symbol or text and colour of the background. My preference is to create my own image and this can very simply be dragged into the configuration.

There is an oddity in how BTT handles custom button images. It seems like it wants a 96 pixel square image by default, however I have conclusively proven that my actual Stream Deck buttons are 72 pixels square. I just create my buttons at 96 pixels and drag them in and it all seems to work, so it’s not a problem, as such, unless you’re trying to be pixel-perfect.

With basic configuration and appearance set, the real fun begins… adding the actions. Unlike Stream Deck’s clunky ‘multi action action’, BTT expects you to add multiple actions. My longest one to date has 26 actions. Adding actions is fairly straightforward, although another bug rears its head here.

When you add the first action, the application jumps back to the top level of its hierarchy, so you do not immediately get to edit your action. If you’re in a group, this is quite disconcerting, as you’re taken back out of the group. It’s easy to just go back to the action, but there are a few paper cut bugs like this.

As soon as you have configured any triggers and actions they are live, though with groups it seems you have to exit the group and return to see new buttons or new imagery on existing buttons.

So I have described a greatly expanded, if somewhat buggy version of the native Stream Deck software. Is that worth the price of BTT? I think so, because it has a much wider array of capabilities for the Stream Deck and, even with the bugs, it’s easier to build up complex action sequences and also to have your buttons adapt to the current environment. Then you can add in all the other capabilities of the software.

I have a TouchBar-equipped MacBook Pro. I’ve never been against the TouchBar, but neither had I really made much use of it. Until I got BTT. Now I have a battery percentage and charge time indication, the latest readings from my personal weather station, which opens my Weather Underground web page when tapped, a list of ejectable drives, which ejects those drives when tapped, and an indicator of current Bluetooth status, which toggles Bluetooth on or off when tapped.

For me, the main thing BTT has enabled is total nerdery. In part 1, I described how I set the lights in my study for my nights on call. That process has changed a few times and currently does this:

1. Turn off the Canvas light panels.
2. Set all of the room lights to bright green for 4 seconds.
3. Set all of the room lights to bright orange for 4 seconds.
4. Set all of the room lights to bright red for 4 seconds.
5. Drop the brightness of the room lights to 10%.
6. Set my Mac screen brightness to 10%.
7. Set the Stream Deck brightness to 10%.

This takes a total of 26 steps, mostly calling a shell script I developed as a wrapper for very long HomeControl URLs.

My current Stream Deck configurations are:

• The lighting group with 5 buttons for room light control, 3 to set scenes on the Canvas, and 4 to set the Canvas brightness to fixed levels, including off.
• The Microsoft Teams group with 9 buttons.
• A laptop battery level indication. This button doesn’t do anything, but its appearance is set by a shell script so it shows me the current battery percentage.
• Seven Finder tag buttons (six colours and a clear) that appear only when Finder is focused. These run AppleScript which in turn calls a shell script.
• A group of 10 buttons that appear when DxO PhotoLab is focused, which give access to commonly used tools.
• An additional group of 8 buttons for PhotoLab for its Local Adjustment mode.
• A button for the Citrix Viewer application that presses a special key to invoke the Windows “Insert” key (which is not present on Mac keyboards).
• A button for Terminal that enters the SSH command to my web server.

That’s 51 buttons in total (not counting the group buttons) using a variety of actions types. I think I’ve only just begun.