Control SermonWave from a Stream Deck or Companion Próximamente

SermonWave is adding 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 describes the planned setup so you can get ready.

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 is planned to work 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 will 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 (planned)#

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.

Captura de pantalla próximamente

Planned 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 planned addresses#

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

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

Planned 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 (planned)#

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.

Captura de pantalla próximamente

Step 4 — Set up Bitfocus Companion (planned)#

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 (planned)#

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 (planned). 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 (planned)#

The OBS plugin is planned to add more controls of its own, so a Stream Deck or Companion can talk only to OBS on your network. These hotkeys are planned to appear under OBS Settings → Hotkeys:

• SermonWave: Start translation, SermonWave: Stop translation and SermonWave: Start / stop translation (toggle)
• SermonWave: Toggle language (one per language, for example Español)
• SermonWave: Start translated stream / Stop translated stream, and Start translated recording / Stop translated recording, per language

Trigger them from the Stream Deck OBS plugin or Companion's OBS module. For advanced setups, the plugin is also planned to answer obs-websocket vendor requests (vendor sermonwave) such as Start, Stop, Toggle and ToggleLanguage, and to send status events for button feedback. For what works today, see OBS hotkeys and automation.

Troubleshooting#

These are the planned replies. Wording may change.

FAQ#

When will this be available?#

It is in development. There is no release date yet. This article will be updated when it ships.

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. It is planned that only organization admins can create or revoke control tokens.

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

It is planned to work with any tool that can send a web request, such as a home automation hub or a script.