Content Updates

Detailed Description


There are several levels of abstraction when analyzing musical recordings. Initially, there is the signal in its "physical" form. On the next level, the signal interpreted as a series of musical events - the notes played when creating the signal. These notes and their relationship in time and pitch can be interpreted further, leading to abstractions like tempo, bar signatures, key signatures, tuning and chords.
Updates may happen on any of these levels, both independently or concurrently. In the most simple but most unlikely case, the signal is completely replaced, and all the higher abstractions therefore also invalidated. This also means that all user edits done in an audio modification will be lost. More likely is a minor modification of the signal, such as applying a high pass filtering to remove rumble in the audio source. This will not change any higher abstractions (all notes etc. remain the same), so any edits inside the audio modification or any notation of the music based on the analysis will remain intact. Another case is the correction of the analysis by the user. The signal does not change in this case, but mis-detected notes are added or removed so the mid-level abstraction which is considered with the notes changes. Whether or not this also changes higher interpretations such as the detected harmonic structure depends on the case at hand.
ARA defines a set of flags that allow to communicate the level of change, which helps to avoid unnecessary flushing of the user edits inside an audio modification and allows for optimizations of the analysis. The flags are providing a guarantee what has NOT changed. This may seem odd at first but if for example a given host does not know about harmonies, it cannot make any assumption about whether these have changed or not.

Enumeration Type Documentation

◆ ARAContentUpdateFlags

Flags indicating the scope of a content update. If notifying the API partner about a content update, the caller can make guarantees about which abstractions of the signal are unaffected by the given change. The enum flags describing these abstractions are or'd together into a single ARAInt32 value.
The C++ ARA Library encapsulates content updates in the ARA::ContentUpdateScopes class.

Enumerator
kARAContentUpdateEverythingChanged 

No flags set means update everything.

kARAContentUpdateSignalScopeRemainsUnchanged 

The actual signal is unaffected by the change. Note that in some cases even when the signal is considered to be unchanged, the values of the actual sample data may change, e.g. if the user applies a sample rate conversion.

kARAContentUpdateNoteScopeRemainsUnchanged 

Content information for notes, beat-markers etc. is unaffected by the change.

kARAContentUpdateTimingScopeRemainsUnchanged 

Content information for tempo, bar signatures etc. is unaffected by the change.

kARAContentUpdateTuningScopeRemainsUnchanged 

Content readers for tuning (static or dynamic) are unaffected by the change. (added in ARA 2.0)

kARAContentUpdateHarmonicScopeRemainsUnchanged 

Content readers for key signatures, chords etc. are unaffected by the change. (added in ARA 2.0)