How do I programmatically change how many times an item in my Test Composition or Test Clip plays?

Document created by DPM Admin Employee on Jul 21, 2017
Version 1Show Document
  • View in full screen mode

General Methodology

Every item in a Test Composition can be set to repeat a specified number of times. If an item is not set to repeat, it will play once. If an item is set to repeat zero times, it will not play at all.

For most types of items, a Script can set the number of times that the item will repeat. A Script can prevent an item from playing by setting its repeat count to zero.

You can insert Scripts into your Test Composition that dynamically change the repeat counts of one or more items when the Script plays.

 

Restrictions

It is important to keep in mind that an item's repeat count cannot be changed once it has started playing.

Since all Tracks start playing immediately when the Test Composition begins, a Script cannot modify the repeat count for a Track. However, the repeat count for lower-level items, such as Test Clips, Chains, and Messages can be changed.

Certain types of items are only allowed to have a repeat count of either zero or one. These items are Checkpoints and Delays. For these items, the repeat count is used only to "enable" or "disable" the play of the item.

For items that have a specific scheduled time to play, during play the Maestro server may begin initializing them up to 5 seconds before their scheduled time, for performance reasons. Once this initialization process has started, the repeat count cannot be changed. Items with a scheduled time are all Test Clips and all items inside a time-based Test Clip except those items inside Chains. A time-based Test Clip is any type of Test Clip other than Sequenced.

 

Instructions

Insert one or more Scripts into your Test Clips at the points at which you wish to adjust the repeat counts of one or more following items, keeping in mind the restrictions listed above.

Your Scripts can traverse the object hierarchy of the Test Composition to find the other items in the Test Composition. For example, the following statement retrieves the item in the current Test Clip that immediately follows the current Script:

var anItem = $context.currentItem.nextItem;

Refer to the Scripting documentation for more information about how to traverse the object hierarchy.

Once your Script has found an item to change, the following examples show how to adjust the item's repeat count. In these examples, it is assumed that "anItem" is a variable containing an item's object whose repeat count is to be changed.

  • To set the repeat count to zero (thus preventing the item from playing), make the following call:

    anItem.setRepeat(anItem.REPEAT_TIMING_SERIAL,
      anItem.REPEAT_TYPE_COUNT_CONSTANT, 0,
      anItem.REPEAT_DISTRIBUTION_CONSTANT, 0);

  • To set the repeat count to a new value, assuming the new value is contained in variable "newCount", make the following call:

    anItem.setRepeat(anItem.REPEAT_TIMING_SERIAL,
      anItem.REPEAT_TYPE_COUNT_CONSTANT, newCount,
      anItem.REPEAT_DISTRIBUTION_CONSTANT, 0);

    Replace "REPEAT_TIMING_SERIAL" with "REPEAT_TIMING_PARALLEL" if the item is to repeat in parallel rather than serially.

  • To remove any repeat count, thus making the item play exactly once, make the following call:

    anItem.clearRepeat();

You must ensure that you change the repeat count before the item starts playing. This can be assured in any of the following ways.

  • The item follows the Script within the same Chain.
  • The item follows the Script within the same Sequenced Test Clip.
  • The Script and the item are in the same Test Clip and there is a Checkpoint between them.
  • The timing of your Test Composition is such that you know that the Script will always be played before the item.

    Be aware that for items that have a specific scheduled time to play, during play the Maestro server may begin initializing them up to 5 seconds before their scheduled time, for performance reasons.  Once this initialization process has started, their repeat count cannot be changed.  Items with a scheduled time are all Test Clips and all items inside a time-based Test Clip except those items inside Chains.
 

Attachments

    Outcomes