Controla SermonWave desde un Stream Deck o Companion Beta

SermonWave tiene una API web sencilla para que puedas iniciar y detener la traducción, y cambiar de idioma, con solo presionar un botón en un Stream Deck o en Bitfocus Companion. Este artículo te muestra cómo configurarlo.

Para quién es#

• Equipos de producción que manejan luces, diapositivas y cámaras desde un Elgato Stream Deck.
• Cabinas que usan Bitfocus Companion para controlar muchos dispositivos desde una sola superficie de control.
• Cualquiera que quiera un botón de "Iniciar traducción" sin abrir el panel.

Funciona con todos los tipos de dispositivo de SermonWave: la caja SW1, un dispositivo web (navegador) y el plugin de OBS.

Antes de empezar#

• Debes ser Admin Org. Solo los administradores de la organización ven la configuración de control. Consulta Usuarios y roles.
• El dispositivo que quieres controlar, ya configurado. Consulta Elige un tipo de dispositivo.
• Una prueba o un plan activos. Igual que con el botón Iniciar del panel, un inicio desde un botón se rechaza cuando tu prueba o tu suscripción terminó. Detener sigue funcionando. Consulta Planes y tu prueba gratuita.
• Acceso a internet en la computadora donde corre la aplicación de Stream Deck o Companion.

Paso 1 — Crea un token de control#

Un token de control es una clave secreta que permite que un botón controle un dispositivo. Un token del dispositivo del santuario no puede controlar el dispositivo del salón de jóvenes.

1. En el panel, ve a Dispositivos y abre el dispositivo.
2. Abre la pestaña Configuración y busca la tarjeta Control por Stream Deck / API.
3. Escribe un nombre que reconozcas después, como "Stream Deck de la cabina", y haz clic en Crear token.
4. Copia el token de inmediato. Empieza con swc_ y solo se muestra una vez. La tarjeta también muestra direcciones listas para usar para cada acción.

Captura de pantalla próximamente

Administración de tokens:

• Hasta 10 tokens por dispositivo. Crea uno por cada superficie de control para poder revocar uno sin afectar a los demás.
• La tarjeta muestra de cada token el Nombre y las fechas de Creado y Último uso.
• Haz clic en Revocar para desactivar un token. Los botones que lo usan dejan de funcionar al instante.

Permitir en URL. De forma predeterminada, el token debe enviarse en un encabezado de la solicitud. Activa Permitir en URL solo para herramientas que no pueden enviar encabezados, como un simple botón "Open website". El token se agrega entonces a la dirección como ?token=swc_....

Paso 2 — Conoce las direcciones#

Todas las direcciones empiezan con esta base, donde <device_id> es el número de tu dispositivo:

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

Detalles:

• Envía el token en un encabezado: Authorization: Bearer swc_...
• Usa POST cuando tu herramienta lo permita. Las acciones también aceptan GET, para herramientas que solo pueden abrir una dirección.
• Usa códigos de idioma que tu dispositivo ya ofrece, como es (español) o fr (francés). No puedes quitar el último idioma.
• Los cambios de idioma se guardan igual que los cambios en la pestaña Configuración. Si el dispositivo está fuera de línea, se guardan y se aplican cuando se vuelve a conectar.
• Agrega ?format=text para recibir una sola palabra, como recording, en lugar de JSON.

Paso 3 — Configura un Elgato Stream Deck#

1. En la aplicación de Stream Deck, abre el Marketplace e instala el plugin gratuito Web Requests o API Ninja.
2. Arrastra la acción HTTP Request del plugin a una tecla.
3. Pon Method en POST y URL en la dirección de una acción, por ejemplo .../toggle.
4. Agrega el encabezado. En Web Requests, escribe Authorization: Bearer swc_... en Headers. En API Ninja, usa {"Authorization":"Bearer swc_..."}.
5. Presiona la tecla durante un ensayo. Muestra una marca de verificación cuando SermonWave aceptó el comando, y una alerta si hay un error. Confírmalo en Supervisa una sesión en vivo.

Haz una tecla por acción, por ejemplo Iniciar, Detener o "Alternar español" (.../language/toggle/es). Una Multi Action de Stream Deck puede encadenarlas.

Captura de pantalla próximamente

Paso 4 — Configura Bitfocus Companion#

1. Agrega la conexión Generic: HTTP Requests.
2. En un botón, agrega una acción POST. Usa tu dirección .../toggle (o /start, /stop, /language/toggle/es).
3. En el campo del encabezado, escribe {"Authorization":"Bearer swc_..."}.
4. Opcional: agrega respuesta visual al botón (ver abajo).

Paso 5 — Respuesta visual del botón con el estado#

La dirección /status devuelve state (recording, armed, idle u offline), si el dispositivo está en vivo, la cantidad de oyentes y los idiomas actuales.

• Companion: consulta .../status cada 2 a 5 segundos con una acción GET en un trigger. Guarda $.state en una variable personalizada y luego colorea el botón: rojo para recording, ámbar para armed, gris para offline.
• Stream Deck: si tu plugin puede consultar una dirección y mostrar la respuesta en la tecla, consulta .../status?format=text cada 2 segundos o más. Si no, la marca de verificación o la alerta en cada pulsación es tu respuesta visual.
• No necesitas consultar justo después de una pulsación. La respuesta a una acción ya incluye el nuevo estado.

Límites de solicitudes. Cada token puede enviar unas 30 acciones y 300 consultas de estado por minuto. Consultar cada 2 segundos usa unas 30. Un dispositivo ejecuta un comando a la vez, así que una doble pulsación no puede hacerlo cambiar de un lado a otro. Si desde una misma red llegan demasiados tokens incorrectos, se bloquea por un tiempo.

Ejemplos con 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

Control local en OBS#

El plugin de OBS tiene sus propios controles, así que un Stream Deck o Companion puede comunicarse solo con OBS en tu red, sin necesidad de internet. Aparecen en Ajustes de OBS → Atajos (OBS Settings → Hotkeys), y el plugin también responde a solicitudes de proveedor de obs-websocket (proveedor sermonwave). Para ver la lista completa y cómo usarlos, consulta Atajos de OBS y control con Stream Deck.

Solución de problemas#

Estas son las respuestas que puedes recibir. El texto puede cambiar.

Preguntas frecuentes#

No veo la tarjeta Control por Stream Deck / API.#

Solo la ven los administradores de la organización, y se puede desactivar para una cuenta. Si eres administrador y no aparece, pide a soporte que la active.

¿Un solo token controla todos mis dispositivos?#

No. Cada token controla exactamente un dispositivo. Crea un token en cada dispositivo que quieras controlar.

¿Los voluntarios que no son administradores pueden crear tokens?#

No. Solo los administradores de la organización pueden crear o revocar tokens de control.

¿Funciona con otras herramientas además de Stream Deck y Companion?#

Sí. Funciona cualquier herramienta que pueda enviar una solicitud web, como un sistema de domótica o un script.