Contrôler SermonWave depuis un Stream Deck ou Companion Bêta

SermonWave propose une API web simple pour démarrer et arrêter la traduction, et changer de langue, d'une simple pression sur un bouton de Stream Deck ou dans Bitfocus Companion. Cet article explique comment la configurer.

Pour qui#

• Aux équipes de régie qui pilotent lumières, diapositives et caméras depuis un Elgato Stream Deck.
• Aux régies qui utilisent Bitfocus Companion pour piloter de nombreux appareils depuis une seule surface de contrôle.
• À toute personne qui veut un bouton « Démarrer la traduction » sans ouvrir le tableau de bord.

Cela fonctionne avec tous les types d'appareils SermonWave : le boîtier SW1, un appareil web (navigateur) et le plugin OBS.

Avant de commencer#

• Vous devez être Admin de l'organisation. Seuls les administrateurs de l'organisation voient les paramètres de contrôle. Voir Utilisateurs et rôles.
• L'appareil que vous voulez contrôler, déjà configuré. Voir Choisir un type d'appareil.
• Un essai ou un forfait actif. Comme pour le bouton Démarrer du tableau de bord, un démarrage depuis un bouton est refusé lorsque votre essai ou votre abonnement a pris fin. Arrêter fonctionne toujours. Voir Forfaits et essai gratuit.
• Un accès à Internet sur l'ordinateur qui exécute l'application Stream Deck ou Companion.

Étape 1 — Créer un jeton de contrôle#

Un jeton de contrôle est une clé secrète qui permet à un bouton de contrôler un appareil. Un jeton pour l'appareil du sanctuaire ne peut pas contrôler celui de la salle des jeunes.

1. Dans le tableau de bord, allez dans Appareils et ouvrez l'appareil.
2. Ouvrez l'onglet Paramètres et repérez la carte Contrôle Stream Deck / API.
3. Saisissez un nom que vous reconnaîtrez plus tard, par exemple « Stream Deck de la régie », puis cliquez sur Créer un jeton.
4. Copiez le jeton immédiatement. Il commence par swc_ et n'est affiché qu'une seule fois. La carte liste aussi des adresses prêtes à l'emploi pour chaque action.

Capture d'écran bientôt disponible

Gestion des jetons :

• Jusqu'à 10 jetons par appareil. Créez-en un par surface de contrôle, pour pouvoir en révoquer un sans casser les autres.
• La carte affiche pour chaque jeton son Nom et ses dates Créé et Dernière utilisation.
• Cliquez sur Révoquer pour désactiver un jeton. Les boutons qui l'utilisent cessent aussitôt de fonctionner.

Autorisé dans l'URL. Par défaut, le jeton doit être envoyé dans un en-tête de requête. N'activez Autorisé dans l'URL que pour les outils qui ne peuvent pas envoyer d'en-têtes, comme un simple bouton « Ouvrir un site web ». Le jeton est alors ajouté à l'adresse sous la forme ?token=swc_....

Étape 2 — Connaître les adresses#

Chaque adresse commence par cette base, où <device_id> est le numéro de votre appareil :

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

Détails :

• Envoyez le jeton dans un en-tête : Authorization: Bearer swc_...
• Utilisez POST quand votre outil le permet. Les actions acceptent aussi GET, pour les outils qui ne savent qu'ouvrir une adresse.
• Utilisez des codes de langue que votre appareil propose déjà, comme es (espagnol) ou fr (français). Vous ne pouvez pas retirer la dernière langue.
• Les changements de langue sont enregistrés comme ceux faits dans l'onglet Paramètres. Si l'appareil est hors ligne, ils sont enregistrés et appliqués dès qu'il se reconnecte.
• Ajoutez ?format=text pour recevoir un seul mot, comme recording, au lieu de JSON.

Étape 3 — Configurer un Elgato Stream Deck#

1. Dans l'application Stream Deck, ouvrez le Marketplace et installez le plugin gratuit Web Requests ou API Ninja.
2. Faites glisser l'action HTTP Request du plugin sur une touche.
3. Réglez Method sur POST et URL sur l'adresse d'une action, par exemple .../toggle.
4. Ajoutez l'en-tête. Dans Web Requests, saisissez Authorization: Bearer swc_... dans Headers. Dans API Ninja, utilisez {"Authorization":"Bearer swc_..."}.
5. Appuyez sur la touche pendant une répétition. Elle affiche une coche lorsque SermonWave a accepté la commande, et une alerte en cas d'erreur. Vérifiez dans le suivi en direct.

Créez une touche par action, par exemple Démarrer, Arrêter ou « Basculer l'espagnol » (.../language/toggle/es). Une Multi Action du Stream Deck peut les enchaîner.

Capture d'écran bientôt disponible

Étape 4 — Configurer Bitfocus Companion#

1. Ajoutez la connexion Generic: HTTP Requests.
2. Sur un bouton, ajoutez une action POST. Utilisez votre adresse .../toggle (ou /start, /stop, /language/toggle/es).
3. Dans le champ d'en-tête, saisissez {"Authorization":"Bearer swc_..."}.
4. Facultatif : ajoutez un retour visuel sur le bouton (voir ci-dessous).

Étape 5 — Retour des boutons avec l'état#

L'adresse /status renvoie state (recording, armed, idle ou offline), indique si l'appareil est en direct, le nombre d'auditeurs et les langues actuelles.

• Companion : interrogez .../status toutes les 2 à 5 secondes avec une action GET sur un déclencheur. Enregistrez $.state dans une variable personnalisée, puis colorez le bouton : rouge pour recording, orange pour armed, gris pour offline.
• Stream Deck : si votre plugin peut interroger une adresse et afficher la réponse sur la touche, interrogez .../status?format=text toutes les 2 secondes ou plus. Sinon, la coche ou l'alerte à chaque pression vous sert de retour.
• Inutile d'interroger juste après une pression. La réponse à une action contient déjà le nouvel état.

Limites de fréquence. Chaque jeton peut envoyer environ 30 actions et 300 vérifications d'état par minute. Une interrogation toutes les 2 secondes en utilise environ 30. Un appareil exécute une seule commande à la fois, si bien qu'une double pression ne peut pas le faire basculer dans un sens puis dans l'autre. Trop de jetons erronés envoyés depuis un même réseau entraînent un blocage temporaire.

Exemples avec 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

Contrôle local dans OBS#

Le plugin OBS a ses propres commandes : un Stream Deck ou Companion peut ainsi communiquer uniquement avec OBS sur votre réseau, sans Internet. Elles apparaissent dans OBS sous Settings → Hotkeys (Paramètres → Raccourcis clavier si OBS est en français), et le plugin répond aussi aux requêtes « vendor » d'obs-websocket (vendor sermonwave). Pour la liste complète et la façon de les utiliser, voir Raccourcis clavier et automatisation dans OBS.

Dépannage#

Voici les réponses que vous pouvez recevoir. Leur formulation peut changer.

Questions fréquentes#

Je ne vois pas la carte Contrôle Stream Deck / API.#

Seuls les administrateurs de l'organisation la voient, et elle peut être désactivée pour un compte. Si vous êtes administrateur et qu'elle n'apparaît pas, demandez à l'assistance de l'activer.

Un seul jeton peut-il contrôler tous mes appareils ?#

Non. Chaque jeton contrôle exactement un appareil. Créez un jeton sur chaque appareil que vous voulez contrôler.

Les bénévoles qui ne sont pas administrateurs peuvent-ils créer des jetons ?#

Non. Seuls les administrateurs de l'organisation peuvent créer ou révoquer des jetons de contrôle.

Est-ce que cela fonctionne avec d'autres outils que Stream Deck et Companion ?#

Oui. Tout outil capable d'envoyer une requête web fonctionne, comme une box domotique ou un script.