Action

Actions

An action object represents a collection of changes applied at a specific time. In many cases, the results of actions are actually represented in beats. When actions are applied, the Composer ensures all tempo-altering actions occur first, followed by all others, so the time in beats can be correctly calculated. Currently, no actions work directly with beats. If you prefer to work directly with beats, do not use actions.

action objects to be applied at the specified time reside within the same JSON object. However, some combinations do not make sense (for example, attempting to both add and silence the exact same instruments at the same time). Also, since JSON objects are unordered, there is no way to predict the order in which simultaneous actions will be applied. Therefore, timeline authors must ensure the behavior of all actions make sense.

Data Item Type Required/ Optional Description
time number required The time, in seconds, relative to the start of the span at which the requested actions are applied. For example, if a span begins at absolute time 10s, an action in that span at time 10s would occur at absolute time 20s

The available actions are:

The following example is an object with multiple actions occurring at 22 seconds after the start of the span:

{
    "time": 22,
    "add_region": {
        "id": 1337,
        "descriptor": "happy_classic_rock"
    },
    "copy_instruments_from_time": 0,
    "set_tempo": 120
}

The following sections describe the available actions.