Add Region

Add Region

The add_region action adds a region to the timeline.

Data Item Type Required/ Optional Description
add_region object or text required Provides information about a region of music to be created, or the string “silence” to create a silence region
add_region.id number optional A unique identifier. If omitted, the Composer creates a unique identifier automatically. NOTE: If an id is not provided, the created region cannot be the target of a copy_region action in the same timeline
add_region.descriptor text required The descriptor id needed to compose music
add_region.random_tempo boolean optional If set to true, a random tempo based on the specified descriptor is selected in the style of set_tempo at the start of the region. If omitted, the default is false (the tempo stays the same)
add_region.random_instruments boolean optional If set to true, a random collection of instruments based on the specified descriptor is selected in the style of set_instruments at the start of the region. If omitted, the default is false (the instrumentation stays the same)
add_region.ringout_at number optional If provided, from the time provided until the next silence or the end of the span, the music ends with a “ringout” (instruments play one final note that lasts the remainder of the region)
add_region.cut_at number optional If provided, the music continues until the end of the region and then abruptly stops. Note: Currently, the number itself has no meaning
add_region.key object optional The key_signature active at the start of the region

NOTE: cut_at and ringout_at are mutually exclusive. If both are provided, it is unspecified which is used. If both are omitted, a ringout_at is automatically provided two seconds before the end of the region.

Example music Region:

{
    "time": 0,
    "add_region": {
        "id": 1337,
        "descriptor": "documentary_minimal_intriguing",
        "random_tempo": true,
        "random_instruments": true,
        "ringout_at": 20,
        "key": {
            "tonic": "bes",
            "quality": "major"
        }
    }
}

Example silence Region:

{
    "time": 15,
    "add_region": "silence"
}