Module Documentation
Here is a list of all modules:
[detail level 123]
 ▼Basic TypesPre-defined types to ensure binary compatibility between plug-in and host. These types must be used when crossing the API boundary, but intermediate types can be used internally. For example, you can use your own struct representing color, but when defining color for ARA operations your internal color struct must be converted to ARAColor
 Fixed-size IntegersARA defines platform-independent signed integers with fixed size of 32 or 64 bits and for a pointer-sized signed integer
 Boolean ValuesSince Microsoft still doesn't fully support C99 and fails to provide <stdbool.h>, we need to roll our own. On the other hand this ensures a fixed size of 32 bits, too. 32 bits were chosen so that ARABool is consistent with the other enum-like data types such as ARAContentType. Since ARABool is only used in temporary structs that are valid only for the duration of a call and likely passed in a register in most cases, there's no point in trying to optimize for size by using 8 bit boolean types. Note that in order to avoid conversion warnings in Visual Studio, you should not directly cast bool to ARABool or vice versa, but instead use a ternary operator or a comparison like this:
 EnumsARA enums can either be used to represent distinct enumerations, or to declare C-compatible constant integer flags that can be or'd together as bit masks. To ensure binary compatibility between plug-in and host, the underlying type of ARA enums is always ARAInt32
 StringsUser-readable texts are stored as UTF-8 encoded unicode strings. It's not defined if and how the string is normalized - if either side has requirements regarding normalization, it needs to apply these after reading the string from the other side. Unicode rules apply regarding normalization, comparison etc. Both hosts and plug-ins are required to support at least all ISO/IEC 8859-1 based characters (from U+0020 up to U+007E and from U+00A0 up to U+00FF) in their text display rendering
 Common Time-Related Data TypesSome basic data types used in several contexts
 Sampled Audio DataThe audio samples are encoded using these format descriptions. The data alignment and byte order always matches the machine's native layout
 ColorARA color representation
 Object ReferencesARA uses pointer-sized unique identifiers to reference objects at runtime - typical C++-based implementations will use the this-pointer as ID. C-style code could do the same, or instead choose to use array indices as ID.
Those objects that are archived by the host can be persistently identified by an ARAPersistentID that the host assigns as a property of the object
 ▼API VersionsARA implements two patterns for its ongoing evolution of the API: incremental, fully-backwards compatible additions by appending features to it versioned structs, and major, potentially incompatible updates through its API generations
 API GenerationsWhile purely additive features can be handled through ARA's versioned structs, ARA API generations allow for non-backwards-compatible, fundamental API changes. For hosts that rely on a certain minimum ARA feature set provided by the plug-ins, it also offers a convenient way to filter incompatible plug-ins. Plug-ins on the other hand can use the API generation chosen by the host to optimize their feature set for the given environment, such as disabling potentially costly fallback code required for older hosts when running in a modern host
 Versioned StructsIn the various interface and data structs used in the ARA API, callback pointers or data fields may be added in later revisions of the current API generation. Each of these extensible structs starts with a structSize data field that describes how much data is actually contained in the given instance of the struct, thus allowing to determine which of the additional features are supported by the other side. All struct members that are later additions will be marked with the macro ARA_ADDENDUM. Members that are not marked as addendum must always be present in the struct. Accordingly, the minimum value of structSize is the size of the struct in the first API revision. When creating such a struct in your code, the maximum value is the size of the struct in the current API revision used at compile time. When parsing a struct received from the other side, the value may be even larger since the other side may use an even later API revision.
Note that when implementing ARA, it is important not to directly use sizeof() when filling in the structSize values. If you later update to newer API headers, the values of sizeof() will change and your code thus will be broken until you've implemented all additions. Instead, use the ARA_IMPLEMENTED_STRUCT_SIZE macro or similar techniques added in the ARA C++ library dispatcher code, see there
 DebuggingARA strictly separates programming errors from runtime error conditions such as missing files, CPU or I/O overloads etc. Runtime errors occur when accessing external data and resources, which is always done on the host side of the ARA API. Accordingly, the host has the responsibility to detect any such errors and to properly communicate the issue to the user. Since ARA leverages existing technologies, host implementations usually already feature proper code for this. With the error reporting done on the host side, plug-ins do not need to know any details about runtime errors - a simple bool to indicate success or failure is sufficient for implementing normal operation or graceful error recovery. Thus, ARA does not need to define error codes for communicating error details across the API. As an example, consider audio data being read from a server across the network - if the connection breaks, the host will recognize the issue and bring up an according user notification. If the plug-in requests the now inaccessible audio data, the host simply flags that an error occurred and the plug-in can either retry later or use silence as fallback data.
A different kind of errors are programming errors. If either side fails to properly follow the API contract, undefined behavior can occur. Tracking down such bugs from one side only can be difficult and very time consuming, thus ARA strives to aid developers in this process by defining a global assert function that both sides call whenever detecting programming errors related to the ARA API. When debugging (or when running unit tests), either side can provide the code for the assert function, so that no matter what side you're debugging from you can always inject your custom assert handling in order to be able to set proper breakpoints etc. The assert function is only a debug facility: it will usually be disabled on end user systems, and it must never be used for flow control in a shipping product. Instead, each side should implement graceful fallback behavior after asserting the programming error, e.g. by defining a special value for invalid object refs (NULL or -1, depending on the implementation) which will be returned as a placeholder whenever object creation fails due to a programming error on the other side and then filtering this value accordingly whenever objects are referenced
 ▼ARA Model Graph
 DocumentThe document is the root object for a model graph and typically represents a piece of music such as a song or an entire performance. It is bound to a document controller in a 1:1 relationship. The document controller is used to manage the entire graph it contains. Because of the 1:1 relationship, the document is never specified when calling into the document controller. Edits of the document and any of the objects it contains are done in cycles started with ARADocumentControllerInterface::beginEditing() and concluded with ARADocumentControllerInterface::endEditing(). This allows plug-ins to deal with any render thread synchronization that may be necessary, as well as postponing any internal updates until the end of the cycle when the ARA graph has its full state available. A document is the root object for persistency and is the owner of any amount of associated audio sources, region sequences and musical contexts.
Plug-in developers using the C++ ARA Library can use the ARA::PlugIn::Document class
 Musical ContextA musical context describes both rhythmical concepts of the music such as bars and beats and their distribution over time, as well as harmonic structures and their distribution over time. A musical context is always owned by one document. Musical contexts are not persistent when storing documents, instead the host re-creates them as needed.
Plug-in developers using the C++ ARA Library can use the ARA::PlugIn::MusicalContext class
 Region Sequences (Added In ARA 2.0)Region sequences allow hosts to group playback regions, typically by "tracks" or "lanes" in their arrangement. Each sequence is associated with a musical context, and all regions in a sequence will be adapted to that same context. Further, all regions within a sequence are expected to play back through the same routing (incl. same latency), typically the same "mixer track" or "audio channel". Regions in a sequence can overlap, and such overlapping regions will sound concurrently. A region sequence is always owned by one document, and refers to a musical context. Region sequences are not persistent when storing documents, instead the host re-creates them as needed.
Plug-in developers using the C++ ARA Library can use the ARA::PlugIn::RegionSequence class
 Audio SourceAn audio source represents a continuous sequence of sampled audio data. Typically a host will create an audio source object for each audio file used with ARA plug-ins. Conceptually, the contents of an audio source are immutable (even though updates are possible, this is an expensive process, and user edits based on the modified content may get lost). An audio source is always owned by one document, and in turn owns any amount of associated audio modifications. Audio sources are persistent when storing documents.
Plug-in developers using the C++ ARA Library can use the ARA::PlugIn::AudioSource class
 Audio ModificationAn audio modification contains a set of musical edits that the user has made to transform the content of an audio source when rendered by the ARA plug-in. An audio modification is always owned by one audio source, and in turn owns any amount of associated playback regions. Audio modifications are persistent when storing documents.
Plug-in developers using the C++ ARA Library can use the ARA::PlugIn::AudioModification class
 Playback RegionA playback region is a reference to an arbitrary time section of an audio modification, mapped to a certain section of playback time. It is linked to a region sequence, which in turn is linked to a musical context. All playback regions that share the same audio modification play back the same musical content, but may adapt that content to the given section of the musical context and to the content of other regions in the same region sequence (see content based fades). Note that if a plug-in offers any user settings to control this adaptation (such as groove settings), then these settings should be part of the audio modification state, not of the individual playback regions. A playback is always owned by one audio modification, and refers to a region sequence. Playback regions are not persistent when storing documents, instead the host re-creates them as needed.
Plug-in developers using the C++ ARA Library can use the ARA::PlugIn::PlaybackRegion class
 ▼Content Reading
 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
 ▼Host Interfaces
 Audio Access ControllerThis interface allows plug-ins to read the audio data from the host in a random access order. It is used from multiple threads, both host and plug-in need to carefully observe the threading rules for each function. The basic design idea is that each audio reader is used single-threaded, but multiple audio readers can work concurrently (even on the same audio source). Audio readers can be considered random access iterators, and like most iterators operate on conceptually constant data structures. If the host changes sample rate, channel count or other audio source properties that the reader relies upon, the plug-in must discard any existing audio readers for the source and later re-create them based on the new configuration. The host can temporarily disable access to the audio source in order to control the exact timing of stopping the readers from accessing the source. Whenever an audio reader is destroyed, the plug-in is responsible for thread safety - it may need to block until a concurrent read operation on the I/O thread has finished. Hosts must take care in their audio reader implementation to avoid potential deadlocks in this situation. Note that when rendering, the audio source will often not be read in a consecutive order - depending on the edits the user applied at audio modification level, the access may jump back and forth quite often. The reader implementation should be optimized accordingly.
Host developer using C++ ARA Library can implement the ARA::Host::AudioAccessControllerInterface. For plug-in developers this interface is wrapped by the ARA::PlugIn::HostAudioAccessController
 Archiving ControllerThis interface allows plug-ins to read and write archives with minimal memory impact. It also allows for displaying progress when archiving or unarchiving model graphs. Its functions may only be called during the archiving/unarchiving process.
Because of the potentially large size of the archives, ARA does not use simple monolithic memory blocks as known from many companion APIs. Instead, it establishes a stream-like archive format so that copying large blocks of memory can be avoided. Plug-ins that create large archives should use any mean of data reduction that is appropriate to reduce the archive size. For example, they may implement gzip compression. Since it has good knowledge of the characteristics of the data, it can configure the compression algorithms so that optimal results are achieved. Consequently, there's no point for host to try to compress the data any further with generic algorithms.
Hosts that support both 32 and 64 bit architectures shall be aware of the fact that ARA archive sizes are pointer-sized data types, so they will differ in bit width between these architectures. This must be taken into account when storing the archive size in the host's document structure. Also, when importing documents from 64 bit into 32 bit, the host must check whether the archive is small enough to be loaded at all (i.e. its size fits into 32 bits). If not, it shall refuse to load the archive and provide a proper error message. This may seem like a restriction, but the reasoning behind this is that if the archive already exceeds the available address space, the resulting unarchived graph will do so too.
There's no creation or destruction call for the archive readers/writers because they are provided by the host for the duration of the (un-)archiving process, so the lifetime is implicitly defined.
When using API generation 1 or older and loading an archive through the deprecated functions begin-/endRestoringDocumentFromArchive(), plug-ins may choose to access the associated archive reader upon either begin- or endRestoringDocumentFromArchive() or even upon both calls, as suitable for their implementation - hosts must be able to provide the requested data during the duration of both calls.
Host developer using C++ ARA Library can implement the ARA::Host::ArchivingControllerInterface. For plug-in developers this interface is wrapped by the ARA::PlugIn::HostArchivingController
 Model Content Access ControllerThis optional interface provides access to host model data such as the musical context. Its functions may only be called from ARADocumentControllerInterface.create...() or update...() for the object currently created/updated, or from ARADocumentControllerInterface::endEditing() for any object.
Host developer using C++ ARA Library can implement the ARA::Host::ContentAccessControllerInterface. For plug-in developers this interface is wrapped by the ARA::PlugIn::HostContentAccessController
 Model Update Controller InterfaceThis optional host interface allows the host to be notified about content changes in the plug-in. Its functions may only be called from ARADocumentControllerInterface::notifyModelUpdates().
Host developer using C++ ARA Library can implement the ARA::Host::ModelUpdateControllerInterface. For plug-in developers this interface is wrapped by the ARA::PlugIn::HostModelUpdateController
 Playback Controller InterfaceThis optional host interface allows the plug-in to request playback state changes. The functions in this interface may be called concurrently, but not from render-threads. The host may choose to ignore any of these requests. The requests will typically be scheduled and executed with some delay. The current state of playback is transmitted via the companion API.
Host developer using C++ ARA Library can implement the ARA::Host::PlaybackControllerInterface. For plug-in developers this interface is wrapped by the ARA::PlugIn::HostPlaybackController
 Document Controller InstanceThe callbacks into the host are published by the host when creating a document controller on the plug-in side to maintain an ARA model graph. The instance struct and all interfaces and host refs therein must remain valid until the document controller is destroyed. The host can choose to create its controller objects per document controller instance, or it can share a single instance between all document controllers, whatever fits its needs. It may even mix-and-match both approaches per individual interface
 ▼Plug-In Interfaces
 Partial Document Persistency
These optional filters allow to only store a subset of the document graph into an archive, or only restore a subset of an archive into the document graph
 Processing Algorithm Selection
 Document ControllerARA model objects are created and managed by the ARA Document Controller provided by the plug-in. The host uses the factory and management functions of the Document Controller to create a partial copy of its model translated into the ARA world. It is created using a factory which can be either retrieved by scanning the plug-in binaries for a dedicated factory or by requesting it from a living companion plug-in instance. The host is responsible for keeping the document controller alive as long as any objects created through it are still living (kind of implicit ref-counting). This means that its live time is independent of the companion plug-in instances - they may all be gone at some point but the ARA graph may still be accessed through its document controller. The host must also keep the document controller alive as long as any companion plug-in instance which it has bound to it is actively used. The actual destruction of the plug-in instance may be done later (to ease reference counting implementation), but rendering the plug-in, accessing its state or showing its UI is only valid as long as the ARA document controller it has been bound is still alive. Except for some rare, explicitly documented functions like getPlaybackRegionHeadAndTailTime(), the document controller interface must always be called from the same thread - usually hosts will manage their internal model as well as the attached ARA graph from the application's main thread, triggered from the main run loop. If a host decides to use a different thread for maintaining the ARA model, it may need to implement some sort of locking so that its updates on the ARA model thread do not interfere concurrently with the main run loop's event processing as it drives the plug-in's UI code and notification system.
Plug-in developers using C++ ARA Library can implement the ARA::PlugIn::DocumentControllerInterface, or extend the already implemented ARA::PlugIn::DocumentController class as needed. For host developers this interface is wrapped by the ARA::Host::DocumentController
 Document Controller InstanceThe callbacks into the plug-in are published by the plug-in when the host requests the creation of a document controller via the factory. The instance struct and all interfaces and host refs therein must remain valid until the document controller is destroyed. The plug-in can choose to create its controller objects per document controller instance, or it can share a single instance between all document controllers, whatever fits its needs. It may even mix-and-match both approaches per individual interface
 Plug-In FactoryStatic entry into ARA, allows to create ARA objects
 ▼Plug-In ExtensionThe plug-in extension provides ARA-specific additional functionality per companion plug-in instance. On a conceptual level, the plug-in extension is not an object of its own, but merely a set of additional interfaces of the companion plug-in instance, augmenting it with a few ARA-specific features in a fashion that is independent from the actual companion API in use. Accordingly, it is coupled 1:1 to the companion plug-in instance and its lifetime matches the lifetime of the companion plug-in instance (no separate destruction function needed). Along the same lines, plug-in extensions themselves are not persistent.
The plug-in extension is exposed towards the host when it binds a plug-in instance as created by the companion APIs to a specific ARA model graph, represented by its associated document controller. This setup call is executed via a vendor-specific extension of the companion API and may only be made once. It shifts the "normal" companion plug-in into the ARA world, and once established, this coupling cannot be undone, it remains active until the plug-in instance is destroyed.
Note that both performing the explicit binding and the implicit unbinding upon destruction will likely need to access plug-in internal data structures shared with with the document controller implementation. To avoid adding costly thread safety measures when maintaining this shared state, hosts should always perform these operations from the document controller thread (typically the main thread). This restriction may or may not apply when using the same companion API without ARA, so host developers might need to add extra precaution for the ARA case.
When ARA is enabled, the renderer behavior has slightly different semantics compared to the non-ARA use case. Since ARA renderers are essentially generators that use non-realtime data to generate realtime signals, they do not use the realtime input signal for processing. Playback renderers will simply ignore their inputs, but editor renderers will always add their output signal to the input signal provided by the host. If a plug-in assumes both rendering roles, playback rendering will already ignore the inputs, so the editor rendering will directly add to the playback output, not to the input.
Since ARA 2.0, the host can explicitly establish the roles that the given instance will assume in its specific implementation upon binding the plug-in instance to the ARA document controller. Each role is associated with a dedicated feature set that only is available when the particular role has been established. Depending on the chosen roles, the following calls control which playback regions are to be rendered according to which rule. Separating roles allows for more flexible ARA integrations and optimizes resource usage. A host could for example use a playback renderer plug-in instance playback region, plus one plug-in instance per track for editor rendering and viewing all regions on that track. Amongst other behavior, the roles heavily affect the relationship between plug-in instances and playback regions. For rendering, each plug-in extension can handle multiple playback regions if desired, albeit the semantics for modifying the set of associated regions per renderer are somewhat different between playback and editor renderers, see below. For editor view purposes, the relationship is not explicit to accommodate for a very broad range of user interface concepts that need to interact with the API. Generally, each editor view is associated with all playback regions in the document controller to which the plug-in is bound. However, typically only a varying subset of those regions will be shown at any point in time, depending on the intrinsic feature set of the plug-in, and reflecting the selection that the user has performed in the host - see notifySelection()
 Playback Renderer Interface (Added In ARA 2.0)See kARAPlaybackRendererRole.
Plug-in developers using C++ ARA Library can implement the ARA::PlugIn::PlaybackRendererInterface, or extend the already implemented ARA::PlugIn::PlaybackRenderer class as needed. For host developers this interface is wrapped by the ARA::Host::PlaybackRenderer
 Editor Renderer Interface (Added In ARA 2.0)See kARAEditorRendererRole.
Plug-in developers using C++ ARA Library can implement the ARA::PlugIn::EditorRendererInterface, or extend the already implemented ARA::PlugIn::EditorRenderer class as needed. For host developers this interface is wrapped by the ARA::Host::EditorRenderer
 Editor View Interface (Added In ARA 2.0)See kARAEditorViewRole.
Users will often reconfigure the plug-in view through scrolling, zooming, navigating lists of entities, etc. to select the subset of ARA entities that they currently need to view or edit. Those selection features can be implemented in the plug-in (which was the only available solution in ARA 1). However, the host applications already have established user workflows for selecting their representations of the ARA objects. Making those workflows available to the plug-ins is leads to a much more consistent, streamlined user experience. Since the views are implemented through the companion API, there is no matching ARA entity yet. Instead, the companion plug-in instance is used as a controller for its associated view. (Note that while some companion APIs allow for multiple views of a given plug-in used at the same time, this is not recommended when using ARA editor views.) These calls only affect views, not the audio rendering. They only should be made while the plug-in is showing its UI, or before entering this state (i.e. during GUI setup phase), in order to optimize resource usage. Accordingly, the host should send an update of the selection when (re-)opening an ARA plug-in view. These calls also may be made while changes are being made to the model graph (i.e. inside of pairs of ARADocumentControllerInterface::beginEditing() and ARADocumentControllerInterface::endEditing()).
Plug-in developers using C++ ARA Library can implement the ARA::PlugIn::EditorViewInterface, or extend the already implemented ARA::PlugIn::EditorView class as needed. For host developers this interface is wrapped by the ARA::Host::EditorView
 Deprecated: Plug-In Extension Interface.This interface was used before ARA 2.0 defined dedicated plug-in roles. It is only to be implemented when ARA 1 backwards compatibility is desired. An ARA 1 call to set/removePlaybackRegion() in this interface is equivalent to calling both set/removePlaybackRegion() in ARAPlaybackRendererInterface and add/removePlaybackRegion() in ARAEditorRendererInterface. To some extend ARA 1 also uses this to for tasks now associated with ARAEditorViewInterface: opening the UI of an ARA 1 plug-in instance is interpreted as selection of the playback region set via this interface
 ARA Audio File ChunksTo allow for distributing persistent ARA audio source state information together with the underlying audio file in a way that is transparent to the plug-ins and can be supported by all hosts, ARA 2.0 defines a format for embedding such states into standardized audio file chunks. From there, they can be imported into any ARA document using Partial Document Persistency.
The most obvious use case for this is that it enables audio content providers to ship audio files with properly validated, ready-to-use audio source analysis for multiple plug-ins (or incompatible versions of a plug-in if needed). For example, this allows for loading polyphonic audio loops into Melodyne without time-consuming analysis and very quickly adjusting them to follow the song key and chord progression, making the published audio material much more versatile to use in various productions. Other scenarios where such file chunks are used include exporting data from one plug-in to another, or adding ARA objects to a host document via dragging and dropping audio files from a plug-in that either generates these files on the fly (e.g. export of layers in SpectraLayers) or copies them from a built-in sound library.
The ARA chunk should be evaluated by the host both when adding a new audio file to the arrangement and when applying a new/different ARA plug-in for a region/file already used in the arrangement. Note that after loading the data, ARA content readers can be used to extract more information about the audio source - such as tempo map, time and key signatures, etc.
Plug-in vendors shall optimize the encoding of the audio source state information for audio file chunks according to very different criteria compared to encoding the same state for regular ARA song document archives: The audio file states are going to be widely distributed and will be used over a long period of time in very different contexts, whereas song documents are typically only used on a single machine for a rather short time. Audio file archives therefore should emphasize small data size over en-/decoding speed - encoding is only done once, and decoding only happens for a single audio source at a time (compared to hundreds of audio sources in a typical song archive). Even more important, audio file archives are likely going to be used across a wide range of products versions and shall be stable across a long time. The encoding should therefore be as much backwards compatible as possible, potentially even using different encoding based on the current state of the audio source: if e.g. a particular non-backwards compatible feature of the plug-in is not used in the given state, the plug-in can choose an older format to store the data than if that particular feature was utilized. For these reasons, audio file chunks will typically not use the ARAFactory::documentArchiveID but instead one of the IDs listed in ARAFactory::compatibleDocumentArchiveIDs.
Creating audio file chunks may not be meaningful nor supported for any given plug-in. If for example the plug-in does not perform any costly analysis and has no relevant editable audio source state, there is no reason to create audio file chunks for it. Therefore, creating such chunks is currently done only through dedicated authoring tools (such as Melodyne's standalone version) and not directly available in ARA host applications.
Covering both AIFF and WAVE formats, ARA stores its data by extending iXML chunks as specified here: http://www.ixml.info Inside the iXML document, there's a custom tag <ARA> that encloses a dictionary of audio source archives, encoded as array tagged <audioSources>. Each entry in the array is intended for a different plug-in (or incompatible version fo a plug-in) and contains the tag <documentArchiveID> which also functions as the key for the dictionary, and associated data which includes the actual binary archive and meta information, for example:
 ▼Companion APIs
 Audio UnitARA support for Audio Units is mostly based on private Audio Unit properties. The input/output pattern for the associated property data structs is similar to struct AudioUnitParameterStringFromValue in the Audio Unit API. To be able to detect potential collisions if some host or Audio Unit uses the same private property for non-ARA communication, the actual ARA data is embedded into a property data struct that also contains an ARA magic number. For this magic number to work properly for all host/plug-in combinations, it's crucial that hosts set it on input and check it after output, and that plug-ins check it before writing to the property struct
 Audio Unit V3Experimental support for Audio Unit v3 (App Extension)
 VST3
 ▼ARA C++ Library
 ▼Utility Classes and FunctionsUtilities designed to make communicating across the API boundary between host and plug-in more convenient
 Versioned Sized StructsClasses used to managed versioned ARA structs by their structSize member
 Reading ContentClasses designed to make content reading more convenient
 Content Update ScopesUtility class for defining the scope of a content update
 Interpreting Pitch, Chords, and Key SignaturesClasses designed to parse and interpret ARAContentChord / ARAContentKeySignature data
 Musical Timeline ConversionsClasses designed to perform conversions between musical and linear timelines
 Surround Channel ArrangementUtility class dealing with the Companion-API-dependent surround channel arrangements
 Rounding Utility FunctionsRounding utility functions used in the ARA SDK
 std::vector Utility Functionsstd::vector related utility functions used in the ARA SDK
 ▼Host DispatchClasses and interfaces designed to ease ARA hosting implementations.
Requires linking ARAHostDispatch.cpp with your binary
 Host InterfacesInterfaces to be implemented by ARA hosts
 Plug-In Interface WrappersWrappers for the interfaces used to communicate with and control ARA plug-ins
 ▼Plug-In DispatchClasses and interfaces designed to ease ARA plug-in implementations.
Requires linking ARAPlugInDispatch.cpp with your binary
 Plug-In InterfacesInterfaces to be implemented by ARA plug-ins
 Host Interface WrappersWrappers for the interfaces used to communicate with and control the ARA host
 ▼ARAPlugFully implemented interfaces from ARA Plug-In Dispatch.
Requires linking ARAPlugInDispatch.cpp and ARAPlug.cpp with your binary
 Utility ClassesClasses that plug-in developers can use to make ARA operations and host communication easier
 Model ObjectsC++ classes representing the ARA Model Graph objects
 Document ControllerCustomizable default implementation of DocumentControllerInterface.
 Plug-In Instance RolesClasses that implement the ARA plug-in extension instance role interfaces
 Plug-In EntryClasses that implement the entry into the ARA plug-in
 ARA IPCProxies for both host and plug-in side implementations of ARA IPC