The Playback Simulation API provides a way to preview what will display in the future based on the evaluation of item conditions in a sequence and then simulating playback.
Time is artificially progressed to provide an itemised list of items that will play in the near future based on the current state of the system.
The functionality of the Playback Simulation API mirrors that of the Reports > Playback simulator option within the Admin Interface and offers a programmatic way to obtain the results for presentation or other purposes.
Warning
The simulator provides a prediction of what will display. This prediction should be treated as such because the state of the system is continuously changing and the flexibility of the programmatic digital signage system introduces many non-deterministic features.
Some important points to remember:
- The simulator assumes all content is fully downloaded. If a local player is missing content for a slot, the slot will be skipped. The server does not know what specific items will be available at a given time, however, if items are known to be missing a warning will appear in the info section of the JSON response.
- The simulator assumes all conditional logic is deterministic. Conditions containing functionality such as random can not be predicted by the simulator. Likewise, conditions that rely on variables that change during playback will not be accurate.
- The simulator assumes that playback suffers no delays due to buffering or incorrect playback rates. Many devices introduce pauses of up to 1 second before starting playback of high resolution videos. This delay is not known or predicted in the simulator.
Playback Simulation API Endpoint
A HTTP GET request must be sent to the following address:
/api/simulate-screen/[SCREEN-ID]
Where SCREEN-ID is the screen ID (MAC address) of the screen to simulate playback for. The current data associated with the screen will be used to evaluate conditions in the sequence currently selected for the screen.
Individual sequences can also be simulated using the following address:
/api/simulate-sequence/[SEQUENCE-ID]
The query string for the sequence can include data values that will be used when evaluating conditions. For example ?time=1577836800000 could be included to simulate starting playback at 1st Jan 2020.
When display reporting is available and the most recent (loop unique) display report record is within the last hour, this time and item will be used as the starting point for the simulation. Otherwise the current time will be used.
Playback Simulation API Response
The Simulation API returns a JSON response with the following structure:
"result": [] // List of items that played in the simulation
"info": [] // Information and warnings about the simulation
Additional information available:
"data": {} // Snapshot of current data used for evaluating conditions
"sequenceStack": {} // Snapshot of sequences that are referenced
"blobstoreHttpEndpoint": // Location where media can be accessed (append Blob ID)
"blobstoreHttpsEndpoint": // Location where media can be accessed securely (append Blob ID)
"activeStorage": // The data consumed by items that played
"totalStorage": // The total data consumed by all items including those that were skipped
Each result in the result array contains the following information:
"startMillis": // The time the item started playing
"sequenceId": // The sequence ID containing the item, useful when inner sequences are used
"item": { } // The item that played
For more information about object structure please refer to RESTful API.