Bitfocus Companion + Tevyr

#What you get with the Tevyr module

The Tevyr module wraps Tevyr's public API as native Companion actions, presets, variables, and feedbacks — so buttons light up with live state and you never touch a URL.

#Prerequisites

• Tevyr Premium or Enterprise plan — the API the module uses is gated to these tiers
• A Tevyr API key and the room passcode for the room you want to control (Tevyr dashboard → Settings → API)
• Bitfocus Companion 3.0 or later — running on the venue's control machine, a Raspberry Pi, or any always-on computer
• A Stream Deck (any size), a Loupedeck, or any hardware Companion supports — or no hardware at all, since Companion's built-in Emulator works as an on-screen button surface

#Step-by-step setup

#Step 1 — Install Companion

Download Bitfocus Companion from bitfocus.io/companion (pick the Companion desktop app — not "Buttons", "Pi", or "Satellite"). Install it, launch it, and click Launch GUI — that opens the control panel in your browser at http://localhost:8000. Everything below happens in that browser window.

#Step 2 — Get your Tevyr API key + room passcode

In the Tevyr dashboard, open Settings → API and copy two things:

• API key — a long token that authorizes API access for the room
• Room passcode (room_id) — the short code that identifies the room (e.g. 117299)

Keep both handy for Step 4. (See the API setup guide for details.)

#Step 3 — Add the Tevyr module

There are two ways to get the module into Companion. Try the store first; if it's not there yet, use the manual import.

#Option A — From the Bitfocus module store (recommended)

1. In Companion, click Connections → Add connection.
2. Search for Tevyr.
3. Click it → Add.

If Tevyr appears in the search, you're done — skip to Step 4.

#Option B — Manual import (the .tgz package)

1. Download the module package — grab the latest tevyr-x.y.z.tgz from the Tevyr module releases on GitHub.
2. In Companion, go to Settings → Modules (or the Modules tab) → click Import module package.
3. Select the .tgz file you downloaded. Companion installs it and shows Tevyr in your modules list.
4. Now go to Connections → Add connection → search Tevyr → Add.

That's it — the manually-imported module behaves identically to the store version. (The only difference: store modules auto-update; a manually-imported one you'd re-import to update.)

#Step 4 — Configure the connection (your API key)

After adding the connection, Companion opens its config form. Fill in:

Click Save. The connection's status dot turns green / OK once it authenticates. If it's red, hover it for the reason:

• Bad config — the API key or room passcode is empty.
• Authentication failure — the key is invalid/expired, the passcode doesn't match the key, or your plan doesn't include API access (needs Premium/Enterprise).
• Connection failure — the machine running Companion can't reach api.tevyr.com; check its internet.

#Step 5 — Add buttons from the presets

This is the fast part — you don't build buttons by hand.

1. Click Buttons in the top navigation (the main button grid).
2. Open the Presets panel and pick Tevyr — you'll see the categories: Timer, Display, Messages, Ad-hoc, Macros, Viewer.
3. Drag a preset (e.g. Play/Pause, Next, +30s, Blackout, Run Macro #1) onto any empty button in the grid. It arrives fully wired — action + live colors included.

About the #1 / #2 / #3 presets (messages, ad-hoc timers, macros): they target an item by its position in your room's list. Drag the one you want; to point at a different item, open the button's action and pick it from the dropdown or type another number.

#Step 6 — Test it

You don't need physical hardware to test:

1. Go to Surfaces → Add Emulator (if you don't already have one), then open the Emulator (or http://localhost:8000/emulator/). It's an on-screen Stream Deck.
2. Make sure your Tevyr room has a session loaded.
3. Click the Play/Pause button in the Emulator → your Tevyr timer starts/pauses in real time.

On a real Stream Deck, the same buttons appear automatically — just press them.

#Useful variables for button text

Put any of these on a button's text as $(tevyr:variable) for live-updating displays:

#MIDI input → Tevyr cueing

Companion speaks MIDI natively, so a MIDI keyboard or MIDI Show Control desk can drive Tevyr through the module:

1. Connections → Add connection → MIDI, and pick your MIDI input device.
2. Triggers → Add trigger.
3. Condition: MIDI Note On, your channel + note (e.g. C4).
4. Action: a Tevyr action — e.g. Timer: Next session or Timer: Toggle play/pause.

Map a row of keys to your common cues for a tactile cue pad. For a full theatrical rig, listen for MSC commands and map them to Tevyr actions (MSC GO → Next, MSC STOP → Stop, MSC PANIC → Panic blackout) — Tevyr behaves like any other device on the control bus.

#Lighting, audio & DMX consoles

Lighting desks, audio consoles, and DMX fixtures don't talk to Tevyr directly — but Companion bridges them. Run the Tevyr module for show control, and add the relevant device module in the same Companion install; a Companion trigger (or a Tevyr webhook / macro flow.http_request step) fires the device module in sync with your timer.

Each module is added inside Companion (Connections → Add connection → pick the module), exactly like the Tevyr connection. Check each module's own docs for the actions it exposes.

#Run a Tevyr macro from a button

Build a macro in Tevyr (e.g. blackout + green light + start recording + Slack ping), then fire it from a Stream Deck key:

1. Drag the Macros → Run Macro #1 preset onto a button (it targets the first macro in your room), or add the Macros: Run action and pick your macro from the dropdown.
2. Press it — the macro runs asynchronously on the server; progress shows in the Tevyr controller's playback toast.

Skip if already running is on by default, so a double-tap won't start two concurrent runs.

#Troubleshooting

#Connection shows red / "Authentication failure"

Double-check the API key and room passcode match (they're a pair, from Settings → API), and that the room is on a Premium/Enterprise plan. A Free-tier key returns a plan-required error.

#A button does nothing

Open Companion's Log tab and press the button again — failed actions print a clear warning line (e.g. NO_ACTIVE_SESSION if there's no session loaded, or RATE_LIMITED). If you see NO_ACTIVE_SESSION, load/select a session in the room first.

#Tevyr isn't in the "Add connection" search

The module is still in Bitfocus's review queue — install it manually with the .tgz (see Step 3, Option B). Once approved, it appears in the store automatically.

#Button colors / variables aren't updating

Make sure Poll for live state is On in the connection config. Polling (~1 request/second) is what keeps feedbacks and variables live; the module automatically backs off if it ever hits the rate limit.

#Controlling multiple Tevyr rooms from one Companion

Add a second Tevyr connection with that room's own API key + passcode. Each set of buttons targets its own room — handy for venues running two halls in parallel.

#Related

• API reference — every endpoint, for custom actions beyond the presets
• Macros — build the multi-step cues a single button fires
• QLab guide — for theater shows running QLab as the master cue list
• Webhooks — the other direction: Tevyr fires events into Companion
• Use case: Livestreams — how Stream Deck operators run multi-output Tevyr events