LDSperimetral HTTP-API

Version: 1.58.1

Zuletzt aktualisiert: 2026-11-12

Diese Referenz beschreibt die implementierten Player-Steuerungsdienste und onTV-Messdienste. Alle Beispiele dienen zur Veranschaulichung.

Inhalt

• Einrichtung und Zugriff
• Anfragen und Antworten
• Player-Routen
• Parameter
• Player-Daten
• onTV-Routen und -Daten
• Beispiele
• Einschränkungen

Einrichtung und Zugriff

Verwenden Sie eine funktionierende LDSperimetral-Installation unter Windows mit deren .NET Framework 4.7.2-Laufzeitumgebung und normaler Player-Konfiguration. Die Anwendung muss ausgeführt werden. Die API wird von der Anwendung selbst bereitgestellt, nicht von einem separaten Server.

Aktivieren Sie im Terminal-Konfigurationsfenster die Remote-Player-Steuerung für den Player-Dienst. Aktivieren Sie den onTV-Zähler separat für den Statistikdienst. Speichern und wenden Sie die Terminal-Konfiguration an. Das Fenster lehnt denselben Port wie den Synchronisationsnetzwerkport ab. Die entsprechenden gespeicherten Einstellungen in config/terminals.xml sind remote_player_enabled, on_tv_meter_enabled und port. Beide Aktivierungs-Flags sind standardmäßig auf „false“ gesetzt. Der Standardwert im Code für port ist 8083; eine bestehende Installation kann einen anderen Port verwenden.

Ersetzen Sie HOST durch die Adresse des Player-Computers und PORT durch den konfigurierten HTTP-Port. Verwenden Sie 127.0.0.1 nur von diesem Computer aus. Der Host bindet an http://0.0.0.0:PORT/; dies ist kein Client-Ziel. Windows-URL-Berechtigungen, Firewall-Regeln und die Netzwerkerreichbarkeit können den Zugriff beeinflussen. Beim Start kann die Berechtigung zum Öffnen des TCP-Firewall-Ports und zum Gewähren einer Windows-URL-Reservierung angefordert werden. Befolgen Sie die Aufforderungen der Anwendung, einschließlich eines Neustarts, falls dieser angefordert wird.

Der Dienst verwendet einfachen HTTP und ein Standard-WebHttpBinding. In diesen Diensten sind kein API-Schlüssel, kein Login, keine Autorisierung pro Befehl und keine IP-Zugriffsliste für Clients implementiert. Erreichbare Clients können Wiedergabe- und Messbefehle ausführen. Beschränken Sie den Zugriff auf vertrauenswürdige Clients. Windows-URL-Reservierungen berechtigen den Serverprozess zum Lauschen; sie authentifizieren keine API-Aufrufer. Von diesem Host werden keine HTTPS- oder CORS-Konfigurationen bereitgestellt. Cross-Origin-Zugriffe über den Browser stellen keine zugesicherte Schnittstelle dar.

Anfragen und Antworten

Alle folgenden Routen verwenden GET, einschließlich Befehlen, die den Status ändern. Hängen Sie jede Route an die Basis-URL des Dienstes an. Es sind weder ein Anfragetext (Request Body) noch Abfrageparameter (Query Parameter) deklariert. Platzhalter in geschweiften Klammern sind erforderliche Pfadsegmente, es sei denn, die Route beschreibt ausdrücklich das Platzhalterzeichen zum Stoppen von Overlays. Senden Sie die Klammern nicht wörtlich mit.

Antworten verwenden WCF-JSON-Serialisierung und ein gemeinsames Objekt:

Anwendungsfehler werden in diesem Envelope zurückgegeben, ohne den HTTP-Status explizit zu ändern. Ein normaler serialisierter Anwendungsfehler bleibt daher eine erfolgreiche HTTP-Antwort. Überprüfen Sie immer den status und danach das erwartete result. Ein Transport- oder WCF-Routing-Fehler kann einen anderen Nachrichtenkörper haben und darf nicht als garantierter Envelope geparst werden. Tests erwarten HTTP 404 für eine unbekannte Route und 405 für eine nicht unterstützte Methode; diese Erwartungen wurden für diese Referenz nicht anhand eines laufenden Hosts verifiziert.

Bei Boolean-Befehlen bedeuten status: 0 und result: true, dass der Befehlspfad verarbeitet wurde. Sie beweisen keine erfolgreiche audiovisuelle Ausgabe oder den Abschluss eines Übergangs. Einige nachgeschaltete Methoden fangen Fehler ab oder tun nichts, wenn kein Renderer vorhanden ist. Fragen Sie get_reproduction_state nach einem Befehl ab und warten Sie mit einem vom Client definierten Timeout auf den gewünschten Zustand. Es gibt keine Befehls-ID, keinen Endpunkt für den Abschluss, keine Push-Benachrichtigung und keine festgelegte Übergangsfrist. Senden Sie einen Befehl nicht wiederholt, während Sie auf dessen Wirkung warten.

Außer bei ping laufen Player-Operationen über den Dispatcher des Steuerungsfensters, sofern verfügbar. Dadurch wird deren Steuerungszugriff im UI-Thread serialisiert, separate HTTP-Anfragen werden dadurch jedoch nicht zu einer atomaren Transaktion. Statistikoperationen verwenden diesen Player-Dispatch-Helfer nicht.

Player-Routen

Alle Pfade in dieser Tabelle sind relativ zu /ws/remoteplayer/.

Die benannte Overlay-Route ist spezifischer als der Platzhalter. Ein nicht existierender Overlay-Name gibt SEQUENCE_NOT_FOUND zurück; dies ist keine Stopp-Anfrage. Platzhalter-Routing mit leerem Ende und andere kodierte Pfad-Spezialfälle erfordern weiterhin eine Host-Validierung.

Parameter

Prozentkodieren Sie jedes Zeichenfolgen-Pfadsegment als UTF-8. Beispielsweise wird aus Demo Show der Wert Demo%20Show; kodieren Sie ein wörtliches + als %2B, # als %23, ? als %3F und % als %25. Kodieren Sie nicht die Trennzeichen zwischen Routensegmenten. URL-Hilfsprogramme verwenden Uri.EscapeDataString für Startreferenzen. Kodierte Schrägstriche, Backslashes und vollständige Dateisystempfade können durch den Windows-HTTP-Stack beeinflusst werden und wurden hier nicht verifiziert. Bevorzugen Sie einen eindeutigen Namen oder Basisnamen ohne Pfadtrennzeichen. Fehlende erforderliche Segmente können das WCF-Routing vor der Anwendungsvalidierung fehlschlagen lassen.

Player-Daten

Die folgenden Feldnamen entsprechen exakt den JSON-Vertragsnamen. Die Reihenfolge der Objekteigenschaften ist nicht signifikant. Dateifelder enthalten gespeicherte Referenzen und können Dateisysteminformationen preisgeben; gehen Sie nicht davon aus, dass es sich dabei um öffentliche Download-URLs handelt.

Zeitwerte sind JSON-Zeichenfolgen, keine Zahlen oder formatierten Zeitspannen (Time Spans). Beide Zeitfelder lauten "0", wenn keine Sequenz aktiv ist. Ihre Interpolation verwendet die Server-Kultur; gehen Sie nicht von einem invarianten Dezimaltrennzeichen oder einer Messgenauigkeit im Millisekundenbereich aus. Aus dem Modell kopierte Datei-/Namenswerte können null sein. Ein Anwendungsfehler kann null, leere oder teilweise gefüllte Ergebnisse zurückgeben; überprüfen Sie den status, bevor Sie sie verwenden.

onTV-Routen und -Daten

Alle Pfade in dieser Tabelle sind relativ zu /ws/statsmeter/. Behalten Sie die Schreibweise mesures exakt wie gezeigt bei.

Diese Befehle markieren Messzeiträume. Sie starten oder stoppen keine Playlist-Wiedergabe und erkennen kein Sendesignal. Der Controller gibt ein Standardintervall oder eine leere Liste für die Listenoperation zurück, wenn kein Renderer vorhanden ist. Ein Renderer ohne Statistikzähler kann null zurückgeben; Start und Stopp stoßen dann auf eine Dereferenzierung bei der Dienstprotokollierung und melden einen internen Fehler. Dies kann eine OK-Antwort ohne tatsächliche Messung sein.

Die nicht festgelegte Markierung (Unset Marker) ist ein Datum mit dem Jahr 1970, initialisiert als 1. Januar 1970. Ein offenes Intervall hat ein nicht festgelegtes Ende. Kein aufgezeichnetes Intervall erzeugt ein Standardobjekt mit beiden Datumsangaben als nicht festgelegt. Wiederholtes Stoppen belässt ein geschlossenes Intervall unverändert. Datumsangaben stammen von DateTime.Now auf dem Server. WCF verwendet die Darstellung /Date(milliseconds[+or-offset])/, möglicherweise mit JSON-Slash-Escaping; dies ist kein ISO 8601-Vertrag. Der optionale Offset und die Behandlung von lokalen/nicht angegebenen DateTime-Werten müssen auf dem bereitgestellten Host überprüft werden. Interpretieren Sie den Sentinel-Wert nicht als echten gemessenen Zeitstempel.

Die Millisekunden-Akkumulation verwendet vor dem Runden eine Konvertierung in eine 32-Bit-Ganzzahl. Lange Verläufe können diesen Bereich überschreiten. Betrachten Sie dies nicht als unbegrenzt präzisen Dauermesszähler oder als garantierten Gesamtverlauf über Neustarts hinweg. Statistik-Catcher melden INTERNAL_ERROR; deren Nachricht kann null bleiben.

Beispiele

Alle Anfragen und JSON-Werte in diesem Abschnitt dienen zur Veranschaulichung. Der Host, Namen und Dateireferenzen sind Platzhalter ohne private Daten. Antworten sind vollständige Envelopes, sofern nicht anders beschrieben. Die Reihenfolge der Eigenschaften und JSON-Leerzeichen können abweichen.

Überprüfen Sie die Verfügbarkeit vom Player-Computer aus, wenn der konfigurierte Port 8083 ist:

curl "http://127.0.0.1:8083/ws/remoteplayer/ping"

{"message":null,"result":true,"status":0}

Sequenzen in einer verfügbaren Playlist namens Demo Show auflisten:

curl "http://127.0.0.1:8083/ws/remoteplayer/list_playlist_sequences/Demo%20Show"

{"message":null,"result":[{"filename":"demo.sequence","is_on_top":false,"name":"Opening"}],"status":0}

Starten Sie deren erste Sequenz und fragen Sie anschließend den Status ab. Dies sind zwei separate Anfragen:

curl "http://127.0.0.1:8083/ws/remoteplayer/start_sequence/Demo%20Show/0"
curl "http://127.0.0.1:8083/ws/remoteplayer/get_reproduction_state"

Veranschaulichende Befehlsantwort:

{"message":null,"result":true,"status":0}

Veranschaulichende Statusantwort nach dem Übergang:

{"message":null,"result":{"is_playing":true,"is_paused":false,"is_render_active":true,"is_quickaction":false,"current_playlist":"Demo Show","current_playlist_file":"demo.playlist","current_sequence":"Opening","current_sequence_index":0,"current_overlay_sequence_name":"","current_overlay_sequence_file":"","current_sequence_elapsed_time":"1000","current_sequence_total_time":"300000"},"status":0}

Ein ungültiger Sequenzindex in einer vorhandenen Playlist:

curl "http://127.0.0.1:8083/ws/remoteplayer/start_sequence/Demo%20Show/-1"

{"message":"Sequence index must identify an existing sequence.","result":false,"status":5}

Abfrage einer fehlenden Playlist:

{"message":"Playlist [Missing] not found.","result":[],"status":4}

Starten Sie ein Overlay namens Demo Overlay und entfernen Sie es anschließend wieder:

curl "http://127.0.0.1:8083/ws/remoteplayer/start_aot_sequence/Demo%20Overlay"
curl "http://127.0.0.1:8083/ws/remoteplayer/start_aot_sequence/"

Globale Helligkeit auf 50 Prozent setzen:

curl "http://127.0.0.1:8083/ws/remoteplayer/set_global_brightness/50"

onTV-Intervall öffnen, inspizieren und schließen, dann die Gesamtsummen ablesen:

curl "http://127.0.0.1:8083/ws/statsmeter/start_on_tv_interval"
curl "http://127.0.0.1:8083/ws/statsmeter/state_on_tv_interval"
curl "http://127.0.0.1:8083/ws/statsmeter/stop_on_tv_interval"
curl "http://127.0.0.1:8083/ws/statsmeter/get_mesures_statistics"

Veranschaulichende Statistikantwort nach einem abgeschlossenen Fünf-Sekunden-Intervall:

{"message":null,"result":{"intervals_recorded":1,"total_seconds_in_tv":5},"status":0}

Einschränkungen

Datums-Offsets, Wildcard-Routing, HTTP-Fehlermeldungen und deploymentspezifischer Zugriff erfordern eine Validierung auf der Zielinstallation.

Diese API-Schicht implementiert weder Ratenbegrenzung (Rate Limiting), Client-Isolierung, Anfragetransaktionen, allgemeine Idempotenzgarantien noch Garantien für den audiovisuellen Abschluss. Befehle verwenden GET, weshalb Link-Vorschauen, Prefetching, Caching und automatische Wiederholungen für Befehle unsicher sein können. Verwenden Sie einen Client, der Anfragen nur bei Bedarf sendet und keine zwischengespeicherten Abfrageantworten wiederverwendet. Der Servercode erstellt keinen Cache-Control-Vertrag.

Die onTV-HTML-Schnittstelle, WCF-Metadaten und mex-Endpunkte sind von den hier dokumentierten JSON-Operationen getrennt. Sie stellen keine zusätzlichen Player-Befehlsrouten dar. In diesen beiden JSON-Verträgen sind weder Uploads, Playlist-Bearbeitungen, Dateidownloads, Helligkeitsrücklesevorgänge noch Ereignisabonnements (Event Subscriptions) deklariert.