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:
- A Composition allows you to submit a timeline and receive a (potentially modified) timeline in return.
- A Render allows you to submit a timeline and receive audio in return.
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.
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.
The top level JSON object of the timeline contains an easily overlooked key
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.
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
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
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.