Choose Instruments

Choose Instruments

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 small/medium/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_groups list of a "metered" Span with a status of "active" during the time a particular Region is in use.

Individual Instruments

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 and instrument_type. 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 each instrument_category and instrument_type should be less than or equal to the associated cap.

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_group in 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.

Each 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 status object remains active until the next status or the end of the Span, whichever comes first.

In other words, if you would like an instrument to play for the entire Span, set it to be "active" at 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 add_instruments, silence_instruments, and 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 time rather than relative beat, which may or may not be more useful depending on your requirements.