While the overarching feel of the music is controlled by the Descriptor chosen, a great deal of its character is tied to the instruments which are playing it. When unspecified, the provided Descriptor will be used to choose an instrumentation that will give a good result, however there are times when you may want more direct control. Here are some important concepts and examples of for dealing with instrument choices directly.
A Band is a named collection of instruments that work will together. Every Descriptor has a number of Bands associated with it which are idiomatic for the requested style of music. If a Region is provided without any active instruments, an arbitrary Band will be chosen based on the Descriptor.
Note: Bands not specifically associated with with a particular Descriptor may work, however the resulting music is not guaranteed to convey the desired properties of the requested Descriptor.
The Descriptors which a Band is associated with are listed in its
data.attributes.tags containing the
"category": "descriptor" field. In order
to find all Bands associated with a known Descriptor, filter a list of Bands by
whether or not they contain a tag for the Descriptor(s) you are looking for.
Bands contain different numbers of Instruments. Generally using fewer Instruments
sounds more intimate, whereas larger amounts feel more powerful. The minimum and
maximum number of Instruments in a Band for any given Descriptor varies depending
on the intended feel, but Bands may, for example, be sorted by the length of the
data.attributes.instruments list to convey their smallest to biggest nature.
Each Band is also tagged with a
band_size which is typically
large and can be further used to differentiate them regardless
of the actual number of Instruments they contain.
Note: The timeline itself works with Instruments, not Bands. To use a Band, put all of its Instruments in the
instrument_groupslist of a
"metered"Span with a
"active"during the time a particular Region is in use.
Each Descriptor has a number of Instruments associated with it that are appropriate for the music it represents, much like Bands. In cases where you want to go off the beaten path, you may freely replace or supplement the Instruments in any Band with others associated with the same Descriptor. Alternatively you may want to ignore Bands completely and build your own. The choice is yours, but if you are planning to do so, please read the next section for some additional considerations.
Instrument Tags and Constraints
The provided Bands contain varying numbers of Instruments. There is no requirement that a timeline contain Instruments from any particular Band. It may be desirable to use fewer Instruments than are in the smallest provided Band, and as long as there is at least one Instrument playing, the music should not be silent. Replacing one Instrument for an other is generally fine provided that you are happy with what the new one will do in its place.
Things get less clear when adding more Instruments than were there before however. How many is too many? What would sound good here? To help answer some of these questions, Descriptors provide not only a list of all Instruments that they were designed to work well with, but also a set of constraints to inform you of the upper bounds for various combinations.
There are two “levels” of constraints:
instrument_category refers to broad groupings of related
Instruments (such as basses, keyboards, etc.) and
instrument_type to more
specific groupings (such as electric basses, acoustic pianos, etc.). Every
instrument_type has exactly one parent
instrument_category (e.g. electric
bass and acoustic bass are both basses).
Every Descriptor has a key
data.attributes.constraints containing a list of
objects specifying two things: a
cap, the maximum number of
Instruments with the associated Tag that we suggest using with
that Descriptor, and the Tag(s) to which the
cap applies. The intent
is that during any Region, the total number of Instruments that are playing from
instrument_type should be less than or equal to
Note: These constraints are suggestions and are not directly enforced. These limits have been chosen because they ensure that the resulting music behaves how it was intended, but may be violated at your own risk. However the result of doing so is undefined.
When Things Play
Deciding which Instruments you want to use is only half of the equation; you also need to be able to tell them when you want them to make sound. Instruments live inside the
timeline.span.instrument_groups list of a
"metered" Span. An important note is that all Instruments which will be used anywhere in the same
"metered" Span are listed regardless of when they are used. It helps to think of this like a mixer or full score: you need to know everything that will be playing at any point, regardless where they may be resting.
Note: What we have been referring to as an Instrument here is officially called an
instrument_groupin the timeline because it may actually represent something like a drum set, which technically is made up of multiple instruments. For our purposes here however we will continue to think about them as singular entities.
instrument_group object contains a list called
statuses, which denotes
that particular Instrument will be allowed to play. Each
status contains two
pieces of information: the
beat (relative to the start of the Span) on which
the status takes effect, and a
status of either
"active" (meaning that it
can play) or
"inactive" (meaning that it cannot play). Each
remains active until the next
status or the end of the Span, whichever comes
In other words, if you would like an instrument to play for the entire Span, set it to be
beat 0.0 and be finished. If, however, you are working with multiple Regions and/or otherwise want certain Instruments to start and stop at different times, you can to specify so here.
If you prefer working with Actions, see
set_instruments, which allow you to more
declaratively add, remove, or replace all Instruments respectively. This
approach has the added difference that they are specified by absolute
rather than relative
beat, which may or may not be more useful depending on