Drive Your Stage Timer From a Stream Deck (or Anything)

Wire your stage timer to a Stream Deck in under 10 minutes with these four steps: (1) generate an EZStageManager Pro API key, (2) install the free Bitfocus Companion desktop app, (3) add a Generic HTTP connection, and (4) configure each button as an HTTP POST pointing at endpoints like /api/v1/rooms/YOUR_ROOM/timer/start with an Authorization: Bearer YOUR_KEY header.

Every show producer reaches a moment where alt-tabbing to the browser to hit Play feels like the wrong move. Real consoles have buttons. Here’s how to give your timer the same treatment — physical, dedicated, one-press-one-action.

Why physical buttons matter

Browsers are great for setup. Mid-show, they’re a liability. A misclicked tab, a keyboard shortcut that doesn’t fire because the wrong window has focus, a notification banner that steals attention — none of these things happen on a Stream Deck. You press a button, the action fires.

For most operators, the highest-leverage physical buttons are:

• Start / Pause — the most-pressed buttons in any show
• +1 min / −1 min — for the inevitable on-the-fly schedule changes
• Send pre-set messages to stage— “Wrap up,” “Q&A next,” “Great job”
• Flash— when the speaker has tunnel vision and isn’t looking at the timer
• Blackout — between segments

What you need

• An EZStageManager Pro account (API access is Pro-only)
• Bitfocus Companion — free, runs on Mac/Windows/Linux. Download here.
• An Elgato Stream Deck(optional). Companion has an on-screen emulator if you’re just testing or don’t have hardware yet.

Total cost beyond the Pro plan: $0 if you skip the hardware.

Step-by-step setup

1. Generate an API key

Open your API keys page and click Generate key. Name it something you’ll remember — for example, “Stream Deck — Mainstage.” Copy the full key the moment it appears. You won’t see it again. If you lose it, revoke and create another.

2. Install Companion and add the HTTP module

Open Companion. Go to the Connections tab → click Add connection → search for Generic HTTP→ add it. It’s the official way to wire any button to any HTTP endpoint.

3. Create your first button

Pick an empty button on your surface. Configure it like this:

• Action source: Generic HTTP
• Action: HTTP POST
• URL:
  https://ezstagemanager.com/api/v1/rooms/YOUR_ROOM/timer/start
• Header: Authorization = Bearer ezsm_live_... (your key from step 1)

Replace YOUR_ROOMwith the code that shows up in your controller’s URL — for example, abc-1234.

4. Press the button

Your timer starts. If it doesn’t, jump to the troubleshooting section.

A button layout that works

For a 15-button Stream Deck Mk.2 (or the equivalent Companion emulator), this layout covers ~95% of live-show needs:

Row 1:  [ START ]  [ PAUSE ]  [ RESET ]  [ +1 MIN ]  [ −1 MIN ]
Row 2:  [ FLASH ]  [ BLKOUT ]  [ MSG: Wrap ]  [ MSG: QA ]  [ MSG: Clear ]
Row 3:  [       ]  [       ]  [          ]  [        ]  [           ]

The endpoints behind each:

• START: POST /api/v1/rooms/YOUR_ROOM/timer/start
• PAUSE: POST .../timer/pause
• RESET: POST .../timer/reset
• +1 MIN: POST .../timer/add?seconds=60
• −1 MIN: POST .../timer/add?seconds=-60
• FLASH: POST .../flash
• BLKOUT: POST .../blackout (no params = toggle)
• MSG: Wrap: POST .../message?text=Wrap+up&type=warning
• MSG: QA: POST .../message?text=Q%26A+next&type=info
• MSG: Clear: DELETE .../message

Pro tip: Companion supports button feedback. Point a button’s text source at GET /api/v1/rooms/YOUR_ROOM and display the live remaining_seconds on the button face. Now your Stream Deck shows the clock without taking your eyes off the room.

Beyond Stream Deck

Anything that can make an HTTP request can drive your timer. A few patterns that producers we’ve talked to use:

• A shell script on the desk laptop that auto-starts the timer at a scheduled time:

  #!/bin/bash
  sleep_until="09:00:00"
  while [[ "$(date +%H:%M:%S)" < "$sleep_until" ]]; do sleep 1; done
  curl -X POST https://ezstagemanager.com/api/v1/rooms/abc-1234/timer/start \
    -H "Authorization: Bearer $EZSM_KEY"

• A Zapier / Make.com / n8n flow that fires a message to stage when a calendar event starts.
• An MQTT bridge if you live in the home-automation world and want a physical knob to drive your timer.
• Your own custom hardware — an ESP32, an Arduino with WiFi, a Raspberry Pi with a fancy button. The API is just a URL.

Troubleshooting

401 Unauthorized

Your Authorization header is missing or the key is wrong. Common mistakes: forgetting the Bearer prefix, copying only part of the key, or using a key you’ve since revoked.

403 Forbidden

Either your Pro subscription lapsed (keys validate Pro on every request) or the room belongs to a different account. Check your account page.

404 Not Found

The room code in the URL doesn’t match any room you own. Re-check by visiting your rooms page and copying the code from the room you intend to control.

200 OK but nothing happens on screen

Almost certainly: you’re hitting a room that doesn’t have an open viewer/controller tab. The API write succeeded; nothing is rendering it. Open the viewer URL in a separate window to confirm.

Want the full endpoint reference? See the API docs. Want to talk to a human? Email support@ezstagemanager.com.