Content Reading

Detailed Description

Subpages

 Content Updates
 
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.
 
 Content Readers And Content Events
 
Reading content description follows the same pattern both from the host and from the plug-in side. ARA establishes iterator objects called content reader to access the data in small units called content events. There are several types available, each defining a certain abstract representation of its associated events.
Upon creation, content readers are bound to a given content type and to an object of which the content shall be read. Optionally the reader can be restricted to only cover a given time range. Once created, its event count is queried and the individual events are read, then the reader is disposed of. This is all done immediately, reader objects are only temporary objects that are created and destroyed from the same stack frame.
The data pointer returned when reading an event's data remains owned by the content reader and must remain valid until the reader is either another event is read or the reader is destroyed.
The events returned by the reader are sorted in an order that depends on the content type, but generally follows their appearance on the timeline. If several events appear at the same (start-)time, their order is not defined and the receiver must apply further sorting if desired.
The C++ ARA Library offers convenient content reader classes for host and plug-in developers. Host developers can read plug-in content using ARA::Host::ContentReader, and plug-in developers can use ARA::PlugIn::HostContentReader to read host content.
 
 Timeline
 
ARA expresses musical timing as a mapping between song time measured in seconds and musical time measured in quarter notes. The mapping is created by dividing the timeline into sections of constant musical tempo. These tempo sections are then annotated as a list of tempo sync points, where each point represents both the end of one and the beginning of another section. The location of a tempo sync point is specified both in song time and musical time. The actual tempo of a section can be easily derived from the relationship of the duration of the section in song time and the duration of the section in musical time (note that neither the quarters nor the seconds must necessarily be integer values here):
 
 Notes
 
Notes in ARA correspond to what a composer would notate to describe the music. Notes are described by their position in time, their pitch and their relative volume. The pitch can be interpreted as frequency, but ARA also offers a musical description of the pitch very similar to MIDI: it defines the tuning for the overall musical scale and provides an integer number to identify the pitch for each note within this tuning, along with an average detune for each note actually played. ARA pitch numbers match MIDI note numbers, so that the note A4 has the value 69. This note is also used to specify the tuning reference, commonly at 440 Hz. At 440 Hz reference tuning the ARA pitch number 0 thus equals 8.1757989 Hz. Some notes may not have a well-defined pitch, such as percussive notes. For such notes, a frequency of kARAInvalidFrequency and a pitch number of kARAInvalidPitchNumber are used.
 
 Tuning, Key Signatures and Chords (Added In ARA 2.0)
 
ARA expresses "western standard" octave-cyclic, 12-tone scales as tunings and key signatures. While some applications such as Melodyne offer a much more complex model that allows for acyclic and/or micro-tonal scales, those models usually don't map well to each others, and introduce a complexity that can not meaningfully be handled by applications with the "main stream" model. Further, there is no standardized musical theory for expressing chords in such scales. Should the actual need to deal with more complex scales arise in the future, a new content type may be added to cover this.