Variables

A variable stores a value such as:

name of a media file
vehicle position
current date and time
number of times a button was pressed
which device to control
etc

Name

A variable name can be any valid resource name. The name is used throughout WinScript Live. For example:

In sequence event parameters (such as Set Variable = and Format)
Referenced by remote commands to set or get the value
In watch lists to write value changes to the live log
Assigned to panel items (such as Text and Sliders)

Alias

All variables can have a user defined alias. The alias can be used anywhere the variable name can be used. A few examples of how to use an alias are:

make a short name for a variable used often in the script
simplify access to a specific variable within an array
create a meaningful name for any bit within an integer variable

Type

Each variable has a type. The following table provides a brief summary:

Type	Description	Minimum	Maximum
Bool	true or false	0	1
Date/Time	date and/or time stored as a Unix timestamp
Decimal	real numbers such as 1.5000 or -123.4567	-2147483648.0000	2147483647.0000
Device	a reference to any existing device associated with a protocol
Integer	whole numbers such as -50 or 1234567	-2147483648	2147483647
LCDString	a special string that includes multi-line LCD display info
Percent	0% to 100%	0%	100%
String	typically used for text but may also include special characters and binary data
Timecode	SMPTE/EBU-style (hours:minutes:seconds.frames) at a specific frame rate	-23:59:59.999	23:59:59.999

Initial Value

The initial value of each variable is set only when the controller loads the script. This is most useful for read-only variables.

Edit

Configuration

A variable can sometimes be accessed by its component parts such as array elements or integer bits. The configuration settings for the variable define this behavior.

Zero-indexed

Variable array elements and bits in WinScript are counted starting from 1. Enable the "Zero-indexed" setting to begin counting from 0. This is typically more programmer-friendly but it depends on the intended use of the variable. For example:

To create an array of audio file names called "audioFileName" that starts at 1, leave "Zero-indexed" disabled. The first name can then be accessed directly as audioFileName[1]
To create an integer to track input states called "inputState" that starts at 0, enable "Zero-indexed". The first bit can then be accessed directly as inputState.0

The first bit of an integer value is always the least significant.

Array

Any variable can be used as an array. Enable "Array" with "Array Size" of 2 or more elements. Each element of the array is a variable of the same type.

For example: To track the number of times that 5 different shows have run, create an Integer variable named "showRunCounter" and set the array size to 5. The array elements can be accessed by events such as Get At and Set At, or directly using showRunCounter[1] through showRunCounter[5]

Note: It is also possible to access bits directly from within an array of integers. Either set an alias for the bit or use a full name such as myIntegerArray[1].1 or myIntegerArray[3].2

Additional Options

These options depend on the type of variable.

Read Only

Set the "Read Only" option to prevent the variable from being changed. The Initial Value must be set or the variable will never have a value.

It is only possible to override a read-only variable by enabling a Force Value in the Watch List. The Force Value will remain until it is disabled or the controller is restarted.

Min and Max

Most numeric variables have a default minimum and maximum value. These can be changed for Integer and Decimal variable types to ensure the value never falls outside of a specific range.

Frame Rate

Timecode variables use the same frame rate as the internal clock as the default setting. This can be changed in the script configuration.

Each timecode variable can also be set to a different frame rate to allow conversions between various systems. For example:

A system that tracks time in milliseconds can be converted to the internal frame rate for precise timing of additional events.
An internal clock rate of 60fps can be converted to a media server's playback time at 24fps.

Device

When a variable type is set to Device, it can be used to reference any device of a specific make and model found in the script's device list. The device can then be changed while the script is running using the Set Variable = event.

This is an advanced feature typically used with device arrays such as a fleet of vehicles that have on-board audio or a venue that has multiple projectors of the same model

Converting Variable Types

When using the "Set Variable =" event in a script, it is possible to assign a value of one type to a variable of a different type. For example, an Integer value can be assigned to a String variable, or vice-versa. The value will be automatically converted to the desired type as described below.

The same behavior applies when using an event such as "Add", "Subtract", "Multiply", or "Divide" to modify the value of a variable. For example, adding an Integer value to a Timecode variable will increase the timecode value by a specific number of frames.

Conversion Behavior

The exact result of converting a value from one variable type to another depends on both the type of the original value and the type of the destination variable.

String Variables

Converting an Integer value to a String produces the integer value with surrounding quotes (examples: "0", "1234", "-9999").
Converting a Decimal value to a String produces the decimal value with surrounding quotes and rounded to two decimal places (examples: "0.00", "123.45").
Converting a Percent value to a String produces the percentage value followed by a percent symbol, with surrounding quotes (examples: "0%", "50%", "100%").
Converting a Bool value to a String produces the value "true" or "false".
Converting a Timecode value to a String produces a value in the format "hh:mm:ss.ff" (hours, minutes, seconds, frames).
Converting a Date/Time value to a String produces a value in the format "MM/DD/YYYY hh:mm:ss". Hours are from 00 to 23. All numbers are displayed with leading zeroes.
Converting a Device reference variable to a String produces the name of the device with surrounding quotes (examples: "V16X", "MyProjector").
Converting any other type of value to a String is invalid.

Integer Variables

Converting a String value to an Integer will attempt to parse the string contents as follows:
- If the string represents a valid integer value (examples: "0", "1234", "-9999"), the resulting integer will have the same value.
- If the string is "true", "on", "yes", or "enabled", the resulting integer value is 1.
- If the string is "false", "off", "no", or "disabled", the resulting integer value is 0.
- For any other string value, the result is invalid.
Converting a Decimal value to an Integer discards everything after the decimal point.
Converting a Percent value to an Integer produces the same value without the trailing percent sign (examples: 0, 25, 100).
Converting a Bool value to an Integer produces a value of 0 (false) or 1 (true).
Converting a Timecode value to an Integer produces the total number of frames.
Converting a Date/Time value to an Integer produces a Unix timestamp (number of seconds since midnight UTC on 1/1/1970).
Converting a Device reference variable to an Integer produces the index of the device within the script, starting from 0.
Converting any other type of value to an Integer is invalid.

Bool Variables

Converting any other type of value to a Bool will first convert the value to an Integer as described above ("Integer Variables"). If the resulting integer is 0, the Bool variable's value becomes false. Otherwise, it becomes true.

Decimal Variables

Converting a String value to a Decimal will attempt to parse the string contents as follows:
- If the string represents a valid integer or decimal value (examples: "0.0", "1234.56", "-99.99"), the resulting decimal will have the same value.
- For any other string value, the result is invalid.
Converting a Percent value to a Decimal produces an equivalent scalar value (for example, 0% produces 0.0, and 100% produces 1.0).
Converting any other type of value to a Decimal produces the same result as converting to an Integer ("Integer Variables").

Percent Variables

Converting any other type of value to a Percent will first convert the value to a Decimal as described above ("Decimal Variables"). The resulting decimal value is then converted to a percentage, where 0.0 equals 0% and 1.0 equals 100%.

Timecode Variables

Converting a String value to a Timecode will attempt to parse the string in the format "hh:mm:ss" (hours, minutes, seconds) or "hh:mm:ss.ff" (hours, minutes, seconds, frames).
Converting an Integer value to a Timecode will treat the integer value as a total number of frames.
Converting a Decimal value to a Timecode will treat the decimal value as a fractional number of seconds.
Converting a Bool or Date/Time value to a Timecode will first convert the value to an Integer as described above ("Integer Variables"). The resulting integer will be treated as a total number of frames.
Converting any other type of value to a Timecode is invalid.

Date/Time Variables

Converting a String value to a Date/Time will attempt to parse the string in the format "MM/DD/YYYY hh:mm:ss". Hours are from 00 to 23. Leading zeroes are optional.
Converting an Integer value to a Date/Time will treat the integer value as a Unix timestamp (seconds since midnight UTC on 1/1/1970).
Converting a Timecode value to a Date/Time will treat the timecode as an amount of elapsed time since midnight UTC on 1/1/1970.
Converting a Decimal or Bool value to a Date/Time will first convert the value to an Integer as described above ("Integer Variables"). The resulting integer will be treated as a Unix timestamp.
Converting any other type of value to a Date/Time is invalid.

Device Reference Variables

Converting a String value to a device reference will reference a device by name (examples: "V16X", "MyProjector").
Converting an Integer value to a device reference will reference a device by index, where 0 is the show controller itself.
Converting any other type of value to a device reference is invalid.