Bitfocus Companion + Tevyr

#What you can do

Companion turns Tevyr into a button-press operation:

#Prerequisites

• Tevyr Premium or Enterprise plan — the API is gated to these tiers
• A Tevyr API key for the room you want to control (see API setup)
• 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 — including no hardware at all, since Companion's web UI works as a soft button surface too

#One-time setup

#1. Add a Generic HTTP connection

Tevyr is reachable through Companion's built-in Generic HTTP module — no Tevyr-specific plugin required.

1. Open the Companion web UI (default: http://localhost:8000 on the machine running Companion)
2. Click Connections → Add connection
3. Search for Generic HTTP and click Add
4. In the connection's settings:
   • Label: Tevyr
   • Base URL: https://api.tevyr.com/v1
   • Leave authentication blank (we'll pass the API key per-button as a query parameter)
5. Click Save

#2. Map your first button

1. Click Buttons in the top nav
2. Pick a page (e.g., page 1) and click an empty button slot
3. In the button editor, scroll to Press actions → Add action
4. Choose Tevyr → Generic: Make GET request
5. In the URL field, paste a recipe from below (replacing YOUR_ROOM_ID and YOUR_API_KEY)
6. Set the button label and color in the Style panel
7. Click Apply

Press the Stream Deck button → the URL fires → Tevyr responds. That's the whole loop.

#Recipes

Replace YOUR_ROOM_ID and YOUR_API_KEY in every URL with your actual values from your Tevyr API panel.

#Recipe 1 — Play/Pause toggle

The most common button. Fires once to pause, fires again to resume — Tevyr toggles state internally.

https://api.tevyr.com/v1/timer/start_stop?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY

Style: Big play/pause icon, green when running, amber when paused. Use Companion's variable system to read the timer state and update the button color live.

#Recipe 2 — Next / Previous session

Two buttons, side by side. The bread-and-butter of running a multi-session event.

https://api.tevyr.com/v1/timer/next?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY

https://api.tevyr.com/v1/timer/prev?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY

Style: Right-arrow and left-arrow icons. Green for next, neutral for previous (encourages forward motion).

#Recipe 3 — Add / subtract 30 seconds

Catch-up buttons. The speaker is running long? Tap +30 a couple times. Running short? Tap -30.

https://api.tevyr.com/v1/timer/add_time?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY&seconds=30

https://api.tevyr.com/v1/timer/subtract_time?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY&seconds=30

Style: "+30" and "-30" labels in big mono text. Position them as a pair next to play/pause.

#Recipe 4 — Pre-saved flash messages

Dedicate four buttons to your most common messages. The text flashes full-screen on every speaker output.

https://api.tevyr.com/v1/message/flash?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY&content=5+minutes&color=amber

https://api.tevyr.com/v1/message/flash?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY&content=Wrap+up&color=red

https://api.tevyr.com/v1/message/flash?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY&content=Q%26A+open&color=green

https://api.tevyr.com/v1/message/flash?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY&content=Tech+break&color=white

Style: Color-match each button to its message color so the operator builds muscle memory. URL-encode special characters: + for space, %26 for &, %20 is also fine for space.

#Recipe 5 — Panic blackout button

The "oh no" button. One big red Stream Deck key that hides every Tevyr screen instantly.

https://api.tevyr.com/v1/display/enable_blackout?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY

To clear (put on a different button or hold-to-clear):

https://api.tevyr.com/v1/display/disable_blackout?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY

Style: Solid red background, bold "BLACKOUT" label. Place it in a corner so it's never accidentally pressed during normal show flow.

#Recipe 6 — On-air toggle

A single button bound to two cues — first press turns the on-air light on, second press turns it off. Use Companion's step feature for this.

# Step 1 (press 1):
https://api.tevyr.com/v1/display/enable_on_air?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY

# Step 2 (press 2):
https://api.tevyr.com/v1/display/disable_on_air?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY

Style: Red dot icon when active, grey when inactive. Use Companion's button feedback to update the visual state automatically.

#MIDI input → Tevyr cueing

Companion's killer feature for theater and live music: it speaks MIDI natively. Wire a MIDI keyboard or MIDI Show Control desk into Companion, and Companion fires Tevyr API calls in response — effectively turning Tevyr into a MIDI-controllable device.

#Setup

1. In Companion, Connections → Add connection → MIDI
2. Pick your MIDI input device from the dropdown (Companion auto-detects USB MIDI gear and IAC virtual ports)
3. Triggers → Add trigger
4. Set the trigger condition: MIDI Note On, channel 1, note C4 (or whatever note your controller sends)
5. Set the action: Tevyr → Generic: Make GET request, URL = https://api.tevyr.com/v1/timer/next?...

Now pressing that MIDI key advances Tevyr. Map a row of 8 keys to your 8 most common cues for a tactile cue pad.

#MIDI Show Control bridge

For a full theatrical MSC rig where the lighting console is the master and Tevyr is a slave, configure Companion to listen for MSC commands and translate them into Tevyr API calls:

• MSC GO on cue 47 → fire /v1/timer/next
• MSC STOP → fire /v1/timer/stop
• MSC RESUME → fire /v1/timer/start_stop
• MSC PANIC → fire /v1/display/enable_blackout

This pattern means Tevyr behaves like any other MIDI-controllable device on a theatrical control bus — operators don't need to know it's HTTP under the hood.

#Live button feedback (advanced)

Companion can read API responses and update button visuals based on Tevyr state. Useful for play/pause buttons that show running vs paused colors automatically.

1. Connections → Generic HTTP → Variables — set up a polling URL pointing at /v1/event/playback_status
2. Buttons → your play/pause button → Feedbacks → Add feedback
3. Set conditions: when JSON response field status equals running, set button background green; when paused, set amber

The polling adds a small amount of network traffic (~once per second) but keeps the operator's tactile world in sync with the timer state.

#Troubleshooting

#"Button doesn't fire anything"

• Check the URL works in a browser first. Paste it into Chrome — if you get a JSON response, the URL is correct. If you get a 401/403, your API key is wrong.
• Companion runs on its own machine. Make sure that machine has internet access to https://api.tevyr.com.
• Check Companion's log panel — the Connections view shows recent calls and their HTTP status codes.

#"MIDI controller doesn't trigger anything"

• Open Companion's MIDI input log (in the connection's debug view) — confirm the MIDI message is actually arriving. If it's not, the issue is upstream (cable, port selection, or MIDI device itself).
• If MIDI arrives but the trigger doesn't fire, check the trigger's note number and channel match exactly.

#"API calls are 1-2 seconds late"

• Network latency on venue Wi-Fi. The fix is the same as for any networked control: build a small lead time into your cue sheet, or wire your control machine via Ethernet instead of Wi-Fi.

#"I want to control multiple Tevyr events from one Companion install"

Add a second Generic HTTP connection with a different label and a different api_key baked into its base URL. Each set of buttons targets a different event — useful for venues running two halls in parallel.

#Fire a saved macro from a Stream Deck button

The cleanest pattern for "one button → many actions" — build a macro in Tevyr (blackout + green light + start recording + Slack ping), then bind its UUID to a Stream Deck button.

1. In Tevyr — open the Macros panel, build your sequence, and copy the macro ID from the URL bar (or from GET /v1/macros/list).
2. In Companion — add a Generic HTTP action on a button with this URL:

   https://api.tevyr.com/v1/macros/run?room_id=YOUR_PASSCODE&macro_id=YOUR_MACRO_ID&api_key=YOUR_KEY
   

   Copy
3. The macro fires asynchronously on the server — Companion gets a 202 Accepted immediately. Step-by-step progress shows up in the Tevyr controller's playback toast.

skip_if_running defaults to true so a bumped button won't fire two concurrent runs. Pass &skip_if_running=false if you want overlapping runs (rare).

To discover all macros for a room (to label your buttons), hit GET /v1/macros/list?room_id=…&api_key=… once and paste the names into your button labels.

#Related

• API reference — every endpoint Companion can hit
• Macros — build the multi-step cues Stream Deck buttons fire
• QLab guide — for theater shows running QLab as the master cue list (Companion can act as a backup or co-controller)
• Webhooks — go the other direction: Tevyr fires events into Companion (e.g., timer hit warning → Stream Deck button flashes red)
• Use case: Livestreams — how Stream Deck operators run multi-output Tevyr events