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

What are Companion and Streamdeck

This short how-to video shows you how to use Stagetimer and its API with Bitfocus Companion and the Elgato Streamdeck.

Streamdeck is a reasonably priced customizable button surface. Companion enables the use of Streamdeck with professional video production hardware and software.

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.

Using Stagetimer with Streamdeck and Companion
Using Stagetimer 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.

Generate an API key for the room
Generate an API key for the room

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.

See the complete documentation on https://stagetimer.io/docs/api/
See the complete documentation on https://stagetimer.io/docs/api/

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.

Creating a start button with Companion
Creating a start button with Companion

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.

Creating a stop button with Companion
Creating a stop button with Companion

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.

Creating a toggle button to change the background to black
Creating a toggle button to change the background to black

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.

Changing colors for visual feedback
Changing colors for visual feedback

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.

Creating a button to add 5 minutes
Creating a button to add 5 minutes

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.

Creating a button to subtract 5 minutes
Creating a button to subtract 5 minutes

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.

Working with multiple timers and messages
Working with multiple 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.

See the complete documentation on https://stagetimer.io/docs/api/
See the complete documentation on https://stagetimer.io/docs/api/

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.

Change the index number to target an individual message or timer
Change the index number to target an individual message or timer
Change the index once you paste the code to the path field
Change the index once you paste the code to the path field

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.

Easily check index number for timers
Easily check index number for timers

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.