Event Reference
This page documents the built-in events that can be used in your script. Devices that you add may have their own set of events defined in their product file, which are not included here.
Note
This page documents the events available on the V16X and V4X show controllers. RidePlayer and BinloopX contain additional events to control Media Playback, which will be added to this page in a forthcoming update. In the meantime, all events are documented within the "Event Wizard" for each event in WinScript Live. Right-click on the event and click "Edit" to launch the event wizard.
Add
The Add event either adds a constant value to a variable, or adds the contents of two variables together. Acceptable variable types are Integer, Decimal, and Timecode. Timecode variables will be converted into the total number of frames contained in that timecode variable.
| Name | Param1 | Param2 |
|---|---|---|
| Add | Destination Variable | Value or Variable to add to Param1 |
Arm
The Arm event sets the status of a sequence tracking SMPTE LTC timecode to the 'armed' state. In the 'armed' state, the sequence will be watching the LTC input and will chase timecode.
| Name | Param1 |
|---|---|
| Arm | Sequence to Arm |
BitAnd
BitAnd does a bitwise AND operation on two variables, storing the result in the first variable. For example, the BitAnd of 15(b1111) and 8(b1000) would be 8(b1000).
| Name | Param1 | Param2 |
|---|---|---|
| BitAnd | Variable1 | Variable2 |
BitOr
BitOr does a bitwise OR operation on two variables, storing the result in the first variable. For example, the BitOr of 15(b1111) and 8(b1000) would be 15(b1111).
| Name | Param1 | Param2 |
|---|---|---|
| BitOr | Variable1 | Variable2 |
Blink
Blink toggles a discrete output at a specified rate. Blinking continues until the output is reset by a Off, On, Pulse, OutPort, or Toggle event.
| Name | Param1 | Param2 |
|---|---|---|
| Blink | Output | Blink Rate (timecode value, number of frames, or timecode variable) |
Ceiling
Ceiling rounds up a Decimal value to an integer value. The significance parameter is the multiple to which to round. For example, 6.35 with a significance parameter of 2 would round to 8. Use a significance parameter of 1 for a "normal" ceil function.
| Name | Param1 | Param2 |
|---|---|---|
| Ceiling | Value | Significance |
Concat
Concatenate a string-type variable with another variable or constant string value. The result is stored in the first variable.
| Name | Param1 | Param2 |
|---|---|---|
| Concat | String variable | Constant value("Hello") or String variable |
Convert
Convert a string (like "1,340") to an integer variable. The result will be stored in Param1.
| Name | Param1 | Param2 |
|---|---|---|
| Convert | Variable | Constant value("Hello") or String variable |
Disarm
The Disarm event sets the status of a sequence tracking SMPTE LTC timecode to the 'disarmed' state. In the 'disarmed' state, the sequence will ignore incoming timecode and not execute.
| Name | Param1 |
|---|---|
| Disarm | Sequence to Disarm |
Display
"At Position" Variation
This variation of the display event displays a string constant, String variable, or LCDString variable at a specified location on the display.
| Name | Param1 | Param2 | Param3 |
|---|---|---|---|
| Display(At Position) | Variable or Display String | Row (Optional) | Column (Optional) |
"With Variables" Variation
This variation of the display event is used to display text on the display, with variable values embedded in the text. This variation can take up to 7 variable parameters.
| Name | Param1 | Param2 | ... | Param8 |
|---|---|---|---|---|
| Display(With Variables) | Display String Variable or Display String | Variable to insert (optional) | ... | Variable to insert (optional) |
Creating Display Strings
The "LCD Help" wizard is a helpful tool to build Display Strings for you. It is located in the event wizard, in the "..." menu next to the Display String parameter.
While the LCD Help wizard is the recommended way, you can also generate Display Strings by hand. Each line in a display string should be in quotes and separated by commas. For example, "1","2","3","4" would display:
1
2
3
4
The keyword clr has a special meaning - it clears the line. For example, "1",clr,"3",clr,"5" would display:
1
3
5
Variables can be inserted into your string using specifiers. For example, "Effect Count: %d" would place the variable in Param2 into the string at the location of the "%d" specifier, as an integer value.
More information on format specifiers is available here.
Divide
Divide one variable by another variable or constant value. Store Result in first variable.
| Name | Param1 | Param2 |
|---|---|---|
| Divide | Numerator and result variable | Denominator, constant value or variable |
Empty
The Empty event takes no action and changes no state on the device. It can be used as a label placeholder or time delay. "Empty" was previously known as "nop" (No Operation).
| Name | Param1 |
|---|---|
| Empty | No Parameters |
Divide
Divide one variable by another variable or constant value. Store Result in first variable.
| Name | Param1 | Param2 |
|---|---|---|
| Divide | Numerator and result variable | Denominator, constant value or variable |
Eval
The Eval event evaluates the result of an expression string and stores it in a variable. This event can be used to perform complex math operations in a single event. Further information on how to form expression strings are available here.
| Name | Param1 | Param2 |
|---|---|---|
| Eval | Result variable | String containing an expression |
Floor
Floor rounds down a Decimal value to an integer value. The significance parameter is the multiple to which to round. For example, 7.35 with a significance parameter of 2 would round to 6. Use a significance parameter of 1 for a "normal" floor function.
| Name | Param1 | Param2 |
|---|---|---|
| Floor | Value | Significance |
Format
Create an ASCII string using other variables as inputs to the string. This is similar to the "sprintf" function in the programming language C.
| Name | Param1 | Param2 | Param 3 | ... | Param8 |
|---|---|---|---|---|---|
| Format | String variable to store result | Format String (eg. "hello %s %d") | Variable | ... | Variable |
Param2’s "Format String" is made up of format specifiers that indicate where and how the variables in Param3-ParamN should be inserted.
More information on format specifiers is available here.
Get At
The Get At event is used to get an item from an array at the specified index, and store it into a variable.
The first index of an array depends on the "Zero-indexed" setting in the variable setup wizard. If "Zero-indexed" is checked, then the first item in the array is at position 0. If "Zero-indexed" is not checked, then the first item in the array is at position 1.
"Variable" Variation
The variable variation is used for any array type other than Device Arrays. For instance, to retrieve index 4 of an array of 32 integer variables.
| Name | Param1 | Param2 | Param3 |
|---|---|---|---|
| Get At(Variable) | Result Variable | Array Variable | Array index |
"Device" Variation
| Name | Param1 | Param2 | Param3 |
|---|---|---|---|
| Get At(Variable) | Variable of type "Device" | Device Array Variable | Array index |
Get Date
The Get Date event saves the year, month, day, or weekday portion of a DateTime variable into an integer variable. In the case of weekday, Sunday is represented as 0, and Saturday as 6.
| Name | Param1 | Param2 | Param3 |
|---|---|---|---|
| Get Date | Year, Month, Day, or Weekday | Integer Variable | Datetime Variable |
Get Length
The Get Length event retrieves the length of a constant string value or a string variable.
| Name | Param1 | Param2 |
|---|---|---|
| Get Length | Integer variable to store the result | String variable or string constant |
Get Random
The Get Random event generates a random number and stores it into an integer variable.
| Name | Param1 | Param2 | Param3 |
|---|---|---|---|
| Get Random | Integer variable to store the result | Min value (optional: default is variable's min value) | Max value (optional: default is variable's max value) |
Get Seq Time
The Get Seq Time event retrieves the current time of the specified timed sequence, and stores it in a Timecode variable.
| Name | Param1 | Param2 |
|---|---|---|
| Get Seq Time | Sequence Name | Timecode Variable to store the current sequence time |
Get Time
The Get Time event stores the hours, minutes, or seconds part of a Date/Time variable in an integer variable.
| Name | Param1 | Param2 | Param3 |
|---|---|---|---|
| Get Time | 'Hours', 'Minutes', or 'Seconds' | Integer variable to store the result | Date/Time variable |
In Port
The In Port event reads a group of eight or 16 inputs to a Variable. The lowest number input becomes the LSB, etc.
For example, assuming inputs of 10011101 (where 1 is on), after the InPort event is executed, Var7 will contain the value 157.
The first parameter of the event chooses which bank of inputs to read. "All" reads 16 inputs (if available on your device) as a 16bit integer, "Bank 1" reads Inputs 1-8 as an 8-bit integer, and "Bank 2" reads Inputs 9-16 as an 8-bit integer.
| Name | Param1 | Param2 |
|---|---|---|
| In Port | 'All', 'Bank1', or 'Bank2' | Integer variable to store the result |
Left
The Left event stores the specified number of characters from the start of a string.
For instance, the 'Left' event, with 4 characters specified, called on the string "Walleye", would result in "Wall".
This event modifies the string that is passed in directly, the result is stored in the same string that you pass as Param1.
| Name | Param1 | Param2 |
|---|---|---|
| Left | String Variable | Number of characters to keep from the start of the string |
Log Message
The Log Message event adds a user-specified log message to the Live Log (in connected in Live Mode) or to the Operational Logs stored on the device. Additionally, a severity level can be assigned to the message which will change the color of the entry in the Live Log. Severity levels can be "Error", "Warning", or "Info".
Param2’s "Format String" is made up of format specifiers that indicate where and how the variables in Param3-ParamN should be inserted.
More information on format specifiers is available here.
| Name | Param1 | Param2 | Param3 | ... | Param9 |
|---|---|---|---|---|---|
| Log Message | Severity Level | Format String (eg. "hello %s %d") | Variable | ... | Variable |
Loop
The Loop event starts a sequence and enables looping on the sequence, so that it will repeat continuously. Param2(Start Frame) allows the user to start the sequence at a specified offset into the sequence.
| Name | Param1 | Param2 |
|---|---|---|
| Loop | Sequence Name | Start Frame (eg. 00:00:01.00) |
Message Out
The Message Out event sends a string of characters or bytes to a device that has been added to your script. The message sends via the protocol configured for that device. The show controller will not wait for a response from the device except in the case of TCP, where a standard TCP handshake is performed to establish a connection.
You can specify the message with a String variable, or a combination of a string constant and bytes specified as hex values. For instance, "myMessage"h0D would send the ASCII string "myMessage" followed by a byte with the value of hex 0D (an ASCII carriage return).
This event is useful for communicating with devices that do not have a full Product File available.
| Name | Param1 | Param2 |
|---|---|---|
| Message Out | Device | Message as a String or String Var |
Mod
The Mod event performs a modulus operation on the specified variable, and then stores the result in that same variable. The modulus operation finds the remainder when two integers are divided. For instance, '13 mod 5' would give a result of '3'.
| Name | Param1 | Param2 |
|---|---|---|
| Mod | Variable | Constant value or variable to divide by |
Multiply
The Multiply event multiplies a variable by another variable or value. The result is stored in the first variable.
| Name | Param1 | Param2 |
|---|---|---|
| Multiply | Variable | Constant value or variable to multiply by |
Off
The Off event turns off an output or boolean variable. In the case of the boolean variable, Off means False.
| Name | Param1 |
|---|---|
| Off | Output or Boolean Variable |
On
The On event turns on an output or boolean variable. In the case of the boolean variable, On means True.
| Name | Param1 |
|---|---|
| On | Output or Boolean Variable |
Out Port
Sets a group of eight Outputs to a single binary value. The lowest number Output becomes the Least Significant Bit (or LSB), the highest becomes the Most Significant Bit (or MSB).
For example, setting output bank 1 (Outputs 1-8) to a value of 157 (or 10011101) would result in the following output settings: Output 8: On, Output 7: Off, Output 6: Off, Output 5: On, Output 4: On, Output 3: On, Output 2: Off, Output 1: On.
The first parameter of the event chooses which bank of outputs to set. "All" sets 16 outputs (if available on your device) as a 16bit integer, "Bank 1" sets Outputs 1-8 as an 8-bit integer, and "Bank 2" sets Outputs 9-16 as an 8-bit integer.
| Name | Param1 | Param2 |
|---|---|---|
| Out Port | 'All', 'Bank1', or 'Bank2' | Integer variable or constant containing the value to set |
Pause
The Pause event pauses the execution of a currently running sequence. This differs from a Stop in that it does not reset the sequence time back to zero.
| Name | Param1 |
|---|---|
| Loop | Sequence Name |
Ping
The Ping event sends a 'ping' request to the specified device, and after receiving a response, stores the MAC Address of the device in the .MACID device variable of the device. This event does not affect the .Error variable for the device.
| Name | Param1 |
|---|---|
| Ping | Device |
Play
The Play event starts (or restarts, if allowed) the execution of a sequence. The user can specify a start trim and end trim, which will shorten the length of the sequence by the specified amounts.
| Name | Param1 | Param2 | Param3 |
|---|---|---|---|
| Play | Sequence Name | Start Trim (as a timecode) | End Trim (as a timecode) |
Pulse
The Pulse events turns an output on or off for a specified amount of time.
| Name | Param1 | Param2 | Param 3 |
|---|---|---|---|
| Pulse | Output | Pulse time (as timecode or number of frames) | "On" or "Off" |
Ramp
The Ramp event sets an analog output or a variable to a specified value over a period of time.
| Name | Param1 | Param2 | Param 3 |
|---|---|---|---|
| Ramp | Variable or Analog Output | Variable or Value to ramp to | Ramp Duration as a timecode or number of frames |
Reboot
The Reboot event reboots the show controller.
| Name |
|---|
| Reboot |
Recover Display
The Recover Display event shows a stored LCD snapshot that was saved by the "Store Display" event. If no text was previously stored, the Show Controller's version number is displayed.
The stored display is stored in non-volatile memory and remains after a controller reboot.
| Name |
|---|
| Recover Display |
RegExp Parse
The RegExp Parse event takes a regular expression and parses it into up to 7 variables. Use "Capture Groups" in your regex to select which parts should be stored into variables.
| Name | Param1 | Param2 | ... | Param8 |
|---|---|---|---|---|
| RegExp Parse | String or String variable containing the RegEx to parse | Variable1 | ... | Variable7 |
Restore Variable
The Restore Variable event loads a variable value that has been stored in non-volatile memory by the "Store Variable" event.
| Name | Param1 |
|---|---|
| Restore Variable | Variable Name |
Right
The Right event stores the specified number of characters from the end of a string.
For instance, the 'Right' event, with 3 characters specified, called on the string "Walleye", would result in "eye".
This event modifies the string that is passed in directly, the result is stored in the same string that you pass as Param1.
| Name | Param1 | Param2 |
|---|---|---|
| Right | String Variable | Number of characters to keep from the end of the string |
Round
The Round event rounds a decimal value to the provided number of decimal places. Use 0 for the places param to round to the nearest whole number. The result is stored in same decimal variable that you pass in Param1.
| Name | Param1 | Param2 |
|---|---|---|
| Round | Decimal variable | The number of digits to which you want to round |
Send Mail
The Send Mail event sends an email to a specified email address using the SMTP settings set from the front panel or AMI-Terminal. Note: Secure SMTP is not supported. This event is only supported on the V16ProS.
| Name | Param1 | Param2 | Param3 |
|---|---|---|---|
| Send Mail | To (email address enclosed in angle brackets, ie. email@service.com ) | Subject | Body |
Set At
The Set At event is used to set the value of a position in the array.
| Name | Param1 | Param2 | Param3 |
|---|---|---|---|
| Set At | Array Variable | Index | Variable or Value |
Set Date
The Set Date event sets the year, month, or day portion of a DateTime variable from an integer variable.
| Name | Param1 | Param2 | Param3 |
|---|---|---|---|
| Set Date | Year, Month or Day | Datetime Variable | Integer Variable |
Set Loop
The Set Loop event sets the loop state of a sequence. This allows you to make a running sequence start looping or stop looping after it has been started.
| Name | Param1 | Param2 |
|---|---|---|
| Set Loop | Sequence | Loop State, as a boolean value or variable |
Set Time
The Set Time event sets the hours, minutes, or seconds part of a Date/Time variable from an integer variable.
| Name | Param1 | Param2 | Param3 |
|---|---|---|---|
| Set Time | 'Hours', 'Minutes', or 'Seconds' | Date/Time variable | Integer variable or value |
Set Value =
Analog Variation
The analog variation sets an Analog Output equal to a specified variable or value.
| Name | Param1 | Param2 |
|---|---|---|
| Set Value = (Analog) | Analog Output | Constant value, or variable |
Variable Variation
The variable variation sets a variable equal to a specified variable or value.
| Name | Param1 | Param2 |
|---|---|---|
| Set Value = (Variable) | Variable | Constant value, or variable |
Set Variable =
The Set Variable = event sets a variable equal to a specified variable or value.
| Name | Param1 | Param2 |
|---|---|---|
| Set Variable = | Variable | Constant value, or variable |
Stop
Stops a running sequence and resets it back to start. This was previously named "Reset" in firmware version earlier than v6.0.0.
| Name | Param1 |
|---|---|
| Stop | Sequence |
Store Display
Stores a snapshot of the current text on the Display. The snapshot can be recovered later using the "Recover Display" event. The snapshot is stored in non-volatile memory and is available even after a power-cycle.
| Name |
|---|
| Store Display |
Store Variable
Stores a variable in non-volatile memory. The variable can be recovered later using the "Recover Variable" event. The variable is stored in non-volatile memory and is available even after a power-cycle.
A maximum of 256 variables with a maximum length of 256 characters can be stored. Variables are stored using their name.
| Name | Param1 |
|---|---|
| Store Variable | Variable |
Subtract
The Subtract event either subtracts a constant value from a variable, or subtracts two variables. Acceptable variable types are Integer, Decimal, and Timecode. Timecode variables will be converted into the total number of frames contained in that timecode variable.
| Name | Param1 | Param2 |
|---|---|---|
| Subtract | Variable to subtract from | Variable or value |
Timecode Mute
The Timecode Mute event mutes the SMPTE LTC timecode output. When muted, the LTC still runs and can be manipulated, but there is no output on the SMPTE LTC connector.
| Name |
|---|
| Timecode Mute |
Timecode Pause
The Timecode Pause event pauses the SMPTE LTC timecode. Pausing stops timecode from incrementing and holds the value it was paused at. This event is functionally the same as Timecode Stop.
| Name |
|---|
| Timecode Pause |
Timecode Set
The Timecode Set event sets the current value of the SMPTE LTC timecode. This can be done while the timecode is in any state (paused, running, etc).
| Name | Param1 |
|---|---|
| Set Timecode | Timecode (eg. 00:00:10.02) or Timecode Variable |
Timecode Start
The Timecode Start event starts the SMPTE LTC timecode generator.
| Name |
|---|
| Start Timecode |
Timecode Stop
The Timecode Stop event stops the SMPTE LTC timecode generator. This is functionally the same as Timecode Pause.
| Name |
|---|
| Stop Timecode |
Timecode Unmute
The Timecode Unmute event unmutes the SMPTE LTC timecode output.
| Name |
|---|
| Timecode Unmute |
Toggle
The toggle event inverts the state of an Output or Boolean variable. For instance, toggling an output that is currently On will turn it off, and vice-versa.
| Name | Param1 |
|---|---|
| Toggle | Output or variable to toggle |