Controlling Stagetimer via Companion for Stream Deck - Complete Guide

Companion drives a Stream Deck and controls Stagetimer through the Stagetimer module. The API needs a Pro or Premium plan.

Prefer a video?

Matthew Hand describes how to use Stagetimer with Bitfocus Companion (26 min)

Getting Started

1. Get an Elgato Stream Deck, a keypad with programmable LCD buttons.

   

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. Enter the Room ID and API key into the Stagetimer connection in Companion. Click Save. The status turns into a green checkmark.

   

   Note: The Companion module can also be used with the Stagetimer desktop app. In this scenario, you need to adjust the API URL to connect with your desktop app (explained later).

6. Switch to the “Buttons” tab in Companion, open “Presets” → “Stagetimer API” → “Transport”, and drag the “Start/Stop” button onto a Stream Deck field.

   

   

Using the Companion Module with the Desktop App

The module also works with the desktop app. The API needs a paid plan; every paid plan includes an offline license key.

1. Run the desktop app on an IP address Companion can reach: 127.0.0.1 on the same computer, your network IP on another.

2. Open the room and click Menu → API to get the room ID, API key and API URL.

   

3. Paste them into the Stagetimer connection in Companion and click Save. The status turns green.

   

Control Multiple Rooms in Companion

Switching rooms dynamically

The Utility: Switch room action changes the active room of a connection, so one button layout serves every room.

Requirements:

• A team API key, which has access to all rooms in your team.

Add the Utility: Switch room action to a button and enter the Room ID of the target room. The Room ID field takes variables. The module reconnects to the new room and every variable and feedback updates.

You can check which room is currently active using the $(stagetimer:roomId) variable.

Using multiple connections

To control several rooms at once, set up one connection per room:

1. In the Connections tab, locate your existing Stagetimer connection.

2. Change the label of your first Stagetimer connection to something distinctive (e.g., stagetimer-1). This helps differentiate between multiple rooms.

   

3. Click the “Add connection” button and search for “stagetimer” to add another Stagetimer API module.

4. Configure the second connection with:

   • A unique label (e.g., stagetimer-2)
   • The Room ID for your second room
   • The corresponding API key

   

5. Once both connections are set up, you can add buttons for either room to your Stream Deck. The presets section will now show options for both connections.

   

6. When setting up button text, you can use variables specific to each connection by referencing the connection label:

   • For room 1: $(stagetimer-1:currentTimerName)
   • For room 2: $(stagetimer-2:currentTimerName)

   

Reference

The Stagetimer module provides presets, actions, variables and feedbacks. The preset buttons show how to combine them in your own buttons.

Presets

Transport presets

Button	Name	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.
	Reset	Reset the selected timer to its original duration.
	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.
	Jump back 10s	Jump the playhead of the current timer 10 seconds back. The duration does not change. It cannot jump back past the start of the timer. If it would, the timer does not move.
	Jump forward 10s	Jump the playhead of the current timer 10 seconds forward. The duration does not change.
	+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

Button	Name	Description
	Time remaining	Shows a live countdown of the full current timer including wrap-up colors.
	Time remaining (hours)	Shows only the hours of the current timer including wrap-up colors.
	Time remaining (minutes)	Shows only the minutes of the current timer including wrap-up colors.
	Time remaining (seconds)	Shows only the seconds of the current timer including wrap-up colors.
	Wrap-up indicator	Indicates the current wrap-up state: “On time”, “Wrap up..”, “Wrap up!”, or “Over time!”
	Timer appearance	Defines how the timer is displayed. Read more: Timer Appearances
	Current timer	Shows the title of the current timer.
	Current speaker	Shows the speaker of the current timer.
	Current timer labels	Shows the labels of the current timer.
	Next timer labels	Shows the labels of the next timer.
	Timezone	Shows the timezone setting of the room.
	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 ON AIR	Toggles ON AIR mode on or off.

Timer presets

Button	Name	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.
	Create timer	Create a new timer. Options to configure the timer before it is created.

Message presets

Button	Name	Description
	Toggle message	Toggle a message. Option to target any message indicated by index (starting from 1) or message ID.
	Show message	Show a message. Option to target any message indicated by index (starting from 1) or message ID.
	Hide message	Hide a message. Option to target any message indicated by index (starting from 1) or message ID. Otherwise hides the active message.
	Create message	Create a new message. Options to configure the message before it is created.

Actions

Targeting a specific timer or message

The Timer: * and Message: * actions target either an index (position in the list, starting at 1) or an ID. Use one or the other, not both — if both fields are filled, the ID wins. Leave the index blank when targeting by ID.

Both fields accept variables, so you can act on whatever is currently on screen. For example, set Timer ID to $(stagetimer:currentTimerId) and clear the Timer index to reset the currently selected timer. To do the same without any variables, use Transport: Reset, which always applies to the selected timer.

Variables

Room

Variable	Description
$(stagetimer:roomId)	Room ID
$(stagetimer:roomName)	Room name
$(stagetimer:roomTimezone)	Room timezone (Docs)

Playback Snapshot

The time display matches the Stagetimer output, taking timer appearance into account. The remaining time variables are always strictly a countdown.

Variable	Description
$(stagetimer:timeDisplay)	Time display
$(stagetimer:timeDisplayHours)	Time display (hours)
$(stagetimer:timeDisplayMinutes)	Time display (minutes)
$(stagetimer:timeDisplaySeconds)	Time display (seconds)
$(stagetimer:currentTimerRemaining)	Timer remaining time
$(stagetimer:currentTimerRemainingAsMs)	Timer remaining time (ms)
$(stagetimer:currentTimerRemainingHours)	Timer remaining time (hours)
$(stagetimer:currentTimerRemainingMinutes)	Timer remaining time (minutes)
$(stagetimer:currentTimerRemainingSeconds)	Timer remaining time (seconds)

Current Timer

The timer currently selected in the room. These variables are empty while no timer is selected.

Variable	Description
$(stagetimer:currentTimerId)	Timer ID
$(stagetimer:currentTimerName)	Timer name
$(stagetimer:currentTimerSpeaker)	Timer speaker
$(stagetimer:currentTimerNotes)	Timer notes
$(stagetimer:currentTimerAppearance)	Timer appearance (Docs)
$(stagetimer:currentTimerStartTime12h)	Hard start time (12h format, Docs)
$(stagetimer:currentTimerStartTime24h)	Hard start time (24h format, Docs)
$(stagetimer:currentTimerDuration)	Timer duration
$(stagetimer:currentTimerDurationAsMs)	Timer duration (ms)
$(stagetimer:currentTimerLabels)	Timer labels (comma-separated)
$(stagetimer:currentTimerLabel1)	Timer label 1
$(stagetimer:currentTimerLabel2)	Timer label 2
$(stagetimer:currentTimerLabel3)	Timer label 3

Next Timer

The timer that follows the current one. These variables are empty when the last timer is selected, so $(stagetimer:nextTimerId) can be used to detect the end of the rundown.

Variable	Description
$(stagetimer:nextTimerId)	Timer ID
$(stagetimer:nextTimerName)	Timer name
$(stagetimer:nextTimerSpeaker)	Timer speaker
$(stagetimer:nextTimerNotes)	Timer notes
$(stagetimer:nextTimerAppearance)	Timer appearance (Docs)
$(stagetimer:nextTimerStartTime12h)	Hard start time (12h format, Docs)
$(stagetimer:nextTimerStartTime24h)	Hard start time (24h format, Docs)
$(stagetimer:nextTimerDuration)	Timer duration
$(stagetimer:nextTimerDurationAsMs)	Timer duration (ms)
$(stagetimer:nextTimerLabels)	Timer labels (comma-separated)
$(stagetimer:nextTimerLabel1)	Timer label 1
$(stagetimer:nextTimerLabel2)	Timer label 2
$(stagetimer:nextTimerLabel3)	Timer label 3

Current Message

These variables describe the message currently showing on the viewer. They are empty while no message is showing.

Variable	Description
$(stagetimer:currentMessageId)	Message ID
$(stagetimer:currentMessageText)	Message text
$(stagetimer:currentMessageColor)	Message color

Feedbacks

• Blackout mode
• Connected
• Flashing
• Focus mode
• ON AIR 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

Use the Stagetimer API directly

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 “Delete message” function.

Here’s a step-by-step guide to use such functions:

1. Create a Generic Button in Companion

   Add 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

   Copy the curl command from the API documentation into the “Path” field and replace the placeholders with your Room ID and API key. The API Documentation button in the room’s API popup prefills every command with your room ID, API key and API URL.

   

3. Customize the Command As Per Your Need

   Example: this command deletes the top message in the room on every press.

   curl "https://api.stagetimer.io/v1/delete_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY&index=1"