Player Simulator
  • 30 Aug 2024
  • 5 Minutes to read

Player Simulator


Article summary

This guide is for the Dise One playout engine only. Please reference other guides for Dise Premium & Dise Lite.

Your content goes here

This document describes how to set up a test and debug environment for Dise templates.

The Player Simulator is a light-weight implementation of the Dise Player API, suitable for running and debugging templates in a stand-alone environment, i.e. outside of the normal CMS/Player system. The dynamic data which would normally come from the CMS needs to be provided in local “mock” files.

Prerequisites

A suitable IDE is recommended:

  • Visual Studio Code.

  • Visual Studio.

  • any other IDE which supports TypeScript debugging.

Debugging directly in a browser is possible, but not recommended if a proper IDE experience is available.

Template Test File Structure

Template repositories usually have this structure (with a single template, called “testTemplate” here):

Index.html

our launcher-file

PlayerSimulator/

PlayerSim – an ES6-module in later versions of the framework

TemplateFramework/

a Git-link to TemplateFramework as a SubModule

testTemplate/

our template

template.html

our template main-file for release

debug.html

our template main-file with any development-changes

any other files

MockData/

content.json

mock Playlist

settings.json

template settings we would usually get from the CMS

attributes.json

any initial attributes for testing

           …

any test-assets, like videos or images

The formats of the various files are described below.

Settings.json

The settings.json file is used to define settings which would normally be found in the manifest file (template.json) when the template is added to and used from the CMS.

An example of a minimal settings.json:

{
    "settings": {
        "targetWidth": 1920,
        "targetHeight": 1080
    }
}

(defaults to allowReuse: true and scalePlayer: false)

In most cases, a fallback-duration should be set, allowReuse, and scalePlayer:

{
    "id": "",
    "name": "Test Template",
    "settings": {
    "defaultDuration": 15,
    "targetWidth": 1920,
    "targetHeight": 1080,
    "allowReuse": false,
    "scalePlayer": true
    }
}

Content.json

The content.json file contains the mock playlist with content item(s) for testing the template. It is a simple JSON array with “any” objects:

[
    {
        "text": "Hello world!",
        "someFile": {
            "url": https: //foo.bar.com/image.jpg
        }
    },
    {
        "text": "Status update",
        "someFile": {
            "url": https: //foo.bar.com/status.png
        }
    }
]

When the template is used, this data will be provided by the CMS, in the same format.

The template should check the format and data and handle any errors.

Attributes.json

The attributes.json file may contain any mock attributes (tags and triggers) to pass to the template as metadata.attributes for testing:

[
    {
        "name": "static.MagicEnabled",
        "active": true
    },
    {
        "name": "dyn.Observers",
        "active": true,
        "data": "[\"Zaphod Beeblebrox\"]"
    }
]

Index.html Launcher File

The index.html file is the main entry point for running the template:

<!DOCTYPE html>
<html lang="en">

<head>
    <meta HTTP-EQUIV="Expires" CONTENT="-1" />
    <meta HTTP-EQUIV="Pragma" CONTENT="no-cache" />
    <meta charset="utf-8" />
    <title>Dise Player Simulator</title>
    <script> const templates = { test: { testTemplate: ['testTemplate'], } } </script>
    <script
        type="module"> import { PlayerSimulator } from "./PlayerSimulator/out/PlayerSimulator.js"; // Select template here: const template = templates.test.testTemplate; const players = []; function startPlayer(e) { const props = getProps(template); return new PlayerSimulator(e, props.content, props.settings, props.page); } const start = () => players.push(startPlayer(document.getElementsByTagName('container')[0])); if (document.readyState !== 'complete') document.addEventListener('DOMContentLoaded', () => start(), false); else start(); function getProps(propsA) { if (!Array.isArray(propsA) || !propsA[0]) throw Error('Invalid'); const [folder, relPage, relContent, relSettings] = propsA; return { page: relPage || folder + '/Debug.html', content: relContent || folder + '/MockData/Content.json', settings: relSettings || folder + '/MockData/Settings.json' }; }; </script>
    <style>
        html body {
            margin: 0;
            padding: 0;
            border: 0;
            font-family: sans-serif;
        }

        container {
            display: block;
            width: 100vw;
            height: 100vh;
            position: relative;
            background-color: #ddd;
            overflow: hidden;
        }

        container iframe {
            position: absolute;
            z-index: 1;
            top: 0px;
            left: 0px;
            width: 100%;
            height: 100%;
        }
    </style>
</head>

<body>
    <container></container>
</body>

</html>

The templates object will have references to all templates in the repo for easy testing. The-tuple-syntax for each relative Url allows for overriding the launch-file, content, and settings.

Development in Visual Studio Code

VS Code's built-in debugger can help to accelerate your development and debug loop. You can set up the debugger in VS Code by installing two extensions:

  • Debugger for Chrome

  • Live Server

  1. Launch Live Server by right clicking index.html launcher-file in the root directory.

  2. Navigate to VS Code debugger and create a config file in VS Debugger by clicking the "Run and Debug" button. Select Chrome as a development environment. Replace "url": with the link in the browser http://127.0.0.1:5500/Index.html. Note that port “5500” can vary depending on the local setup.

    Or paste this snippet in the config file:

  1. Compile template and set it to watch/live-reload by cd (your template-folder), then tsc -p . -w command in the terminal/cmd/shell.

  2. Set a breakpoint and run the VS Code debugger.

Development in Visual Studio

  1. Install the TypeScript Tools extension. If you use LESS/SASS, also install the WebCompiler extension.

  2. Add a Web project with the relevant files. There are multiple project types to do this – check the Microsoft documentation.

  3. Set the HTML file which hosts PlayerSimulator as the Start Page; set a break-point in the template and press F5.

Building a Release ZIP file

Once developed, tested, and debugged the template in PlayerSim, the next step is to build a production release ZIP file which can then be uploaded to the CMS. See Adding new templates for more information about the structure of the ZIP file.

To easily automate creation of these ZIP files, the folder and file structure is standardised as follows:

testTemplate/

our template

template.html

our template main-file for release

template.js

our template code file, generated by the TypeScript compiler

css/

template.min.css

our template CSS file, generated by the LESS preprocessor

assets/

all files in this folder are included

fonts/

all files in this folder are included

editor/

all files in this folder are included

deployment/

template.json

the manifest file

The release ZIP file is then built using a Node.js script, which is provided as part of the Player Simulator.

The package.json file looks as follows:

"scripts": {
    "build-testTemplate": "cd testTemplate && tsc -p . & lessc css/template.less css/template.css & lessc --clean-css css/template.less css/template.min.css",
    "zip-testTemplate": "node build/zipDiseTemplate.js testTemplate testTemplate.zip"
}

To build the ZIP file:

npm run zip-testTemplate

The ZIP file is then created in the deployment folder.



Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.