Create

Create

The create action is different from other actions in that rather than acting as a macro for more easily altering aspects of a timeline, it takes an abstract request for what you want to hear and attempts to populate a timeline with a result that matches. Also, unlike all other actions, create does not have a time associated with it, since it acts on the entire span it is associated with.

A create action takes a list of objects describing what should happen. Each object has a key called using which describes what information should be used. At some point in the future this will also allow for additional options.

The using key can be given a string containing space-separated words that will influence the resulting music. This style is useful if the arguments are all single words, if it is intended to be populated by something that produces a single string, etc. It can also be an object with a query key that is an array of strings to use, which is useful for inputs that are multiple words long, if it is intended to be populated by something that produces an array, etc.

With either style, the input to using will be used by the Composer to make decisions regarding what music will be created. While ideally anything a user provides would produce a good result, the more closely related to Amper’s terminology the inputs are, the more predictable the music will end up being. As a rule of thumb any id or name field from any Entity is a reasonable choice. Other queries may work, but there are no guarantees about the results.

Supplying multiple word queries will cause the Composer to attempt to create music which matches as many of the words as possible. Depending on what property of the music the words relate to, some will carry more emphasis than others. Additionally, mutually exclusive words will generally cancel each other out.

Note: queries that do not match anything the Composer can produce will be ignored. If there are no usable queries, the create action will be unable to create any regions and will produce a warning in the timeline’s notifications array.

See How to use the Create Action for more information.

Data Item Type Required/ Optional Description
create array required An array of objects
create[].using string required See below

The using key can be one of two things * a string of space-separated words * an object with the following keys:

Data Item Type Required/ Optional Description
query array required An array of strings to use

Example space separated string style:

{
    "create": [
        {
            "using": "playful hiphop"
        }
    ]
}

Example object style:

{
    "create": [
        {
            "using": {
                "query": [
                    "playful",
                    "hiphop"
                ]
            }
        }
    ]
}