Integrate Stagetimer with Companion for Streamdeck (Step-by-Step Guide)

What are Companion and Streamdeck

What is Stagetimer

stagetimer.io is a cloud-based event timer that runs in the browser and can be shared via link or QR code. It can be used on any operating system and an up-to-date browser. The API allows you to control timers and messages with Streamdeck and Companion.

1. Get the API key and Room ID from Stagetimer

The API lets you perform many actions: start and stop a timer, reset it back, add and remove time from a running timer, blackout the screen, show a message and a few more.

To get started, go to the controller page of Stagetimer and click on the API button at the top of the page. You will get an API popup that shows your room ID, which is the same as in your browser’s address bar, as well as an API key. To generate an API key you need a Pro subscription or Event license. See prices here.

With the Room ID and API key, you can then address the API. See how it works and find the pre-filled code snippets on the documentation page, and simply copy and paste them over.

2. Creating a start and stop button in Companion

The first thing we want to do is create a start and stop button. Several options are available in this API pre-filled snippets. Most of them are differentiated by only a small change in the last word on the snippet. For example, there is a start, a stop, and a toggle command, which means switching between start and stop.

To create a start and stop button simply copy the code snippet and then move over to the Companion administration page. Add a regular button and define a name in the “Button text” field. In the “Press actions” section, add a command called Run shell path. Run shell path allows you to paste the command into the “Path” field, and the button is ready to use.

You can add the stop button following the same steps. Go back to the documentation page and copy the stop command. Add another regular button, call it stop and go to the Run shell path command under press actions. Paste the console command, then the button appears on the Streamdeck. With that, you can start the timer and then stop it again.

3. Creating a blackout button with toggle state in Companion

Another option is to create a button with a toggle state. Take the blackout command, for example, which will switch the screen to black and when you press it again, it will switch it back to the timer. To do that, simply copy the command on the documentation page and add a new button. Choose a name for the button, such as “black”, for example. For this button, you have to activate the “Latch/Toggle” option. Under the “Latch actions”, again, choose the Run shell path and paste the command from the documentation page. Under the “Unlatch actions” section, do the same thing. Select the Run shell path option and paste the same command.

To add a visual highlight, you can make the background of the button itself change, which will give you optical feedback. With this, once you push the button, the background of the button will change color and you will be able to see that the command is activated. And when you click the button again, the background will change back to the chosen color. To do this, click on the field “Add key down/on action”, under “Latch Actions”, and select “Button Background Color”. You will then be able to pick a color. Do the same under “Unlatched Actions” and pick another color. You will now have a visual cue that the feature is activated or deactivated.

4. Creating a button to add/subtract from a timer in Companion

To add or subtract time from a running timer, simply create a tweak command. To do that, copy the snippet on the documentation page and you will be able to adjust the time added or subtracted as you wish. Go to the Companion page, add a new button and give it a name. Under “Press action”, select Run shell path and past the code you have copied. At the very end of the code, you can change the +10m to whatever value you choose.

You can then simply copy the button and change the end of the command to -5m. This creates a variation of the button which will subtract 5 minutes from the timer. It allows you to add and subtract minutes from the running timer by just clicking one button.

5. Target individual timers in Companion

When working with multiple timers you may need to target individual elements. To do so, go to the individual message endpoints section of the documentation page where you will find a list of snippets to target specific timers and messages.

If you want to have a specific message, such as a wrap-up message, or want to be able to just flash the message on the screen, you can do it directly from Streamdeck. Go to the individual message endpoint on the documentation page to check the snippets for individual timer and message endpoints.

👉 In a previous version the index was zero-based, meaning that the first element is a zero, the second is a one, the third is a two, and so on. This is no longer the case.

To toggle a message on and off, for example, you simply have to copy the toggle command from the documentation page on the section for individual endpoints. Then create a new button on the Companion website and give it a name, like “wrap up”. Select Run shell path under “Press actions” and add the command to the path.

It is important here to change the index. In the command field, you must change the 1 to the corresponding index. To target the third message on the controller page, use index 3. Once you paste the code into the path field, you can change the index number to match the message or timer you want to target.

The index number for timers and messages is easy to find. Just go to the controller page. The number is to the right of each element.

With the index number at hand, you can then copy the command you need from the documentation page and create a new button just as you have done with the steps mentioned above.

With these commands, you will be able to easily control timers and messages with Streamdeck and Companion.