PLAYDECK-API
Integrieren Sie PLAYDECK mithilfe unserer Standard-REST-API (OpenAPI 3) und der WebSocket-Schnittstelle in Skripte, Automatisierungssysteme und benutzerdefinierte Benutzeroberflächen, um die Steuerung in Echtzeit über einen einzigen Port zu ermöglichen.
In diesem Artikel:
→ Welche Schnittstelle brauche ich?
→ REST-API-Schnellstart
→ Interaktive API-Referenz
→ WebSocket-Echtzeitkanal
→ Eingabe von älteren TCP-Befehlen
→ Beispiele für die Integration
Welche Schnittstelle brauche ich?
PLAYDECK bietet je nach Ihren Integrationsanforderungen verschiedene Schnittstellen an. Wählen Sie anhand der folgenden Übersicht das richtige Protokoll und den richtigen Port aus:
| Anwendungsfall | Empfohlene Schnittstelle | Hafen |
|---|---|---|
| Skripte, cURL, Postman, benutzerdefinierte HTTP-Integrationen | REST-API /api/v1 (OpenAPI 3) | 11411 |
| Live-Status, Ereignisse, HTML-Overlays, Bitfocus Companion | WebSocket-Kanal | 11411 |
| Fertige Steuerflächen | Bitfocus Companion (über WebSocket) | 11411 |
| Alte TCP-Clients / Bestehende Automatisierungspipelines | TCP-Befehle in | 11375 |
Empfehlung: Die meisten neuen Integrationsprojekte sollten mit dem REST-API. Wechseln Sie dazu oder kombinieren Sie es mit WebSocket nur, wenn Sie kontinuierliche Statusaktualisierungen mit geringer Latenz oder Ereignisauslöser in Echtzeit benötigen.
REST-API-Schnellstart
Während PLAYDECK läuft, ist die HTTP-REST-API automatisch über den Port 11411 (nutzt denselben Dienst wie die integrierte Web-Fernbedienung).
Basis-URL
http://HOST:11411/api/v1
Ersetzen MODERATOR durch die tatsächliche IP-Adresse Ihres PLAYDECK-Geräts, die Sie unter Einstellungen ➔ Netzwerk ➔ Entwickler-API.
Testen in PLAYDECK
Sie benötigen keine externen Tools, um mit dem Testen zu beginnen. Öffnen Sie Einstellungen ➔ Netzwerk ➔ Entwickler-API innerhalb der Softwareanwendung, um Beispielanfragen direkt über die Benutzeroberfläche zu senden oder die interaktive Dokumentation zu öffnen.
Beispiele für HTTP-Anfragen
1. Service-Zustandsprüfung:
GET /api/v1/health HTTP/1.1
Host: HOST:11411
2. Playout-Status abrufen (JSON-Antwort):
GET /api/v1/status HTTP/1.1
Host: HOST:11411
3. Trigger-Play auf Playout, Kanal 1:
POST /api/v1/channels/1/play HTTP/1.1
Host: HOST:11411
4. Block 1, Clip 2 auf Playout, Kanal 1 abspielen:
POST /api/v1/channels/1/play/1/2 HTTP/1.1
Host: HOST:11411
Viele Aktionen akzeptieren optionale Pfadparameter zur gezielten Steuerung (wie beispielsweise Block-/Clip-IDs, Timecode-Offsets oder Overlay-IDs).
Legacy-Befehl „Escape Hatch“
Wenn Sie die klassische PLAYDECK-Befehlssprache über HTTP vollständig nutzen möchten, können Sie Befehle im Pipe-Format an den dafür vorgesehenen Befehls-Endpunkt übermitteln:
POST /api/v1/commands HTTP/1.1
Host: HOST:11411
Content-Type: application/json
{
"command": "play",
"args": ["1", "1", "2"]
}
Hinweis: Für den Betrieb im lokalen Netzwerk (LAN) ist in der aktuellen Version kein API-Schlüssel und kein Authentifizierungstoken erforderlich.
Interaktive API-Referenz
Der vollständige, maschinenlesbare Vertrag für diese Schnittstelle wird als OpenAPI-3-Spezifikationsdokument bereitgestellt.
➔ Download: OpenAPI-Spezifikation (YAML)
Für interaktives Durchsuchen, die Überprüfung von Nutzdaten und direkte “Try it out”-Tests mit Ihrer aktiven PLAYDECK-Instanz:
- Start PLAYDECK.
- Gehen Sie zu Einstellungen ➔ Netzwerk ➔ Entwickler-API und klicken Sie auf Offene API-Referenz.
- Alternativ können Sie auf einem beliebigen Rechner im selben Netzwerk einen Webbrowser öffnen und folgende Adresse aufrufen:
http://HOST:11411/api/v1/docs
Auf dieser Dokumentationsseite werden alle verfügbaren REST-Endpunkte, erforderlichen Parameter, Schemadefinitionen und erwarteten Antwortinhalte dynamisch aufgelistet.
WebSocket-Echtzeitkanal
Hafen 11411 verarbeitet gleichzeitig WebSocket-Verbindungen. Dieser bidirektionale Kanal wurde speziell für Anwendungen entwickelt, die einen kontinuierlichen Datenstrom erfordern:
- Aktueller Status von Playout: Hochfrequente Positionsverfolgung bei der Wiedergabe und Timecode-Aktualisierungen.
- Ereignisauslöser: Sofortige Benachrichtigungen, wenn ein Clip, ein Block oder eine Wiedergabeliste startet, stoppt oder in einer Schleife abgespielt wird.
- Klassische Pipe-Befehle: Direkte Verarbeitung nativer Steuerbefehle im Format
<play|1|...>.
Der Beamte Bitfocus Companion PLAYDECK-Modul, das Web-Fernbedienungs-Benutzeroberfläche, benutzerdefinierte HTML-Grafik-Overlays und Director-View-Vorlagen nutzen diesen speziellen Echtzeitkanal. Eine vollständige Dokumentation zur Syntax der Befehle und Ereignistypen finden Sie direkt im Anwendungspaket oder in Ihrem lokalen Vorlagenverzeichnis:
Web-Remote-Benutzeroberfläche:
c:\Program Files\JoyEventMedia\Playdeck\html\webremote.html
HTML-Vorlagen:
C:\Users\Public\Documents\JoyEventMedia\Playdeck\HTML-Templates\
oder
c:\Users\\AppData\Local
Eingabe von älteren TCP-Befehlen
Um die Abwärtskompatibilität mit der bestehenden Infrastruktur für die Sendeautomatisierung zu gewährleisten, akzeptiert PLAYDECK weiterhin eingehende TCP-Rohverbindungen auf Port 11375.
Diese Einstellung wird unter folgendem Menüpunkt verwaltet: Einstellungen ➔ Netzwerk ➔ Eingehend ➔ TCP-Befehle aktivieren. Die Syntax der Nutzdaten entspricht dem durch Pipe-Zeichen getrennten Format, das vom WebSocket-Kanal und von REST verwendet wird /api/v1/commands Endpunkt.
- Anmerkung des Entwicklers: Für alle von Grund auf neu entwickelten Projekte und die Integration neuer Skripte empfehlen wir dringend, die REST-API anstelle von reinen TCP-Sockets zu verwenden.
Beispiele für die Integration
- Bitfocus Companion: Schnelle Bereitstellung physischer Hardware-Bedienelemente mithilfe unseres produktionsreifen nativen Moduls über WebSockets.
- Web-Fernsteuerung: Umfassende Schnittstelle zur Produktionssteuerung, die über jeden Browser am Port zugänglich ist
11411. - Director-Ansicht und HTML-Overlays: Integrierte Webvorlagen, die die Live-Statusbindung veranschaulichen.
- Maßgeschneiderte Software-Tools: Schnelle Anwendungsentwicklung mithilfe von Standard-HTTP-Clients, die auf Basis unserer OpenAPI-Spezifikation generiert werden und optional durch WebSockets für Telemetriedaten unterstützt werden.
Haben Sie Fragen oder spezielle Anforderungen an den Arbeitsablauf? Wenden Sie sich an unser Technikteam unter [email protected].
