# Actions Specifications

Actions are commands and computations performed by Antescofo at a certain point in time. Often, theses actions are messages sent to a MAX/PD object to trigger other activities. Other actions correspond to internal computations. Actions can be also used to specify the temporal organization of subsequent actions.

Actions can be categorized as instantaneous or durative:

- an instantaneous action takes no time to be performed (see the Synchrony hypothesis);

- a durative action is an action that takes times to be performed.

However, another relevant categorization is atomic or compound:

- An atomic action performs an elementary computation or a simple message passing that cannot be decomposed.

- A compound action groups other ‘‘child actions’’ allowing for polyphony (i.e. actions that are interleaved in time or that are are performed in parallel), loops (i.e. actions that are iterated and repeated in time), conditional actions, etc.

An atomic action is always instantaneous. Usually, a compound action takes time to be performed. Howevever, some compound actions may be instantaneous (for example, a conditional action that involves only one atomic action without delay.

## Action Sequence

Actions always appear in sequences called groups. A group organizes the performance of its actions in time. Some groups are explicit when they are introduced with the Group construction (the fundamental compound action). Or they can be implicit:

- as the sequence of actions that appears after a musical event,

- as the children of other compound actions: Loop, Whenever, etc.,

- as the body of a process,

- as the @action clause of a Curve,

- as an @abort clause of a compound action,

- as an @init clause, a @whenever clause or as the body of a method in an object.

An action in an sequence of actions:

- starts with an optional delay

- is linked with the previous action through a continuation operator. They are currently three continuation operators:

  - `` (nothing, the two actions appears in sequence in the text) which specifies that the action that follows starts with the begining of the previous one;

  - `==>` which triggers the next action with the end of the previous one;

  - and `+=>` which launches the next action at the end of the previous one including its children.

In addition, actions have optional attributes that are specified differently depending on whether the action is atomic or compound.

## A Glimpse of Syntax

### Actions Sequence

Sequence of actions appear after a musical event or as the body of a compound action. They are made explicit with the notion of Group which is used to specify additional properties of the sequence (e.g. synchronization attributes).

The @local, @global and @tempovar keywords introduce variables declaration. The local variables are local to the sequence of actions.

### Atomic Action

These actions are further described in chapter Atomic Actions. They are performed instantaneously.

### Compound Action

These actions are further described in chapter Compound Actions. They act as temporal containers organizing the temporal relationships of other actions.

## Action Attributes

Each action has some optional attributes which appear as a comma separated list:

            Group G  @att₁, @att₂ := value  { }
            atomic_action  @att₁, @att₂ := value
            compound_action @att₁, @att₂ := value { ... }

In this example, `@att1` is an attribute limited to one keyword, and `@att2` is an attribute that requires a parameter. The parameter is given after the optional `:=` sign.

Some attributes are specific to some kind of actions. There are listed below and they are described in the section dedicated to this kind of action:

- @norec is relevant only for the abort atomic action,

- @action and @grain are meaningful only for the Curve construct,

- @abort and @exclusive have an impact on all compound actions,

- @immediate is relevant only for Whenever,

- @staticscope is a qualifier for process definition,

- synchronization attributes may alter all actions, incuding atomic ones (even if a @tempo specification on an atomic action is meaningless).

Curve Related Attributes

Whenever Related Attributes

Process Definition Related Attributes

Abort Related Attributes

Compound Actions Related Attributes

Synchronization Related Attributes

### Labels

There is one additional attribute that can be specified for all actions: a label. The label of a compound action usally follows the keyword introducing the compound action, like the label `G` for the group in the example above. The label can also be specified with the `::antescofo@label` attribute:

           action ... @label := a_label
           action ... @label := "a label"

(this is the only way to give a label to an atomic action or to an `if` or a `switch`).

Labels are used to refer to an action, for instance to terminate it. Like events, actions can be labeled with:

- a simple identifier,

- a string,

- an integer.

There can be several labels for the same action. Unlike with event labels, the $-identifier associated to the label of an action cannot be used to refer to the relative position of this action in the score.

## Delays

An optional specification of a delay can be given before any action A. This defines the amount of time between the previous event or action in the score and the computation of A. It can be expressed in seconds, milliseconds, or beats.

The delay countdown will begin to run from either the beginning or the end of the previous action, in accordance with to the continuation operator that precedes it. If the action is triggered by an event, the delay countdown must begin upon recognition of said event. See the section Continuation Operator for more information. For the rest of this section we suppose a default continuation: the delays are counted down from the beginning of the previous action.

Upon the expiration of the delay, we say that the action is fired (we use also the word triggered or launched). Thus, the following sequence

              NOTE C2 2.0
                d₁ action₁
                d₂ action₂
              NOTE D2 1.0

specifies that, in an ideal performance that adheres strictly to the temporal constraint specified in the score, `action₁` will be fired `d₁` after the recognition of the `C2` note, and `action₂` will be triggered `d₂` after the firing of `action₁`. That is to say, `action₂` is fired `d₁ + d₂` after the recognition of `C2`.

A delay can be any expression. This expression is evaluated when the preceding event is launched. That is, expression `d₂` is evaluated in the logical instant where `action₁` is computed. If the result is not a number, an error is signaled.

### Zero Delay

The absence of a delay is equivalent to a zero delay. A zero-delayed action is launched synchronously with the preceding action or with the recognition of its associated event. Synchronous actions are performed in the same logical instant and last zero time, cf. paragraph Logical Instant.

### Absolute and Relative Delay

A delay can be either absolute or relative. An absolute delay is expressed in seconds (or in milliseconds) and refers to wall clock time or physical time. The qualifier (s or ms, respectively) is used to denote an absolute delay:

                       a₀
                   1 s a₁
             (2*$v) ms a₂

Action `a₁` occurs one second after `a₀` and `a₂` occurs (2 * $v) milliseconds after `a₁`. If the qualifier (s or ms) is missing, the delay is expressed in beat and it is relative to the tempo of the enclosing group.

### Evaluation of a Delay

In the previous example, the delay for `a₂` implies a computation whose result may depend of the date of the computation (for instance, the variable `$v` may be updated somewhere else in parallel). So, it is important to know when the computation of a delay occurs: it takes place when the previous action is launched, since the launching of this action is also the start of the delay. And the delay of the first action in a group is computed when the group is launched.

A second remark is that, once computed, the delay itself is not reevaluated until its expiration. However, the delay can be expressed in the relative tempo or relatively to a computed tempo and its mapping into the physical time is reevaluated as needed - that is, when the tempo changes.

Delay vs. Expressions. The expression used in the specification of a delay, and more generally of a duration1, must evaluate to a numeric (integer or float). There no specific type of value corresponding to a delay.

This means that `1 s` is not a value. The `s` or `ms` qualifier appears in the specification of a delay, but is not part of the expression defining the duration of the delay. A consequence is that you cannot pass `1 s` as the value of an argument (however, you can pass `1`).

### Synchronization Strategies

Delays can be seen as temporal relationships between actions. There are several ways, called synchronization strategies, to implement these temporal relationships at runtime.

For instance, assuming that in the first example of this section `action₂` actually occurs after the occurrence of `NOTE D`, one may count a delay of \(d₁ + d₂ - 2.0\) starting from `NOTE D` after launching `action₂`. This approach will be for instance more tightly coupled with the stream of musical events. Synchronization strategies are discussed in chapter Synchronization Strategies.

## When an Action is Performed

We write at the beginning of this chapter that actions are performed when arriving at some date. But the specification of this date can take several forms. It can be

- the occurrence of a musical event (detected by the listening machine)

- the change of a musical parameter (i.e., the tempo)

- the start or the end of another action

- the expiration of a delay

- the reception of an OSC message

- a logical event (see the whenever construction and the chapter Patterns) triggered by an internal update (via `:=`) or an external update (via `setvar`) of a variable

- the reception of a message from the host environment (Max, PD)

- the loading of the score (cf. @eval_when_load)

- the signal spanned by an abort action (see @abort handlers)

- the sampling of a Curve

- the instance of an iterative construct Loop and Forall

- the launch of a process (cf. Processes) or the creation of an object (cf. Objects)

In addition, for delays and for durative actions, the passing of time depends on a temporal scope which defines a tempo, a synchronization strategy and other temporal parameters. These notions are investigated in chapter Synchronization.

1. used for the period of a Loop and in the breakpoint of a Curve ↩

#### Search

From here you can search these documents. Enter your search terms below.