LDSperimetral HTTP API
Documented LDSperimetral AssemblyVersion: 1.58.1.1 (declared in the application source). Documentation last updated: 2026-11-12. This identifies the reviewed source version; it does not certify an installed executable.
This reference describes the implemented player control and onTV measurement services. All examples are illustrative. They were not captured from a running application.
Contents
- Setup and access
- Requests and responses
- Player routes
- Parameters
- Player data
- onTV routes and data
- Examples
- Limitations
Setup and access
Use a working LDSperimetral installation on Windows with its .NET Framework 4.7.2 runtime and normal player configuration. The application must be running. The API is hosted by the application, not by a separate server.
In the terminal configuration window, enable remote player control for the player service. Enable the onTV meter separately for the statistics service. Save and apply the terminal configuration. The window rejects the same port as the synchronization network port. The corresponding stored settings in config/terminals.xml are remote_player_enabled, on_tv_meter_enabled, and port. Both enabled flags default to false. The code default for port is 8083; an existing installation can use another port.
| Service | Base URL |
|---|---|
| Player | http://HOST:PORT/ws/remoteplayer/ |
| onTV statistics | http://HOST:PORT/ws/statsmeter/ |
| onTV browser interface | http://HOST:PORT/ontvmeter |
Replace HOST with the player computer address and PORT with its configured HTTP port. Use 127.0.0.1 only from that computer. The host binds to http://0.0.0.0:PORT/; this is not a client destination. Windows URL permissions, firewall rules and network reachability can affect access. Startup can request permission to open the TCP firewall port and grant a Windows URL reservation. Follow the application prompts, including a restart when requested.
The service uses plain HTTP and a default WebHttpBinding. No API key, login, per-command authorization or client IP allowlist is implemented in these services. Reachable clients can issue playback and measurement commands. Restrict network access to trusted clients. Windows URL reservations authorize the server process to listen; they do not authenticate API callers. No HTTPS or CORS configuration is supplied by this host. Browser cross-origin access is not a promised interface.
Requests and responses
All routes below use GET, including commands that change state. Append each route to its service base URL. No request body or query parameter is declared. Placeholders in braces are required path segments unless the route explicitly describes the overlay stop wildcard. Do not send the braces literally.
Responses use WCF JSON serialization and a common object:
| JSON field | Type | Meaning |
|---|---|---|
status | integer | Application status from the table below. |
message | string or null | Diagnostic text; not a stable identifier. |
result | route-specific value | Boolean, string, object, array or null. |
| Value | Identifier | Meaning |
|---|---|---|
0 | OK | No application error reported. |
1 | COUNTER_NOT_EXIST | Defined in the shared enum; not returned explicitly by these routes. |
2 | TIMER_NOT_EXIST | Defined in the shared enum; not returned explicitly by these routes. |
3 | INTERNAL_ERROR | Request processing failed. |
4 | PLAYLIST_NOT_FOUND | No available playlist matched. |
5 | INVALID_ARGUMENT | Invalid sequence index, empty playlist start, or non-integer brightness. |
6 | SEQUENCE_NOT_FOUND | No available overlay matched. |
7 | SERVICE_NOT_READY | Player control unavailable or shutting down, or brightness controls unavailable. |
Application errors are returned in this envelope without explicitly changing HTTP status. A normal serialized application error therefore remains an HTTP success response. Always inspect status, then the expected result. A transport or WCF routing error can have a different body and must not be parsed as a guaranteed envelope. Tests expect HTTP 404 for an unknown route and 405 for an unsupported method; these expectations were not verified against a running host for this reference.
For boolean commands, status: 0 and result: true mean that the command path was processed. They do not prove successful audiovisual output or completion of a transition. Some downstream methods catch errors or do nothing when no render exists. Query get_reproduction_state after a command and wait for the intended state with a client-defined timeout. There is no command ID, completion endpoint, push notification, or specified transition deadline. Do not repeatedly send a command while waiting for its effect.
Except for ping, player operations pass through the control window dispatcher when available. This serializes their control access on the UI thread, but does not make separate HTTP requests an atomic transaction. Statistics operations do not use this player dispatch helper.
Player routes
All paths in this table are relative to /ws/remoteplayer/.
| GET route | Successful result | Effect or query |
|---|---|---|
ping | boolean true | Checks that the service answers; does not check render readiness. |
get_instance_name | string | Configured instance name; can be empty. |
list_playlists | array of PlaylistInfo | Available playlists in collection order. |
list_playlist_sequences/{playlist_name} | array of SequenceInfo | Sequences in playlist order; indices start at zero. |
list_overlay_sequences | array of SequenceInfo | Available always-on-top overlay sequences. |
get_reproduction_state | ReproductionState | Current control and render state. |
start_playlist/{playlist_name} | boolean | Starts the selected playlist, including quick action playlists. Empty playlists are rejected. |
start_sequence/{playlist_name}/{sequence_number} | boolean | Starts the selected existing sequence. |
start_aot_sequence/{sequence_name_or_file} | boolean | Starts the selected always-on-top overlay over the background. |
start_aot_sequence/* | boolean | Wildcard stop handler. Use start_aot_sequence/ to remove the overlay; retain the trailing slash. Do not send a literal asterisk. |
stop | boolean | Calls the player stop operation. Query state to confirm playback stopped. |
pause | boolean | Pauses if the render is not already paused. |
resume | boolean | Resumes if the render is paused. |
pauseresume | boolean | Toggles render pause state. |
play_next | boolean | Starts the next sequence; wraps from last to first. Does nothing without an active sequence and playlist. |
quick_action_exit | boolean | Requests exit when the render is in quick action mode; otherwise does nothing. |
set_global_brightness/{brightness_tpc} | boolean | Sets every available brightness matrix value to the supplied percentage divided by 100. No HTTP brightness query is defined. |
The named overlay route is more specific than the wildcard. A nonexistent overlay name returns SEQUENCE_NOT_FOUND; it is not a stop request. Empty-tail wildcard routing and other encoded path edge cases still require host validation.
Parameters
| Parameter | Type and rules |
|---|---|
playlist_name | Required string. Matches the exact playlist name or the basename of its definition file, including extension. Matching is case-sensitive and returns the first match in the available collection. A full definition path is not a playlist lookup key. |
sequence_number | Required signed 32-bit integer parsed with invariant culture. Must be between 0 and sequence_count - 1. Negative, non-integer, overflow and out-of-range values return INVALID_ARGUMENT after playlist lookup. A missing playlist returns PLAYLIST_NOT_FOUND first. |
sequence_name_or_file | Required string for overlay start. Matches the exact overlay name, stored file value, or file basename. Matching is case-sensitive and returns the first match. Prefer names or basenames for URLs. |
brightness_tpc | Required signed 32-bit integer text. Numeric values are clamped to 0 through 100 percent. Non-integers and overflow return INVALID_ARGUMENT. Parsing uses the server's default integer culture. Use plain decimal digits with an optional sign. |
Percent-encode each string path segment as UTF-8. For example, Demo Show becomes Demo%20Show; encode a literal + as %2B, # as %23, ? as %3F, and % as %25. Do not encode the separators between route segments. URL helpers use Uri.EscapeDataString for launch references. Encoded slashes, backslashes and full filesystem paths can be affected by the Windows HTTP stack and are not verified here. Prefer a unique name or basename without path separators. Missing required segments can fail WCF routing before application validation.
Player data
The field names below are exact JSON contract names. Object property order is not significant. File fields contain stored references and can expose filesystem information; do not assume that they are public download URLs.
| PlaylistInfo field | Type and meaning |
|---|---|
name | string; playlist name. |
filename | string; stored playlist definition file reference. |
is_quick_action | boolean; playlist interrupt flag. |
has_button | boolean; quick access button flag. |
button_color | object; WCF color members A, B, G, R (byte channels, 0–255) and ScA, ScB, ScG, ScR (floating-point scRGB channels). This is not a CSS string. |
sequence_count | integer; number of sequences. |
| SequenceInfo field | Type and meaning |
|---|---|
name | string; sequence name. |
filename | string; stored sequence file reference. |
is_on_top | boolean; true for overlay listings, false for playlist sequence listings. |
| ReproductionState field | Type and meaning |
|---|---|
is_playing | boolean; an active playlist exists. Does not establish visible output. |
is_paused | boolean; control pause state. |
is_render_active | boolean; render active flag, false without a render. |
is_quickaction | boolean; an active playlist and a render in quick action mode exist. |
current_playlist | string; active playlist name, otherwise empty. |
current_playlist_file | string; active playlist definition reference, otherwise empty. |
current_sequence | string; active sequence name, otherwise empty. |
current_sequence_index | integer; zero-based active sequence index, otherwise -1. |
current_overlay_sequence_name | string; active overlay name, otherwise empty. |
current_overlay_sequence_file | string; active overlay file reference, otherwise empty. |
current_sequence_elapsed_time | string; elapsed sequence counter multiplied by 1000, in milliseconds. |
current_sequence_total_time | string; sequence duration in milliseconds, truncated toward zero. |
Time values are JSON strings, not numbers or formatted time spans. Both time fields are "0" without an active sequence. Their interpolation uses the server culture; do not assume an invariant decimal separator or millisecond measurement precision. File/name values copied from the model can be null. An application error can return null, empty or partially populated results; check status before using them.
onTV routes and data
All paths in this table are relative to /ws/statsmeter/. Keep the spelling mesures exactly as shown.
| GET route | Successful result | Effect or query |
|---|---|---|
start_on_tv_interval | OnTVInterval | Opens a measurement interval; an already open interval is retained. |
stop_on_tv_interval | OnTVInterval | Closes the last interval if open. |
state_on_tv_interval | OnTVInterval | Returns the last interval, including a closed interval. |
get_all_intervals_on_tv | array of OnTVInterval | Returns the render meter's interval list. No pagination or date filter is declared. |
get_mesures_statistics | TransmissionStatistics | Counts and totals completed intervals. |
These commands mark measurement periods. They do not start or stop playlist playback and do not detect a broadcast signal. The controller returns a default interval, or an empty list for the list operation, when no render exists. A render without a statistics meter can return null; start and stop then encounter the service logging dereference and report an internal error. This can be an OK response without an actual measurement.
| OnTVInterval field | Type and meaning |
|---|---|
begin | WCF JSON DateTime string; interval start. |
end | WCF JSON DateTime string; interval end. |
The unset marker is a date with year 1970, initialized as January 1, 1970. An open interval has an unset end. No recorded interval produces a default object with both dates unset. Repeated stop leaves a closed interval unchanged. Dates originate from DateTime.Now on the server. WCF uses the /Date(milliseconds[+or-offset])/ representation, with possible JSON slash escaping; it is not an ISO 8601 contract. The optional offset and the local/unspecified DateTime handling must be checked on the deployed host. Do not interpret the sentinel as a real measured timestamp.
| TransmissionStatistics field | Type and meaning |
|---|---|
intervals_recorded | integer; count where both begin and end years differ from 1970. |
total_seconds_in_tv | integer seconds; sum of completed interval milliseconds, converted to a 32-bit integer, then divided by 1000 and rounded with Math.Round. Open intervals are excluded. |
The millisecond accumulation uses a 32-bit integer conversion before rounding. Long histories can exceed that range. Do not treat this as an unlimited precision duration counter or as a guaranteed lifetime history across restarts. Statistics catches report INTERNAL_ERROR; their message can remain null.
Examples
All requests and JSON values in this section are illustrative. The host, names and file references are placeholders with no private data. Responses are complete envelopes unless described otherwise. Property order and JSON whitespace can differ.
Check availability from the player computer when the configured port is 8083:
curl "http://127.0.0.1:8083/ws/remoteplayer/ping"
{"message":null,"result":true,"status":0}
List sequences in an available playlist named Demo Show:
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}
Start its first sequence, then query state. These are two separate requests:
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"
Illustrative command response:
{"message":null,"result":true,"status":0}
Illustrative state response after the transition:
{"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}
An invalid sequence index in an existing 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}
A missing playlist query:
{"message":"Playlist [Missing] not found.","result":[],"status":4}
Start an overlay named Demo Overlay, then remove it:
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/"
Set global brightness to 50 percent:
curl "http://127.0.0.1:8083/ws/remoteplayer/set_global_brightness/50"
Open, inspect and close an onTV interval, then read totals:
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"
Illustrative statistics response after one completed five-second interval:
{"message":null,"result":{"intervals_recorded":1,"total_seconds_in_tv":5},"status":0}
Limitations
This is a source-reviewed reference, not a report of live requests. A standalone .NET Framework WCF serializer check confirmed the color member names, but this was not a live HTTP response. Date offsets, wildcard routing, HTTP error bodies and deployment-specific access require validation on the target installation.
No rate limit, client isolation, request transaction, general idempotency guarantee or audiovisual completion guarantee is implemented by this API layer. Commands use GET, so link previewing, prefetching, caching and automatic retries can be unsafe for commands. Use a client that sends requests only when intended and does not reuse cached query responses. The server code does not establish a cache-control contract.
The onTV HTML interface, WCF metadata and mex endpoints are separate from the JSON operations documented here. They are not additional player command routes. No upload, playlist editing, file download, brightness readback or event subscription operation is declared in these two JSON contracts.