# 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](/bittsy/creating-protocols/starting-definitions.md) 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](/bittsy/creating-protocols/starting-definitions.md) 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](/bittsy/creating-protocols/starting-definitions.md#audio) 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](/bittsy/creating-protocols/tags/tags-referencing-files.md#typedlet-and-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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ldevumd.gitbook.io/bittsy/creating-protocols/action-statements.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.