Control SermonWave from a Stream Deck or Companion Beta

SermonWave has a simple web API so you can start and stop translation, and switch languages, with one button press on a Stream Deck or in Bitfocus Companion. This article shows how to set it up.

Who it's for#

• Production teams who run lights, slides and cameras from an Elgato Stream Deck.
• Booths that use Bitfocus Companion to drive many devices from one control surface.
• Anyone who wants a "Start translation" button without opening the Dashboard.

It works with every kind of SermonWave device: the SW1 box, a Web device (browser) and the OBS plugin.

Before you start#

• You must be an Org Admin. Only organization admins see the control settings. See Users and roles.
• The device you want to control, already set up. See Choose a device type.
• An active trial or plan. Like the Dashboard Start button, a start from a button is refused when your trial or subscription has ended. Stop still works. See Plans and trial.
• Internet access on the computer that runs the Stream Deck app or Companion.

Step 1 — Create a control token#

A control token is a secret key that lets a button control one device. A token for your sanctuary device cannot control your youth room device.

1. In the Dashboard, go to Devices and open the device.
2. Open the Settings tab and find the Stream Deck / API control card.
3. Enter a name you will recognize later, such as "Booth Stream Deck", and click Create token.
4. Copy the token right away. It starts with swc_ and is shown only once. The card also lists ready-made addresses for each action.

Zrzut ekranu wkrótce

Token management:

• Up to 10 tokens per device. Create one per control surface so you can revoke one without breaking the others.
• The card shows each token's Name, Created and Last used dates.
• Click Revoke to stop a token. Buttons that use it stop working at once.

Allow in URL. By default the token must be sent in a request header. Turn on Allow in URL only for tools that can't send headers, such as a plain "Open website" button. The token is then added to the address as ?token=swc_....

Step 2 — Know the addresses#

Every address starts with this base, where <device_id> is your device's number:

https://dashboard.sermonwave.com/api/hub/control/<device_id>

Details:

• Send the token in a header: Authorization: Bearer swc_...
• Use POST when your tool allows it. Actions also accept GET, for tools that can only open an address.
• Use language codes your device already offers, such as es (Spanish) or fr (French). You can't remove the last language.
• Language changes are saved like changes in the Settings tab. If the device is offline, they are saved and applied when it reconnects.
• Add ?format=text to get one word back, such as recording, instead of JSON.

Step 3 — Set up an Elgato Stream Deck#

1. In the Stream Deck app, open the Marketplace and install the free Web Requests or API Ninja plugin.
2. Drag the plugin's HTTP Request action onto a key.
3. Set Method to POST and URL to an action address, for example .../toggle.
4. Add the header. In Web Requests, type Authorization: Bearer swc_... in Headers. In API Ninja, use {"Authorization":"Bearer swc_..."}.
5. Press the key during a rehearsal. It shows a check mark when SermonWave accepted the command, and an alert on an error. Confirm in Live monitoring.

Make one key per action, for example Start, Stop or "Toggle Spanish" (.../language/toggle/es). A Stream Deck Multi Action can chain them.

Zrzut ekranu wkrótce

Step 4 — Set up Bitfocus Companion#

1. Add the Generic: HTTP Requests connection.
2. On a button, add a POST action. Use your .../toggle (or /start, /stop, /language/toggle/es) address.
3. In the header field, enter {"Authorization":"Bearer swc_..."}.
4. Optional: add button feedback (below).

Step 5 — Button feedback with status#

The /status address returns state (recording, armed, idle or offline), whether the device is live, the listener count and the current languages.

• Companion: poll .../status every 2 to 5 seconds with a GET action on a trigger. Save $.state into a custom variable, then color the button: red for recording, amber for armed, grey for offline.
• Stream Deck: if your plugin can poll an address and show the reply on the key, poll .../status?format=text every 2 seconds or more. Otherwise the check mark or alert on each press is your feedback.
• You don't need to poll right after a press. The reply to an action already includes the new state.

Rate limits. Each token can send about 30 actions and 300 status checks per minute. Polling every 2 seconds uses about 30. A device runs one command at a time, so a double-press can't make it flip back and forth. Too many wrong tokens from one network are blocked for a while.

Examples with curl#

T=swc_your_token_here
BASE=https://dashboard.sermonwave.com/api/hub/control/<device_id>
curl -X POST -H "Authorization: Bearer $T" $BASE/start
curl -X POST -H "Authorization: Bearer $T" $BASE/language/toggle/fr
curl -X POST -H "Authorization: Bearer $T" $BASE/language/set/es,fr
curl -H "Authorization: Bearer $T" "$BASE/status?format=text"
curl -X POST -H "Authorization: Bearer $T" $BASE/stop

Local control in OBS#

The OBS plugin has controls of its own, so a Stream Deck or Companion can talk only to OBS on your network, with no internet needed. They appear under OBS Settings → Hotkeys, and the plugin also answers obs-websocket vendor requests (vendor sermonwave). For the full list and how to use them, see OBS hotkeys and automation.

Troubleshooting#

These are the replies you can get. Wording may change.

FAQ#

I don't see the Stream Deck / API control card.#

Only organization admins see it, and it can be switched off for an account. If you are an admin and it is missing, ask support to turn it on.

Will one token control all of my devices?#

No. Each token controls exactly one device. Create a token on each device you want to control.

Can volunteers who are not admins create tokens?#

No. Only organization admins can create or revoke control tokens.

Does it work with tools other than Stream Deck and Companion?#

Yes. Any tool that can send a web request works, such as a home automation hub or a script.