Integre o PLAYDECK a scripts, sistemas de automação e interfaces de usuário personalizadas usando nossa API REST padrão (OpenAPI 3) e a interface WebSocket para controle em tempo real em uma única porta.
Neste artigo:
→ Qual interface eu preciso?
→ Guia rápido da API REST
→ Referência interativa da API
→ Canal em tempo real via WebSocket
→ Entrada de comandos TCP legados
→ Exemplos de integração
Qual interface eu preciso?
O PLAYDECK oferece diferentes interfaces, dependendo dos seus requisitos de integração. Use a visão geral a seguir para selecionar o protocolo e a porta corretos:
| Caso de uso | Interface recomendada | Porto |
|---|---|---|
| Scripts, cURL, Postman, integrações HTTP personalizadas | API REST /api/v1 (OpenAPI 3) | 11411 |
| Status em tempo real, Eventos, Sobreposições em HTML, Bitfocus Companion | Canal WebSocket | 11411 |
| Superfícies de controle pré-fabricadas | Bitfocus Companion (via WebSocket) | 11411 |
| Clientes TCP legados / Pipelines de automação existentes | Comandos TCP em | 11375 |
Recomendação: A maioria dos novos projetos de integração deve começar com o API REST. Mude para essa opção ou combine-a com WebSocket somente se você precisar de atualizações contínuas de status com baixa latência ou acionamentos de eventos em tempo real.
Guia rápido da API REST
Enquanto o PLAYDECK estiver em execução, a API REST HTTP fica automaticamente disponível na porta 11411 (que utiliza o mesmo serviço que o Web Remote integrado).
URL base
http://HOST:11411/api/v1
Substituir ANFITRIÃO com o endereço IP real do seu aparelho PLAYDECK, que pode ser encontrado em Configurações ➔ Rede ➔ API do desenvolvedor.
Testes no PLAYDECK
Você não precisa de ferramentas externas para começar a testar. Abra Configurações ➔ Rede ➔ API do desenvolvedor dentro do aplicativo de software para enviar solicitações de amostras diretamente da interface do usuário ou abrir a documentação interativa.
Exemplos de solicitações HTTP
1. Avaliação do estado do serviço:
GET /api/v1/health HTTP/1.1
Host: HOST:11411
2. Obter o status do Playout (resposta em JSON):
GET /api/v1/status HTTP/1.1
Host: HOST:11411
3. Ativação da operação no canal 1 do Playout:
POST /api/v1/channels/1/play HTTP/1.1
Host: HOST:11411
4. Reproduza o Bloco 1, Clipe 2 no Canal 1 do Playout:
POST /api/v1/channels/1/play/1/2 HTTP/1.1
Host: HOST:11411
Muitas ações aceitam parâmetros de caminho opcionais para controle direcionado (como IDs de bloco/clipe, deslocamentos de código de tempo ou IDs de sobreposição).
Escotilha de Emergência do Comando Legacy
Se você precisar de suporte completo à linguagem de comando clássica do PLAYDECK via HTTP, poderá enviar comandos no formato pipe para o endpoint dedicado a comandos:
POST /api/v1/commands HTTP/1.1
Host: HOST:11411
Content-Type: application/json
{
"command": "play",
"args": ["1", "1", "2"]
}
Observação: Na versão atual, não é necessária nenhuma chave de API nem token de autenticação para operações em rede local (LAN).
Referência interativa da API
O contrato completo, legível por máquina, para esta interface é fornecido como um documento de especificação OpenAPI 3.
➔ Download: Especificação OpenAPI (YAML)
Para navegação interativa, inspeção de carga útil e testes diretos com a opção “Experimente” em sua instância ativa do PLAYDECK:
- Lançamento PLAYDECK.
- Acesse Configurações ➔ Rede ➔ API do desenvolvedor e clique em Referência da API Aberta.
- Como alternativa, abra um navegador da web em qualquer computador da mesma rede e acesse:
http://HOST:11411/api/v1/docs
Esta página de documentação lista dinamicamente todos os endpoints REST disponíveis, os parâmetros obrigatórios, as definições de esquema e os conteúdos de resposta esperados.
Canal em tempo real via WebSocket
Porto 11411 gerencia simultaneamente conexões WebSocket. Esse canal bidirecional foi projetado especificamente para operações que exigem transmissão contínua de dados:
- Status contínuo do Playout: Rastreamento da posição de reprodução em alta frequência e atualizações do código de tempo.
- Gatilhos de eventos: Notificações imediatas quando um clipe, bloco ou lista de reprodução começa, para ou entra em loop.
- Comandos clássicos do Pipe: Processamento direto de comandos de controle nativos formatados como
<play|1|...>.
O representante oficial Módulo PLAYDECK do Bitfocus Companion, o Interface de usuário remota na web, sobreposições gráficas personalizadas em HTML e modelos do Director View utilizam esse canal específico em tempo real. A documentação completa da sintaxe dos comandos e tipos de eventos pode ser encontrada diretamente no pacote do aplicativo ou no diretório local de modelos:
Interface de usuário remota na web:
c:\Program Files\JoyEventMedia\Playdeck\html\webremote.html
Modelos HTML:
C:\Users\Public\Documents\JoyEventMedia\Playdeck\HTML-Templates\
ou
c:\Users\\AppData\Local
Entrada de comandos TCP legados
Para manter a compatibilidade com versões anteriores da infraestrutura de automação de transmissão existente, o PLAYDECK continua aceitando conexões TCP brutas recebidas na porta 11375.
Essa configuração é gerenciada em Configurações ➔ Rede ➔ Entrada ➔ Comandos TCP de entrada. A sintaxe da carga útil corresponde ao formato delimitado por barras verticais usado pelo canal WebSocket e pela REST /api/v1/comandos ponto final.
- Nota do desenvolvedor: Para todos os projetos de desenvolvimento criados do zero e novas integrações de scripts, recomendamos fortemente o uso da API REST em vez de soquetes TCP diretos.
Exemplos de integração
- Bitfocus Companion: Implantação rápida de superfícies de controle de hardware físico por meio de nosso módulo nativo pronto para produção via WebSockets.
- Controle remoto pela web: Interface de controle de produção com todos os recursos, acessível por meio de qualquer navegador na porta
11411. - Visualização do diretor e sobreposições em HTML: Modelos da web integrados que demonstram a vinculação de status em tempo real.
- Ferramentas de software personalizadas: Desenvolvimento rápido de aplicativos utilizando clientes HTTP padrão gerados a partir de nossa especificação OpenAPI, opcionalmente complementados por WebSockets para telemetria.
Tem dúvidas ou necessidades específicas relacionadas a fluxos de trabalho? Entre em contato com nossa equipe de engenharia pelo e-mail [email protected].
