Senza categoria

API PLAYDECK

26 ottobre 2025 da

Integra PLAYDECK in script, sistemi di automazione e interfacce utente personalizzate utilizzando la nostra API REST standard (OpenAPI 3) e l'interfaccia WebSocket per il controllo in tempo reale su un'unica porta.

In questo articolo:
→ Di quale interfaccia ho bisogno?
→ Guida rapida all'API REST
→ Guida interattiva alle API
→ Canale in tempo reale WebSocket
→ Inserimento dei comandi TCP tradizionali
→ Esempi di integrazione

Di quale interfaccia ho bisogno?

PLAYDECK offre diverse interfacce a seconda delle esigenze di integrazione. Utilizza la seguente panoramica per selezionare il protocollo e la porta corretti:

Caso d'usoInterfaccia consigliataPorto
Script, cURL, Postman, integrazioni HTTP personalizzateAPI REST /api/v1 (OpenAPI 3)11411
Stato in tempo reale, Eventi, Sovrapposizioni HTML, Bitfocus CompanionCanale WebSocket11411
Superfici di controllo prefabbricateBitfocus Companion (tramite WebSocket)11411
Client TCP legacy / Pipeline di automazione esistentiComandi TCP in11375

Raccomandazione: La maggior parte dei nuovi progetti di integrazione dovrebbe iniziare con il API REST. Passa a questa opzione o abbinala a WebSocket solo se sono necessari aggiornamenti di stato continui e a bassa latenza o trigger di eventi in tempo reale.

Guida rapida all'API REST

Mentre PLAYDECK è in esecuzione, l'API HTTP REST è automaticamente disponibile sulla porta 11411 (che utilizza lo stesso servizio del Web Remote integrato).

URL di base

http://HOST:11411/api/v1


Sostituisci HOST con l'indirizzo IP effettivo del tuo dispositivo PLAYDECK, che trovi in Impostazioni ➔ Rete ➔ API per sviluppatori.

Test all'interno di PLAYDECK

Non servono strumenti esterni per iniziare a eseguire i test. Apri Impostazioni ➔ Rete ➔ API per sviluppatori all'interno dell'applicazione software per inviare richieste di campioni direttamente dall'interfaccia utente o per aprire la documentazione interattiva.

Esempi di richieste HTTP

1. Verifica dello stato del servizio:

GET /api/v1/health HTTP/1.1
Host: HOST:11411


2. Recupera lo stato di Playout (risposta JSON):

GET /api/v1/status HTTP/1.1
Host: HOST:11411


3. Attivazione del Play sul canale 1 di Playout:

POST /api/v1/channels/1/play HTTP/1.1
Host: HOST:11411


4. Riproduci il blocco 1, clip 2 sul canale 1 di Playout:

POST /api/v1/channels/1/play/1/2 HTTP/1.1
Host: HOST:11411


Molte azioni accettano parametri di percorso opzionali per un controllo mirato (come gli ID di blocchi/clip, gli offset del timecode o gli ID di sovrapposizione).

Scappatoia di emergenza del comando Legacy

Se hai bisogno di una copertura completa del classico linguaggio di comando PLAYDECK tramite HTTP, puoi inviare comandi in formato pipe all'endpoint dedicato ai comandi:

POST /api/v1/commands HTTP/1.1
Host: HOST:11411
Content-Type: application/json

{
  "command": "play",
  "args": ["1", "1", "2"]
}


Nota: nella versione attuale non è richiesta alcuna chiave API né alcun token di autenticazione per le operazioni in rete locale (LAN).

Guida interattiva alle API

Il contratto completo leggibile da macchina relativo a questa interfaccia è fornito sotto forma di documento di specifica OpenAPI 3.

➔ Scarica: Specifiche OpenAPI (YAML)

Per la navigazione interattiva, l'ispezione del payload e i test diretti con l'opzione “Provalo” sulla tua istanza PLAYDECK attiva:

  1. Lancio PLAYDECK.
  2. Vai a Impostazioni ➔ Rete ➔ API per sviluppatori e clicca su Riferimento API aperto.
  3. In alternativa, apri un browser web su qualsiasi computer all'interno della stessa rete e vai all'indirizzo: http://HOST:11411/api/v1/docs

Questa pagina della documentazione elenca in modo dinamico tutti gli endpoint REST disponibili, i parametri richiesti, le definizioni degli schemi e i payload di risposta previsti.

    Canale in tempo reale WebSocket

    Porto 11411 gestisce contemporaneamente le connessioni WebSocket. Questo canale bidirezionale è stato progettato specificamente per operazioni che richiedono uno streaming di dati continuo:

    • Stato continuo Playout: Monitoraggio della posizione di riproduzione ad alta frequenza e aggiornamenti del timecode.
    • Trigger di evento: Notifiche immediate quando un clip, un blocco o una playlist inizia, si interrompe o viene riprodotto in loop.
    • Comandi classici di Pipe: Elaborazione diretta dei comandi di controllo nativi formattati come <play|1|...>.

    Il sito ufficiale Modulo PLAYDECK di Bitfocus Companion, il Interfaccia utente remota via web, le sovrapposizioni grafiche HTML personalizzate e i modelli di Director View utilizzano questo specifico canale in tempo reale. La documentazione completa sulla sintassi dei comandi e dei tipi di evento è disponibile direttamente all'interno del pacchetto dell'applicazione o nella directory locale dei modelli:

    Interfaccia utente remota web:
c:\Program Files\JoyEventMedia\Playdeck\html\webremote.html

Modelli HTML:
C:\Users\Public\Documents\JoyEventMedia\Playdeck\HTML-Templates\
oppure
c:\Users\\AppData\Local

    Inserimento dei comandi TCP tradizionali

    Per garantire la compatibilità con le versioni precedenti dell’infrastruttura di automazione delle trasmissioni esistente, PLAYDECK continua ad accettare connessioni TCP non elaborate in entrata sulla porta 11375.

    Questa impostazione viene gestita in Impostazioni ➔ Rete ➔ In entrata ➔ Comandi TCP in entrata. La sintassi del payload corrisponde al formato delimitato da barre verticali utilizzato dal canale WebSocket e dall'API REST /api/v1/comandi punto finale.

    • Nota dello sviluppatore: Per tutti i progetti di sviluppo realizzati da zero e le nuove integrazioni di script, consigliamo vivamente di utilizzare l'API REST anziché i socket TCP grezzi.

    Esempi di integrazione

    • Bitfocus Companion: Implementazione rapida di superfici di controllo hardware fisiche tramite il nostro modulo nativo pronto per la produzione su WebSockets.
    • Controllo remoto via web: Interfaccia completa per il controllo della produzione, accessibile tramite qualsiasi browser sulla porta 11411.
    • Visualizzazione del regista e sovrapposizioni HTML: Modelli web integrati che mostrano il collegamento in tempo reale dello stato.
    • Strumenti software personalizzati: Sviluppo rapido di applicazioni tramite client HTTP standard generati dalla nostra specifica OpenAPI, con supporto opzionale di WebSocket per la telemetria.

    Hai domande o esigenze specifiche relative ai flussi di lavoro? Contatta il nostro team di ingegneri all'indirizzo [email protected].