What is a script?

Information showing in DISE movies and templates may be the result of a script. 

A script is a file containing Python (.py), JScript (.js) or VBScript (.vbs) code, which is started by the DISE playback engine. Scripts may interface with DISE by using DISE library functions. 

Scripts for movies are set up in DISE Composer and will be distributed to a DISE Premium player together with a DISE Movie. 


We recommend using Python for all scripting.


TABLE OF CONTENTS


Setting scripts in Composer

The recommended way to set a script in Composer is to select Movie tab > Edit scripts.

This opens up a new dialog to set scripts for the movie. Click the Add button to browse for script files to run. 


We differentiate between three kinds of scripts; load scripts, background scripts or event scripts.

  • Load scripts are set to run before scene resources (images, etc) are loaded (put in cache). They are executed in list order.
    Please note that the playback will not wait for load scripts to finish executing, and may terminate script execution if it takes too long - the default stop timeout is 30 seconds.
    The DISE playback engine will keep track of how long a script took to run in order to try to optimize script start time.
  • Background scripts will run independently (asynchronously) in the background.
    The background script start to run the first time a template is played, the background python thread will keep running until the template is removed from the playlist.
    These scripts do not have a stop timeout. However if they exit by themselves they will eventually be restarted.
    If two or more template messages are running, only one instance of the background script will start. There is a python method DISEScript.GetState() to see the status of the playback which is handy to know when to quit, for example in infinite loops (see below)
  • Event scripts are run for example on a click event. These scripts are not set up as above, but instead in each scene or object's Events dialog.


Writing scripts

DISE library

The DISE library provides access to methods to interface with DISE. The available methods are:


DISEScript.Log([optional]string loglevel, string message)

Logs a message to DISE portal.

If loglevel is specified, it needs to be one of:

  • debug
  • info
  • notice
  • warning
  • error
  • critical
  • alert
  • emergency


DISEScript.Sleep(integer x)

Delays the script execution by x milliseconds.

DISEScript.GetState(integer x)

If the script is running, will return Normal , if it is not running, Terminated.


DISEScript.GetDatafeed(string name, [optional]string mediatype)

Queries the portal for a datafeed with the given name and returns its value.

If mediatype is specified, will only search for datafeeds of that mediatype.

Valid mediatypes are:

  • text
  • text/plain
  • image
  • image/*
  • video
  • video/*

DISEScript.GetVariable([optional]string scope, string name)

See also Variables.

Queries the portal for a variable with the given name and returns its value. If the variable is nonexistant, an empty string is returned.

If 2 parameters are provided, the first parameter is interpreted as the scope of the variable. The possible scopes are:

  • global
    The default for background scripts.
  • local
    The default for load scripts. Variable will only be visible to the containing movie/template.

DISEScript.SetVariable([optional]string scope, string name, string value)

See also Variables.

Sets a variable in the portal.

If 3 parameters are provided, the first parameter is interpreted as the scope of the variable. The possible scopes are:

  • global
    The default for background scripts.
  • local
    The default for load scripts. Variable will only be visible to the containing movie/template.

DISEScript.GetTrigger(string name)

Queries the playback engine for a trigger with the given name and returns its value as a boolean value.

DISEScript.SetTrigger(string name, boolean value)

Sets a trigger in the portal with the name provided.

DISEScript.ToggleTrigger(string name)

Sets the trigger in the portal, setting its value to true if it is already false, and to false if it is true.


bool DISEScript.Back()

Sends a back command to all currently playing playlists on the player.


bool DISEScript.Back(string name)

Sends a back command to the currently playing playlist with the provided name on the player.


bool DISEScript.Forward()

Sends a forward command to all currently playing playlists on the player.


bool DISEScript.Forward(string name)

Sends a forward command to the currently playing playlist with the provided name on the player.


string DISEScript.Action(string name, string parameter1, string parameter2)

Custom actions 

Will return the result of the action.

Supported actions are:

  • UpdateFile
    Triggers a file update.
    parameter1 is the destination file, parameter2 is the source file.
    If source is omitted the destination file is reloaded.
    Source file will be removed if specified.
  • TakeOver
    Creates a new layer for a specific media, playing once.
    All other material is paused during this playback.
    parameter1 is the file path, parameter2 is the media type.

DISEScript.Exit()

Immediately exits the currently running script (will continue with the next script if multiple scripts are defined)


Python

Python scripts are written in normal .py files, with a few exceptions: 

  1. Specify the script host engine to use, in the first row of the file:
    #pragma language Python.AXScript.2

  2. You may use #include statements to have other .py files included:
    #include "otherfile.py"

  3. You may use the DISE library methods (see section "DISE library" above) to access various DISE functionality.


Install Python


Mocks

If you need to test your Python scripts outside of DISE, feel free to use this stub in place of the DISE library: 

class DISEScript:
    @classmethod
    def Log(*x):            return "Log"
    @classmethod
    def Sleep(*x):          return "Sleep"
    @classmethod
    def GetDatafeed(*x):    return "GetDatafeed"
    @classmethod
    def GetVariable(*x):    return "GetVariable"
    @classmethod
    def SetVariable(*x):    return "SetVariable"
    @classmethod
    def GetState(*x):       return "GetState"
    @classmethod
    def GetTrigger(*x):     return "GetTrigger"
    @classmethod
    def SetTrigger(*x):     return "SetTrigger"
    @classmethod
    def ToggleTrigger(*x):  return "ToggleTrigger"


JScript

JScript scripts are written in normal .js files, with a few exceptions: 


  • The first row in the file must specify the script host engine to use:
    #pragma language JScript
  • You may use #include statements to have other .js files included:
    #include "otherfile.js"


Mocks & polyfills

If you need to test your JScript scripts outside of DISE, feel free to use this stub in place of the DISE library:

var DISEScript = {
    Log :           function() { return "Log"},
    Sleep :         function() { return "Sleep"},
    GetState :      function() { return "GetState"},
    GetDatafeed :   function() { return "GetDatafeed"},
    GetVariable :   function() { return "GetVariable"},
    SetVariable :   function() { return "SetVariable"},
    GetTrigger :    function() { return "GetTrigger"},
    SetTrigger :    function() { return "SetTrigger"},
    ToggleTrigger : function() { return "ToggleTrigger"}
};

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf#Polyfill


VBScript

JScript scripts are written in normal .vbs files, with a few exceptions: 


  • The first row in the file must specify the script host engine to use:
    #pragma language VBScript
  • You may use #include statements to have other .vbs files included:
    #include "otherfile.vbs"


Scripts on events

Scripts can be triggered on events which can be added to a scene in Composer (More information here) or you can add an event using interactivity (More information here). 

These scripts by default have a global scope, so are visible to any movie / template currently playing.

As an example, below I add an image to Composer and then set the script to trigger whenever the image is clicked. 



Settings

When the "Run script" command is selected in the Event settings you are able to modify how the script will run. 



  1. Browse for the script on your PC. The script will be sent along with the DISE Movie and content.
  2. Playback, loading etc. will not continue until the script has finished executing.
  3. The amount of time you want to wait for the script execution before timing out.


Scripting example


Step by step instructions for Weather in Composer. 

  1. Copy the script text found below to a text file and name it "weather.py"
  2. Create an account on https://darksky.net/dev and retrieve an API key.
    Please also read up on the Dark Sky Terms of Service before using the API.
  3. Make sure that you have Python installed, as described in the "Install Python" above
  4. Run "pip install darkskylib" from a command prompt.
  5. Edit the weather.py file and replace 
    1. APIKEY in the script with your API key. 
    2. 59.378333, 13.504167 with your location in decimal form.
  6. In Composer, select Movie tab > Edit scripts.
  7. Click the Add button next to Load scripts and browse to the script file.
  8. Create two text fields and connect them to the variables in the script. See image below for for instructions.
    type in "#VAR#" followed by the variable name. For example, the variable "weather.summary", set in the script below, would be data connected as #VAR#weather.summary.
  9. You should now be able to "Play all scenes" and see the result.



from darksky import forecast
from datetime import date, timedelta
LOCATION = 59.378333, 13.504167
icon_by_category = {
  "clear-day":"1",
  "clear-night":"2",
  "rain":"8",
  "snow":"#",
  "sleet":"$",
  "wind":"F",
  "fog":"M",
  "cloudy":"Y",
  "partly-cloudy-day":"3",
  "partly-cloudy-night":"4"
  }

weekday = date.today()
with forecast('APIKEY', *LOCATION, lang='en', units='si') as location:
  temperature = int(round(location.currently.temperature))
  category = location.currently.icon # clear-day, clear-night, rain, snow, sleet, wind, fog, cloudy, partly-cloudy-day, or partly-cloudy-night
  DISEScript.SetVariable("weather.temperature", str(temperature))
  DISEScript.SetVariable("weather.summary", location.currently.summary)
  DISEScript.SetVariable("weather.icon", icon_by_category.get(category,")"))


Troubleshooting


Integrations