API PLAYDECK
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'uso | Interfaccia consigliata | Porto |
|---|---|---|
| Script, cURL, Postman, integrazioni HTTP personalizzate | API REST /api/v1 (OpenAPI 3) | 11411 |
| Stato in tempo reale, Eventi, Sovrapposizioni HTML, Bitfocus Companion | Canale WebSocket | 11411 |
| Superfici di controllo prefabbricate | Bitfocus Companion (tramite WebSocket) | 11411 |
| Client TCP legacy / Pipeline di automazione esistenti | Comandi TCP in | 11375 |
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:
- Lancio PLAYDECK.
- Vai a Impostazioni ➔ Rete ➔ API per sviluppatori e clicca su Riferimento API aperto.
- 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].
