Action statements

Action statements start or stop the presentation of stimuli. They are used to control the displays, lights, and speakers.

Media files that are presented in action statements in one STEP persist through that step and into subsequent ones until they are instructed to turn off, either by reaching the end of the file (for audio and video files that are set to play only once) or by including a corresponding action statement later in the protocol that turns the stimulus off.

Images

IMAGE <side> <tag>
IMAGE <side> OFF

IMAGE CENTER dog
IMAGE LEFT OFF

Sides that are used in IMAGE action statements should come from the SIDES starting definition and should be matched to a display in the DISPLAYS starting definition.

Videos

VIDEO <side> <tag> <LOOP or ONCE>
VIDEO <side> OFF

VIDEO CENTER checkerboard LOOP
VIDEO CENTER OFF

Sides that are used in VIDEO action statements should come from the SIDES starting definition and should be matched to a display in the DISPLAYS starting definition. The audio component of the video will play through a correspondingly-named audio channel, if available (see explanation for both stereo and multichannel audio systems below).

ONCE will play the file to the end, then remove the video from the screen (it is not necessary to use a VIDEO <side> OFF statement to remove it, but doing so will not cause any problems). LOOP will continue looping back to the start whenever the file ends, and continue replaying the file until the next VIDEO <side> OFF statement.

Audio

AUDIO <audio channel or STEREO> <tag> <LOOP or ONCE>
AUDIO <audio channel or STEREO> OFF

AUDIO LEFT music1 ONCE
AUDIO RIGHT OFF 

As with video, ONCE will play the file to the end, then stop the audio from presenting to the speaker(s) (it is not necessary to use an AUDIO <side> OFF statement to remove it, but doing so will not cause any problems). LOOP will continue looping back to the start whenever the file ends, and continue replaying the file until the next AUDIO <side> OFF statement.

Stereo (2.1) audio systems

In a stereo audio system, channels are LEFT and RIGHT. Protocols run with stereo audio systems can also use the keywords CENTER and STEREO. Both of these commands will play audio simultaneously from the left and right speakers.

AUDIO CENTER passage LOOP
AUDIO STEREO passage LOOP

Multichannel (5.1 or 7.1) audio systems

To make use of more than two speakers on a multichannel audio system, your protocols will require an AUDIO starting definition in order to provide names for the available audio channels. Any of these names can then be used in the AUDIO action statement format.

AUDIO LEFTBACK passage LOOP

It is important to note that while in a stereo 2.1 system, STEREO and CENTER mean the same thing, they are not assumed to be the same thing whenever a multichannel AUDIO starting definition is provided. In this case, STEREO is the only command that means to play from two speakers simultaneously (these will be the first two speakers defined in the AUDIO starting definition, which are designated the front left and front right speakers on sound cards). CENTER can be used as a name in the AUDIO starting definition to mean a particular speaker, and if it is not present in the starting definition, it is not considered a valid channel name.

A note on STEREO/CENTER

AUDIO STEREO music ONCE

Using the above command, in a single action statement, ensures temporal synchrony in presenting the audio file across the left and right speakers. Two separate action statements playing tags to separate channels do not ensure complete synchrony. When playing a single tag to left and right, STEREO (or CENTER, for a 2.1 system) is therefore always preferable.

Whenever it is crucial that two different audio streams begin to play simultaneously, it is better to use audio files in which these streams have already been mixed together/placed into separate channels (as desired), and use a single action statement to play this file.

Action statements using LINKED tags

LINKED tags are defined earlier in the protocol, and consist of 2 or 3 member tags of different types (image, audio, or video).

LINKED dog = {dog_image, dog_audio}

Creating these tags via TYPEDLET and LINKED allows you to use action statements that refer to these tags in the same way across action statements of different types.

IMAGE LEFT dog
AUDIO LEFT dog ONCE

In protocols where they are suitable, LINKED tags help cut down on the number of tag names to which you must directly refer.