stream deck

    Reliable Shortcuts with Stream Deck and Keyboard Maestro

    I talked myself into buying a Stream Deck to control my Mac. I didn’t want one for the media features. I wanted a cool, programmable external keyboard-like thing to trigger actions. For example, I have buttons to turn my office lights on and off, toggle between playing sounds through my external speakers and headphones, and open my notes app to the Today’s Journal page. I like it.

    Most docs I found suggest using the Shortcuts plugin to execute Apple Shortcuts. I recommend that you use Keyboard Maestro instead. The “Shortcuts” plugin is neat in principle. It’s free. It looks like exactly the right tool for the job. For me, it’s not. Using the most current macOS (version 14.3.1), Stream Deck app (v6.5.0), and plugin (v1.0.7.1), keypresses work about half the time. After using the setup for a few days straight, it always hangs and stops responding altogether until I quit and restart the Stream Deck app. It’s frustrating to have this nice device to boost productivity, then have to pause for a beat every time I’ve used it to see if it worked.

    The Keyboard Maestro setup’s experience has been the opposite. Once configured, if I press a button, that button does what it’s supposed to do 100% of the time. It has some drawbacks: it’s slightly more complex to configure, and you have to pay for Keyboard Maestro (which if you’re a Mac power user, you’ll want to do anyway). Still, the result has been worth it.

    Here’s how I used it to build the toggle I mentioned that switches between speakers and headphones.

    First, I created Shortcuts called “SoundSource: Output to Headphones” and “SoundSource: Output to Speakers”, with each Shortcut doing the expected thing. The names don’t matter: I could have called them “Spam” and “Eggs” for all my Mac would care. I just like being verbose so I can quickly find things again next time I want to tweak them.

    The Shortcuts

    Next, I made Keyboard Maestro macros that execute those Shortcuts:

    "SoundSource: Output to Headphones" (without trigger) "SoundSource: Output to Speakers" (without trigger)

    Then I opened the Stream Deck app to create the “Multi Action Switch” button. I put mine on row 1, column 3. That’ll be important in a moment.

    Toggle 1 Toggle 2

    When you create a Keyboard Maestro action inside a Multi Action Switch, the Stream Deck app doesn’t fill in the “Virtual Row” and “Virtual Column” values like it would if you put the Keyboard Maestro action directly into an empty key. That’s OK. We’re going to change the column value anyway! See how I used Virtual Columns “301” and “302”? That lets the Keyboard Maestro app treat these as separate buttons. The Stream Deck app will do the work of remembering which action we’re currently on.

    With that done, I went back into the Keyboard Maestro editor and added “USB Device Key Triggers” to each macro. When it was waiting for me to press a button, I tapped the physical Stream Deck button I was setting up.

    "SoundSource: Output to Headphones" (with trigger) "SoundSource: Output to Speakers" (with trigger)

    That’s a little bit more complicated than the “Shortcuts plugin” setup, but only a little bit:

    • I’d have to create the Shortcuts either way.
    • I’d have to create the Multi Action Switch either way.
    • Instead of using the “Shortcuts” plugin to run Shortcuts directly, I send a trigger to Keyboard Maestro and have it run the Shortcuts.

    In exchange for this smidgen of extra one-time work, now my Stream Deck buttons work perfectly and instantly every time I press them. I don’t hesitate to see if the effect I wanted to happen had indeed happened because I can trust that it did. That made an enormous difference in how productively I can use the little Stream Deck.