Composition vs. Render

Composition vs. Render

Amper’s API provides two primary avenues for working with music: Compositions and Renders. The differences between them are subtle but important:

When to Work With a Render

If your goal is to request audio of any sort, then you need to create a Render. This may at first seem like the only thing you would ever need, which may be the case depending on your usage requirements, but there are some important behaviors to keep in mind:

Your Music May Change

Timelines will be altered without prior warning if there are issues with some parts of them (e.g. supplying invalid Instruments or Descriptors, providing inappropriate Scale Qualities, etc.). There is currently no way for the API to report changes back to you without a timeline being requested. In these cases, there is no way for you to know exactly what changed or why.

Your Timeline May Be Invalid

When getting accustomed to working with timelines, there is a very real chance that a required key may be accidentally missing, a comma was deleted by mistake, or any number of other subtle issues. When requesting a Render, an invalid timeline will be unable to produce audio, which will result in a failure notification without much context. Production systems using the API that have been sufficiently tested should never provide invalid timelines, but for development this is a concern.

Ideal Use

If you are sure that the timeline you are submitting is valid, you are uninterested in any potential changes that will be made to it, and all you want is the resulting audio, then a Render is your best choice.

When to Work With a Composition

The timeline is not just an input format, it is also a form of two-way communication between you and the Amper Composer. When working with a Composition you are guaranteed to get back a timeline regardless of the input. This gives you a window into what happened between when you submitted your request and when you received the result in the following ways.

Notifications

The top level JSON object of the timeline contains an easily overlooked key called notifications. This is a write-only key, anything present when submitting a request will be ignored and removed, but anything of note that unexpectedly changed will be written to a list. For instance, if an invalid Instrument id is provided, it will be removed from the timeline and a notice will be written. If a timeline is rejected, as much information regarding why will be placed in the (otherwise basically empty) resulting timeline. This is invaluable for development, testing, debugging, etc.

Observing Changes

In cases where inappropriate options were provided, a previously submitted timeline is provided containing changes, or optional keys have been omitted, the resulting timeline will be different from the provided one. By comparing the two it is possible to see what has changed. This can be helpful when trying to synchronize the music with some visualization or GUI, alerting you to when any important differences between the input and the output, etc.

Asking for Information

There is some information that is unknowable when providing an input timeline. This includes the results from requests like random_tempo, random_instruments, and the like within Actions, the exact beat that the time of an Action is, and other things that are difficult or impossible to know before the timeline has been processed. Editing-centric usage can benefit from this approach by allowing automatic changes to be known whether or not audio is being requested.

Ideal Use

If you are at all interested in feedback other than only audio, then a Composition is the best choice.

Working With Both

Nothing (aside from rate limiting restrictions) prevents you from requesting both a Composition and a Render at the same time. Provided that the input timeline used for both requests are identical, valid, and contains a random_seed, the music in both requests will be identical. Working this way would allow having further insight into the created music as well as the ability to hear it.