API de PLAYDECK
Integra PLAYDECK en scripts, sistemas de automatización e interfaces de usuario personalizadas mediante nuestra API REST estándar (OpenAPI 3) y la interfaz WebSocket para el control en tiempo real a través de un único puerto.
En este artículo:
→ ¿Qué interfaz necesito?
→ Guía rápida de la API REST
→ Referencia interactiva de la API
→ Canal en tiempo real WebSocket
→ Introducción de comandos TCP heredados
→ Ejemplos de integración
¿Qué interfaz necesito?
PLAYDECK ofrece diferentes interfaces en función de tus necesidades de integración. Utiliza la siguiente tabla para seleccionar el protocolo y el puerto adecuados:
| Caso de uso | Interfaz recomendada | Puerto |
|---|---|---|
| Scripts, cURL, Postman, integraciones HTTP personalizadas | API REST /api/v1 (OpenAPI 3) | 11411 |
| Estado en tiempo real, eventos, superposiciones HTML, Bitfocus Companion | Canal WebSocket | 11411 |
| Superficies de control prefabricadas | Bitfocus Companion (a través de WebSocket) | 11411 |
| Clientes TCP heredados / Flujos de automatización existentes | Comandos TCP en | 11375 |
Recomendación: La mayoría de los nuevos proyectos de integración deberían comenzar con el API REST. Cambia a esta opción o combínala con WebSocket solo si necesitas actualizaciones de estado continuas y de baja latencia o activadores de eventos en tiempo real.
Guía rápida de la API REST
Mientras PLAYDECK está en ejecución, la API REST HTTP está disponible automáticamente en el puerto 11411 (que comparte el mismo servicio que el Web Remote integrado).
URL base
http://HOST:11411/api/v1
Sustituir ANFITRIÓN por la dirección IP real de tu máquina PLAYDECK, que encontrarás en Ajustes ➔ Red ➔ API para desarrolladores.
Pruebas en PLAYDECK
No necesitas herramientas externas para empezar a realizar pruebas. Abre Ajustes ➔ Red ➔ API para desarrolladores desde la propia aplicación de software para enviar solicitudes de muestras directamente desde la interfaz de usuario o abrir la documentación interactiva.
Ejemplos de solicitudes HTTP
1. Revisión del estado del servicio:
GET /api/v1/health HTTP/1.1
Host: HOST:11411
2. Obtener el estado de Playout (respuesta JSON):
GET /api/v1/status HTTP/1.1
Host: HOST:11411
3. Activación de la orden «Play» en el canal 1 de Playout:
POST /api/v1/channels/1/play HTTP/1.1
Host: HOST:11411
4. Reproduce el bloque 1, clip 2, en el canal 1 de Playout:
POST /api/v1/channels/1/play/1/2 HTTP/1.1
Host: HOST:11411
Muchas acciones admiten parámetros de ruta opcionales para un control más preciso (como los identificadores de bloque o clip, los desplazamientos de código de tiempo o los identificadores de superposición).
Escotilla de emergencia del Legacy Command
Si necesitas una compatibilidad total con el lenguaje de comandos clásico de PLAYDECK a través de HTTP, puedes enviar comandos con formato de barra vertical al punto final dedicado a los comandos:
POST /api/v1/commands HTTP/1.1
Host: HOST:11411
Content-Type: application/json
{
"command": "play",
"args": ["1", "1", "2"]
}
Nota: En la versión actual no se requiere ninguna clave API ni token de autenticación para las operaciones en la red de área local (LAN).
Referencia interactiva de la API
El contrato completo, legible por máquina, para esta interfaz se proporciona en forma de documento de especificación OpenAPI 3.
➔ Descargar: Especificación OpenAPI (YAML)
Para la navegación interactiva, la inspección de la carga útil y las pruebas directas con la opción “Pruébalo” en tu instancia activa de PLAYDECK:
- Inicio PLAYDECK.
- Ve a Ajustes ➔ Red ➔ API para desarrolladores y haz clic en Referencia de la API abierta.
- También puedes abrir un navegador web en cualquier ordenador de la misma red y acceder a:
http://HOST:11411/api/v1/docs
Esta página de documentación muestra de forma dinámica todos los puntos finales REST disponibles, los parámetros obligatorios, las definiciones de esquemas y las cargas útiles de respuesta esperadas.
Canal en tiempo real WebSocket
Puerto 11411 gestiona simultáneamente conexiones WebSocket. Este canal bidireccional está diseñado específicamente para operaciones que requieren una transmisión continua de datos:
- Estado de Playout continuo: Seguimiento de la posición de reproducción a alta frecuencia y actualizaciones del código de tiempo.
- Desencadenantes de eventos: Notificaciones inmediatas cuando un clip, un bloque o una lista de reproducción se inicia, se detiene o se reproduce en bucle.
- Comandos clásicos de Pipe: Procesamiento directo de comandos de control nativos con el formato
<play|1|...>.
El funcionario Módulo PLAYDECK de Bitfocus Companion, el Interfaz de usuario remota web, las superposiciones gráficas HTML personalizadas y las plantillas de Director View utilizan este canal específico en tiempo real. La documentación completa sobre la sintaxis de los comandos y los tipos de eventos se puede consultar directamente en el paquete de la aplicación o en el directorio local de plantillas:
Interfaz de usuario remota web:
c:\Program Files\JoyEventMedia\Playdeck\html\webremote.html
Plantillas HTML:
C:\Users\Public\Documents\JoyEventMedia\Playdeck\HTML-Templates\
o
c:\Users\\AppData\Local
Introducción de comandos TCP heredados
Para mantener la compatibilidad con versiones anteriores de la infraestructura de automatización de emisiones existente, PLAYDECK sigue aceptando conexiones TCP sin procesar entrantes en el puerto 11375.
Esta configuración se gestiona en Ajustes ➔ Red ➔ Entrante ➔ Comandos TCP en. La sintaxis de la carga útil coincide con el formato delimitado por barras verticales que utilizan el canal WebSocket y REST /api/v1/comandos punto final.
- Nota del desarrollador: Para todos los proyectos de desarrollo que partan de cero y las nuevas integraciones de scripts, recomendamos encarecidamente utilizar la API REST en lugar de sockets TCP sin procesar.
Ejemplos de integración
- Bitfocus Companion: Implementación rápida de superficies de control de hardware físico mediante nuestro módulo nativo listo para producción a través de WebSockets.
- Control remoto web: Interfaz de control de producción con todas las funciones, accesible a través de cualquier navegador en el puerto
11411. - Vista del director y superposiciones HTML: Plantillas web integradas que muestran la vinculación de estados en tiempo real.
- Herramientas de software a medida: Desarrollo rápido de aplicaciones mediante clientes HTTP estándar generados a partir de nuestra especificación OpenAPI, con el respaldo opcional de WebSockets para la telemetría.
¿Tienes alguna pregunta o necesitas un flujo de trabajo a medida? Ponte en contacto con nuestro equipo de ingeniería en [email protected].
