Content Readers And Content Events

Detailed Description


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

Class Documentation

◆ ARAContentTimeRange

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.
 

Enumeration Type Documentation

◆ ARAContentGrade

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.

Enumerator
kARAContentGradeInitial 

Default data used as placeholder value. This grade can be used when no actual content information is present, such as the widely used default tempo of 120 bpm. This grade will typically be encountered while the analysis is still pending or still being executed. It may also be used if analysis failed to provide any meaningful results.

kARAContentGradeDetected 

Data was provided by automatic content detection without any user intervention. Since the user has not reviewed the data, it may not be reliable in some cases.

kARAContentGradeAdjusted 

Data was reviewed or edited by the user but not specifically approved as fully correct. This is the typical state of the data in the regular studio workflow.

kARAContentGradeApproved 

Data has been specifically approved by the user as fully correct, e.g. for shipping it as part of a content library.

◆ ARAContentType

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