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

1. The first step is to acquire an Elgato Stream Deck, a budget-friendly keypad equipped with programmable LCD buttons. You can purchase it here.

   

2. Download and launch the Companion app.

3. In the GUI, add the “stagetimer.io: Stagetimer API” connection.

   

4. The Companion module can control one Stagetimer room. Open the desired room to get its Room ID and API key.

   

   

5. 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.

   

   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).

6. 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!

   

   

7. 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:

1. 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.

2. 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.

   

3. 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!

   

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:

1. Create a Generic Button in Companion

   Start by adding a regular button in Companion and attach the “Run shell path” action to it.

   

2. Copy-Paste the curl Command from the Stagetimer API Documentation

   Next, 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.

   

3. 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.