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:
add_instruments
add_region
copy_instruments_from_time
copy_region
copy_tempo_from_time
create
Note: for this action only thetime
key is not requiredramp_tempo
set_instruments
set_tempo
silence_instruments
The following example is an object with multiple actions
occurring at 22
seconds after the start of the span
:
- Add a
region
ofdocumentary_minimal_intriguing
. - Copy the instruments in use from 0 seconds after the start of the
span
. Set the tempo at that time to 120 BPM.
{ "time": 22, "add_region": { "id": 1337, "descriptor": "documentary_minimal_intriguing" }, "copy_instruments_from_time": 0, "set_tempo": 120 }
The following sections describe the available actions.