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.
Classes | |
| struct | ARAContentTuning |
| Content reader event class: periodic 12-tone tuning table provided by kARAContentTypeStaticTuning. Defines the tuning of each pitch class in the octave-cyclic 12-tone pitch system. Allows to import (12-tone) Scala files. Stretched tunings are not supported by ARA at this point, but may be added in a future release as an additional tuning stretch curve applied on top of this average tuning. ARA defines a single overall tuning (i.e. there's always only one event for this reader). 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 | ARAContentKeySignature |
| Content reader event class: key signature provided by kARAContentTypeKeySignatures. Defines the usage of each pitch class in the octave-cyclic 12-tone pitch system. This content type describes the key signatures as would be annotated in a score, not the local scales (which may be using some out-of-key notes via additional per-note accidentals). The event position relates to ARAContentTempoEntry, a valid tempo map must be provided by any provider of ARAContentBarSignature. Each key signature is valid until the following one, the first key signature is assumed to also be valid any time before it is actually defined. 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... | |
| struct | ARAContentChord |
| Content reader event class: chords provided by kARAContentTypeSheetChords. The event position relates to ARAContentTempoEntry, a valid tempo map must be provided by any provider of ARAContentBarSignature. Each chord is valid until the following one, and the first chord is assumed to also be valid any time before it is actually defined (i.e. its position is effectively ignored). The "undefined chord" markup (all intervals unused) can be used to express a range where no chord is applicable. Such gaps may appear between "regular" chords, or they can be used to limit the otherwise infinite duration of the first and last "regular" chord if desired. 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... | |
Typedefs | |
| typedef ARAInt32 | ARACircleOfFifthsIndex |
| The root of a key signature or chord as an index (or angle) in the circle of fifths from 'C'. Enharmonic equivalents such as Db and C# are distinguished: More... | |
| typedef ARAByte | ARAKeySignatureIntervalUsage |
| The ARAKeySignatureIntervalUsage defines whether a particular interval is used (kARAKeySignatureIntervalUsed) or not (kARAKeySignatureIntervalUnused). Future extensions of the API could further specify the usage of a given interval, similar to the chord intervals below. However since there are currently no clear-cut use cases for such a distinction, this is not yet specified. | |
| typedef ARAByte | ARAChordIntervalUsage |
| The ARAChordIntervalUsage defines whether a particular interval is used (kARAChordIntervalUsed) or not (kARAChordIntervalUnused), or if used may instead further specify the function of the interval in the chord by specifying its diatonic degree: 1 = unison, 3 = third, up to 13 = thirteenth Note that the bass note of a chord is treated separately, see below. | |
Markup values of ARAKeySignatureIntervalUsage. | |
| constexpr ARAKeySignatureIntervalUsage | kARAKeySignatureIntervalUnused { 0x00 } |
| Marks an interval of the ARAContentKeySignature as unused. | |
| constexpr ARAKeySignatureIntervalUsage | kARAKeySignatureIntervalUsed { 0xFF } |
| Marks an interval of the ARAContentKeySignature as used. | |
Markup values of ARAChordIntervalUsage. | |
common degrees per note if root is C:
C D E F G A B
1 b9 2/9 #9/3 3 4/11 #11/b5 5 #5/b6/b13 6/7/13 7/#13 7
(7 only if dim)
| |
| constexpr ARAChordIntervalUsage | kARAChordDiatonicDegree1 { 0x01 } |
| ARAChordIntervalUsage value when the corresponding chromatic interval is used with the given diatonic function. | |
| constexpr ARAChordIntervalUsage | kARAChordDiatonicDegree2 { 0x02 } |
| ARAChordIntervalUsage value when the corresponding chromatic interval is used with the given diatonic function. | |
| constexpr ARAChordIntervalUsage | kARAChordDiatonicDegree3 { 0x03 } |
| ARAChordIntervalUsage value when the corresponding chromatic interval is used with the given diatonic function. | |
| constexpr ARAChordIntervalUsage | kARAChordDiatonicDegree4 { 0x04 } |
| ARAChordIntervalUsage value when the corresponding chromatic interval is used with the given diatonic function. | |
| constexpr ARAChordIntervalUsage | kARAChordDiatonicDegree5 { 0x05 } |
| ARAChordIntervalUsage value when the corresponding chromatic interval is used with the given diatonic function. | |
| constexpr ARAChordIntervalUsage | kARAChordDiatonicDegree6 { 0x06 } |
| ARAChordIntervalUsage value when the corresponding chromatic interval is used with the given diatonic function. | |
| constexpr ARAChordIntervalUsage | kARAChordDiatonicDegree7 { 0x07 } |
| ARAChordIntervalUsage value when the corresponding chromatic interval is used with the given diatonic function. | |
| constexpr ARAChordIntervalUsage | kARAChordDiatonicDegree9 { 0x09 } |
| ARAChordIntervalUsage value when the corresponding chromatic interval is used with the given diatonic function. | |
| constexpr ARAChordIntervalUsage | kARAChordDiatonicDegree11 { 0x0B } |
| ARAChordIntervalUsage value when the corresponding chromatic interval is used with the given diatonic function. | |
| constexpr ARAChordIntervalUsage | kARAChordDiatonicDegree13 { 0x0D } |
| ARAChordIntervalUsage value when the corresponding chromatic interval is used with the given diatonic function. | |
| constexpr ARAChordIntervalUsage | kARAChordIntervalUsed { 0xFF } |
| ARAChordIntervalUsage value when the corresponding chromatic interval is used, but its diatonic function is unknown. | |
| constexpr ARAChordIntervalUsage | kARAChordIntervalUnused { 0x00 } |
| ARAChordIntervalUsage value when the corresponding chromatic interval is not used. | |
| struct ARAContentTuning |
Content reader event class: periodic 12-tone tuning table provided by kARAContentTypeStaticTuning. Defines the tuning of each pitch class in the octave-cyclic 12-tone pitch system. Allows to import (12-tone) Scala files. Stretched tunings are not supported by ARA at this point, but may be added in a future release as an additional tuning stretch curve applied on top of this average tuning. ARA defines a single overall tuning (i.e. there's always only one event for this reader). 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 | |
| float | concertPitchFrequency |
| Frequency of the concert pitch 'A' in hertz, defaulting to kARADefaultConcertPitchFrequency aka 440.0f. | |
| ARACircleOfFifthsIndex | root |
| Root key for the following per-key tunings. | |
| float | tunings [12] |
| Tuning of each note pitch as an offset from the equal temperament tuning in cent. Each entry defaults to 0.0f. The first entry relates to the root, increasing chromatically up to the full octave. More... | |
| ARAUtf8String | name |
| User-readable name of the tuning as displayed in the content provider. The tuning name may or may not include the root note, depending on context - for example, equal temperament does not care about the root note so it is always omitted, Werckmeister tunings typically imply a root note of C unless noted explicitly otherwise, etc. The name is provided only for display purposes, in case the receiver wants to display the tuning exactly as done in the sender instead of utilizing its built-in naming system for tunings based on the above properties. The receiver must copy the name, the pointer may be only valid as long as the containing ARAContentTuning struct. It may be NULL if the provider does not provide a name for the tuning in its UI. | |
| float ARAContentTuning::tunings[12] |
Tuning of each note pitch as an offset from the equal temperament tuning in cent. Each entry defaults to 0.0f. The first entry relates to the root, increasing chromatically up to the full octave.
Example:
Arabian Rast: {0.0f, 0.0f, 0.0f, 0.0f, -50.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, -50.0f}
| struct ARAContentKeySignature |
Content reader event class: key signature provided by kARAContentTypeKeySignatures. Defines the usage of each pitch class in the octave-cyclic 12-tone pitch system. This content type describes the key signatures as would be annotated in a score, not the local scales (which may be using some out-of-key notes via additional per-note accidentals). The event position relates to ARAContentTempoEntry, a valid tempo map must be provided by any provider of ARAContentBarSignature. Each key signature is valid until the following one, the first key signature is assumed to also be valid any time before it is actually defined. 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 | |
| ARACircleOfFifthsIndex | root |
| Root key of the signature. | |
| ARAKeySignatureIntervalUsage | intervals [12] |
| Scales intervals (aka scale mode) of the signature. The index of this arrays entry is the chromatic interval to the keys root pitch class. More... | |
| ARAUtf8String | name |
| Optional user-readable name of the key signature as displayed in the content provider (including the root note name). Typically, the receiver has a built-in system to generate a suitable name for a key signature based on its internal abstractions. However, this internal model might cover all states that the ARA model can provide, or vice versa. If there is such a mismatch, the internal name generation algorithm will likely fail - in which case the receiver may fall back to the string provided here. Note that the utility library that ships with the ARA SDK contains C++ code that can create a proper name for the most common key signatures, otherwise falling back to this name. The receiver must copy the name, the pointer may be only valid as long as the containing ARAContentKeySignature struct. It may be NULL if the provider does not provide a name for the key signature in its UI. When encoding the string to send it across the ARA API, flat and sharp symbols must be represented with the Unicodes 0x266D "MUSIC FLAT SIGN" and 0x266F "MUSIC SHARP SIGN" respectively (as also required for ARAContentChord::name). | |
| ARAQuarterPosition | position |
| Start time in quarter notes, see ARAContentTempoEntry. | |
| ARAKeySignatureIntervalUsage ARAContentKeySignature::intervals[12] |
Scales intervals (aka scale mode) of the signature. The index of this arrays entry is the chromatic interval to the keys root pitch class.
Examples (Hex Values):
major {FF, 00, FF, 00, FF, FF, 00, FF, 00, FF, 00, FF}
natural minor {FF, 00, FF, FF, 00, FF, 00, FF, FF, 00, FF, 00}
| struct ARAContentChord |
Content reader event class: chords provided by kARAContentTypeSheetChords. The event position relates to ARAContentTempoEntry, a valid tempo map must be provided by any provider of ARAContentBarSignature. Each chord is valid until the following one, and the first chord is assumed to also be valid any time before it is actually defined (i.e. its position is effectively ignored). The "undefined chord" markup (all intervals unused) can be used to express a range where no chord is applicable. Such gaps may appear between "regular" chords, or they can be used to limit the otherwise infinite duration of the first and last "regular" chord if desired. 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 | |
| ARACircleOfFifthsIndex | root |
| Root note of the chord. Examples: F: root = -1 C/E: root = 0 G/D: root = 1. | |
| ARACircleOfFifthsIndex | bass |
| Bass note of the chord. Usually identical to the root, but may be different from root, or even different from any other note represented by the intervals below. Examples: F: bass = -1 C/E: bass = 4 G/D: bass = 2. | |
| ARAChordIntervalUsage | intervals [12] |
| Chords intervals, defining gender, suspensions and extensions. The index of this array's entry is the chromatic interval to the chords root pitch class. Depending on the chord's musical interpretation, the interval corresponding to the bass note may or may not be included in here. If all intervals are unused, this chord represents an "undefined chord", which is used as a markup for gaps in the chord progression. More... | |
| ARAUtf8String | name |
| Optional user-readable name of the chord as displayed in the content provider (including the root note name). Typically, the receiver has a built-in system to generate a suitable name for a chord based on its internal abstractions. However, this internal model might cover all states that the ARA model can provide, or vice versa. If there is such a mismatch, the internal name generation algorithm will likely fail - in which case the receiver may fall back to the string provided here. Note that the utility library that ships with the ARA SDK contains C++ code that can create a proper name for any ARA chord, completely avoiding the necessity to use this name string. The receiver must copy the name, the pointer may be only valid as long as the containing ARAContentChord struct. It may be NULL if the provider does not provide a name for the chord in its UI. Chord annotation systems often use symbols in addition to Latin letters and Arabic numbers. Depending on UI considerations such as the font in use, different applications may use different Unicode codes to represent the same symbols internally. In order to send strings containing such symbol across the ARA API without ambiguities, they must be mapped to the following Unicode codes: More... | |
| ARAQuarterPosition | position |
| Start time in quarter notes, see ARAContentTempoEntry. | |
| ARAChordIntervalUsage ARAContentChord::intervals[12] |
Chords intervals, defining gender, suspensions and extensions. The index of this array's entry is the chromatic interval to the chords root pitch class. Depending on the chord's musical interpretation, the interval corresponding to the bass note may or may not be included in here. If all intervals are unused, this chord represents an "undefined chord", which is used as a markup for gaps in the chord progression.
Examples (hexadecimal values):
major {FF, 00, 00, 00, FF, 00, 00, FF, 00, 00, 00, 00}
major {01, 00, 00, 00, 03, 00, 00, 05, 00, 00, 00, 00}
minor {01, 00, 00, 03, 00, 00, 00, 05, 00, 00, 00, 00}
major 13 {01, 00, 09, 00, 03, 00, 00, 05, 00, 0D, 07, 00}
major add13 {01, 00, 00, 00, 03, 00, 00, 05, 00, 0D, 00, 00}
major 6 {01, 00, 00, 00, 03, 00, 00, 05, 00, 06, 00, 00}
| ARAUtf8String ARAContentChord::name |
Optional user-readable name of the chord as displayed in the content provider (including the root note name). Typically, the receiver has a built-in system to generate a suitable name for a chord based on its internal abstractions. However, this internal model might cover all states that the ARA model can provide, or vice versa. If there is such a mismatch, the internal name generation algorithm will likely fail - in which case the receiver may fall back to the string provided here. Note that the utility library that ships with the ARA SDK contains C++ code that can create a proper name for any ARA chord, completely avoiding the necessity to use this name string. The receiver must copy the name, the pointer may be only valid as long as the containing ARAContentChord struct. It may be NULL if the provider does not provide a name for the chord in its UI.
Chord annotation systems often use symbols in addition to Latin letters and Arabic numbers. Depending on UI considerations such as the font in use, different applications may use different Unicode codes to represent the same symbols internally. In order to send strings containing such symbol across the ARA API without ambiguities, they must be mapped to the following Unicode codes:
| typedef ARAInt32 ARACircleOfFifthsIndex |
The root of a key signature or chord as an index (or angle) in the circle of fifths from 'C'. Enharmonic equivalents such as Db and C# are distinguished:
... -5: Db ... -1: F 0: C 1: G 2: D ... 7: C# ... 11: E# ...