Status API
Introduction
The Status API provides read-only access to the current status of a player. It returns information such as device identification, operating status, rendering statistics, file errors, time and network configuration, display settings, storage information, content pull scheduling, firmware version, and licensing details in XML format. A JPEG snapshot of the currently rendered content can also be requested.
For frequent monitoring, prefer the RPC API where applicable. Generating full status XML or snapshots consumes CPU resources and may affect rendering smoothness if requested too often. To retrieve the current player configuration, use the Configuration API.
Authentication
The access to the Status API is protected. Authentication is done using the credentials of users defined in Control Center, with "monitoring" or "admin" rights.
| Player | User rights | Authentication |
|---|---|---|
| DSOS players | monitoring, admin | HTTP Basic, TLS-SRP |
| HMP200, HMP130, HMP100 | monitoring, admin | HTTP Basic |
Using AJAX
AJAX calls can be employed within web pages to get information from the Status API. If the script is loaded from the player content server, then the authorization is done when logging onto the player. If the script is located on another host (CORS), then you need to manually enter the credentials in the browser's pop-up dialog when asked or include the credentials through the "Authorization" header (see the example below).
To protect the player against CSRF when using CORS, the spx-api-key query string parameter must be appended to the end-point and set to the API Key value configured on that player (from Control Center ⇾ Advanced Applications ⇾ APIs Security, or by using the <rpc-api-key> configuration tag).
Notes:- CORS (cross-origin resource sharing) and CSRF (Cross-site request forgery) protection are supported for the Status API starting with DSOS 4.5.3.
- It is possible to configure manually the same API key for different devices, so that the same script can be used for any of them.
Endpoints
The Status API base URL is http(s)://Player_address/status with two endpoints: /info and /snapshot.
Note:info
GEThttp(s)://Player_address/status/info
- Returns an XML response containing the current status of the player.
GEThttp(s)://Player_address/status/info?offset=-HH:mm:ss
GEThttp(s)://Player_address/status/info?offset=date
- Returns an extended XML response containing the current status of the player and the evolution of the temperature and rendering stats of the player. The
offsetparameter can be a negative time period (-HH:mm:ss) or a date. Note that the maximum period is 24h and no more than 100 entries are retrieved, whichever comes first.
Response
The result is an XML document having the following structure:
<?xml version="1.0"?>
<status xmlns="http://www.spinetix.com/namespace/1.0/spxstatus" xmlns:spxs="http://www.spinetix.com/namespace/1.0/spxstatus" spxs:version="5">
<device>...</device>
<status>...</status>
<stats>
<sample>...</sample>
</stats>
<fileErrors>...</fileErrors>
<time>...</time>
<network>...</network>
<screen>...</screen>
<storage>...</storage>
<storagedevices>...</storagedevices>
<version>...</version>
<uploader>...</uploader>
<license>...</license>
</status>
where:
<device> Contains information about the device.
<name>→ model name,<serial>→ serial number,<ethmac>→ MAC address,<revision>→ hardware revision.
<status> Contains information about the operating status.
<safemode>→ the Safe mode status (on / off).<firmware>→ the firmware update status, from the following:- complete - the update was complete, or the update check does not detect any available updates.
- available - there are updates available.
- pending - some packages have been updated, but a new run is needed to complete the update process.
<bootid>→ an unique boot ID,<uptime>→ device uptime,<bootReason>→ the reason of the last boot,<temp>→ device internal temperature (this is not available on HMP130 / HMP100).
<stats><sample> Current device stats - see more details about these on player.log section.
<time>→ the time of the stats sampling,<render>→ the total rendering time,<pictures>→ the number of rendered pictures (frames) within the sampling period (usually 1 min).<usage>→ usage stats,<peak>→ peak stats,<buffers>→ buffers stats,<dropFPS>→ FPS drop stats,<dropPeak>→ peak drop stats.
<fileErrors> Contains information about file errors.
<error>→ file error details (time, code, source, description).
<time>
<date>→ the current date and time<timezone>→ the configured time zone.<GMTOffset>→ the GMT offset of the configured time zone.
<network> Contains information about the network configuration.
<deviceName>→ device name,<hostname>→ device hostname,<ip>→device IPv4 address,<prefixLength><interface>→ the network interface type (Ethernet, WLAN, 3G)<ipv6><ipv6addr>→IPv6 addresses,<secondaryAddresses><address>→ the Ethernet address details when the player is configured for Wi-Fi.<configuration><interface>→ interface type (ethernet, wlan),<method>→ configuration type (dhcp, static).
<screen> Contains information about the screen configuration.
<screenID>→ Multiscreen ID,<snapshotURI>→ URI to get the snapshot,<resolutionWidth>,<resolutionHeight>→ resolution width and height, or unknown<verticalRefresh>→ vertical refresh, or unknown<aspectRatio>→ aspect ratio, or unknown<overscanPercent>→ overscan percent,<orientation>→ display orientation,<powerSave>→ display power save (on / off),<audio><mute>→ audio status (on / off),<display>→ information about the display(s) connected to the player’s video output(s):<id>→ video connector ID (e.g., “card0-DP-1”)<type>→ the type of the display connector (HDMI, DVI, DisplayPort Alt Mod)<power_save>→ the display power save (on / off)<mode>→ information about the video output mode, such as:<colorspace>→ the video output color space, such as: “RGB 4:4;4” or “YCbCr 4:2:0”.<width>,<height>,<refresh>→ resolution<region>→ x1, x2, y1, y2 coordinates of the displayed canvas<hdr>→ information about HDR output (bits per color component, color gamut, and transfer function), if enabled. Applies only to iBX440 players.
<powered>→ the status of the display (on | off | unknown)<pm_supported>→ 0 or 1, tells if power management is supported with the currently attached display; this is a most-likely guess since it is not possible to know for sure<cec_capable>→ 0 or 1, tells if the output has a CEC adapter or not. Added in firmware 4.6.0.
<storage> Contains information about the storage information.
<content>→ information about the storage space of the Local Storage partition,<system>→ information about the storage space of the System partition.
<storagedevices> Contains information about the storage device information.
<storagedevice><location><size><unit>
<version>
<firmware>→ firmware version and build number.<bootloader><version>→ bootloader version.
<uploader> Content pull scheduling information.
<mode>→ the content Pull mode, which can be:- "Disabled" - no content pull,
- "Manual" - pull from a web server,
- "Automatic" - pull according to an ICS file uploaded on the device,
- "Server" - pull according to a remote ICS file.
<projectSource>, <projectTime>→ project source URI and time of pull when mode is manual.<calendar>→ calendar URI when mode is server.
<license> Contains data related to the Feature Set. Added in firmware 4.7.6.
<checkDate>→ the date & time of the check<features>→ license feature details (name, source, etc.), when a Feature Set is currently activated on the player.
Extended response
When the offset parameter is used, the XML response includes more rendering statistics (up to 100 <sample> entries are added under <stats>), as well as the evolution of the player's internal temperature (also capped at 100 entries):
<tempHistory><sample> Contains information about the device temperature.
<time>→ the time of the stats sampling,<C>→ the temperature in degree Celsius,<F>→ the temperature in degree Fahrenheit.
snapshot
GEThttp(s)://Player_address/status/snapshot
- Returns a JPEG image representing the snapshot of the content being rendered.
Note: