Detailed Description


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):

                    rightTempoEntry.quarterPosition - leftTempoEntry.quarterPosition
sectionTempoInBpm = ----------------------------------------------------------------- * 60.0 sec
                    rightTempoEntry.timePosition  - leftTempoEntry.timePosition

The advantage of providing such sync points whenever the tempo changes instead of specifying the tempo directly is that there are no rounding errors that sum up over time - whenever the tempo changes, this happens fully in sync. The disadvantage of this representation is that there is no way to express the tempo before the first and after the last tempo sync point, because the initial and final tempo sections stretch "forever" into the past resp. future. ARA works around this by defining that the initial tempo is equal to the tempo between the first and the second tempo sync point and that the final tempo is equal to the tempo between the last-but-one and the last tempo sync point. This means that there must always be at least 2 sync points in a valid ARA time line definition.
To ease parsing the timeline, ARA further requires that there must be a tempo sync point given at quarter 0, even if there is no actual tempo change at this point in time. This allows for precisely determining any offset between time 0 seconds and quarter 0 without introducing possible rounding errors. (If a content range is specified, this only applies if quarter 0 is part of the content range.)
Musical timing is commonly not notated by simply counting quarter notes - instead bars are defined that form repeating patterns. ARA expresses this by providing a list of bar signatures. Like in standard musical notation, the bar signatures are expressed as a fraction of two integer values: numerator/denominator. The location of a bar signature is specified in musical time. To make sense musically, the distance between two bar signatures must be an integer multiple of the bar length of the earlier of the two signatures (even though the bar length itself may not be integer, e.g. when using a measure of 7/8). Note that when implementing the translation of these values to/from your code, potential rounding issues must be handled properly to ensure the desired positions are extracted.

Classes

struct  ARAContentTempoEntry
 Content reader event class: tempo map provided by kARAContentTypeTempoEntries. Event sort order is by timePosition. As with all content readers, a pointer to this struct retrieved via getContentReaderDataForEvent() is still owned by the callee and must remain valid until either getContentReaderDataForEvent() is called again or the reader is destroyed via destroyContentReader(). More...
 
struct  ARAContentBarSignature
 Content reader event class: bar signatures provided by kARAContentTypeBarSignatures. The event position relates to ARAContentTempoEntry, a valid tempo map must be provided by any provider of ARAContentBarSignature. Each bar signature is valid until the following one, and the first bar signature is assumed to also be valid any time before it is actually defined. The location of the first bar signature is also considered to be the location of bar 1. Event sort order is by position. As with all content readers, a pointer to this struct retrieved via getContentReaderDataForEvent() is still owned by the callee and must remain valid until either getContentReaderDataForEvent() is called again or the reader is destroyed via destroyContentReader(). More...
 

Class Documentation

◆ ARAContentTempoEntry

struct ARAContentTempoEntry

Content reader event class: tempo map provided by kARAContentTypeTempoEntries. Event sort order is by timePosition. As with all content readers, a pointer to this struct retrieved via getContentReaderDataForEvent() is still owned by the callee and must remain valid until either getContentReaderDataForEvent() is called again or the reader is destroyed via destroyContentReader().

Public Attributes

ARATimePosition timePosition
 Time in seconds relative to the start of the song or the audio source/modification.
 
ARAQuarterPosition quarterPosition
 Corresponding time in quarter notes.
 

◆ ARAContentBarSignature

struct ARAContentBarSignature

Content reader event class: bar signatures provided by kARAContentTypeBarSignatures. The event position relates to ARAContentTempoEntry, a valid tempo map must be provided by any provider of ARAContentBarSignature. Each bar signature is valid until the following one, and the first bar signature is assumed to also be valid any time before it is actually defined. The location of the first bar signature is also considered to be the location of bar 1. Event sort order is by position. As with all content readers, a pointer to this struct retrieved via getContentReaderDataForEvent() is still owned by the callee and must remain valid until either getContentReaderDataForEvent() is called again or the reader is destroyed via destroyContentReader().

Public Attributes

ARAInt32 numerator
 Numerator of the bar signature.
 
ARAInt32 denominator
 Denominator of the bar signature.
 
ARAQuarterPosition position
 Start time in quarter notes, see ARAContentTempoEntry.