Automation Overview

How automation works

You can automate playing Media Items by building automation Scripts (Scripts) . A Script is composed of one or more command Steps (Steps) which execute in sequence or can be timed to fire at a specified time. You can run a Script manually by pressing Run Script button in the Automator window (Figure 2.). Or Scripts can be run at a specific time of day by starting them with the Scheduler. To get started with Scripts, read this page , then look at the Script samples .

To Page Top

Automation Scripts

Automation Scripts have the following behavior:

They execute step commands in sequence (like a music player playlist) or by timing steps to execute after a specified time interval has expired.
They can be run repeatedly any number of times.
They can be run other Scripts by executing a Run Script Step command.
They can be scheduled to execute at a specified time of day. (Scheduled Time)

To Page Top

Step Types

Automation Steps include the following types.

Load - Loads a Media Item into a Media Screen. (see Dos and Don'ts below regarding Load steps)
Play - Plays a Media Item. This will load the video to a Media Screen if it is not already loaded.
Stop - Stops the video playback of a Media Screen. Resets play position to start of media (00:00).
Pause - Pauses the video playback of a Media Screen.
Resume - Resume the video playback of a Media Screen at the play position where it was paused.
Unload - Unloads (closes) a Media Screen. It's a good practice to unload a media screen after play completes.
Screen Visible - Makes a Media Screen visible or invisible based on the value of the boolean variable (True = Screen Visible, False = Screen Invisible). You can automatically make a video Pause when it becomes invisible, then Resume when it becomes visible again. See the "Pause/Resume Video on Screen Visibility Change" option for details (found in Screens(1) Options panel).
Bring to Front - The step will bring the specified Media Screen to the front of other Media Screens. If you have multiple Media Screens loaded on one display, they will stack one in front of the other with only one being visible. Your Script logic may require that a screen be moved to the front at a given time. When you first Play or Load a Media Screen it will be opened frontmost in the order -- subsequent plays do not automatically move the screen to the front.
Full Screen - Makes a Media Screen display full screen or returns its window to previous normal size, based on the value of the boolean variable (true=Full Screen / false= Normal Window Size).
Delay - Delay puts a time delay between sequential steps in the script.
Run Script - Run another Script. You are prompted to select a target Script. Script execution will continue immediately to the next step in the script -- The Automator does not wait for the invoked script to complete. If the target script is already running, this step will be ignored.
Stop Script - Stops a Script. A script can stop itself after an amount of time by enabling the step's Offset Time. Or it can stop another script.
Pause Script - Pauses a Script. A script can Pause itself after an amount of time by enabling the step's Offset Time. Or it can Pause another script.
Resume Script - Resumes a Script. A script can Resume itself after an amount of time by enabling the step's Offset Time. Or it can Resume another script.
Start External Program - Starts an External Program. You are prompted to select the External Program. You can specify variables (parameters) to pass to the program if the target program accepts command line arguments.
Wait On Script - Causes a Wait for a specified Script to complete processing. You are prompted to select a target Script to wait on. If the specified script is not currently running, the step will not wait and execution will continue to the next step. This step cannot be offset timed. See script sample for more usage detail.
Unload All Screens* - Unloads All Media Screens that are currently loaded.
Halt All Scripts* - Stops ALL currently running scripts (including the script that contains this command).
Pause All - All currently playing Media Items are Paused including Scripts and the Scheduler. Caution: Once paused, execution can ONLY be resumed manually (via Actions > Resume All menu item or Alt+R shortcut), since all Scripts are now in a paused state. Or see the Resume All command below for handling of Offset Timed step. See script sample for more usage detail.
Resume All - All currently paused Media Items are Resumed including Scripts and the Scheduler. When the Auotmator has been paused by a Pause All command, a Resume All Step command can be executed ONLY by making the Step Offset Timed. See script sample for more usage detail.

* End Processing Steps - These steps can be used to provide clean-up at a scheduled time or after a specified expired time duration (offset timed). Execute the "Unload All Screens" step before the "Halt All Scripts" step when using the two together. See script sample for more usage detail.

See the Script Editor for details on how Steps are added to a Script.

To Page Top

Script Dos and Don'ts

Avoid Load Step Before Play Step

In most cases, you should NOT use a Load step before a Play step (Sequence A below). In fact it is less efficient than simply performing just a Play Step. And the combination (Load+Play) can cause timing issues in some cases -- The Load may not complete before the Play step is executed resulting in unpredictable behavior. Only use a Load step in cases where you want to open a Media Screen frozen on frame one, then perform the Play step at some later time.

Load + Play Sequence
A - Avoid: Load(video1); Play(video1); Load(video2); Play(video2)...

When Using Load Templates, Don't Use Unload Steps

One of the efficiences of using Load Templates is that a template Media Screen gets reused for each subsequent Play step.

As a rule of thumb, rather than using a sequence like this.
A - Avoid: Play(video1); Unload (video1); Play(video2); Unload (video2); Play(video3); Unload (video3)...

Simply use this.
B - Better: Play(video1); Play(video2); Play(video3)...

Sequence A, will cause the template Media Screen to be destroyed with each unload and rebuilt with each Play step. This will result in a noticable delay between video plays.

To Page Top

Sequential vs Offset Timed Steps

Script Steps execute in one of two modes. When Offset Time is NOT enabled, the Step is treated as a simple sequential Step.

Sequential order - Each Step executes in sequence, waiting for the previous Step to complete. Think of a playlist of a music player.
Offset Time - The Step executes after a specified delay (offset) from the moment that the containing Script starts to run. (ex. 10 seconds after the Script starts.)

To Page Top

Using time controls and time behavior

Offset Time: A Step will execute after a specified amount of time from the instant its containing Script starts to run. This is the best method for making videos play concurrently. For example, set Offset Time to 2 seconds then the Step will execute 2 seconds after the Script starts to run.
A Step is treated as a simple sequential Step, when Offset Time is not enabled.
Steps with equivalent Offset Times will start to execute simultaneously.
Steps with an Offset Time of zero (0) will execute immediately when the Script starts.
Pausing a Script that has Offset Timed Steps, will cause start time of those Steps to be delayed as well. For example, if a Step has an Offset Time of 10 seconds and you pause the Script after 5 seconds then resume some time later, the effective start time for this step will be at 5 seconds after the Script is resumed.
A Delay Step are always executed as sequential Step.
A Delay Step will preserve its delay time while a Script is paused.
Playing a Media Item that is setup to Loop (in the Play Modifiers) is a special case. A looping video never finishes until you manually hit the Stop button. So it will prevent any subsequent Steps from executing. If you use a Looping video, you will need to Stop the Script manually.

To Page Top

Rules of Script Execution

The Load Rule

Caution! A Media Item MUST be loaded to a Media Screen before it can be referenced by any Script Steps. It can be loaded either manually from the Media List Editor or by a Script Load Step. If you attempt to execute a step that references an unloaded Media Screen, you will see a "Load missing" error message and the step will be skipped. See the Log file messages when unexpected results occur.

Load Time For Load Steps

Load Time of a Media Item is not predictable and is based on multiple factors: Speed of the computer and CPU usage by other running programs; Size of media file; Media formats (low resolution vs high definition formats); Codec that does the decompression of the media; Media file physical location (remote/Web vs local machine file) and other variables. A Load step will generally take up to a few seconds to create a visible Media Screen on the display. The amount of time it takes for the media to open and be ready for play will take additional time and will vary based on the factors mentioned above.

Load Step for Existing Media Screen

When a Media Screen is already loaded, and a Load Step for the Media Item is executed, it is simply ignored. It will not affect the playing status of an existing Media Screen.

Unloading After Play - Best Practice

For large videos (ie large file size), it is a best practice to Unload the Media Screen after it finshes playing. This frees up RAM memory.

Playing Sequential Media Items

The Automator will wait to recieve an End Of Media signal before proceeding to the next sequential step. An End Of Media signal implies that the end of the audio or video has been reached.

Playing Offset-Timed Media Items

The Automator simply starts playing an Offset-Timed Play step at its specified time interval. It has no effect on execution of sequential steps. The Automator will wait for all playing Media Items to finish before completing a script run.

Multiple References to One Media Screen

Multiple Scripts can run concurrently (at the same time). If two Scripts reference the same Media Screen, they may interfere with each other depending on the timing of these Scripts. For example, consider the case of two Scripts containing this step: Play Video1. When Script1 executes this step, the Video1 Media Screen will start to play Video1 from position 00:00. When Script2 executes this step, the Video1 will restart play at position 00:00 (effectively rewinding it to the beginning). If you want to have Video1 play in multiple Media Screens, simply create two duplicate Media Items that have Video1 for the media file.

Playing Image or Text Screen Media Items

Static Image files (Jpg, Png, etc) and Text Screens do not have an inherent time duration (length) like video and audio. See Default Image Text Screen Duration for rules on how a time duration is determined.

Affect of Pause on Delay Times

If you click Pause while a Delay Step is in effect, the delay time will suspend (stop draining) until Resume is clicked. So for example, consider a 20 second Delay. If you click Pause 5 seconds into the delay, there will be 15 seconds of delay remaining once you click Resume.

Affect of Pause on Offset-Timed Steps

If you click Pause while Offset-Timed Steps are waiting to execute, the execution time of these steps will suspend until the script is resumed. For example, if you have a Play step that is Offset-Timed to execute 10 seconds after the script starts, and you click the Pause button 5 seconds after the script starts, when you click Resume button there will still be 5 seconds of wait time before the Play step is executed.

To Page Top

Script Single Instance Rule

Any number of Scripts may run simultaneously. However, only one instance of a given Script can run at a given time. So for example if Script-A and Script-B are running and Script-B tries to execute a Step Run Script(Script-A), the Automator will see that Script-A is already running and ignore the Step.

To Page Top

Script Self Reference

A Run Script Step will start another Script to run. However, a Script should not contain a Run Script Step that starts itself. It will be ignored due to the Single Instance Rule above.

To Page Top

Runaway Script Error Condition

If a Script is detected repeating itself rapidly in a very short time span, the Automator will assume it is in a Runaway condition and abort it.

Under certian conditions, you could create a Script that spins out of control, repeating itself as rapidly as your CPU can process it. This is usually associated with a Script set to Loop or Repeat and composed of timed Steps (ex Offset Timed Steps). The Script Editor detects and warns about obvious cases, but not all problems can be detected at edit time.

To Page Top

Script Recursion Error Condition

If a Script is detected as running in an infinite Recursion loop, the Automator will abort it.

This can happen if you are not careful with 'Run Script' Steps in your Scripts. For example, if you run Script A in Listing 1, it would cause a Recursion loop (A runs B; B runs A; A runs B; ad infinitum...). If not stopped, the two Scripts would continue to run each other until the computer runs out of memory.

Figure 1. Script Recursion

Figure 2. Automator main window

Language

To Page Top