Player and Cloud Extender APIs

Player and Cloud Extender APIs

Splash Player and Cloud Extenders can be queried by external processes in order to obtain its status, perform diagnostics or alter its playback. This communication occurs via TCP over the port specified in the Player.exe.config file and are case insensitive.

Splash Player

The details of the possible queries are listed below:

Splash Player API Commands

Command Description
Info Deprecated: use PlayerInfo instead. Info returns basic information about the player, such as its MAC address and Last Check In time.
Interrupt

Allows the immediate interrupting of the normal playback, replacing the currently playing Design with something else. The result depends on which interrupt code is sent:

  • 0 – Regular playback
  • 1 – Play a file from the Interrupt bundle set in the Player configuration
  • 2 – Play an empty black screen
  • 112 – Display diagnostics information
  • Semicolon – This is required between the command and code: for example, interrupt;1

Note: See Specify a Second Parameter for Interrupts.
Takeover

Allows to control Event-Based Takeovers. The command needs an action command and a trigger Guide code, separated by semicolons. The trigger code is necessary and is displayed in the Takeover section of the takeover campaign. Actions available:

  • Start: Starts the takeover.
  • Stop: Stops the takeover before it completes.

Example: takeover;start;42595db1-92fb-499b-bc23-8745846d5551
NetworkInfo Retrieve network information about the player (see Player API Response Structure).
PlayerInfo Retrieve general information about the player (see Player API Response Structure).
PlayoutInfo Retrieve playout information about the player (see Player API Response Structure).
Shutdown Forces the player to shut down immediately.
Restart Force the player to restart.
Uptime Returns how long the player has been running.
LastPlayTime Returns the time when the last Design finished playing.
CheckIn

Triggers a player check-in. The type of check-in depends on the parameter passed:

  • Network – Network check-in (for regular content, tasks, configuration, face assignment).
  • Deployment – Player Updates (New version of player, CEF, MPV), Push IP address and other values.
  • Forward – Forward and Store and Forward and Play content from FTP servers.
  • Emergency – Emergency Messages.
  • Dynamic – Dynamic content on top of images.

Multiple parameters can be sent at once, they need to be separated by semicolons. If no additional parameter is added, all check-ins are triggered at once.

Examples:

checkin – Triggers all check-ins.

checkin;network;forward – Triggers Forward and Store check-in after a regular check-in.

Cloud Extender

Command Description
Info Deprecated: use CloudExtenderInfo instead. Info returns basic information about the cloud extender, such as its MAC address and Last Check In time.
NetworkInfo Retrieve network information about the cloud extender (see Cloud Extender Response Structure).
CloudExtenderInfo Retrieve general information about the cloud extender (see Cloud Extender Response Structure).
Shutdown Forces the cloud extender to shut down immediately.
Uptime Returns how long the cloud extender has been running.
CheckIn

Triggers a player check-in. The type of check-in depends on the parameter passed:

  • Network – Network check-in (for regular content, tasks, configuration, face assignment).
  • Deployment – Cloud Extender Updates (New version of cloud extender), Push IP address and other values to fill the cloud extender’s Basic Info page.
  • Forward – Forward and Store and Forward and Play content from FTP servers.
  • Dynamic – Dynamic content on top of images.

If no additional parameter is added, all check-ins are triggered at once.

Examples:

checkin – Triggers all check-ins.

checkin;network;forward – Triggers Forward and Store check-in after a regular check-in.

Every output from the Player API is returned in JSON format.

NetworkInfo Response:

Field Type Description
LastForwardAndStoreRefreshUtcTime DateTime Specific UTC date and time of the last refresh of forward and store content.
LastPlayoutCheckInUtcTime DateTime Specific UTC date and time of the most recent player check in.
LastEmergencyMessageCheckIUtcTime DateTime Specific UTC date and time of the most recent player check in for emergency messages.
DownloadQueue List of FileDownload MonitoringInfo

List of FileDownloadMonitoringInfo objects that includes:

  • FileName: String
  • Type: String (possible values are Media, ForwardAndStore, Programmatic, Update, Other)
RetryDownloadQueue List of FileDownload MonitoringInfo

List of List of FileDownloadMonitoringInfo objects that includes:

  • FileName: String
  • Type: String (possible values are Media, ForwardAndStore, Programmatic, Update, Other)

PlayerInfo Response:

Field Type Description
LocalUtcTime DateTime The player's local UTC time.
StartedSinceUtcTime DateTime The specific UTC date and time of last start.
Version String The player software version.

HardwareKey

 String The computed hardware key. This is computed from all the different MAC addresses active on the player.
PrimaryMACAddress String Primary network MAC address.

PlayoutInfo Reponse:

Field Type Description
Faces FaceMonitoringInfo Array

FaceMonitoringInfo Structure:

Field Type Description
FaceID GUID Unique identifier for the face
X Int Display coordinate X axis
Y Int Display coordinate Y axis
Width Int Width in pixels
Height Int Height in pixels
Zones ZoneMonitoringInfo Array

ZoneMonitoringInfo Structure:

Field Type Description
ZoneID GUID In the case of a single zone, the Zone ID will be that of the Face ID. When there is more than one zone on the face, each zone will have its own unique identifier.
EnableSynchronization Bool Indicates if the zone is synchronized with zones on other players or another zone on the same player.
IsSyncGroupMaster* Bool Indicates whether this zone is the leader for follower zones.
SynchronizationGroupName string The zone sync group name.
X Int Display coordinate X axis
Y Int Display coordinate Y axis
Width Int Width in pixels
Height Int Height in pixels
IsOutsideOperatingTimes bool Indicates if it is within the zone's operating time.
IsPlayingOverridingEmergencyMessage Bool Is the spot currently playing an Emergency Message overriding the loop content.
LastPlayUtcTime String Specific UTC date and time of the last complete play.

* Please note that we are in the process of changing the terminology in the platform to "IsSyncGroupLeader".

Every output from the Cloud Extender API is returned in JSON format.

NetworkInfo Response:

Field Type Description
LastForwardAndStoreRefreshUtcTime DateTime Specific UTC date and time of the last refresh of forward and store content.
DownloadQueue List of FileDownload MonitoringInfo

List of FileDownloadMonitoringInfo objects that includes:

  • FileName: String
  • Type: String (possible values are Media, ForwardAndStore, Programmatic, Update, Other)
RetryDownloadQueue List of FileDownload MonitoringInfo

List of List of FileDownloadMonitoringInfo objects that includes:

  • FileName: String
  • Type: String (possible values are Media, ForwardAndStore, Programmatic, Update, Other)

CloudExtenderInfo Response:

Field Type Description
LocalUtcTime DateTime The cloud extender's local UTC time.
StartedSinceUtcTime DateTime The specific UTC date and time of last start.
Version String The cloud extender software version.

HardwareKey

 String The computed hardware key. This is computed from all the different MAC addresses active on the cloud extender.
PrimaryMACAddress String Primary network MAC address.

A second parameter can also be specified. The second parameter is a guid: interrupt;1;<guid of the bundle to use for interrupt> ... this is optional.

If it is not specified, the bundle specified in Splash for the interrupt bundle will be used.

These queries can be tested with software that can send TCP messages like Packet Sender.

If Packet Sender is installed on the player, the host is localhost and the port is by default 7185 unless it has been modified in the player.exe.config

See Also: