Controlling Stagetimer via Companion for Stream Deck (Comprehensive Guide)

Companion, an open-source software, enhances your live video production experience by allowing you to control hardware and software, such as Stagetimer, using Elgato’s Stream Deck. This user guide will walk you through the process of setting up the Companion with the Stagetimer module and explain the functions available.
Please note, you’ll need a Stagetimer account with a Pro or Premium plan to access the API, a prerequisite for Companion integration.
Getting Started
-
The first step is to acquire an Elgato Stream Deck, a budget-friendly keypad equipped with programmable LCD buttons. You can purchase it here.
Elgato Stream Deck -
Download and launch the Companion app.
-
In the GUI, add the “stagetimer.io: Stagetimer API” connection.
Adding the Stagetimer API connection in the Companion app -
The Companion module can control one Stagetimer room. Open the desired room to get its Room ID and API key.
Retrieving the Room ID and API key API key location -
Input the Room ID and API key into the Stagetimer connection on the Companion app. Click “Save” and ensure the status turns into a green checkmark, confirming successful setup.
Stagetimer connection status check Note: The Companion module can also be used with the Stagetimer offline version. In this scenario, you need to adjust the API URL to connect with your offline version (explained later).
-
Now, let’s add a button. Switch to the “Buttons” tab in Companion, navigate to “Presets” → “Stagetimer API” → “Transport”, and drag and drop the “Start/Stop” button onto one of the available Stream Deck fields. The new button should appear on your Stream Deck, ready to control your Stagetimer!
Adding the “Start/Stop” button The “Start/Stop” button visible on the Stream Deck -
Feel free to add any other buttons based on your requirements and kickstart your event!
Reference
The Stagetimer module provides numerous presets, actions, variables, and feedbacks. You can inspect the preset buttons as examples to see how to use these elements to create your own custom buttons.
Presets
Transport Presets
Preset | Description |
---|---|
Start/Stop | Toggle the timer between start and stop, the button turns red when the timer is started |
Start | Start the timer, the button turns red when the timer is started |
Stop | Stop or pause the timer, the button turns red when the timer is paused |
Previous | Resets the timer or selects the previous timer if it already is reset. Has an option to autostart the previous timer. |
Next | Selects the next timer. Has an option to autostart the next timer. |
+5min | Add 5 minutes to the current timer |
+1min | Add 1 minute to the current timer |
+30s | Add 30 seconds to the current timer |
-5min | Subtract 5 minutes from the current timer |
-1min | Subtract 1 minute from the current timer |
-30s | Subtract 30 seconds from the current timer |
Viewer Presets
Preset | Description |
---|---|
Current timer | Shows a live countdown of the current timer including wrap-up colors |
Ready: Wrap up time indicator | Indicates the current wrap-up state “On time”, “Wrap up..”, “Wrap up!”, “Over time!” |
Current title | Shows the title of the current timer |
Current speaker | Shows the speaker of the current timer |
Flash 3 times | Triggers the timer to flash 3 times. Option to flash between 1 and 99 times |
Stop flashing | Stops the timer from flashing |
Toggle blackout mode | Toggles blackout mode on or off, hiding the timer |
Toggle focus mode | Toggles focus mode on or off, emphasizing the message |
Timer Presets
Preset | Description |
---|---|
Reset | Reset to the first timer. Option to target any timer indicated by index (starting from 1) or timer ID |
Start timer | Start the second timer. Option to target any timer indicated by index (starting from 1) or timer ID |
Stop timer | Stop the second timer. Option to target any timer indicated by index (starting from 1) or timer ID |
Message Presets
Preset | Description |
---|---|
Toggle message | Toggle the first message. Option to target any message indicated by index (starting from 1) or timer ID |
Show message | Show the second message. Option to target any message indicated by index (starting from 1) or timer ID |
Hide message | Hide the second message. Option to target any message indicated by index (starting from 1) or timer ID |
Actions
Action | Description |
---|---|
Message: Hide | Hide a message in the room |
Message: Show | Show a message in the room |
Message: Toggle visibility | Show/hide a message in the room |
Timer: Reset | Reset a specific timer to the original duration |
Timer: Start | Start or resume a specific timer in the room |
Timer: Stop | Stop a specific timer in the room |
Timer: Toggle playback | Toggle (start/stop) a specific timer in the room |
Transport: Add time | Add an amount of time to the highlighted timer in the room |
Transport: Next | Highlight the next timer in the list |
Transport: Previous | Reset the highlighted timer in the room if it is running. If not running, highlight the previous timer in the list. Optionally, start the previous timer once it’s highlighted. |
Transport: Start | Start or resume the highlighted timer in the room |
Transport: Start/stop | Start/stop the highlighted timer in the room |
Transport: Stop | Stop the highlighted timer in the room |
Transport: Subtract time | Subtract an amount of time from the highlighted timer in the room |
Utility: Get room | Get the status of the room |
Utility: Get status | Get the playback status of the room |
Utility: Test auth | Test connection and authentication |
Viewer: Disable blackout mode | Disable blackout mode in the room |
Viewer: Disable focus mode | Disable focus mode in the room |
Viewer: Enable blackout mode | Enable blackout mode in the room |
Viewer: Enable focus mode | Enable focus mode in the room |
Viewer: Flash the screen | Flashes the screen in the room. Can be used to grab the attention of speakers. |
Viewer: Stop flashing | Stops any flashing timers and messages on the screen. |
Viewer: Toggle blackout mode | Toggle (enable/disable) blackout mode in the room |
Viewer: Toggle focus mode | Toggle (enable/disable) focus mode in the room |
Variables
Variable | Description |
---|---|
$(stagetimer:currentTimerDuration) | Timer duration |
$(stagetimer:currentTimerDurationAsMs) | Timer duration (ms) |
$(stagetimer:currentTimerId) | Timer ID |
$(stagetimer:currentTimerName) | Timer name |
$(stagetimer:currentTimerNotes) | Timer notes |
$(stagetimer:currentTimerRemaining) | Timer remaining time |
$(stagetimer:currentTimerRemainingAsMs) | Timer remaining time (ms) |
$(stagetimer:currentTimerSpeaker) | Timer speaker |
$(stagetimer:roomId) | Room ID |
$(stagetimer:roomName) | Room name |
Feedbacks
- Blackout mode
- Flashing
- Focus mode
- Message showing
- Playback running
- Playback stopped
- Timer is over time
- Timer is running and on time
- Timer is showing red wrap-up warning
- Timer is showing yellow wrap-up warning
Using the Companion Module with the Offline Version
You’re not limited to using the Stagetimer Companion module with the web version of Stagetimer. The module also works seamlessly with the offline version of Stagetimer.
The offline version is available here: https://stagetimer.io/offline-version/
Note: You need a paid Stagetimer account to use the API with the offline version. All paid plans include an offline license key.

Follow the steps below to set it up:
-
Start by launching the Stagetimer offline version. Ensure it’s running on an IP address that is accessible from the Companion app. If both applications are on the same computer,
127.0.0.1
should work perfectly. If they’re on separate systems, you might need to run it on your wireless or wired network IP. -
Next, navigate to the room and click on “Menu” → “API”. This will display the room ID, API Key, and API URL. These are the details you’ll need for the Companion module configuration.
API details found under “Menu” -> “API” in the offline version -
Finally, copy these details and paste them into the Companion module configuration. In the Companion app, this configuration section is also referred to as “Connections”. If the status turns green after clicking “Save”, that means you’re all set!
Update Companion module configuration
Congratulations, you’re now ready to control your Stagetimer offline version using the Companion module!
Leverage Unavailable Module Functions with the Stagetimer API
Accessing the full spectrum of Stagetimer API commands through Companion is a breeze.
The Stagetimer API documentation lists all accessible commands. Many are readily available as actions or presets in the Stagetimer module. However, a few might be missing, like the ”Create message” function.
Here’s a step-by-step guide to utilize such functions:
-
Create a Generic Button in Companion
Start by adding a regular button in Companion and attach the “Run shell path” action to it.
Adding a regular button in Companion -
Copy-Paste the
curl
Command from the Stagetimer API DocumentationNext, copy the
curl
command exactly as it appears from the Stagetimer API documentation and paste it into the “Path” field. Remember to replace placeholders with your Room ID and API Key in the command.Pasting the curl
command into the “Path” field in Companion -
Customize the Command As Per Your Need
As an example, if you want the button to send a new message, “Hello World”, each time it’s clicked, modify the command as follows:
curl "https://api.stagetimer.io/v1/create_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY&text=Hello+World"
Pro Tip: When you click the “API Documentation” button from the room’s API popup, then it will prefill all API commands with your room ID, API Key and it will use the correct API URL if you use the offline version.
And there you go! You’ve successfully expanded your Stagetimer module functions within Companion.