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.
Classes | |
| struct | ARAContentTimeRange |
| Content reader optional creation parameter: a range in time to filter content events. As an optimization hint, a content reader can be asked to restrict its data to only those events that intersect with the given time range. Reader implementations should strive to respect this request, but focus on overall performance - the events actually returned may exceed the specified range by any amount, and calling code must evaluate the returned event positions/event durations. Note that when calls accept a pointer to a content time range, that pointer is only valid for the duration of the call - the data must be evaluated/copied inside the call, and the pointer must not be stored anywhere. Further, in most of these calls the pointer to a content range may be NULL, indicating that the entire content range of the object should be read. More... | |
Typedefs | |
| typedef struct ARAContentReaderRefMarkupType * | ARAContentReaderRef |
| Reference to the plug-in side representation of a content reader (opaque to the host). | |
| typedef struct ARAContentReaderHostRefMarkupType * | ARAContentReaderHostRef |
| Reference to the host side representation of a content reader (opaque to the plug-in). | |
| struct ARAContentTimeRange |
Content reader optional creation parameter: a range in time to filter content events. As an optimization hint, a content reader can be asked to restrict its data to only those events that intersect with the given time range. Reader implementations should strive to respect this request, but focus on overall performance - the events actually returned may exceed the specified range by any amount, and calling code must evaluate the returned event positions/event durations.
Note that when calls accept a pointer to a content time range, that pointer is only valid for the duration of the call - the data must be evaluated/copied inside the call, and the pointer must not be stored anywhere. Further, in most of these calls the pointer to a content range may be NULL, indicating that the entire content range of the object should be read.
Public Attributes | |
| ARATimePosition | start |
| Events at start time are considered part of the range. | |
| ARATimeDuration | duration |
| Events at start time + duration are not considered part of the range. | |
| enum ARAContentGrade : ARAInt32 |
Content grade: degree of reliability of the provided content information. The most prominent use of the content grade is to solve conflicts between data provided by the host and data found via analysis on the plug-in side. Another example is that when being notified about content changes in the plug-in, a host may choose to trigger certain automatic updates only if the grade of the content is above a certain reliability threshold.
| enum ARAContentType : ARAInt32 |
Types of data that can be shared between host and plug-in.
| Enumerator | |
|---|---|
| kARAContentTypeNotes | Returns const ARAContentNote * for each note. |
| kARAContentTypeTempoEntries | Returns const ARAContentTempoEntry * for each tempo sync point. |
| kARAContentTypeBarSignatures | Returns const ARAContentBarSignature * for each bar signature change. In the original ARA 1 API, this value was called kARAContentTypeSignatures - while its name has been changed with ARA 2 to distinguish it from kARAContentTypeKeySignatures, its semantics and binary encoding are still the same. |
| kARAContentTypeStaticTuning | Returns single const ARAContentTuning *. |
| kARAContentTypeKeySignatures | Returns const ARAContentKeySignature * for each key signature change. |
| kARAContentTypeSheetChords | Returns const ARAContentChord * for each chord in a lead-sheet-like notation. (i.e. the sheet chord can imply notes that are not actually played in the audio, or vice versa. also, sheet chords are typically quantized to integer beats or even bars.) |